brainclaw 1.18.0 → 1.19.1

package/dist/core/next-actions.js

@@ -0,0 +1,157 @@
+/**
+ * Verifying a spawned worker: always `bclaw_dispatch_status`, never
+ * `bclaw_find(agent_run)` + a pid check. On Windows an ack-wrapped spawn runs
+ * under cmd.exe, so `agent_run.pid` is the wrapper (which exits by design) and
+ * reads dead while the worker is alive (trp_7fc3e3c4). `dispatch_status`
+ * returns a sentinel-based verdict instead.
+ */
+export function verifyDispatchAction(targetId, note) {
+    return {
+        tool: 'bclaw_dispatch_status',
+        args: { target_id: targetId },
+        when: note
+            ? `${note} — sentinel-based liveness verdict (do NOT judge from agent_run.pid)`
+            : 'verify the spawned worker is actually alive — sentinel-based verdict (do NOT judge from agent_run.pid)',
+    };
+}
+/** Cap on repeated per-target actions, so a wide fan-out cannot flood the field. */
+const FANOUT_CAP = 3;
+function verifyActions(targetIds, note) {
+    const shown = targetIds.slice(0, FANOUT_CAP);
+    const actions = shown.map((id) => verifyDispatchAction(id, note));
+    if (targetIds.length > shown.length) {
+        // Say what was dropped rather than silently truncating.
+        actions.push({
+            tool: 'bclaw_dispatch_status',
+            args: { target_id: '<one of the remaining targets>' },
+            when: `${targetIds.length - shown.length} further target(s) were dispatched — verify each one the same way`,
+        });
+    }
+    return actions;
+}
+/**
+ * After a release, the follow-up depends entirely on what the cascade decided:
+ * a blocked plan transition needs the other claim holders inspected, a
+ * completed plan is ready for review, and a plain release has no next step at
+ * all.
+ */
+export function releaseClaimNextActions(outcome) {
+    const actions = [];
+    if (outcome.planWarning && outcome.planId) {
+        // The cascade refused: other claims still hold the plan. Both the diagnosis
+        // and the eventual manual transition are real MCP calls.
+        actions.push({
+            tool: 'bclaw_find',
+            args: { entity: 'claim', filter: { plan_id: outcome.planId, status: 'active' } },
+            when: 'the plan was NOT transitioned because other claims are still active — see who else holds it',
+        });
+        actions.push({
+            tool: 'bclaw_transition',
+            args: { entity: 'plan', id: outcome.planId, to: outcome.requestedPlanStatus ?? 'done' },
+            when: 'once the other claims are released, transition the plan yourself',
+        });
+        return actions;
+    }
+    if (outcome.planTransitioned && outcome.planId) {
+        // Documented workflow: implement → release → review.
+        actions.push({
+            tool: 'bclaw_coordinate',
+            args: {
+                intent: 'review',
+                task: `Review the work delivered under plan ${outcome.planId}`,
+                open_loop: true,
+            },
+            when: 'the plan is done — the next workflow stage is review',
+        });
+    }
+    return actions;
+}
+/**
+ * Only two transitions imply an unambiguous next call. Everything else
+ * (candidate accepted, plan done, trap retired, …) is terminal for the caller,
+ * so it returns nothing rather than inventing busywork.
+ */
+export function transitionNextActions(outcome) {
+    if (outcome.entity === 'plan' && outcome.to === 'in_progress') {
+        return [{
+                tool: 'bclaw_work',
+                args: { intent: 'execute', planId: outcome.id, scope: '<scope you are about to edit>' },
+                when: 'the plan is in progress — claim the scope before editing',
+            }];
+    }
+    if (outcome.entity === 'plan' && outcome.to === 'blocked') {
+        return [{
+                tool: 'bclaw_quick_capture',
+                args: { text: '<what blocks this plan>', type: 'trap' },
+                when: 'record WHY it is blocked so the next agent does not rediscover it',
+            }];
+    }
+    return [];
+}
+/**
+ * Coordinate's follow-up is driven by whether anything actually spawned, not by
+ * the intent alone: the same `intent='assign'` needs verification when it
+ * spawned and nothing MCP-callable when it produced manual commands.
+ */
+export function coordinateNextActions(outcome) {
+    const actions = [];
+    const spawned = outcome.executionStatus === 'delivered_and_started';
+    if (spawned && outcome.assignmentIds.length > 0) {
+        actions.push(...verifyActions(outcome.assignmentIds));
+    }
+    if (outcome.loopId) {
+        actions.push({
+            tool: 'bclaw_loop',
+            args: { intent: 'get', loop_id: outcome.loopId },
+            when: spawned
+                ? 'inspect loop state — its `next_expected` names the turn the loop is waiting on'
+                : 'the loop is open but nothing spawned — inspect it and drive the turn yourself',
+        });
+    }
+    // Manual-handoff spawning intents: the launch commands are in the text body
+    // (not MCP-callable), so the only real MCP follow-up is verification AFTER
+    // the operator runs them.
+    if (!spawned && outcome.executionStatus === 'command_ready_manual' && outcome.assignmentIds.length > 0) {
+        actions.push(verifyActions(outcome.assignmentIds, 'once you have run the launch command(s) printed above')[0]);
+    }
+    return actions;
+}
+export function dispatchNextActions(outcome) {
+    if (outcome.dryRun) {
+        return [{
+                tool: 'bclaw_dispatch',
+                args: { intent: 'execute' },
+                when: 'this was a dry run — nothing was dispatched; re-run without dryRun to actually spawn',
+            }];
+    }
+    const actions = [];
+    if (outcome.spawnedTargets.length > 0) {
+        actions.push(...verifyActions(outcome.spawnedTargets));
+    }
+    if (outcome.blockedCount > 0) {
+        actions.push({
+            tool: 'bclaw_dispatch',
+            args: { intent: 'analysis' },
+            when: `${outcome.blockedCount} lane(s) are blocked — analysis explains which gate holds each one`,
+        });
+    }
+    return actions;
+}
+export function createEntityNextActions(outcome) {
+    if (outcome.entity === 'plan') {
+        return [{
+                tool: 'bclaw_add_step',
+                args: { planId: outcome.id, data: { text: '<first unit of work>' } },
+                when: 'break the plan into steps so progress is trackable',
+            }];
+    }
+    if (outcome.entity === 'sequence') {
+        return [{
+                tool: 'bclaw_dispatch',
+                args: { intent: 'analysis' },
+                when: 'inspect lane readiness before dispatching the sequence',
+            }];
+    }
+    return [];
+}
+//# sourceMappingURL=next-actions.js.map

package/dist/core/review-loop-close.js

@@ -1,9 +1,19 @@
 import { getLoop } from './loops/store.js';
 import { complete_turn, advance } from './loops/verbs.js';
 import { withLoopLock } from './loops/lock.js';
+import { LOOP_ARTIFACT_BODY_MAX_BYTES } from './loops/types.js';
 /** review-loop:lop_xxx → the loop id (mirrors assignment-reconciler.ts). */
 const REVIEW_LOOP_SCOPE_RE = /^review-loop:(lop_[0-9a-z]+)/;
 const LOOP_TERMINAL = new Set(['completed', 'cancelled', 'blocked']);
+/** Keep the loop-facing verdict valid while the full worker body stays durable in harvest metadata. */
+function capVerdictBody(prefix, detail) {
+    const full = `${prefix}${detail ? `: ${detail}` : ''}`;
+    if (Buffer.byteLength(full, 'utf8') <= LOOP_ARTIFACT_BODY_MAX_BYTES)
+        return full;
+    const marker = '…[truncated; full body retained in lane harvest event]';
+    const room = LOOP_ARTIFACT_BODY_MAX_BYTES - Buffer.byteLength(prefix, 'utf8') - Buffer.byteLength(': ', 'utf8') - Buffer.byteLength(marker, 'utf8');
+    return `${prefix}: ${Buffer.from(detail, 'utf8').subarray(0, Math.max(0, room)).toString('utf8').replace(/�+$/, '')}${marker}`;
+}
 /** Build the fix+re-review brief for a request_changes cycle turn (symmetric).
  *  Exported so the turn-owned reconcile path (pln#630 PR3b) reuses the identical
  *  wording — the reviewer contract must not drift between the legacy and turn-owned
@@ -78,14 +88,21 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                     return noop(`loop already ${loop.status}`, loop.status);
                 const slot = resolveReviewerSlot(loop, assignment);
                 const acceptedVerdictExists = loop.artifacts.some(isAcceptedVerdict);
-                const summary = (lane.review_summary ?? '').trim();
+                const detail = (lane.body ?? lane.review_summary ?? '').trim();
                 // ── approve → close on reviewer_green ───────────────────────────────
                 if (verdict === 'approve') {
                     if (slot) {
                         // isVerdictAccepted fires reviewer_green ONLY on an "accepted…" body.
                         complete_turn({
                             id: loopId, slot_id: slot.slot_id, actor,
-                            artifact: { phase: loop.current_phase, type: 'verdict', body: `accepted${summary ? `: ${summary}` : ''}` },
+                            // pln#639 BUG-2 — the phase the slot was DISPATCHED in, not the
+                            // loop's phase at close time. Same defect as the ideation closer;
+                            // fixed here too because this is the far more travelled path.
+                            // Safe for the approve flow: `reviewer_green` scans every artifact
+                            // via isVerdictAccepted regardless of phase, and no gate in the
+                            // engine keys on `type: 'verdict'` — so this changes attribution
+                            // truth without changing a single gate outcome.
+                            artifact: { phase: slot.phase ?? loop.current_phase, type: 'verdict', body: capVerdictBody('accepted', detail) },
                         }, cwd);
                     }
                     else if (!acceptedVerdictExists) {
@@ -130,7 +147,8 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                 const symmetric = loop.protocol?.review_mode === 'symmetric';
                 complete_turn({
                     id: loopId, slot_id: slot.slot_id, actor,
-                    artifact: { phase: loop.current_phase, type: 'verdict', body: `changes-requested${summary ? `: ${summary}` : ''}` },
+                    // pln#639 BUG-2 — dispatch phase, not close-time phase (see above).
+                    artifact: { phase: slot.phase ?? loop.current_phase, type: 'verdict', body: capVerdictBody('changes-requested', detail) },
                 }, cwd);
                 if (!symmetric) {
                     const advancedAsym = advance({ id: loopId, actor }, cwd);
@@ -174,7 +192,7 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                         agent_id: slot.agent_id,
                         phase: advanced.loop.current_phase,
                         iteration: advanced.loop.iteration_count,
-                        task: buildFixCycleTask(summary, advanced.loop.iteration_count),
+                        task: buildFixCycleTask(detail, advanced.loop.iteration_count),
                     },
                 };
             },

package/dist/core/schema.js

@@ -715,6 +715,28 @@ export const ClaimSchema = z.object({
     assignment_message_id: z.string().optional(),
     /** Assignment ID from the Agent SDK runtime protocol. Links claim to its Assignment lifecycle entity. */
     assignment_id: z.string().optional(),
+    /**
+     * pln#636 C0-b — commit the claim's work started FROM, recorded at creation.
+     *
+     * This is the immutable baseline any "what did this claim actually touch?"
+     * comparison needs. The design review settled the question by rejecting both
+     * options it offered: neither `git diff` against HEAD nor the worktree's dirty
+     * set is authoritative, because a lane that commits mid-work moves the ground
+     * under both. A fixed point recorded up front is the only honest basis.
+     *
+     * Optional and never backfilled: the 613 claims that predate this field simply
+     * have no baseline, and a conformity check must treat that as `unverifiable`
+     * rather than guessing one (see core/claim-scope.ts on the inverted default).
+     */
+    base_sha: z.string().optional(),
+    /**
+     * pln#636 C0-b — file footprint the claim DECLARES, when its creator knows it.
+     *
+     * Raises conformity coverage above what classifying a free-string `scope` can
+     * reach (57.6% of the live corpus is path-resolvable). Purely additive: absent
+     * means "fall back to classifying `scope`", never "no files allowed".
+     */
+    paths: z.array(z.string()).optional(),
 });
 // --- Assignment schemas (Agent SDK runtime protocol) ---
 export const AssignmentStatusSchema = z.enum([
@@ -974,6 +996,12 @@ export const RuntimeEventTypeSchema = z.enum([
  * environment, e.g. a genuinely MCP-less agent). The coordinator ingests it with
  * `brainclaw harvest <assignment_id>`.
  */
+/**
+ * Largest inline worker body accepted in a LANE-RESULT. This is deliberately
+ * larger than a loop artifact body: harvest persists the original body in its
+ * durable runtime event before a loop closer applies its smaller display cap.
+ */
+export const LANE_RESULT_BODY_MAX_BYTES = 64 * 1024;
 export const LaneResultSchema = z.object({
     assignment_id: z.string(),
     /**
@@ -994,6 +1022,18 @@ export const LaneResultSchema = z.object({
     files_changed: z.array(z.string()).optional(),
     /** Free-form notes (blockers, follow-ups). */
     notes: z.string().optional(),
+    /**
+     * Full worker reasoning or review content. Unlike `summary`, this is the
+     * durable handoff payload and is copied into the coordinator-side harvest
+     * event, so it survives worktree cleanup. Optional for legacy workers.
+     */
+    body: z.string().refine((body) => Buffer.byteLength(body, 'utf8') <= LANE_RESULT_BODY_MAX_BYTES, `LANE-RESULT.body must be ≤ ${LANE_RESULT_BODY_MAX_BYTES} bytes`).optional(),
+    /**
+     * Type the worker associated with `body`. Optional because legacy
+     * `artifacts` remains a list of opaque labels/refs. A loop harvester may
+     * reconcile this to its phase's required artifact type.
+     */
+    artifact_type: z.string().min(1).optional(),
     /**
      * pln#628 Focus 4B — review-loop verdict. A worker running a review-loop turn
      * sets this to signal whether the change is good to merge (`approve`) or needs

package/dist/core/surface-freshness.js

@@ -0,0 +1,150 @@
+/**
+ * pln#638 volet 2b — lazy freshness reconcile for generated guidance surfaces.
+ *
+ * WHY THIS EXISTS. 2a made the live header HONEST: it stopped claiming
+ * "auto-refreshed" and started naming its real triggers (session-end, handoff,
+ * `export --write`) plus the version and timestamp that wrote it. Honesty alone
+ * does not help an agent tier that never fires any of those triggers, though — it
+ * just tells that tier, truthfully, that the file might be arbitrarily old. 2b
+ * closes the loop by USING the stamp: compare it against the running version and
+ * say so, once, at a path we already visit.
+ *
+ * NO DAEMON, NO WATCHER — the validated lazy-reconcile pattern. The check is a
+ * pure comparison plus a directory scan of a registry that already exists
+ * (`AGENT_EXPORT_REGISTRY` / `LIVE_COMPANION_EXPORT_REGISTRY`), so it is DERIVED
+ * rather than enumerated. That is review finding F1 applied here: a hand-kept
+ * list of generated surfaces would itself be an unguarded generated surface, and
+ * would reproduce the exact defect this plan exists to fix.
+ *
+ * ADVISORY, AND SILENT ON DOUBT. A surface with no stamp is not stale — it is
+ * unknown (it may predate the stamp, or be hand-written by the operator). Only a
+ * stamp that PARSES and names a DIFFERENT version is reported. Nothing here
+ * rewrites a file: regeneration stays the explicit act it always was.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { AGENT_EXPORT_REGISTRY, LIVE_COMPANION_EXPORT_REGISTRY } from './agent-files.js';
+/**
+ * Matches the provenance line emitted by `renderLiveHeader`
+ * (instruction-templates.ts) and by the protocol-skill front-matter.
+ *
+ * Deliberately tolerant about what follows the version: the timestamp format is
+ * not what this parser is for, and a stricter pattern would go stale the first
+ * time the header gains a field.
+ */
+const PROVENANCE_RE = /Written by brainclaw v(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/;
+/** `brainclaw_version: X` in a generated SKILL.md front-matter. */
+const SKILL_PROVENANCE_RE = /^\s*brainclaw_version:\s*v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\s*$/m;
+/** Read the provenance stamp out of a generated surface's content. Never throws. */
+export function parseSurfaceProvenance(content) {
+    const header = PROVENANCE_RE.exec(content);
+    if (header?.[1])
+        return { version: header[1] };
+    const skill = SKILL_PROVENANCE_RE.exec(content);
+    if (skill?.[1])
+        return { version: skill[1] };
+    return {};
+}
+/**
+ * Compare one surface's stamp against the running version.
+ *
+ * An UNKNOWN stamp is never reported as stale. Treating "no stamp" as "out of
+ * date" would fire on every hand-written AGENTS.md in every project that ever
+ * adopted brainclaw — the false-positive failure mode that teaches agents to
+ * ignore a channel.
+ */
+export function assessSurfaceFreshness(content, currentVersion) {
+    const { version } = parseSurfaceProvenance(content);
+    if (!version)
+        return { kind: 'unknown', reason: 'no brainclaw provenance stamp' };
+    if (version === currentVersion)
+        return { kind: 'fresh', version };
+    return { kind: 'stale', stampedVersion: version, currentVersion };
+}
+/**
+ * The set of surfaces this project could have on disk, derived from the export
+ * registries rather than listed here. Deduplicated because several agents share
+ * a target (four of them write AGENTS.md).
+ */
+function candidateSurfacePaths() {
+    return [...new Set([
+            ...AGENT_EXPORT_REGISTRY.map((t) => t.relativePath),
+            ...LIVE_COMPANION_EXPORT_REGISTRY.map((t) => t.relativePath),
+        ])];
+}
+/**
+ * Scan the project's generated surfaces and report the ones stamped with a
+ * different brainclaw version.
+ *
+ * Cheap by construction: it only stats/reads files the registries name (~25
+ * paths, most absent in any given project), and reads at most the head of each —
+ * the stamp is in the header, so there is no reason to pull a whole file into
+ * memory. Never throws; an unreadable file is simply not reported.
+ */
+export function reconcileSurfaceFreshness(cwd, currentVersion) {
+    const result = { stale: [], freshCount: 0, unknownCount: 0 };
+    for (const relativePath of candidateSurfacePaths()) {
+        const full = path.join(cwd, relativePath);
+        let head;
+        try {
+            if (!fs.existsSync(full))
+                continue;
+            // The stamp lives in the header; 4KB covers it with room to spare.
+            const fd = fs.openSync(full, 'r');
+            try {
+                const buf = Buffer.alloc(4096);
+                const read = fs.readSync(fd, buf, 0, buf.length, 0);
+                head = buf.subarray(0, read).toString('utf-8');
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            continue; // unreadable → not reported, never a crash
+        }
+        const verdict = assessSurfaceFreshness(head, currentVersion);
+        if (verdict.kind === 'stale')
+            result.stale.push({ relativePath, stampedVersion: verdict.stampedVersion });
+        else if (verdict.kind === 'fresh')
+            result.freshCount += 1;
+        else
+            result.unknownCount += 1;
+    }
+    return result;
+}
+/**
+ * Build the advisory for a stale-surface scan, or `undefined` when there is
+ * nothing to say.
+ *
+ * NO `next_actions`, deliberately. The recovery is `brainclaw export --write`,
+ * and there is no MCP tool that performs it — `bclaw_setup` is the onboarding
+ * wizard and takes no write flag. Pointing at it anyway would ship a next_action
+ * whose args the engine rejects, which is the precise class of drift this plan
+ * exists to eliminate; and per pln#634's own rule, a builder with no genuine
+ * follow-up returns nothing rather than inventing one. The command therefore
+ * travels in the message, where it is true.
+ */
+export function staleSurfaceWarning(result, currentVersion) {
+    if (result.stale.length === 0)
+        return undefined;
+    const shown = result.stale.slice(0, 8);
+    const overflow = result.stale.length - shown.length;
+    return {
+        code: 'generated_surfaces_stale',
+        message: `${result.stale.length} generated guidance surface(s) were written by an older brainclaw than v${currentVersion}: `
+            + shown.map((s) => `${s.relativePath} (v${s.stampedVersion})`).join(', ')
+            + (overflow > 0 ? ` (+${overflow} more)` : '')
+            + '. An agent tier that never triggers a regeneration is reading them as-is.'
+            + ' Run `brainclaw export --write` to refresh them.',
+        data: {
+            current_version: currentVersion,
+            stale_surfaces: shown.map((s) => ({ path: s.relativePath, stamped_version: s.stampedVersion })),
+            ...(overflow > 0 ? { stale_surfaces_omitted: overflow } : {}),
+            refresh_command: 'brainclaw export --write',
+        },
+    };
+}
+//# sourceMappingURL=surface-freshness.js.map

package/dist/core/warnings.js

@@ -0,0 +1,98 @@
+/**
+ * Codes that historically shipped as a JSON blob keep shipping that exact blob,
+ * so no existing consumer sees a changed string. The set is enumerated rather
+ * than inferred so a NEW code cannot accidentally start emitting JSON at a
+ * consumer that only ever saw prose.
+ */
+const LEGACY_JSON_CODES = new Set([
+    'agent_validation_failed',
+    'plan_already_assigned',
+    'scope_already_claimed',
+]);
+/** Derive the legacy `warnings` string for a structured warning. */
+export function renderLegacyWarning(detail) {
+    if (LEGACY_JSON_CODES.has(detail.code)) {
+        return JSON.stringify({ warning: detail.code, ...(detail.data ?? {}) });
+    }
+    return detail.message;
+}
+/**
+ * Build the structured record without touching any legacy channel.
+ *
+ * Used by surfaces that have NO historical `warnings: string[]` to stay
+ * compatible with — a field introduced already-structured (pln#636 C2's
+ * `LaneHarvestResult.warnings`, for one) should not have to invent a throwaway
+ * string array just to reach this shape.
+ */
+export function toWarningDetail(input) {
+    return {
+        code: input.code,
+        message: input.message,
+        ...(input.data ? { data: input.data } : {}),
+        ...(input.next_actions?.length ? { next_actions: input.next_actions } : {}),
+    };
+}
+/**
+ * Record a structured warning into BOTH channels at once.
+ *
+ * Taking the two arrays as parameters (rather than owning them) is what keeps
+ * this additive: the caller's `warnings: string[]` stays the same object it
+ * already passes by reference to its own helpers.
+ */
+export function pushStructuredWarning(warnings, details, input) {
+    const detail = toWarningDetail(input);
+    details.push(detail);
+    warnings.push(renderLegacyWarning(detail));
+}
+// ── Builders for the migrated sites ─────────────────────────────────────────
+// Each owns its recovery path, which is the entire point of the structured
+// channel: `scope_already_claimed` used to be a dead-end string; now it names
+// the two calls that resolve it.
+export function agentValidationFailedWarning(input) {
+    return {
+        code: 'agent_validation_failed',
+        message: `Agent '${input.agent}' cannot be dispatched to${input.reason ? `: ${input.reason}` : ''}.`,
+        data: { agent: input.agent, code: input.code, reason: input.reason },
+        next_actions: [{
+                tool: 'bclaw_find',
+                args: { entity: 'agent', filter: { scope: 'global' } },
+                when: 'list the dispatchable agents and pick a target that is actually spawnable',
+            }],
+    };
+}
+export function planAlreadyAssignedWarning(input) {
+    return {
+        code: 'plan_already_assigned',
+        message: `'${input.planId}' already has an active assignment for ${input.existingAgent} — this call adds a second one.`,
+        data: { plan_id: input.planId, existing_agent: input.existingAgent },
+        next_actions: [{
+                tool: 'bclaw_find',
+                args: { entity: 'assignment', filter: { agent: input.existingAgent, status: 'offered' } },
+                when: 'inspect the existing assignment before letting two agents work the same scope',
+            }],
+    };
+}
+export function scopeAlreadyClaimedWarning(input) {
+    return {
+        code: 'scope_already_claimed',
+        message: `Scope '${input.scope}' is already claimed by ${input.existingAgent} (${input.existingClaimId}).`,
+        data: {
+            scope: input.scope,
+            existing_agent: input.existingAgent,
+            existing_claim_id: input.existingClaimId,
+        },
+        next_actions: [
+            {
+                tool: 'bclaw_get',
+                args: { entity: 'claim', id: input.existingClaimId },
+                when: 'see who holds the scope and since when before creating a second claim on it',
+            },
+            {
+                tool: 'bclaw_coordinate',
+                args: { intent: 'reroute', task: `Reassign work on ${input.scope}`, scope: input.scope },
+                when: 'hand the existing claim to another agent instead of double-claiming the scope',
+            },
+        ],
+    };
+}
+//# sourceMappingURL=warnings.js.map

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.18.0 on 2026-07-31T14:51:44.969Z
+// Source: brainclaw v1.19.1 on 2026-08-02T07:16:39.143Z
 export const FACTS = {
-  "version": "1.18.0",
-  "generated_at": "2026-07-31T14:51:44.969Z",
+  "version": "1.19.1",
+  "generated_at": "2026-08-02T07:16:39.143Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-31T14:51:42.799Z",
+    "generated_at": "2026-08-02T07:16:37.042Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -491,7 +491,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 142,
+        "duration_ms_median": 123,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.18.0",
-  "generated_at": "2026-07-31T14:51:44.969Z",
+  "version": "1.19.1",
+  "generated_at": "2026-08-02T07:16:39.143Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-31T14:51:42.799Z",
+    "generated_at": "2026-08-02T07:16:37.042Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -489,7 +489,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 142,
+        "duration_ms_median": 123,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/docs/concepts/plans-and-claims.md

@@ -166,6 +166,63 @@ Without claims, multiple agents can easily touch the same area at once and gener
 Claims are not necessarily hard file locks.
 They are a shared coordination signal.
 
+### Scope grammar and conformity (v1.19.0+)
+
+A claim's `scope` is a free string, and in practice it is used three ways. Measured
+over the 613 real claims in the dogfood store:
+
+| Shape | Share | Example |
+|---|---|---|
+| Path-like | 57.6% | `src/core/auth.ts`, `docs/` |
+| Loop reference | 22.8% | `review-loop:lop_…`, `ideate-loop:lop_…:lsl_…` |
+| Free prose | 19.6% | `Loop engine residuals #1-4` |
+
+So **42.4% of real scopes cannot be matched to a file path at all** — and the
+non-matchable share is *growing*, because coordinator-created lane claims are the
+ones being minted. Any check built naively on path matching would false-accuse on
+nearly one claim in two.
+
+brainclaw therefore classifies a scope into `paths` / `loop_ref` / `prose` / `empty`
+and reports conformity as `in_scope`, `out_of_scope`, or **`unverifiable`** — a
+first-class verdict that every consumer renders as **silence**. Only a
+path-resolvable scope with concrete stray files can ever produce an accusation.
+`.brainclaw/` and `.git/` are never counted as out of scope: every brainclaw call
+rewrites them, so counting them would accuse every agent on every claim.
+
+The reserved loop prefixes are **enumerated**, not inferred from shape — so
+`project-resolution: the gate` reads as prose, and a Windows absolute path
+(`C:/Users/…`) stays a path rather than being read as a `C:` prefix.
+
+### `base_sha` and declared `paths[]`
+
+A new claim records **`base_sha`**, the commit its work started from, resolved once
+at creation and never moved. This is the baseline any "what did this claim actually
+touch?" comparison needs: neither `git diff HEAD` nor the worktree's dirty set is
+authoritative, because a lane that commits mid-work moves the ground under both —
+each would report "touched nothing" the instant it committed.
+
+Optionally a creator can declare **`paths[]`**, a machine-readable footprint that
+raises conformity coverage above what classifying a free-string `scope` can reach.
+
+Both are additive and never backfilled. A claim with no baseline is `unverifiable`,
+never guessed, and acquiring a claim **never fails or blocks** because a baseline
+could not be computed — outside a git repo the claim is simply created without one.
+
+> `paths[]` is currently settable through the core and the CLI, but is not yet
+> exposed in `bclaw_claim`'s published MCP inputSchema.
+
+### Liveness: file evidence, not just a session
+
+A spawned sandboxed worker cannot reach MCP, so it cannot maintain any server-side
+liveness record — which is why proof-of-life lives in filesystem sentinels the
+worker writes into its own worktree. Since v1.19.0 claim liveness reads that same
+evidence (worktree/project heartbeat plus filesystem activity) **before** consulting
+any session record, with the same 30-minute freshness window an assignment gets.
+
+Previously a demonstrably-alive worker kept its *assignment* while its *claim* aged
+out on wall-clock alone — and a coordinator-created claim, which carries no
+`session_id`, fell straight through to `never-adopted`.
+
 ## Policy checks
 
 Before editing a scope, agents can verify governance compliance using `check-policy`: