brainclaw 1.13.0 → 1.14.0

package/README.md

@@ -431,6 +431,14 @@ npm run test:coverage      # with coverage report
 
 For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
+### v1.14.0
+
+Coordination hygiene, a dispatch-supervisor spec, and a monorepo worktree fix — from continued cross-machine dogfooding, each Codex-reviewed before merge:
+
+- **Coordination hygiene v1** (pln#602) — family-level TTL sweep (park-don't-delete, `config.hygiene`-overridable), lazy at the `bclaw_work` read path (zero extra reads on a healthy store) + full at session-start, K-times aging of stale warnings/hints into one actionable aggregate, and `brainclaw doctor --hygiene`.
+- **Worktree creation for in-tree projects** (pln#614) — `bclaw_coordinate(assign|review)` on a project dir that isn't the git root (app inside a monorepo) now resolves the real toplevel (`resolveGitToplevel` with a parent-walk past an invalid nested `.git`), so it spawns instead of failing with "not a git repository". Standalone projects unchanged; validated E2E on the reporting monorepo.
+- **Dispatch-supervisor round-3 spec** (pln#545, docs) — `docs/concepts/dispatch-supervisor.md`: honest worker-liveness attribution (Node supervisor + `run_id`-keyed sentinels), A0→B hard dependency, Windows Job Object FAIL-CLOSED, complete behavior matrix. Implementation lands later as A0-first increments.
+
 ### v1.13.0
 
 Operator-maturity batch from two days of heavy multi-agent dogfooding — dispatch/worktree lifecycle, claim parity, write-path auto-repair, model routing, benchmark gate, 2× faster context reads:

package/dist/cli.js

@@ -782,12 +782,13 @@ program
     .option('--verify-journal', 'Phase-2 cutover gate (pln#565): rebuild state from the event journal and diff vs live projections; exits non-zero on any drift')
     .option('--spawn-check', 'Real spawn round-trip per installed agent before dispatch (pln#520 step 2): validates delivery + handshake on this host, exits non-zero on any installed-agent failure')
     .option('--spawn-check-timeout <ms>', 'Per-agent timeout for --spawn-check (default 15000)', parseInt)
+    .option('--hygiene', 'Coordination-hygiene snapshot (pln#602): counts per family, park candidates, serve-count aging stats. Read-only.')
     .action(async (options) => {
     if (options.spawnCheck) {
         await runDoctorSpawnCheck({ cwd: options.cwd, json: options.json, timeoutMs: options.spawnCheckTimeout });
         return;
     }
-    runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch, verifyJournal: options.verifyJournal });
+    runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch, verifyJournal: options.verifyJournal, hygiene: options.hygiene });
 });
 // --- repair (Phase 4 Sprint 2 Lane C / pln#397) ---
 program

package/dist/commands/doctor.js

@@ -4,6 +4,10 @@ import os from 'node:os';
 import path from 'node:path';
 import * as childProcess from 'node:child_process';
 import { reconcileAllOpenRuns } from '../core/agentrun-reconciler.js';
+import { loadHygienePolicy } from '../core/hygiene-policy.js';
+import { computeServeStats, loadServeRegistry } from '../core/hint-aging.js';
+import { listAssignments } from '../core/assignments.js';
+import { parkClosedAutoHandoffs } from '../core/gc-semantic.js';
 import { runSpawnCheck, renderSpawnCheckReport } from '../core/spawn-check.js';
 import { loadAgentRun } from '../core/agentruns.js';
 import { listAgentIdentities, listDebrisAgentIdentities, resolveCurrentAgentIdentity } from '../core/agent-registry.js';
@@ -638,7 +642,101 @@ function runJournalVerification(options) {
     if (drift.length > 0)
         process.exit(1);
 }
+function medianAgeDays(items, nowMs) {
+    if (items.length === 0)
+        return 0;
+    const ages = items
+        .map((a) => Math.floor((nowMs - new Date(a.created_at).getTime()) / 86_400_000))
+        .sort((a, b) => a - b);
+    const mid = Math.floor(ages.length / 2);
+    return ages.length % 2 === 1 ? ages[mid] : (ages[mid - 1] + ages[mid]) / 2;
+}
+export function runHygieneReport(options = {}) {
+    const cwd = options.cwd;
+    const policy = loadHygienePolicy(cwd);
+    const nowMs = Date.now();
+    const allAssignments = listAssignments(cwd);
+    const open = allAssignments.filter((a) => a.status === 'offered' || a.status === 'accepted' || a.status === 'started');
+    const offered = open.filter((a) => a.status === 'offered');
+    const accepted = open.filter((a) => a.status === 'accepted');
+    const started = open.filter((a) => a.status === 'started');
+    const heartbeatAgeMs = (a) => {
+        const anchor = a.last_heartbeat_at ?? a.offered_at ?? a.created_at;
+        return nowMs - new Date(anchor).getTime();
+    };
+    const offered_park_candidates = offered.filter((a) => heartbeatAgeMs(a) > policy.assignment_offered_ttl_ms).length;
+    const accepted_park_candidates = accepted.filter((a) => heartbeatAgeMs(a) > policy.assignment_accepted_ttl_ms).length;
+    const handoffParkDry = parkClosedAutoHandoffs(cwd ?? process.cwd(), Math.floor(policy.handoff_closed_ttl_ms / 86_400_000), true);
+    const registry = loadServeRegistry(cwd);
+    const staleStats = computeServeStats(registry.warnings, policy.stale_warning_serve_k);
+    const hintsStats = computeServeStats(registry.hints, policy.workflow_hint_serve_k);
+    return {
+        generated_at: new Date(nowMs).toISOString(),
+        disabled: policy.disabled,
+        policy,
+        families: {
+            assignments: {
+                total_open: open.length,
+                offered: offered.length,
+                accepted: accepted.length,
+                started: started.length,
+                offered_park_candidates,
+                accepted_park_candidates,
+                median_open_age_days: medianAgeDays(open, nowMs),
+            },
+            handoffs: {
+                closed_park_candidates: handoffParkDry.candidates,
+            },
+            stale_warnings: {
+                total_tracked: staleStats.total,
+                over_threshold: staleStats.over_threshold,
+                median_count: staleStats.median_count,
+                oldest_first_at: staleStats.oldest_first_at,
+            },
+            workflow_hints: {
+                total_tracked: hintsStats.total,
+                over_threshold: hintsStats.over_threshold,
+                median_count: hintsStats.median_count,
+                oldest_first_at: hintsStats.oldest_first_at,
+            },
+        },
+    };
+}
+function renderHygieneReport(report) {
+    const lines = [];
+    lines.push(`Coordination hygiene — snapshot ${report.generated_at}`);
+    if (report.disabled) {
+        lines.push('  ✗ policy.disabled=true — hygiene sweep + aging are opted out via config.hygiene.disabled.');
+    }
+    lines.push('');
+    const a = report.families.assignments;
+    lines.push(`Assignments (open ${a.total_open}: offered ${a.offered} / accepted ${a.accepted} / started ${a.started}, median age ${a.median_open_age_days}d)`);
+    lines.push(`  Park candidates: offered=${a.offered_park_candidates}, accepted=${a.accepted_park_candidates} — next sweep at session-start or bclaw_work will converge.`);
+    const h = report.families.handoffs;
+    lines.push(`Handoffs closed park candidates: ${h.closed_park_candidates} (auto-generated, older than ${Math.floor(report.policy.handoff_closed_ttl_ms / 86_400_000)}d)`);
+    const sw = report.families.stale_warnings;
+    lines.push(`Stale warnings tracked: ${sw.total_tracked} (over serve-K=${report.policy.stale_warning_serve_k}: ${sw.over_threshold}, median count ${sw.median_count}${sw.oldest_first_at ? `, oldest first-served ${sw.oldest_first_at.slice(0, 10)}` : ''})`);
+    const wh = report.families.workflow_hints;
+    lines.push(`Workflow hints tracked: ${wh.total_tracked} (over serve-K=${report.policy.workflow_hint_serve_k}: ${wh.over_threshold}, median count ${wh.median_count}${wh.oldest_first_at ? `, oldest first-served ${wh.oldest_first_at.slice(0, 10)}` : ''})`);
+    lines.push('');
+    lines.push('Read-only: no state was mutated. Session-start and bclaw_work drive the actual sweep/park; the counters age at bclaw_work read paths.');
+    return lines.join('\n');
+}
 export function runDoctor(options = {}) {
+    if (options.hygiene) {
+        if (!memoryExists(options.cwd)) {
+            console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+            process.exit(1);
+        }
+        const report = runHygieneReport(options);
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(renderHygieneReport(report));
+        }
+        return;
+    }
     if (options.verifyJournal) {
         runJournalVerification(options);
         return;

package/dist/commands/harvest.js

@@ -21,13 +21,19 @@ import { memoryExists } from '../core/io.js';
 import { loadAssignment, transitionAssignment } from '../core/assignments.js';
 import { loadClaim, releaseClaimsCascade, logCascadeReleaseResult } from '../core/claims.js';
 import { getCapabilityProfile, dispatchCanCommit } from '../core/agent-capability.js';
-import { commitWorktreeOnBehalf, worktreesBaseDir } from '../core/worktree.js';
+import { commitWorktreeOnBehalf, worktreesBaseDir, resolveGitToplevel } from '../core/worktree.js';
 /**
  * Auto-detect all worktree directories under the brainclaw-managed base dir.
  * Returns subdirectories that exist on disk (may or may not have an inbox).
  */
 function autoDetectWorktreePaths(cwd) {
-    const base = worktreesBaseDir(cwd);
+    // Codex review of PR #49 (MED): createWorktree now writes in-tree worktrees
+    // under the git-TOPLEVEL hash (pln#614), so the scan base must resolve the
+    // toplevel too — otherwise `harvest --all` / candidates from an in-tree
+    // project subdir scan the stale subdir hash and miss every lane result. Only
+    // the scan base is toplevel-resolved; .brainclaw store reads/writes elsewhere
+    // keep the original project cwd.
+    const base = worktreesBaseDir(resolveGitToplevel(cwd));
     if (!fs.existsSync(base))
         return [];
     return fs.readdirSync(base, { withFileTypes: true })

package/dist/commands/mcp.js

@@ -9,6 +9,10 @@ import { generatedSchemas } from './mcp-schemas.generated.js';
 import { getTriggeredItems, renderTriggeredItems } from '../core/lifecycle.js';
 import { resolveCrossProjectLinks, resolveCrossProjectWritableTarget, resolveProjectCwd, writeCrossProjectSignal } from '../core/cross-project.js';
 import { buildContext, renderContextMarkdown, renderContextPromptTemplate, renderContextBriefing } from '../core/context.js';
+import { ageStaleWarnings, ageWorkflowHints, loadServeRegistry } from '../core/hint-aging.js';
+import { loadHygienePolicy } from '../core/hygiene-policy.js';
+import { sweepAssignmentsAtReadPath, selectReadPathSweepCandidates } from '../core/assignment-sweeper.js';
+import { loadAssignment } from '../core/assignments.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, readDiskBrainclawVersion, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
@@ -5095,6 +5099,45 @@ async function _executeMcpToolCallInner(payload) {
                     }
                 }
             }
+            let stalePostAging;
+            let staleAggregate;
+            let hintsPostAging;
+            let hintsAggregate;
+            if (contextResult) {
+                try {
+                    const policy = loadHygienePolicy(targetCwd);
+                    if (!policy.disabled) {
+                        // Filter candidates from the projection (no extra reads) — only
+                        // assignments whose surfaced last_heartbeat_at is old enough to
+                        // possibly cross a family TTL. Zero read overhead when the open
+                        // work is fresh (the common case).
+                        const openAssignments = contextResult.open_work?.active_assignments ?? [];
+                        // Codex PR#48 finding 3 (pln#578 guardrail): select candidate ids
+                        // from the already-surfaced projection — created/terminal rows are
+                        // dropped BEFORE any full loadAssignment, so a healthy store costs
+                        // zero extra file reads. Selection logic is unit-tested in
+                        // selectReadPathSweepCandidates.
+                        const candidateIds = selectReadPathSweepCandidates(openAssignments, policy, Date.now());
+                        if (candidateIds.length > 0) {
+                            const full = candidateIds
+                                .map((id) => loadAssignment(id, targetCwd))
+                                .filter((a) => a !== undefined);
+                            sweepAssignmentsAtReadPath(full, targetCwd, {
+                                actor: 'bclaw_work-readpath',
+                                policy,
+                            });
+                        }
+                        const registry = loadServeRegistry(targetCwd);
+                        const aged = ageStaleWarnings(contextResult.stale_warnings ?? [], targetCwd, { policy, registry });
+                        stalePostAging = aged.warnings;
+                        staleAggregate = aged.aggregate;
+                        const agedHints = ageWorkflowHints(contextResult.workflow_hints ?? [], targetCwd, { policy, registry });
+                        hintsPostAging = agedHints.hints;
+                        hintsAggregate = agedHints.aggregate;
+                    }
+                }
+                catch { /* non-fatal — hygiene must never break bclaw_work */ }
+            }
             // Build the full context result, then compact it if requested.
             // Compact mode (default) strips the heavy ContextResult down to a
             // minimal summary that fits within MCP token limits (~25k chars).
@@ -5110,7 +5153,8 @@ async function _executeMcpToolCallInner(payload) {
                     status: item.extra ?? 'unknown',
                     plan_id: item.plan_id,
                 }));
-                const staleTop3 = (contextResult.stale_warnings ?? []).slice(0, 3).map((w) => ({
+                const stalePool = stalePostAging ?? contextResult.stale_warnings ?? [];
+                const staleTop3 = stalePool.slice(0, 3).map((w) => ({
                     id: w.id,
                     entity: w.entity,
                     text: w.text.slice(0, 80),
@@ -5134,6 +5178,7 @@ async function _executeMcpToolCallInner(payload) {
                             : {}),
                     }
                     : undefined;
+                const hintsPool = hintsPostAging ?? contextResult.workflow_hints ?? [];
                 resultPayload = {
                     context_schema: contextResult.context_schema,
                     profile: contextResult.profile,
@@ -5142,7 +5187,9 @@ async function _executeMcpToolCallInner(payload) {
                     context_diff: trimmedDiff ?? null,
                     plan_summary: planItems,
                     stale_warnings: staleTop3,
-                    workflow_hints: (contextResult.workflow_hints ?? []).slice(0, 3),
+                    ...(staleAggregate ? { stale_warnings_aggregate: staleAggregate } : {}),
+                    workflow_hints: hintsPool.slice(0, 3),
+                    ...(hintsAggregate ? { workflow_hints_aggregate: hintsAggregate } : {}),
                     claim_conflicts: contextResult.claim_conflicts ?? [],
                     open_work: contextResult.open_work ?? null,
                     _compact: true,

package/dist/commands/session-start.js

@@ -16,7 +16,9 @@ import { releaseStaleClaimsFromOtherAgents } from '../core/claims.js';
 import { SessionSnapshotSchema } from '../core/schema.js';
 import { auditLocalAgentWorkspaceFiles } from '../core/agent-files.js';
 import { buildAgentInventory, loadAgentInventory, saveAgentInventory, diffInventory } from '../core/agent-inventory.js';
-import { checkMemoryPressure, enforceRuntimeNoteRetention } from '../core/gc-semantic.js';
+import { checkMemoryPressure, enforceRuntimeNoteRetention, parkClosedAutoHandoffs } from '../core/gc-semantic.js';
+import { sweepAssignments } from '../core/assignment-sweeper.js';
+import { loadHygienePolicy } from '../core/hygiene-policy.js';
 import { maybeCreateCheckpoint } from '../core/events/checkpoint.js';
 import { pullSignalsFromLinkedProjects, markSignalProcessed } from '../core/federation-transport.js';
 import { pullSignalsFromCloud, isCloudSyncEnabled } from '../core/federation-cloud.js';
@@ -207,6 +209,19 @@ export async function startSession(options = {}) {
             enforceRuntimeNoteRetention({ cwd: options.cwd });
         }
         catch { /* non-fatal — retention sweep must never block session start */ }
+        // pln#602 — coordination hygiene pass. Converge orphan offered/accepted
+        // assignments (workers that died without a self-report — fable-audit-2026-07
+        // witnesses) and park closed auto-generated handoffs so bclaw_work stops
+        // serving debris. Runs at session-start ONLY (not on the hot read path);
+        // opt-out via config.hygiene.disabled honoured through the policy load.
+        try {
+            const policy = loadHygienePolicy(options.cwd);
+            if (!policy.disabled) {
+                sweepAssignments(options.cwd, { actor: 'session-start', policy });
+                parkClosedAutoHandoffs(options.cwd ?? process.cwd(), Math.floor(policy.handoff_closed_ttl_ms / (24 * 60 * 60 * 1000)));
+            }
+        }
+        catch { /* non-fatal — hygiene sweep must never block session start */ }
         // pln#566 Inc0 — keep a recent journal-derived checkpoint available off the
         // hot path so the (capability-gated, OFF by default) checkpointRead read
         // path has something to serve once enabled. Gated by a growth threshold so

package/dist/core/assignment-sweeper.js

@@ -16,6 +16,7 @@
 import { spawnSync } from 'node:child_process';
 import { listAssignments, transitionAssignment } from './assignments.js';
 import { signalExists, readHeartbeat, latestActivityMs } from './runtime-signals.js';
+import { DEFAULT_HYGIENE_POLICY } from './hygiene-policy.js';
 function lastCommitAgeMs(worktreePath, nowMs) {
     if (!worktreePath)
         return undefined;
@@ -104,28 +105,60 @@ function collectImplicitEvidence(assignment, cwd, nowMs, sinceMs, freshTtlMs) {
  * @param options.actor - Actor name for audit trail (default: 'sweeper')
  */
 export function sweepAssignments(cwd, options) {
+    return sweepAssignmentsFromList(listAssignments(cwd), cwd, options);
+}
+/**
+ * Read-path variant: sweep only the assignments the caller ALREADY loaded
+ * (typically open_work.active_assignments). No `listAssignments` call, so no
+ * additional store scan on the hot bclaw_work path (pln#602 perf guardrail
+ * per the pln#578 read-path optimisation). Use `sweepAssignmentsFromList`
+ * with a bounded slice when a full pass would violate the budget.
+ *
+ * @param assignments - pre-loaded assignments to consider (only non-terminal ones matter)
+ * @param cwd - project root
+ * @param options.nowMs - Override current time for testing
+ * @param options.actor - Actor for the audit trail (default: 'sweeper-readpath')
+ * @param options.policy - Family-level TTL/policy overrides
+ */
+export function sweepAssignmentsFromList(assignments, cwd, options) {
+    const policy = options?.policy;
+    if (policy?.disabled) {
+        return { timed_out: [], expired: [], implicitly_advanced: [] };
+    }
     const now = options?.nowMs ?? Date.now();
     const actor = options?.actor ?? 'sweeper';
     const result = { timed_out: [], expired: [], implicitly_advanced: [] };
-    const all = listAssignments(cwd);
-    for (const assignment of all) {
+    for (const assignment of assignments) {
+        // pln#602 / Codex PR#48 finding 2: when a hygiene `policy` is supplied
+        // (session-start full sweep, bclaw_work read-path), the age comparison,
+        // the implicit-evidence freshness window, AND the status_reason MUST use
+        // the family TTLs (offered 3d / accepted 1d / started 1d by default), NOT
+        // the assignment's embedded heartbeat_ttl_ms/acceptance_ttl_ms (~30/15min).
+        // Otherwise a 20-min offered assignment that `doctor --hygiene` does not
+        // list as a candidate could still be expired here — the exact incoherence
+        // Codex flagged. Without a policy (the dispatcher convergence sweep,
+        // dispatcher.ts), fall back to the embedded TTLs so short-window dispatch
+        // convergence is unchanged.
+        const startedTtl = policy?.assignment_started_ttl_ms ?? assignment.heartbeat_ttl_ms;
+        const acceptedTtl = policy?.assignment_accepted_ttl_ms ?? assignment.acceptance_ttl_ms;
+        const offeredTtl = policy?.assignment_offered_ttl_ms ?? assignment.acceptance_ttl_ms;
         // Check started assignments for heartbeat timeout
         if (assignment.status === 'started') {
             const lastBeat = assignment.last_heartbeat_at ?? assignment.started_at;
             if (!lastBeat)
                 continue;
             const ageMs = now - new Date(lastBeat).getTime();
-            if (ageMs > assignment.heartbeat_ttl_ms) {
+            if (ageMs > startedTtl) {
                 // can_948acfd6: a worker without MCP cannot bump last_heartbeat_at —
                 // its file evidence is the heartbeat. Fresh file activity vetoes the
                 // administrative timeout.
                 const sinceMs = new Date(assignment.started_at ?? assignment.created_at).getTime();
-                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, assignment.heartbeat_ttl_ms);
+                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, startedTtl);
                 if (evidence.fresh)
                     continue;
                 try {
                     transitionAssignment(assignment.id, 'timed_out', {
-                        status_reason: `No heartbeat for ${Math.round(ageMs / 60_000)} minutes (TTL: ${Math.round(assignment.heartbeat_ttl_ms / 60_000)}min); implicit evidence: ${evidence.description}`,
+                        status_reason: `No heartbeat for ${Math.round(ageMs / 60_000)} minutes (TTL: ${Math.round(startedTtl / 60_000)}min); implicit evidence: ${evidence.description}`,
                         actor,
                     }, cwd);
                     result.timed_out.push({ assignment_id: assignment.id, agent: assignment.agent, age_ms: ageMs });
@@ -139,10 +172,12 @@ export function sweepAssignments(cwd, options) {
             if (!acceptedAt)
                 continue;
             const ageMs = now - new Date(acceptedAt).getTime();
-            // Use acceptance_ttl for accepted→timed_out (same window: agent should start quickly after accepting)
-            if (ageMs > assignment.acceptance_ttl_ms) {
+            // Use the accepted-family TTL for accepted→timed_out (agent should start
+            // soon after accepting; family default 1d, or embedded acceptance_ttl_ms
+            // for the policy-less convergence sweep).
+            if (ageMs > acceptedTtl) {
                 const sinceMs = new Date(acceptedAt).getTime();
-                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, assignment.acceptance_ttl_ms);
+                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, acceptedTtl);
                 if (evidence.fresh) {
                     // Working without MCP — record the implicit start so the FSM matches reality.
                     try {
@@ -171,13 +206,13 @@ export function sweepAssignments(cwd, options) {
             if (!offeredAt)
                 continue;
             const ageMs = now - new Date(offeredAt).getTime();
-            if (ageMs > assignment.acceptance_ttl_ms) {
+            if (ageMs > offeredTtl) {
                 // can_948acfd6: ANY worker evidence (ack sentinel touched pre-exec,
                 // heartbeat written, files edited, commit landed) is an implicit
                 // acceptance — the worker just couldn't say so via MCP. Expiring it
                 // is the false-administrative-death observed three times in sprint 1.
                 const sinceMs = new Date(offeredAt).getTime();
-                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, assignment.acceptance_ttl_ms);
+                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, offeredTtl);
                 if (evidence.any) {
                     try {
                         transitionAssignment(assignment.id, 'accepted', {
@@ -191,7 +226,7 @@ export function sweepAssignments(cwd, options) {
                 }
                 try {
                     transitionAssignment(assignment.id, 'expired', {
-                        status_reason: `Not accepted within ${Math.round(ageMs / 60_000)} minutes (TTL: ${Math.round(assignment.acceptance_ttl_ms / 60_000)}min); no implicit evidence`,
+                        status_reason: `Not accepted within ${Math.round(ageMs / 60_000)} minutes (TTL: ${Math.round(offeredTtl / 60_000)}min); no implicit evidence`,
                         actor,
                     }, cwd);
                     result.expired.push({ assignment_id: assignment.id, agent: assignment.agent, age_ms: ageMs });
@@ -202,4 +237,50 @@ export function sweepAssignments(cwd, options) {
     }
     return result;
 }
+/**
+ * Pure candidate selection for the bclaw_work read-path sweep (Codex PR#48
+ * finding 3, pln#578 guardrail). Given ONLY the in-memory projections that
+ * buildContext already surfaced, return the ids worth a full loadAssignment:
+ *   - status must be sweepable (offered/accepted/started) — created/terminal
+ *     rows can never transition and are dropped BEFORE any file read, so a
+ *     healthy store full of `created` assignments costs zero extra I/O;
+ *   - among those, only rows whose surfaced heartbeat is older than the
+ *     smallest family TTL (or that carry no heartbeat) are suspicious;
+ *   - capped at read_path_sweep_budget.
+ * Extracted so the hot-path zero-read guarantee is unit-testable without the
+ * MCP handler.
+ */
+export function selectReadPathSweepCandidates(projections, policy, nowMs) {
+    if (policy.disabled)
+        return [];
+    const minTtl = Math.min(policy.assignment_offered_ttl_ms, policy.assignment_accepted_ttl_ms, policy.assignment_started_ttl_ms);
+    return projections
+        .filter((a) => {
+        if (a.status !== 'offered' && a.status !== 'accepted' && a.status !== 'started')
+            return false;
+        const beat = a.last_heartbeat_at;
+        if (!beat)
+            return true;
+        return nowMs - new Date(beat).getTime() > minTtl;
+    })
+        .slice(0, policy.read_path_sweep_budget)
+        .map((a) => a.id);
+}
+export function sweepAssignmentsAtReadPath(assignments, cwd, options) {
+    const policy = options?.policy ?? DEFAULT_HYGIENE_POLICY;
+    if (policy.disabled) {
+        return { timed_out: [], expired: [], implicitly_advanced: [] };
+    }
+    const budget = policy.read_path_sweep_budget;
+    // Prefer offered/accepted (the empirical debris class); the sweep is a no-op
+    // for terminal statuses so filtering is a perf hygiene, not correctness.
+    const eligible = assignments
+        .filter((a) => a.status === 'offered' || a.status === 'accepted' || a.status === 'started')
+        .slice(0, budget);
+    return sweepAssignmentsFromList(eligible, cwd, {
+        ...options,
+        actor: options?.actor ?? 'sweeper-readpath',
+        policy,
+    });
+}
 //# sourceMappingURL=assignment-sweeper.js.map

package/dist/core/gc-semantic.js

@@ -543,6 +543,85 @@ export function enforceRuntimeNoteRetention(options = {}) {
     result.backup_path = backupPath;
     return result;
 }
+/**
+ * pln#602 — park closed auto-generated handoffs older than the cutoff.
+ *
+ * The stale-warning surface counts every open handoff older than 14d as
+ * something the agent should act on. Once a handoff is `closed` (accepted +
+ * fulfilled OR explicitly retired), it stops being a workflow signal and
+ * starts being noise: the fable-audit trace repeatedly rendered fully-served
+ * handoffs from months prior. Park them next to the released-claims archive
+ * (same JSONL + backup pattern) so `bclaw_find` still surfaces them on demand
+ * but the compact bclaw_work context can move on.
+ *
+ * Auto-generated detection matches the same "Session sess_ … auto-generated
+ * handoff" prefix that `dedupAutoHandoffs` uses — human-authored handoffs
+ * stay put regardless of age (they may carry decisions the agent needs).
+ */
+export function parkClosedAutoHandoffs(cwd, minAgeDays = DEFAULT_MIN_AGE_DAYS, dryRun = false) {
+    const cutoff = new Date(Date.now() - minAgeDays * 24 * 60 * 60 * 1000).toISOString();
+    const handoffsDir = path.join(cwd, '.brainclaw', 'coordination', 'handoffs');
+    if (!fs.existsSync(handoffsDir))
+        return { candidates: 0, parked: 0 };
+    const eligible = [];
+    const files = fs.readdirSync(handoffsDir).filter((f) => f.endsWith('.json'));
+    for (const file of files) {
+        const filePath = path.join(handoffsDir, file);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const parsed = JSON.parse(content);
+            const status = typeof parsed.status === 'string' ? parsed.status : '';
+            if (status !== 'closed')
+                continue;
+            const text = typeof parsed.text === 'string' ? parsed.text : '';
+            const isAutoGenerated = text.startsWith('Session sess_') && text.includes('auto-generated handoff');
+            if (!isAutoGenerated)
+                continue;
+            const updatedAt = typeof parsed.updated_at === 'string' ? parsed.updated_at
+                : typeof parsed.created_at === 'string' ? parsed.created_at : '';
+            if (!updatedAt || updatedAt > cutoff)
+                continue;
+            eligible.push({ filePath, content });
+        }
+        catch {
+            // Skip unparseable — a separate check (loadDirectoryItems) will surface it.
+        }
+    }
+    if (dryRun || eligible.length === 0) {
+        return { candidates: eligible.length, parked: 0 };
+    }
+    const archivePath = path.join(handoffsDir, 'compacted.jsonl');
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = path.join(cwd, '.brainclaw', 'gc-backups', `compact-handoffs-closed-${timestamp}.jsonl`);
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    let parked = 0;
+    for (const { filePath, content } of eligible) {
+        // Codex PR#48 finding 4: order the steps so a partial failure can never
+        // leave the source on disk AND its record already in the compaction log
+        // (which produced a duplicate compacted record on the next pass). The safe
+        // order is backup → unlink → archive:
+        //   1. backup first  — park-don't-delete safety net is written before any
+        //      removal, so the raw handoff is always recoverable.
+        //   2. unlink next    — if this throws, we do NOT archive, so no compacted
+        //      record exists for a source that is still present → no duplicate.
+        //   3. archive last   — if this throws after a successful unlink, the source
+        //      is gone (in the backup) and simply absent from compacted.jsonl; the
+        //      next pass cannot re-see it, so still no duplicate.
+        try {
+            const parsed = JSON.parse(content);
+            parsed._compacted_at = new Date().toISOString();
+            parsed._compaction_type = 'closed-auto-handoff';
+            fs.appendFileSync(backupPath, content.trim() + '\n', 'utf-8');
+            fs.unlinkSync(filePath);
+            fs.appendFileSync(archivePath, JSON.stringify(parsed) + '\n', 'utf-8');
+            parked += 1;
+        }
+        catch (err) {
+            logger.debug('parkClosedAutoHandoffs: failed to park', err);
+        }
+    }
+    return { candidates: eligible.length, parked, backup_path: backupPath };
+}
 /**
  * Deduplicate auto-generated session-end handoffs. These carry the same
  * commits list when several sessions close on the same project state, so the