chore(plan-exec): 2026-07-17-worker-daemon-pause-resume — phase "Phase 4: Docs + spec lockstep" passed gates

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGgfho2J6YfRSQN1bSDhj6

Author: edgehero

README.md

@@ -72,6 +72,86 @@ flowchart LR
 
 Read [`SECURITY.md`](SECURITY.md) before you rely on it — it states plainly what is and is not defended.
 
+## Run as a service
+
+`pi-dispatch worker` is a long-running process — run it in a terminal, or hand it to your OS's service
+manager so it starts on boot and restarts on a crash. The units in [`deploy/`](deploy/) are **per-host
+templates, not turnkey**: each carries `<PLACEHOLDER>` paths you fill in for your machine. The systemd
+unit's *structure* is checked by `systemd-analyze`; the launchd and nssm units are worked examples. All
+three run the worker on the **host** — it drives the `docker` CLI and is not itself containerised — so
+they need the AOF-enabled Valkey from [`deploy/docker-compose.yml`](deploy/docker-compose.yml) running
+alongside, which is what makes the queue **and the pause state** survive a reboot.
+
+**Steer the running worker** without stopping it — these commands talk to Valkey, so they work whether the
+worker runs in a terminal or under a service manager:
+
+- `pi-dispatch pause` — stop taking new jobs. **Durable**: the pause lives in the queue and survives a
+  worker restart, so a paused worker comes back paused after a reboot. Jobs still enqueue; they just wait.
+- `pi-dispatch resume` — start taking jobs again.
+- `pi-dispatch status` — prints `{ pausedState, waiting, active, paused, delayed, failed }`. `pausedState`
+  is the switch; `paused` is the backlog **count** of jobs that piled up while paused (they land in the
+  `paused` list, not `waiting`).
+
+### Linux (systemd)
+
+Edit [`deploy/worker.service`](deploy/worker.service): set `WorkingDirectory`, `EnvironmentFile`, `User`,
+and the `node` path to your clone. Then install and start it:
+
+```bash
+sudo cp deploy/worker.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now worker
+```
+
+`systemctl stop worker` sends **SIGTERM** — the worker stops accepting jobs and lets the in-flight
+container drain before it exits.
+
+### macOS (launchd)
+
+Edit [`deploy/com.pi-dispatch.worker.plist`](deploy/com.pi-dispatch.worker.plist) and its wrapper
+[`deploy/worker-env-wrapper.sh`](deploy/worker-env-wrapper.sh): set the repo-root and log paths (launchd
+has no `EnvironmentFile`, so the wrapper loads `.env` at runtime). Then bootstrap it:
+
+```bash
+launchctl bootstrap gui/$(id -u) deploy/com.pi-dispatch.worker.plist
+```
+
+`launchctl bootout gui/$(id -u)/com.pi-dispatch.worker` sends **SIGTERM** for the same graceful drain.
+
+### Windows (nssm)
+
+Put `nssm.exe` on PATH ([nssm.cc](https://nssm.cc)), set `SERVICE` / `REPO` / `LOGDIR` in
+[`deploy/nssm-install.cmd`](deploy/nssm-install.cmd), then run it and start the service:
+
+```
+deploy\nssm-install.cmd
+nssm start pi-dispatch-worker
+```
+
+The wrapper [`deploy/worker-env-wrapper.cmd`](deploy/worker-env-wrapper.cmd) loads `.env` at runtime. A
+console-stop (`nssm stop pi-dispatch-worker`) sends the worker a signal it handles, so it drains
+gracefully.
+
+### Drain before a planned restart
+
+A planned restart should abort no in-flight job. Pause, wait for the queue to go idle, restart, then
+resume:
+
+```bash
+pi-dispatch pause                     # stop taking new jobs (durable)
+pi-dispatch status                    # repeat until "active": 0 — nothing in flight
+sudo systemctl restart worker         # (or the launchctl / nssm equivalent)
+pi-dispatch resume                    # take jobs again
+```
+
+Because the pause is durable, the worker comes back paused even if the restart outruns your `resume`, so
+nothing slips through in the gap.
+
+**Windows caveat**: stop the service with nssm's **console-stop** (`nssm stop`), which delivers a signal
+the worker handles and drains gracefully. Task Scheduler is a weaker fallback — it stops a task with a
+hard kill, giving the worker no chance to drain; a job killed mid-flight leaves a stray container that the
+worker's **boot reaper** clears on the next start, rather than draining cleanly.
+
 ## Advanced: GitHub automation
 
 pi-dispatch can also be triggered by GitHub — label an issue, and a container works it on a fresh clone,
@@ -133,7 +213,8 @@ minutes.
 ## Status
 
 The local-folder path (image, worker, `pi-dispatch run` / `worker`) and the GitHub webhook path
-(receiver → queue → clone → PR) are built and work. The admin panel and scheduled (cron) triggers are in
+(receiver → queue → clone → PR) are built and work; the worker runs in a terminal or as an OS service on
+Linux, macOS or Windows (see **Run as a service**). The admin panel and scheduled (cron) triggers are in
 progress. The design is specified in
 [`specs/`](specs/) — start with [`specs/constitution.md`](specs/constitution.md) for the non-negotiables
 and [`specs/design.md`](specs/design.md) for the decisions and what was rejected.

specs/design.md

@@ -192,6 +192,12 @@ money with no upstream turn limit (`REQ-RUNNER-TURN-BUDGET`).
   throttles concurrent streams and tokens-per-minute long before Docker runs out of memory. A **config
   knob rather than a constant** because one of the two inputs is an unmeasured guess (`OQ-002`), so
   re-tuning after measurement should be a deploy, not a code change.
+- **Boot-reaper invariant — single worker per docker daemon**: The knob is parallelism *within* one worker
+  process; the design assumes exactly one worker per docker daemon. The boot reaper clears every stray
+  `pi-job-*` container on start (a leaked container keeps spending, so it must go before any new job
+  launches) — a co-located second worker sharing the daemon would read the first's in-flight container as
+  its own to remove and kill a live job. Per-host is the common case, but the docker daemon, not the host,
+  is the true boundary.
 - **Traces to**: `OQ-002`, `REQ-QUEUE-BURST-NO-DROP`
 
 ## DES-CRON-VIA-BULLMQ-SCHEDULER
@@ -481,7 +487,8 @@ pi-dispatch/
   flows/          # frontend-fix.md, bug-fix.md, triage.md — DEFAULTS, seeded into the data volume
   persona/        # hard rules; baked into the image. Not runtime-editable
   deploy/         # docker-compose runs Valkey only; worker/receiver/panel are host Node processes
-                  #   (DES-WORKER-ON-HOST). systemd units ship as untested examples.
+                  #   (DES-WORKER-ON-HOST). The systemd unit is a verified-structure per-host template;
+                  #   launchd (.plist) and Windows (nssm) units are added as untested examples.
   .env.example    # provider key, spend/concurrency knobs, VALKEY_URL, PI_JOB_IMAGE
   docs/
 ```
@@ -498,8 +505,11 @@ it is where the SDK traps in `INT-SDK-SESSION-OPTIONS` live, and they are cheape
 else in the frame.
 
 **Platform**: Windows, macOS and Linux, wherever Docker runs. `docker-compose` is the supported
-deployment; systemd units ship as untested examples. Two consequences are not incidental and are tracked
-where they bite: a containerised worker talking to the Docker socket resolves bind-mount paths in the
+deployment; the systemd unit is a verified-structure per-host template — its structure statically checked
+by `systemd-analyze`, its placeholders unresolved, so it is neither turnkey nor end-to-end tested — and
+the launchd (`.plist`) and Windows (nssm) units are added as untested examples. Two consequences are not
+incidental and are tracked where they bite: a containerised worker talking to the Docker socket resolves
+bind-mount paths in the
 *daemon's* namespace, not its own; and a home machine behind NAT cannot receive GitHub webhooks without
 a tunnel.
 

specs/requirements.md

@@ -219,9 +219,11 @@ local), the credential (a short-lived scoped token for GitHub jobs vs none for l
   nothing. Streaming the container output is not a debug nicety — on the operator's own machine, watching
   the agent work on their own folder is the primary feedback surface, and a missing completion line is
   what tells them a run did nothing.
-- **Note on logs**: this is the operator's own terminal for their own folder, not a persistent multi-user
-  log; `no-pii-in-logs` still applies to any *stored* worker logs (log the stable job id and outcome,
-  not task bodies).
+- **Note on logs**: in a terminal this is the operator's own console for their own folder, not a
+  persistent multi-user log. **Under a service manager it becomes one**: the console is the manager's
+  captured, persistent log (systemd's journald, launchd's `StandardOutPath`, nssm's `AppStdout`), so
+  `no-pii-in-logs` applies to it directly — not only to hypothetical *stored* logs. Log the stable job id
+  and outcome, not task bodies.
 - **Traces to**: `CONST-PI-VERSION-PINNED`, `DES-CLI-TRIGGER-FOR-LOCAL`, `INT-RUNNER-EXIT-CODE-PROTOCOL`
 - **Acceptance**: Given a local job reaching a terminal state, the worker console shows exactly one
   completion or failure line carrying the job id and outcome; during the run, the container's output is