wiki-browser Continuous Delivery Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: When a test-passing change to wiki-browser's own Go source lands on master, the Raspberry Pi rebuilds and redeploys itself — automatically, crash-safely, and with auto-rollback on a bad deploy.

Architecture: A GitHub Action (the WB Action) runs on every push, classifies the changed paths, runs go test ./... for code changes, and makes one HMAC-signed POST /api/webhook/ci to the Pi. The handler always triggers a git-sync Sync and, on deploy:true, writes the approved commit to a trigger file. A systemd .path unit turns that into a wb-cd oneshot run: wb-cd builds the exact commit via git archive, atomically swaps the binaries, restarts wiki-browser (which now drains in-flight Agent jobs gracefully), health-checks /healthz, and rolls back to the previous binaries if the new one is unhealthy.

Tech Stack: Go 1.x, os/exec (git, make, systemctl, tar), net/http, gopkg.in/yaml.v3, the existing internal/walker / internal/gitsync / internal/alert / internal/agent packages, GitHub Actions, systemd.

Spec: docs/superpowers/specs/2026-05-21-wiki-browser-cd-design.html

File Structure

New files:

• internal/walker/matcher.go — Matcher: the shared "is this a tracked document" predicate.
• internal/walker/matcher_test.go — matcher tests.
• cmd/classify-ci-change/main.go — the WB Action's path classifier (Go program, run via go run).
• cmd/classify-ci-change/classify.go — the pure classification function.
• cmd/classify-ci-change/classify_test.go — classifier tests.
• internal/cd/config.go — Config for the deploy engine.
• internal/cd/state.go — State (deployed/poisoned commit) load + atomic save.
• internal/cd/state_test.go — state tests.
• internal/cd/git.go — commitPresent, archiveCommit.
• internal/cd/git_test.go — git-helper tests.
• internal/cd/build.go — buildCommit (archive + make build).
• internal/cd/swap.go — snapshotBinaries, swapBinaries, restartService, healthCheck.
• internal/cd/swap_test.go — swap/health tests.
• internal/cd/deploy.go — Deployer, Run (the trigger-drain loop), deployOne, rollback, alerting.
• internal/cd/deploy_test.go — deploy-loop tests.
• internal/cd/helpers_test.go — newTestRepo and shared test helpers.
• cmd/wb-cd/main.go — the wb-cd oneshot: config load → cd.Deployer → Run.
• deploy/wb-cd.path — systemd path unit watching the trigger file.
• deploy/wb-cd.service — systemd oneshot unit.
• deploy/wb-cd-alert.service — systemd OnFailure= alert unit.
• wiki-browser/ci-tracked-paths.yaml — committed non-secret extensions/exclude policy for the classifier.
• .github/workflows/wiki-browser.yml — the WB Action (committed at the monorepo root, not under wiki-browser/).

Modified files:

• internal/config/config.go — add the CD block, defaults, validation.
• internal/walker/walker.go — use Matcher instead of the inline extSet/exclude fields.
• internal/server/handler_webhook.go — rewrite for the /api/webhook/ci payload + trigger-file write.
• internal/server/server.go — Deps gains Version/Commit/BuildTime/CDTriggerFile/Draining; route rename; drainGuard; real /healthz handler.
• internal/server/embed.go — ShellData gains version fields.
• internal/server/handler_doc.go — writeShell populates the version fields.
• internal/server/templates/shell.html — version footer.
• internal/server/static/chrome.css — footer styling.
• internal/agent/service.go — Drain, draining flag, ErrDraining.
• cmd/wiki-browser/main.go — version vars; new shutdown sequence (drain); wire CD config + version into Deps.
• deploy/wiki-browser.service — TimeoutStopSec=11m.
• Makefile — COMMIT/VERSION/BUILD_TIME ldflags; build cmd/wb-cd.
• wiki-browser.example.yaml — cd: block.

Decomposition note: internal/cd is split by responsibility — config.go/state.go (persisted state), git.go/build.go (read-only build inputs), swap.go (filesystem + systemd side effects), deploy.go (the orchestration loop). deploy.go holds function-field seams for build/restart/health so the loop and rollback logic are unit-testable without compiling a real binary or touching systemd.

Spec deviation (carry into review): The spec's drain section says "queued jobs stay in the DB; the next instance drains them on boot." internal/agent has no dequeue loop — Submit inserts the job row and immediately spawns its goroutine, which then blocks on a semaphore. So "already-submitted" jobs are in-flight goroutines, not a DB queue. This plan's Drain rejects only new Submit calls and waits for every already-submitted job (running or semaphore-blocked) to finish, bounded by the 10-minute cap. This loses no work and is simpler than introducing a dequeue loop; the cap + hard Stop() still bound the wait.

Working directory convention: Tasks 1–14 run from wiki-browser/. Task 15 also starts from wiki-browser/, except the GitHub workflow is created and staged as ../.github/workflows/wiki-browser.yml because GitHub only reads workflows from the monorepo root.

Task 1: Config — cd: block

Files:

• Modify: internal/config/config.go

• Test: internal/config/config_test.go

• Step 1: Write the failing tests

Add to internal/config/config_test.go. Mirror the existing git:/alert: block tests in that file for the config-loading helper shape (minimalValidConfigYAML / mustLoadConfigFromString / loadConfigFromString already exist there from the #10 work).

func TestCDBlockDefaults(t *testing.T) {
	dir := t.TempDir()
	yaml := minimalValidConfigYAML(t, dir) +
		"\ncd:\n" +
		"  bin_dir: /srv/wiki-browser/bin\n" +
		"  trigger_file: /srv/wiki-browser/cd-trigger\n" +
		"  state_file: /srv/wiki-browser/cd-state.json\n"
	c := mustLoadConfigFromString(t, yaml)
	if c.CD == nil {
		t.Fatal("CD block should be non-nil when present")
	}
	if c.CD.HealthPollTimeout != 90*time.Second {
		t.Errorf("HealthPollTimeout default = %v, want 90s", c.CD.HealthPollTimeout)
	}
}

func TestCDBlockRequiresPaths(t *testing.T) {
	dir := t.TempDir()
	yaml := minimalValidConfigYAML(t, dir) + "\ncd:\n  bin_dir: /srv/wiki-browser/bin\n"
	if _, err := loadConfigFromString(t, yaml); err == nil {
		t.Fatal("expected error: cd.trigger_file / cd.state_file required")
	}
}

func TestNoCDBlockMeansNilCD(t *testing.T) {
	dir := t.TempDir()
	c := mustLoadConfigFromString(t, minimalValidConfigYAML(t, dir))
	if c.CD != nil {
		t.Errorf("CD should be nil when no cd: block present")
	}
}

• Step 2: Run tests to verify they fail

Run: go test ./internal/config/ -run 'TestCDBlock|TestNoCDBlock' -v Expected: FAIL — c.CD undefined.

• Step 3: Add the struct

In internal/config/config.go, add to the Config struct after Alert:

	CD *CD `yaml:"cd"`

Add the new type after the Alert type:

// CD configures the wb-cd continuous-delivery oneshot. Optional: absent a `cd:`
// block, the /api/webhook/ci route still serves doc-sync, but a deploy:true
// payload has nowhere to write and is logged and ignored.
type CD struct {
	BinDir            string        `yaml:"bin_dir"`            // live binaries + bin/prev/
	TriggerFile       string        `yaml:"trigger_file"`       // webhook writes here; .path watches it
	StateFile         string        `yaml:"state_file"`         // deployed/poisoned commit
	HealthPollTimeout time.Duration `yaml:"health_poll_timeout"` // /healthz poll budget
}

• Step 4: Add defaults and validation

In applyDefaults(), after the Alert block:

	if c.CD != nil && c.CD.HealthPollTimeout == 0 {
		c.CD.HealthPollTimeout = 90 * time.Second
	}

In validate(), before the final return nil:

	if c.CD != nil {
		if c.CD.BinDir == "" {
			return fmt.Errorf("cd.bin_dir is required when a cd: block is present")
		}
		if c.CD.TriggerFile == "" {
			return fmt.Errorf("cd.trigger_file is required when a cd: block is present")
		}
		if c.CD.StateFile == "" {
			return fmt.Errorf("cd.state_file is required when a cd: block is present")
		}
		if c.CD.HealthPollTimeout < 0 {
			return fmt.Errorf("cd.health_poll_timeout must not be negative")
		}
	}

These paths are intentionally not os.Stat-checked: the trigger and state files are created on demand, and bin_dir is a provisioning artifact validated by the operator runbook, not config load.

• Step 5: Run tests to verify they pass

Run: go test ./internal/config/ -v Expected: PASS (all existing config tests plus the three new ones).

• Step 6: Commit

git add internal/config/config.go internal/config/config_test.go
git commit -m "config: add optional cd: block"

Task 2: walker.Matcher — shared tracked-path predicate

Files:

• Create: internal/walker/matcher.go
• Modify: internal/walker/walker.go
• Test: internal/walker/matcher_test.go

The classifier (cmd/classify-ci-change, Task 3) must answer "would the running wiki serve this file?" with the exact rule the walker uses. Extract that rule into a Matcher so there is one implementation, not two.

• Step 1: Write the failing test

Create internal/walker/matcher_test.go:

package walker

import "testing"

func TestMatcherTracked(t *testing.T) {
	m := NewMatcher([]string{".md", ".html"}, []string{"www/**"})

	cases := []struct {
		path string
		want bool
	}{
		{"docs/intro.md", true},
		{"docs/page.HTML", true},   // extension match is case-insensitive
		{"main.go", false},         // wrong extension
		{"www/index.md", false},    // user exclude
		{".git/config.md", false},  // baked-in default exclude
		{"node_modules/x/readme.md", false},
		{"a/.claude/skills/s.md", false},
	}
	for _, c := range cases {
		if got := m.Tracked(c.path); got != c.want {
			t.Errorf("Tracked(%q) = %v, want %v", c.path, got, c.want)
		}
	}
}

func TestMatcherExcluded(t *testing.T) {
	m := NewMatcher([]string{".md"}, []string{"vendor/**"})
	if !m.Excluded("vendor/lib/x.md") {
		t.Error("Excluded(vendor/...) should be true")
	}
	if m.Excluded("docs/x.md") {
		t.Error("Excluded(docs/...) should be false")
	}
}

• Step 2: Run the test to verify it fails

Run: go test ./internal/walker/ -run TestMatcher -v Expected: FAIL — NewMatcher undefined.

• Step 3: Create matcher.go

Create internal/walker/matcher.go:

package walker

import (
	"path/filepath"
	"strings"
)

// Matcher decides, for a repo-relative slash-separated path, whether it is a
// tracked document: its extension is in the configured set and it is not
// excluded. It is the single source of truth shared by the Walker (what to
// serve) and cmd/classify-ci-change (what a push touched).
type Matcher struct {
	extSet  map[string]struct{}
	exclude *ExcludeMatcher
}

// NewMatcher builds a Matcher. exclude is combined with DefaultExcludes.
func NewMatcher(extensions, exclude []string) *Matcher {
	m := &Matcher{
		extSet:  make(map[string]struct{}, len(extensions)),
		exclude: NewExcludeMatcher(exclude),
	}
	for _, e := range extensions {
		m.extSet[strings.ToLower(e)] = struct{}{}
	}
	return m
}

// Excluded reports whether path is excluded (baked-in defaults or user list).
func (m *Matcher) Excluded(path string) bool { return m.exclude.Match(path) }

// extOK reports whether path has a tracked extension.
func (m *Matcher) extOK(path string) bool {
	_, ok := m.extSet[strings.ToLower(filepath.Ext(path))]
	return ok
}

// Tracked reports whether path is a served document: tracked extension and not
// excluded.
func (m *Matcher) Tracked(path string) bool {
	return !m.Excluded(path) && m.extOK(path)
}

• Step 4: Refactor walker.go to use Matcher

In internal/walker/walker.go, replace the Walker struct's exclude/extSet fields with a single matcher:

type Walker struct {
	opts    Options
	matcher *Matcher

	mu    sync.RWMutex
	files map[string]struct{} // repo-relative slash paths
}

In New, replace the matcher construction:

	w := &Walker{
		opts:    opts,
		matcher: NewMatcher(opts.Extensions, opts.Exclude),
		files:   make(map[string]struct{}),
	}
	if err := w.scan(); err != nil {
		return nil, fmt.Errorf("initial scan: %w", err)
	}
	return w, nil

(Delete the old w.exclude / w.extSet assignment and the for _, e := range opts.Extensions loop.)

In scanInto, replace w.exclude.Match(rel) with w.matcher.Excluded(rel) and !w.matchesExt(rel) with !w.matcher.extOK(rel):

		if w.matcher.Excluded(rel) {
			if d.IsDir() {
				return fs.SkipDir
			}
			return nil
		}
		if d.IsDir() {
			return nil
		}
		if !w.matcher.extOK(rel) {
			return nil
		}

Delete the now-unused matchesExt method. Remove the strings import from walker.go if it becomes unused (it does — strings only appeared in matchesExt and the deleted loop; verify with the build in Step 5).

• Step 5: Run tests to verify they pass

Run: go test ./internal/walker/ -v Expected: PASS — all existing walker tests plus the new matcher tests.

Run: go build ./... Expected: builds clean.

• Step 6: Commit

git add internal/walker/matcher.go internal/walker/matcher_test.go internal/walker/walker.go
git commit -m "walker: extract shared Matcher predicate"

Task 3: cmd/classify-ci-change — the WB Action classifier

Files:

• Create: cmd/classify-ci-change/classify.go
• Create: cmd/classify-ci-change/main.go
• Test: cmd/classify-ci-change/classify_test.go

A Go program run by the WB Action via go run. It diffs the previous-push range, classifies the changed paths into two sets, and writes three booleans to $GITHUB_OUTPUT.

• Step 1: Write the failing test

Create cmd/classify-ci-change/classify_test.go:

package main

import (
	"os"
	"os/exec"
	"path/filepath"
	"strings"
	"testing"

	"github.com/getorcha/wiki-browser/internal/walker"
)

func TestClassify(t *testing.T) {
	m := walker.NewMatcher([]string{".md", ".html"}, []string{"www/**"})

	cases := []struct {
		name                       string
		paths                      []string
		code, tracked, notify bool
	}{
		{
			name:    "doc only",
			paths:   []string{"docs/x.md"},
			code:    false, tracked: true, notify: true,
		},
		{
			name:    "wiki-browser go code",
			paths:   []string{"wiki-browser/internal/server/server.go"},
			code:    true, tracked: false, notify: true,
		},
		{
			name:    "wiki-browser embedded template",
			paths:   []string{"wiki-browser/internal/server/templates/shell.html"},
			code:    true, tracked: false, notify: true,
		},
		{
			name:    "wiki-browser doc - tracked doc but not a build input",
			paths:   []string{"wiki-browser/docs/plans/x.md"},
			code:    false, tracked: true, notify: true,
		},
		{
			name:    "wiki-browser markdown - tracked doc but not a build input",
			paths:   []string{"wiki-browser/CLAUDE.md"},
			code:    false, tracked: true, notify: true,
		},
		{
			name:    "the workflow file itself",
			paths:   []string{".github/workflows/wiki-browser.yml"},
			code:    true, tracked: false, notify: true,
		},
		{
			name:    "excluded doc",
			paths:   []string{"www/landing.md"},
			code:    false, tracked: false, notify: false,
		},
		{
			name:    "unrelated subproject code",
			paths:   []string{"crm/src/main.go"},
			code:    false, tracked: false, notify: false,
		},
		{
			name:    "code and doc together",
			paths:   []string{"wiki-browser/internal/index/index.go", "docs/x.md"},
			code:    true, tracked: true, notify: true,
		},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			got := classify(c.paths, m)
			if got.Code != c.code || got.Tracked != c.tracked || got.Notify != c.notify {
				t.Errorf("classify(%v) = %+v, want code=%v tracked=%v notify=%v",
					c.paths, got, c.code, c.tracked, c.notify)
			}
		})
	}
}

func TestChangedPathsUsesPushRange(t *testing.T) {
	dir := t.TempDir()
	oldWD, _ := os.Getwd()
	if err := os.Chdir(dir); err != nil {
		t.Fatal(err)
	}
	defer os.Chdir(oldWD)

	runGit(t, "init", "-b", "master")
	runGit(t, "config", "user.email", "test@example.com")
	runGit(t, "config", "user.name", "Test")
	os.WriteFile("a.md", []byte("a"), 0o644)
	runGit(t, "add", "a.md")
	runGit(t, "commit", "-m", "a")
	base := gitOut(t, "rev-parse", "HEAD")

	os.WriteFile("b.md", []byte("b"), 0o644)
	runGit(t, "add", "b.md")
	runGit(t, "commit", "-m", "b")
	os.WriteFile("c.md", []byte("c"), 0o644)
	runGit(t, "add", "c.md")
	runGit(t, "commit", "-m", "c")
	head := gitOut(t, "rev-parse", "HEAD")

	paths, err := changedPaths(base, head)
	if err != nil {
		t.Fatal(err)
	}
	if got := strings.Join(paths, ","); got != "b.md,c.md" {
		t.Fatalf("changedPaths = %q, want b.md,c.md", got)
	}
}

func TestChangedPathsAllZeroBaseUsesEmptyTree(t *testing.T) {
	dir := t.TempDir()
	oldWD, _ := os.Getwd()
	if err := os.Chdir(dir); err != nil {
		t.Fatal(err)
	}
	defer os.Chdir(oldWD)

	runGit(t, "init", "-b", "master")
	runGit(t, "config", "user.email", "test@example.com")
	runGit(t, "config", "user.name", "Test")
	os.WriteFile("README.md", []byte("x"), 0o644)
	runGit(t, "add", "README.md")
	runGit(t, "commit", "-m", "seed")
	head := gitOut(t, "rev-parse", "HEAD")

	paths, err := changedPaths(strings.Repeat("0", 40), head)
	if err != nil {
		t.Fatal(err)
	}
	if len(paths) != 1 || paths[0] != "README.md" {
		t.Fatalf("changedPaths = %v, want [README.md]", paths)
	}
}

func TestWriteOutputsAppendsGitHubOutput(t *testing.T) {
	out := filepath.Join(t.TempDir(), "github-output")
	t.Setenv("GITHUB_OUTPUT", out)
	if err := writeOutputs(map[string]bool{"notify": true}); err != nil {
		t.Fatal(err)
	}
	got, err := os.ReadFile(out)
	if err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(string(got), "notify=true\n") {
		t.Fatalf("GITHUB_OUTPUT = %q, want notify=true", got)
	}
}

func runGit(t *testing.T, args ...string) {
	t.Helper()
	if out, err := exec.Command("git", args...).CombinedOutput(); err != nil {
		t.Fatalf("git %v: %v\n%s", args, err, out)
	}
}

func gitOut(t *testing.T, args ...string) string {
	t.Helper()
	out, err := exec.Command("git", args...).Output()
	if err != nil {
		t.Fatalf("git %v: %v", args, err)
	}
	return strings.TrimSpace(string(out))
}

• Step 2: Run the test to verify it fails

Run: go test ./cmd/classify-ci-change/ -v Expected: FAIL — package does not exist.

• Step 3: Write classify.go

Create cmd/classify-ci-change/classify.go:

package main

import "strings"

// Result is the classifier verdict.
type Result struct {
	Code    bool // a deploy build input changed
	Tracked bool // a document the running wiki serves changed
	Notify  bool // Code || Tracked — whether to call the Pi at all
}

// trackedMatcher is the narrow surface classify needs from walker.Matcher.
type trackedMatcher interface {
	Tracked(path string) bool
}

// classify decides, from a list of repo-relative changed paths, whether the
// push is a deploy build-input change and/or a tracked-document change.
func classify(paths []string, m trackedMatcher) Result {
	var r Result
	for _, p := range paths {
		if isBuildInput(p) {
			r.Code = true
		}
		if m.Tracked(p) {
			r.Tracked = true
		}
	}
	r.Notify = r.Code || r.Tracked
	return r
}

// isBuildInput reports whether a changed path affects the wiki-browser binary.
// Build inputs are everything under wiki-browser/ except docs/, .claude/ and
// *.md, plus the WB Action workflow file itself (it controls deployment).
func isBuildInput(path string) bool {
	if path == ".github/workflows/wiki-browser.yml" {
		return true
	}
	if !strings.HasPrefix(path, "wiki-browser/") {
		return false
	}
	if strings.HasPrefix(path, "wiki-browser/docs/") {
		return false
	}
	if strings.HasPrefix(path, "wiki-browser/.claude/") {
		return false
	}
	if strings.HasSuffix(strings.ToLower(path), ".md") {
		return false
	}
	return true
}

• Step 4: Run the test to verify it passes

Run: go test ./cmd/classify-ci-change/ -v Expected: PASS.

• Step 5: Write main.go

Create cmd/classify-ci-change/main.go:

// Command classify-ci-change is run by the WB Action. It diffs the push range,
// classifies the changed paths, and writes code_changed / tracked_changed /
// notify to $GITHUB_OUTPUT. Any error exits non-zero so the Action fails loud.
package main

import (
	"flag"
	"fmt"
	"os"
	"os/exec"
	"strings"

	"github.com/getorcha/wiki-browser/internal/walker"
	"gopkg.in/yaml.v3"
)

// emptyTree is git's well-known empty-tree hash, used when base is the
// all-zero sentinel (a branch's first push).
const emptyTree = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"

// policy is the committed non-secret mirror of the wiki's document-tracking
// config: just the values, not the matching logic.
type policy struct {
	Extensions []string `yaml:"extensions"`
	Exclude    []string `yaml:"exclude"`
}

func main() {
	base := flag.String("base", "", "github.event.before")
	head := flag.String("head", "", "github.sha")
	policyPath := flag.String("policy", "ci-tracked-paths.yaml", "path policy file")
	flag.Parse()

	if err := run(*base, *head, *policyPath); err != nil {
		fmt.Fprintln(os.Stderr, "classify-ci-change:", err)
		os.Exit(1)
	}
}

func run(base, head, policyPath string) error {
	pol, err := loadPolicy(policyPath)
	if err != nil {
		return err
	}
	m := walker.NewMatcher(pol.Extensions, pol.Exclude)

	paths, err := changedPaths(base, head)
	if err != nil {
		return err
	}
	res := classify(paths, m)

	return writeOutputs(map[string]bool{
		"code_changed":    res.Code,
		"tracked_changed": res.Tracked,
		"notify":          res.Notify,
	})
}

func loadPolicy(path string) (policy, error) {
	raw, err := os.ReadFile(path)
	if err != nil {
		return policy{}, fmt.Errorf("read policy %s: %w", path, err)
	}
	var p policy
	if err := yaml.Unmarshal(raw, &p); err != nil {
		return policy{}, fmt.Errorf("parse policy %s: %w", path, err)
	}
	if len(p.Extensions) == 0 {
		return policy{}, fmt.Errorf("policy %s: extensions is required", path)
	}
	return p, nil
}

// changedPaths returns the repo-relative paths changed between base and head.
// A missing or all-zero base (first push) is diffed against the empty tree.
func changedPaths(base, head string) ([]string, error) {
	if head == "" {
		return nil, fmt.Errorf("head is required")
	}
	from := base
	if from == "" || from == strings.Repeat("0", 40) || !revExists(base) {
		from = emptyTree
	}
	out, err := exec.Command("git", "diff", "--name-only", from+".."+head).CombinedOutput()
	if err != nil {
		return nil, fmt.Errorf("git diff %s..%s: %w\n%s", from, head, err, out)
	}
	var paths []string
	for _, ln := range strings.Split(string(out), "\n") {
		if ln = strings.TrimSpace(ln); ln != "" {
			paths = append(paths, ln)
		}
	}
	return paths, nil
}

func revExists(rev string) bool {
	return exec.Command("git", "rev-parse", "--verify", "--quiet", rev+"^{commit}").Run() == nil
}

// writeOutputs appends key=value lines to the file named by $GITHUB_OUTPUT.
func writeOutputs(kv map[string]bool) error {
	path := os.Getenv("GITHUB_OUTPUT")
	if path == "" {
		// Not under Actions — print so a manual run is still useful.
		for k, v := range kv {
			fmt.Printf("%s=%t\n", k, v)
		}
		return nil
	}
	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
	if err != nil {
		return fmt.Errorf("open GITHUB_OUTPUT: %w", err)
	}
	defer f.Close()
	for k, v := range kv {
		if _, err := fmt.Fprintf(f, "%s=%t\n", k, v); err != nil {
			return err
		}
	}
	return nil
}

• Step 6: Run the full build and tests

Run: go build ./... && go test ./cmd/classify-ci-change/ -v Expected: builds clean; tests PASS.

• Step 7: Commit

git add cmd/classify-ci-change/
git commit -m "cmd/classify-ci-change: WB Action path classifier"

Task 4: Version stamping + Makefile

Files:

• Modify: cmd/wiki-browser/main.go

• Modify: Makefile

• Test: cmd/wiki-browser/main_test.go

• Step 1: Write the failing test

Add to cmd/wiki-browser/main_test.go:

func TestVersionVarsHaveDefaults(t *testing.T) {
	// The ldflags-injected vars must have safe defaults so a bare `go build`
	// or `go test` (no -X) does not produce empty version strings.
	if version == "" || commit == "" || buildTime == "" {
		t.Fatalf("version vars must default non-empty: version=%q commit=%q buildTime=%q",
			version, commit, buildTime)
	}
}

• Step 2: Run the test to verify it fails

Run: go test ./cmd/wiki-browser/ -run TestVersionVars -v Expected: FAIL — version undefined.

• Step 3: Add the version vars

In cmd/wiki-browser/main.go, after the const block at the top of the file:

// Version metadata, overridden at build time via -ldflags "-X main.version=...".
// Defaults keep a bare `go build` / `go test` working.
var (
	version   = "dev"
	commit    = "dev"
	buildTime = "unknown"
)

• Step 4: Run the test to verify it passes

Run: go test ./cmd/wiki-browser/ -run TestVersionVars -v Expected: PASS.

• Step 5: Update the Makefile

Replace the top of Makefile (the build and build-arm64 targets) with:

# Version metadata stamped into the wiki-browser binary. wb-cd overrides these
# on the Pi with the exact commit it is deploying.
COMMIT     ?= $(shell git rev-parse HEAD 2>/dev/null || echo dev)
VERSION    ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo dev)
BUILD_TIME ?= $(shell date -u +%Y-%m-%dT%H:%MZ)
LDFLAGS     = -s -w -X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.buildTime=$(BUILD_TIME)

build:
	go build -trimpath -ldflags="$(LDFLAGS)" -o dist/wiki-browser ./cmd/wiki-browser
	go build -trimpath -ldflags="$(LDFLAGS)" -o dist/wb-agent ./cmd/wb-agent
	go build -trimpath -ldflags="$(LDFLAGS)" -o dist/wb-cd ./cmd/wb-cd

# Cross-compile every binary for a 64-bit Pi.
build-arm64:
	GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
	  go build -trimpath -ldflags="$(LDFLAGS)" -o dist/wiki-browser-arm64 ./cmd/wiki-browser
	GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
	  go build -trimpath -ldflags="$(LDFLAGS)" -o dist/wb-agent-arm64 ./cmd/wb-agent
	GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
	  go build -trimpath -ldflags="$(LDFLAGS)" -o dist/wb-cd-arm64 ./cmd/wb-cd

The -X main.commit= flag is a no-op for wb-agent/wb-cd (they have no main.commit symbol) — the linker silently ignores it, so one LDFLAGS for all three is correct.

make build now references ./cmd/wb-cd, which does not exist until Task 14. Do not run make build until then — go build ./... and go test ./... in the interim do not depend on the Makefile.

• Step 6: Commit

git add cmd/wiki-browser/main.go cmd/wiki-browser/main_test.go Makefile
git commit -m "build: stamp version/commit/build-time via ldflags"

Task 5: /healthz JSON

Files:

• Modify: internal/server/server.go

• Test: internal/server/server_test.go (create if absent; otherwise add to it)

• Step 1: Write the failing test

Add to internal/server/server_test.go (create the file with package server if it does not exist):

package server

import (
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"testing"
)

func TestHealthzReturnsJSONVersion(t *testing.T) {
	d := Deps{Version: "abc1234", Commit: "abc1234full", BuildTime: "2026-05-21T14:30Z"}
	rec := httptest.NewRecorder()
	d.handleHealthz(rec, httptest.NewRequest("GET", "/healthz", nil))
	if rec.Code != http.StatusOK {
		t.Fatalf("status = %d, want 200", rec.Code)
	}
	var got map[string]string
	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
		t.Fatalf("body not JSON: %v", err)
	}
	if got["status"] != "ok" {
		t.Errorf("status = %q, want ok", got["status"])
	}
	if got["commit"] != "abc1234full" {
		t.Errorf("commit = %q, want abc1234full", got["commit"])
	}
	if got["version"] != "abc1234" {
		t.Errorf("version = %q, want abc1234", got["version"])
	}
	if got["built"] != "2026-05-21T14:30Z" {
		t.Errorf("built = %q", got["built"])
	}
}

• Step 2: Run the test to verify it fails

Run: go test ./internal/server/ -run TestHealthz -v Expected: FAIL — handleHealthz / Deps.Version undefined.

• Step 3: Add the Deps fields and the handler

In internal/server/server.go, add to the Deps struct (after Title/Root):

	// Version, Commit, BuildTime are the build-stamp values surfaced at
	// /healthz and in the UI footer. Empty in tests and dev builds.
	Version   string
	Commit    string
	BuildTime string

Add the handler (a method on Deps, e.g. at the end of server.go):

// handleHealthz reports liveness plus the running build identity. wb-cd's
// post-deploy check reads the full commit here to confirm the swap took.
func (d Deps) handleHealthz(w http.ResponseWriter, r *http.Request) {
	writeJSON(w, http.StatusOK, map[string]string{
		"status":  "ok",
		"commit":  d.Commit,
		"version": d.Version,
		"built":   d.BuildTime,
	})
}

In Mux, replace the inline /healthz closure:

	mux.HandleFunc("GET /healthz", d.handleHealthz)

• Step 4: Run tests to verify they pass

Run: go test ./internal/server/ -run TestHealthz -v Expected: PASS.

• Step 5: Commit

git add internal/server/server.go internal/server/server_test.go
git commit -m "server: /healthz returns JSON build identity"

Task 6: UI version footer

Files:

• Modify: internal/server/embed.go

• Modify: internal/server/handler_doc.go

• Modify: internal/server/templates/shell.html

• Modify: internal/server/static/chrome.css

• Test: internal/server/handler_doc_test.go

• Step 1: Write the failing test

Add to internal/server/handler_doc_test.go. Mirror the existing writeShell/handleRoot tests in that file for the Deps setup.

func TestShellRendersVersionFooter(t *testing.T) {
	d := newDocTestDeps(t) // existing helper used by other handler_doc tests
	d.Version = "abc1234"
	d.Commit = "abc1234ffffffffffffffffffffffffffffffff"
	d.BuildTime = "2026-05-21 14:30"

	rec := httptest.NewRecorder()
	d.handleRoot(rec, httptest.NewRequest("GET", "/", nil))

	body := rec.Body.String()
	if !strings.Contains(body, "abc1234") {
		t.Error("footer should show the version")
	}
	if !strings.Contains(body, "github.com/getorcha/orcha/commit/abc1234ffff") {
		t.Error("version should link to the GitHub commit")
	}
	if !strings.Contains(body, "2026-05-21 14:30") {
		t.Error("footer should show the build time")
	}
}

If newDocTestDeps does not exist, build the Deps inline the way the existing handler_doc_test.go tests do (they need a Walker); the assertions above are what matter.

• Step 2: Run the test to verify it fails

Run: go test ./internal/server/ -run TestShellRendersVersionFooter -v Expected: FAIL — version not in the rendered shell.

• Step 3: Add the ShellData fields

In internal/server/embed.go, add to the ShellData struct:

	// Version/Commit/BuildTime drive the subtle chrome footer. Empty in dev
	// builds — the template omits the footer when Version is empty.
	Version   string
	Commit    string
	BuildTime string

• Step 4: Populate the fields in writeShell

In internal/server/handler_doc.go, add to the ShellData{...} literal in writeShell:

		Version:         d.Version,
		Commit:          d.Commit,
		BuildTime:       d.BuildTime,

• Step 5: Add the footer to shell.html

In internal/server/templates/shell.html, immediately before the closing </body> tag:

  {{ if .Version }}
  <footer class="wb-version">
    <a href="https://github.com/getorcha/orcha/commit/{{ .Commit }}" target="_blank" rel="noopener">{{ .Version }}</a>
    <span>· {{ .BuildTime }}</span>
  </footer>
  {{ end }}

• Step 6: Style the footer

Append to internal/server/static/chrome.css:

/* Version footer — subtle build-identity stamp, bottom-right of the chrome. */
.wb-version {
  position: fixed;
  bottom: 0;
  right: 0;
  z-index: 5;
  padding: 2px 8px;
  font-size: 11px;
  line-height: 1.4;
  color: var(--wb-muted, #78716c);
  background: var(--wb-surface, #ffffff);
  border-top-left-radius: 4px;
  border-top: 1px solid var(--wb-rule, #e7e5e4);
  border-left: 1px solid var(--wb-rule, #e7e5e4);
  opacity: 0.6;
}
.wb-version:hover { opacity: 1; }
.wb-version a { color: inherit; text-decoration: none; }
.wb-version a:hover { text-decoration: underline; }

(If chrome.css does not define --wb-muted/--wb-surface/--wb-rule, the fallbacks in the var() calls apply; adjust the fallbacks to match the file's actual palette if it uses different token names.)

• Step 7: Run tests to verify they pass

Run: go test ./internal/server/ -run TestShellRendersVersionFooter -v Expected: PASS.

• Step 8: Verify in a browser

Templates and static assets are embedded via embed.FS — rebuild and restart. Per wiki-browser/CLAUDE.md:

make build
pkill -f 'dist/wiki-browser' || true
nohup ./dist/wiki-browser -config=wiki-browser.dev.yaml >/tmp/wb.log 2>&1 &
disown
playwright-cli open --browser=chromium http://localhost:8080/doc/README.md
playwright-cli screenshot --filename=/tmp/wb-footer.png

make build requires cmd/wb-cd (Task 14). If executing tasks in order, defer this browser step until after Task 14, or temporarily go build -o dist/wiki-browser ./cmd/wiki-browser directly. Read /tmp/wb-footer.png and confirm the version chip is visible, subtle, and bottom-right.

• Step 9: Commit

git add internal/server/embed.go internal/server/handler_doc.go internal/server/templates/shell.html internal/server/static/chrome.css internal/server/handler_doc_test.go
git commit -m "chrome: subtle version footer"

Task 7: Webhook handler rewrite — /api/webhook/ci

Files:

• Modify: internal/server/handler_webhook.go
• Modify: internal/server/server.go
• Test: internal/server/handler_webhook_test.go

The #10 Task-9 handler parsed GitHub's native push event. It now parses the WB Action's payload {deploy, commit, ref, delivery_id}, always triggers doc-sync, and on deploy:true writes the commit to the CD trigger file.

• Step 1: Rewrite the tests

Replace the body of internal/server/handler_webhook_test.go with:

package server

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"net/http"
	"net/http/httptest"
	"os"
	"path/filepath"
	"strings"
	"testing"
)

func sign(secret, body []byte) string {
	m := hmac.New(sha256.New, secret)
	m.Write(body)
	return "sha256=" + hex.EncodeToString(m.Sum(nil))
}

const fakeCommit = "a1b2c3d4e5f6789012345678901234567890abcd"

func TestCIWebhookRejectsMissingSignature(t *testing.T) {
	d := Deps{WebhookSecret: []byte("topsecret")}
	req := httptest.NewRequest("POST", "/api/webhook/ci",
		strings.NewReader(`{"deploy":false,"commit":"`+fakeCommit+`"}`))
	rec := httptest.NewRecorder()
	d.handleCIWebhook(rec, req)
	if rec.Code != http.StatusUnauthorized {
		t.Fatalf("status = %d, want 401", rec.Code)
	}
}

func TestCIWebhookRejectsBadCommit(t *testing.T) {
	secret := []byte("s")
	body := []byte(`{"deploy":false,"commit":"not-a-sha"}`)
	d := Deps{WebhookSecret: secret}
	req := httptest.NewRequest("POST", "/api/webhook/ci", strings.NewReader(string(body)))
	req.Header.Set("X-Hub-Signature-256", sign(secret, body))
	rec := httptest.NewRecorder()
	d.handleCIWebhook(rec, req)
	if rec.Code != http.StatusBadRequest {
		t.Fatalf("status = %d, want 400", rec.Code)
	}
}

func TestCIWebhookSyncOnlyReturns204(t *testing.T) {
	secret := []byte("s")
	body := []byte(`{"deploy":false,"commit":"` + fakeCommit + `","ref":"refs/heads/master"}`)
	d := Deps{WebhookSecret: secret} // GitSync nil, no trigger file — must still 204
	req := httptest.NewRequest("POST", "/api/webhook/ci", strings.NewReader(string(body)))
	req.Header.Set("X-Hub-Signature-256", sign(secret, body))
	rec := httptest.NewRecorder()
	d.handleCIWebhook(rec, req)
	if rec.Code != http.StatusNoContent {
		t.Fatalf("status = %d, want 204", rec.Code)
	}
}

func TestCIWebhookDeployWritesTriggerFile(t *testing.T) {
	secret := []byte("s")
	trigger := filepath.Join(t.TempDir(), "cd-trigger")
	body := []byte(`{"deploy":true,"commit":"` + fakeCommit + `","ref":"refs/heads/master"}`)
	d := Deps{WebhookSecret: secret, CDTriggerFile: trigger}
	req := httptest.NewRequest("POST", "/api/webhook/ci", strings.NewReader(string(body)))
	req.Header.Set("X-Hub-Signature-256", sign(secret, body))
	rec := httptest.NewRecorder()
	d.handleCIWebhook(rec, req)
	if rec.Code != http.StatusNoContent {
		t.Fatalf("status = %d, want 204", rec.Code)
	}
	got, err := os.ReadFile(trigger)
	if err != nil {
		t.Fatalf("trigger file not written: %v", err)
	}
	if strings.TrimSpace(string(got)) != fakeCommit {
		t.Fatalf("trigger file = %q, want %q", got, fakeCommit)
	}
}

func TestCIWebhookDeployWriteFailureReturns5xx(t *testing.T) {
	secret := []byte("s")
	trigger := filepath.Join(t.TempDir(), "missing", "cd-trigger")
	body := []byte(`{"deploy":true,"commit":"` + fakeCommit + `","ref":"refs/heads/master"}`)
	d := Deps{WebhookSecret: secret, CDTriggerFile: trigger}
	req := httptest.NewRequest("POST", "/api/webhook/ci", strings.NewReader(string(body)))
	req.Header.Set("X-Hub-Signature-256", sign(secret, body))
	rec := httptest.NewRecorder()
	d.handleCIWebhook(rec, req)
	if rec.Code < 500 {
		t.Fatalf("status = %d, want 5xx on trigger write failure", rec.Code)
	}
}

func TestCIWebhookDeployWithoutCDConfiguredStill204(t *testing.T) {
	secret := []byte("s")
	body := []byte(`{"deploy":true,"commit":"` + fakeCommit + `","ref":"refs/heads/master"}`)
	d := Deps{WebhookSecret: secret} // CDTriggerFile empty
	req := httptest.NewRequest("POST", "/api/webhook/ci", strings.NewReader(string(body)))
	req.Header.Set("X-Hub-Signature-256", sign(secret, body))
	rec := httptest.NewRecorder()
	d.handleCIWebhook(rec, req)
	if rec.Code != http.StatusNoContent {
		t.Fatalf("status = %d, want 204 (deploy ignored, logged)", rec.Code)
	}
}

• Step 2: Run tests to verify they fail

Run: go test ./internal/server/ -run TestCIWebhook -v Expected: FAIL — handleCIWebhook / Deps.CDTriggerFile undefined.

• Step 3: Rewrite handler_webhook.go

Replace the whole file with:

package server

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log/slog"
	"net/http"
	"os"
	"path/filepath"
	"regexp"
)

// webhookMaxBody caps the request body the webhook handler will read.
const webhookMaxBody = 1 << 20 // 1 MiB — the CI payload is tiny

var fullSHA = regexp.MustCompile(`^[0-9a-f]{40}$`)

// ciPayload is the WB Action's request body.
type ciPayload struct {
	Deploy     bool   `json:"deploy"`
	Commit     string `json:"commit"`
	Ref        string `json:"ref"`
	DeliveryID string `json:"delivery_id"`
}

// handleCIWebhook verifies the WB Action's HMAC-signed delivery, triggers a
// git-sync Sync (the doc pull), and — on deploy:true — writes the approved
// commit to the CD trigger file. Public route: unauthenticated by session,
// protected only by the shared secret. Responds 204 fast after successful
// validation and trigger write; sync and the CD run proceed out of band.
func (d Deps) handleCIWebhook(w http.ResponseWriter, r *http.Request) {
	if len(d.WebhookSecret) == 0 {
		w.WriteHeader(http.StatusServiceUnavailable)
		return
	}
	body, err := io.ReadAll(io.LimitReader(r.Body, webhookMaxBody))
	if err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	if !validSignature(d.WebhookSecret, body, r.Header.Get("X-Hub-Signature-256")) {
		slog.Warn("ci-webhook: signature verification failed", "remote", r.RemoteAddr)
		w.WriteHeader(http.StatusUnauthorized)
		return
	}
	var p ciPayload
	if err := json.Unmarshal(body, &p); err != nil {
		slog.Warn("ci-webhook: bad payload", "err", err)
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	if !fullSHA.MatchString(p.Commit) {
		slog.Warn("ci-webhook: malformed commit", "commit", p.Commit, "delivery", p.DeliveryID)
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	if d.GitSync != nil {
		wantRef := "refs/heads/" + d.GitSync.Branch()
		if p.Ref != wantRef {
			slog.Warn("ci-webhook: ref not the synced branch", "ref", p.Ref, "want", wantRef)
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		d.GitSync.RequestSync()
	}
	if p.Deploy {
		if d.CDTriggerFile == "" {
			slog.Warn("ci-webhook: deploy requested but cd is not configured",
				"commit", p.Commit, "delivery", p.DeliveryID)
		} else if err := writeTriggerFile(d.CDTriggerFile, p.Commit); err != nil {
			slog.Error("ci-webhook: write trigger file failed", "err", err)
			w.WriteHeader(http.StatusServiceUnavailable)
			return
		} else {
			slog.Info("ci-webhook: deploy queued", "commit", p.Commit, "delivery", p.DeliveryID)
		}
	}
	w.WriteHeader(http.StatusNoContent)
}

// writeTriggerFile atomically writes commit to path (temp file + rename), so
// the .path unit never observes a half-written trigger.
func writeTriggerFile(path, commit string) error {
	tmp := path + ".tmp"
	if err := os.WriteFile(tmp, []byte(commit+"\n"), 0o644); err != nil {
		return err
	}
	return os.Rename(tmp, filepath.Clean(path))
}

// validSignature constant-time compares the HMAC-SHA256 header.
func validSignature(secret, body []byte, header string) bool {
	if header == "" {
		return false
	}
	m := hmac.New(sha256.New, secret)
	m.Write(body)
	want := "sha256=" + hex.EncodeToString(m.Sum(nil))
	return hmac.Equal([]byte(header), []byte(want))
}

• Step 4: Update Deps and the route

In internal/server/server.go, add to the Deps struct after WebhookSecret:

	// CDTriggerFile is the path wb-cd watches. Empty leaves a deploy:true
	// webhook logged-and-ignored (doc-sync still happens).
	CDTriggerFile string

In Mux, rename the webhook route:

	if len(d.WebhookSecret) > 0 {
		mux.HandleFunc("POST /api/webhook/ci", d.handleCIWebhook)
	}

• Step 5: Run tests to verify they pass

Run: go test ./internal/server/ -run TestCIWebhook -v Expected: PASS.

Run: go test ./internal/server/ -v Expected: PASS — no other test referenced the old /api/webhook/github route or handleGitHubWebhook. If one does, update it to the new route/handler name.

• Step 6: Commit

git add internal/server/handler_webhook.go internal/server/server.go internal/server/handler_webhook_test.go
git commit -m "server: rewrite webhook as /api/webhook/ci with deploy payload"

Task 8: Agent service graceful drain

Files:

• Modify: internal/agent/service.go

• Test: internal/agent/service_test.go

• Step 1: Write the failing test

Add to internal/agent/service_test.go. Reuse the existing service-test harness (fakeRunner, the NewService/ServiceConfig setup used by other tests in the file).

func TestDrainRejectsNewSubmitsAndWaitsForInflight(t *testing.T) {
	// A runner that blocks until released, so a job is genuinely in flight
	// while Drain runs.
	release := make(chan struct{})
	started := make(chan struct{})
	svc := newTestService(t, testServiceOpts{
		runner: blockingRunner{started: started, release: release},
	})

	jobID, err := svc.Submit(SubmitInput{
		Kind: "perspective", SourcePath: "a.md",
		PersonaName: "p", SourceSHA: "s", PersonaSHA: "ps",
	})
	if err != nil {
		t.Fatalf("Submit: %v", err)
	}
	<-started // the job is running

	drained := make(chan bool, 1)
	go func() { drained <- svc.Drain(context.Background()) }()

	// New Submit during the drain must be rejected.
	if _, err := svc.Submit(SubmitInput{
		Kind: "perspective", SourcePath: "b.md",
		PersonaName: "p", SourceSHA: "s", PersonaSHA: "ps",
	}); !errors.Is(err, ErrDraining) {
		t.Fatalf("Submit during drain: err = %v, want ErrDraining", err)
	}

	close(release) // let the in-flight job finish
	if ok := <-drained; !ok {
		t.Fatal("Drain returned false; want true (job finished within budget)")
	}
	_ = jobID
}

func TestDrainHitsCapWhenJobNeverFinishes(t *testing.T) {
	release := make(chan struct{})
	started := make(chan struct{})
	svc := newTestService(t, testServiceOpts{
		runner: blockingRunner{started: started, release: release},
	})
	defer func() { close(release); svc.Stop() }()

	if _, err := svc.Submit(SubmitInput{
		Kind: "perspective", SourcePath: "a.md",
		PersonaName: "p", SourceSHA: "s", PersonaSHA: "ps",
	}); err != nil {
		t.Fatalf("Submit: %v", err)
	}
	<-started

	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
	defer cancel()
	if ok := svc.Drain(ctx); ok {
		t.Fatal("Drain returned true; want false (cap hit before the job finished)")
	}
}

blockingRunner is a Runner whose Run closes started, then blocks on release, then returns a success RunResult. Add it to the test file (mirror the existing fakeRunner shape):

type blockingRunner struct {
	started chan struct{}
	release chan struct{}
}

func (r blockingRunner) Run(ctx context.Context, _ Job) RunResult {
	close(r.started)
	select {
	case <-r.release:
	case <-ctx.Done():
	}
	return RunResult{ExitCode: 0}
}

If newTestService/testServiceOpts do not already exist in service_test.go, build the Service inline the way the existing tests do; the behavioural assertions are the contract.

Also add a regression assertion for the acceptance race: the implementation should expose the accepted job to Drain before Submit releases s.mu. If the local test harness can pause storage calls, pause Submit after acceptance but before the runner goroutine starts, call Drain concurrently, and assert it does not return until the paused submit is released and the job finishes. If the existing harness cannot pause storage cleanly, factor the acceptance block into a small helper and unit-test that it sets draining/inflight/wg accounting as one critical section. This test is mandatory: a job accepted before drain begins must not be missed by the wait group.

• Step 2: Run tests to verify they fail

Run: go test ./internal/agent/ -run TestDrain -v Expected: FAIL — Drain / ErrDraining undefined.

• Step 3: Implement Drain

In internal/agent/service.go:

Add to the error var block:

	ErrDraining = errors.New("agent: service is draining; not accepting new jobs")

Add a draining field to the Service struct's mutex-guarded block (next to consecutiveFailures):

	draining bool // guarded by mu

In Submit, add the draining check inside the existing s.mu.Lock() block — right after the lock, before the inflight check:

	s.mu.Lock()
	if s.draining {
		s.mu.Unlock()
		return "", ErrDraining
	}
	if _, ok := s.inflight[key]; ok {
		s.mu.Unlock()
		return "", ErrInflight
	}
	jobID := uuid.NewString()
	s.inflight[key] = struct{}{}
	s.wg.Add(1) // accepted jobs must be visible to Drain before releasing mu
	s.mu.Unlock()

Remove the later jobID := uuid.NewString(), s.inflight[key] = struct{}{}, and s.wg.Add(1) from their old locations. From this point on, any error path before the goroutine is launched must balance both the in-memory gate and the wait group:

releaseAccepted := func() {
	s.releaseInflight(key)
	s.wg.Done()
}

Use releaseAccepted() for checkPersistedInflight / InsertJob failures, and keep the goroutine's existing defer s.wg.Done() for accepted jobs that actually launch. The invariant is: once Submit accepts a job under s.mu, Drain must wait for it even if the job has not reached the runner yet. Do not check draining, unlock, and only later call wg.Add(1) — that reintroduces the race this task is meant to prevent.

Add the Drain method (after Stop):

// Drain stops accepting new jobs and waits for every already-submitted job
// (running or semaphore-queued) to finish, or until ctx is done. It does NOT
// cancel in-flight jobs — that is the whole point. Returns true if all jobs
// finished within ctx, false if ctx fired first; on false the caller should
// Stop() to hard-cancel the stragglers.
func (s *Service) Drain(ctx context.Context) bool {
	s.mu.Lock()
	s.draining = true
	s.mu.Unlock()

	done := make(chan struct{})
	go func() {
		s.wg.Wait()
		close(done)
	}()
	select {
	case <-done:
		return true
	case <-ctx.Done():
		return false
	}
}

• Step 4: Run tests to verify they pass

Run: go test ./internal/agent/ -v Expected: PASS.

• Step 5: Commit

git add internal/agent/service.go internal/agent/service_test.go
git commit -m "agent: Drain — stop new jobs, wait for in-flight"

Task 9: Server draining mode + main.go shutdown sequence

Files:

• Modify: internal/server/server.go

• Modify: cmd/wiki-browser/main.go

• Test: internal/server/server_test.go

• Step 1: Write the failing test

Add to internal/server/server_test.go:

import "sync/atomic" // add to the import block

func TestDrainGuardRejectsMutationsWhileDraining(t *testing.T) {
	var draining atomic.Bool
	inner := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
	})
	h := drainGuard(&draining, inner)

	// Not draining → passes through.
	rec := httptest.NewRecorder()
	h.ServeHTTP(rec, httptest.NewRequest("POST", "/x", nil))
	if rec.Code != http.StatusOK {
		t.Fatalf("not draining: status = %d, want 200", rec.Code)
	}

	// Draining → 503 with Retry-After.
	draining.Store(true)
	rec = httptest.NewRecorder()
	h.ServeHTTP(rec, httptest.NewRequest("POST", "/x", nil))
	if rec.Code != http.StatusServiceUnavailable {
		t.Fatalf("draining: status = %d, want 503", rec.Code)
	}
	if rec.Header().Get("Retry-After") == "" {
		t.Error("draining response missing Retry-After")
	}
}

func TestDrainGuardNilIsPassthrough(t *testing.T) {
	inner := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
	})
	rec := httptest.NewRecorder()
	drainGuard(nil, inner).ServeHTTP(rec, httptest.NewRequest("POST", "/x", nil))
	if rec.Code != http.StatusOK {
		t.Fatalf("nil draining flag: status = %d, want 200", rec.Code)
	}
}

• Step 2: Run tests to verify they fail

Run: go test ./internal/server/ -run TestDrainGuard -v Expected: FAIL — drainGuard undefined.

• Step 3: Add the Deps field and drainGuard

In internal/server/server.go, add "sync/atomic" to the imports, and add to Deps after CDTriggerFile:

	// Draining, when set and true, makes mutating routes return 503 so a
	// redeploy's drain is not extended by new write requests. Nil disables
	// the guard (tests, and any build without a shutdown drain).
	Draining *atomic.Bool

Add the middleware (near withSession in server.go):

// drainGuard returns 503 for mutating requests once draining is set, so the
// shutdown drain is not prolonged by new writes. The CI webhook is guarded
// too: the WB Action retries a 503 against the freshly-started process.
func drainGuard(draining *atomic.Bool, h http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if draining != nil && draining.Load() {
			w.Header().Set("Retry-After", "30")
			writeJSONError(w, http.StatusServiceUnavailable, "draining")
			return
		}
		h.ServeHTTP(w, r)
	})
}