@yemi33/minions 0.1.2369 → 0.1.2371

package/docs/harness-propagation.md

@@ -1,273 +1,43 @@
-# Harness Propagation
+# Native Repository Harness
 
-> Status: contract doc for the **seamless user/repo harness invocation** plan
-> (`plans/seamless-user-repo-harness-invocation.md`, PRD
-> `prd/minions-opg-2026-06-10-4.json`). This is the foundation item — it nails
-> down the *current* propagation surfaces and the worktree footgun so the
-> rest of the plan can extend them without reinventing the contract. Read this
-> before adding a new adapter method, a new asset kind, or a new opt-out flag.
+Minions delegates repository instructions, skills, commands, and MCP discovery
+to the selected CLI runtime. It does not classify repository assets, inject
+selected skill content into prompts, add external harness directories, suppress
+repository instruction files, or attest which harnesses an agent used.
 
-## What is a "harness"
+## Runtime contract
 
-In this doc, "harness" means any user-installed or repo-local asset that the
-runtime CLI auto-discovers when it starts:
+For each dispatch Minions:
 
-- **Skills** — `SKILL.md` files the CLI loads as reusable workflows.
-- **Slash commands** — `*.md` files the CLI exposes as `/command-name`.
-- **MCP servers** — JSON config entries that point at a stdio/HTTP server.
+1. Creates or selects the checkout.
+2. Sets the CLI working directory to the repository root or the configured
+   `meta.workdir`.
+3. Invokes the selected runtime adapter with the task prompt and explicit
+   orchestration/security flags.
 
-A harness is "propagated" when it reaches a dispatched agent without the user
-having to register it again in Minions. The single-line goal: *if it works
-when you type the same task into `claude` / `copilot` / `codex` in this repo
-on this machine, it works when Minions dispatches the same task here.*
+From that point, Claude, Copilot, or Codex performs its normal native discovery
+from the working directory and user configuration. Running the same CLI in the
+same checkout should expose the same repository harness.
 
-## The four propagation mechanisms
+Repository harness files must exist in the dispatched checkout. In worktree
+mode, uncommitted files from the operator's main checkout are intentionally not
+copied into the dispatch worktree. Commit shared repository harness files, use
+the runtime's user-level configuration for personal assets, or opt into live
+checkout mode when the operator tree itself must be used.
 
-Every asset reaches the agent through exactly one of these mechanisms today.
-No engine code branches on `runtime.name` for any of them — the runtime
-adapter answers the contract questions and the engine fans out.
+## Explicit exceptions
 
-### 1. Runtime native discovery (no engine code involved)
+- `engine.copilotDisableBuiltinMcps` prevents Copilot's bundled GitHub MCP from
+  bypassing Minions PR tracking. This is an orchestration safety policy, not a
+  repository-harness override.
+- `engine.claudePreApproveWorkspaceMcps` pre-approves the checkout's native
+  `.mcp.json` entries so a headless Claude process does not block on an invisible
+  trust prompt. It does not alter discovery or server definitions.
+- Workspace manifests may restrict tools and repositories as an explicit
+  security boundary.
 
-The CLI reads its own config and indexes its own asset dirs on every spawn.
-Minions does not copy, symlink, or aggregate user-level assets — it just
-makes sure the relevant dirs are *readable* from the agent's cwd (see
-mechanism #3 below). The actual loading is the CLI's job.
+## Diagnostics
 
-| Runtime | User skills | User commands | User MCP servers |
-|---------|-------------|---------------|------------------|
-| Claude (`engine/runtimes/claude.js`) | `~/.claude/skills`, `~/.agents/skills`, plus `~/.claude/plugins/<…>/skills` | `~/.claude/commands`, plugin `commands/` | `~/.claude.json → mcpServers` |
-| Copilot (`engine/runtimes/copilot.js`) | `~/.copilot/skills`, `~/.agents/skills`, `~/.copilot/installed-plugins/<…>/skills` | `~/.copilot/commands` *(probe)* | `~/.copilot/mcp-config.json → mcpServers` |
-| Codex (`engine/runtimes/codex.js`) | `~/.agents/skills`, `/etc/codex/skills` | not yet supported by CLI | not yet a stable contract |
-
-The first column is the source of truth for "where does the CLI look on
-this machine?". The dashboard's tooling page mirrors this via
-`engine/queries.js → collectSkillFiles / collectCommandFiles`.
-
-### 2. Cwd routing (`shared.resolveSpawnPaths`)
-
-`engine/shared.js → resolveSpawnPaths(project, type, MINIONS_DIR)` decides
-what the agent's `cwd` is:
-
-- **Read-only types** (`meeting`, `ask`, `explore`, `plan-to-prd`, `plan`)
-  → `cwd = project.localPath` (the operator's main checkout — sees
-  uncommitted files).
-- **Code-mutating types** (`implement`, `fix`, `review`, `test`, `verify`,
-  `decompose`, `docs`) → `cwd = <worktree>` (a fresh `git worktree add`
-  checked out at branch tip — only sees committed files).
-
-Cwd routing matters because every CLI's native discovery is **rooted at
-cwd**. Project-scope skills like `<repo>/.claude/skills/foo/SKILL.md` are
-loaded by the CLI only if `<cwd>/.claude/skills/foo/SKILL.md` exists at
-spawn time. See *The worktree-uncommitted footgun* below.
-
-Live-checkout mode (`project.checkoutMode: 'live'`) collapses both branches
-to `cwd = project.localPath` for every dispatch type, so the agent sees
-the operator's working tree as-is (including uncommitted assets). The
-tradeoff is single-mutating-dispatch concurrency per project — see
-`docs/live-checkout-mode.md`.
-
-### 3. `--add-dir` (`engine/spawn-agent.js → computeAddDirs`)
-
-`computeAddDirs({ runtime, minionsDir, homeDir })` builds the list of
-absolute dirs the CLI is allowed to read **outside** its cwd. The current
-list:
-
-1. `minionsDir` — always first, so playbooks, system prompt, and skill
-   index are reachable from any worktree.
-2. Every existing dir returned by `runtime.getUserAssetDirs({ homeDir })`
-   for the resolved runtime — e.g. `~/.claude` + `~/.agents` for Claude,
-   `~/.copilot` + `~/.agents` for Copilot, `~/.codex` + `~/.agents` for
-   Codex.
-
-Non-existent dirs are dropped (Claude CLI rejects unknown `--add-dir`
-entries) and the list is deduped by resolved path.
-
-`--add-dir` is the **only** mechanism today that crosses the worktree
-boundary. It does not (yet) cover project-local-but-uncommitted assets —
-that's plan item #5 (`harnessPropagateProjectLocal`).
-
-### 4. MCP suppression flags
-
-Two flags strip otherwise-inherited MCP / instruction surfaces; everything
-else flows through implicitly because the CLI reads its native config on
-every spawn:
-
-- `engine.copilotDisableBuiltinMcps` (default `true`) → `--disable-builtin-mcps`
-  on Copilot. Strips Copilot's built-in `github-mcp-server` so dispatched
-  agents do not try to open a parallel PR through the bundled MCP while
-  Minions is already managing the PR via the host integration.
-- `engine.copilotSuppressAgentsMd` (default `true`) → `--no-custom-instructions`
-  on Copilot. Strips project `AGENTS.md` auto-load so Minions playbook
-  prompts are not silently overridden by repo-local instructions.
-
-There is no equivalent flag for stripping user-level skills, user-level
-slash commands, or user-level MCPs. The current posture is "always inherit"
-— `engine.hermeticHarness` (P-49e1c8b7, default `false`) is the per-fleet /
-per-agent opt-out. When TRUE:
-
-- `--add-dir` collapses to exactly `[minionsDir]` — every dir from
-  `runtime.getUserAssetDirs({ homeDir })` is dropped.
-- `harnessPropagateProjectLocal` is skipped — no `--project-harness-dir`
-  flags emitted.
-- `claudePreApproveWorkspaceMcps` is skipped — workspace `.mcp.json`
-  servers are not pre-approved in `~/.claude.json`.
-
-The flag is **independent** of `copilotDisableBuiltinMcps` and
-`copilotSuppressAgentsMd` — those keep their existing semantics so an
-operator can run hermetic Claude *and* keep Copilot's built-in MCPs off
-or AGENTS.md auto-load suppressed without re-thinking each lever. Per-agent
-override at `agent.hermeticHarness` (resolved via
-`shared.resolveAgentHermeticHarness(agent, engine)`, mirrors
-`shared.resolveAgentBareMode`).
-
-## The worktree-uncommitted footgun
-
-The single biggest behavioral wrinkle for new contributors:
-
-1. The operator drops an experimental skill at
-   `<repo>/.claude/skills/bar/SKILL.md` on their main checkout.
-2. The skill works fine when invoked by hand:
-   `cd <repo>; claude "use the bar skill"` — Claude's auto-discovery
-   sees it because cwd is the main checkout.
-3. The operator dispatches an `implement` work item against the same repo.
-4. The engine runs `git worktree add <wt> origin/<branch>` (uncommitted
-   files do not appear in a fresh worktree), then spawns the agent with
-   `cwd = <wt>`.
-5. Claude's discovery now happens at `<wt>` — `.claude/skills/bar/` is
-   absent. The agent silently underperforms with no error message.
-
-Read-only dispatch types (`meeting`, `ask`, `explore`, `plan-to-prd`,
-`plan`) do **not** hit this footgun, because their cwd is
-`project.localPath`. Mutating types do.
-
-`--add-dir` is not currently extended to cover this case (plan item #5),
-so the only workarounds today are:
-
-- **Commit it.** The skill becomes visible to every dispatch and every
-  teammate, with the usual reviewability tradeoff.
-- **Move it user-scope.** Drop it under `~/.claude/skills/bar/` instead —
-  the CLI's user-skill discovery still works inside a worktree because
-  `--add-dir` attaches `~/.claude`.
-- **Flip to live-checkout mode.** Set `project.checkoutMode = 'live'` on
-  the project so every dispatch runs in `project.localPath`. Caveats in
-  `docs/live-checkout-mode.md`.
-
-The dashboard tooling page does not yet surface this gap; that's plan
-item #8 ("Harness diagnostics" panel). Until then, run
-`minions doctor --harness` to get the per-runtime view of which dirs the
-engine actually surfaces, and check that flagged "missing" entries
-actually match the assets you expected to inherit.
-
-## `minions doctor --harness`
-
-One-shot CLI diagnostic that prints, per registered runtime, every dir
-or file the engine would surface to a spawned agent under its scope label.
-Implemented in `engine/preflight.js → runHarnessDoctor(minionsHome)` and
-wired into `bin/minions.js` and `engine/cli.js` as the `--harness` mode
-of the existing `minions doctor` command.
-
-### What it prints
-
-```
-Minions Harness Propagation
-  Runtime: claude
-    User asset dirs (--add-dir to agents):
-      ✓ /home/you/.claude                                [user]
-      ✓ /home/you/.agents                                [user]
-    Skill roots (CLI native discovery):
-      ✓ /home/you/.claude/skills                         [user]
-      ✓ /home/you/.agents/skills                         [user]
-      ⚠ /repo/.claude/skills                             [project:myrepo]   (missing on disk)
-      ✓ /repo/.agents/skills                             [project:myrepo]
-    Skill write targets (auto-extract destinations):
-      ✓ /home/you/.claude/skills                         [personal]
-      ✓ /repo/.claude/skills                             [project:myrepo]
-  Runtime: copilot
-    User asset dirs (--add-dir to agents):
-      ✓ /home/you/.copilot                               [user]
-      ✓ /home/you/.agents                                [user]
-    …
-  Worktree --add-dir snapshot (engine fleet default: copilot):
-    ✓ /home/you/.minions                                 [minions]
-    ✓ /home/you/.copilot                                 [user]
-    ✓ /home/you/.agents                                  [user]
-  All harness paths surveyed. Missing on-disk paths are warnings, not failures —
-  they're listed so you can decide whether to create the dir, populate it, or
-  ignore it for this host.
-```
-
-### Exit behavior
-
-The command exits **0 on a healthy host** even if some scoped paths do
-not exist on disk. The whole point is to surface "what would the engine
-attach today?" — a user that does not run Codex may legitimately have
-no `~/.codex` dir, and that is not a failure. Exits non-zero only on a
-true runtime/config error (e.g. registry refuses to resolve a known
-runtime, or `config.json` is unparseable).
-
-### When to run it
-
-- After installing a new skill / command / MCP and "it didn't take" on
-  the next dispatched agent — confirm Minions actually surfaces that dir
-  for the runtime you're dispatching with.
-- After changing `engine.defaultCli` — different runtimes have different
-  asset dirs; the `Worktree --add-dir snapshot` block reflects the fleet
-  default.
-- After re-cloning a repo with `<repo>/.claude/skills/` — the diagnostic
-  shows whether the project-scope path is on disk.
-- Before reporting "agent ignored my skill" — half the time the answer is
-  visible in the diagnostic output.
-
-It does **not** check whether the assets *load successfully* inside the
-CLI (no parse of `SKILL.md`, no MCP handshake). For loadability,
-inspect the dashboard tooling page or run an `ask` dispatch and watch
-the live output.
-
-## Adapter contract summary
-
-The runtime adapters answer these questions. The engine never special-cases
-a runtime by name — it only calls these methods on the resolved adapter.
-
-| Method | Signature | Used by |
-|--------|-----------|---------|
-| `getUserAssetDirs({ homeDir })` | → `string[]` | `engine/spawn-agent.js → computeAddDirs`; `runHarnessDoctor` |
-| `getSkillRoots({ homeDir, project? })` | → `[{ scope, dir, projectName? }]` | `engine/queries.js → collectSkillFiles`; `runHarnessDoctor` |
-| `getSkillWriteTargets({ homeDir, project? })` | → `{ personal, project? }` | `engine/lifecycle.js → extractSkillsFromOutput`; `runHarnessDoctor` |
-| `getCommandRoots({ homeDir, project? })` | → `[{ scope, dir, projectName? }]` | `engine/queries.js → collectCommandFiles` (via `getProjectHarnesses` for project scope); `runHarnessDoctor` |
-| `getMcpConfigPaths({ homeDir, project? })` | → `[{ scope, file, projectName? }]` | `runHarnessDoctor`; planned: `engine/queries.js → getStatusSlowStateMtimePaths` |
-
-`runHarnessDoctor` renders all five surfaces as "Slash commands" and "MCP
-config files" sections alongside the existing User asset dirs / Skill
-roots / Skill write targets blocks. Adapters that don't yet have a stable
-CLI contract for a surface (today: Codex for both commands and MCP,
-Copilot for project-scope commands) return `[]` so consumers can iterate
-runtimes generically without per-runtime branching.
-
-`engine/queries.js` exposes two shared helpers — `getUserHarnesses(homeDir)`
-and `getProjectHarnesses(project)` — that iterate every registered runtime
-via `engine/runtimes.listRuntimes()` + `resolveRuntime()` and union the
-`getSkillRoots` / `getCommandRoots` / `getMcpConfigPaths` contributions,
-deduped by absolute path. The same physical dir contributed by multiple
-adapters (e.g. `~/.agents/skills` exposed by Claude, Copilot, and Codex)
-surfaces once with a `runtimes: [name, ...]` provenance array. Use them
-from dashboard / diagnostics consumers instead of re-walking adapters by
-hand; `collectSkillFiles` / `collectCommandFiles` already do.
-
-> **Follow-up.** `getStatusSlowStateMtimePaths` still hardcodes the
-> per-runtime MCP file paths; refactoring it to consume
-> `getUserHarnesses(...).mcps` + `getProjectHarnesses(...).mcps` is
-> tracked separately so the slow-state mtime tracker automatically picks
-> up new adapters.
-
-## Related docs
-
-- `docs/runtime-adapters.md` — full adapter interface table.
-- `docs/live-checkout-mode.md` — `project.checkoutMode: 'live'`
-  contract (alternative to the worktree-add-dir story for repos where
-  worktrees are unworkable).
-- `docs/skills.md` — skill block format and auto-extraction targets.
-- `plans/seamless-user-repo-harness-invocation.md` — full multi-item plan
-  this doc is the foundation of.
-- `CLAUDE.md` → "Agent Spawn" + "Adapter Contract" — load-bearing
-  invariants the propagation contract piggy-backs on.
+`minions doctor --harness` and the dashboard Tools view show adapter-declared
+native locations as read-only inventory. They do not influence spawning and do
+not claim that a runtime loaded or used an asset.

package/docs/human-vs-automated.md

@@ -15,7 +15,7 @@
 | Metrics | Engine (auto-collect) | Engine | You (view) | — |
 | Error recovery | Engine (detect) | — | You (retry/delete) | You |
 | Project linking | You (`minions add/scan`) | — | — | — |
-| MCP servers / Skills / Commands | You (native CLI config) | Inherited by agents | — | — (opt-out via `hermeticHarness`) |
+| MCP servers / Skills / Commands | You (native CLI config) | Discovered natively by the selected runtime | — | — |
 
 ## The Two Human Gates
 

package/docs/named-agents.md

@@ -43,7 +43,6 @@ The full per-agent config shape supported under `config.agents.<id>`:
 | `model` | string | Per-agent model override (omitted → runtime picks its own default). |
 | `maxBudgetUsd` | number | Per-spawn USD cap. **`0` is a valid cap** (read-only / dry-run agents), not "unlimited". |
 | `bareMode` | boolean | Run Claude in `--bare` mode (Claude-runtime knob). |
-| `hermeticHarness` | boolean | Strip user-scope skill/command/MCP roots from the worktree; `--add-dir` resolves to `[minionsDir]` only. |
 | `workspace_manifest` | object | Optional permission scoping — see below. |
 
 ### Three-tier resolution chain
@@ -57,7 +56,6 @@ The resolver helpers live in [`engine/shared.js`](../engine/shared.js):
 | `resolveAgentModel(agent, engine)` | `agent.model` → `engine.defaultModel` → `undefined` (adapter omits `--model`, CLI uses its own default). |
 | `resolveAgentMaxBudget(agent, engine)` | `agent.maxBudgetUsd` → `engine.maxBudgetUsd` → `undefined` (no cap). Nullish-coalesced so `0` is honored. |
 | `resolveAgentBareMode(agent, engine)` | `agent.bareMode` → `engine.claudeBareMode` → `false`. Strict null check so a per-agent `false` overrides an engine `true`. |
-| `resolveAgentHermeticHarness(agent, engine)` | `agent.hermeticHarness` → `engine.hermeticHarness` → `false`. Same strict-override semantics. |
 
 Empty string / `null` / `undefined` all count as "unset" for the string knobs, so an agent
 inherits the fleet default rather than blanking the value.

package/docs/plan-lifecycle.md

@@ -116,18 +116,18 @@ The verify agent and the user can then build and run from these paths.
 
 ## Manual Archive Lifecycle
 
-Archiving is a deliberate dashboard action, not a post-verify side effect. When a PRD completes, `checkPlanCompletion()` writes the completion summary, persists `status: "completed"` plus `_completionNotified`, and creates the verify work item. The PRD remains in `prd/` and its source plan remains in `plans/` so humans can review the guide, inspect the final state, resume stale work, or reopen items before hiding the plan from active views.
+Archiving is a deliberate dashboard action, not a post-verify side effect. When a PRD completes, `checkPlanCompletion()` writes the completion summary, persists `status: "completed"` plus `_completionNotified` in SQL, and creates the verify work item. The PRD remains active and its source plan remains in `plans/` so humans can review the guide, inspect the final state, resume stale work, or reopen items before hiding the plan from active views.
 
 The verify agent does not call `archivePlan()`. After the testing guide and any follow-up PR work are satisfactory, use the dashboard archive action, which calls `POST /api/plans/archive` with the active PRD or plan filename.
 
 Manual archive behavior:
 
-1. For PRD JSON files, the dashboard archives them **in-place** in `prd/` — the file is not moved. The JSON is stamped with `archived: true`, `status: "archived"`, and `archivedAt` (Phase 10 step 4.2b). **No `.backup` sidecar is written or restored for any `prd/*.json`** — Phase 10 step 4.3 dropped the PRD backup/restore lifecycle entirely (root-level PRDs used to get one to survive the now-retired rename race; SQL is canonical, so a stale `.backup` is pure resurrection fuel, not a safety net).
+1. The dashboard updates the SQL PRD row with `archived: true`, `status: "archived"`, and `archivedAt`.
 2. If the PRD has `source_plan`, the matching `plans/<source>.md` is moved to `plans/archive/<source>.md`.
 3. Pending or queued work items linked to the archived PRD are cancelled with `_cancelledBy: "plan-archived"`; completed work items remain as history.
 4. Plan worktrees are cleaned up by the archive handler/lifecycle cleanup path.
 
-Use unarchive only when the archived PRD/plan should reappear in active views. Reopening completed work should happen before archive, or after unarchive, so the materializer can see the active PRD file.
+Use unarchive only when the archived PRD/plan should reappear in active views. Reopening completed work should happen before archive, or after unarchive, so the materializer can see the active SQL PRD.
 
 ## Human Feedback on PRs
 
@@ -151,10 +151,9 @@ After PRs are created, humans can leave comments containing `@minions` to trigge
 | File | Purpose |
 |------|---------|
 | `plans/*.md` | Source plans awaiting review or linked to active PRDs |
-| `prd/*.json` | Active PRDs with materializable items |
+| SQL `prds` + `prd_items` | Active and archived PRDs with materializable items |
 | `plans/archive/` | Manually archived plan Markdown files |
-| `prd/*.json` (with `archived: true`) | PRDs archived in-place (Phase 10 step 4.2b — not moved; flag + `archivedAt` stamped on the file) |
-| `prd/archive/` | Legacy: PRDs archived before Phase 10 (still scanned for filename-collision detection) |
+| `prd/` | Legacy upgrade input only; migration 018 imports and retires these files |
 | `playbooks/verify.md` | Verification task playbook |
 | `playbooks/implement.md` | Implementation playbook |
 | `playbooks/plan-to-prd.md` | Plan → PRD conversion playbook |

package/docs/qa-runbook-lifecycle.md

@@ -17,7 +17,7 @@ engine-assigned `id`). `target` is a name from `/api/managed-processes` or
 
 ## Run-record path
 
-`qa-runs.json` (newest-first, capped). Each run:
+The SQL `qa_runs` table stores newest-first, capped run records. Each run:
 `{ id, runbookId, runbookName, target, status, startedAt, completedAt, workItemId, agentId, artifacts }`.
 `status` ∈ `pending|dispatched|running|passed|failed|error`. Created by
 `POST /api/qa/runbooks/run` (`{ id }`), which dispatches a `qa-validate`
@@ -27,29 +27,14 @@ and clears the interval on page navigation via the `switchPage` wrapper in
 `dashboard/js/qa.js` (matches `_stopPlanPoll`/`_stopMeetingPoll` pattern in
 `dashboard/js/state.js`).
 
-### Persistence (Phase 8: SQLite source of truth)
-
-Since the Phase 8 migration (`migrate-qa-state-to-sqlite`), both
-`qa-runs.json` and `qa-sessions.json` are dual-written sidecars and SQLite
-(`engine/state.db`, tables `qa_runs` + `qa_sessions`) is the source of
-truth. Every mutation goes through `shared.mutateQaRuns` /
-`shared.mutateQaSessions`, which apply inside a SQLite transaction
-(`BEGIN IMMEDIATE`) then best-effort mirror to JSON under a `withFileLock`
-on the sidecar path so cross-process writers serialize. Reads go through
-`small-state-store.readQaRuns` / `readQaSessions`, which compare the SQL
-content-hash to the JSON sidecar and rehydrate SQL from JSON when an
-external editor (operator hand-edit, manual rollback) has diverged.
-
-The JSON mirror is gated by `engine.qaDualWriteJson` (default true). Once
-operators trust SQL as the source of truth and have migrated external
-tooling off the JSON files, flip it false via Dashboard → Settings →
-Advanced → "QA: dual-write JSON sidecars" to halve write I/O. With the
-toggle off, `qa-runs.json` / `qa-sessions.json` stop receiving updates
-(stale snapshot at the moment of the flip), so don't disable until any
-external readers have moved to the SQL tables or the dashboard `/api/qa/*`
-endpoints. The qa-runs cap (`QA_RUNS_MAX_RECORDS=2000`) and qa-sessions
-cap (`QA_SESSIONS_MAX_RECORDS=500`) still apply, enforced in-memory at
-createRun/createSession time.
+### Persistence
+
+SQLite (`engine/state.db`, tables `qa_runs` and `qa_sessions`) is the sole
+source of truth. Every mutation goes through `shared.mutateQaRuns` or
+`shared.mutateQaSessions` inside a transaction. Legacy JSON is imported only
+during upgrade or through the explicit offline recovery command. The qa-runs
+cap (`QA_RUNS_MAX_RECORDS=2000`) and qa-sessions cap
+(`QA_SESSIONS_MAX_RECORDS=500`) remain enforced at creation time.
 
 ### Deleting runs
 
@@ -253,7 +238,7 @@ errors are mapped to HTTP via `_qaSessionsErrorToStatus`:
   DRAFT agent. Path is sandboxed by `_isSafeSessionId` (kebab-case ≤ 64
   chars, no `..`, no separators) before every read/write that maps id →
   path. Gitignored.
-- **Managed-spawn**: `engine/managed-processes.json` entry with
+- **Managed-spawn**: SQL managed-process entry with
   `name='qa-session-<sessionId>'`. Cleaned up by `/kill` or by the
   session's `cancelSession` if the operator opts for the cancel-without-
   spawn-kill path.

package/docs/shared-lifecycle-module-map.md

@@ -105,7 +105,6 @@ because either is a bug:
 |---|---|---|
 | minions root pointer | `readMinionsRootPointer`, `saveMinionsRootPointer` | shared.js |
 | dashboard port file | `readDashboardPortFile`, `writeDashboardPortFile` | shared.js |
-| agent Copilot home dir | `resolveAgentCopilotHome`, `ensureAgentCopilotHome` | shared.js |
 | canonical PR id | `parseCanonicalPrId`, `getCanonicalPrId` | shared.js |
 | PR record | `findPrRecord`, `normalizePrRecord` | shared.js |
 | worktree owner marker | `writeWorktreeOwnerMarker`, `hasWorktreeOwnerMarker` | shared.js |
@@ -214,7 +213,7 @@ means zero such files were found), **Proposed target module**.
 | `redactPromptDescription` | 447-458 | Redactor applied to WI description text before it is injected into an agent // prompt. Applies the standard log redactor (_redactString) first, then catches // any remaining Authorization: Bearer header — including alrea | yes | `engine.js` | engine/shared.js (keep) |
 | `log` | 459-531 | Log. | yes | `engine/abandoned-pr-reconciliation.js`, `engine/ado-git-auth.js`, `engine/ado-status.js`, `engine/ado.js`, `engine/cc-worker-pool.js`, `engine/check-status.js` +72 more | engine/shared.js (keep) — logging/timestamp primitives |
 | `_currentLogPath` | 532-547 | Resolve the log file path at write time, not at module load time. `LOG_PATH` is captured eagerly when shared.js first loads. In production this is fine — there's a single shared.js instance per process. In tests the requ | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
-| `_currentLogDbPath` | 548-559 | Resolve the SQL state.db path at write time — same isolation contract // as _currentLogPath. MINIONS_LOG_PATH only redirects the JSON sidecar; // the SQL store stays attached to MINIONS_TEST_DIR / MINIONS_HOME because // | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
+| `_currentLogDbPath` | 548-559 | Resolve the SQL state.db path at write time with test/home isolation. | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
 | `resolveEngineCacheDir` | 560-593 | MINIONS_TEST_DIR-aware engine dir for cache files (runtime caps, models, // spawn-debug.log). Returns `<MINIONS_TEST_DIR>/engine` under tests; otherwise // the caller's source-adjacent fallback (typically `__dirname`-der | yes | `engine/runtimes/claude.js`, `engine/runtimes/codex.js`, `engine/runtimes/copilot.js` | engine/shared.js (keep) |
 | `openUrlInBrowser` | 594-645 | Cross-platform URL opener. Uses execSync so failures fall through the // try/catch and the caller sees them. Dashboard self-open and `minions dash` // / `minions restart` post-health open all funnel through here. // // E | yes | `test/unit/dashboard-port-resolution.test.js`, `dashboard.js`, `engine.js` | engine/shared.js (keep) |
 | `_bumpBrowserOpenMetric` | 646-662 | Bump per-reason counter under metrics._engine.browserOpens. Best-effort — // metrics.json writes must never throw out of openUrlInBrowser. Schema: // _engine.browserOpens.<reason> = { count, suppressedCount, lastAt } | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
@@ -324,7 +323,6 @@ means zero such files were found), **Proposed target module**.
 | `resolveAgentBareMode` | 3974-3991 | Resolve whether this agent should run in Claude `--bare` mode. Priority: 1. `agent.bareMode` — per-agent override (boolean) 2. `engine.claudeBareMode` — fleet default 3. `false` — hardcoded fallback Strict undefined/null | yes | `test/unit.test.js`, `engine.js` | engine/shared.js (keep) |
 | `_normalizeMcpServerList` | 3992-4005 | P-mcp-storm — Resolve the list of MCP server names to disable for spawned // Copilot agents. The engine FILTERS these out of the agent's seeded // COPILOT_HOME mcp-config (engine.js `_applyAgentCopilotHome`) — a server a | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
 | `resolveCopilotAgentDisabledMcpServers` | 4006-4030 | Resolve copilot agent disabled mcp servers. | yes | `test/unit/agent-copilot-home.test.js` | engine/shared.js (keep) |
-| `resolveAgentHermeticHarness` | 4031-4062 | P-49e1c8b7 — Resolve whether this agent should run with a hermetic harness. Priority (mirrors `resolveAgentBareMode`): 1. `agent.hermeticHarness` — per-agent override (boolean) 2. `engine.hermeticHarness` — fleet default | yes | `engine/spawn-agent.js`, `engine.js` | engine/shared.js (keep) |
 | `applyLegacyCcModelMigration` | 4063-4082 | If `config.engine.ccModel` is set but `config.engine.defaultModel` is unset, mutate the in-memory `config.engine` so `defaultModel` mirrors `ccModel` and log a one-time deprecation notice. Does NOT write to disk. Returns | yes | `engine/cli.js`, `test/unit.test.js` | engine/shared.js (keep) |
 | `_resetLegacyCcModelMigrationFlag` | 4083-4113 | Test helper: reset the dedup flag so repeated tests can re-trigger the log. | yes | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
 | `runtimeConfigWarnings` | 4114-4194 | Inspect runtime fleet config and return warning entries for misconfiguration. Warnings emitted: - Unknown CLI: any `cli` value (per-agent, ccCli, defaultCli) not in `registeredRuntimes`. Each unknown value produces one e | yes | `engine/preflight.js` | engine/process-utils.js (new) — process spawn/pid/tmp-dir lifecycle helpers |
@@ -337,13 +335,11 @@ means zero such files were found), **Proposed target module**.
 | `_qaDualWriteEnabled` | 4673-4681 | Phase 8 — QA state mutators. Both qa-runs and qa-sessions are top-level JSON arrays (mutator receives the array; mutates in place or returns a replacement). The store diffs by `id`. Falls back to mutateJsonFileLocked on  | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
 | `_qaMutator` | 4682-4720 | Qa mutator. | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
 | `mutateWatches` | 4721-4741 | Route a watches mutation through the SQL store. Same shape as mutateWorkItems / mutatePullRequests: mutator receives the watches array, mutates in place or returns a replacement, and the store diffs by id. SQL-canonical  | yes | `engine/watches.js` | engine/shared.js (keep) |
-| `mutateMetrics` | 4742-4763 | Route a metrics mutation through the SQL store with a JSON dual-write mirror. Same shape as mutateWorkItems / mutatePullRequests: mutator receives the full legacy-shape metrics object, mutates in place or returns a repla | yes | `engine/cleanup.js`, `engine/llm.js`, `test/unit/auto-recovery.test.js`, `engine.js` | engine/shared.js (keep) |
+| `mutateMetrics` | 4742-4763 | Route a metrics mutation through the SQL store. | yes | `engine/cleanup.js`, `engine/llm.js`, `test/unit/auto-recovery.test.js`, `engine.js` | engine/shared.js (keep) |
 | `trackReviewMetric` | 4764-4784 | Update per-agent review metrics (prsApproved/prsRejected). Only writes for configured agents. | yes | `engine/ado.js`, `engine/github.js`, `engine/queries.js`, `test/unit.test.js` | engine/shared.js (keep) |
 | `queuePlanToPrd` | 4785-4822 | Queue a plan-to-prd work item with dedup check inside lock. Returns { queued, alreadyQueued, id, item } so callers (e.g. POST /api/plans/execute) can surface the new or existing work item id back to the dashboard. Return | yes | `test/unit.test.js`, `dashboard.js` | engine/shared.js (keep) |
 | `extractPlanDeclaredProject` | 4823-4845 | Extract plan declared project. | yes | `dashboard.js`, `engine.js` | engine/shared.js (keep) |
 | `extractPlanTargetProjects` | 4846-4974 | P-7a3f1c08: Parse a cross-repo plan's list of target projects. // Primary signal: `<!-- minions:targetProjects=a, b, c -->` HTML comment. // Fallback (human): ` Projects: a, b \| c` markdown line in the first 80 lines. // | yes | `dashboard.js`, `engine.js` | engine/shared.js (keep) |
-| `normalizeHarnessUsed` | 4975-5027 | normalizeHarnessUsed(raw) — validate/clamp an untrusted harnessUsed-shaped // object into the canonical { skills, mcpServers, commands, docs } form. // Drops malformed entries (non-objects, or missing the kind's required | yes | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
-| `groundHarnessUsed` | 5028-5099 | groundHarnessUsed(harnessUsed, propagated) — Stage 2 grounding cross-check // (P-c6f5e8b3). Normalizes an agent's self-reported `harnessUsed` and annotates // every surviving entry with a strict-boolean `grounded` field  | yes | `engine/cli.js` | engine/shared.js (keep) |
 | `_bumpPruneDefaultClaudeStrip` | 5100-5114 | Bump rolling-daily strip counter for docs/deprecated.json#prune-default-claude-config // removal gate (>=30 consecutive days of zero strips). Best-effort; mirrors // engine/cleanup.js:1200-1213 _engine.legacyStatusMigrat | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
 | `pruneDefaultClaudeConfig` | 5115-5185 | Prune default claude config. | yes | `test/unit.test.js`, `dashboard.js`, `minions.js` | engine/shared.js (keep) |
 | `_isStringArrayOrNull` | 5186-5202 | Is string array or null. | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
@@ -398,14 +394,11 @@ means zero such files were found), **Proposed target module**.
 | `parseWorktreePorcelain` | 6139-6169 | Parse `git worktree list --porcelain` output. Pure — callers run the subprocess (sync `execSilent` or async `execAsync`) and feed stdout in. Returns `[{path, head, branch, bare, detached, locked, prunable}]`. `branch` st | yes | `engine/cleanup.js`, `engine/worktree-gc.js`, `test/unit.test.js`, `engine.js` | engine/worktree-utils.js (new) — general worktree path/branch/owner-marker helpers (worktree-pool.js/worktree-gc.js already own pool sizing + GC sweep; this new module would take the shared low-level helpers those two currently import from shared.js) |
 | `assertWorktreeOutsideProject` | 6170-6203 | Throws when `worktreePath` would land inside (or equal) `projectRoot`. Called by the engine spawn path before `git worktree add`, and by the cleanup sweep that audits already-registered worktrees per linked project. The  | yes | `test/unit.test.js`, `dashboard.js`, `engine.js` | engine/worktree-utils.js (new) — general worktree path/branch/owner-marker helpers (worktree-pool.js/worktree-gc.js already own pool sizing + GC sweep; this new module would take the shared low-level helpers those two currently import from shared.js) |
 | `resolveProjectRootDir` | 6204-6259 | Resolve the project root directory used as the parent for git worktree paths during dispatch. Centralizes the fallback that engine spawnAgent used to do inline (`project.localPath ? path.resolve(project.localPath) : path | yes | `engine/create-pr-worktree.js`, `test/unit.test.js`, `engine.js` | engine/shared.js (keep) |
-| `resolveAgentCopilotHome` | 6260-6286 | Resolve a stable, repo-EXTERNAL COPILOT_HOME for spawned copilot agents. Copilot loads `$COPILOT_HOME/mcp-config.json` and SPAWNS every server in it on every process start. `--disable-mcp-server <name>` only hides a serv | yes | `test/unit/agent-copilot-home.test.js`, `engine.js` | engine/shared.js (keep) |
 | `resolveAgentTempBaseDir` | 6287-6308 | Derive a scratch/temp base dir on the same volume agent work already lives on — the configured worktree location (engine.worktreeRoot, default `../worktrees`). Agents (copilot/node/git + JVM-based MCP servers) write heav | yes | `test/unit/agent-temp-dir.test.js`, `engine.js` | engine/shared.js (keep) |
-| `ensureAgentCopilotHome` | 6309-6412 | Seed the agent COPILOT_HOME's mcp-config (copy of `~/.copilot/mcp-config.json` // MINUS `engine.copilotAgentDisabledMcpServers`) and return the home path. This // is the single source of truth for "what MCP servers may a | yes | `test/unit/agent-copilot-home.test.js`, `dashboard.js`, `engine.js` | engine/shared.js (keep) |
 | `resolveSpawnPaths` | 6413-6505 | Resolve the agent's working directory and (when needed) the parent dir for git worktree placement. Decouples the two concerns that spawnAgent used to conflate (W-mp73x32w000l143d): 1. cwd — where the agent process actual | yes | `engine/live-checkout.js`, `test/unit.test.js`, `engine.js` | engine/shared.js (keep) |
 | `_applyWorkdirOrThrow` | 6506-6518 | ── meta.workdir helpers (P-714ef144) // // Per-WI `meta.workdir` is a relative POSIX subpath under the spawn base // (project.localPath for read-only / live; worktree root for mutating). // When set, the engine lands the | no | _internal-only (no callers found outside shared.js)_ | engine/shared.js (keep) |
 | `validateWorkItemWorkdir` | 6519-6561 | Validate work item workdir. | yes | `dashboard.js`, `engine.js` | engine/shared.js (keep) |
 | `applyWorkdir` | 6562-6586 | Apply workdir. | yes | `engine.js` | engine/shared.js (keep) |
-| `filterProjectHarnessDirsForWorkdir` | 6587-6650 | Filter project harness dirs for workdir. | yes | `engine.js` | engine/shared.js (keep) |
 | `isAllowedOrigin` | 6651-6686 | Returns true if the origin-like header value (either an `Origin` header value such as `http://localhost:7331` or a full `Referer` URL) belongs to the local dashboard allowlist. Port-agnostic. Returns false for null/undef | yes | `test/unit.test.js`, `dashboard.js` | engine/shared.js (keep) |
 | `isAllowedDashboardOrigin` | 6687-6705 | Returns true if the given `Origin` header value should receive an `Access-Control-Allow-Origin` echo on GET/HEAD responses. STRICTER than `isAllowedOrigin` — that helper is the mutating-request gate (allows any localhost | yes | `test/unit.test.js`, `dashboard.js` | engine/shared.js (keep) |
 | `buildSecurityHeaders` | 6706-6721 | Returns the baseline set of security response headers to apply on every HTTP response from the dashboard. Values match OWASP defaults for a same-origin SPA served from 127.0.0.1. The HTML entry-point response intentional | yes | `test/unit.test.js`, `dashboard.js` | engine/shared.js (keep) |
@@ -609,7 +602,6 @@ Same columns as above, relative to `lifecycle.js`.
 | `parseAgentOutput` | 4020-4024 | Agent Output Parsing | yes | `engine/timeout.js`, `test/unit.test.js`, `engine.js` | engine/lifecycle.js (keep) |
 | `hasActionableFailureClass` | 4025-4047 | Has actionable failure class. | no | _internal-only (no callers found outside lifecycle.js)_ | engine/lifecycle.js (keep) |
 | `handleInjectionFlag` | 4048-4134 | F5 (W-mpeklod3000we69c): handle agent-reported injection attempts. The agent set `securityFlags.injectionAttempt: true` in its completion report after spotting attacker-controlled instructions inside an `<UNTRUSTED-INPUT | no | _internal-only (no callers found outside lifecycle.js)_ | engine/lifecycle.js (keep) |
-| `resolveHarnessPropagated` | 4135-4149 | resolveHarnessPropagated(dispatchItem) — P-c6f5e8b3. Locate the spawn-time // `_harnessPropagated` manifest for a dispatch. The in-memory dispatchItem // (spawnAgent's closure object) normally carries it directly; after  | yes | `engine.js` | engine/lifecycle.js (keep) |
 | `parseCompletionReportFile` | 4150-4172 | Parse completion report file. | yes | `engine/timeout.js`, `test/unit.test.js` | engine/lifecycle.js (keep) |
 | `normalizeCompletionArtifacts` | 4173-4198 | Normalize completion artifacts. | yes | _internal-only (no callers found outside lifecycle.js)_ | engine/lifecycle.js (keep) |
 | `normalizeArtifactPath` | 4199-4212 | Normalize artifact path. | no | _internal-only (no callers found outside lifecycle.js)_ | engine/lifecycle.js (keep) |

package/docs/team-memory.md

@@ -1,6 +1,6 @@
 # Team Memory
 
-Minions agents share knowledge through a layered memory system. Before an agent does any independent research — web searches, broad codebase exploration, external doc reading — it is expected to check what the team already knows.
+Minions agents share knowledge through a layered Markdown system plus a structured SQLite retrieval index. Before an agent does any independent research — web searches, broad codebase exploration, external doc reading — it is expected to check what the team already knows.
 
 This document describes the four-tier read order the engine enforces in dispatch prompts, the rationale, and the constraint that `knowledge/` is **sweep-write-only**.
 
@@ -12,7 +12,21 @@ Multiple agents work the same repository in parallel and across days. Without sh
 - Agents re-litigate decisions the team already made (drift, regressions).
 - Human-flagged warnings (e.g., "do not self-approve PRs") get ignored because they live outside the prompt.
 
-Team memory closes the loop. The engine injects pinned context and recent team notes into every dispatch prompt automatically, and the playbooks instruct agents to consult `knowledge/` and `notes/inbox/` on disk before going wider. This keeps work cheap, decisions sticky, and prior learnings reusable.
+Team memory closes the loop. The engine always injects pinned context. By default it also injects recent team and personal notes; when structured retrieval is enabled outside shadow mode, it replaces those broad appendices with a bounded task-relevant memory pack. Playbooks still instruct agents to consult `knowledge/` and `notes/inbox/` on disk before going wider.
+
+## Structured memory and retrieval
+
+Migration `017-agent-memory.js` backfills the existing Markdown sources into `memory_records` and an FTS5 index without deleting or rewriting those files. Records carry a type (`semantic`, `episodic`, or `procedural`), scope, trust level, source reference, confidence, importance, validity timestamps, and lifecycle status (`active`, `superseded`, `retracted`, or `expired`).
+
+`engine/memory-retrieval.js` searches active records in global, current-project, and assigned-agent scopes. It reranks lexical matches by scope, trust, path match, recency, importance, and confidence, then packs the best records into a strict byte budget. Agent- or external-authored procedural records are never recalled as instructions. Every injected pack remains inside an `<UNTRUSTED-INPUT>` fence.
+
+Rollout is controlled by the default-off `memoryRetrieval` feature flag:
+
+- **Flag off:** legacy prompt behavior.
+- **Flag on + `memoryRetrievalShadowMode: true` (default):** compute retrieval and telemetry, but keep legacy prompts.
+- **Flag on + shadow mode off:** inject `Relevant Memory` when retrieval finds evidence; otherwise fall back to legacy notes and personal memory.
+
+Settings expose top-k, candidate count, byte budget, shadow mode, and episodic capture. The Inbox page's **Memory search** control shows provenance and status and supports explicit pin, retract, and restore actions.
 
 ## The four-tier read order
 
@@ -54,7 +68,7 @@ Agents read `knowledge/` directly with grep/glob/view. They **do not** write to
 
 `notes.md` is the rolling team notebook. The consolidation sweep periodically merges high-signal findings from the inbox into dated `### YYYY-MM-DD` sections at the top of `notes.md`, with links back to the underlying KB entries.
 
-The engine injects `notes.md` into every prompt under a "Team Notes (MUST READ)" heading. When the file exceeds `ENGINE_DEFAULTS.maxNotesPromptBytes`, the engine keeps the most recent 10 sections, truncates the body, and appends a footer noting how many older sections live on disk so agents can read the full file when they need depth.
+In legacy and shadow modes, the engine injects `notes.md` under a "Team Notes (MUST READ)" heading. When active retrieval returns evidence, the bounded `Relevant Memory` pack replaces this broad appendix. When the file exceeds `ENGINE_DEFAULTS.maxNotesPromptBytes`, the legacy path keeps the most recent 10 sections, truncates the body, and appends a footer noting how many older sections live on disk.
 
 ### 4. `notes/inbox/` — fresh agent findings
 
@@ -70,7 +84,7 @@ The consolidation sweep is what eventually promotes inbox notes into `knowledge/
 
 #### Failure-path exception
 
-Inbox writes are **success artifacts only**. If a task fails, is blocked, is cancelled, or ends partial, the agent must **not** create an inbox note — the failure is reported through the completion JSON, the PR/work-item comment, or the task-specific failure channel instead. This keeps the inbox a clean signal and prevents noise from drowning out durable findings.
+Inbox writes are **success artifacts only**. If a task fails, is blocked, is cancelled, or ends partial, the agent must **not** create an inbox note. When `memoryEpisodicCapture` is enabled, lifecycle records a compact structured outcome for successful, partial, and failed dispatches; it never stores transcripts or chain-of-thought and skips nonce-mismatched or injection-flagged reports.
 
 ## Rationale