brainclaw 1.17.0 → 1.19.0

package/dist/commands/mcp.js

@@ -27,7 +27,8 @@ import { switchProject } from './switch.js';
 import { assessBootstrapNeed, resolveEmptyMemoryRecommendation } from '../core/setup-flow.js';
 import { WorkRequestSchema } from '../core/facade-schema.js';
 import { codeMapWorkSection, codeMapRefreshNextActions } from '../core/code-map/work-section.js';
-import { sweepDeadPidRunningAgentRunsAtRead } from '../core/agentrun-reconciler.js';
+import { sweepDeadPidRunningAgentRunsAtRead, sweepTurnOwnedPreRunLeaseAtRead } from '../core/agentrun-reconciler.js';
+import { extractSuggestedTools, observeToolCall, recordSuggestion } from '../core/guidance-telemetry.js';
 import { bumpActiveAssignmentHeartbeat } from '../core/assignments.js';
 import { handleBclawAckMessage, handleBclawCoordinate, handleBclawDispatch, handleBclawLoop, handleBclawSendMessage, } from './mcp-write-coordination.js';
 import { ensureTrust, resolveMutationIdentity, explicitSessionIdFromEnv, projectInfoForCwd, scopeMetadataForTarget, } from './mcp-write-support.js';
@@ -1556,7 +1557,10 @@ async function _executeMcpToolCallInner(payload) {
             };
         }
         if (name === 'bclaw_coordinate') {
-            return await handleBclawCoordinate(args, { cwd, connectionSessionId, currentModel });
+            // pln#521 P1 — scopeInfo carries WHICH selector produced `cwd`, which the
+            // review open_loop project gate needs to distinguish a chosen project
+            // from the bare cwd fallback.
+            return await handleBclawCoordinate(args, { cwd, connectionSessionId, currentModel, effectiveScope: scopeInfo });
         }
         if (name === 'bclaw_loop') {
             return await handleBclawLoop(args, { cwd, connectionSessionId });
@@ -1871,7 +1875,21 @@ export async function executeMcpToolCall(payload) {
             sweepDeadPidRunningAgentRunsAtRead(cwd);
         }
         catch { /* best-effort */ }
+        // pln#630 PR2c-lease: converge turn-owned runs still `created`/`launching`
+        // on their dispatch/launch lease (inert until live turn-owned dispatch).
+        try {
+            sweepTurnOwnedPreRunLeaseAtRead(cwd);
+        }
+        catch { /* best-effort */ }
+    }
+    // pln#634 PR2 — guidance adherence. Judge the PREVIOUS response's suggestion
+    // against the call actually being made now, before delegating. Tool names
+    // only, never arguments or content. Best-effort: telemetry may not break a
+    // tool call.
+    try {
+        observeToolCall({ sessionId: effectiveConnectionSessionId, tool: payload.name, cwd });
     }
+    catch { /* never break the tool path */ }
     // ── Delegate to inner handler ───────────────────────────────────────────────
     const outcome = await _executeMcpToolCallInner({
         ...payload,
@@ -1879,6 +1897,15 @@ export async function executeMcpToolCall(payload) {
         connectionSessionId: effectiveConnectionSessionId,
         effectiveScope: effective,
     });
+    // Remember what THIS response suggested, so the next call can be judged.
+    try {
+        recordSuggestion({
+            sessionId: effectiveConnectionSessionId,
+            tool: payload.name,
+            suggested: extractSuggestedTools(outcome.response),
+        });
+    }
+    catch { /* never break the tool path */ }
     // Apply legacy deprecation warning uniformly (Phase 3 slice 3g). Read tools
     // already get it at line 2560; write tools historically did not. This
     // wrapper ensures every call through a deprecated name surfaces the

package/dist/commands/session-end.js

@@ -21,6 +21,8 @@ import { memoryExists } from '../core/io.js';
 import { buildOperationalIdentity, clearCurrentSession } from '../core/identity.js';
 import { buildContextDiff } from '../core/context-diff.js';
 import { listClaims, releaseClaim } from '../core/claims.js';
+import { reconcileClaimConformity } from '../core/claim-conformity.js';
+import { toWarningDetail } from '../core/warnings.js';
 import { listRuntimeNotes, saveRuntimeNote, generateRuntimeNoteId } from '../core/runtime.js';
 import { loadState, persistState } from '../core/state.js';
 import { listArchivedCandidates, listCandidates } from '../core/candidates.js';
@@ -147,6 +149,18 @@ export async function endSession(options = {}) {
     const state = loadState(options.cwd);
     const claimPlanIds = new Set(activeClaims.map((c) => c.plan_id).filter(Boolean));
     const inProgressPlans = state.plan_items.filter((p) => p.status === 'in_progress' && (p.assignee === registered.agent_name || claimPlanIds.has(p.id)));
+    // pln#636 C2 — sweep this session's own claims before auto-release closes
+    // them. session-end is the backstop trigger: it catches a claim whose worker
+    // neither released it via MCP nor reported through a LANE-RESULT.
+    const conformityWarnings = [];
+    for (const c of activeClaims) {
+        try {
+            const conformity = reconcileClaimConformity(c, options.cwd ?? process.cwd());
+            if (conformity.warning)
+                conformityWarnings.push(toWarningDetail(conformity.warning));
+        }
+        catch { /* advisory only — a session must always be able to end */ }
+    }
     let openWorkWarning;
     if (activeClaims.length > 0 || inProgressPlans.length > 0) {
         if (options.autoRelease) {
@@ -369,6 +383,7 @@ export async function endSession(options = {}) {
         open_work_warning: openWorkWarning,
         session_stats: sessionStats,
         compaction_hint: compactionHint,
+        ...(conformityWarnings.length ? { scope_warnings: conformityWarnings } : {}),
         ...(reflectedHandoff ? { handoff: reflectedHandoff } : {}),
     };
     // pln#564 — session_end pushes the agent into a short dogfooding reflection

package/dist/commands/session-start.js

@@ -18,6 +18,9 @@ import { auditLocalAgentWorkspaceFiles } from '../core/agent-files.js';
 import { buildAgentInventory, loadAgentInventory, saveAgentInventory, diffInventory } from '../core/agent-inventory.js';
 import { checkMemoryPressure, enforceRuntimeNoteRetention, parkClosedAutoHandoffs } from '../core/gc-semantic.js';
 import { sweepAssignments } from '../core/assignment-sweeper.js';
+import { getInstalledBrainclawVersion } from '../core/brainclaw-version.js';
+import { reconcileSurfaceFreshness, staleSurfaceWarning } from '../core/surface-freshness.js';
+import { toWarningDetail } from '../core/warnings.js';
 import { loadHygienePolicy } from '../core/hygiene-policy.js';
 import { maybeCreateCheckpoint } from '../core/events/checkpoint.js';
 import { pullSignalsFromLinkedProjects, markSignalProcessed } from '../core/federation-transport.js';
@@ -282,6 +285,21 @@ export async function startSession(options = {}) {
         }
         catch { /* non-fatal */ }
     }
+    // pln#638 volet 2b — LAZY freshness reconcile of the generated guidance
+    // surfaces. session-start is the right trigger because it is the moment the
+    // agent is about to READ that guidance, and it is a path we already visit — no
+    // daemon, no watcher (feedback_lazy_reconcile_pattern). Advisory only: nothing
+    // is regenerated here, because regeneration is an explicit act and silently
+    // rewriting a file the operator may have edited would be worse than a warning.
+    let staleSurfaces;
+    if (maintenanceMode === 'full') {
+        try {
+            const currentVersion = getInstalledBrainclawVersion();
+            const freshness = reconcileSurfaceFreshness(options.cwd ?? process.cwd(), currentVersion);
+            staleSurfaces = staleSurfaceWarning(freshness, currentVersion);
+        }
+        catch { /* non-fatal */ }
+    }
     // Materialize incoming federation signals from linked projects (Phase 0 — local)
     if (maintenanceMode === 'full') {
         try {
@@ -338,6 +356,7 @@ export async function startSession(options = {}) {
         ...(sharedCheckoutWarning ? { shared_checkout_warning: sharedCheckoutWarning } : {}),
         ...(staleClaimsReleased ? { stale_claims_released: staleClaimsReleased } : {}),
         ...(memoryPressure ? { memory_pressure: memoryPressure } : {}),
+        ...(staleSurfaces ? { stale_surfaces: toWarningDetail(staleSurfaces) } : {}),
         ...(autoRegistered ? { auto_registered: true } : {}),
     };
 }

package/dist/core/agentrun-reconciler.js

@@ -38,7 +38,8 @@ import { loadClaim, releaseClaim } from './claims.js';
 import { loadAssignment } from './assignments.js';
 import { createRuntimeEvent } from './events.js';
 import { nowISO } from './ids.js';
-import { readHeartbeat, readLogTail, signalExists, latestActivityMs } from './runtime-signals.js';
+import { readHeartbeat, readLogTail, signalExists, latestActivityMs, readCompletionSignals } from './runtime-signals.js';
+import { findReservationByRunId, evidenceMatchesAttempt, launchGrant, revokeLaunchGrant } from './loops/attempt-reservation.js';
 // ── Constants ──────────────────────────────────────────────────────────────
 /**
  * Minimum age before a run is eligible for reconciliation. Below this, the
@@ -188,9 +189,51 @@ export function collectEvidence(run, cwd, options) {
             fs_activity_age_ms = now - lastFs;
     }
     catch { /* defensive */ }
+    // pln#630 PR2b-c (§13 R3) — read-strict gate. A run owned by a turn-attempt
+    // reservation is completed ONLY on turn-keyed evidence: a `completed` sentinel
+    // body whose turn_id/run_id/nonce match the attempt's CURRENT launch
+    // generation. A bare assignment-keyed presence sentinel — or a stale prior
+    // generation's body — never counts (closes phantom-completion). Legacy runs
+    // (no owning reservation) keep presence-based acceptance.
+    let turn_owned = false;
+    let turn_keyed_completed = false;
+    try {
+        const reservation = findReservationByRunId(run.id, cwd);
+        if (reservation) {
+            turn_owned = true;
+            const bodies = readCompletionSignals(signalRoot, run.assignment_id);
+            // Evidence must be turn-keyed AND carry the RIGHT status (a `.completed`
+            // file whose body says status:'failed' is not completion evidence —
+            // read-strict trusts the body, not the filename, review PR2b-c #C2).
+            const matchedCompleted = bodies.completed !== undefined
+                && bodies.completed.status === 'completed'
+                && evidenceMatchesAttempt(reservation, bodies.completed);
+            const matchedFailed = bodies.failed !== undefined
+                && bodies.failed.status === 'failed'
+                && evidenceMatchesAttempt(reservation, bodies.failed);
+            if (matchedCompleted && matchedFailed) {
+                // §13 R4 — a completed+failed contradiction WITHHOLDS both (never a
+                // silent accept). Conflict-event journaling is deferred to
+                // reconcileTurn (PR3); collectEvidence stays side-effect-free.
+                turn_keyed_completed = false;
+                failed_signal = false;
+            }
+            else {
+                turn_keyed_completed = matchedCompleted;
+                // Read-strict governs FAILURE too for a turn-owned run: override the
+                // presence-based failed_signal so a stale/legacy bare `.failed` marker
+                // cannot phantom-FAIL a healthy generation (symmetric to completed,
+                // review PR2b-c #B). A genuine death with no turn-keyed evidence still
+                // fails via the process-dead + stale path below.
+                failed_signal = matchedFailed;
+            }
+        }
+    }
+    catch { /* defensive — fall back to legacy (non-turn-owned) behavior */ }
     return {
         age_ms, has_post_start_commit, claim_released, assignment_completed, process_alive,
         completed_signal, failed_signal, heartbeat_exists, heartbeat_age_ms, fs_activity_age_ms,
+        turn_owned, turn_keyed_completed,
     };
 }
 /**
@@ -209,7 +252,7 @@ function fsActiveWithin(evidence, windowMs) {
  * Inference only fires after the stale window with no life evidence, so this is
  * conservative. (Loop auto-close on failure is a follow-up.)
  */
-function cascadeReleaseOnFailure(run, actor, cwd) {
+function cascadeReleaseOnFailure(run, actor, cwd, terminalStatus = 'failed') {
     if (!run.claim_id)
         return;
     try {
@@ -219,8 +262,8 @@ function cascadeReleaseOnFailure(run, actor, cwd) {
             createRuntimeEvent({
                 agent: actor,
                 session_id: run.session_id,
-                event_type: 'run_failed',
-                text: `Auto-released claim ${run.claim_id} after run ${run.id} was reconciled to failed (trp#433 GC cascade)`,
+                event_type: terminalStatus === 'cancelled' ? 'run_cancelled' : 'run_failed',
+                text: `Auto-released claim ${run.claim_id} after run ${run.id} was reconciled to ${terminalStatus} (trp#433 GC cascade)`,
                 tags: ['reconciler', 'gc', 'claim-release'],
                 assignment_id: run.assignment_id,
                 run_id: run.id,
@@ -232,6 +275,13 @@ function cascadeReleaseOnFailure(run, actor, cwd) {
     catch { /* best-effort — never let GC break reconciliation */ }
 }
 function anyCompletionEvidence(evidence) {
+    // pln#630 PR2b-c (§13 R3): a turn-owned run is completed ONLY on turn-keyed
+    // evidence — never a bare presence sentinel or an assignment-keyed proxy
+    // (claim_released / assignment_completed / post_start_commit). This is the
+    // read-strict split that closes the stale-sentinel + presence-only
+    // phantom-completion holes. Legacy (non-turn-owned) runs are unchanged.
+    if (evidence.turn_owned)
+        return evidence.turn_keyed_completed;
     return evidence.completed_signal
         || evidence.has_post_start_commit
         || evidence.claim_released
@@ -345,7 +395,7 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
         const evidence = {
             age_ms: 0, has_post_start_commit: false, claim_released: false,
             assignment_completed: false, process_alive: undefined,
-            completed_signal: false, failed_signal: false, heartbeat_exists: false,
+            completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false,
         };
         return {
             run_id: runId, action: 'no_op', reason: 'run not found', evidence,
@@ -361,6 +411,18 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
             evidence, previous_status, current_status: run.status,
         };
     }
+    // pln#630 PR2c-lease (§4 + R5): a turn-owned run preallocated `created`/
+    // `launching` converges on its DISPATCH/LAUNCH LEASE, not the pid/heartbeat
+    // heuristics below (which assume a worker already spawned and can emit
+    // life-signs). Delegate before the generic evidence path so these runs never
+    // orphan `created`/`launching` forever. Inert for non-turn-owned runs
+    // (evidence.turn_owned=false → fall through to the unchanged generic path).
+    if ((run.status === 'created' || run.status === 'launching') && evidence.turn_owned) {
+        const reservation = findReservationByRunId(run.id, cwd);
+        if (reservation) {
+            return reconcileTurnOwnedPreRunLease(run, reservation, evidence, cwd, options);
+        }
+    }
     const grace = options.healthCheckGraceMs ?? DEFAULT_HEALTH_CHECK_GRACE_MS;
     const stale = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
     const actor = options.actor ?? 'reconciler';
@@ -450,6 +512,84 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
         evidence, previous_status, current_status: run.status,
     };
 }
+/**
+ * pln#630 PR2c-lease (§4 + R5) — converge a TURN-OWNED run still in `created`/
+ * `launching` against its dispatch/launch LEASE, not the pid/heartbeat heuristics
+ * (which presuppose a spawned, life-sign-emitting worker). Reached only from
+ * `reconcileAgentRun`'s turn-owned delegate branch, so it always has the owning
+ * reservation + pre-collected evidence.
+ *
+ * Outcomes (never `completed` — no phantom success from an unspawned/unproven run):
+ *   - turn-keyed completion present → NO-OP (finalization is reconcileTurn's job, PR3);
+ *   - within lease → NO-OP (the worker may yet cross the launch fence / start);
+ *   - past lease + launch grant CROSSED → `failed` / `launch_attempted_unknown`
+ *     (the worker WAS invoked; its outcome is unknowable, so it must not complete);
+ *   - past lease + grant not crossed → `cancelled` / `reserved_never_launched`
+ *     (no launch receipt — nothing ran; matches attemptStatus(revoked)='cancelled').
+ */
+function reconcileTurnOwnedPreRunLease(run, reservation, evidence, cwd, options) {
+    const now = options.nowMs ?? Date.now();
+    const actor = options.actor ?? 'reconciler';
+    const previous_status = run.status;
+    // A genuine turn-keyed completion is NOT an expiry: never fail/cancel a run
+    // that produced accepted evidence. Its finalization (assignment/claim/artifacts)
+    // is reconcileTurn's responsibility (PR3); here we simply decline to expire it.
+    if (evidence.turn_keyed_completed) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: 'turn-keyed completion present — defer finalization to reconcileTurn',
+            evidence, previous_status, current_status: run.status,
+        };
+    }
+    // Effective deadline: once armed, the launch lease is the tighter authoritative
+    // bound; before arm, the dispatch lease bounds how long a committed reservation
+    // may wait to spawn. A non-parseable lease cannot expire a run (fail-safe: leave
+    // it for explicit reconcile rather than converge on garbage).
+    const leaseISO = reservation.launch?.lease_deadline ?? reservation.lease_deadline;
+    const leaseMs = Date.parse(leaseISO);
+    if (!Number.isFinite(leaseMs) || now < leaseMs) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: Number.isFinite(leaseMs)
+                ? `within lease (deadline ${leaseISO})`
+                : `lease deadline unparseable (${leaseISO}) — cannot expire`,
+            evidence, previous_status, current_status: run.status,
+        };
+    }
+    // Past lease, no accepted completion — the launch-grant status (authoritative,
+    // decision-file reconciled) decides the terminal.
+    const grant = launchGrant(reservation.turn_id, cwd);
+    const crossed = grant?.status === 'crossed';
+    const targetStatus = crossed ? 'failed' : 'cancelled';
+    const action = crossed ? 'inferred_failed' : 'inferred_cancelled';
+    const reason = crossed
+        ? `launch_attempted_unknown: launch grant crossed but run never reached running by lease ${leaseISO} — outcome unknown, never completed`
+        : `reserved_never_launched: no launch receipt by lease ${leaseISO} (grant=${grant?.status ?? 'none'})`;
+    // pln#630 dec#149 R1 (review Finding 2) — make the reserved_never_launched strand REACHABLE
+    // through the WIRED lazy reconciler: revoke the still-armed grant so its authoritative status
+    // becomes `revoked`. That is what lets reconcileTurn's fix-cycle strand detector see the strand
+    // and re-emit, and lets the re-dispatch re-arm a fresh generation (dec#149 R1). Idempotent +
+    // best-effort: a race to crossed/revoked is fine (the decision file governs) and must never
+    // block the run's terminal transition below.
+    if (!crossed && grant?.status === 'armed') {
+        try {
+            revokeLaunchGrant(reservation.turn_id, grant.epoch, 'reserved_never_launched', cwd, actor);
+        }
+        catch { /* raced to crossed/revoked — authoritative status governs */ }
+    }
+    try {
+        transitionAgentRun(run.id, targetStatus, { actor, status_reason: reason }, cwd);
+        cascadeReleaseOnFailure(run, actor, cwd, targetStatus);
+        return { run_id: run.id, action, reason, evidence, previous_status, current_status: targetStatus };
+    }
+    catch (err) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: `lease-expiry transition rejected: ${err instanceof Error ? err.message : String(err)}`,
+            evidence, previous_status, current_status: run.status,
+        };
+    }
+}
 /**
  * Read-path reconciliation for a `running` run whose tracked PID reads dead.
  *
@@ -478,7 +618,7 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
         const evidence = {
             age_ms: 0, has_post_start_commit: false, claim_released: false,
             assignment_completed: false, process_alive: undefined,
-            completed_signal: false, failed_signal: false, heartbeat_exists: false,
+            completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false,
         };
         return {
             run_id: runId, action: 'no_op', reason: 'run not found', evidence,
@@ -610,6 +750,30 @@ export function sweepDeadPidRunningAgentRunsAtRead(cwd, options = {}) {
         .slice(0, limit);
     return candidates.map((run) => reconcileDeadPidRunningAgentRunAtRead(run.id, cwd, options));
 }
+/**
+ * pln#630 PR2c-lease — lazy read-path sweep for TURN-OWNED runs still in
+ * `created`/`launching`, converging them on their dispatch/launch lease via
+ * `reconcileAgentRun`'s turn-owned delegate. Strictly turn-owned: a legacy
+ * (non-reservation-owned) `created`/`launching` run is SKIPPED here, so this
+ * sweep changes nothing for existing runs and is fully inert until live
+ * turn-owned dispatch (PR2c-b) mints such a run. Errors are isolated per run.
+ */
+export function sweepTurnOwnedPreRunLeaseAtRead(cwd, options = {}) {
+    const results = [];
+    for (const status of ['created', 'launching']) {
+        for (const run of listAgentRuns(cwd, { status })) {
+            // Only turn-owned runs converge on the lease here — legacy runs keep their
+            // existing (non-read-path) reconciliation route untouched.
+            if (!findReservationByRunId(run.id, cwd))
+                continue;
+            try {
+                results.push(reconcileAgentRun(run.id, cwd, options));
+            }
+            catch { /* best-effort — never block reads on reconciliation errors */ }
+        }
+    }
+    return results;
+}
 /**
  * Reconcile every non-terminal agent_run matching `filter`. Useful for
  * batch sweeps from `bclaw_assignment_events` or `brainclaw doctor --dispatch`.
@@ -628,7 +792,7 @@ export function reconcileAllOpenRuns(cwd, filter = {}, options = {}) {
             catch {
                 results.push({
                     run_id: run.id, action: 'no_op', reason: 'reconcile threw — skipped',
-                    evidence: { age_ms: 0, has_post_start_commit: false, claim_released: false, assignment_completed: false, process_alive: undefined, completed_signal: false, failed_signal: false, heartbeat_exists: false },
+                    evidence: { age_ms: 0, has_post_start_commit: false, claim_released: false, assignment_completed: false, process_alive: undefined, completed_signal: false, failed_signal: false, heartbeat_exists: false, turn_owned: false, turn_keyed_completed: false },
                     previous_status: run.status, current_status: run.status,
                 });
             }

package/dist/core/agentruns.js

@@ -101,7 +101,12 @@ export function findLatestAgentRunForAssignment(assignmentId, cwd) {
     })[0];
 }
 const VALID_TRANSITIONS = new Map([
-    ['created', new Set(['launching', 'waiting_input', 'running', 'cancelled', 'interrupted'])],
+    // `failed` added (pln#630 PR2c-lease): a turn-owned run preallocated `created`
+    // whose launch grant CROSSED but crashed before the created→launching
+    // transition is `launch_attempted_unknown` — a failure, reconciled straight
+    // from `created`. (reserved_never_launched, where the grant never crossed,
+    // goes to `cancelled`, already permitted.)
+    ['created', new Set(['launching', 'waiting_input', 'running', 'failed', 'cancelled', 'interrupted'])],
     ['launching', new Set(['waiting_input', 'running', 'failed', 'cancelled', 'timed_out', 'interrupted'])],
     ['waiting_input', new Set(['launching', 'running', 'blocked', 'cancelled', 'timed_out', 'interrupted'])],
     ['running', new Set(['blocked', 'completed', 'failed', 'cancelled', 'timed_out', 'interrupted'])],

package/dist/core/claim-conformity.js

@@ -0,0 +1,193 @@
+/**
+ * pln#636 C2 — server-side lazy conformity reconcile.
+ *
+ * WHY SERVER-SIDE AT ALL. C1's PreToolUse hook only reaches hook-capable hosts.
+ * The workers that most need a scope signal are the ones that reach nothing: a
+ * spawned sandboxed lane never sees MCP, never loads a hook, and reports through
+ * a file. So the universal net has to live where the *outcome* is ingested, not
+ * where the write happens. Reconcile at the lifecycle boundaries every tier
+ * eventually crosses — release, assignment completion, harvest ingestion,
+ * session end — per the validated lazy-reconcile pattern. No daemon, no watcher.
+ *
+ * WHY POST-HOC IS THE HONEST SHAPE. By the time any of these fire the write has
+ * already landed. The only truthful output is an advisory that names the strays
+ * and the two calls that resolve them — never an error, never a block
+ * (trp_5f342186 is the scar tissue).
+ *
+ * THE BASELINE PROBLEM, and why `base_sha` exists (C0-b, review F3). Neither
+ * `git diff HEAD` nor the worktree's dirty set is authoritative: a lane that
+ * commits mid-work moves the ground under both, so the same claim would read
+ * "touched nothing" the moment it committed. The comparison runs against the
+ * commit recorded at claim creation — a fixed point — and unions in the dirty
+ * set so uncommitted work counts too.
+ *
+ * SILENT ON DOUBT. Every degradation path (no baseline, no git, detached
+ * worktree, unreadable repo) yields `unverifiable`, which emits NOTHING. The
+ * acceptance bar for this whole design is a zero false-positive rate on the real
+ * 613-claim corpus, and 42.4% of that corpus is not path-resolvable at all.
+ *
+ * @module
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { assessScopeConformity } from './claim-scope.js';
+/** Cap on how many stray paths ride along in a warning payload. */
+const MAX_REPORTED_PATHS = 10;
+/**
+ * Run git and return stdout, or undefined on ANY failure.
+ *
+ * Never throws and never inspects stderr: a conformity nicety may not degrade
+ * the workflow it observes, so an unavailable git, a detached worktree or a
+ * garbage-collected branch all read as "cannot tell".
+ */
+function git(cwd, args) {
+    try {
+        const r = spawnSync('git', args, { cwd, encoding: 'utf-8', windowsHide: true });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return undefined;
+        return r.stdout;
+    }
+    catch {
+        return undefined;
+    }
+}
+function splitPaths(out) {
+    if (!out)
+        return [];
+    return out.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+}
+/**
+ * Split WITHOUT trimming, for `--porcelain` output.
+ *
+ * The porcelain prefix is fixed-width — status codes in columns 1-2, a space in
+ * column 3, path from index 3 — so a leading space is DATA. Trimming ` M
+ * src/x.ts` first turns the subsequent `slice(3)` into `rc/x.ts`: a path that
+ * matches no pathspec and reads as a stray, i.e. a false accusation on every
+ * unstaged edit.
+ */
+function splitLinesRaw(out) {
+    if (!out)
+        return [];
+    return out.split(/\r?\n/).filter((l) => l.trim().length > 0);
+}
+/**
+ * Where a claim's work physically happened: its own worktree when it has one,
+ * otherwise the project root. A lane claim's diff is meaningless read from the
+ * coordinator's checkout.
+ */
+function claimWorkdir(claim, cwd) {
+    const dir = claim.worktree_path ?? cwd;
+    try {
+        return fs.existsSync(dir) ? dir : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Files this claim's worker touched since the claim was created.
+ *
+ * Union of two sources, because either alone lies:
+ *  - `git diff --name-only <base_sha>` — everything committed since the
+ *    baseline, which the dirty set loses the instant a lane commits.
+ *  - `git status --porcelain` — uncommitted work, which the diff cannot see.
+ *
+ * A claim with no `base_sha` (created outside a repo, or before C0-b shipped) is
+ * unverifiable rather than compared against a guessed baseline.
+ */
+export function collectTouchedPaths(claim, cwd) {
+    const workdir = claimWorkdir(claim, cwd);
+    if (!workdir)
+        return { paths: [], unverifiableReason: 'claim worktree no longer exists' };
+    if (!claim.base_sha)
+        return { paths: [], unverifiableReason: 'claim has no recorded base_sha baseline' };
+    // Confirm the baseline is still reachable before trusting a diff against it —
+    // a pruned worktree branch would otherwise make git fail and read as "clean".
+    if (git(workdir, ['cat-file', '-e', `${claim.base_sha}^{commit}`]) === undefined) {
+        return { paths: [], unverifiableReason: 'recorded base_sha is no longer reachable in this worktree' };
+    }
+    const committed = splitPaths(git(workdir, ['diff', '--name-only', claim.base_sha]));
+    // -uall so a whole new untracked directory is reported file-by-file rather
+    // than collapsed to its directory name, which no pathspec would match.
+    const dirty = splitLinesRaw(git(workdir, ['status', '--porcelain', '-uall']))
+        .map((line) => line.slice(3).trim())
+        // A rename reads `R  old -> new`; the destination is what was written.
+        .map((p) => (p.includes(' -> ') ? p.split(' -> ')[1] : p))
+        .map((p) => p.replace(/^"|"$/g, ''));
+    const paths = [...new Set([...committed, ...dirty])].filter((p) => p.length > 0);
+    return { paths };
+}
+function widenNextActions(claim, unexpected) {
+    return [
+        {
+            tool: 'bclaw_update',
+            args: {
+                entity: 'claim',
+                id: claim.id,
+                // Widening means declaring the footprint, not rewriting the prose scope:
+                // `paths[]` is the machine-readable half (C0-b) and is additive.
+                paths: unexpected.slice(0, MAX_REPORTED_PATHS),
+            },
+            when: 'the work legitimately spans these paths — declare them so the next reconcile is silent',
+        },
+        {
+            tool: 'bclaw_create',
+            args: {
+                entity: 'trap',
+                title: `Work on ${claim.scope} pulls in ${unexpected[0]}`,
+                body: 'Recurring coupling found by a claim-scope reconcile. Record why these move together.',
+            },
+            when: 'the strays reveal a real coupling worth warning the next agent about',
+        },
+    ];
+}
+export function reconcileClaimConformity(claim, cwd, options = {}) {
+    const touched = options.touchedPaths
+        ? { paths: [...options.touchedPaths].filter((p) => p.trim().length > 0) }
+        : collectTouchedPaths(claim, cwd);
+    if (touched.unverifiableReason) {
+        return {
+            verdict: { kind: 'unverifiable', reason: touched.unverifiableReason },
+            touchedPaths: [],
+        };
+    }
+    // A declared `paths[]` footprint is the claim's own machine-readable statement
+    // of intent, so it outranks the prose scope when present — that is the entire
+    // reason C0-b made it optional-but-additive.
+    //
+    // Comma, not space: `resolveScopeToPathspecs` splits on ',' and treats any
+    // whitespace inside a token as proof of prose (dirty-scope.ts:143-154), so a
+    // space-joined list would silently classify as unverifiable.
+    const declared = claim.paths?.length ? claim.paths.join(',') : claim.scope;
+    const verdict = assessScopeConformity({
+        scope: declared,
+        cwd: claimWorkdir(claim, cwd) ?? cwd,
+        touchedPaths: touched.paths,
+    });
+    if (verdict.kind !== 'out_of_scope') {
+        return { verdict, touchedPaths: touched.paths };
+    }
+    const shown = verdict.unexpected.slice(0, MAX_REPORTED_PATHS);
+    const overflow = verdict.unexpected.length - shown.length;
+    return {
+        verdict,
+        touchedPaths: touched.paths,
+        warning: {
+            code: 'wrote_outside_claim_scope',
+            message: `Claim ${claim.id} declared '${claim.scope}' but ${verdict.unexpected.length} touched `
+                + `file(s) sit outside it: ${shown.join(', ')}`
+                + (overflow > 0 ? ` (+${overflow} more)` : '')
+                + '. Advisory only — the work is already written.',
+            data: {
+                claim_id: claim.id,
+                scope: claim.scope,
+                declared_pathspecs: verdict.pathspecs,
+                unexpected_paths: shown,
+                ...(overflow > 0 ? { unexpected_paths_omitted: overflow } : {}),
+                base_sha: claim.base_sha,
+            },
+            next_actions: widenNextActions(claim, verdict.unexpected),
+        },
+    };
+}
+//# sourceMappingURL=claim-conformity.js.map