@yemi33/minions 0.1.2363 → 0.1.2365

package/dashboard/js/command-center.js

@@ -1286,6 +1286,9 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
         updateStreamDiv();
       } else if (evt.type === 'heartbeat') {
         return;
+      } else if (evt.type === 'status') {
+        streamStatusNote = evt.message || '';
+        updateStreamDiv();
       } else if (evt.type === 'tool') {
         ccSegmentsApplyTool(segments, { name: evt.name, input: evt.input || {}, id: evt.id || null });
         if (activeTab) activeTab._segments = segments;

package/dashboard.js

@@ -2644,15 +2644,14 @@ function _getMtimes() {
   return result;
 }
 
-// Reset the per-source caches whose TTL would otherwise serve stale data
-// across rebuilds. Skill files (`queries._skillsCache` 30s) and MCP servers
-// (`_mcpServersCache` 5min) are the two with TTLs longer than our poll
-// cadence, and both back slices the user sees on screen. Called on every
-// mtime-detected rebuild so the rebuild always reads fresh disk state.
+// Reset per-source caches whose TTL would otherwise survive an mtime-triggered
+// status rebuild and serve stale data.
 function _invalidateInnerCachesForRebuild() {
   try { queries.invalidateSkillsCache(); } catch { /* optional */ }
   _mcpServersCache = null;
   _mcpServersCacheTs = 0;
+  _diskVersionCache = null;
+  _diskVersionCacheTs = 0;
 }
 
 function _mtimesChanged(prev, curr) {
@@ -3706,6 +3705,7 @@ function _ensureCcLiveStream(tabId) {
     tabId,
     text: '',
     tools: [],
+    statusMessage: '',
     donePayload: null,
     writer: null,
     endResponse: null,
@@ -6341,6 +6341,11 @@ const server = http.createServer(async (req, res) => {
       if (!wiPath) {
         const prdFile = body.prdFile;
         if (!prdFile) return jsonReply(res, 404, { error: 'work item not found in any source' });
+        // W-mrdykt9m0006e459 — prdFile is unauthenticated client input; reject
+        // traversal/absolute paths and anything that resolves outside PRD_DIR
+        // before it ever reaches a filesystem read.
+        try { shared.sanitizePath(prdFile, PRD_DIR); }
+        catch { return jsonReply(res, 400, { error: 'invalid prdFile path' }); }
 
         // Look up PRD item to create a new work item on-demand.
         // safeJsonNoRestore — PRDs are terminal artifacts; a stale .backup
@@ -10048,6 +10053,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     if (!hasImages && shared.resolveCcUseWorkerPool(engineConfig)) {
       return _invokeCcStreamViaPool({ prompt, liveState, toolUses, model, effort, engineConfig, systemPrompt, tabId });
     }
+    const setStatus = (message) => {
+      liveState.statusMessage = message;
+      if (liveState.writer) liveState.writer({ type: 'status', message });
+    };
+    if (hasImages) {
+      _touchCcLiveStream(liveState);
+      setStatus('Looking at the image...');
+    }
     const { callLLMStreaming } = require('./engine/llm');
     return callLLMStreaming(prompt, systemPrompt, {
       timeout: CC_CALL_TIMEOUT_MS, label: 'command-center', model, maxTurns,
@@ -10056,11 +10069,17 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       engineConfig, images,
       onChunk: (text, segmentId) => {
         _touchCcLiveStream(liveState);
+        if (liveState.statusMessage) {
+          setStatus('');
+        }
         liveState.text = text;
         if (liveState.writer) liveState.writer({ type: 'chunk', text, segmentId });
       },
       onToolUse: (name, input, id) => {
         _touchCcLiveStream(liveState);
+        if (liveState.statusMessage) {
+          setStatus('');
+        }
         // Claude (direct) now threads a tool_use id; with an id the chip starts
         // 'pending' and can be flipped to completed/failed by onToolUpdate.
         const entry = { name, input: input || {}, id: id || null, status: id ? 'pending' : null };
@@ -10515,6 +10534,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             writeCcEvent({ type: 'tool-update', id: tool.id, status: tool.status });
           }
         }
+        if (live.statusMessage) writeCcEvent({ type: 'status', message: live.statusMessage });
         if (live.text) writeCcEvent({ type: 'chunk', text: live.text });
         if (live.donePayload) {
           writeCcEvent(live.donePayload);
@@ -11276,6 +11296,15 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         } catch { /* unknown/free-text runtime */ }
         return modelStr;
       }
+      const _isClear = (v) => v === '' || v === null;
+      let _registeredCliNames = null;
+      const _validCli = (name) => {
+        if (_registeredCliNames == null) {
+          try { _registeredCliNames = _engineRuntimes.listRuntimes(); }
+          catch { _registeredCliNames = []; }
+        }
+        return _registeredCliNames.length === 0 || _registeredCliNames.includes(String(name));
+      };
       if (body.engine) {
         const e = body.engine;
         const D = shared.ENGINE_DEFAULTS;
@@ -11385,15 +11414,6 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         // chooses)" option submits '' and we must persist that as "unset".
         // Validate `defaultCli` and `ccCli` against the runtime registry so a
         // typo in the dashboard can't pin the fleet to a non-existent runtime.
-        const _isClear = (v) => v === '' || v === null;
-        let _registeredCliNames = null;
-        const _validCli = (name) => {
-          if (_registeredCliNames == null) {
-            try { _registeredCliNames = require('./engine/runtimes').listRuntimes(); }
-            catch { _registeredCliNames = []; }
-          }
-          return _registeredCliNames.length === 0 || _registeredCliNames.includes(String(name));
-        };
         if (e.defaultCli !== undefined) {
           if (_isClear(e.defaultCli)) _deleteEngineConfig('defaultCli');
           else if (_validCli(e.defaultCli)) _setEngineConfig('defaultCli', String(e.defaultCli));
@@ -11589,8 +11609,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // CLI values pin the agent to a specific runtime. `0` is a valid
           // maxBudgetUsd (read-only / dry-run agents).
           if (updates.cli !== undefined) {
-            if (updates.cli === '' || updates.cli === null) delete config.agents[id].cli;
-            else config.agents[id].cli = String(updates.cli);
+            if (_isClear(updates.cli)) delete config.agents[id].cli;
+            else if (_validCli(updates.cli)) config.agents[id].cli = String(updates.cli);
+            else _clamped.push(`agents.${id}.cli: "${updates.cli}" not registered (kept previous value)`);
           }
           if (updates.model !== undefined) {
             if (updates.model === '' || updates.model === null) delete config.agents[id].model;
@@ -14901,7 +14922,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   // dashboard route serves dashboard/slim.html instead of the full SPA.
   // Checked at request time so /api/features/toggle flips behavior with
   // no restart; flag-off means zero behavior change for the catch-all.
-  if (pathname === '/' && features.isFeatureOn('slim-ux', CONFIG)) {
+  const fullDashboardRequested = new URL(req.url, 'http://localhost').searchParams.get('fullDashboard') === '1';
+  if (pathname === '/' && !fullDashboardRequested && features.isFeatureOn('slim-ux', CONFIG)) {
     return serveSlimUx(req, res);
   }
 
@@ -15134,13 +15156,17 @@ if (require.main === module) {
   // engine reads, port binding) is captured rather than dying silently.
   _installCrashHandlers();
 
-  // Every copilot the dashboard spawns — Command Center, doc-chat, and the CC
-  // worker pool (`copilot --acp`) — inherits this process's COPILOT_HOME. Point
-  // it at the seeded, MCP-filtered home so those `direct:true` copilot calls
-  // load the filtered config instead of the operator's full `~/.copilot` stack
-  // (which would pop a Microsoft auth window per call). Mirrors the engine's
-  // boot-time set. See shared.ensureAgentCopilotHome. Fail-open.
-  try { process.env.COPILOT_HOME = shared.ensureAgentCopilotHome(MINIONS_DIR, CONFIG?.engine); } catch {}
+  // Deliberately do NOT set process.env.COPILOT_HOME here. Command Center,
+  // doc-chat, and the CC worker pool (`copilot --acp`) all spawn `copilot`
+  // as this process's children, so they should inherit the operator's real
+  // `~/.copilot` home (including their model preference in settings.json)
+  // exactly like an interactive `copilot` CLI session would — that's the
+  // documented CLI contract. An earlier revision forced these onto an
+  // isolated, MCP-filtered home to dodge MCP-server auth popups, but that
+  // broke CC's settings inheritance and reintroduced a staleness/reseed bug;
+  // reverted (W-mre75l6x00024f49). Per-dispatch agent isolation is unaffected
+  // — the engine process still seeds its own COPILOT_HOME at boot and
+  // re-stamps it per spawn via `_applyAgentCopilotHome` (engine.js).
 
   // Kick off first npm check on startup, then re-check every 4 hours.
   // Guarded here so that requiring dashboard as a module (unit tests, _withDashServer)

package/docs/README.md

@@ -7,14 +7,28 @@ A navigable index of every Markdown file under `docs/`. Entries are grouped by a
 Hands-on stories and distribution guides for people running or evaluating Minions.
 
 - [blog-first-successful-dispatch.md](blog-first-successful-dispatch.md) — Narrative walkthrough of the first end-to-end agent dispatch and the seven failed spawn attempts that preceded it.
-- [distribution.md](distribution.md) — How Minions is published (this repo: `@opg-microsoft/minions` to GitHub Packages; paired peer `yemi33/minions` to npm) and the bidirectional sync contract — automated opg → yemi33 backport workflow + manual yemi33 → opg sync PRs.
+- [documentation-audit-2026-07-09.md](documentation-audit-2026-07-09.md) — Verified user-facing documentation audit covering runtime, CLI, storage, routing, and broken-link corrections.
+- [distribution.md](distribution.md) — How Minions is published (this repo: `@opg-microsoft/minions` to GitHub Packages; paired peer `@yemi33/minions` to npm) and the bidirectional sync contract — automated opg → yemi33 backport workflow + manual yemi33 → opg sync PRs.
+- [onboarding.md](onboarding.md) — Condensed first-30-minutes walkthrough for a new operator.
+- [tutorials/README.md](tutorials/README.md) — Progressive tutorial track from installation through advanced automation and operations.
+
+### Tutorial track
+
+- [tutorials/01-install-and-connect.md](tutorials/01-install-and-connect.md) — Install Minions, verify a runtime, link a project, and start the dashboard.
+- [tutorials/02-first-task.md](tutorials/02-first-task.md) — Dispatch and inspect a bounded first task.
+- [tutorials/03-plan-driven-feature.md](tutorials/03-plan-driven-feature.md) — Review, approve, execute, and verify a dependency-aware plan.
+- [tutorials/04-runtimes-and-harness.md](tutorials/04-runtimes-and-harness.md) — Select runtimes and verify project skill, command, and MCP propagation.
+- [tutorials/05-schedules-and-watches.md](tutorials/05-schedules-and-watches.md) — Combine time-based schedules with state-based watches.
+- [tutorials/06-managed-services.md](tutorials/06-managed-services.md) — Leave an engine-owned development service running with health checks.
+- [tutorials/07-cross-repo-plan.md](tutorials/07-cross-repo-plan.md) — Coordinate one plan across multiple linked repositories.
+- [tutorials/08-operations-and-recovery.md](tutorials/08-operations-and-recovery.md) — Diagnose pending, failed, orphaned, and stopped work safely.
 
 ## Contributor-facing
 
 Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
 
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
-- [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
+- [command-center.md](command-center.md) — Command Center (CC) chat panel: configured-runtime sessions, resume semantics, system-prompt invalidation, and per-tab session storage.
 - [specs/agent-rename.md](specs/agent-rename.md) — Design spec for **agent rename & name decoupling** — the prerequisite for the Role/Agent Library. Formalizes the stable opaque agent id, makes charters name-agnostic, and adds `POST /api/agents/rename` (display name + emoji). Feature-flagged (`agent-rename`) and fully backward-compatible.
 - [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library, feature-flagged behind `agent-library` and fully backward-compatible. Builds on `agent-rename.md`. Role = the reusable durable charter; agent = a thin instance (identity + variable expertise + role pointer). Phase 0 renames `skills`→`expertise`; Phase 1 exposes/edits role charters + per-agent expertise; Phase 2 adds role/agent CRUD with builtin delete-protection.
 - [completion-reports.md](completion-reports.md) — Canonical schema for the per-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
@@ -26,7 +40,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [cross-repo-plans.md](cross-repo-plans.md) — Cross-repo plans: a single plan whose work items ship into two or more configured projects — per-item `project` field, per-project work-item fan-out, and one verify work item per touched repo.
 - [dead-code-audit-retractions.md](dead-code-audit-retractions.md) — Retracted dead-code-audit findings (false positives) that future audits MUST read before re-citing.
 - [deprecated-process.md](deprecated-process.md) — Schema for `docs/deprecated.json` and the weekly `cleanup-deprecated` audit walk that retires entries past their removal signal.
-- [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target (accepted; implementation tracked in CHANGELOG.md Phases 0–9).
+- [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` (accepted; implementation tracked in CHANGELOG.md Phases 0–10).
 - [harness-mode.md](harness-mode.md) — Tri-Agent Harness Mode (`harness_mode: "tri_agent"` on scheduled tasks): Planner → Generator → Evaluator loop that iterates a shared on-disk artifact until a rubric passes or the iteration cap fires.
 - [harness-propagation.md](harness-propagation.md) — How user-level and project-local harness assets (skills, slash-commands, MCP config, `CLAUDE.md` / `AGENTS.md`) propagate into an agent's worktree via `--add-dir`, the `harnessPropagateProjectLocal` flag, and the project-local-on-main worktree-visibility footgun.
 - [harness-transparency.md](harness-transparency.md) — The `harnessUsed` self-report contract: capture (agent reports the skills / MCPs / commands / docs it used) → ground (engine cross-checks against `_harnessPropagated` and annotates `grounded:true\|false`, never dropping) → surface (PR comment, final agent note, work-item modal).
@@ -54,7 +68,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Slim-UX follow-up architecture suggestions paired with `concepts.md`.
 - [team-memory.md](team-memory.md) — Per-agent memory layer (`knowledge/agents/<id>.md`) and the consolidation/routing rules that populate it from `notes/inbox/`.
 - [timeouts-and-liveness.md](timeouts-and-liveness.md) — What kills (or doesn't kill) a live tracked agent: the wall-clock vs steering kill invariants, spawn-phase watchdog gates, steering safety nets, and stale-orphan detection ladder.
-- [watches.md](watches.md) — Persistent monitoring jobs (`engine/watches.json`): target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.
+- [watches.md](watches.md) — Persistent monitoring jobs: target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.
 - [workspace-manifests.md](workspace-manifests.md) — Declarative per-agent permission scoping: `allowed_tools` / `allowed_repos` / `allowed_external_urls` / `memory_scope`, dispatch-time repo gate, and runtime `--allowedTools` narrowing.
 - [worktree-lifecycle.md](worktree-lifecycle.md) — Worktree pool recycling, the live-dispatch guard that prevents wiping an agent's unpushed work, the dirty/divergent quarantine path, and the Windows EPERM/EBUSY file-lock retry footgun.
 
@@ -62,15 +76,13 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 Operational runbooks for engine operators and fleet maintainers.
 
-- [notes.md](notes.md) — Consolidated team knowledge: patterns, conventions, bugs, and build findings accumulated from agent inbox notes. Read by the engine and injected into agent prompts as shared context.
 - [auto-discovery.md](auto-discovery.md) — Auto-discovery and execution pipeline: the per-tick orchestration loop and the four work-discovery sources.
 - [diagnostics-memory.md](diagnostics-memory.md) — Operator runbook for the in-process memory + perf observability surface: `/api/diagnostics/memory[/history]`, `/api/diagnostics/heap-snapshot` guard-token capture, `MEMORY_BASELINE` log emissions, `--cpu-prof`/`--heap-prof` capture, and the `test/perf/soak.test.js` heap-growth regression gate.
 - [diagnostics-crash-reports.md](diagnostics-crash-reports.md) — Proactive Node crash-diagnostics reports (`--report-on-fatalerror --report-on-signal --diagnostic-dir=...`) for the engine.js process on Windows: where reports land, config/opt-out, and retention.
 - [engine-restart.md](engine-restart.md) — How agents survive an engine restart: state persistence, the 20-minute startup grace period, and orphan reattachment via PID files and `live-output.log`.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.
-- [onboarding.md](onboarding.md) — First-30-minutes walkthrough for a new operator: install, init, dispatch a first work item, watch it land.
-- [preflight.md](preflight.md) — `minions doctor` and the lighter per-CLI `minions preflight` checks: what each non-self-explanatory row (permission bypass, runtime detection, drive-root, etc.) is asserting.
+- [preflight.md](preflight.md) — `minions doctor` and the internal initialization/startup preflight: what each non-self-explanatory row (permission bypass, runtime detection, drive-root, etc.) is asserting.
 - [security.md](security.md) — Threat model: single-user/loopback deployment assumptions, dashboard Origin gate, data-flow trust boundaries, secret handling, and known residual risks (CSRF sweep, prompt injection, log-redactor audit).
 
 ---

package/docs/architecture-review-2026-07-09.md

@@ -0,0 +1,94 @@
+# Architecture Review — 2026-07-09
+
+Scope: engine orchestration, SQL/JSON state boundaries, runtime/process recovery,
+worktree lifecycle, pipelines/schedules, dashboard/API settings, and prompt
+assembly. Findings were verified against `origin/main` at `b1b83dd2`.
+
+## Fixed in this change
+
+### High: Codex processes were rejected by orphan recovery
+
+`isProcessCommandLineMatchingAgent` recognized only Claude and Copilot. After an
+engine restart, a live Codex dispatch could therefore be classified as a
+recycled PID and retried while the original process was still running.
+
+The process gate now recognizes all bundled runtime CLIs, including native and
+npm-installed Codex and Claude layouts, without accepting unrelated substring
+matches.
+
+### High: worktree GC lost the project name from real dispatch rows
+
+Worktree GC assumed `dispatch.meta.project` was a string, while production
+dispatches store a project descriptor object. In shared worktree-root layouts,
+the resulting `default` hash could fail to protect another project's active
+worktree from orphan cleanup.
+
+GC now resolves both the current object shape and the legacy string shape.
+
+### Medium: invalid per-agent runtimes bypassed settings validation
+
+Fleet runtime fields were validated against the adapter registry, but
+`agents.<id>.cli` was persisted verbatim. A typo could poison future dispatches
+with a runtime-resolution failure. Per-agent overrides now share the fleet
+validation path and preserve the previous value on invalid input.
+
+### Medium: the no-TTL status cache omitted its own source files
+
+`/api/status` includes config-, install-, and package-derived fields but its
+mtime registry omitted `config.json`, `.install-id`, and `package.json`.
+Out-of-process changes could remain stale indefinitely. These inputs now
+participate in cache invalidation.
+
+### Medium: Slim UX trapped users away from advanced settings
+
+Slim linked to `/?fullDashboard=1`, but root takeover ignored the query string
+and served Slim again. The root dispatcher now honors that explicit classic-UX
+escape hatch.
+
+### Low: prompt validation generated warnings for valid templates
+
+The validator required the literal `## Your Task`, while established playbooks
+also use `## Task Description` and `## Mission`. Those valid aliases now satisfy
+the task-section contract, eliminating recurring false-positive warnings.
+
+### Low: cancelled cron work blocked future schedule fires
+
+The dashboard run-now path already treated cancelled work as terminal, but the
+engine's cron enqueue dedup did not. Both paths now allow a new run after
+cancellation.
+
+## Verified follow-up findings
+
+These require separate focused changes rather than expanding this PR:
+
+1. **Dispatch SQL/JSON empty-state resurrection (high).** A process that has not
+   written SQL can still adopt stale `dispatch.json` when the SQL table is empty.
+   The durable fix is a mirror-generation/hash marker or removal of the legacy
+   fallback, not moving filesystem writes inside a SQLite transaction.
+2. **Pipeline task terminal-state model (high).** Task stages use a boolean
+   completion check and promote failed work items to a completed pipeline stage;
+   cancelled/review-blocked work can wedge indefinitely. Replace the boolean
+   helper with an explicit terminal outcome (`completed`, `failed`,
+   `waiting-human`, non-terminal) and propagate it through parallel stages.
+3. **Settings save spans two independent writes (medium).** Config and routing
+   are saved through separate endpoints, so routing failure can leave a partial
+   configuration update. A combined transactional settings contract should
+   replace the client-side two-step sequence.
+4. **ADO identity lookup duplication (medium).** PR polling resolves the same
+   authenticated user more than once per PR. Cache it once per organization and
+   poll pass to reduce throttling pressure.
+5. **Late descendant process leak window (medium).** Spawn cleanup snapshots
+   descendants at 3 seconds and then every 30 seconds. Children created and
+   reparented inside that window can evade final cleanup. Track descendants more
+   frequently while the runtime is alive.
+6. **Supervisor stale PID reuse (medium).** Startup trusts any live PID in
+   `supervisor.pid`. Validate the command line against this checkout's
+   `engine/supervisor.js` before suppressing startup.
+
+## Healthy areas
+
+- Config/routing references and schedule schemas were valid.
+- Runtime work-item and pull-request mirrors had no stuck dispatched rows,
+  duplicate PR IDs, or unknown PR states.
+- No active dispatch was older than the five-hour wall-clock limit.
+- Cooldown state was small and not exhibiting pending-context bloat.

package/docs/command-center.md

@@ -1,8 +1,8 @@
 # Command Center
 
-The Command Center (CC) is the dashboard's conversational chat panel. It opens from the **CC** button in the top-right header and lets you drive the engine — dispatching work items, saving notes, approving plans, and asking questions about minions state — through a persistent Claude/Copilot session with full repo awareness.
+The Command Center (CC) is the dashboard's conversational chat panel. It opens from the **CC** button in the top-right header and lets you drive the engine — dispatching work items, saving notes, approving plans, and asking questions about Minions state — through a persistent session on the configured CC runtime.
 
-CC is intentionally a thin wrapper around the runtime CLI: state changes happen via `Bash`-tool `curl` calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/llm.js` `callLLM({ direct: true })` → claude/copilot CLI session persisted in `engine/cc-sessions.json`. Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
+CC is intentionally a thin wrapper around the runtime CLI: state changes happen via tool-driven calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/llm.js` `callLLM({ direct: true })` → runtime session persisted in `engine/state.db` (`cc_sessions`; `engine/cc-sessions.json` is a passive mirror). Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
 
 For canonical detail (system prompt, session lifecycle, turn-ID surfacing pipeline, doc-chat integration, and CC API contract), read [`CLAUDE.md`](../CLAUDE.md) — see the **CC API Contract** and **Sessions** sections — and the source in [`dashboard/js/command-center.js`](../dashboard/js/command-center.js), [`dashboard.js`](../dashboard.js) (`handleCommandCenter`), and [`prompts/cc-system.md`](../prompts/cc-system.md).
 
@@ -70,6 +70,8 @@ Any violation rejects the **whole turn** with a typed error envelope (`code: 'in
 
 **Worker-pool interaction (W-mray463s001zcee2).** The opt-in Copilot ACP worker pool (`engine.ccUseWorkerPool: true`, default ON for Copilot CC) is a **separate protocol path** from the table above — `engine/cc-worker-pool.js`'s `session/prompt` call only ever sends a single text content block (`[{ type: 'text', text: prompt }]`) and has no image/attachment content-block support today. This used to mean image turns were silently dropped whenever the pool was active, with a comment incorrectly blaming a Copilot capability gap (`imageInput:false`) that doesn't exist — Copilot's `imageInput` is `true` and fully supports images on the direct spawn path. The fix: `_invokeCcStream` (dashboard.js) now checks for a non-empty `images` array **before** routing through `resolveCcUseWorkerPool` — image-bearing turns bypass the warm pool for that turn only and cold-spawn a one-off CLI process via the working `--attachment` path (same as the non-pooled path always used), while image-less turns keep using the fast warm pool. If `engine/cc-worker-pool.js`'s ACP session protocol is later extended to carry attachments (Option A), this per-turn bypass in `_invokeCcStream` should be revisited/removed.
 
+Because that bypass can spend tens of seconds starting a one-off process before the first model token, the SSE stream shows a user-focused “Looking at the image…” status instead of exposing the cold-start implementation detail or leaving an apparently stalled spinner.
+
 `_resolveImageOpts` (in `engine/llm.js`) is pure and unit-tested: it forwards the `images` list only when `runtime.capabilities.imageInput` is truthy, otherwise returns the typed error so CC/doc-chat surface the envelope instead of a silently-text-only reply. `_spawnProcess` re-applies the same gate (`if (!caps.imageInput) adapterOpts.images = undefined`) as defense in depth. Image **filenames** are run through the untrusted-input fence (`buildSource('cc-image-filename', …)`) before they reach prompt text, since they are user-supplied.
 
 **No new `engine.*` flag.** The limits above are module-level constants in `dashboard.js` (`CC_IMAGE_MAX_COUNT`, `CC_IMAGE_MAX_DECODED_BYTES`, `CC_IMAGE_MIME_ALLOWLIST`), not config keys; `engine/shared.js` `ENGINE_DEFAULTS` was not touched. Per CLAUDE.md Best Practice #9 (Settings parity), no Settings toggle is added because no new `engine.*` flag was introduced. Runtime selection that determines whether images are accepted is the existing `engine.ccCli` / `ccModel` override, which already has a Settings control.

package/docs/constants.md

@@ -6,7 +6,7 @@ All cross-cutting status / type / condition values are defined in [`engine/share
 WI_STATUS = { PENDING, DISPATCHED, DONE, FAILED, PAUSED, QUEUED, DECOMPOSED, CANCELLED }
 DONE_STATUSES = Set([WI_STATUS.DONE, 'in-pr', 'implemented', 'complete'])  // legacy aliases on read only
 WORK_TYPE = { IMPLEMENT, IMPLEMENT_LARGE, FIX, REVIEW, VERIFY, PLAN, PLAN_TO_PRD,
-              DECOMPOSE, MEETING, EXPLORE, ASK, TEST, DOCS, SETUP }
+              DECOMPOSE, MEETING, EXPLORE, ASK, TEST, DOCS, SETUP, BUILD_FIX_COMPLEX }
 PLAN_STATUS = { ACTIVE, AWAITING_APPROVAL, APPROVED, PAUSED, REJECTED, COMPLETED, REVISION_REQUESTED }
 PRD_ITEM_STATUS = { MISSING, UPDATED, DONE };  PRD_MATERIALIZABLE = Set([MISSING, UPDATED])
 PR_STATUS = { ACTIVE, MERGED, ABANDONED, CLOSED, LINKED };  PR_POLLABLE_STATUSES = Set([ACTIVE, LINKED])

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

@@ -0,0 +1,43 @@
+# Documentation Audit: 2026-07-09
+
+Scope: `README.md`, `CLAUDE.md`, `docs/**/*.md`, `playbooks/*.md`,
+`agents/*/charter.md`, and `prompts/*.md`.
+
+The audit prioritized user-facing claims that can cause an operator to install
+the wrong runtime, use a nonexistent command, inspect a passive state mirror as
+canonical data, or misunderstand routing and dashboard behavior.
+
+## Corrected findings
+
+| 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:3520`, `engine/runtimes/index.js` |
+| Root and per-project JSON trackers were described as primary state | Migrated runtime state is primary in `engine/state.db`; JSON trackers are passive mirrors | `engine/dispatch-store.js:49-68`, `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:504`, `engine/projects.js:564` |
+| `WORK_TYPE` documentation omitted complex build fixes | Added `BUILD_FIX_COMPLEX` | `engine/shared.js:4370-4396`, `routing.md:10-28` |
+| Command Center sessions were described as a JSON-file store | Sessions are stored in SQLite; the JSON file is a mirror | `engine/shared.js:1830`, `engine/db/migrations/011-remaining-state.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` |
+| 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
+
+The tutorial track under [`docs/tutorials/`](tutorials/README.md) now covers:
+
+1. installation and project linking;
+2. a first bounded dispatch;
+3. plan-to-PRD implementation and verification;
+4. runtime and harness configuration;
+5. schedules and watches;
+6. managed development services;
+7. cross-repository plans;
+8. operations and recovery.
+
+## Follow-up policy
+
+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
+routes against `dashboard.js`, work types against `routing.md`, and state
+storage claims against the SQL store modules.

package/docs/engine-restart.md

@@ -10,8 +10,8 @@ When the engine restarts, it loses its in-memory process handles (`activeProcess
 
 | State | Storage | Survives Restart |
 |-------|---------|-----------------|
-| Dispatch queue (pending/active/completed) | `engine/dispatch.json` | Yes |
-| Agent status (working/idle/error) | Derived from `engine/dispatch.json` | Yes |
+| Dispatch queue (pending/active/completed) | `engine/state.db` (`dispatches`; `engine/dispatch.json` is a passive mirror) | Yes |
+| Agent status (working/idle/error) | Derived from `engine/state.db` | Yes |
 | Agent live output | `agents/*/live-output.log` | Yes (mtime used for orphan cleanup) |
 | Process handles (`ChildProcess`) | In-memory Map | **No** |
 | Cooldown timestamps | In-memory Map | **No** (repopulated from `engine/cooldowns.json`) |

package/docs/managed-spawn.md

@@ -1,7 +1,7 @@
 # Managed-spawn primitive
 
 > Engine-owned long-running services with sidecar declaration, healthcheck-gated dispatch SUCCESS, and dashboard discovery.
-> Plan: [`plans/plan-w-mp7k1r760003b5dd-2026-05-15.md`](../plans/plan-w-mp7k1r760003b5dd-2026-05-15.md) · Module: [`engine/managed-spawn.js`](../engine/managed-spawn.js) · Dashboard panel: `/engine` → "Managed Processes".
+> Module: [`engine/managed-spawn.js`](../engine/managed-spawn.js) · Dashboard panel: `/engine` → "Managed Processes".
 
 ## Why this exists