@yemi33/minions 0.1.2338 → 0.1.2340

package/dashboard/js/render-prs.js

@@ -291,10 +291,10 @@ function prRow(pr) {
     '<td><a class="pr-title" title="' + escapeHtml(titleText) + '" href="' + escapeHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escapeHtml(titleText) + '</a>' + followupChip + pausedChips + (descPreview ? '<div class="pr-desc" title="' + escapeHtml(descPreview) + '">' + escapeHtml(descPreview.length > 120 ? descPreview.slice(0, 120) + '...' : descPreview) + '</div>' : '') + '</td>' +
     '<td><span class="pr-badge ' + statusClass + '" title="' + escapeHtml(statusLabel) + '">' + escapeHtml(statusLabel) + '</span></td>' +
     '<td><span class="pr-badge ' + reviewClass + '" title="' + escapeHtml(reviewTitle || reviewLabel) + '">' + escapeHtml(reviewLabel) + '</span></td>' +
+    '<td><span class="pr-badge ' + buildClass + '" title="' + escapeHtml(buildTitle || buildLabel) + '">' + escapeHtml(buildLabel) + '</span></td>' +
     '<td><span class="' + branchClass + '" title="' + escapeHtml(branchError || branchLabel) + '">' + escapeHtml(branchLabel) + '</span>' + pendingReasonHtml + '</td>' +
     '<td><span class="pr-agent" title="' + escapeHtml(agentText) + '">' + escapeHtml(agentText) + '</span></td>' +
     '<td>' + reviewerCell + '</td>' +
-    '<td><span class="pr-badge ' + buildClass + '" title="' + escapeHtml(buildTitle || buildLabel) + '">' + escapeHtml(buildLabel) + '</span></td>' +
     '<td>' + (observeBtn || '<span style="color:var(--muted);font-size:var(--text-base)">—</span>') + '</td>' +
     '<td><span class="pr-date" title="' + escapeHtml(createdLabel) + '">' + escapeHtml(createdLabel) + '</span></td>' +
     '<td><button class="pr-info-pill" data-pr-id="' + escapeHtml(String(prId)) + '" onclick="event.stopPropagation();openPrDetail(this.dataset.prId)" title="Open PR detail (in-stack modal)">&#x2197;</button>' +
@@ -312,10 +312,10 @@ const PRS_COLGROUP =
     '<col style="width:320px">' +   // Title
     '<col style="width:110px">' +   // Status
     '<col style="width:130px">' +   // Review
+    '<col style="width:130px">' +   // Build
     '<col style="width:200px">' +   // Branch
     '<col style="width:140px">' +   // Agent
     '<col style="width:140px">' +   // Signed Off By
-    '<col style="width:130px">' +   // Build
     '<col style="width:100px">' +   // Observe
     '<col style="width:130px">' +   // Created
     '<col style="width:80px">' +    // Actions (info-pill + remove)
@@ -325,7 +325,7 @@ function prTableHtml(rows) {
   return '<div class="pr-table-wrap pr-table-wrap--prs"><table class="pr-table pr-table--prs">' +
     PRS_COLGROUP +
     '<thead><tr>' +
-    '<th>PR</th><th>Title</th><th>Status</th><th>Review</th><th>Branch</th><th>Agent</th><th>Signed Off By</th><th>Build</th><th>Observe</th><th>Created</th><th></th>' +
+    '<th>PR</th><th>Title</th><th>Status</th><th>Review</th><th>Build</th><th>Branch</th><th>Agent</th><th>Signed Off By</th><th>Observe</th><th>Created</th><th></th>' +
     '</tr></thead><tbody>' + rows + '</tbody></table></div>';
 }
 

package/docs/kb-sweep.md

@@ -8,10 +8,11 @@ The KB sweep is a 3-pass cycle implemented in [`engine/kb-sweep.js`](../engine/k
 
 ```
 Entries in knowledge/<category>/*.md
-  → Pass 1: Hash dedup       (cheap, no LLM)
-  → Pass 2: LLM batch sweep  (Haiku, batches of 30)
+  → Pass 1: Hash dedup        (cheap, no LLM)
+  → Pass 2: LLM batch sweep   (Haiku, batches of 30)
+  → Pass 2.5: Age-TTL expiry  (per-category, no LLM)
   → Pass 3: Per-entry rewrite (Haiku, concurrency 5)
-  → Prune _swept/ archive    (>30 days)
+  → Prune _swept/ archive     (>30 days)
   → Invalidate KB cache, write engine/kb-swept.json
 ```
 
@@ -41,6 +42,26 @@ Reclassification targets are validated against `shared.KB_CATEGORIES` (`architec
 
 If a batch returns invalid JSON or the runtime is unavailable, that batch is skipped with a warning and the rest of the sweep continues (source: [`engine/kb-sweep.js:139-151`](../engine/kb-sweep.js#L139)).
 
+### Pass 2.5 — Age-Based TTL Expiry
+
+Cheap, deterministic. No LLM call. This pass is what keeps the KB from ballooning indefinitely: the dedup and rewrite passes can only reclaim *duplicate* or *empty* entries, but the highest-volume categories (`project-notes`, `build-reports`, `reviews`) are dominated by **one-off, PR/incident-scoped notes** that are each unique by PR#/date. Nothing in Passes 1–3 can ever remove them, so without an age cutoff they accumulate forever.
+
+For every surviving entry, the pass computes the entry's age and archives it to `knowledge/_swept/` when it exceeds that category's TTL (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js) `_expireByAge`). Two safety properties:
+
+- **Age is taken from the authored date** (`YYYY-MM-DD-` filename prefix / `date:` frontmatter), *not* mtime — so the Pass 3 rewrite touching a file does not reset its clock and let a stale entry live forever. When no date is parseable it falls back to mtime; when neither exists the entry is treated as fresh and never age-expired (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js) `_entryAgeMs`).
+- **Only categories with a positive TTL are eligible.** Durable categories (`architecture`, `conventions`) are absent from the default map and are never age-expired. Per-agent memory under `knowledge/agents/` is never even scanned into the manifest (it's not in `KB_CATEGORIES`), and pinned entries are excluded upstream — so none of them can be aged out.
+
+The TTL map is `ENGINE_DEFAULTS.kbCategoryTtlDays`, overridable per-fleet via `config.engine.kbCategoryTtlDays` (merged over the defaults; set a category to `0` to disable expiry for it):
+
+| Category | Default TTL (days) |
+|----------|--------------------|
+| `project-notes` | 21 |
+| `build-reports` | 14 |
+| `reviews` | 30 |
+| `architecture`, `conventions` | — (never) |
+
+Because expiry archives to `_swept/` (subject to the same 30-day retention as every other pass), an over-aggressive TTL is fully recoverable for ~30 days before the archive is pruned.
+
 ### Pass 3 — Per-Entry Rewrite
 
 Survivors of Passes 1 and 2 that are still on disk get rewritten one entry at a time, with up to `NORMALIZE_CONCURRENCY = 5` parallel workers (source: [`engine/kb-sweep.js:26`](../engine/kb-sweep.js#L26)). Each entry is sent to Haiku with a fixed template prompt that:
@@ -145,12 +166,13 @@ The KB page is refreshed by the dashboard's main refresh loop **every third tick
   hashDuplicatesArchived,  // Pass 1
   llmDuplicatesArchived,   // Pass 2 (within-batch dupes)
   staleRemoved,            // Pass 2 (LLM-flagged removals)
+  ageExpired,              // Pass 2.5 (per-category age-TTL archival)
   reclassified,            // Pass 2 (category moves)
   rewritten,               // Pass 3
   rewriteBytesBefore, rewriteBytesAfter,
   sweptArchivePruned,      // Files purged from _swept/ (>30 days)
   durationMs,
-  summary: '<n> hash-dup, <n> llm-dup, <n> stale, <n> reclassified, <n> rewritten (<bytes> saved)',
+  summary: '<n> hash-dup, <n> llm-dup, <n> stale, <n> age-expired, <n> reclassified, <n> rewritten (<bytes> saved)',
 }
 ```
 

package/docs/proposals/repo-pool-for-live-checkout.md

@@ -0,0 +1,239 @@
+# Design review: Repo pool for live-checkout projects (multi-enlistment dispatch)
+
+> **Review-only artifact.** This document exists so the approved implementation
+> plan and materialized PRD for the *Repo pool for live-checkout projects*
+> feature have a reviewable, git-tracked surface — `plans/` and `prd/` are
+> gitignored and never committed, so there is otherwise nothing for a human to
+> comment on before the dependent implementation work items land as code PRs.
+> **No functional code changes accompany this file.**
+>
+> **Sources (do not edit — reproduced here verbatim):**
+> - Plan: `plans/plan-w-mr3xban70004446a-2026-07-02.md` (author: Ripley, 2026-07-02)
+> - PRD: `prd/src-2026-07-06.json` (generated by lambert, approved by calebt 2026-07-06)
+
+---
+
+## Goal
+
+Let a single logical live-checkout project (e.g. `src` / Office monorepo) be
+backed by a **pool of live enlistment paths** instead of one `localPath`. Today
+live mode caps mutating dispatch to **one** in-flight operation per project and
+refuses on a dirty tree — even when the operator has a second, equally-valid
+enlistment of the same monorepo (e.g. `C:/office/src` **and** `C:/off2/src`)
+sitting idle. The engine has no way to know about the second checkout, so all
+live dispatches serialize through one path.
+
+With a pool, when a mutating work item is dispatched the engine:
+
+1. Picks any **free** (not currently mid-dispatch) + **clean-tree** enlistment
+   from the pool.
+2. Validates that the specific subproject/subpath the WI needs actually exists
+   in that enlistment (some enlistments may be sparse/partial checkouts).
+3. Dispatches **in-place** in the chosen enlistment, applying today's per-path
+   live-checkout policies (dirty refusal, auto-stash, auto-reset, auto-base-repair)
+   against **that** enlistment only.
+4. If **all** pool members are busy or invalid for the required subpath, falls
+   back to today's behavior: the WI stays pending with a `skipReason` and is
+   retried next tick (no hard failure).
+
+Backward compatibility is a hard requirement: a project with no `livePool` (just
+the singular `localPath`) behaves **exactly** as today. `livePool` is strictly
+additive.
+
+## Codebase Analysis
+
+### How live mode works today (single path)
+
+- **Config shape.** A project opts into live mode with `checkoutMode: 'live'`
+  and a single `localPath`. Example `src` in `config.json`:
+  `{ name:'src', localPath:'C:/office/src', checkoutMode:'live', … }`
+  (source: `config.json` → projects[] `src`).
+- **Mode resolution.** `shared.resolveCheckoutMode(project, workItemType)`
+  returns `'live'|'worktree'`, honoring the legacy `worktreeMode` field and the
+  `liveValidation` hybrid routing (source: `engine/shared.js:2911`).
+  `shared.isLiveCheckoutProject(project)` is the convenience predicate
+  (source: `engine/shared.js:2943`).
+- **Path resolution.** `shared.resolveSpawnPaths(project, type, minionsDir, opts)`
+  short-circuits for live mode and returns
+  `{ cwd: path.resolve(project.localPath) (+workdir), worktreeRootDir:null, liveMode:true }`
+  (source: `engine/shared.js:6355-6382`). It throws `LIVE_CHECKOUT_NO_LOCALPATH`
+  if `localPath` is falsy. **This is the single point where the enlistment path
+  is chosen** — it hard-reads `project.localPath`.
+- **Per-project mutating-concurrency cap of 1.** The allocation loop in the
+  engine builds an in-memory `liveProjectsInUse` **Set of project names**, seeded
+  from `dispatch.active` each tick, and skips any pending mutating item whose
+  project is already in the set with `_pendingReason = 'live_checkout_busy'`
+  (source: `engine.js:10604-10613` seed, `engine.js:10767-10797` gate,
+  `engine.js:10861-10897` skip-reason annotation). Read-only types
+  (`READ_ONLY_ROOT_TASK_TYPES`) are excluded. **This cap survives restart because
+  it is derived from `dispatch.active`, which is SQL-backed** (see persistence
+  below). The pool needs this to become a **per-path** claim, not per-project.
+- **In-place checkout + recovery policies.** `spawnAgent` (engine.js) calls
+  `engine/live-checkout.js#prepareLiveCheckout({ localPath: cwd, branchName, … })`
+  which: runs `git status --porcelain` (dirty gate), mid-operation / detached-HEAD
+  preflight, stale-base guard, and branch checkout/creation — all against the one
+  `cwd` (source: `engine.js:2453-2497`, `engine/live-checkout.js:374`). The dirty
+  recovery policies resolve per-project-then-fleet-wide:
+  - `liveCheckoutAutoStash` — `resolveLiveCheckoutAutoStash` (source: `engine/live-checkout.js:1248`), applied via `applyLiveCheckoutAutoStash` (source: `engine.js:2509`).
+  - `liveCheckoutAutoReset` — `shared.resolveLiveCheckoutAutoReset` (self-resolves by matching project on `localPath`, source: `docs/live-checkout-mode.md` §2b, `engine/live-checkout.js:332`).
+  - `liveCheckoutAutoBaseRepair` — `_defaultResolveAutoBaseRepair` (source: `engine/live-checkout.js:352`).
+  **All three resolve/match by `localPath`**, so they need to key off the
+  selected enlistment path, not the project's canonical `localPath`.
+- **Dispatch-end restore.** `restoreLiveCheckoutAtDispatchEnd` /
+  `maybeRestoreLiveCheckoutFromRecord` put the tree back on `originalRef`
+  (source: `engine/live-checkout.js:1009, 1423`). These operate on a recorded
+  `localPath` and must record/restore the **selected** enlistment.
+
+### Persistence (survives restart)
+
+- Dispatch state lives in **SQLite** `engine/state.db` `dispatches` table via
+  `engine/dispatch-store.js` (`readDispatchSectioned` / `applyDispatchMutation`),
+  mirrored read-only to `dispatch.json` (source: `engine/dispatch-store.js:49,244,298`).
+  Each active dispatch is one JSON record. **Because `liveProjectsInUse` is
+  rebuilt from `dispatch.active` every tick, recording the claimed enlistment
+  path on the active dispatch record makes the per-path claim automatically
+  restart-durable** — no new table strictly required. The claim field (e.g.
+  `meta.liveEnlistmentPath`) rides on the existing record and is diffed/persisted
+  by `applyDispatchMutation` like any other field.
+
+### Subproject / subpath declaration (already partially exists)
+
+- `meta.workdir` is already a validated relative-POSIX subpath under the spawn
+  base; when set, the engine lands the agent at `<base>/<workdir>` and clips
+  harness discovery to that subtree (source: `engine/shared.js:6404-6416`,
+  `validateWorkItemWorkdir`). This is the natural signal for "which subpath does
+  this WI need" — subproject validation can reuse/extend it. There is also
+  `detectDominantSubproject({ projectPath, changedPaths })` used post-completion
+  (source: `engine.js:4033`).
+
+### Dashboard / Settings surfaces (parity requirement)
+
+- **Config-mirror API.** `dashboard.js` `mergeSettingsConfigUpdate` mirrors each
+  per-project field (`mainBranch`, `checkoutMode`, `liveCheckoutAutoStash`,
+  `liveValidation`) from the validated candidate to `current` with
+  present→copy / absent→delete semantics (source: `dashboard.js:415-467`).
+  **Any new `livePool` field must be added here or it is silently dropped.**
+- **Settings UI.** `dashboard/js/settings.js` renders the per-project checkout-mode
+  dropdown, the `liveCheckoutAutoStash` tri-state, and `localPath` display
+  (source: `dashboard/js/settings.js:262-316`). The pool editor lives here.
+- **Project cards.** `dashboard/js/render-other.js` renders per-project git
+  branch/dirty/state pills from `p.gitBranch/p.gitDirty/p.gitState`
+  (source: `dashboard/js/render-other.js:103-172`), fed by the per-`localPath`
+  git-status probe cache in `engine/queries.js:2512-2607` (15s TTL, keyed by
+  normalized `localPath`). Per-enlistment status reuses this probe per path.
+- **Status payload.** `dashboard.js:2768-2785` emits `checkoutMode`,
+  `liveValidationType`, etc. per project — the place to add pool-member status.
+
+### Tests
+
+- Rich existing suite under `test/unit/` — `resolve-spawn-paths-live-mode.test.js`,
+  `prepare-live-checkout.test.js`, `spawn-agent-live-mode-wiring.test.js`,
+  `live-checkout-same-tick-concurrency.test.js`, `live-checkout-mutex-issue518.test.js`,
+  `live-checkout-auto-stash.test.js`, `live-checkout-auto-reset.test.js`,
+  `live-validation-config.test.js`. These are the templates for the new tests and
+  the regression guard for back-compat. `prepareLiveCheckout` and the resolvers
+  already take injectable `_git`/`_exists`/`autoReset` seams for filesystem-free
+  unit tests — the pool selector should follow the same DI style.
+
+## Approach (scope & design)
+
+**Core idea:** introduce a small, pure **pool-selection module** that, given a
+project + the set of currently-claimed enlistment paths + the required subpath,
+returns the chosen free/clean/valid enlistment (or `null`). Thread the chosen
+path through the existing single-path machinery by treating it as the effective
+`localPath` for that one dispatch. Everything downstream of "which path" stays
+unchanged — it just receives the selected path instead of `project.localPath`.
+
+Key design decisions and rationale:
+
+1. **`livePool` is additive; `localPath` stays canonical.** New optional field
+   `project.livePool: [{ path, label?, sparseScope?: string[] }]`. When absent or
+   empty → **current behavior, unchanged** (single `localPath`). When present, the
+   effective pool is `livePool` (and `localPath` MAY be included as an implicit
+   first member for zero-config migration — decided in item 1). Rationale: keeps
+   the entire non-pool codepath byte-identical, satisfying the hard back-compat
+   requirement, and lets `resolveCheckoutMode` / `isLiveCheckoutProject` stay
+   untouched (pool is orthogonal to mode).
+
+2. **Per-path claim replaces per-project Set.** Change the engine's
+   `liveProjectsInUse` (Set<projectName>) into a claim map keyed by
+   `projectName + '\u0000' + enlistmentPath`, seeded from `dispatch.active` by
+   reading each active dispatch's recorded `meta.liveEnlistmentPath` (falling back
+   to `project.localPath` for legacy single-path active dispatches). Rationale:
+   reuses the existing restart-durable derivation (no new SQL table), and a
+   single-path project degenerates to exactly one key = today's cap-of-1.
+
+3. **Selection happens at allocation, is recorded on the WI/dispatch meta, and
+   is consumed by `resolveSpawnPaths`.** The allocation loop selects the
+   enlistment and stamps `item.meta.liveEnlistmentPath`; `resolveSpawnPaths`
+   (and `spawnAgent`'s `prepareLiveCheckout` call) prefer
+   `meta.liveEnlistmentPath` over `project.localPath` when set. Rationale: keeps
+   selection in the one place that already reasons about cross-tick/within-tick
+   claims (the branch-mutex + live-busy gate), and makes the claim durable via the
+   dispatch record before the agent spawns, closing the double-claim window.
+
+4. **Clean-tree + subpath validation at selection are cheap.** Clean-tree reuses
+   the existing 15s-TTL per-path git-status probe cache (`engine/queries.js`), so
+   selection does not add a fresh `git status` per tick per path. Subpath
+   validation is a pure `fs.existsSync(<path>/<subpath>)` (or a `sparseScope`
+   prefix match when declared) — no build, no git. Rationale: selection runs every
+   tick; it must be O(cheap). The authoritative dirty gate still runs inside
+   `prepareLiveCheckout` at spawn against the **selected** path (defense in depth).
+
+5. **Per-enlistment recovery policies.** `resolveLiveCheckoutAutoReset` /
+   `resolveLiveCheckoutAutoStash` / `resolveLiveCheckoutAutoBaseRepair` currently
+   match the project by `localPath`; they must match/apply against the **selected
+   enlistment path**. Rationale: auto-stash/reset must touch only the chosen
+   enlistment, never a sibling.
+
+6. **Mid-dispatch subpath race fails non-retryably.** If a chosen enlistment
+   passes selection-time subpath validation but the subpath is gone by spawn
+   (manual repo edit / sparse re-checkout race), fail with a dedicated
+   `FAILURE_CLASS.LIVE_POOL_SUBPATH_MISSING` (added to `dispatch.js` `neverRetry`)
+   rather than silently re-picking mid-dispatch. Rationale: matches the existing
+   `LIVE_CHECKOUT_*` structural-failure pattern (blob-fetch, worktree-conflict) —
+   deterministic, operator-actionable, no retry storm.
+
+7. **Selection order is deterministic: first-free-clean-valid in `livePool`
+   declaration order** (with `localPath` implicit-first if adopted). Rationale:
+   simplest correct, predictable, and directly testable; round-robin adds state
+   with no real benefit at the expected pool size (2–3). Documented explicitly so
+   behavior is a contract.
+
+---
+
+## Work items (from PRD `prd/src-2026-07-06.json`)
+
+The approved PRD breaks the feature into 10 items. `depends_on` uses the PRD item
+ids; complexity is the PRD's `estimated_complexity`.
+
+| # | id | Title | Type | Depends on | Complexity |
+|---|----|-------|------|-----------|-----------|
+| 1 | `P-a1c3f2b9` | livePool config schema + validation + normalization | implement | — | medium |
+| 2 | `P-b7d4e0a1` | Pure pool-selection module (`engine/live-pool.js`) | implement | `P-a1c3f2b9` | medium |
+| 3 | `P-c2e8f5d3` | Thread selected enlistment path through spawn-path resolution | implement | `P-a1c3f2b9` | medium |
+| 4 | `P-e5a9b2c7` | Per-path claim gate in the allocation loop | implement | `P-b7d4e0a1`, `P-c2e8f5d3` | large |
+| 5 | `P-f8b1a4d6` | Per-enlistment recovery policy resolution | implement | `P-c2e8f5d3` | medium |
+| 6 | `P-a0d7c3e9` | Mid-dispatch subpath-missing failure class | implement | `P-c2e8f5d3`, `P-e5a9b2c7` | small |
+| 7 | `P-d4f0b8a2` | Settings UI: pool editor + config-mirror wiring | implement | `P-a1c3f2b9` | large |
+| 8 | `P-c9e2a6f4` | Dashboard project card: per-enlistment status | implement | `P-e5a9b2c7` | medium |
+| 9 | `P-b3a7d1c8` | Docs + CLAUDE.md pool contract | docs | `P-a1c3f2b9`, `P-e5a9b2c7`, `P-f8b1a4d6`, `P-a0d7c3e9` | small |
+| 10 | `P-e1c5b9a3` | Worked back-compat + example config regression test | test | `P-e5a9b2c7`, `P-f8b1a4d6` | small |
+
+### Open questions (from the PRD)
+
+1. **Subpath declaration source:** should the PRD add an explicit `meta.subpath`
+   field, or is the existing `meta.workdir` sufficient for the driving Loop-Android
+   use case? (Plan recommends reusing `meta.workdir`; add `meta.subpath` only if a
+   WI needs a validation subpath differing from where the agent lands.)
+2. **localPath auto-prepend:** should a project's existing `localPath` be an
+   implicit first pool member when `livePool` is set (safest for migration), or
+   must the operator list it explicitly? (Plan recommends implicit-first + dedup —
+   this PRD assumes yes.)
+3. **Clean-tree probe staleness:** the 15s-TTL probe could claim a path that just
+   went dirty; the authoritative gate in `prepareLiveCheckout` catches it at spawn
+   (refuse/auto-stash/auto-reset) at the cost of an occasional wasted selection.
+   Confirm this trade-off vs. a fresh probe at selection.
+4. **Second enlistment on a different base branch:** pool selection does not
+   normalize branches across members; the existing stale-base guard applies per
+   selected path. Confirm this is acceptable operator responsibility.

package/engine/kb-sweep.js

@@ -83,6 +83,67 @@ function _pruneOldSwept() {
   return pruned;
 }
 
+/**
+ * Resolve the effective per-category age-TTL map (category → days), merging
+ * `opts.engineConfig.kbCategoryTtlDays` over `ENGINE_DEFAULTS.kbCategoryTtlDays`.
+ * Only positive finite day-counts survive — a category set to 0, negative, or a
+ * non-number is dropped (expiry disabled for it). Durable categories that appear
+ * in neither map are simply absent → never age-expired.
+ */
+function _resolveTtlByCategory(opts = {}) {
+  const defaults = (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.kbCategoryTtlDays) || {};
+  const override = (opts.engineConfig && opts.engineConfig.kbCategoryTtlDays) || {};
+  const merged = { ...defaults, ...override };
+  const out = {};
+  for (const [cat, days] of Object.entries(merged)) {
+    const n = Number(days);
+    if (Number.isFinite(n) && n > 0) out[cat] = n;
+  }
+  return out;
+}
+
+/**
+ * Age of a manifest entry in ms. Prefers the authored date (`entry.date`, from
+ * the filename `YYYY-MM-DD-` prefix / frontmatter) so age is immune to the
+ * rewrite pass touching mtime; falls back to mtime. Unknown age → 0 (fresh,
+ * never expired) so a malformed/date-less entry is never archived by age alone.
+ */
+function _entryAgeMs(entry, now) {
+  const parsed = typeof entry.date === 'string' && entry.date ? Date.parse(entry.date) : NaN;
+  if (Number.isFinite(parsed)) return Math.max(0, now - parsed);
+  if (Number.isFinite(entry.mtimeMs) && entry.mtimeMs > 0) return Math.max(0, now - entry.mtimeMs);
+  return 0;
+}
+
+/**
+ * Age-based TTL expiry pass. Archives (to knowledge/_swept/) manifest entries in
+ * a TTL-listed category whose age exceeds that category's TTL. Durable categories
+ * (absent from the TTL map) are never touched. Pinned entries are already
+ * excluded upstream (they never enter the manifest), and knowledge/agents/ is
+ * never scanned into the manifest at all — so per-agent memory is inherently safe.
+ *
+ * @returns {{ expired:number, survivors:object[] }}
+ */
+function _expireByAge(manifest, opts = {}) {
+  const ttlByCategory = _resolveTtlByCategory(opts);
+  if (Object.keys(ttlByCategory).length === 0) return { expired: 0, survivors: manifest.slice() };
+  const now = Number(opts.now) || Date.now();
+  const DAY_MS = 24 * 60 * 60 * 1000;
+  let expired = 0;
+  const survivors = [];
+  for (const e of manifest) {
+    const ttlDays = ttlByCategory[e.category];
+    if (!ttlDays) { survivors.push(e); continue; }
+    if (_entryAgeMs(e, now) <= ttlDays * DAY_MS) { survivors.push(e); continue; }
+    const fp = path.join(KB_DIR, e.category, e.file);
+    if (!fs.existsSync(fp)) continue; // already removed by an earlier pass
+    if (opts.dryRun) { expired++; continue; }
+    if (_archiveKbFile(fp, `age-expired: ${e.category} entry older than ${ttlDays}d`)) expired++;
+    else survivors.push(e); // archive failed — keep it visible
+  }
+  return { expired, survivors };
+}
+
 /** Group entries by content hash, keep most-recent per group. Cheap, no LLM. */
 function _hashDedup(manifest, opts = {}) {
   const groups = new Map(); // hash → entries[]
@@ -478,6 +539,7 @@ async function _runKbSweepImpl(opts = {}) {
     hashDuplicatesArchived: 0,
     llmDuplicatesArchived: 0,
     staleRemoved: 0,
+    ageExpired: 0,
     reclassified: 0,
     rewritten: 0,
     rewriteBytesBefore: 0,
@@ -526,8 +588,17 @@ async function _runKbSweepImpl(opts = {}) {
   summary.staleRemoved = llmActions.removed;
   summary.reclassified = llmActions.reclassified;
 
+  // 2.5. Age-based TTL expiry (W-mr48yth5) — archive transient-category entries
+  // older than their per-category TTL to knowledge/_swept/. This is the pass that
+  // keeps PR/incident-scoped one-off notes (project-notes, build-reports, reviews)
+  // from accumulating indefinitely — dedup/rewrite can't reclaim them because each
+  // is unique by PR#/date. Durable categories (no TTL) are untouched.
+  const survivingAfterLlm = afterHash.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
+  const ageResult = _expireByAge(survivingAfterLlm, opts);
+  summary.ageExpired = ageResult.expired;
+
   // 3. Per-entry rewrite (compress + normalize)
-  // Filter to entries that survived hash + LLM passes (still on disk)
+  // Filter to entries that survived hash + LLM + age passes (still on disk)
   const stillOnDisk = afterHash.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
   const rewriteResult = await _rewritePass(stillOnDisk, callLLM, trackEngineUsage, opts);
   summary.rewritten = rewriteResult.processed;
@@ -549,7 +620,7 @@ async function _runKbSweepImpl(opts = {}) {
   }
 
   summary.durationMs = Date.now() - t0;
-  summary.summary = `${summary.hashDuplicatesArchived} hash-dup, ${summary.llmDuplicatesArchived} llm-dup, ${summary.staleRemoved} stale, ${summary.reclassified} reclassified, ${summary.rewritten} rewritten (${(summary.bytesBefore - summary.bytesAfter).toLocaleString()} bytes saved)`;
+  summary.summary = `${summary.hashDuplicatesArchived} hash-dup, ${summary.llmDuplicatesArchived} llm-dup, ${summary.staleRemoved} stale, ${summary.ageExpired} age-expired, ${summary.reclassified} reclassified, ${summary.rewritten} rewritten (${(summary.bytesBefore - summary.bytesAfter).toLocaleString()} bytes saved)`;
 
   if (!opts.dryRun) {
     try { shared.mutateKbSwept(() => ({ timestamp: ts(), summary: summary.summary, detail: summary })); } catch { /* ignore */ }
@@ -706,6 +777,9 @@ module.exports = {
   _parseFrontmatter,
   _serializeFrontmatter,
   _hashDedup,
+  _expireByAge,
+  _entryAgeMs,
+  _resolveTtlByCategory,
   _archiveKbFile,
   COMPRESS_THRESHOLD_BYTES,
   SWEPT_FLAG_KEY,

package/engine/shared.js

@@ -3155,6 +3155,22 @@ const ENGINE_DEFAULTS = {
   // & Review Loop, or set `engine.autoFixPaused: true` in config.json.
   autoFixPaused: false, // hard-stop kill-switch / master override (see comment above)
   autoConsolidateMemory: false, // opt-in: periodically spawn engine/kb-sweep-runner.js from the tick loop (4h cadence). Inbox→notes consolidation already runs every tick via consolidateInbox; this flag only controls the KB sweep.
+  // W-mr48yth5 — per-category age-based TTL (in days) for the KB sweep's expiry
+  // pass. During runKbSweep, an entry in a listed category whose authored date
+  // (filename `YYYY-MM-DD-` prefix, falling back to file mtime) is older than
+  // its TTL is archived to knowledge/_swept/ (recoverable — pruned after 30d by
+  // the existing _pruneOldSwept pass). Transient, PR/incident-scoped categories
+  // accumulate one-off notes that hash-dedup / LLM-dedup / rewrite can never
+  // reclaim (each is unique by PR#/date), so they get finite TTLs; durable
+  // categories (architecture, conventions) and per-agent memory (knowledge/agents/,
+  // never scanned by the sweep) are intentionally omitted → never age-expired.
+  // config.engine.kbCategoryTtlDays is merged over these defaults; set a category
+  // to 0 (or omit it) to disable expiry for that category.
+  kbCategoryTtlDays: {
+    'project-notes': 21,
+    'build-reports': 14,
+    'reviews': 30,
+  },
   // W-mqtvnnj1000357fa — fleet-wide fallback for live-checkout auto-stash. When
   // true, a dirty live-checkout tree is `git stash push --include-untracked`'d
   // before dispatch instead of failing with FAILURE_CLASS.LIVE_CHECKOUT_DIRTY,

package/engine.js

@@ -10645,55 +10645,84 @@ async function tickInner() {
 
   // Dispatch items — spawnAgent moves each from pending→active on disk.
   // We use the already-loaded item objects; spawnAgent handles the state transition.
+  //
+  // W-mr9o1oe0001c4601 — Spawn all claimed items for this tick CONCURRENTLY
+  // rather than awaiting each spawnAgent serially. `spawnAgent` does real
+  // wall-clock work per item (prompt build + `git worktree add`, which on a
+  // ~250k-file monorepo can take multiple seconds), so the old sequential loop
+  // made eager routing (engine/routing.js already fans work across every idle
+  // agent in a single allocation pass) visibly "trickle in" one agent at a time,
+  // contradicting the stated eager-dispatch design. `toDispatch` is already
+  // bounded by `slotsAvailable` (≤ maxConcurrent — the seed loop above decrements
+  // `generalSlots` and stops pushing at 0), so an unbounded Promise.allSettled
+  // here is naturally capped; no dedicated spawn-concurrency knob is needed.
+  // Concurrent `git worktree add` against the same repo is safe on this codebase:
+  // each worktree gets its own `.git/worktrees/<name>` metadata dir, and
+  // runWorktreeAdd already retries the exact lock-contention errors
+  // (`index.lock`, `could not lock`, `resource busy`, `already exists`) that
+  // concurrent adds can transiently produce. The per-project live-checkout gate
+  // (liveProjectsInUse) already caps live-mode projects to one mutating dispatch,
+  // so concurrent in-place writes to one operator checkout cannot happen here.
   const dispatched = new Set();
-  for (const item of toDispatch) {
-    if (!dispatched.has(item.id)) {
-      let proc;
-      try { proc = await spawnAgent(item, config); } catch (spawnErr) {
-        log('error', `spawnAgent exception for ${item.id}: ${spawnErr.message}`);
-        proc = null;
-      }
-      if (_isTickStale(myGeneration)) return;
-      if (proc === null) {
-        // spawnAgent failed (e.g., worktree creation error). It already called
-        // completeDispatch internally which handles retry logic, but log at the
-        // dispatch-loop level for visibility and handle any edge cases where
-        // completeDispatch wasn't called.
-        log('error', `spawnAgent returned null for ${item.id} (${item.type} → ${item.agent}) — spawn failed`);
-        // Defensive: ensure the work item is re-queued if completeDispatch didn't fire
-        if (item.meta?.item?.id) {
-          try {
-            const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
-              ? path.join(ENGINE_DIR, '..', 'work-items.json')
-              : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
-            if (wiPath) {
-              if (_isTickStale(myGeneration)) return;
-              mutateWorkItems(wiPath, items => {
-                const wi = items.find(i => i.id === item.meta.item.id);
-                if (wi && wi.status === WI_STATUS.DISPATCHED) {
-                  // completeDispatch didn't update the work item — re-queue manually
-                  wi.status = WI_STATUS.PENDING;
-                  wi._retryCount = (wi._retryCount || 0) + 1;
-                  wi._lastRetryReason = 'spawnAgent returned null';
-                  wi._lastRetryAt = ts();
-                  delete wi.dispatched_at;
-                  delete wi.dispatched_to;
-                  log('info', `Re-queued ${item.meta.item.id} as pending (retry ${wi._retryCount})`);
-                }
-              });
-            }
-          } catch (e) { log('warn', `Failed to re-queue work item after spawn failure: ${e.message}`); }
-        }
-      } else {
-        dispatched.add(item.id);
-        // Sync PRD item status after successful spawn (#480)
-        if (item.meta?.item?.sourcePlan) {
-          try { syncPrdItemStatus(item.meta.item.id, WI_STATUS.DISPATCHED, item.meta.item.sourcePlan); }
-          catch (e) { log('warn', `prd sync after spawn: ${e.message}`); }
-        }
+  const spawnOneItem = async (item) => {
+    // Dedup by id (toDispatch is already deduped by seenPendingIds — defensive).
+    if (dispatched.has(item.id)) return;
+    // Staleness: if a newer tick force-released this one while we were building
+    // the batch, don't spawn a stale tick's agents.
+    if (_isTickStale(myGeneration)) return;
+    let proc;
+    try { proc = await spawnAgent(item, config); } catch (spawnErr) {
+      log('error', `spawnAgent exception for ${item.id}: ${spawnErr.message}`);
+      proc = null;
+    }
+    // A newer tick may have superseded us mid-spawn — don't mutate shared state.
+    if (_isTickStale(myGeneration)) return;
+    if (proc === null) {
+      // spawnAgent failed (e.g., worktree creation error). It already called
+      // completeDispatch internally which handles retry logic, but log at the
+      // dispatch-loop level for visibility and handle any edge cases where
+      // completeDispatch wasn't called.
+      log('error', `spawnAgent returned null for ${item.id} (${item.type} → ${item.agent}) — spawn failed`);
+      // Defensive: ensure the work item is re-queued if completeDispatch didn't fire
+      if (item.meta?.item?.id) {
+        try {
+          const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
+            ? path.join(ENGINE_DIR, '..', 'work-items.json')
+            : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
+          if (wiPath) {
+            if (_isTickStale(myGeneration)) return;
+            mutateWorkItems(wiPath, items => {
+              const wi = items.find(i => i.id === item.meta.item.id);
+              if (wi && wi.status === WI_STATUS.DISPATCHED) {
+                // completeDispatch didn't update the work item — re-queue manually
+                wi.status = WI_STATUS.PENDING;
+                wi._retryCount = (wi._retryCount || 0) + 1;
+                wi._lastRetryReason = 'spawnAgent returned null';
+                wi._lastRetryAt = ts();
+                delete wi.dispatched_at;
+                delete wi.dispatched_to;
+                log('info', `Re-queued ${item.meta.item.id} as pending (retry ${wi._retryCount})`);
+              }
+            });
+          }
+        } catch (e) { log('warn', `Failed to re-queue work item after spawn failure: ${e.message}`); }
+      }
+    } else {
+      dispatched.add(item.id);
+      // Sync PRD item status after successful spawn (#480)
+      if (item.meta?.item?.sourcePlan) {
+        try { syncPrdItemStatus(item.meta.item.id, WI_STATUS.DISPATCHED, item.meta.item.sourcePlan); }
+        catch (e) { log('warn', `prd sync after spawn: ${e.message}`); }
       }
     }
-  }
+  };
+  // Promise.allSettled: one item's spawn failure never affects another's, and
+  // each spawnOneItem already swallows its own errors (per-item try/catch), so a
+  // rejected task here is not expected — allSettled is belt-and-suspenders.
+  await Promise.allSettled(toDispatch.map((item) => spawnOneItem(item)));
+  // A force-release may have superseded this tick while spawns were in flight —
+  // abort before the downstream skip-reason annotation reads/mutates shared state.
+  if (_isTickStale(myGeneration)) return;
 
   // Annotate remaining pending items with skipReason so dashboard can show why they're waiting.
   // Re-read dispatch after spawns (spawnAgent moves items from pending→active).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2338",
+  "version": "0.1.2340",
   "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"