brainclaw 1.18.0 → 1.19.0

package/dist/commands/mcp.js

@@ -28,6 +28,7 @@ import { assessBootstrapNeed, resolveEmptyMemoryRecommendation } from '../core/s
 import { WorkRequestSchema } from '../core/facade-schema.js';
 import { codeMapWorkSection, codeMapRefreshNextActions } from '../core/code-map/work-section.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';
@@ -1881,6 +1882,14 @@ export async function executeMcpToolCall(payload) {
         }
         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,
@@ -1888,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/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

package/dist/core/claim-scope.js

@@ -0,0 +1,155 @@
+/**
+ * pln#636 C0-a — claim scope grammar + conformity verdict.
+ *
+ * WHY THIS IS SMALL. The design originally called for a fresh classifier. It is
+ * not needed: `resolveScopeToPathspecs` (core/dirty-scope.ts) already resolves a
+ * free-string scope to git pathspecs or `unknown`, and its own header has
+ * documented the bifurcation since pln#520 ("~60% are not resolvable to paths at
+ * all"). Writing a second classifier would have been duplicated truth. This
+ * module adds only the two things that were genuinely missing.
+ *
+ * MISSING PIECE 1 — a DECLARED grammar for the reserved semantic prefixes.
+ * dirty-scope hardcodes `review-loop:` alone (line ~149), but production carries
+ * three variants. Census over the 613 live claims in this store:
+ *
+ *     review-loop           133
+ *     ideate-loop             5
+ *     ideation-loop           2
+ *     C                       1   ← a WINDOWS DRIVE LETTER, not a prefix
+ *     project-resolution      1   ← prose that happens to contain a colon
+ *     worktree-as-contract    1   ← ditto
+ *
+ * Two traps fall straight out of that data. A naive `/^[a-z-]+:/i` would read
+ * `C:/Users/...` as a semantic scope and stop treating an absolute Windows path
+ * as a path. And an unknown `word:` prefix is prose, not a loop reference — so
+ * the reserved set is ENUMERATED, never inferred from shape.
+ *
+ * MISSING PIECE 2 — the verdict's default on `unknown` must be INVERTED relative
+ * to the dirty guard, and this is the load-bearing insight of C0:
+ *
+ *   - The dirty guard BLOCKS on unknown. Its cardinal rule is that a noisy,
+ *     visible false-positive beats a silent false-negative, because letting a
+ *     worker edit stale code is worse than refusing a legitimate dispatch.
+ *   - A conformity advisory must be SILENT on unknown. Accusing an agent of
+ *     writing outside its scope when we cannot tell teaches it to ignore the
+ *     channel (the pln#634 failure mode) — and a channel an agent has learned to
+ *     skip is worse than no channel. Saying nothing costs nothing.
+ *
+ * Same classification, opposite correct default, because the cost of being wrong
+ * points the other way. Hence `unverifiable` is a first-class verdict every
+ * consumer must render as silence.
+ *
+ * @module
+ */
+import path from 'node:path';
+import { resolveScopeToPathspecs } from './dirty-scope.js';
+/**
+ * Reserved semantic prefixes, enumerated from production usage. A scope starting
+ * with one of these refers to a loop lane, never to files.
+ *
+ * `ideate-loop` and `ideation-loop` BOTH appear in the live store — an
+ * inconsistency in the emitting code, not here. Both are accepted so
+ * classification is correct today; unifying the emitters is a separate cleanup.
+ */
+export const RESERVED_SCOPE_PREFIXES = ['review-loop', 'ideate-loop', 'ideation-loop'];
+/** True when the token is an absolute Windows path (`C:/…`), not a prefixed scope. */
+function looksLikeWindowsDrive(scope) {
+    return /^[A-Za-z]:[\\/]/.test(scope);
+}
+/**
+ * Classify a claim scope.
+ *
+ * Order matters: the drive-letter check runs BEFORE the prefix check, because
+ * `C:` satisfies a naive prefix pattern while being a path.
+ */
+export function classifyClaimScope(scope, cwd) {
+    const trimmed = scope?.trim();
+    if (!trimmed)
+        return { kind: 'empty', reason: 'no scope recorded on the claim' };
+    if (!looksLikeWindowsDrive(trimmed)) {
+        for (const prefix of RESERVED_SCOPE_PREFIXES) {
+            if (!trimmed.toLowerCase().startsWith(`${prefix}:`))
+                continue;
+            const rest = trimmed.slice(prefix.length + 1);
+            const [loopId, slotId] = rest.split(':');
+            return {
+                kind: 'loop_ref',
+                loopRef: {
+                    prefix,
+                    loopId: (loopId ?? '').trim(),
+                    ...(slotId?.trim() ? { slotId: slotId.trim() } : {}),
+                },
+                reason: `scope refers to a ${prefix} lane, not to files`,
+            };
+        }
+    }
+    const resolved = resolveScopeToPathspecs(trimmed, cwd);
+    if (resolved.kind === 'pathspecs')
+        return { kind: 'paths', pathspecs: resolved.pathspecs };
+    return { kind: 'prose', reason: resolved.reason };
+}
+function normalise(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/** A touched file is in scope when it equals or sits under one declared pathspec. */
+function matchesPathspec(file, pathspec) {
+    const f = normalise(file);
+    const spec = normalise(pathspec.replace(/^:\(glob\)/, '')).replace(/\/$/, '');
+    if (spec.includes('*') || spec.includes('?')) {
+        // Delegating real globs to git is the resolver's job; here a glob scope is
+        // deliberately unverifiable rather than approximated with a hand-rolled matcher.
+        return false;
+    }
+    return f === spec || f.startsWith(`${spec}/`);
+}
+/**
+ * Compare the files a claim actually touched against the scope it declared.
+ *
+ * SILENT ON DOUBT, by construction. A loop-ref, prose, empty or glob scope
+ * yields `unverifiable`, and so does an empty touched-file list — there is
+ * nothing to accuse anyone of. Only a path-resolvable scope with concrete
+ * touched files can ever produce `out_of_scope`.
+ */
+export function assessScopeConformity(input) {
+    const classified = classifyClaimScope(input.scope, input.cwd);
+    if (classified.kind !== 'paths' || !classified.pathspecs?.length) {
+        return { kind: 'unverifiable', reason: classified.reason ?? 'scope is not path-resolvable' };
+    }
+    if (input.touchedPaths.length === 0) {
+        return { kind: 'unverifiable', reason: 'no touched files to compare' };
+    }
+    if (classified.pathspecs.some((spec) => spec.includes('*') || spec.includes('?'))) {
+        return { kind: 'unverifiable', reason: 'glob scope — left to git rather than approximated here' };
+    }
+    const specs = classified.pathspecs;
+    const matched = [];
+    const unexpected = [];
+    for (const file of input.touchedPaths) {
+        // The coordination store and git internals are never "outside scope": every
+        // brainclaw call rewrites them, so counting them would accuse every agent.
+        const n = normalise(file);
+        if (n.startsWith('.brainclaw/') || n.startsWith('.git/'))
+            continue;
+        if (specs.some((spec) => matchesPathspec(file, spec)))
+            matched.push(n);
+        else
+            unexpected.push(n);
+    }
+    if (unexpected.length === 0) {
+        return matched.length > 0
+            ? { kind: 'in_scope', matched }
+            : { kind: 'unverifiable', reason: 'every touched file was a system path' };
+    }
+    return { kind: 'out_of_scope', unexpected, pathspecs: specs };
+}
+/**
+ * Absolute→relative helper for callers holding worktree-absolute paths (a git
+ * diff run inside a lane worktree returns repo-relative already, but a hook sees
+ * absolute `tool_input.file_path`).
+ */
+export function toRepoRelative(absoluteOrRelative, repoRoot) {
+    if (!path.isAbsolute(absoluteOrRelative))
+        return normalise(absoluteOrRelative);
+    return normalise(path.relative(repoRoot, absoluteOrRelative));
+}
+//# sourceMappingURL=claim-scope.js.map

package/dist/core/claims.js

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -13,6 +14,7 @@ import { refreshLiveCompanions } from '../commands/export.js';
 import { loadSessionById } from './identity.js';
 import { loadState, persistState } from './state.js';
 import { createRuntimeEvent } from './events.js';
+import { latestActivityMs, readHeartbeat } from './runtime-signals.js';
 import { emitRegistryPostImage, registryFaultPoint } from './events/registry-post-image.js';
 import { maybeEnqueueClaimTransition, isFederationEnqueueActive } from './federation-outbox.js';
 /** Parse duration string like '4h', '30m' to ms. */
@@ -119,6 +121,35 @@ export function saveClaim(claim, cwd) {
         saveClaimUnlocked(claim, cwd);
     });
 }
+/**
+ * pln#636 C0-b — resolve the commit a claim starts from.
+ *
+ * Recorded once, at creation, and never updated: it is the fixed point a later
+ * "what did this claim actually touch?" comparison needs. The design review
+ * rejected both alternatives — neither HEAD-at-read-time nor the worktree dirty
+ * set is authoritative once a lane commits mid-work.
+ *
+ * BEST-EFFORT BY CONSTRUCTION. A non-git project, a detached state, or a missing
+ * git binary yields `undefined`, and a claim without a baseline is simply
+ * `unverifiable` downstream. Claim acquisition must never fail because a
+ * conformity nicety could not be computed.
+ */
+export function resolveClaimBaseSha(cwd) {
+    try {
+        const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+            cwd: cwd ?? process.cwd(),
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
+        if (result.status !== 0)
+            return undefined;
+        const sha = result.stdout.trim();
+        return /^[0-9a-f]{7,40}$/i.test(sha) ? sha : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Atomically check for an active claim on `scope` and save a new one if absent.
  *
@@ -126,6 +157,10 @@ export function saveClaim(claim, cwd) {
  * the mutation-pipeline mutex serializes filesystem writes on the claims store.
  */
 export function acquireClaimScope(input, cwd) {
+    // Resolved OUTSIDE the mutate callback: one git call per acquisition, and it
+    // stays off the critical section (mutate serializes filesystem writes on the
+    // claims store, so a subprocess spawn inside it would widen the lock window).
+    const baseSha = resolveClaimBaseSha(cwd);
     return mutate({ cwd }, () => {
         const conflictingClaim = listClaims(cwd).find((claim) => claim.status === 'active' && claim.scope === input.scope);
         if (conflictingClaim) {
@@ -143,6 +178,10 @@ export function acquireClaimScope(input, cwd) {
             status: 'active',
             plan_id: input.plan_id,
             model: input.model,
+            // pln#636 C0-b — capture the baseline while we know it. Absent when the
+            // project is not a git repo; downstream treats that as unverifiable.
+            ...(baseSha ? { base_sha: baseSha } : {}),
+            ...(input.paths?.length ? { paths: input.paths } : {}),
         };
         saveClaimUnlocked(claim, cwd);
         return { acquired: true, claim };
@@ -502,11 +541,82 @@ const DEFAULT_STALE_HOURS = 24;
  * even if it has no session yet (coordinator claims are created before the worker session starts).
  */
 const YOUNG_CLAIM_THRESHOLD_MS = 30 * 60_000; // 30 minutes
+/** Default freshness window for file evidence — matches the default `heartbeat_ttl_ms`. */
+const DEFAULT_EVIDENCE_TTL_MS = 30 * 60_000;
 /**
- * Assess the liveness of an active claim against session state.
+ * How far into the future a file timestamp may sit before we stop trusting it.
+ *
+ * WHY THIS TOLERANCE EXISTS, and why the naive `age < 0 → ignore` was wrong.
+ * `fs.stat().mtimeMs` is sub-millisecond on NTFS while `Date.now()` is coarser,
+ * so a heartbeat written microseconds ago routinely stats as *newer than now* —
+ * i.e. the freshest evidence possible was the evidence most likely to be thrown
+ * away. That reproduced as a nondeterministic liveness verdict: the same claim
+ * read `live` on an idle machine and `never-adopted` under load.
+ *
+ * A file dated slightly ahead is therefore clamped to age 0 (maximally fresh),
+ * while one dated grossly ahead is discarded — that is a genuinely wrong clock or
+ * a hand-forged timestamp, and inventing liveness from it would let a dead
+ * worker hold a claim forever.
+ */
+const FUTURE_EVIDENCE_TOLERANCE_MS = 5 * 60_000;
+/**
+ * pln#636 — age of the freshest FILE evidence that this claim's worker is alive.
+ *
+ * WHY FILE EVIDENCE AND NOT A SESSION. A sandboxed spawned worker cannot reach
+ * MCP, so it cannot maintain any server-side liveness record — which is exactly
+ * why the project moved proof-of-life to filesystem sentinels: the dispatcher
+ * injects a "Liveness — DO THIS FIRST" step into every brief, and the worker
+ * writes/refreshes a heartbeat in the ONE location a sandbox can write (its own
+ * worktree). `assignment-sweeper` already honours that evidence; claims did not,
+ * which meant a demonstrably-alive sandboxed worker kept its assignment but had
+ * its CLAIM aged out on wall-clock alone (trp_4d0fc2ef). This closes that
+ * asymmetry by reading the same signals.
+ *
+ * Deliberately reads the leaf `runtime-signals` module rather than
+ * `collectEvidence`: agentrun-reconciler imports `loadClaim` from here, so
+ * importing it back would create a cycle.
+ *
+ * Returns undefined when there is nothing to read — no assignment, no signals —
+ * and never throws.
+ */
+function freshestEvidenceAgeMs(claim, nowMs, cwd) {
+    if (!claim.assignment_id)
+        return undefined;
+    const root = cwd ?? process.cwd();
+    let freshest;
+    const consider = (ms) => {
+        if (ms === undefined)
+            return;
+        const age = nowMs - ms;
+        // Slightly-future timestamps are a clock-granularity artefact, not skew —
+        // clamp them to "just now". Grossly-future ones are untrustworthy: ignore
+        // rather than invent liveness. See FUTURE_EVIDENCE_TOLERANCE_MS.
+        if (age < -FUTURE_EVIDENCE_TOLERANCE_MS)
+            return;
+        const normalised = age < 0 ? 0 : age;
+        if (freshest === undefined || normalised < freshest)
+            freshest = normalised;
+    };
+    try {
+        const hb = readHeartbeat(root, claim.assignment_id, claim.worktree_path);
+        if (hb.exists)
+            consider(hb.mtimeMs);
+    }
+    catch { /* evidence is best-effort */ }
+    try {
+        consider(latestActivityMs(root, claim.assignment_id, claim.worktree_path));
+    }
+    catch { /* evidence is best-effort */ }
+    return freshest;
+}
+/**
+ * Assess the liveness of an active claim.
  *
  * Decision tree:
- *  1. Young (< 30 min) → never auto-release — dispatcher may not have sent the worker yet.
+ *  0. Young (< 30 min) → never auto-release — dispatcher may not have sent the worker yet.
+ *  1. FRESH FILE EVIDENCE → 'live', whatever the session says. This branch comes
+ *     first because it is the only proof a sandboxed, MCP-less worker can
+ *     produce, and it is the same evidence the assignment sweeper trusts.
  *  2. Has session_id + session alive → 'live' — long-running work; do NOT release.
  *  3. Has session_id + adopted_at + session dead → 'orphaned' — crash recovery scenario.
  *  4. Has session_id + no adopted_at + session dead → 'stale' — direct agent claim, session ended.
@@ -525,6 +635,21 @@ export function assessClaimLiveness(claim, options = {}) {
             ageMs,
         };
     }
+    // 1. FILE EVIDENCE FIRST (pln#636, trp_4d0fc2ef). A sandboxed worker proves
+    //    life by writing a heartbeat into its worktree — the only place it can
+    //    write — and by touching files there. That evidence outranks any session
+    //    reasoning: a worker actively committing is alive whether or not a session
+    //    record exists, and a coordinator-created claim has no session_id at all.
+    const evidenceAgeMs = freshestEvidenceAgeMs(claim, nowMs, options.cwd);
+    const evidenceTtlMs = options.evidenceTtlMs ?? DEFAULT_EVIDENCE_TTL_MS;
+    if (evidenceAgeMs !== undefined && evidenceAgeMs < evidenceTtlMs) {
+        return {
+            status: 'live',
+            reason: `File evidence is fresh (${Math.round(evidenceAgeMs / 60_000)}min ago) — the worker is demonstrably active`,
+            ageMs,
+            evidenceAgeMs,
+        };
+    }
     // 2–4. Has a session_id — check session liveness
     if (claim.session_id) {
         let sessionAgeMs;