@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/design-state-storage.md

@@ -2,7 +2,7 @@
 
 > Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Implemented**
 
-> **Implementation status:** Migrations 001–024 implement the full SQLite cutover and final compatibility cleanup. `engine/state.db` is the sole runtime-state authority; migration 018 records the cutover, migrations 020–024 absorb the remaining scoped/archive/session state and one-time PRD collision repair. Historical migrations retain one-time JSON import support. Normal runtime never references retired mirrors. `minions state check`, `backup`, and `export` provide operations support; explicit offline recovery import is available through `minions state import-legacy-json <dir> --confirm`. The remaining sections are retained as historical design rationale.
+> **Implementation status:** Migrations 001–024 implement the full SQLite cutover and final compatibility cleanup. `engine/state.db` is the sole runtime-state authority; migration 018 records the cutover, migrations 020–024 absorb the remaining scoped/archive/session state and one-time PRD collision repair. Historical migrations retain one-time JSON import support. Normal runtime never references retired mirrors. `minions state check`, `backup`, `summary`, `verify-backup`, and `export` provide operations support; explicit offline recovery import is available through `minions state import-legacy-json <dir> --confirm`. The remaining sections are retained as historical design rationale.
 
 ## Executive Summary
 
@@ -30,11 +30,11 @@ Minions previously persisted runtime state as flat JSON files guarded by file-lo
 
 **Total live state:** ~1.8 MB across 9+ JSON files.
 
-(source: `engine/shared.js` `mutateJsonFileLocked` (~L1542) for locking, `engine/queries.js` for paths, live file sizes from `ls -la engine/*.json`)
+(source: `engine/core/shared.js` `mutateJsonFileLocked` (~L1542) for locking, `engine/core/queries.js` for paths, live file sizes from `ls -la engine/*.json`)
 
 ### 1.2 Concurrency Model
 
-All mutations go through `mutateJsonFileLocked()` (source: `engine/shared.js` ~L1542):
+All mutations go through `mutateJsonFileLocked()` (source: `engine/core/shared.js` ~L1542):
 
 ```
 acquire .lock file (exclusive create via fs.openSync 'wx')
@@ -46,12 +46,12 @@ release .lock file
 ```
 
 Key properties:
-- **Synchronous blocking** — `withFileLock` spins with `sleepMs(25)` until lock acquired or 5s timeout (source: `engine/shared.js` `withFileLock` ~L1329)
+- **Synchronous blocking** — `withFileLock` spins with `sleepMs(25)` until lock acquired or 5s timeout (source: `engine/core/shared.js` `withFileLock` ~L1329)
 - **Whole-file granularity** — updating one field in one work item rewrites all 180 items (370 KB)
-- **Stale lock recovery** — locks older than 5 min (`LOCK_STALE_MS = 300_000`) are force-removed; holders that recorded a `{pid, ts, token}` payload are kept alive past the threshold while `process.kill(pid, 0)` succeeds, with a hard last-resort cap at 5×LOCK_STALE_MS (source: `engine/shared.js`, P-b7d4e8f2)
-- **Identity-checked reap and release** — every acquisition stamps a unique `token` into the lock payload. Reaping never unlinks the lock path directly: the reaper re-observes the same token after a short grace delay, takes custody with an atomic `rename`, and verifies the quarantined file is the acquisition it judged stale (restoring it otherwise). Release likewise unlinks only while the on-disk token is still ours. Removing a lock by path alone is a TOCTOU that lets a second writer into the critical section and silently loses one update (source: `engine/shared.js` `withFileLock`, W-ms2nbtkj00016ffc)
+- **Stale lock recovery** — locks older than 5 min (`LOCK_STALE_MS = 300_000`) are force-removed; holders that recorded a `{pid, ts, token}` payload are kept alive past the threshold while `process.kill(pid, 0)` succeeds, with a hard last-resort cap at 5×LOCK_STALE_MS (source: `engine/core/shared.js`, P-b7d4e8f2)
+- **Identity-checked reap and release** — every acquisition stamps a unique `token` into the lock payload. Reaping never unlinks the lock path directly: the reaper re-observes the same token after a short grace delay, takes custody with an atomic `rename`, and verifies the quarantined file is the acquisition it judged stale (restoring it otherwise). Release likewise unlinks only while the on-disk token is still ours. Removing a lock by path alone is a TOCTOU that lets a second writer into the critical section and silently loses one update (source: `engine/core/shared.js` `withFileLock`, W-ms2nbtkj00016ffc)
 - **Compromised sections fail loudly** — if the lock is gone or re-owned when the critical section ends, `withFileLock` throws `ELOCKCOMPROMISED`. `mutateJsonFileLocked` / `mutateTextFileLocked` first re-apply the mutation against the current on-disk state (up to `LOCK_COMPROMISE_REDOS`) when their own write did not survive, so a raced update is recovered rather than dropped
-- **Read caching** — only `dispatch.json` has a 2s TTL cache (source: `engine/queries.js`)
+- **Read caching** — only `dispatch.json` has a 2s TTL cache (source: `engine/core/queries.js`)
 
 ### 1.3 Read vs Write Ratio
 
@@ -228,13 +228,13 @@ A creative zero-dep option: use append-only JSON Lines files as the write log, w
 
 Stay with files. Fix the two highest-pain issues immediately:
 
-1. **Cap `cooldowns.json`** — Add a cleanup sweep that deletes entries older than 7 days. This file is 511 KB with 125 keys, most of which are stale. Implement in `engine/cooldown.js` cleanup function. (source: `engine/cooldown.js`)
+1. **Cap `cooldowns.json`** — Add a cleanup sweep that deletes entries older than 7 days. This file is 511 KB with 125 keys, most of which are stale. Implement in `engine/orchestration/cooldown.js` cleanup function. (source: `engine/orchestration/cooldown.js`)
 
-2. **Cap `dispatch.json` completed array** more aggressively — Currently capped at 100 entries (source: `engine/dispatch.js:112-114`). Reduce to 50 or archive to `dispatch/completed/` directory. The 380 KB file is mostly completed entries.
+2. **Cap `dispatch.json` completed array** more aggressively — Currently capped at 100 entries (source: `engine/orchestration/dispatch.js:112-114`). Reduce to 50 or archive to `dispatch/completed/` directory. The 380 KB file is mostly completed entries.
 
-3. **Add read caches to `work-items.json` and `pull-requests.json`** — Same 2s TTL pattern as dispatch.json (source: `engine/queries.js:82-91`). These are read 8+ times per tick but only written 1-2 times.
+3. **Add read caches to `work-items.json` and `pull-requests.json`** — Same 2s TTL pattern as dispatch.json (source: `engine/core/queries.js:82-91`). These are read 8+ times per tick but only written 1-2 times.
 
-4. **Convert `log.json` to append-only JSONL** — Eliminates the parse-entire-file-to-append pattern in `_flushLogBuffer()` (source: `engine/shared.js` `_flushLogBuffer` ~L499). Log rotation becomes `readFile → keep last 2000 lines → writeFile` instead of `parse JSON array → splice → stringify → write`.
+4. **Convert `log.json` to append-only JSONL** — Eliminates the parse-entire-file-to-append pattern in `_flushLogBuffer()` (source: `engine/core/shared.js` `_flushLogBuffer` ~L499). Log rotation becomes `readFile → keep last 2000 lines → writeFile` instead of `parse JSON array → splice → stringify → write`.
 
 ### Phase 2: `node:sqlite` Migration (When API stabilizes — estimated Node 26 LTS)
 

package/docs/diagnostics-crash-reports.md

@@ -12,7 +12,7 @@ crash of `node.exe` would have vanished without a trace.
 ## What this does
 
 Every spawn of `engine.js` — via `minions start`/`restart` (`bin/minions.js`)
-**and** the supervisor's respawn-on-death path (`engine/supervisor.js`) —
+**and** the supervisor's respawn-on-death path (`engine/recovery/supervisor.js`) —
 now gets Node's own diagnostic-report flags folded into `NODE_OPTIONS`:
 
 ```
@@ -44,7 +44,7 @@ existing `engine/diagnostics/` directory used for heap snapshots and
 CPU/heap profiles (see [docs/diagnostics-memory.md](diagnostics-memory.md)
 §3–4), in its own subfolder so retention sweeps don't collide. The directory
 is gitignored and created on first spawn if missing
-(`getEngineCrashDiagnosticsEnv`, [`engine/shared.js`](../engine/shared.js)).
+(`getEngineCrashDiagnosticsEnv`, [`engine/core/shared.js`](../engine/core/shared.js)).
 
 ## Config + opt-out
 
@@ -67,12 +67,12 @@ is gitignored and created on first spawn if missing
   after editing `enabled`, since it only takes effect at the next spawn.
 
 Both live in `ENGINE_DEFAULTS.crashDiagnostics`
-([`engine/shared.js`](../engine/shared.js)).
+([`engine/core/shared.js`](../engine/core/shared.js)).
 
 ## Retention / cleanup
 
-Reports are pruned by `pruneCrashDiagnosticsReports` (`engine/shared.js`),
-called from `engine/cleanup.js#runCleanup` — the same periodic cleanup pass
+Reports are pruned by `pruneCrashDiagnosticsReports` (`engine/core/shared.js`),
+called from `engine/orchestration/cleanup.js#runCleanup` — the same periodic cleanup pass
 that already runs every `ENGINE_DEFAULTS.cleanupEvery` ticks (default 60
 ticks ≈ 10 min at the default 10 s tick interval). It keeps the newest
 `retainCount` files by mtime and deletes the rest, mirroring the existing
@@ -82,7 +82,7 @@ swallowed and retried on the next cleanup pass.
 
 ## Idempotency across the CLI → supervisor respawn chain
 
-Both `bin/minions.js` (initial spawn) and `engine/supervisor.js` (respawn on
+Both `bin/minions.js` (initial spawn) and `engine/recovery/supervisor.js` (respawn on
 death) call the same `getEngineCrashDiagnosticsEnv(config)` helper. It checks
 whether the caller's `NODE_OPTIONS` already contains `--diagnostic-dir=`
 (which a spawned child inherits from its parent's env) and returns `{}`
@@ -119,13 +119,13 @@ a second or two, without killing the process.
 
 ## Related modules and tests
 
-- Module: [`engine/shared.js`](../engine/shared.js) — `CRASH_REPORTS_DIR`,
+- Module: [`engine/core/shared.js`](../engine/core/shared.js) — `CRASH_REPORTS_DIR`,
   `getEngineCrashDiagnosticsEnv`, `pruneCrashDiagnosticsReports`,
   `ENGINE_DEFAULTS.crashDiagnostics`.
 - Spawn wiring: [`bin/minions.js`](../bin/minions.js)
   (`spawnFullStackAndVerify`, the post-install/upgrade auto-start path) and
-  [`engine/supervisor.js`](../engine/supervisor.js) (`spawnEngine`).
-- Cleanup wiring: [`engine/cleanup.js`](../engine/cleanup.js) `runCleanup`.
+  [`engine/recovery/supervisor.js`](../engine/recovery/supervisor.js) (`spawnEngine`).
+- Cleanup wiring: [`engine/orchestration/cleanup.js`](../engine/orchestration/cleanup.js) `runCleanup`.
 - Tests: [`test/unit/crash-diagnostics.test.js`](../test/unit/crash-diagnostics.test.js).
 - Related: [docs/diagnostics-memory.md](diagnostics-memory.md) (memory/GC/heap
   observability — the sibling diagnostics surface this doc's directory lives

package/docs/diagnostics-memory.md

@@ -75,7 +75,7 @@ curl -s http://localhost:7331/api/diagnostics/memory | jq
 ```
 
 Field reference (every value originates from
-[`engine/diagnostics-memory.js`](../engine/diagnostics-memory.js)
+[`engine/observability/diagnostics-memory.js`](../engine/observability/diagnostics-memory.js)
 `sampleSelf()`):
 
 | Field | Source | Units |
@@ -107,7 +107,7 @@ In-memory ring buffer of samples. Two backing rings:
   `DIAGNOSTICS_MEMORY_SAMPLE_INTERVAL_MS = 60 000` ms,
   [`dashboard.js:122`](../dashboard.js)). Capacity is
   `RING_BUFFER_CAP = 1440` samples (≈ 24 h at 60 s cadence,
-  [`engine/diagnostics-memory.js:28`](../engine/diagnostics-memory.js)).
+  [`engine/observability/diagnostics-memory.js:28`](../engine/observability/diagnostics-memory.js)).
 - `process=engine` — the dashboard's **polled accumulation** of the
   engine's sidecar. Engine.js only persists the latest sample to
   `engine/diagnostics-memory.json`, so engine-side history is rebuilt by
@@ -148,7 +148,7 @@ A 400 is returned when `process` is missing or not exactly one of
 
 Every `ENGINE_DEFAULTS.memoryBaselineEveryTicks` ticks (default `6`,
 defined at
-[`engine/shared.js:3092`](../engine/shared.js)), the engine emits one
+[`engine/core/shared.js:3092`](../engine/core/shared.js)), the engine emits one
 structured log line and writes the latest sample to the sidecar. At the
 default `tickInterval: 10` the cadence is ≈ 60 s.
 
@@ -421,7 +421,7 @@ they sit in `notes/inbox/` with predictable slugs:
 | 2 — heap dominators + leak candidates | `P-f6a7b8c9` | `notes/inbox/ripley-memory-audit-phase-2-heap-dominators*.md` | `knowledge/architecture/2026-06-12-ripley-memory-audit-phase-2-heap-dominators.md` |
 | 3 — CPU + allocation hot frames | `P-a7b8c9d0` | `notes/inbox/ripley-memory-audit-phase-3-cpu-and-allocations*.md` | `knowledge/architecture/2026-06-12-ripley-memory-audit-phase-3-cpu-and-allocations.md` |
 
-Use [`engine/kb-sweep.js`](../engine/kb-sweep.js) (see
+Use [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) (see
 [`docs/kb-sweep.md`](kb-sweep.md)) or the dashboard's "Sweep" button to
 trigger promotion. The cheap-win PR items downstream of the explores
 (`P-b8c9d0e1`, `P-c9d0e1f2`, `P-d0e1f2a3`) consume the prioritized lists
@@ -430,7 +430,7 @@ re-deriving the same findings.
 
 ## Related modules and tests
 
-- Module: [`engine/diagnostics-memory.js`](../engine/diagnostics-memory.js) — sampler + ring buffer + GC observer.
+- Module: [`engine/observability/diagnostics-memory.js`](../engine/observability/diagnostics-memory.js) — sampler + ring buffer + GC observer.
 - Engine wiring: [`engine.js`](../engine.js) `emitMemoryBaseline` + `processHeapSnapshotRequest`.
 - Dashboard wiring: [`dashboard.js`](../dashboard.js) `handleDiagnosticsMemory`, `handleDiagnosticsMemoryHistory`, `handleDiagnosticsHeapSnapshot`.
 - Frontend: [`dashboard/pages/engine-memory-panel.html`](../dashboard/pages/engine-memory-panel.html) + [`dashboard/js/memory-panel.js`](../dashboard/js/memory-panel.js).

package/docs/documentation-audit-2026-07-09.md

@@ -12,13 +12,13 @@ canonical data, or misunderstand routing and dashboard behavior.
 | Stale claim | Correction | Source of truth |
 |---|---|---|
 | Node.js 18+ was sufficient | Node.js 22.5+ is required for `node:sqlite` | `package.json:68` |
-| Agent dispatch was described as Claude-only | Copilot is the default fleet runtime; Claude and Codex remain supported | `engine/shared.js:3188`, `engine/runtimes/index.js` |
+| Agent dispatch was described as Claude-only | Copilot is the default fleet runtime; Claude and Codex remain supported | `engine/core/shared.js:3188`, `engine/runtimes/index.js` |
 | Root and per-project JSON trackers were described as primary state | `engine/state.db` is the sole runtime-state authority; retired trackers are migration inputs only | `engine/db/migrations/018-sql-only-cutover.js`, `CLAUDE.md` "State storage" |
-| `minions preflight` was documented as a public command | `minions doctor` is public; lighter checks run internally during initialization and startup | `bin/minions.js:1207-1264`, `engine/cli.js:232-255` |
-| Git repository host default was documented as ADO | The fallback host is GitHub | `engine/projects.js:450`, `engine/projects.js:510` |
-| `WORK_TYPE` documentation omitted complex build fixes | Added `BUILD_FIX_COMPLEX` | `engine/shared.js:4057-4081`, `routing.md:10-28` |
-| Command Center sessions were described as a JSON-file store | Per-tab and global sessions are stored only in SQLite | `engine/small-state-store.js`, `engine/db/migrations/022-global-cc-session.js` |
-| Watches were described as checking every three ticks and persisting to JSON | The default cadence is 18 ticks; persistence routes through the SQL watch store | `engine/shared.js` `watchPollEvery`, `engine/watches-store.js` |
+| `minions preflight` was documented as a public command | `minions doctor` is public; lighter checks run internally during initialization and startup | `bin/minions.js:1207-1264`, `engine/operations/cli.js:232-255` |
+| Git repository host default was documented as ADO | The fallback host is GitHub | `engine/planning/projects.js:450`, `engine/planning/projects.js:510` |
+| `WORK_TYPE` documentation omitted complex build fixes | Added `BUILD_FIX_COMPLEX` | `engine/core/shared.js:4057-4081`, `routing.md:10-28` |
+| Command Center sessions were described as a JSON-file store | Per-tab and global sessions are stored only in SQLite | `engine/persistence/small-state-store.js`, `engine/db/migrations/022-global-cc-session.js` |
+| Watches were described as checking every three ticks and persisting to JSON | The default cadence is 18 ticks; persistence routes through the SQL watch store | `engine/core/shared.js` `watchPollEvery`, `engine/watches/store.js` |
 | Two local documentation links targeted files that are not shipped | Removed the runtime `notes.md` link and the stale managed-spawn plan link | `docs/README.md`, `docs/managed-spawn.md` |
 
 ## New tutorial coverage
@@ -38,6 +38,6 @@ The tutorial track under [`docs/tutorials/`](tutorials/README.md) now covers:
 
 Reference docs remain intentionally detailed. Tutorials should link to those
 references rather than duplicate full schemas. Future sweeps should continue to
-verify CLI examples against `bin/minions.js` and `engine/cli.js`, dashboard
+verify CLI examples against `bin/minions.js` and `engine/operations/cli.js`, dashboard
 routes against `dashboard.js`, work types against `routing.md`, and state
 storage claims against the SQL store modules.

package/docs/engine-restart.md

@@ -1,6 +1,6 @@
 # Engine Restart & Agent Survival
 
-> Last verified: 2026-07-23 against `bin/minions.js`, `engine/cli.js` startup reattachment, `engine/timeout.js`, `engine/restart-health.js`, and `ENGINE_DEFAULTS`.
+> Last verified: 2026-07-29 against `bin/minions.js`, `engine/operations/cli.js` startup reattachment, `engine/orchestration/timeout.js`, `engine/recovery/supervisor.js`, `engine/recovery/restart-health.js`, and `ENGINE_DEFAULTS`.
 
 ## The Problem
 
@@ -41,7 +41,9 @@ Configurable via `config.json`:
 ### 2. Process-Based Liveness
 
 At startup, each non-pooled active dispatch reads its PID file, verifies that
-the process is alive and its persisted execution path is still safe, restores
+the process is alive, verifies its command line still belongs to an agent
+runtime (protecting against PID reuse), and confirms its persisted execution
+path is still safe, restores
 the matching session id when available, and repopulates `activeProcesses` with
 `reattached: true`. A recent `live-output.log` can provide temporary
 unknown-PID liveness when no PID file survived.
@@ -63,7 +65,9 @@ when the drain deadline expires it is cancelled and terminalized as a
 retryable timeout before the old engine exits.
 
 Unexpected crashes remain fail-safe: persisted `item.pooled` dispatches never
-trust the worker PID and are reaped through the normal retry path on startup.
+trust the worker PID and are reaped through the restart-recovery path on startup.
+Restart recovery has its own bounded counter, so host/daemon failures do not
+consume the semantic agent retry or per-agent reassignment budgets.
 
 ### 4. Stop Warning
 
@@ -79,16 +83,38 @@ To kill them now, run: node engine.js kill
 
 ### 5. Exponential Backoff on Failures
 
-If an agent is killed as an orphan and the work item retries, cooldowns use exponential backoff (2^failures, max 8x) to prevent spam-retrying broken tasks.
+If an agent is killed as an orphan and the work item retries, cooldowns use exponential backoff (2^failures, max 8x) to prevent spam-retrying broken tasks. Confirmed restart losses use `_infrastructureRetryCount` (bounded by `ENGINE_DEFAULTS.maxRetries`) instead of `_retryCount`.
 
 ### 6. Crash-Loop Counter + Alert (W-mr2azk6i000y06e0)
 
-The engine.js *process itself* (not an agent) can crash and get auto-respawned by three independent mechanisms: `engine/supervisor.js#checkEngine` (dead-PID), `engine/supervisor.js#checkEngineHung` (stale-heartbeat), and `engine/watchdog.js` (OS-scheduled external recovery); `dashboard.js`'s in-process 30s watchdog also auto-restarts on a dead PID (the user-triggered Restart Engine button is excluded). Each successful respawn calls `shared.recordEngineRespawn(source)`, which appends `{ts, source}` to `control.json`'s `engineRespawns[]` (rolling window, default `CRASH_LOOP_WINDOW_MS` = 10 min). Once respawns within the window reach `CRASH_LOOP_THRESHOLD` (default 3), `control.crashLoopAlert` is set (dashboard-visible via `/api/status`) and a deduped (one-per-day) `notes/inbox/` alert is written; the alert clears automatically once the window rolls past the incident. Override the window/threshold via `MINIONS_CRASH_LOOP_WINDOW_MS` / `MINIONS_CRASH_LOOP_THRESHOLD` env vars.
+The engine.js *process itself* (not an agent) can crash and get auto-respawned by three independent mechanisms: `engine/recovery/supervisor.js#checkEngine` (dead-PID), `engine/recovery/supervisor.js#checkEngineHung` (stale-heartbeat), and `engine/recovery/watchdog.js` (OS-scheduled external recovery); `dashboard.js`'s in-process 30s watchdog also auto-restarts on a dead PID (the user-triggered Restart Engine button is excluded). Each successful respawn calls `shared.recordEngineRespawn(source)`, which appends `{ts, source}` to `control.json`'s `engineRespawns[]` (rolling window, default `CRASH_LOOP_WINDOW_MS` = 10 min). Once respawns within the window reach `CRASH_LOOP_THRESHOLD` (default 3), `control.crashLoopAlert` is set (dashboard-visible via `/api/status`) and a deduped (one-per-day) `notes/inbox/` alert is written; the alert clears automatically once the window rolls past the incident. Override the window/threshold via `MINIONS_CRASH_LOOP_WINDOW_MS` / `MINIONS_CRASH_LOOP_THRESHOLD` env vars.
+
+On Windows, the scheduled watchdog permits parallel one-shot ticks and caps each
+instance at two minutes, so a stranded launcher cannot block future recovery
+fires. Source checkouts pin the task to `<MINIONS_HOME>/bin/minions.js`; packaged
+installs fall back to the installed CLI executable.
+
+Partial state (only engine or dashboard alive) is debounced for 90 seconds.
+After that grace, the OS watchdog starts only the missing component; it never
+tears down the healthy component with `minions restart`. Both-dead state still
+triggers `minions start` immediately. Windows dashboard PID probing also fails
+open: a slow or timed-out `tasklist` command is indeterminate, not evidence
+that the engine died.
 
 ### 7. Exclusive Restart Topology
 
 Managed dashboard spawns must bind the requested port; automatic fallback remains available only for standalone `node dashboard.js` use. Before a supervisor respawn, every matching stale daemon is killed and confirmed dead. If any PID survives, the supervisor skips the replacement and retries on its next tick instead of creating a second engine or a dashboard on another port.
 
+Daemon ownership is exact: cleanup matches the normalized script token under
+the selected runtime root, never a loose `engine.js`/`dashboard.js` substring
+or an unverified port owner. The supervisor also treats a recent 15s engine
+heartbeat as positive liveness evidence when its shell-based PID probe fails,
+and daemon replacement kills only the daemon PID—not its detached cold-agent
+or managed-service descendants. The OS-scheduled watchdog applies the same
+fresh-heartbeat veto before turning simultaneous probe failures into an
+immediate `minions start`, and it stops trusting an existing PID once the
+recorded engine heartbeat is stale.
+
 `minions restart` first verifies that its exact engine and dashboard PIDs are alive and that the dashboard owns the requested-port beacon. It starts the supervisor only after that cold-start phase succeeds, preventing the supervisor's first watchdog tick from replacing a legitimately slow, not-yet-listening dashboard. It then verifies ownership of the exact engine, dashboard, and supervisor PIDs and rejects duplicate daemon processes.
 
 A failed verification tears down the partial stack and leaves `stop-intent.json` set so watchdogs cannot race another replacement into the failed topology. Dashboard failures also print the bounded `engine/dashboard-stdio.log` output written since that spawn, or the log path when the process produced no output, instead of returning only a dead-PID summary.
@@ -97,6 +123,65 @@ PID-bearing file locks are reaped immediately when their recorded owner is dead.
 
 Dashboard hot polling avoids recurring event-loop stalls: freshness-directory walks are coalesced briefly, plan scans are cached for 30 seconds and processed in cooperative batches, and quarantine-ref Git reads run asynchronously in parallel.
 
+## Stopping the Runtime: `minions stop` vs `minions stop --all`
+
+Stopping is deliberately two commands, because "ask the engine to shut down" and
+"quiesce the whole runtime" are different contracts.
+
+| Command | What it does | Blocks until |
+|---------|--------------|--------------|
+| `minions stop` | Delegates to `engine.js stop`: writes stop-intent, stamps the shutdown request into `control.json`, returns. The dashboard and supervisor are untouched. | Nothing — it returns as soon as shutdown is *requested*. |
+| `minions stop --all` | Ordered whole-stack teardown: stop-intent → supervisor → dashboard → graceful engine drain → identity-verified reap → late-respawn sweep → verification. | The daemons being verified down. It reports the `engine/state.db-shm` state but does not wait for it. |
+| `minions stop --all --wait` | The same teardown, and then waits for `engine/state.db-shm` to be released. | The database handles being released, or the budget expiring. |
+
+`--timeout <ms>` sets the budget for the whole sequence (default 60000, matching
+the internal installer's quiescence window).
+
+Bare `minions stop` is unchanged and will stay that way: recovery paths, operator
+scripts, and the engine's own callers depend on "request shutdown and return".
+The whole-stack behavior is strictly opt-in.
+
+**Why `--wait` exists.** The dashboard holds `engine/state.db` open independently
+of the engine, so after an engine-only stop the WAL index (`engine/state.db-shm`)
+is still present and non-empty and every quiescence probe correctly stays red.
+Anything that must touch the database file itself — the internal installer's
+pre-migration gate, a manual backup/restore — needs the release proven, not
+assumed.
+
+### Exit codes
+
+`minions stop --all` reports its result through the exit code, so callers branch
+without scraping stdout (`STOP_STACK_EXIT` in `engine/recovery/stop-stack.js`):
+
+| Code | Meaning | Operator action |
+|------|---------|-----------------|
+| `0` | Stopped. Nothing holds the runtime root. | None. |
+| `3` | Did not quiesce within the budget — a daemon is still alive, or (with `--wait`) the WAL index is still held. | Retry, widen `--timeout`, or find the remaining holder. |
+| `4` | Refused: a live PID could not be proven to belong to this runtime root, so nothing was signalled. | Inspect the reported PID; Minions will not kill a process it cannot verify. |
+
+`4` is deliberately distinct from `3`: when identity cannot be proven, nothing was
+force-killed at all, and telling the operator to widen a budget would be wrong.
+
+### One implementation, four other callers
+
+The sequence itself lives in `engine/recovery/stop-stack.js#stopRuntimeStack`.
+`minions restart`, `minions nuke`, `minions uninstall`, and the `init` upgrade
+path all call it through `stopWholeRuntimeStack()` in `bin/minions.js` — there is
+no second copy of the teardown in the tree.
+
+Those four pass `waitForRelease: false`: they either replace the stack
+immediately or delete the runtime root, so blocking on the WAL index would add
+latency without adding safety. They still get the same ordered teardown, the same
+identity-verified termination, the same late-respawn sweep, and the same
+structured verdict.
+
+`restart` keeps its own budget (`engine.shutdownTimeout + 5000`) and its own
+gates on top: it aborts if a *live daemon of ours* survived the teardown, but not
+when a holder is merely a stale PID file pointing at a foreign process
+(`holderIsLiveDaemon`) — healing that state is exactly what `restart` is for. The
+dashboard port gate, the beacon clearing, and the post-spawn topology
+verification are unchanged.
+
 ## Safe Restart Pattern
 
 ```bash

package/docs/harness-mode.md

@@ -1,7 +1,7 @@
 # Tri-Agent Harness Mode
 
 > Status: opt-in feature flag on scheduled tasks (`harness_mode: "tri_agent"`).
-> Shipped: W-mq07a9gf000jbc2b. Module: [`engine/harness.js`](../engine/harness.js).
+> Shipped: W-mq07a9gf000jbc2b. Module: [`engine/agents/harness.js`](../engine/agents/harness.js).
 
 ## What it is