brainclaw 1.12.0 → 1.14.0

package/README.md

@@ -66,6 +66,20 @@ Capable agents use the MCP equivalents `bclaw_code_find` / `bclaw_code_brief`, e
 
 ---
 
+## Measured agent experience
+
+The onboarding path a fresh agent takes — init, first `bclaw_work`, first `code_find` — is exercised on every CI run by a reproducible bench (`scripts/bench.mjs`) against a synthetic store calibrated on the shape of a real production project (~200 plans, ~500 handoffs, ~450 claims). Budgets (`bench-budgets.json`) live in the repo alongside the coverage gate; a regression beyond a per-scenario tolerance fails the build. The latest report ships as `dist/facts.json` under `facts.bench` so the site can render current numbers.
+
+The bench covers three scenarios:
+
+- **Cold onboard** — fresh machine → init → first useful context. Measures the baseline time-to-first-value.
+- **Warm work** — `bclaw_work` consult over a real-shaped store. Tracks the cost of building context when the store is non-empty (the surface `pln#578`/`pln#566` optimise).
+- **First edit** — `code_find` + `code_brief` on the fresh-agent path. Tracks payload compactness (`pln#598`) and match relevance (`pln#601`).
+
+Reproduce locally with `npm run bench` (writes `dist/bench-report.json`); check budgets with `npm run bench:check`. The bench runs in-process against synthetic fixtures, so it is deterministic per seed and safe to run on any machine.
+
+---
+
 ## Agent Surfaces
 
 brainclaw exposes the same collaboration state through three surfaces, but they do not have the same role in an agent-first workflow.
@@ -417,6 +431,32 @@ 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:
+
+- **Model selection for codex and copilot spawns** (pln#606) — `dispatch run --model <m>` now reaches codex (`exec -m`) and copilot argv, verified on the installed binaries. The codex `--add-dir` writable-roots spike closed negative on Windows: file-first stays the codex transport.
+- **Auto-repair identity & session on canonical writes** (pln#608) — `bclaw_create`/`update`/`remove`/`transition` auto-register + auto-session instead of throwing "Start a session first", with an explicit `session auto-created` warning; the trust boundary for unknown identities is unchanged.
+- **Time-to-first-value benchmark with blocking CI budgets** (pln#604) — seeded synthetic stores, three scenarios (cold_onboard / warm_work / first_edit), budgets versioned in `bench-budgets.json`.
+- **Claim lifecycle parity** (trp#928) — `bclaw_transition(entity='claim')` wired, `coordinator_override` (trusted+) on release/transition, cascade release with per-claim logging on plan-done / loop close / assignment-completed / harvest, entity-scoped `bclaw_find` filter rejections.
+- **Squash-aware worktree GC + junction-safe removal** (trp#926) — squash-merged lanes are finally collected (content-based detection), and the Windows `node_modules`-junction wipe class is closed for good; `dispatch_status` compares against the worktree's creation ref.
+- **VS Code extension** — Backlog pagination (recent plans were invisible, trp#925) and probe/spawn parity with classified, actionable resolver failures (trp#927).
+- **Context read 2× faster on large stores** (pln#578) — 3 of the 4 full-store read passes per context build eliminated (disabled-reputation sweep ×2, estimation reload, triple candidate scan): 23.9 s → 11.9 s, 196 MB → 49 MB parsed, byte-identical output.
+
+### v1.12.0
+
+Auto-localized execution writes for multi-project workspaces (pln#597), from DGX-Spark dogfooding:
+
+- **Execution writes auto-localize into a workspace sibling named by `project=X`** — `bclaw_create`/`bclaw_transition` (plan & claim), `bclaw_claim`, the step tools and `bclaw_delete_plan` open a session + sticky switch into a workspace store-chain child instead of rejecting with "limited to signaling entities", echoing `auto_switched`. The signaling-vs-execution boundary is re-scoped to federation (`cross_project_links`): federated links and unknown names stay blocked.
+
 ### v1.11.1
 
 Agent-identity & session-hook resilience, from a fresh-CLI dogfood on a monorepo:

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
@@ -1179,10 +1180,16 @@ program
     .option('--all', 'Include released claims in list')
     .option('--json', 'Output as JSON for list')
     .option('--plan-status <status>', 'Optional linked plan status when releasing: todo, in_progress, blocked, done, dropped')
+    .option('--coordinator-override', 'Trusted+ only: release a claim owned by another agent')
     .option('--store <target>', 'Target store level: local (default), repo, workspace')
     .option('--local-only', 'Read from local store only for list (skip parent stores in chain)')
     .action((subcommand, args, options) => {
-    runClaimResource(subcommand, args, { ...options, planStatus: options.planStatus, localOnly: options.localOnly });
+    runClaimResource(subcommand, args, {
+        ...options,
+        planStatus: options.planStatus,
+        coordinatorOverride: options.coordinatorOverride,
+        localOnly: options.localOnly,
+    });
 });
 // --- assignment ---
 program
@@ -1222,8 +1229,9 @@ program
     .command('release-claim <id>')
     .description('Release a work claim')
     .option('--plan-status <status>', 'Optional linked plan status: todo, in_progress, blocked, done, dropped')
+    .option('--coordinator-override', 'Trusted+ only: release a claim owned by another agent')
     .action((id, options) => {
-    runReleaseClaim(id, options);
+    runReleaseClaim(id, { ...options, coordinatorOverride: options.coordinatorOverride });
 });
 // --- release-claims ---
 program

package/dist/commands/claim-resource.js

@@ -36,6 +36,7 @@ export function runClaimResource(subcommand, args, options) {
         }
         runReleaseClaim(id, {
             planStatus: options.planStatus,
+            coordinatorOverride: options.coordinatorOverride,
             cwd: options.cwd,
         });
         return;

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/estimation-report.js

@@ -104,7 +104,7 @@ export function renderRatioBar(ratio, width = 40) {
     return bar;
 }
 export function buildEstimationReport(options = {}) {
-    const state = loadState(options.cwd);
+    const state = options.state ?? loadState(options.cwd);
     const done = state.plan_items.filter((p) => p.status === 'done' && (!options.agent || p.author === options.agent));
     const entries = done.map((p) => {
         // Estimate: prefer the sum of per-step estimates when ALL steps carry one,

package/dist/commands/harvest.js

@@ -19,15 +19,21 @@ import { listCandidates, listArchivedCandidates, saveCandidate } from '../core/c
 import { createRuntimeEvent } from '../core/events.js';
 import { memoryExists } from '../core/io.js';
 import { loadAssignment, transitionAssignment } from '../core/assignments.js';
-import { releaseClaimWithCascade, loadClaim } from '../core/claims.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 })
@@ -438,12 +444,16 @@ export function integrateLaneResults(options = {}) {
                     ...entry.files_changed.slice(0, 50).map((f) => ({ type: 'file', ref: f })),
                 ];
                 entry.assignment_completed = forceCompleteAssignment(lane.assignment_id, artifacts, `pln#534 on-behalf integration: ${lane.summary.slice(0, 120)}`, actor, cwd);
-                try {
-                    const rel = releaseClaimWithCascade(assignment.claim_id, { planStatus: 'done', cwd });
-                    entry.claim_released = rel.claim.status === 'released';
-                }
-                catch (err) {
-                    reasons.push(`claim release failed: ${err instanceof Error ? err.message : String(err)}`);
+                // trp#928 — use the cascade helper (was releaseClaimWithCascade — same
+                // logic for the last-claim rule but the cascade wrapper LOGS per-claim,
+                // so a silent ownership failure is observable in the runtime event log
+                // rather than only in this in-memory `reasons` string).
+                const cascade = releaseClaimsCascade([assignment.claim_id], { cwd, planStatus: 'done' });
+                logCascadeReleaseResult({ actor, trigger: 'harvest_integrate', assignment_id: lane.assignment_id, claim_id: assignment.claim_id, cascade, cwd });
+                const claimEntry = cascade.entries[0];
+                entry.claim_released = claimEntry?.released === true;
+                if (claimEntry && !claimEntry.released) {
+                    reasons.push(`claim release ${claimEntry.reason}${claimEntry.error ? `: ${claimEntry.error}` : ''}`);
                 }
             }
             else {
@@ -455,15 +465,15 @@ export function integrateLaneResults(options = {}) {
                 catch (err) {
                     reasons.push(`assignment ${target} transition rejected: ${err instanceof Error ? err.message : String(err)}`);
                 }
-                try {
-                    const rel = releaseClaimWithCascade(assignment.claim_id, {
-                        planStatus: lane.status === 'blocked' ? 'blocked' : undefined,
-                        cwd,
-                    });
-                    entry.claim_released = rel.claim.status === 'released';
-                }
-                catch (err) {
-                    reasons.push(`claim release failed: ${err instanceof Error ? err.message : String(err)}`);
+                const cascade = releaseClaimsCascade([assignment.claim_id], {
+                    cwd,
+                    planStatus: lane.status === 'blocked' ? 'blocked' : undefined,
+                });
+                logCascadeReleaseResult({ actor, trigger: 'harvest_integrate', assignment_id: lane.assignment_id, claim_id: assignment.claim_id, cascade, cwd });
+                const claimEntry = cascade.entries[0];
+                entry.claim_released = claimEntry?.released === true;
+                if (claimEntry && !claimEntry.released) {
+                    reasons.push(`claim release ${claimEntry.reason}${claimEntry.error ? `: ${claimEntry.error}` : ''}`);
                 }
             }
             // Durable trace of the integration.
@@ -615,12 +625,16 @@ export function harvestOrphaned(options) {
                 ...report.files_changed.slice(0, 50).map((f) => ({ type: 'file', ref: f })),
             ];
             report.assignment_completed = forceCompleteAssignment(options.assignmentId, artifacts, 'pln#554 harvest --orphaned: worker died before delivering; work recovered from worktree', actor, cwd);
-            try {
-                const rel = releaseClaimWithCascade(assignment.claim_id, { planStatus: 'done', cwd });
-                report.claim_released = rel.claim.status === 'released';
-            }
-            catch (err) {
-                report.errors.push(`claim release failed: ${err instanceof Error ? err.message : String(err)}`);
+            // trp#928 — log per-claim via releaseClaimsCascade instead of the raw
+            // releaseClaimWithCascade so an ownership_denied outcome is visible in the
+            // runtime event log (previously trapped into report.errors only, which
+            // dies with the CLI invocation).
+            const cascade = releaseClaimsCascade([assignment.claim_id], { cwd, planStatus: 'done' });
+            logCascadeReleaseResult({ actor, trigger: 'harvest_integrate', assignment_id: options.assignmentId, claim_id: assignment.claim_id, cascade, cwd });
+            const claimEntry = cascade.entries[0];
+            report.claim_released = claimEntry?.released === true;
+            if (claimEntry && !claimEntry.released) {
+                report.errors.push(`claim release ${claimEntry.reason}${claimEntry.error ? `: ${claimEntry.error}` : ''}`);
             }
         }
         else {