brainclaw 1.17.0 → 1.19.0

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;