@yemi33/minions 0.1.2427 → 0.1.2429

package/docs/README.md

@@ -66,12 +66,12 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [qa-runbooks.md](qa-runbooks.md) — Per-project QA runbook schema, storage layout (`projects/<name>/runbooks/<id>.json`), CRUD endpoints, run-record lifecycle, and the `qa-validate` agent sidecar contract.
 - [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
 - [runtime-adapters.md](runtime-adapters.md) — Runtime adapter contract (`engine/runtimes/*`): how the engine talks to Claude Code, Copilot CLI, and future CLIs through a single capability-flagged interface.
-- [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop, including structured review learning (durable, opt-in lessons from verified review findings).
+- [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop, including structured review learning (durable, always-on lessons from verified review findings).
 - [shared-lifecycle-module-map.md](shared-lifecycle-module-map.md) — Documentation-only module-boundary audit of `engine/shared.js` / `engine/lifecycle.js`: function inventory, cross-file call graph, and a proposed split map (no code moved).
 - [skills.md](skills.md) — Skill block format: how agents emit reusable `\`\`\`skill` blocks and how the engine extracts them into native personal-skill directories.
 - [slim-ux/concepts.md](slim-ux/concepts.md) — Slim-UX design notes: simplified surface concepts driving the project picker, inline project link, and decoupled folder picker.
 - [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Slim-UX follow-up architecture suggestions paired with `concepts.md`.
-- [team-memory.md](team-memory.md) — End-to-end hybrid memory system: file-backed inputs and consolidation, SQL/FTS5 records, retrieval and fallback, prompt bounds, episodic capture, the review-learning lifecycle (capture/recall/promotion/contradiction/diagnostics) and its staged rollout + rollback, security, APIs, and operations.
+- [team-memory.md](team-memory.md) — End-to-end hybrid memory system: file-backed inputs and consolidation, SQL/FTS5 records, retrieval and fallback, prompt bounds, episodic capture, the review-learning lifecycle (capture/recall/promotion/contradiction/diagnostics) and its rollout history + acceptance measurement, security, APIs, and operations.
 - [timeouts-and-liveness.md](timeouts-and-liveness.md) — What kills (or doesn't kill) a live tracked agent: the wall-clock vs steering kill invariants, spawn-phase watchdog gates, steering safety nets, and stale-orphan detection ladder.
 - [visual-evidence-ci.md](visual-evidence-ci.md) — GitHub Actions before/after dashboard capture: path and label triggers, deterministic base/head fixtures, artifact/comment lifecycle, trust boundary, and local reproduction.
 - [watches.md](watches.md) — Persistent monitoring jobs: target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.

package/docs/completion-reports.md

@@ -195,7 +195,7 @@ These fields do not replace `reviewFindingResolution`. An unchanged
 review-feedback fix must still set `noop: true` and prove the exact trusted
 finding through the stricter no-op contract below.
 
-When `review-learning-capture` is enabled, the engine processes normalized
+The engine processes normalized
 entries only after the completion is otherwise successful and all PR/work-item
 contracts pass. `accepted-fixed` requires verified remote-head advancement or
 an independent approval of the exact current review head.

package/docs/design-state-storage.md

@@ -48,7 +48,9 @@ release .lock file
 Key properties:
 - **Synchronous blocking** — `withFileLock` spins with `sleepMs(25)` until lock acquired or 5s timeout (source: `engine/shared.js` `withFileLock` ~L1329)
 - **Whole-file granularity** — updating one field in one work item rewrites all 180 items (370 KB)
-- **Stale lock recovery** — locks older than 5 min (`LOCK_STALE_MS = 300_000`) are force-removed; holders that recorded a `{pid, ts}` payload are kept alive past the threshold while `process.kill(pid, 0)` succeeds, with a hard last-resort cap at 5×LOCK_STALE_MS (source: `engine/shared.js`, P-b7d4e8f2)
+- **Stale lock recovery** — locks older than 5 min (`LOCK_STALE_MS = 300_000`) are force-removed; holders that recorded a `{pid, ts, token}` payload are kept alive past the threshold while `process.kill(pid, 0)` succeeds, with a hard last-resort cap at 5×LOCK_STALE_MS (source: `engine/shared.js`, P-b7d4e8f2)
+- **Identity-checked reap and release** — every acquisition stamps a unique `token` into the lock payload. Reaping never unlinks the lock path directly: the reaper re-observes the same token after a short grace delay, takes custody with an atomic `rename`, and verifies the quarantined file is the acquisition it judged stale (restoring it otherwise). Release likewise unlinks only while the on-disk token is still ours. Removing a lock by path alone is a TOCTOU that lets a second writer into the critical section and silently loses one update (source: `engine/shared.js` `withFileLock`, W-ms2nbtkj00016ffc)
+- **Compromised sections fail loudly** — if the lock is gone or re-owned when the critical section ends, `withFileLock` throws `ELOCKCOMPROMISED`. `mutateJsonFileLocked` / `mutateTextFileLocked` first re-apply the mutation against the current on-disk state (up to `LOCK_COMPROMISE_REDOS`) when their own write did not survive, so a raced update is recovered rather than dropped
 - **Read caching** — only `dispatch.json` has a 2s TTL cache (source: `engine/queries.js`)
 
 ### 1.3 Read vs Write Ratio

package/docs/security.md

@@ -160,9 +160,11 @@ defenses enforced at the persistence boundary in `engine/review-learning.js`:
   actually showed it, and only within its own project. A forged id, an unshown
   lesson, or a cross-project id is rejected as a diagnostic — it cannot quarantine a
   lesson it was never given.
-- **Flag-gated, capture-only-safe.** Both flags default off; capture-only changes no
-  rendered prompt, and disabling recall is a complete prompt rollback. Stored
-  records stay auditable through the diagnostics endpoints regardless of flag state.
+- **Structurally bounded, not flag-bounded.** Capture and recall are always on;
+  their safety comes from the constraints above (verified findings only,
+  project-scoped byte-capped recall, trusted-trace binding, reversible
+  quarantine), not from a switch. Stored records stay auditable through the
+  diagnostics endpoints.
 - **Injection-flag / nonce gates still apply.** A completion flagged
   `failure_class: "injection-flagged"` or failing the nonce check never reaches
   review-learning capture or application processing.

package/docs/self-improvement.md

@@ -161,7 +161,7 @@ in the future, avoid the patterns flagged here.
 
 Without this, review findings only exist in the inbox file under the reviewer's name. The author never explicitly sees them unless they happen to read the consolidated notes.md. The feedback loop ensures the author gets a direct, targeted learning from every review.
 
-### 3a. Structured review learning (durable, opt-in)
+### 3a. Structured review learning (durable, always-on)
 
 The narrative feedback file above is per-PR and consolidated into free-text notes.
 **Review learning** is its durable, structured evolution: a verified reviewer
@@ -174,11 +174,11 @@ deterministically. It is fully specified in
   and a stable finding key `<project>|<canonical-pr-id>|<host-namespaced-source-key>`.
   They are globally excluded from generic FTS recall and only surface through the
   dedicated project-scoped path.
-- **Capture.** With `review-learning-capture` on, only a completed Minions
+- **Capture.** Only a completed Minions
   `changes-requested` verdict creates an unresolved *candidate*; a verified
   `accepted-fixed` / `satisfied-elsewhere` disposition promotes it to one active
   lesson. Invalid/stale/deferred close or hold the candidate.
-- **Recall.** With `review-learning-recall` on, a dispatch with a resolved project
+- **Recall.** A dispatch with a resolved project
   recalls up to 4 records / 4 KiB as a separately fenced `## Applicable Prior Review
   Lessons` section, ranked by exact symbol → file → tag overlap.
 - **Application, correction, supersession.** Agents report `applied` /
@@ -189,11 +189,12 @@ deterministically. It is fully specified in
 - **Promotion.** A high-confidence, repeatedly observed lesson can be human-promoted
   into repository guidance (`CLAUDE.md` / `AGENTS.md` / Copilot instructions or a
   project skill) via a normal PR — never by editing a checkout.
-- **Diagnostics, retention & rollback.** Retrieval decisions, a lifecycle timeline,
-  rollout aggregates, and the staged-rollout comparison are exposed under
-  `/api/memory-records/*`. Both flags default off and expire 2027-01-31; disabling
-  recall is a complete prompt rollback (see
-  [team-memory.md → Staged rollout and acceptance](team-memory.md#staged-rollout-and-acceptance)).
+- **Diagnostics & retention.** Retrieval decisions, a lifecycle timeline,
+  rollout aggregates, and the rollout comparison are exposed under
+  `/api/memory-records/*`. Capture and recall are unconditional — the temporary
+  `review-learning-capture` / `review-learning-recall` flags were removed once
+  the staged rollout completed (see
+  [team-memory.md → Rollout history and acceptance](team-memory.md#rollout-history-and-acceptance)).
 
 ## 4. Human Feedback on PRs
 

package/docs/team-memory.md

@@ -272,7 +272,7 @@ Migration 027 adds the storage foundation for review-derived procedural memory:
   replace the hash.
 - Human-feedback fix dispatches snapshot that bounded source list in
   `meta.commentSources`, including contexts coalesced during cooldown.
-- When `review-learning-capture` is enabled, only a completed Minions
+- Only a completed Minions
   `changes-requested` verdict creates an unresolved candidate. Review identity,
   project, canonical PR, configured author, reviewer, dispatch, source item,
   and a source hash are persisted; the raw review note remains only in its
@@ -378,7 +378,7 @@ and they are **globally excluded** from the generic FTS pack
 (`searchMemoryRecords` drops `source_type='review-learning'` unless a caller
 passes `includeReviewLearning`, which only the operator dashboard search does).
 
-When `features.review-learning-recall` is on and a dispatch has a resolved
+When a dispatch has a resolved
 project context, the path:
 
 1. lists active project-scoped lessons straight from the review-learning index
@@ -399,9 +399,8 @@ Each run records bounded telemetry through `recordRetrievalRun` with
 `retrieval_kind='review-learning'`, the dispatch and work-item ids, selected
 record ids, per-record scores, and reason codes (`exact-symbol`, `exact-file`,
 `exact-tag`, `lexical`, `not-applicable`, `record-cap`, `byte-cap`) — never any
-prompt or comment body. With recall off (capture-only), the rendered prompt is
-unchanged with respect to review-learning records, and projectless Command
-Center / unrelated central work receive no section.
+prompt or comment body. Projectless Command Center / unrelated central work
+receive no section.
 
 ## Prompt assembly and fallback
 
@@ -412,8 +411,8 @@ appends memory context in this order:
 2. Either **Relevant Memory** or the legacy pair:
    - **Team Notes** from `notes.md`;
    - **Personal Memory** from `knowledge/agents/<agentId>.md`.
-3. **Applicable Prior Review Lessons**, when `review-learning-recall` is on, the
-   dispatch has a project, and at least one applicable lesson exists (bounded and
+3. **Applicable Prior Review Lessons**, when the
+   dispatch has a project and at least one applicable lesson exists (bounded and
    fenced independently of the generic memory budget).
 4. Later non-memory appendices such as propagated project instructions.
 
@@ -498,8 +497,6 @@ completion result.
 | Key | Default | Purpose |
 |-----|---------|---------|
 | `features.memoryRetrieval` | `true` | Enables structured retrieval. Feature resolution is environment override, then `config.features`, then registry default. |
-| `features.review-learning-capture` | `false` | Temporary gate for capturing verified review-learning candidates and lessons. |
-| `features.review-learning-recall` | `false` | Temporary independent gate for the dedicated review-learning recall path. |
 | `engine.memoryRetrievalShadowMode` | `false` | Measure retrieval without replacing legacy prompt memory. |
 | `engine.memoryRetrievalTopK` | `8` | Maximum selected records. |
 | `engine.memoryRetrievalMaxBytes` | `8192` | UTF-8 byte budget for selected record blocks. |
@@ -513,52 +510,41 @@ completion result.
 | `engine.agentMemorySummaryDays` | `30` | Age trigger for summary eligibility. |
 
 Feature flags are exposed by the generic Dashboard **Settings > Features**
-surface. The two review-learning flags expire on 2027-01-31 and default off, so
-the migration alone changes no prompt. Settings also exposes shadow mode,
-episodic capture, retrieval bounds, the inbox threshold, and automatic KB sweep.
-The personal-file window and summary keys are configuration-only today.
-
-Environment overrides are `MINIONS_FEATURE_MEMORYRETRIEVAL=1|0`,
-`MINIONS_FEATURE_REVIEW_LEARNING_CAPTURE=1|0`, and
-`MINIONS_FEATURE_REVIEW_LEARNING_RECALL=1|0`.
-
-## Staged rollout and acceptance
-
-Review-learning ships behind two independent, default-off flags so the schema,
-capture, recall, promotion, contradiction, and diagnostics code can all land on
-`main` without changing a single rendered prompt. The rollout is deliberately
-staged and measured; do not skip stages.
-
-### Stage 0 — flags off (baseline behaviour)
-
-With both `review-learning-capture` and `review-learning-recall` off:
-
-- No candidate or lesson is captured; a `changes-requested` review completion is
-  handled exactly as before.
-- No `## Applicable Prior Review Lessons` section is ever rendered, so the review,
-  fix, re-review, memory, comment-poller, and dashboard flows are byte-for-byte
-  identical to the pre-feature engine.
-- `processReviewLearningApplications` short-circuits (recall gate), so an agent's
-  `reviewLearningApplications` payload is ignored and no lesson is mutated.
-- Any records that already exist in SQL (e.g. from a prior enabled window or the
-  offline backfill) stay fully auditable through the diagnostics endpoints; only
-  prompt injection is gated, never storage or inspection.
-
-### Stage 1 — capture-only for 30 days
-
-Enable `review-learning-capture` only (recall stays off). This is the measurement
-baseline: verified findings become candidates and lessons and accrue `created`,
-`retrieved`-less, and `repeated-finding` lifecycle events, but **no lesson is ever
-injected into a prompt**. Capture-only changes no rendered prompt. Run this for at
-least 30 days to collect a per-project, per-normalized-area baseline recurrence
-rate (the share of resolved valid findings that recurred).
+surface. Settings also exposes shadow mode, episodic capture, retrieval bounds,
+the inbox threshold, and automatic KB sweep. The personal-file window and summary
+keys are configuration-only today.
+
+Review-learning capture and recall are **not** flagged — they graduated to
+always-on behaviour and have no config or environment override. Their bounds are
+structural, not switchable: capture only accepts verified findings, recall is
+project-scoped and byte-bounded, contradictions are quarantined reversibly, and
+review-learning records are globally excluded from generic FTS retrieval.
+
+The environment override for structured retrieval is
+`MINIONS_FEATURE_MEMORYRETRIEVAL=1|0`.
+
+## Rollout history and acceptance
+
+Review-learning shipped behind two independent, default-off flags
+(`review-learning-capture`, `review-learning-recall`) so the schema, capture,
+recall, promotion, contradiction, and diagnostics code could all land on `main`
+without changing a single rendered prompt. That staged rollout is **complete**:
+both flags were removed and the behaviour is now unconditional. The stages below
+are retained as history and as the shape of the acceptance measurement, which is
+still exposed by the diagnostics endpoints.
+
+### Stage 1 — capture-only measurement window
+
+Capture ran alone (recall still gated off): verified findings became candidates
+and lessons and accrued `created` and `repeated-finding` lifecycle events, but no
+lesson was injected into a prompt. That window is the recurrence baseline — a
+per-project, per-normalized-area share of resolved valid findings that recurred.
 
 ### Stage 2 — one-project recall canary
 
-Enable `review-learning-recall` for a **single project** (per-project
-`config.features` override or the `MINIONS_FEATURE_REVIEW_LEARNING_RECALL` env
-override on that project's engine). Recall now injects at most 4 records / 4 KiB of
-bounded, fenced lessons on dispatches in that project. Watch the canary for:
+Recall was enabled for a single project. Recall injects at most 4 records / 4 KiB
+of bounded, fenced lessons on dispatches in that project. The canary was watched
+for:
 
 - contradiction alerts (`review-learning-contradiction` inbox notes) — an
   evidence-backed contradiction quarantines the offending lesson automatically;
@@ -566,7 +552,7 @@ bounded, fenced lessons on dispatches in that project. Watch the canary for:
   confirm lessons are selected for the right file/symbol reasons; and
 - the recurrence rate for the canary project's first 30 active days.
 
-### Expansion criteria (the success gate)
+### The success gate (still live)
 
 `GET /api/memory-records/rollout-comparison`
 (`memoryStore.getReviewLearningRolloutComparison`) compares the **30-day
@@ -576,23 +562,18 @@ grouped by project and normalized area. It only reports `status: "success"` for
 (`minimumSample`, default 20 — otherwise `status: "insufficient-sample"`) **and**
 the repeated valid-finding rate fell by at least `minReduction` (default `0.25` =
 25%). A zero baseline rate is reported as `no-improvement`, never a divide-by-zero
-success. Do not broaden the recall canary to another project until its comparison
-row reports `success`.
-
-### Immediate prompt rollback
-
-Recall is a pure prompt-injection layer, so rolling it back is instant and total:
-
-1. Set `config.features["review-learning-recall"] = false` (or
-   `MINIONS_FEATURE_REVIEW_LEARNING_RECALL=0`). The very next dispatch renders no
-   `## Applicable Prior Review Lessons` section — disabling recall is a complete
-   prompt rollback.
-2. Optionally set `config.features["review-learning-capture"] = false` to stop
-   accruing new candidates/lessons. Existing records remain in SQL and stay
-   auditable through the diagnostics endpoints; nothing is deleted.
-
-No migration, restart-ordering, or data cleanup is required to roll back — the flags
-gate prompt behaviour, not storage.
+success. The comparison endpoint remains the way to measure review-learning's
+effect per project and area now that the behaviour is always on.
+
+### Reverting is a code change, not a switch
+
+There is no flag to flip any more. Both capture and recall are unconditional, so
+backing the behaviour out means reverting the graduation commit. What has not
+changed is that recall is a pure prompt-injection layer over storage: a revert
+stops candidates accruing and stops the `## Applicable Prior Review Lessons`
+section rendering, but every existing record stays in SQL and stays auditable
+through the diagnostics endpoints. Nothing is deleted, and no migration,
+restart-ordering, or data cleanup is involved.
 
 ### Promotion into repository guidance
 

package/engine/features.js

@@ -102,18 +102,6 @@ const FEATURES = {
     addedIn: '0.1.2233',
     expires: '2027-01-31',
   },
-  'review-learning-capture': {
-    description: 'Capture verified code-review findings as bounded, project-scoped review-learning candidates and procedural lessons.',
-    default: false,
-    addedIn: '0.1.2203',
-    expires: '2027-01-31',
-  },
-  'review-learning-recall': {
-    description: 'Recall bounded applicable review lessons through the dedicated project-scoped review-learning path.',
-    default: false,
-    addedIn: '0.1.2203',
-    expires: '2027-01-31',
-  },
 };
 
 const ENV_TRUTHY = new Set(['1', 'true', 'on', 'yes']);

package/engine/lifecycle.js

@@ -17,7 +17,6 @@ const harness = require('./harness');
 const reviewLearning = require('./review-learning');
 const smallStateStore = require('./small-state-store');
 const prdStore = require('./prd-store');
-const features = require('./features');
 const memoryStore = require('./memory-store');
 const promotion = require('./promotion');
 const { isBranchActive } = require('./cooldown');
@@ -3915,7 +3914,6 @@ function createReviewFeedbackForAuthor(reviewerAgentId, pr, config, opts = {}) {
   const authorAgentId = pr.agent.toLowerCase();
   if (!config.agents?.[authorAgentId]) return null;
   if (opts.reviewVerdict !== REVIEW_STATUS.CHANGES_REQUESTED) return null;
-  if (!features.isFeatureOn('review-learning-capture', config)) return null;
 
   const project = opts.project || opts.dispatchItem?.meta?.project || null;
   if (!project?.name) {
@@ -4512,7 +4510,6 @@ function _recordRepeatedFindingEvent(lesson, group, match, provenance) {
 function captureVerifiedReviewLearnings({
   dispatchItem,
   agentId,
-  config,
   structuredCompletion,
   branchChange,
   reviewFixResolution,
@@ -4522,7 +4519,6 @@ function captureVerifiedReviewLearnings({
   const supportedType = dispatchItem?.type === WORK_TYPE.REVIEW
     || shared.isFixLikeWorkType(dispatchItem?.type);
   if (!supportedType || !Array.isArray(rawLearnings) || rawLearnings.length === 0) return result;
-  if (!features.isFeatureOn('review-learning-capture', config || {})) return result;
 
   let groups;
   try {
@@ -4715,7 +4711,6 @@ function _resolveDispatchProject(dispatchItem) {
 function processReviewLearningApplications({
   dispatchItem,
   agentId,
-  config,
   structuredCompletion,
 } = {}) {
   const result = {
@@ -4727,9 +4722,6 @@ function processReviewLearningApplications({
   };
   const rawApplications = structuredCompletion?.reviewLearningApplications;
   if (!Array.isArray(rawApplications) || rawApplications.length === 0) return result;
-  // Applications describe how recalled lessons fared, so they are only
-  // meaningful when the recall path is active.
-  if (!features.isFeatureOn('review-learning-recall', config || {})) return result;
 
   let applications;
   try {
@@ -6753,7 +6745,6 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       captureVerifiedReviewLearnings({
         dispatchItem,
         agentId,
-        config,
         structuredCompletion,
         branchChange: prFixBranchChange,
         reviewFixResolution,
@@ -6772,7 +6763,6 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       processReviewLearningApplications({
         dispatchItem,
         agentId,
-        config,
         structuredCompletion,
       });
     } catch (err) {

package/engine/playbook.js

@@ -784,12 +784,12 @@ function renderPlaybook(type, vars) {
   }
 
   // Reserved deterministic review-lesson recall (P-a6137579). A dedicated
-  // project + audience path, independent of the generic memory budget above and
-  // gated on its own feature flag. Review-learning records are globally excluded
-  // from generic recall, so with recall off (capture-only) the rendered prompt
-  // is unchanged with respect to those records. Only dispatches with a resolved
-  // project context are eligible; projectless CC / central work get no section.
-  if (projectName && features.isFeatureOn('review-learning-recall', configEarly)) {
+  // project + audience path, independent of the generic memory budget above.
+  // Review-learning records are globally excluded from generic recall, so this
+  // section is the only place they reach a prompt. Only dispatches with a
+  // resolved project context are eligible; projectless CC / central work get no
+  // section.
+  if (projectName) {
     try {
       const applicable = memoryRetrieval.retrieveApplicableReviewLearnings({
         title: vars.item_name || vars.pr_title || '',

package/engine/shared.js

@@ -972,7 +972,16 @@ function mutateTextFileLocked(filePath, mutateFn, {
       safeWrite(filePath, finalText);
     }
     return finalText;
-  }, { retries, retryBackoffMs });
+  }, {
+    retries,
+    retryBackoffMs,
+    compromiseRedos: LOCK_COMPROMISE_REDOS,
+    // Our lock was stolen mid-section, so another writer shared it. Redo the
+    // read-modify-write against the current on-disk state only if our own write
+    // did not survive — otherwise the update is intact and a redo would just
+    // re-apply it.
+    onCompromised: (written) => (safeRead(filePath) === written ? 'accept' : 'redo'),
+  });
 }
 
 function safeUnlink(p) {
@@ -1406,14 +1415,73 @@ function pruneCrashDiagnosticsReports(config) {
   return removed;
 }
 
+/**
+ * Read a lock file's holder payload.
+ *
+ * Returns `{ missing, unreadable, payload }` so callers can tell "the lock is
+ * gone" (definitive — someone removed it) from "we couldn't read it right now"
+ * (transient Windows sharing violation) from "it's there but has no parseable
+ * payload" (legacy lock, or the sub-millisecond window between create and
+ * payload write).
+ */
+function _readLockPayload(lockPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(lockPath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { missing: true, unreadable: false, payload: null };
+    return { missing: false, unreadable: true, payload: null };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') return { missing: false, unreadable: false, payload: parsed };
+  } catch { /* empty (create/write window) or legacy lock → no payload */ }
+  return { missing: false, unreadable: false, payload: null };
+}
+
+/**
+ * Does `payload` describe the same lock acquisition we observed and judged
+ * stale? `observed` is the payload read during the EEXIST inspection.
+ *
+ * Tokens are the authoritative identity. Locks written by an older engine (or
+ * caught in the create/write window) have no token, so fall back to pid — and
+ * treat "still no payload" as "still the same anonymous lock".
+ */
+function _isSameLockAcquisition(observed, payload) {
+  if (observed && observed.token) return !!(payload && payload.token === observed.token);
+  if (payload && payload.token) return false; // a fresh tokened lock replaced it
+  if (observed && Number.isFinite(observed.pid)) return !!(payload && payload.pid === observed.pid);
+  return payload === null;
+}
+
+// Bounded redo budget for a critical section whose lock was compromised (stolen
+// by a reaper or otherwise re-owned mid-section). Read-modify-write callers
+// re-run against the current on-disk state so a raced write is re-applied
+// instead of being silently lost; see mutateJsonFileLocked/mutateTextFileLocked.
+const LOCK_COMPROMISE_REDOS = 3;
+
+/**
+ * Run `fn` under an exclusive file lock at `lockPath`.
+ *
+ * `onCompromised(result)` is consulted when the lock was stolen mid-section
+ * (a reaper removed it, or it is now owned by a different token) — i.e. another
+ * holder shared the critical section. Return `'accept'` to keep `result`, or
+ * `'redo'` to re-run `fn` under a fresh lock (bounded by `compromiseRedos`).
+ * Without the hook a compromised section throws `ELOCKCOMPROMISED` rather than
+ * returning a value that may have been produced from, or clobbered by, a raced
+ * snapshot.
+ */
 function withFileLock(lockPath, fn, {
   timeoutMs = 5000,
   retryDelayMs = 25,
   retries = 0,
-  retryBackoffMs = 1000
+  retryBackoffMs = 1000,
+  compromiseRedos = 0,
+  onCompromised = null
 } = {}) {
   let lastErr = null;
   const maxAttempts = 1 + Math.max(0, retries);
+  let redosLeft = Math.max(0, compromiseRedos);
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
     if (attempt > 0) {
       // Exponential backoff between retry attempts: retryBackoffMs * 2^(attempt-1)
@@ -1421,19 +1489,32 @@ function withFileLock(lockPath, fn, {
       sleepMs(backoff);
     }
     const start = Date.now();
-    let fd = null;
+    let acquired = false;
+    // Per-acquisition identity. The reaper and the release path both compare
+    // against this so neither ever destroys a lock it does not own — an unlink
+    // keyed only on the path is a TOCTOU that lets two holders into the
+    // critical section at once (W-ms2nbtkj00016ffc).
+    const token = `${process.pid}-${uid()}`;
+    let tokenPersisted = false;
     while (Date.now() - start < timeoutMs) {
       try {
         const dir = path.dirname(lockPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-        fd = fs.openSync(lockPath, 'wx');
+        const fd = fs.openSync(lockPath, 'wx');
         // P-b7d4e8f2 — record holder identity so the stale-lock reaper can
         // distinguish a still-alive slow holder from a crashed one. Best-effort:
         // the lock's existence (not its contents) provides mutual exclusion, so
-        // a write failure here must NOT abort acquisition.
+        // a write failure here must NOT abort acquisition (it only downgrades us
+        // to the legacy pid-keyed release path).
         try {
-          fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+          fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now(), token }));
+          tokenPersisted = true;
         } catch { /* payload is advisory; lock semantics unaffected */ }
+        // Close immediately: an open handle keeps the file in Windows'
+        // "pending delete" limbo after unlink, which makes waiters keep seeing
+        // (and repeatedly trying to reap) a lock that is already released.
+        try { fs.closeSync(fd); } catch { /* handle is not load-bearing */ }
+        acquired = true;
         break;
       } catch (err) {
         // EEXIST is the cross-platform exclusive-create collision.
@@ -1453,29 +1534,60 @@ function withFileLock(lockPath, fn, {
         try {
           const stat = fs.statSync(lockPath);
           const mtimeAge = Date.now() - stat.mtimeMs;
-          let holderPid = null;
-          try {
-            const raw = fs.readFileSync(lockPath, 'utf8');
-            const parsed = JSON.parse(raw);
-            if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) {
-              holderPid = parsed.pid;
-            }
-          } catch { /* legacy/empty/corrupt lock → mtime-only fallback */ }
+          const observed = _readLockPayload(lockPath).payload;
+          const holderPid = observed && Number.isFinite(observed.pid) && observed.pid > 0
+            ? observed.pid
+            : null;
 
           const shouldReap = holderPid !== null
             ? !processUtils.isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5
             : mtimeAge > LOCK_STALE_MS;
 
           if (shouldReap) {
+            // Do not race a lock that is simply being released. Require the
+            // SAME acquisition (identified by its token) to still be present
+            // after a short grace delay: a normally-releasing holder's lock
+            // disappears inside that window, and a fresh holder's lock carries
+            // a different token. Without this, the reaper routinely removed a
+            // brand-new live holder's lock in the microseconds after the
+            // previous holder exited (W-ms2nbtkj00016ffc).
+            sleepMs(retryDelayMs);
+            const recheck = _readLockPayload(lockPath);
+            if (recheck.missing || recheck.unreadable
+              || !_isSameLockAcquisition(observed, recheck.payload)) {
+              continue; // resolved itself — back to normal contention
+            }
+            // Reap by IDENTITY, never by path. Renaming is atomic, so exactly
+            // one racer takes custody and can then verify that what it took is
+            // the acquisition it judged stale.
+            const reapPath = `${lockPath}.reap-${process.pid}-${uid()}`;
+            let reaped = false;
             try {
-              fs.unlinkSync(lockPath);
-            } catch (unlinkErr) {
-              // ENOENT: another process deleted the lock between stat and unlink — safe to retry.
-              // EPERM on Windows: file is in 'pending delete' state from a concurrent
-              // reaper — the OS will finalize the delete shortly; retry will succeed.
-              const tolerable = unlinkErr.code === 'ENOENT' ||
-                (process.platform === 'win32' && unlinkErr.code === 'EPERM');
-              if (!tolerable) throw unlinkErr;
+              fs.renameSync(lockPath, reapPath);
+              reaped = true;
+            } catch (reapErr) {
+              // ENOENT: another reaper/holder already removed it — retry.
+              // EPERM on Windows: pending-delete state — retry.
+              const tolerable = reapErr.code === 'ENOENT' ||
+                (process.platform === 'win32' && reapErr.code === 'EPERM');
+              if (!tolerable) throw reapErr;
+            }
+            if (reaped) {
+              const quarantined = _readLockPayload(reapPath).payload;
+              if (_isSameLockAcquisition(observed, quarantined)) {
+                try { fs.unlinkSync(reapPath); } catch { /* already gone */ }
+              } else {
+                // We took custody of a lock we never judged stale — a live
+                // holder replaced the stale one in the last instant. Put it
+                // back and keep waiting. linkSync fails if a newer lock already
+                // exists, which is the correct outcome (that lock is the live
+                // one); the displaced holder then detects the compromise at
+                // release rather than losing its write silently.
+                try { fs.linkSync(reapPath, lockPath); } catch { /* superseded */ }
+                try { fs.unlinkSync(reapPath); } catch { /* already gone */ }
+                sleepMs(retryDelayMs);
+                continue;
+              }
             }
             continue; // lock just removed — retry immediately
           }
@@ -1490,31 +1602,64 @@ function withFileLock(lockPath, fn, {
         sleepMs(retryDelayMs);
       }
     }
-    if (fd === null) {
+    if (!acquired) {
       lastErr = new Error(`Lock timeout: ${lockPath}`);
       continue; // retry if attempts remain
     }
 
+    let result;
+    let thrown = null;
     try {
-      const result = fn();
+      result = fn();
       // P-a3f9b2c1 — Defensive: detect a thenable return and throw synchronously.
-      // The `finally` below releases the lock immediately after `fn()` returns;
-      // an async callback would let the lock be released before its body
-      // completes, silently breaking mutual exclusion. Clean up our own fd /
-      // lock first, then throw so the caller cannot ignore the failure.
+      // The lock is released immediately after `fn()` returns; an async callback
+      // would let the lock be released before its body completes, silently
+      // breaking mutual exclusion. Release below, then throw so the caller
+      // cannot ignore the failure.
       if (result && typeof result.then === 'function') {
-        try { fs.closeSync(fd); } catch { /* cleanup */ }
-        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
-        fd = null; // suppress double-cleanup in `finally`
+        result = undefined;
         throw new Error('withFileLock: fn must be synchronous; got Promise. Use synchronous operations only.');
       }
-      return result;
-    } finally {
-      if (fd !== null) {
-        try { fs.closeSync(fd); } catch { /* cleanup */ }
-        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
+    } catch (err) {
+      thrown = err;
+    }
+
+    // Release by IDENTITY. If the lock file is gone, or now carries a different
+    // token, a reaper stole it mid-section: someone else was in the critical
+    // section with us, so (a) do NOT unlink — that would destroy the successor's
+    // lock and cascade the breach — and (b) report the breach instead of
+    // silently returning a value that may have been produced from, or clobbered
+    // by, a raced snapshot.
+    let compromised = false;
+    const held = tokenPersisted ? _readLockPayload(lockPath) : null;
+    if (held && held.missing) {
+      compromised = true;
+    } else if (held && held.payload && held.payload.token && held.payload.token !== token) {
+      compromised = true;
+    } else {
+      try {
+        fs.unlinkSync(lockPath);
+      } catch (unlinkErr) {
+        // ENOENT means it was removed under us — same breach as `missing`.
+        if (unlinkErr && unlinkErr.code === 'ENOENT') compromised = true;
+        // Anything else is best-effort; the stale reaper will clear it.
       }
     }
+
+    if (thrown) throw thrown;
+    if (compromised) {
+      if (typeof onCompromised === 'function' && redosLeft > 0) {
+        redosLeft--;
+        if (onCompromised(result) !== 'redo') return result;
+        attempt--; // a compromised section is not a failed acquisition attempt
+        sleepMs(retryDelayMs);
+        continue;
+      }
+      const err = new Error(`Lock compromised (concurrent holder detected): ${lockPath}`);
+      err.code = 'ELOCKCOMPROMISED';
+      throw err;
+    }
+    return result;
   }
   throw lastErr;
 }
@@ -1640,7 +1785,21 @@ function mutateJsonFileLocked(filePath, mutateFn, {
       }
       throw error;
     }
-  }, { retries, retryBackoffMs });
+  }, {
+    retries,
+    retryBackoffMs,
+    compromiseRedos: LOCK_COMPROMISE_REDOS,
+    // Our lock was stolen mid-section, so another writer shared it and one of
+    // the two updates was clobbered. Redo the read-modify-write against the
+    // current on-disk state only if our own write did not survive; the other
+    // writer detects and redoes its own loss the same way, so the union is
+    // preserved without double-applying an intact mutation.
+    onCompromised: (written) => {
+      if (written === null) return fs.existsSync(filePath) ? 'redo' : 'accept';
+      const current = safeJsonNoRestore(filePath);
+      return JSON.stringify(current) === JSON.stringify(written) ? 'accept' : 'redo';
+    },
+  });
 }
 
 function mutateControl(mutator) {
@@ -9264,6 +9423,9 @@ module.exports = {
   resolveDispatchPrompt,
   deleteDispatchPromptSidecar,
   withFileLock,
+  _readLockPayload, // exported for testing
+  _isSameLockAcquisition, // exported for testing
+  LOCK_COMPROMISE_REDOS, // exported for testing
   mutateJsonFileLocked,
   mutateControl, recordEngineRespawn,
   mutateEngineState, // W-mp60tw0u000j3931

package/package.json

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