@yemi33/minions 0.1.2424 → 0.1.2426

package/docs/capture-demos.js

@@ -7,80 +7,182 @@
  * Requires: dashboard running on :7331, playwright chromium installed
  */
 const { chromium } = require('@playwright/test');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
 const path = require('path');
 
 const DEMO_DIR = path.join(__dirname, 'demo');
-const BASE = 'http://localhost:7331';
+const DEFAULT_BASE_URL = 'http://localhost:7331';
 const ROOT = path.resolve(__dirname, '..');
+const SCREENSHOT_FILES = Object.freeze([
+  '01-dashboard-overview.png',
+  '02-work-items.png',
+  '03-plans-prd.png',
+  '04-pull-requests.png',
+  '05-meetings.png',
+  '06-pipelines.png',
+  '07-notes-kb.png',
+  '08-schedules.png',
+  '09-engine.png',
+  '10-command-center.png',
+]);
 
-async function capture() {
-  // Seed demo data
-  console.log('  Seeding demo data...');
-  execSync(`node "${path.join(ROOT, 'test', 'seed-demo-data.js')}"`, { stdio: 'inherit' });
+function parseArgs(argv = process.argv.slice(2)) {
+  const options = {
+    baseUrl: DEFAULT_BASE_URL,
+    outputDir: DEMO_DIR,
+    stateDir: null,
+    skipSeed: false,
+    fixedTime: null,
+  };
+  const valueFor = (flag, index) => {
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+    return value;
+  };
 
-  // Wait for dashboard to pick up seeded data
-  await new Promise(r => setTimeout(r, 5000));
+  for (let i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--base-url':
+        options.baseUrl = valueFor(argv[i], i);
+        i++;
+        break;
+      case '--output-dir':
+        options.outputDir = path.resolve(valueFor(argv[i], i));
+        i++;
+        break;
+      case '--state-dir':
+        options.stateDir = path.resolve(valueFor(argv[i], i));
+        i++;
+        break;
+      case '--fixed-time':
+        options.fixedTime = valueFor(argv[i], i);
+        if (!Number.isFinite(Date.parse(options.fixedTime))) {
+          throw new Error('--fixed-time must be an ISO-8601 timestamp');
+        }
+        i++;
+        break;
+      case '--skip-seed':
+        options.skipSeed = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${argv[i]}`);
+    }
+  }
+  return options;
+}
+
+function runSeed({ clean = false, stateDir = null } = {}) {
+  const args = [path.join(ROOT, 'test', 'seed-demo-data.js')];
+  if (clean) args.push('--clean');
+  if (stateDir) args.push('--state-dir', stateDir);
+  execFileSync(process.execPath, args, { stdio: 'inherit' });
+}
 
-  const browser = await chromium.launch({ headless: true });
-  const ctx = await browser.newContext({ viewport: { width: 1400, height: 900 }, colorScheme: 'dark' });
-  const page = await ctx.newPage();
+async function capture(options = {}) {
+  const {
+    baseUrl = DEFAULT_BASE_URL,
+    outputDir = DEMO_DIR,
+    stateDir = null,
+    skipSeed = false,
+    fixedTime = null,
+  } = options;
+  fs.mkdirSync(outputDir, { recursive: true });
 
+  let browser;
+  let seedAttempted = false;
+  let captureError = null;
   try {
-    await page.goto(BASE, { waitUntil: 'networkidle' });
+    if (!skipSeed) {
+      console.log('  Seeding demo data...');
+      seedAttempted = true;
+      runSeed({ stateDir });
+      await new Promise(r => setTimeout(r, 5000));
+    }
+
+    browser = await chromium.launch({ headless: true });
+    const ctx = await browser.newContext({
+      viewport: { width: 1400, height: 900 },
+      colorScheme: 'dark',
+      locale: 'en-US',
+      timezoneId: 'UTC',
+      reducedMotion: 'reduce',
+    });
+    if (fixedTime) {
+      const now = Date.parse(fixedTime);
+      await ctx.addInitScript(({ timestamp }) => {
+        const NativeDate = Date;
+        class FixedDate extends NativeDate {
+          constructor(...args) {
+            super(...(args.length ? args : [timestamp]));
+          }
+          static now() { return timestamp; }
+        }
+        Object.setPrototypeOf(FixedDate, NativeDate);
+        globalThis.Date = FixedDate;
+      }, { timestamp: now });
+    }
+    const page = await ctx.newPage();
+    const screenshot = (file, { fullPage = false } = {}) => page.screenshot({
+      path: path.join(outputDir, file),
+      fullPage,
+    });
+
+    await page.goto(baseUrl, { waitUntil: 'networkidle' });
     await page.waitForTimeout(3000);
 
     // 1. Home / Overview (agents should show as working from seeded dispatches)
     console.log('  Capturing: home');
-    await page.screenshot({ path: path.join(DEMO_DIR, '01-dashboard-overview.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[0]);
 
     // 2. Work Items
     console.log('  Capturing: work items');
     await page.click('a[data-page="work"]');
     await page.waitForTimeout(2000);
-    await page.screenshot({ path: path.join(DEMO_DIR, '02-work-items.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[1]);
 
     // 3. Plans & PRD (seeded PRD with dependency graph)
     console.log('  Capturing: plans & PRD');
     await page.click('a[data-page="plans"]');
     await page.waitForTimeout(2000);
-    await page.screenshot({ path: path.join(DEMO_DIR, '03-plans-prd.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[2]);
 
     // 4. Pull Requests
     console.log('  Capturing: pull requests');
     await page.click('a[data-page="prs"]');
     await page.waitForTimeout(1500);
-    await page.screenshot({ path: path.join(DEMO_DIR, '04-pull-requests.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[3]);
 
     // 5. Meetings
     console.log('  Capturing: meetings');
     await page.click('a[data-page="meetings"]');
     await page.waitForTimeout(1500);
-    await page.screenshot({ path: path.join(DEMO_DIR, '05-meetings.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[4]);
 
     // 6. Pipelines
     console.log('  Capturing: pipelines');
     await page.click('a[data-page="pipelines"]');
     await page.waitForTimeout(1500);
-    await page.screenshot({ path: path.join(DEMO_DIR, '06-pipelines.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[5]);
 
     // 7. Notes & KB
     console.log('  Capturing: notes & KB');
     await page.click('a[data-page="inbox"]');
     await page.waitForTimeout(1500);
-    await page.screenshot({ path: path.join(DEMO_DIR, '07-notes-kb.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[6]);
 
     // 8. Schedules
     console.log('  Capturing: schedules');
     await page.click('a[data-page="schedule"]');
     await page.waitForTimeout(1500);
-    await page.screenshot({ path: path.join(DEMO_DIR, '08-schedules.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[7]);
 
-    // 9. Engine page (dispatch, log, metrics)
+    // 9. Engine page (dispatch, log, metrics) — full-page so below-the-fold
+    // panels (Keep-Processes, Quarantined Work, Managed Processes) are captured.
     console.log('  Capturing: engine');
     await page.click('a[data-page="engine"]');
     await page.waitForTimeout(1500);
-    await page.screenshot({ path: path.join(DEMO_DIR, '09-engine.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[8], { fullPage: true });
 
     // 10. Command Center with mock conversation
     console.log('  Capturing: command center');
@@ -131,17 +233,58 @@ async function capture() {
       el.scrollTop = el.scrollHeight;
     });
     await page.waitForTimeout(500);
-    await page.screenshot({ path: path.join(DEMO_DIR, '10-command-center.png'), fullPage: false });
+    await screenshot(SCREENSHOT_FILES[9]);
 
+    for (const file of SCREENSHOT_FILES) {
+      const screenshotPath = path.join(outputDir, file);
+      if (!fs.existsSync(screenshotPath) || fs.statSync(screenshotPath).size === 0) {
+        throw new Error(`Capture did not produce ${file}`);
+      }
+    }
+  } catch (error) {
+    captureError = error;
   } finally {
-    await browser.close();
-
-    // Clean up demo data
-    console.log('  Cleaning demo data...');
-    execSync(`node "${path.join(ROOT, 'test', 'seed-demo-data.js')}" --clean`, { stdio: 'inherit' });
+    if (browser) {
+      try {
+        await browser.close();
+      } catch (closeError) {
+        if (!captureError) captureError = closeError;
+        else console.error(`  Browser cleanup failed: ${closeError.message}`);
+      }
+    }
+    if (seedAttempted) {
+      console.log('  Cleaning demo data...');
+      try {
+        runSeed({ clean: true, stateDir });
+      } catch (cleanupError) {
+        if (!captureError) captureError = cleanupError;
+        else console.error(`  Cleanup failed: ${cleanupError.message}`);
+      }
+    }
   }
 
-  console.log('\n  Done! Screenshots saved to docs/demo/');
+  if (captureError) throw captureError;
+  console.log(`\n  Done! Screenshots saved to ${outputDir}`);
+  return SCREENSHOT_FILES.map(file => path.join(outputDir, file));
+}
+
+if (require.main === module) {
+  let options;
+  try {
+    options = parseArgs();
+  } catch (error) {
+    console.error(error.message);
+    process.exit(2);
+  }
+  capture(options).catch(error => {
+    console.error(error);
+    process.exit(1);
+  });
 }
 
-capture().catch(e => { console.error(e); process.exit(1); });
+module.exports = {
+  DEFAULT_BASE_URL,
+  SCREENSHOT_FILES,
+  parseArgs,
+  capture,
+};

package/docs/command-center.md

@@ -36,7 +36,7 @@ Canonical envelope (`_buildCcErrorEnvelope` in `dashboard.js`):
 ```json
 { "type": "error",
   "message": "Human-readable cause + remediation hint",
-  "code": "model-unavailable | auth-failure | context-limit | budget-exceeded | crash | cc-turn-timeout | worker-spawn-failed | acp-handshake-failed | worker-died | invalid-image",
+  "code": "model-unavailable | auth-failure | context-limit | budget-exceeded | crash | cc-turn-timeout | worker-spawn-failed | acp-handshake-failed | worker-died | invalid-request | invalid-image",
   "retryable": false,
   "availableModels": ["gpt-4o", "gpt-5.4", "..."],
   "runtime": "copilot"
@@ -45,6 +45,10 @@ Canonical envelope (`_buildCcErrorEnvelope` in `dashboard.js`):
 
 `code` is clamped to the allowlist (`CC_ERROR_CODES` constant); unknown codes collapse to `crash`. `retryable: true` is informational — there is **no auto-retry**; the dashboard always offers a manual Retry button instead. Auto-retrying these errors is a footgun because most are operator-fix categories (auth, budget, missing model) where re-spawning makes no progress.
 
+**Request validation.** Command Center and Doc-Chat validate the complete JSON payload before rate-limit accounting, in-flight reservations, worker acquisition, LLM calls, session mutation, document reads/edits, or SSE headers. Rejections use the same typed envelope with `code: "invalid-request"`, `retryable: false`, and shared `field` / `path` / `details` constraints. Transcripts are capped at 20 typed `{role,text}` entries; tab/session IDs, booleans, messages, documents, selections, content hashes, and image metadata are bounded and type-checked. Streaming reconnects accept only `tabId`, optional `sessionId`, and `reconnect: true`.
+
+Doc-Chat editable paths must be relative, remain inside the Minions root after real-path resolution, avoid symlinks/junctions and protected live runtime files, and belong to a document context such as `plans/`, `prd/`, `projects/`, `knowledge/`, `notes/`, `meetings/`, or `skills/`. Validation returns the resolved path once and handlers reuse it after acquiring the document reservation.
+
 **Watchdog (`engine.ccTurnTimeoutMs`, default 5 min, clamped 10s–1h).** Per-turn **no-progress** cap. Each turn arms a `setTimeout` that fires `event: error` with `code: 'cc-turn-timeout'`, aborts the in-flight LLM call, and ends the stream when no liveness signal arrives within the window. The timer **resets on every progress event** — token chunk, tool-call notification, tool-update — so a turn that's actively streaming or running long tools (e.g. `Bash` running `npm test`, `WebFetch`/`WebSearch` against slow targets, agent sub-dispatches) survives indefinitely up to the outer 1h `CC_CALL_TIMEOUT_MS` hard ceiling. Wired via `liveState._bumpTimer` (CC stream path) and the factory shape of `_raceCcDocChatTimeout` (doc-chat stream path); the non-streaming doc-chat path has no progress hooks and retains wall-clock semantics. Surfaced in Settings → CC overrides.
 
 **No auto-retry policy.** The backend never re-spawns the LLM after an error envelope. The client never silently resends the user's turn. Retry is a single-click manual action — guards against silent budget burn on `budget-exceeded`, infinite loops on `auth-failure`, and accidental re-charges on `context-limit`. The 429 + reconnect paths (rate-limited fetch retry, SSE reconnect-after-disconnect) remain — those are transport-level, not error-envelope-level.

package/docs/completion-reports.md

@@ -21,6 +21,15 @@ Path shape (resolved by `shared.dispatchCompletionReportPath()` in `engine/share
 
 The agent must write the JSON to that exact path before exiting. Any character outside `[a-zA-Z0-9._-]` in the dispatch id is replaced with `-` by the engine when computing the path.
 
+For a mutating dispatch, process exit code `0` is only a transport signal. If
+the JSON file is absent, malformed, or has a status outside the documented
+success/nonterminal enums, the engine keeps the worker in
+`Process exited; validating completion`, then records an error with
+`failure_class: 'completion-report-missing'`. It still runs the PR-attachment
+contract, so a simultaneous missing PR remains visible rather than being
+replaced by the report failure. Nonzero exits retain their original runtime
+failure classification; a missing report does not mask that error.
+
 ## Trust boundary
 
 Each spawn also receives a per-dispatch cryptographic value named
@@ -92,12 +101,112 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `noopReason` | string | Human-readable rationale shown when `noop: true`. Falls back to `summary` if absent. |
 | `reviewFindingResolution` | object | Required when a review-feedback fix leaves the PR branch unchanged. Shape: `{findingId, disposition, currentCodeEvidence}`; see [Review-fix no-op evidence](#review-fix-no-op-evidence). |
 | `files_changed` | string \| array | Comma-separated list (or array) of key files changed. |
+| `not_changed` | string | Scope boundary: adjacent work deliberately left untouched and why. |
 | `affected_files` | string[] | Optional array of relative file paths this dispatch touched or plans to touch. Used by the dispatcher to emit a conflict warning (`WI <new-id> may conflict with in-progress <existing-id> on files: [list]`) when a new WI's `affected_files` overlaps with an in-progress WI's `affected_files`. Logging-only — dispatch is never blocked. Stored back onto the work item after completion so re-dispatches can also participate in overlap detection. |
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
-| `pending` | string | Any remaining work, or `none`. |
+| `securityFlags` | object | Set `{ "injectionAttempt": true }` after detecting an instruction-redirection attempt inside an `<UNTRUSTED-INPUT>` fence. The engine converts it to non-retryable `injection-flagged` and writes an alert. |
+| `reviewLearnings` | array | Optional verified review lessons. At most eight entries; each entry is source-bound, redacted, type-checked, and byte-capped. See [Review-learning completion payloads](#review-learning-completion-payloads). |
+| `reviewLearningApplications` | array | Optional outcomes for recalled review lessons. At most 32 entries; each contains a lesson ID, outcome label, and bounded evidence. |
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |
 | `invalidates` | string[] | Optional. List of work-item IDs (e.g. `["W-abc123"]`) whose goals are superseded by this completion. The engine cancels each listed WI that is currently in `pending` or `queued` status, stamping `cancellationReason: "invalidated-by:<source-wi-id>"`. WIs in any other status (dispatched, done, failed, cancelled) are skipped with a warning — they are NOT cancelled. Missing IDs also log a warning and are skipped. Only processed on successful (`effectiveSuccess`) completions. See [Goal invalidation](#goal-invalidation). |
-| `meta.descriptionAudit` | object | Optional, `fix` / `implement` dispatches that push commits. Records the PR description audit + screenshot-refresh outcome — see [PR description audit](#pr-description-audit). |
+| `meta.descriptionAudit` | object | Optional, `fix` / `implement` dispatches that push commits. Records the PR description audit + screenshot embed/refresh outcome — see [PR description audit](#pr-description-audit). |
+
+## Review-learning completion payloads
+
+Review and fix agents may report verified, reusable lessons and how previously
+recalled lessons affected the task. These fields are optional. Emit them only
+when the dispatch supplies a trusted finding or comment source identity; never
+derive an identity from reviewer prose.
+
+```json
+{
+  "reviewLearnings": [
+    {
+      "rule": "Validate optional telemetry independently from the code-fix result.",
+      "disposition": "accepted-fixed",
+      "source": {
+        "pr": "github:opg-microsoft/minions#951",
+        "sourceKey": "github:review-finding:review-0123456789abcdef"
+      },
+      "project": "minions-opg",
+      "authorAgent": "dallas",
+      "applicability": "project-team",
+      "files": ["engine/lifecycle.js"],
+      "symbols": ["normalizeReviewLearningCompletionPayload"],
+      "tags": ["completion-contract"],
+      "evidence": [
+        "engine/lifecycle.js:5742",
+        "test/unit/structured-completion.test.js:158"
+      ],
+      "confidence": 0.92,
+      "repeatedOf": "M-review-lesson-1"
+    }
+  ],
+  "reviewLearningApplications": [
+    {
+      "id": "M-review-lesson-1",
+      "outcome": "applied",
+      "evidence": "engine/lifecycle.js:5742 validates each optional field independently."
+    }
+  ]
+}
+```
+
+Each `reviewLearnings` entry has this contract:
+
+- `rule` is one generalized procedural rule, not a review quote.
+- `disposition` is one of `accepted-fixed`, `satisfied-elsewhere`, `invalid`,
+  `stale`, `deferred`, or `out-of-scope-follow-up`. The legacy
+  `already-resolved` label is accepted on read and canonicalized to
+  `satisfied-elsewhere`.
+- `source.pr` must equal the canonical dispatch PR. `source.sourceKey` must
+  equal one of the host-namespaced finding or comment identities trusted by
+  that dispatch, such as `github:review-finding:<id>`,
+  `github:review-comment:<id>`, or `ado:thread:<thread>:comment:<comment>`.
+- `project` and `authorAgent` must match the dispatch project and tracked PR
+  author. `applicability` is `author` or `project-team`.
+- `files`, `symbols`, and `tags` are arrays of repository-relative paths,
+  symbol identifiers, and normalized tags. `evidence` is a non-empty array of
+  current file/line, test, or commit references. `confidence` is a finite
+  number from 0 through 1. `repeatedOf`, when present, is a bounded `M-...`
+  lesson ID.
+
+Each `reviewLearningApplications` entry contains a bounded `M-...` `id`, an
+`outcome` of `applied`, `considered-not-applicable`, or `contradicted`, and a
+required evidence string. Report the outcome label and observable evidence
+only. Never include reasoning transcripts or chain-of-thought.
+
+The engine accepts at most eight learnings (64 KiB total) and at most 32
+applications (16 KiB total). Per learning, `rule` is capped at 1,024 bytes;
+the three facet arrays have at most 20 entries; evidence has at most 20
+entries of 400 bytes; tags are 64 bytes; and memory IDs are 160 bytes.
+Application evidence is capped at 400 bytes. Secret-shaped text is redacted
+before the normalized payload is retained.
+
+Malformed `reviewLearnings` and `reviewLearningApplications` fields are
+dropped independently. The engine logs a redacted warning and stamps
+`_reviewLearningDiagnostics` on the work item for operator visibility, while
+an otherwise successful code fix remains successful. A nonce mismatch
+discards the entire completion report. `securityFlags.injectionAttempt: true`
+forces the existing non-retryable failure path and suppresses both review
+learning fields.
+
+These fields do not replace `reviewFindingResolution`. An unchanged
+review-feedback fix must still set `noop: true` and prove the exact trusted
+finding through the stricter no-op contract below.
+
+When `review-learning-capture` is enabled, the engine processes normalized
+entries only after the completion is otherwise successful and all PR/work-item
+contracts pass. `accepted-fixed` requires verified remote-head advancement or
+an independent approval of the exact current review head.
+`satisfied-elsewhere`, `invalid`, and `stale` require an exact current
+`file:line`, commit, or test reference. Positive entries sharing a source are
+stored as one system-trusted, project-scoped procedural record; invalid/stale
+candidates close, while deferred/follow-up candidates remain non-recallable.
+Repeated-finding telemetry requires an exact symbol or file-plus-rule/tag
+match to a prior lesson and records that lesson ID and match reason. Capture
+warnings are bounded and diagnostic-only: they never reverse a successful fix
+or re-review outcome.
 
 ## PR description audit
 
@@ -105,10 +214,12 @@ W-mq5l3f2u000i9045. The `fix` and `implement` playbooks inline a `## PR descript
 
 The audit is best-effort:
 
-- Screenshot recapture requires a runnable dev server (detected via `package.json` scripts named `dev`, `start`, or `serve`) and Playwright MCP. When either is missing or fails, the agent skips the recapture without failing the work item.
-- GitHub does not expose a documented REST endpoint for PR-comment image uploads; the agent skips the recapture on GitHub with `result: "screenshots-refreshed-skipped (gh-attachment-unavailable)"` instead of failing.
+- Screenshot capture requires a runnable dev server (detected via `package.json` scripts named `dev`, `start`, or `serve`) and Playwright MCP. When either is missing or fails, the agent skips the capture without failing the work item.
+- **Proactive embedding (W-mrz1yc79).** For a PR that contains a meaningful **visual/UI change** (dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS), the agent proactively introduces screenshots into the description — it no longer waits for the OPG `Visual evidence capture` CI bot (that bot stays as-is; the in-description embeds are additive). Backend-only, engine-logic, text/prose-only, analysis, and docs changes get no screenshots.
+- **GitHub upload path.** GitHub has no documented REST endpoint for PR-comment image uploads, so the agent publishes the PNGs as assets on a dedicated per-PR prerelease (tag `pr-<num>-visual`, `gh release create/upload … --prerelease`), resolves each asset's `browser_download_url`, and embeds it as `![view (after)](url)`. This works on private repos, uses a per-command `GH_TOKEN` for the repo owner's account (never `gh auth switch`), and never commits PNGs to the source branch. If the upload fails, the agent skips and records the reason instead of failing.
+- **ADO upload path.** `PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then reference the returned URL — now for newly-introduced screenshots too, not just refreshes.
 - Raw PNGs are saved under `agents/<id>/screenshots/` only. **Screenshots NEVER land in the repo** — adding any code path that `git add`s a PNG is a release-blocker bug.
-- The audit never introduces screenshots to a PR that didn't already have any (refresh only), never modifies the PR title, never toggles draft state, and never posts a separate PR comment narrating the description change.
+- The audit never rewrites description prose beyond targeted stale edits, never modifies the PR title, never toggles draft state, and never posts a separate PR comment narrating the description change.
 
 Record the outcome under `meta.descriptionAudit`. All fields are optional and backward-compatible — older agents that never set them stay valid.
 
@@ -130,9 +241,9 @@ Record the outcome under `meta.descriptionAudit`. All fields are optional and ba
 | Field | Type | Notes |
 |---|---|---|
 | `meta.descriptionAudit.ran` | boolean | `true` if the agent executed the audit (whether or not it edited the description). `false` when the audit was suppressed (no commits pushed, no-op completion, `meta.skipDescriptionAudit` set, or the playbook skipped the audit for any reason). Omit `meta.descriptionAudit` entirely when the audit was not even considered. |
-| `meta.descriptionAudit.result` | string | One of: `"no-changes-needed"`, `"description-patched"`, `"screenshots-refreshed"`, `"description-patched+screenshots-refreshed"`, or `"skipped:<reason>"` (e.g. `"skipped:meta-flag"`, `"skipped:no-commits"`, `"skipped:noop"`). The `"screenshots-refreshed-skipped (gh-attachment-unavailable)"` shape is also valid when GitHub's attachment limitation forces a partial-skip. |
-| `meta.descriptionAudit.oldScreenshots` | string[] | URLs of image refs the agent replaced. Omit or `[]` when no screenshots changed. |
-| `meta.descriptionAudit.newScreenshots` | string[] | URLs of newly uploaded image attachments. Omit or `[]` when no screenshots changed. |
+| `meta.descriptionAudit.result` | string | One of: `"no-changes-needed"`, `"description-patched"`, `"screenshots-introduced"`, `"screenshots-refreshed"`, `"description-patched+screenshots-introduced"`, `"description-patched+screenshots-refreshed"`, or `"skipped:<reason>"` (e.g. `"skipped:meta-flag"`, `"skipped:no-commits"`, `"skipped:noop"`). A partial-skip shape like `"screenshots-skipped (dev-server-unavailable)"` is also valid when the dev server, route, Playwright, or upload path is unavailable. |
+| `meta.descriptionAudit.oldScreenshots` | string[] | URLs of image refs the agent replaced when refreshing. Omit or `[]` when no screenshots changed. |
+| `meta.descriptionAudit.newScreenshots` | string[] | URLs of newly uploaded/embedded image assets (release-asset CDN URLs on GitHub, attachment URLs on ADO) — for both newly-introduced and refreshed screenshots. Omit or `[]` when no screenshots changed. |
 | `meta.descriptionAudit.patchedSections` | string[] | Human-readable identifiers of the description sections that changed (e.g. `"feature-bullets"`, `"config-table"`, `"file-list"`, `"line-counts"`, `"ascii-diagram"`, `"screenshots"`). Omit or `[]` when no sections changed. |
 
 Dispatchers can suppress the audit entirely by setting `meta.skipDescriptionAudit: true` on the work item — the playbook then renders an explicit "audit suppressed" notice instead of the audit steps. Use this for skill-meta updates, doc-only fixes whose PR description text won't be affected by the diff, and follow-up dispatches that explicitly own the description themselves.
@@ -174,13 +285,16 @@ Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated s
 | `build-failure` | Compilation, lint, or test failure introduced by the agent | Retry same agent |
 | `timeout` | Hard runtime timeout or stale-orphan timeout | Retry with fresh session |
 | `empty-output` | Agent produced no meaningful output | Flag for human review |
+| `runtime-truncated-exit` | The runtime process exited `0` in the MIDDLE of a turn: its output holds a tool call that was started and never completed (observed: Copilot exiting right after starting a long `npm test`), and no completion report was written. Detected through the optional adapter hook `hasUnfinishedToolCall`. Distinct from `completion-report-missing`, which means the turn ended normally but the agent skipped the report. | Retry — a fresh attempt normally runs to completion |
+| `runtime-session-stale` | A `--resume`d runtime died because its persisted session is unusable: the backing conversation is gone, or its persisted working directory no longer exists (the engine removed/recycled that worktree). Previously surfaced as an opaque `empty-output`. | Retry — the engine clears the cached session first |
 | `spawn-error` | Process failed to start or crashed immediately | Retry with fresh session |
 | `network-error` | API rate limit, DNS, connectivity | Default retry logic |
 | `out-of-context` | Context window exhausted | Flag for human review |
 | `max-turns` | Claude CLI `error_max_turns` — work in progress | Retry same agent |
 | `completion-nonce-mismatch` | Completion JSON missing or mismatched `nonce` (forged completion). See [Trust boundary](#trust-boundary). | Never retry (untrusted) |
+| `completion-report-missing` | A mutating process exited `0` without a valid required JSON completion report | Retry unless another hard lifecycle contract (such as missing PR) already made the work item terminal |
 | `worktree-preflight` | Pre-spawn worktree validation rejected the dispatch (nested-in-project, drive-root collapse, missing base). See [Pre-spawn preflight vs agent failure](#pre-spawn-preflight-vs-agent-failure). | Never retry |
-| `worktree-dirty` | Reused worktree had uncommitted edits the engine could not auto-heal (#2996) | Never retry this dispatch (fresh worktree next cycle) |
+| `worktree-dirty` | Reused worktree had uncommitted edits the engine could not auto-heal (#2996). When the failure came from the self-heal tail (`clean-failed` / `dirty-after-clean` / `recheck-failed`) the engine has already proved there were no unpushed commits, quarantines the tree, and marks the failure retryable. | Never retry this dispatch, EXCEPT the quarantined self-heal cases which retry into a fresh worktree |
 | `worktree-divergent` | Reused worktree's local branch was ahead of origin — unsafe to reset (#2996) | Never retry this dispatch (worktree quarantined) |
 | `worktree-quarantine-env-blocked` | Quarantine rename failed because the OS wouldn't release the worktree dir (Windows EBUSY/EPERM/EACCES) | Retry — re-queued without bumping the per-agent retry counter |
 | `dependency-merge-setup` | Dependency pre-merge plumbing (stash/status/reset) failed before a real file conflict was verified | Retry — fresh worktree can recover |
@@ -194,6 +308,7 @@ Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated s
 | `live-checkout-mid-operation` | Operator tree is mid-operation (in-progress merge/rebase/cherry-pick/bisect) or detached HEAD | Never retry — operator must finish/abort first |
 | `live-checkout-blob-fetch` | `git checkout` failed materializing the tree on a blobless/GVFS-partial clone — deterministic, not transient | Never retry — operator hydrates the branch with their own credentials |
 | `live-checkout-worktree-conflict` | Target branch is already checked out in a second worktree elsewhere — structural, doesn't clear on retry | Never retry — operator removes/reassigns the other worktree |
+| `live-checkout-stale-base` | Spawn-time defense found local `mainRef` ahead of `origin/<mainRef>`; forking would inherit committed contamination | Never retry — operator reconciles the local base first |
 | `live-checkout-wrong-base` | New-branch fork requested but operator HEAD is on an unrelated branch, not the project base | Never retry — operator checks out `mainRef` first (or enable `liveCheckoutAutoBaseRepair`) |
 | `invalid-workdir` | Dispatch carried a `meta.workdir` override that failed validation (absolute path, `..` segment, escape, etc.) | Never retry until the WI's `meta.workdir` is fixed |
 | `model-unavailable` | Requested model returned `overloaded_error` / 503 / service unavailable | Retry — engine swaps in the runtime-appropriate fallback model |
@@ -204,6 +319,7 @@ Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated s
 | `output-truncated` | Agent streamed more stdout than the engine's hard capture cap before the terminal `result` event arrived | Never retry — agent must reduce output volume or split the task |
 | `verify-missing-pr` | A verify WI exited `done` but no PR was attached | Retry — agent may have phantom-crashed before pushing |
 | `project_not_found` | A work item's `project` field names a project that isn't configured | Never retry until the WI's `project` field or config is fixed |
+| `pre-dispatch-eval-stuck` | Legacy persisted classification for unchanged descriptions rejected repeatedly; migration 026 converts these to pending `_preDispatchEval.exhausted` state | Never retry as an execution failure — edit the description |
 | `unknown` | Unclassified failure | Default retry logic |
 
 Use `"N/A"` when `status` is `success` or `partial` without a failure.
@@ -256,13 +372,13 @@ If the live PR branch did not advance, the completion must set `noop: true` and
 {
   "reviewFindingResolution": {
     "findingId": "review-0123456789abcdef",
-    "disposition": "already-resolved",
+    "disposition": "satisfied-elsewhere",
     "currentCodeEvidence": "engine/lifecycle.js:4600 already enforces the condition; test/unit/example.test.js covers it."
   }
 }
 ```
 
-The `findingId` is injected into the fix playbook from trusted `minionsReview` provenance. `disposition` is `already-resolved` or `invalid`, and `currentCodeEvidence` must cite a current `file:line` or commit. An identity-only no-op is retried and does not increment `_noOpFixes`.
+The `findingId` is injected into the fix playbook from trusted `minionsReview` provenance. `disposition` is `satisfied-elsewhere` or `invalid`; legacy `already-resolved` is accepted and canonicalized to `satisfied-elsewhere`. `currentCodeEvidence` must cite a current `file:line` or commit. An identity-only no-op is retried and does not increment `_noOpFixes`.
 
 ## PR-comment follow-ups
 

package/docs/constants.md

@@ -1,10 +1,11 @@
 # Constants — No Magic Strings
 
-All cross-cutting status / type / condition values are defined in [`engine/shared.js`](../engine/shared.js). Engine and dashboard code **never** compares against raw strings; tests enforce.
+Cross-cutting status / type / condition values are defined in [`engine/shared.js`](../engine/shared.js). Engine and dashboard code should use these constants instead of raw strings; source-inspection tests enforce the load-bearing comparisons.
 
 ```js
 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
+PLAN_TERMINAL_STATUSES = Set([...DONE_STATUSES, WI_STATUS.FAILED, WI_STATUS.CANCELLED])
 WORK_TYPE = { IMPLEMENT, IMPLEMENT_LARGE, FIX, REVIEW, VERIFY, PLAN, PLAN_TO_PRD,
               DECOMPOSE, MEETING, EXPLORE, ASK, TEST, DOCS, SETUP, BUILD_FIX_COMPLEX }
 PLAN_STATUS = { ACTIVE, AWAITING_APPROVAL, APPROVED, PAUSED, REJECTED, COMPLETED, REVISION_REQUESTED }
@@ -19,14 +20,25 @@ WATCH_CONDITION = { MERGED, BUILD_FAIL, BUILD_PASS, COMPLETED, FAILED, STATUS_CH
   STAGE_ADVANCED, STUCK_IN_STAGE }
 WATCH_ABSOLUTE_CONDITIONS = Set([MERGED, BUILD_FAIL, BUILD_PASS, COMPLETED, FAILED, CONCLUDED, APPROVED,
   REJECTED, READY_FOR_MERGE, RETRY_LIMIT_REACHED, ALL_ITEMS_DONE, ITEM_FAILED_N_TIMES])  // fire-once
+WATCH_TARGET_TYPE = { PR, WORK_ITEM, MEETING, PLAN, SCHEDULE, PIPELINE, DISPATCH, AGENT }  // built-ins; watches.d/*.js may register more
+WATCH_ACTION_TYPE = { NOTIFY, DISPATCH_WORK_ITEM, RUN_SKILL, WEBHOOK, MINIONS_API,
+  CANCEL_WORK_ITEM, TRIGGER_PIPELINE, ARCHIVE_PLAN, RESUME_PLAN, CC_TRIAGE }
+BUILD_STATUS = { PASSING, FAILING, RUNNING, NONE }
+REVIEW_STATUS = { APPROVED, CHANGES_REQUESTED, WAITING, PENDING }  // APPROVED is permanent terminal — never downgrade
+AGENT_STATUS = { SPAWNING, WORKTREE_SETUP, READY, RUNNING, FINISHED, FAILED, TRUST_BLOCKED, TIMED_OUT }
+MEETING_STATUS = { INVESTIGATING, DEBATING, CONCLUDING, COMPLETED, ARCHIVED }
+PIPELINE_STATUS = { PENDING, RUNNING, COMPLETED, FAILED, PAUSED, WAITING_HUMAN, STOPPED }
+STAGE_TYPE = { TASK, MEETING, PLAN, API, MERGE_PRS, SCHEDULE, WAIT, PARALLEL, CONDITION }  // pipelines/*.json stage kinds
+CHECKOUT_MODES = { WORKTREE, LIVE }  // project.checkoutMode; see docs/live-checkout-mode.md
+FAILURE_CLASS = { ... }  // dispatch failure taxonomy — full enum in docs/completion-reports.md
 ```
 
 ## Engine defaults
 
-Retry/timeout limits, sweep cadences, fleet ceilings, and managed-spawn caps live in `ENGINE_DEFAULTS` (also in `engine/shared.js`). Read defaults from there rather than re-declaring; per-deployment overrides go in `config.engine.*` and resolve through the per-knob helpers (`resolveAgentMaxBudget`, etc.).
+Retry/timeout limits, sweep cadences, fleet ceilings, and managed-spawn caps live in `ENGINE_DEFAULTS` (also in `engine/shared.js`). Read defaults from there rather than re-declaring. Some keys resolve a `config.engine.*` override through a helper (`resolveAgentMaxBudget`, etc.); others are source-only, so verify the call site before documenting a Settings/config knob.
 
 ## Invariants
 
 - **Write only `WI_STATUS.DONE`.** Legacy aliases (`in-pr`, `implemented`, `complete`) are accepted on read for backward compat but never written. `updateWorkItemStatus()` validates writes against `WI_STATUS`.
-- **`mutateJsonFileLocked` for RMW.** All shared-JSON status writes go through the locked mutator wrappers (`mutateDispatch`, `mutateWorkItems`, `mutatePullRequests`) — see [`CLAUDE.md`](../CLAUDE.md) → **Concurrency**.
+- **SQL store mutators for runtime state.** `mutateWorkItems`, `mutatePullRequests`, and `mutateDispatch` delegate to SQL-backed store modules (not JSON-locked wrappers). `mutateJsonFileLocked()` is reserved for intentionally file-backed RMW — configuration, definitions, and coordination sidecars. Route all runtime-state RMW through the appropriate store mutator — see [`CLAUDE.md`](../CLAUDE.md) → **Concurrency**.
 - **No string comparisons.** `pr.status === 'active'` ⇒ `pr.status === PR_STATUS.ACTIVE`. Source-inspection tests grep for the constant form.

package/docs/constellation-style-telemetry.md

@@ -10,12 +10,12 @@ A **1:1 port is the wrong goal.** Constellation's telemetry is built for a *host
 multi-tenant, server-side fleet*: PostgreSQL storage, WebSocket ingestion,
 per-constellation/per-device tenancy, and a bearer-authed global-admin dashboard.
 Minions is the structural opposite — *single-machine, local-first, zero-deps-beyond-Node,
-JSON-file state, loopback dashboard*.
+embedded-SQLite state (`engine/state.db` via built-in `node:sqlite`), loopback dashboard*.
 
 But the **valuable, portable subset is very feasible**, and Minions already has ~60% of it.
 The realistic target is a **local-first usage/analytics layer**: a typed append-only event
 log + a retention/rollup discipline + a dedicated dashboard "Usage" page, optionally a
-`/metrics` Prometheus endpoint. **No database, no new runtime dependencies, no new network
+`/metrics` Prometheus endpoint. **No server database, no new runtime dependencies, no new network
 egress** (preserves the "nothing leaves the machine" property — Minions' own code has no
 external telemetry today).