@yemi33/minions 0.1.2083 → 0.1.2085

package/dashboard/js/settings.js

@@ -393,8 +393,8 @@ async function openSettings() {
     '<h4>Inbox &amp; Status Retention</h4>' +
     '<div class="settings-grid-2">' +
       settingsField('Consolidation Threshold', 'set-inboxConsolidateThreshold', e.inboxConsolidateThreshold || 5, 'notes', 'Inbox notes before auto-consolidation') +
-      settingsField('Status WorkItems Retention', 'set-statusWorkItemsRetentionDays', e.statusWorkItemsRetentionDays ?? 7, 'days', 'Trim done/failed/cancelled work items older than N days from the /api/status workItems slice (active items are always shipped). Cuts SPA payload from ~3MB to <500KB. Set to 0 to disable trimming (full list shipped, restoring legacy behavior).') +
-      settingsField('Status Meetings Retention', 'set-statusMeetingsRetentionDays', e.statusMeetingsRetentionDays ?? 7, 'days', 'Trim completed/archived meetings older than N days from the /api/status meetings slice (active meetings are always shipped). Cuts SPA payload from ~4.3MB to <500KB. Detail modal still fetches full transcripts via /api/meetings/:id. Set to 0 to disable trimming (full list shipped, restoring legacy behavior).') +
+      settingsField('Status WorkItems Retention', 'set-statusWorkItemsRetentionDays', e.statusWorkItemsRetentionDays ?? 0, 'days', 'Optional age-based trim for done/failed/cancelled work items in the /api/status workItems slice (active items are always shipped). Default 0 = no trim — the slim projection that strips description/AC/references already cuts the payload by ~80%. Set to a positive integer to also drop terminal items older than N days.') +
+      settingsField('Status Meetings Retention', 'set-statusMeetingsRetentionDays', e.statusMeetingsRetentionDays ?? 0, 'days', 'Optional age-based trim for completed/archived meetings in the /api/status meetings slice (active meetings are always shipped). Default 0 = no trim — the slim projection that collapses findings/debate/transcript bodies to {agentId: true} sentinels already cuts the payload by ~80%. Set to a positive integer to also drop terminal meetings older than N days. Detail modal still fetches full bodies via /api/meetings/:id.') +
       settingsField('Version Check Interval', 'set-versionCheckInterval', e.versionCheckInterval || 3600000, 'ms', 'How often to check npm for updates (default: 1 hour)') +
     '</div>' +
     '<h4>Operator &amp; Comments</h4>' +

package/dashboard.js

@@ -73,6 +73,11 @@ const TITLE_SUFFIX = IS_DEV_MODE ? ' [DEV]' : '';
 
 const PORT = parseInt(process.env.PORT || process.argv[2]) || 7331;
 let CONFIG = queries.getConfig();
+// Mirror cli.js: clear persisted statusWorkItemsRetentionDays=7 + the matching
+// meetings field (prior default 7) so the new default (0, no trim) reaches the
+// /api/status slimmers without needing an engine bounce first.
+try { shared.applyStatusWorkItemsRetentionMigration(CONFIG); } catch { /* best-effort */ }
+try { shared.applyStatusMeetingsRetentionMigration(CONFIG); } catch { /* best-effort */ }
 let PROJECTS = _getProjects(CONFIG);
 const CONFIG_PATH = path.join(MINIONS_DIR, 'config.json');
 const PINNED_PATH = path.join(MINIONS_DIR, 'pinned.md');
@@ -95,6 +100,8 @@ function ensureConfiguredProjectStateFiles() {
 
 function reloadConfig() {
   CONFIG = queries.getConfig();
+  try { shared.applyStatusWorkItemsRetentionMigration(CONFIG); } catch { /* best-effort */ }
+  try { shared.applyStatusMeetingsRetentionMigration(CONFIG); } catch { /* best-effort */ }
   PROJECTS = _getProjects(CONFIG);
   ensureConfiguredProjectStateFiles();
 }
@@ -1832,19 +1839,19 @@ function _safeStatusSlice(name, fn, fallback) {
 }
 
 // ── /api/status workItems slimming (W-mphejzmj000718bf) ─────────────────────
-// Strip down the workItems slice shipped on /api/status to (a) drop terminal
-// (done/failed/cancelled) items older than engine.statusWorkItemsRetentionDays
-// and (b) project each surviving item onto a narrow shape that omits the
-// large free-text fields (description, full acceptanceCriteria, full
-// references). The dashboard never renders description/AC/references-detail
-// off the cached slice — `wiRow` only needs counts + status/badge fields,
-// and `openWorkItemDetail` fetches the full record on demand via
-// GET /api/work-items/<id>. Live measurement at task time: 796 items / ~3MB
-// → ~50–100 items / <500KB typical. Active items (pending/dispatched/queued)
-// are ALWAYS kept regardless of age.
+// Project each work item onto a narrow shape that omits the large free-text
+// fields (description, full acceptanceCriteria, full references) before
+// shipping on /api/status. The dashboard never renders description/AC/
+// references-detail off the cached slice — `wiRow` only needs counts +
+// status/badge fields, and `openWorkItemDetail` fetches the full record on
+// demand via GET /api/work-items/<id>. This slim projection is the bulk of
+// the payload savings (~3MB → <500KB typical) and runs unconditionally.
 //
-// Set engine.statusWorkItemsRetentionDays = 0 to disable trimming entirely
-// (returns the full list unchanged, restoring legacy behavior).
+// engine.statusWorkItemsRetentionDays is an optional second-tier filter that
+// drops terminal (done/failed/cancelled) items older than N days. Default 0
+// = no trim (legacy behavior, full list shipped). Set to a positive integer
+// to opt into the date-based trim. Active items (pending/dispatched/queued)
+// are ALWAYS kept regardless of age.
 const _ACTIVE_WI_STATUSES_FOR_STATUS = new Set(['pending', 'dispatched', 'queued', 'paused', 'decomposed']);
 const _TERMINAL_WI_STATUSES_FOR_STATUS = new Set(['done', 'failed', 'cancelled']);
 function _resolveStatusWorkItemsRetentionDays() {
@@ -1931,9 +1938,9 @@ function _slimWorkItemsForStatus(items) {
 }
 
 // ── /api/status meetings slimming (W-mphlrxx6000a8760) ──────────────────────
-// Mirrors the workItems trim above (PR #2816). Meetings are the second
-// largest /api/status slice after workItems — live measurement: 22 meetings
-// / 4.3MB (60% of the 7.2MB payload). The list renderer in
+// Mirrors the workItems slim above (PR #2816). Meetings were the second
+// largest /api/status slice — live measurement: 22 meetings / 4.3MB
+// (60% of the 7.2MB payload) before slimming. The list renderer in
 // dashboard/js/render-meetings.js:renderMeetings only needs:
 //   - id, title, status, round, participants, agenda(short), createdAt,
 //     completedAt
@@ -1941,13 +1948,13 @@ function _slimWorkItemsForStatus(items) {
 //     ✓/⏳/○ icon — `m.findings?.[p]` truthy check, line 48-50)
 // The detail modal calls `/api/meetings/:id` which serves the full record
 // (findings.content + debate.content + conclusion + transcript bodies), so
-// dropping those from the slice is safe.
+// dropping those bodies from the slice is safe. The slim projection alone
+// delivers the bulk of the payload savings and always runs.
 //
-// Active meetings (investigating/debating/concluding) are ALWAYS kept
-// regardless of age. Terminal meetings (completed/archived) only survive
-// if their completedAt/roundStartedAt/createdAt is within the window.
-// Set engine.statusMeetingsRetentionDays = 0 to disable trimming entirely
-// (returns the full list — but still slim-shaped — restoring legacy size).
+// engine.statusMeetingsRetentionDays is an optional second-tier filter that
+// drops terminal (completed/archived) meetings older than N days. Default 0
+// = no trim (legacy behavior, full list shipped — but still slim-shaped).
+// Active meetings (investigating/debating/concluding) are ALWAYS kept.
 const _ACTIVE_MEETING_STATUSES_FOR_STATUS = new Set(['investigating', 'debating', 'concluding']);
 const _TERMINAL_MEETING_STATUSES_FOR_STATUS = new Set(['completed', 'archived']);
 function _resolveStatusMeetingsRetentionDays() {

package/docs/README.md

@@ -15,10 +15,13 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
 - [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.
+- [constants.md](constants.md) — Cross-cutting status / type / condition constants (`WI_STATUS`, `WORK_TYPE`, `PR_STATUS`, `WATCH_CONDITION`, …) and the no-magic-strings invariant.
 - [constellation-bridge.md](constellation-bridge.md) — Read-only cross-repo bridge: `engine.constellationBridge.enabled` flag, marker-file contract, and the `minions bridge` subcommand for local debugging.
+- [cooldown-merge-semantics.md](cooldown-merge-semantics.md) — Scoping deliverable defining merge semantics for `saveCooldowns` (longer-of TTL merge, key-level upserts, gitignored on-disk format).
 - [copilot-cli-schema.md](copilot-cli-schema.md) — Behavior and schema reference for the GitHub Copilot CLI adapter (capability flags, stdin vs `-p`, model discovery, effort levels).
-- [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.
+- [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–7).
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
+- [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
 - [managed-spawn.md](managed-spawn.md) — Engine-owned long-running services (managed-spawn primitive): sidecar schema, healthcheck examples, lifecycle, dashboard API, and the WI 1 (build) → WI 2 (test) chained-validation pattern.
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [pr-comment-followup.md](pr-comment-followup.md) — PR-comment follow-up dispatch contract: fix/review agents may spin off a new WI via `POST /api/work-items` with `meta.pr_followup` instead of broadening the current PR or rebutting the comment.

package/docs/command-center.md

@@ -4,4 +4,33 @@ The Command Center (CC) is the dashboard's conversational chat panel. It opens f
 
 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', ...)`).
 
-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). This pointer file exists so the docs index has an entry for "Command Center"; the implementation details are deliberately not duplicated here because they drift.
+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).
+
+## Error surfacing contract (W-mpmwxni2000c25c7-d)
+
+Both CC and Doc-Chat emit a typed error envelope so the dashboard can render a red `.cc-error` bubble (role=alert) with a Retry button and stop the spinner immediately. Errors arrive in two shapes:
+
+1. **SSE mid-stream** (most common). `writeCcEvent` / `writeDocEvent` write the wire as `event: error\ndata: {…envelope…}\n\n` so consumers using `addEventListener('error', …)` see them as named events. The JSON payload still carries `type: 'error'` for clients that only read the `data:` line, so both parser strategies keep working.
+2. **Non-2xx POST response** (pre-stream — `readBody` guard, prototype-pollution rejection, etc.). The body is the same envelope as JSON; the dashboard's `if (!res.ok)` branch parses it and stashes it on the thrown Error as `_ccErrorEnvelope`, then renders the same red bubble.
+
+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",
+  "retryable": false,
+  "availableModels": ["gpt-4o", "gpt-5.4", "..."],
+  "runtime": "copilot"
+}
+```
+
+`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.
+
+**Watchdog (`engine.ccTurnTimeoutMs`, default 5 min, clamped 10s–1h).** 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 terminal event (`done`/`error`) arrives in time. Independent of `CC_CALL_TIMEOUT_MS` (the outer 1h hard ceiling); the watchdog is the *visible-to-user* no-progress cap. 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.
+
+## Per-turn surfacing pipeline
+
+CC handler generates `ccTurnId = 'cct-' + shared.uid()` per request; injected into sysprompt AND prompt body via `_ccTurnHeaderPart(turnId)` (load-bearing: on resumed sessions `engine/llm.js` skips re-sending the sysprompt, so without body injection CC keeps the stale turn ID). Handler reads via `_readCcTurnIdHeader(req)` and calls `_recordCcTurnCreation(turnId, ...)` on success. End-of-turn: `_buildSyntheticActionResultsForTurn` produces synthetic `{action, result}` pairs (`_serverExecuted: true`). Client renders as standalone `role='action'` messages outside the assistant bubble. TTL: 5 min. Endpoints wired: `/api/work-items`, `/api/notes`, `/api/plan`, `/api/knowledge`, `/api/watches`.

package/docs/constants.md

@@ -0,0 +1,32 @@
+# 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.
+
+```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
+WORK_TYPE = { IMPLEMENT, IMPLEMENT_LARGE, FIX, REVIEW, VERIFY, PLAN, PLAN_TO_PRD,
+              DECOMPOSE, MEETING, EXPLORE, ASK, TEST, DOCS, SETUP }
+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])
+DISPATCH_RESULT = { SUCCESS, ERROR, TIMEOUT }
+WATCH_STATUS = { ACTIVE, PAUSED, TRIGGERED, EXPIRED }
+WATCH_CONDITION = { MERGED, BUILD_FAIL, BUILD_PASS, COMPLETED, FAILED, STATUS_CHANGE, ANY, NEW_COMMENTS,
+  VOTE_CHANGE, CONCLUDED, APPROVED, REJECTED, STAGE_COMPLETE, RAN, ENABLED, DISABLED, ACTIVITY_CHANGE,
+  HEAD_COMMIT_CHANGE, MERGEABLE_FLIPPED, READY_FOR_MERGE, BEHIND_MASTER, DRAFT_FLIPPED,
+  STALLED, RETRY_LIMIT_REACHED, DEPENDENCY_MET, ALL_ITEMS_DONE, ITEM_FAILED_N_TIMES,
+  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
+```
+
+## 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.).
+
+## 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**.
+- **No string comparisons.** `pr.status === 'active'` ⇒ `pr.status === PR_STATUS.ACTIVE`. Source-inspection tests grep for the constant form.

package/docs/deprecated.json

@@ -1,4 +1,17 @@
 [
+  {
+    "id": "status-retention-stale-default-migration",
+    "description": "applyStatusWorkItemsRetentionMigration + applyStatusMeetingsRetentionMigration: one-time migrations that drop engine.statusWorkItemsRetentionDays=7 and engine.statusMeetingsRetentionDays=7 from loaded config so the new defaults (0, no trim) reach installs whose config.json was persisted while 7 was the baked-in default. The 7-day cutoffs were added alongside the slim projections (W-mphejzmj000718bf for workItems, W-mphlrxx6000a8760 for meetings) but surfaced as data loss to users (completed rows disappearing from /api/status after a week). The slim projections (which deliver the bulk of the payload savings) still run unconditionally; only the date filters were demoted to opt-in. shared.js mutates the in-memory config; engine/cli.js follows up with guarded shared.mutateJsonFileLocked calls on config.json so the fields are also removed on disk — affected installs are permanently corrected the first time the engine boots after this ships.",
+    "code": [
+      { "file": "engine/shared.js", "note": "applyStatusWorkItemsRetentionMigration / applyStatusMeetingsRetentionMigration definitions + _resetStaleRetentionMigrationFlag / _resetStaleMeetingsRetentionMigrationFlag test helpers — pure, in-memory" },
+      { "file": "engine/cli.js", "note": "Two boot blocks inside start() — each applies the in-memory pass THEN mutateJsonFileLocked on config.json to delete the field with skipWriteIfUnchanged so non-7 installs don't churn the file" },
+      { "file": "dashboard.js", "note": "Initial CONFIG load + reloadConfig() both apply the in-memory migrations so the dashboard picks up the new defaults even if it boots before the engine writes config.json" }
+    ],
+    "deprecated": "2026-05-29",
+    "targetRemovalDate": "2026-06-01",
+    "cleanup": "On or after 2026-06-01 (3 days), delete both migration functions + their reset helpers from engine/shared.js (including the shared.js export lines), the boot calls + mutateJsonFileLocked blocks in engine/cli.js, the call sites in dashboard.js, the tests in test/unit/status-workitems-retention.test.js and test/unit/status-meetings-retention.test.js gated on the function names, and this entry. Three days is enough because the on-disk rewrite happens on first engine boot — any install whose engine has rebooted at least once since this shipped has already had its config.json corrected and is no longer dependent on the in-memory shim.",
+    "notes": "Persistent custom values (any non-7 integer) are preserved untouched. The only at-risk users are those who explicitly want a 7-day window — they can re-set via the Settings page after removal. If a user never restarts the engine in the 3-day window, the shim still strips the persisted 7 on dashboard-only boot via the in-memory pass; the on-disk write is a hardening pass for the common case, not a strict requirement."
+  },
   {
     "id": "config-poll-key-migration",
     "location": "engine/queries.js:126-163",

package/docs/design-state-storage.md

@@ -1,6 +1,8 @@
 # Design: Replacing File-Based State with a Structured Database
 
-> Author: Rebecca (Architect) | Date: 2026-04-07 | Status: Proposal
+> Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Accepted — implementation in progress**
+
+> **Implementation status (as of 2026-05):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–7 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool — see `CHANGELOG.md`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
 
 ## Executive Summary
 

package/docs/keep-processes.md

@@ -0,0 +1,47 @@
+# `keep_processes` sidecar
+
+> Opt-in mechanism for agents that spawn detached children themselves and need to leave them running past their own exit. The companion to engine-owned [managed-spawn](managed-spawn.md).
+
+## When to use `keep_processes`
+
+| Need | Use this |
+|---|---|
+| Long-running dev server / emulator the engine should own across restarts | [managed-spawn](managed-spawn.md) |
+| Short-lived helper the *same* agent needs alive past exit (e.g. `gradle --daemon` for the next gradle invocation) | `meta.keep_processes` |
+| Executable outside the managed-spawn allowlist | `meta.keep_processes` |
+| Service with no healthcheck | `meta.keep_processes` |
+| One-shot script that exits on its own | Neither |
+
+Both can coexist on the same WI. There's no plan to deprecate `keep_processes`; a future cleanup PR can revisit if managed-spawn fully subsumes its use cases.
+
+## Sidecar contract
+
+Set `meta.keep_processes: true` on the WI; agent writes `agents/<id>/keep-pids.json` before exit:
+
+```jsonc
+{
+  "pids": [12345],                 // ≤5 entries
+  "purpose": "gradle daemon for follow-up test WI",
+  "cwd": "D:/repos/my-android-app", // MUST be a real git worktree
+  "ports": [8080],                  // advisory, engine doesn't bind
+  "expires_at": "2026-04-29T00:00:00Z", // TTL ≤1440 min; default 60
+  "written_by": "ripley",
+  "wi_id": "W-mpqtg16a0007f5bb"
+}
+```
+
+`buildKeepProcessesHint` bakes the Windows-correct detached-spawn pattern (`spawn(..., { detached: true, stdio: 'ignore' }).unref()` plus the `start /B` fallback on cmd-only shells) into the agent prompt automatically — agents should not hand-roll the detach call.
+
+## Lifecycle
+
+- **Validation:** sidecar shape + workdir checked in `onAgentClose`. Failure → non-retryable `failure_class: invalid-keep-processes-{workdir,schema}`.
+- **Sweep:** [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) reaps at boot and every 30 ticks. Dead PIDs are pruned; expired TTL → process killed via `shared.killGracefully` then `killImmediate`.
+- **No healthcheck:** unlike managed-spawn, `keep_processes` does not gate WI completion on first-healthy. If the child crashes immediately the agent still succeeds — by design (ad-hoc helper semantics).
+
+## Caps
+
+- **PIDs:** ≤5 per sidecar.
+- **TTL:** ≤1440 min (24h). Default 60.
+- **Cwd:** must exist and resolve to inside a git worktree (`requireGitWorkdir: true`). Monorepo subdirs walk up to `gitWorktreeMaxParentDepth` (default 6).
+
+See also: [`CLAUDE.md`](../CLAUDE.md) → **Agent Spawn**, [managed-spawn.md](managed-spawn.md).

package/engine/cli.js

@@ -471,6 +471,41 @@ const commands = {
     try { shared.applyLegacyCcModelMigration(config, { logger: e.log }); }
     catch (err) { e.log('warn', `legacy ccModel migration failed: ${err.message}`); }
 
+    // Drop persisted statusWorkItemsRetentionDays=7 (the prior baked-in default)
+    // so the new default of 0 (no trim) reaches installs that opened Settings
+    // before the flip. Explicit non-7 values are preserved. We mutate in-memory
+    // AND rewrite config.json so the fix is permanent — the shim in shared.js
+    // can then retire on schedule without users regressing.
+    try {
+      const applied = shared.applyStatusWorkItemsRetentionMigration(config, { logger: e.log });
+      if (applied) {
+        const configPath = path.join(shared.MINIONS_DIR, 'config.json');
+        shared.mutateJsonFileLocked(configPath, (onDisk) => {
+          if (onDisk && onDisk.engine && onDisk.engine.statusWorkItemsRetentionDays === 7) {
+            delete onDisk.engine.statusWorkItemsRetentionDays;
+          }
+          return onDisk;
+        }, { defaultValue: {}, skipWriteIfUnchanged: true });
+      }
+    }
+    catch (err) { e.log('warn', `statusWorkItemsRetentionDays migration failed: ${err.message}`); }
+
+    // Same treatment for statusMeetingsRetentionDays — the meetings slice had
+    // the same 7-day baked-in default and the same data-loss UX.
+    try {
+      const applied = shared.applyStatusMeetingsRetentionMigration(config, { logger: e.log });
+      if (applied) {
+        const configPath = path.join(shared.MINIONS_DIR, 'config.json');
+        shared.mutateJsonFileLocked(configPath, (onDisk) => {
+          if (onDisk && onDisk.engine && onDisk.engine.statusMeetingsRetentionDays === 7) {
+            delete onDisk.engine.statusMeetingsRetentionDays;
+          }
+          return onDisk;
+        }, { defaultValue: {}, skipWriteIfUnchanged: true });
+      }
+    }
+    catch (err) { e.log('warn', `statusMeetingsRetentionDays migration failed: ${err.message}`); }
+
     // Auto-heal projects missing workSources (cloned-repo / hand-rolled-config
     // footgun): without this block, discoverFromWorkItems / discoverFromPrs
     // bail silently and the engine looks healthy but never dispatches. The

package/engine/shared.js

@@ -2184,27 +2184,32 @@ const ENGINE_DEFAULTS = {
   // the override and falls back to auto-resolution.
   operatorLogin: null,
   // ── /api/status workItems retention (W-mphejzmj000718bf) ────────────────────
-  // Trim done/failed/cancelled work items older than this many days from the
-  // /api/status workItems slice to cut the SPA payload (live: 796 items / 3MB
-  // → ~50–100 items / <500KB typical). Active items (pending/dispatched/queued)
-  // are ALWAYS shipped regardless of age — only terminal items past the
-  // window are dropped. The detail modal fetches the full record on demand
-  // via GET /api/work-items/<id> when description/references/AC are needed.
-  // 0 disables the trim (full list shipped, restoring legacy behavior).
-  statusWorkItemsRetentionDays: 7,
+  // Optional age-based trim for done/failed/cancelled work items in the
+  // /api/status workItems slice. Default 0 = no trim (full list shipped). The
+  // bulk of the payload savings (~3MB → ~500KB) comes from _slimWorkItemForStatus
+  // dropping description / full acceptanceCriteria / references — that slim
+  // projection runs unconditionally. The date filter on top was a second-tier
+  // optimization that surfaced as data loss to users (completed items vanishing
+  // from /api/status after 7 days) so it now opts in via a positive integer.
+  // Active items (pending/dispatched/queued) are ALWAYS shipped regardless of
+  // age. The detail modal fetches the full record on demand via
+  // GET /api/work-items/<id> when description/references/AC are needed.
+  statusWorkItemsRetentionDays: 0,
 
   // ── /api/status meetings retention (W-mphlrxx6000a8760) ─────────────────────
-  // Same shape as statusWorkItemsRetentionDays — mirrors the trim+slim pass
-  // for the meetings slice (live: 22 meetings / 4.3MB → ~5 meetings / <500KB
-  // typical). Active meetings (investigating/debating/concluding) are ALWAYS
-  // shipped regardless of age — only terminal meetings (completed/archived)
-  // past the window are dropped. The detail modal fetches the full record
-  // (findings, debate, conclusion, transcript bodies) on demand via
-  // GET /api/meetings/<id> when opened. A top-level meetingsTotal field is
-  // synthesized so the sidebar activity dot still fires when ANY meeting
-  // (including those dropped from the slim slice) gains a new round.
-  // 0 disables the trim (full list shipped, restoring legacy behavior).
-  statusMeetingsRetentionDays: 7,
+  // Same shape as statusWorkItemsRetentionDays — optional age-based trim for
+  // completed/archived meetings in the /api/status meetings slice. Default 0
+  // = no trim (full list shipped). The slim projection (which collapses
+  // ~95KB+ per-round findings/debate/transcript bodies down to {agentId: true}
+  // sentinels) delivers the bulk of the payload savings and always runs.
+  // The date filter on top was demoted to opt-in for the same reason as the
+  // workItems trim: vanishing completed meetings read as data loss. Active
+  // meetings (investigating/debating/concluding) are ALWAYS shipped regardless
+  // of age. The detail modal fetches the full record (findings, debate,
+  // conclusion, transcript bodies) on demand via GET /api/meetings/<id>.
+  // A top-level meetingsTotal field is synthesized so the sidebar activity
+  // dot still fires when ANY meeting gains a new round.
+  statusMeetingsRetentionDays: 0,
 };
 
 // ─── Runtime Fleet Resolution (P-3b8e5f1d) ──────────────────────────────────
@@ -2401,6 +2406,64 @@ function _resetLegacyCcModelMigrationFlag() {
   _legacyCcModelMigrationLogged = false;
 }
 
+// ─── Stale statusWorkItemsRetentionDays Default Migration ────────────────────
+//
+// The retention default was 7 from W-mphejzmj000718bf until users reported the
+// trim hid completed work items from /api/status, which read as data loss.
+// We flipped the baked-in default to 0 (no trim). Installs that opened the
+// Settings page while the default was 7 have `engine.statusWorkItemsRetentionDays: 7`
+// persisted in their config.json — the resolver would return 7 and they'd
+// still see the trim. This shim drops a literal `7` at load time so the new
+// default of 0 applies. Operators who explicitly set a non-7 value (e.g. 14
+// or 30) are left untouched. No on-disk rewrite.
+
+let _staleRetentionMigrationLogged = false;
+
+function applyStatusWorkItemsRetentionMigration(config, { logger = log } = {}) {
+  if (!config || !config.engine || typeof config.engine !== 'object') return false;
+  const e = config.engine;
+  if (e.statusWorkItemsRetentionDays !== 7) return false;
+  delete e.statusWorkItemsRetentionDays;
+  if (!_staleRetentionMigrationLogged) {
+    _staleRetentionMigrationLogged = true;
+    try {
+      logger('warn', 'statusWorkItemsRetentionDays=7 was the previous default — clearing in-memory so the new default (0, no trim) applies. Re-save Settings to persist or set a positive value to opt back in.');
+    } catch { /* logger may not be wired during tests — best-effort */ }
+  }
+  return true;
+}
+
+/** Test helper: reset the dedup flag so repeated tests can re-trigger the log. */
+function _resetStaleRetentionMigrationFlag() {
+  _staleRetentionMigrationLogged = false;
+}
+
+// Same shape as applyStatusWorkItemsRetentionMigration above, for the meetings
+// slice. The prior baked-in default of 7 caused completed/archived meetings to
+// vanish from /api/status after a week; we flipped the default to 0 and strip
+// the literal 7 from persisted configs so the new behavior applies.
+
+let _staleMeetingsRetentionMigrationLogged = false;
+
+function applyStatusMeetingsRetentionMigration(config, { logger = log } = {}) {
+  if (!config || !config.engine || typeof config.engine !== 'object') return false;
+  const e = config.engine;
+  if (e.statusMeetingsRetentionDays !== 7) return false;
+  delete e.statusMeetingsRetentionDays;
+  if (!_staleMeetingsRetentionMigrationLogged) {
+    _staleMeetingsRetentionMigrationLogged = true;
+    try {
+      logger('warn', 'statusMeetingsRetentionDays=7 was the previous default — clearing in-memory so the new default (0, no trim) applies. Re-save Settings to persist or set a positive value to opt back in.');
+    } catch { /* logger may not be wired during tests — best-effort */ }
+  }
+  return true;
+}
+
+/** Test helper: reset the dedup flag so repeated tests can re-trigger the log. */
+function _resetStaleMeetingsRetentionMigrationFlag() {
+  _staleMeetingsRetentionMigrationLogged = false;
+}
+
 // ─── Runtime Config Preflight Warnings ──────────────────────────────────────
 //
 // Emit non-fatal warnings about runtime/CLI configuration drift. Consumed by
@@ -5454,6 +5517,8 @@ module.exports = {
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentModel, resolveCcModel,
   resolveAgentMaxBudget, resolveAgentBareMode,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
+  applyStatusWorkItemsRetentionMigration, _resetStaleRetentionMigrationFlag,
+  applyStatusMeetingsRetentionMigration, _resetStaleMeetingsRetentionMigrationFlag,
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2083",
+  "version": "0.1.2085",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"