brainclaw 1.7.5 → 1.8.0

package/README.md

@@ -345,6 +345,22 @@ npm run test:coverage      # with coverage report
 
 For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
+### v1.8.0
+
+- **Multi-agent dispatch convergence — "worktree-as-contract"** (from a real
+  cross-project field session where a sandboxed worker could neither commit nor
+  reach MCP). The worker's contract shrinks to "edit files in this worktree +
+  drop `LANE-RESULT.json`": `brainclaw harvest --integrate` commits the worktree
+  diff on behalf of a worker that can't self-commit (hard-guarded to the linked
+  worktree, never the main repo), then completes the assignment and releases the
+  claim with plan cascade. A `LANE-RESULT.json` is now the #1 verdict signal in
+  `bclaw_dispatch_status` (worker FINISHED, even without self-update); the
+  dispatcher refuses to spawn without an isolated worktree; `open_loop` reviews
+  pre-flight each reviewer agent with a trivial validation spawn (clear
+  boot-failure reason instead of a generic loop timeout); and decisions/traps
+  gain `verified_at`/`verify_cmd` so perishable facts can be flagged stale.
+  Additive + opt-in throughout. (pln#530, pln#531, pln#532, pln#533, pln#534, trp#468)
+
 ### v1.7.5
 
 - **Security patch (recommended upgrade)** — fixes a git command-injection / RCE

package/dist/cli.js

@@ -1014,6 +1014,7 @@ program
     .command('harvest [assignment_id]')
     .description('Harvest a worker LANE-RESULT.json from its worktree into the project (pass an assignment id, or --all)')
     .option('--all', 'Harvest every lane result found across worktrees')
+    .option('--integrate', 'Worktree-as-contract (pln#534): commit the worktree diff on behalf of a sandboxed worker, lifecycle the assignment, and release the claim')
     .option('--dry-run', 'Preview without writing events/markers')
     .option('--worktree <path>', 'Explicit worktree path to scan (repeatable)', collect, [])
     .option('--json', 'Output as JSON')

package/dist/commands/harvest.js

@@ -18,6 +18,10 @@ import { CandidateSchema, LaneResultSchema } from '../core/schema.js';
 import { listCandidates, listArchivedCandidates, saveCandidate } from '../core/candidates.js';
 import { createRuntimeEvent } from '../core/events.js';
 import { memoryExists } from '../core/io.js';
+import { loadAssignment, transitionAssignment } from '../core/assignments.js';
+import { releaseClaimWithCascade } from '../core/claims.js';
+import { getCapabilityProfile, dispatchCanCommit } from '../core/agent-capability.js';
+import { commitWorktreeOnBehalf } from '../core/worktree.js';
 /**
  * Returns the base directory where brainclaw-managed worktrees are stored
  * for the given project root: `~/.brainclaw/worktrees/<sha1-hash>/`.
@@ -264,6 +268,193 @@ export function harvestLaneResults(options = {}) {
     }
     return result;
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// pln#534 — worktree-as-contract: integrate a worker's lane on its behalf.
+//
+// LEVER #1 from the LeaseUp frontier (can_100f1e8c). The worker's contract is
+// reduced to "edit files in this worktree + drop LANE-RESULT.json". brainclaw
+// carries the rest for a worker that cannot (a sandboxed agent whose root
+// excludes `.git`, i.e. dispatchCanCommit=false): it COMMITS the worktree diff
+// on the worker's behalf so the code lands on the lane branch, then lifecycles
+// the assignment and releases the claim (with plan cascade). Self-commit / MCP /
+// self-lifecycle become PROGRESSIVE enrichments, not prerequisites.
+//
+// Strictly ADDITIVE + opt-in: nothing here runs unless a caller invokes
+// integrateLaneResults / `brainclaw harvest --integrate`. Existing harvest stays
+// report-only.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Happy-path assignment FSM chain walked when force-completing on behalf. */
+const ASSIGNMENT_COMPLETE_CHAIN = ['created', 'offered', 'accepted', 'started', 'completed'];
+/**
+ * Walk a still-open assignment forward to `completed` through the valid FSM
+ * chain (offered→accepted→started→completed), attaching artifacts on the final
+ * step. Idempotent (already-completed → true; transitions no-op). Returns false
+ * for assignments parked off the happy path (failed/blocked/timed_out) — those
+ * are not silently force-completed.
+ */
+function forceCompleteAssignment(assignmentId, artifacts, statusReason, actor, cwd) {
+    const current = loadAssignment(assignmentId, cwd);
+    if (!current)
+        return false;
+    if (current.status === 'completed')
+        return true;
+    const startIdx = ASSIGNMENT_COMPLETE_CHAIN.indexOf(current.status);
+    if (startIdx === -1)
+        return false; // off the happy path (failed/blocked/…): leave it.
+    for (let i = startIdx + 1; i < ASSIGNMENT_COMPLETE_CHAIN.length; i++) {
+        const next = ASSIGNMENT_COMPLETE_CHAIN[i];
+        try {
+            transitionAssignment(assignmentId, next, next === 'completed' ? { actor, artifacts, status_reason: statusReason } : { actor }, cwd);
+        }
+        catch {
+            // A concurrent explicit transition may have moved it; stop walking.
+            break;
+        }
+    }
+    return loadAssignment(assignmentId, cwd)?.status === 'completed';
+}
+/**
+ * Integrate completed lanes on behalf of workers that cannot self-commit.
+ *
+ * For each LANE-RESULT.json found (optionally filtered to one assignment):
+ *  1. resolve the assignment + the worker agent's commit capability;
+ *  2. when the worker CANNOT commit (sandboxed) and the worktree is dirty,
+ *     commit the diff on its behalf onto the lane branch (guarded to the linked
+ *     worktree only — never the main repo);
+ *  3. lifecycle the assignment (status=completed → walk to completed with the
+ *     commit + files as artifacts; status=blocked/failed → best-effort
+ *     transition) and release the claim with plan cascade.
+ *
+ * A worker that CAN commit is left to its self-commit handoff — brainclaw only
+ * lifecycles/releases, it does not author commits for it.
+ */
+export function integrateLaneResults(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const actor = options.agent ?? 'coordinator';
+    const result = { integrated: [], skipped: [], errors: [] };
+    const worktreePaths = (options.worktreePaths && options.worktreePaths.length > 0)
+        ? options.worktreePaths
+        : autoDetectWorktreePaths(cwd);
+    for (const worktreePath of worktreePaths) {
+        const file = getLaneResultPath(worktreePath);
+        if (!fs.existsSync(file))
+            continue;
+        let lane;
+        try {
+            lane = LaneResultSchema.parse(JSON.parse(fs.readFileSync(file, 'utf-8')));
+        }
+        catch (err) {
+            result.errors.push(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        if (options.assignmentId && lane.assignment_id !== options.assignmentId)
+            continue;
+        const assignment = loadAssignment(lane.assignment_id, cwd);
+        if (!assignment) {
+            result.skipped.push(lane.assignment_id);
+            result.errors.push(`No assignment record for lane ${lane.assignment_id} — cannot integrate`);
+            continue;
+        }
+        const profile = getCapabilityProfile(assignment.agent);
+        // No profile ⇒ assume it can commit (conservative: don't author for an
+        // unknown agent), so brainclaw only lifecycles.
+        const workerCanCommit = profile ? dispatchCanCommit(profile) : true;
+        const entry = {
+            assignment_id: lane.assignment_id,
+            worker_agent: assignment.agent,
+            lane_status: lane.status,
+            worker_can_commit: workerCanCommit,
+            committed_on_behalf: false,
+            files_changed: lane.files_changed ?? [],
+            assignment_completed: false,
+            claim_released: false,
+            reason: '',
+        };
+        const reasons = [];
+        // 1. Commit on behalf (only when the worker cannot, and there is a diff).
+        if (!workerCanCommit) {
+            if (options.dryRun) {
+                reasons.push('(dry-run) would commit worktree diff on behalf');
+            }
+            else {
+                const message = `chore(lane): integrate ${assignment.agent} work for ${lane.assignment_id}\n\n`
+                    + `${lane.summary}\n\n[brainclaw committed on behalf — worker sandbox cannot self-commit (pln#534)]`;
+                const commit = commitWorktreeOnBehalf(worktreePath, message, {
+                    authorName: `${assignment.agent} (via brainclaw)`,
+                    authorEmail: 'brainclaw@on-behalf.local',
+                });
+                entry.committed_on_behalf = commit.committed;
+                entry.commit_sha = commit.sha;
+                if (commit.committed)
+                    entry.files_changed = commit.files_changed;
+                reasons.push(commit.reason);
+            }
+        }
+        else {
+            reasons.push('worker can self-commit — no on-behalf commit');
+        }
+        // 2. Lifecycle + release.
+        if (!options.dryRun) {
+            if (lane.status === 'completed') {
+                const artifacts = [
+                    ...(entry.commit_sha ? [{ type: 'commit', ref: entry.commit_sha, description: 'on-behalf integration commit' }] : []),
+                    ...entry.files_changed.slice(0, 50).map((f) => ({ type: 'file', ref: f })),
+                ];
+                entry.assignment_completed = forceCompleteAssignment(lane.assignment_id, artifacts, `pln#534 on-behalf integration: ${lane.summary.slice(0, 120)}`, actor, cwd);
+                try {
+                    const rel = releaseClaimWithCascade(assignment.claim_id, { planStatus: 'done', cwd });
+                    entry.claim_released = rel.claim.status === 'released';
+                }
+                catch (err) {
+                    reasons.push(`claim release failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                // blocked / failed: best-effort lifecycle (FSM may reject from offered).
+                const target = lane.status === 'blocked' ? 'blocked' : 'failed';
+                try {
+                    transitionAssignment(lane.assignment_id, target, { actor, status_reason: lane.summary.slice(0, 200) }, cwd);
+                }
+                catch (err) {
+                    reasons.push(`assignment ${target} transition rejected: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                try {
+                    const rel = releaseClaimWithCascade(assignment.claim_id, {
+                        planStatus: lane.status === 'blocked' ? 'blocked' : undefined,
+                        cwd,
+                    });
+                    entry.claim_released = rel.claim.status === 'released';
+                }
+                catch (err) {
+                    reasons.push(`claim release failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Durable trace of the integration.
+            try {
+                createRuntimeEvent({
+                    agent: actor,
+                    event_type: 'lane_integrated',
+                    text: `Integrated lane ${lane.assignment_id} (${lane.status}) on behalf of ${assignment.agent}`,
+                    tags: ['harvest', 'integrate', 'worktree-as-contract', lane.status],
+                    assignment_id: lane.assignment_id,
+                    metadata: {
+                        assignment_id: lane.assignment_id,
+                        worker_agent: assignment.agent,
+                        committed_on_behalf: entry.committed_on_behalf,
+                        commit_sha: entry.commit_sha ?? null,
+                        files_changed: entry.files_changed,
+                        assignment_completed: entry.assignment_completed,
+                        claim_released: entry.claim_released,
+                    },
+                }, cwd);
+            }
+            catch { /* event is best-effort */ }
+        }
+        entry.reason = reasons.join('; ');
+        result.integrated.push(entry);
+    }
+    return result;
+}
 export function runHarvestLane(assignmentId, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
@@ -274,6 +465,38 @@ export function runHarvestLane(assignmentId, options = {}) {
         console.error('Error: provide an <assignment_id>, or pass --all to harvest every lane result.');
         process.exit(1);
     }
+    // pln#534 — `--integrate` upgrades harvest from report-only to converge-the-
+    // lane: commit the worktree diff on behalf of a sandboxed worker, lifecycle
+    // the assignment, and release the claim. Runs alongside the normal ingest.
+    if (options.integrate) {
+        const integ = integrateLaneResults({
+            assignmentId: options.all ? undefined : assignmentId,
+            worktreePaths: options.worktree,
+            dryRun: options.dryRun,
+            cwd,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(integ, null, 2));
+            return;
+        }
+        const dry = options.dryRun ? ' (dry-run)' : '';
+        if (integ.integrated.length === 0 && integ.errors.length === 0) {
+            console.log(assignmentId ? `No LANE-RESULT.json to integrate for ${assignmentId}.` : 'No lane results to integrate.');
+            return;
+        }
+        for (const e of integ.integrated) {
+            console.log(`  ✔ Integrated [${e.assignment_id}] ${e.lane_status} (worker=${e.worker_agent}, can_commit=${e.worker_can_commit})`);
+            if (e.committed_on_behalf)
+                console.log(`      committed on behalf: ${e.commit_sha?.slice(0, 10)} (${e.files_changed.length} file(s))`);
+            console.log(`      assignment_completed=${e.assignment_completed} claim_released=${e.claim_released}`);
+            if (e.reason)
+                console.log(`      ${e.reason}`);
+        }
+        for (const err of integ.errors)
+            console.error(`  ✗ ${err}`);
+        console.log(`\n✔ Lane integrate complete${dry}: ${integ.integrated.length} integrated, ${integ.errors.length} error(s).`);
+        return;
+    }
     const result = harvestLaneResults({
         assignmentId: options.all ? undefined : assignmentId,
         worktreePaths: options.worktree,

package/dist/commands/mcp.js

@@ -972,6 +972,7 @@ const MCP_WRITE_TOOLS = [
                 autoExecute: { type: 'boolean', description: 'Attempt to spawn target agents after delivery (default: true). When false, returns command_ready_manual with bash commands for the supervisor to run.' },
                 open_loop: { type: 'boolean', description: 'For intent=review only: also open a review Loop on top of the candidate (author + reviewer slots, advance to `findings`, dispatch turns). Default false — existing review callers are unaffected. See docs/concepts/loop-engine.md §Automation.' },
                 review_mode: { type: 'string', enum: ['asymmetric', 'symmetric'], description: 'Optional review Loop mode when open_loop=true. `asymmetric` (default) keeps the classical author→reviewer handoff; `symmetric` lets each reviewer turn also apply fixes directly, halving round-trips for spec/doc reviews. Ignored when open_loop is false.' },
+                preflight: { type: 'boolean', description: 'pln#533: when open_loop=true, run a trivial validation spawn per reviewer agent BEFORE opening the loop so an environment death (config rejected, auth fail, model mismatch) surfaces instantly with a clear reason instead of a generic loop timeout. Reviewers that fail pre-flight are dropped (with a targeted warning); if all fail, loop creation is skipped. Default true; set false to skip (e.g. you already ran `brainclaw doctor --spawn-check`). Ignored when open_loop is false or BRAINCLAW_NO_SPAWN is set.' },
                 agent: { type: 'string', description: 'Caller agent name.' },
                 agentId: { type: 'string', description: 'Caller registered agent id.' },
                 project: { type: 'string', description: 'Optional (pln#359 phase 1b): name of a linked project to dispatch into. When set, claim/assignment/message all land in the target project — the target agent picks the brief up async via its own bclaw_work. Auto-spawn is disabled in cross-project mode. Accepts cross_project_links and workspace store-chain children (see `brainclaw link list`).' },
@@ -4576,6 +4577,7 @@ async function _executeMcpToolCallInner(payload) {
                         dispatcherAgent: opts.senderAgent,
                         dispatcherAgentId: opts.senderAgentId,
                         cwd: opts.cwd,
+                        requireWorktree: true, // pln#531: never spawn a worker in the integration repo
                     });
                     entry.execution_status = execResult.execution_status;
                     if (execResult.pid)
@@ -4952,6 +4954,31 @@ async function _executeMcpToolCallInner(payload) {
                     loopReviewerAgents = resolvedAgents.slice(0, REVIEW_OPEN_LOOP_FANOUT_CAP);
                     preReviewWarnings.push(`open_loop: implicit reviewer fan-out capped at ${REVIEW_OPEN_LOOP_FANOUT_CAP} of ${resolvedAgents.length} spawnable agents; pass targetAgents to override`);
                 }
+                // pln#533 — pre-flight the reviewer agents with a trivial validation
+                // spawn BEFORE opening the loop, so an environment death (config
+                // rejected, auth fail, model mismatch) surfaces instantly with a clear
+                // reason instead of a generic "did not acknowledge" loop timeout. Drop
+                // the agents that fail and surface their reasons; if none survive the
+                // existing length===0 guard skips loop creation. Skipped when open_loop
+                // is off, preflight=false, or BRAINCLAW_NO_SPAWN is set (handled inside
+                // preflightAgents). Cross-project dispatch never auto-spawns, so skip.
+                if (req.open_loop === true && req.preflight !== false && !req.project && loopReviewerAgents.length > 0) {
+                    try {
+                        const { preflightAgents } = await import('../core/spawn-check.js');
+                        const pf = await preflightAgents(loopReviewerAgents, { cwd: dispatchCwd });
+                        if (pf.blocked.length > 0) {
+                            const healthy = loopReviewerAgents.filter((a) => !pf.blocked.some((b) => b.agent === a));
+                            for (const b of pf.blocked) {
+                                preReviewWarnings.push(`pre-flight: dropped reviewer '${b.agent}' — ${b.reason}.${b.recommended_next_action ? ` ${b.recommended_next_action}` : ''}`);
+                            }
+                            loopReviewerAgents = healthy;
+                        }
+                    }
+                    catch (pfErr) {
+                        // Pre-flight is best-effort: a failure here must not block the review.
+                        preReviewWarnings.push(`pre-flight: skipped (check threw: ${pfErr instanceof Error ? pfErr.message : String(pfErr)})`);
+                    }
+                }
                 // Lazy-import the loops module once before defining performReview so
                 // the synchronous withLoopLock work callback can use it without
                 // re-importing inside the callback.

package/dist/core/dispatch-status.js

@@ -26,6 +26,7 @@ import { loadClaim } from './claims.js';
 import { getLoop, listLoops } from './loops/store.js';
 import { isProcessAlive } from './agentrun-reconciler.js';
 import { latestActivityMs } from './runtime-signals.js';
+import { LaneResultSchema } from './schema.js';
 const DEFAULT_TAIL = 20;
 const DEFAULT_STALL_MS = 5 * 60_000;
 // ── Internal helpers ──────────────────────────────────────────────────────
@@ -136,6 +137,24 @@ function computeDiagnosis(assignment, agentRun, runtime, options) {
             recommended_next_action: 'Verify the target_id is correct (asgn_/clm_/lop_/run_). Use bclaw_find(entity="assignment") to list available assignments.',
         };
     }
+    // pln#532 — RESULT is the #1 verdict signal. If the worker wrote LANE-RESULT.json
+    // it has FINISHED — regardless of pid / heartbeat / agent_run.status (a sandboxed
+    // worker frequently cannot self-update the run). This sits above every other
+    // signal, including the agent_run terminal/running checks below.
+    if (runtime.lane_result) {
+        const lr = runtime.lane_result;
+        const ok = lr.status === 'completed';
+        const stale = agentRun && agentRun.status !== 'completed'
+            ? ` (agent_run still ${agentRun.status}; the worker could not self-update — harvest reconciles it)`
+            : '';
+        return {
+            health: 'terminal',
+            summary: `worker reported done via LANE-RESULT.json: status=${lr.status} — ${lr.summary.slice(0, 140)}${stale}`,
+            recommended_next_action: ok
+                ? 'Worker finished. `brainclaw harvest <assignment_id>` to ingest the result, then commit/integrate its worktree diff and converge the lane.'
+                : `Worker reported "${lr.status}". Read the LANE-RESULT summary + stderr; address the blocker or reroute.`,
+        };
+    }
     if (!agentRun) {
         return {
             health: 'not_dispatched',
@@ -248,6 +267,16 @@ export function getDispatchStatus(options) {
         if (lastFs !== undefined)
             lastFsActivityMs = nowMs - lastFs;
     }
+    // pln#532 — the #1 verdict signal: a LANE-RESULT.json at the worktree root means
+    // the worker FINISHED (even if it couldn't self-update the run). Read + validate it.
+    let laneResult;
+    if (worktreeForFs) {
+        try {
+            const parsed = LaneResultSchema.parse(JSON.parse(fs.readFileSync(path.join(worktreeForFs, 'LANE-RESULT.json'), 'utf-8')));
+            laneResult = { status: parsed.status, summary: parsed.summary };
+        }
+        catch { /* no / invalid LANE-RESULT.json */ }
+    }
     const runtime = {
         pid: agentRun?.pid,
         pid_alive: isProcessAlive(agentRun?.pid),
@@ -260,6 +289,7 @@ export function getDispatchStatus(options) {
             stderr: stderrPath ? readLogTail(stderrPath, tailLines) : undefined,
         },
         last_fs_activity_ms: lastFsActivityMs,
+        lane_result: laneResult,
     };
     const diagnosis = computeDiagnosis(assignment, agentRun, runtime, { stallMs, nowMs });
     return {

package/dist/core/dispatcher.js

@@ -850,6 +850,7 @@ export async function dispatch(options, cwd) {
                 dispatcherAgentId: options.dispatcherAgentId,
                 cwd,
                 handshakeTimeoutMs: options.handshakeTimeoutMs,
+                requireWorktree: true, // pln#531: never spawn a worker in the integration repo
             });
             entry.execution_status = execResult.execution_status;
             if (execResult.pid)

package/dist/core/entity-registry.js

@@ -107,7 +107,7 @@ const decision = {
     name: 'decision',
     shortLabelPrefix: 'dec',
     schema: DecisionSchema,
-    updatable: ['text', 'tags', 'outcome', 'scope', 'related_paths'],
+    updatable: ['text', 'tags', 'outcome', 'scope', 'related_paths', 'verified_at', 'verify_cmd'],
     statusField: 'outcome',
     transitions: {
         pending: ['approved', 'rejected', 'deferred'],
@@ -137,7 +137,7 @@ const trap = {
     name: 'trap',
     shortLabelPrefix: 'trp',
     schema: TrapSchema,
-    updatable: ['text', 'tags', 'severity', 'scope', 'related_paths', 'expires_at', 'platform_scope'],
+    updatable: ['text', 'tags', 'severity', 'scope', 'related_paths', 'expires_at', 'platform_scope', 'verified_at', 'verify_cmd'],
     statusField: 'status',
     transitions: {
         active: ['resolved', 'expired'],

package/dist/core/execution.js

@@ -156,6 +156,31 @@ export async function attemptExecution(invoke, options) {
             shell: manual.shell,
         };
     }
+    // pln#531 — isolation invariant: a spawned worker MUST run in its own
+    // worktree. If a worktree was required but none exists (creation failed, or a
+    // claim was reused/re-dispatched without one), REFUSE to spawn instead of
+    // falling back to options.cwd — which is the integration repo, where the
+    // worker would edit the main tree directly (dangerous for an autonomous fleet,
+    // debrief LeaseUp). Return the command for manual, isolated execution.
+    if (options.requireWorktree && !options.worktreePath) {
+        appendAuditEntry({
+            actor: options.dispatcherAgent,
+            actor_id: options.dispatcherAgentId,
+            action: 'spawn_failed',
+            item_id: options.claimId,
+            item_type: 'claim',
+            scope: options.agent,
+            after: { reason: 'no_worktree', refused: true },
+        }, options.cwd);
+        const manual = adapter.prepareManualCommand(invoke, options);
+        return {
+            execution_status: 'command_ready_manual',
+            command: manual.command,
+            shell: manual.shell,
+            error: 'Refusing to spawn without an isolated worktree: with no worktree the worker would run in the integration repo and edit the main tree. Fix worktree creation (see claim worktreeWarning) or run the command manually inside a worktree.',
+            failure_kind: 'spawn_no_worktree',
+        };
+    }
     // Capacity guard: skip if agent is at max concurrent tasks
     if (options.cwd) {
         const instanceCheck = checkActiveInstance(options.agent, options.cwd);

package/dist/core/facade-schema.js

@@ -39,6 +39,16 @@ export const CoordinateRequestSchema = z.object({
      * Ignored when open_loop is false. Defaults to asymmetric.
      */
     review_mode: z.enum(['asymmetric', 'symmetric']).optional(),
+    /**
+     * pln#533: when opening a review Loop (open_loop=true), run a trivial
+     * validation spawn against each reviewer agent first so an environment death
+     * (config rejected, auth fail, model mismatch) surfaces instantly with a
+     * clear reason instead of a generic loop timeout. Defaults to true for
+     * open_loop reviews; set false to skip (e.g. when you have just spawn-checked
+     * the agents yourself). Ignored when open_loop is false or BRAINCLAW_NO_SPAWN
+     * is set.
+     */
+    preflight: z.boolean().optional(),
     /**
      * Caller-minted ULID/UUIDv7 for idempotent retries. Today this is observed
      * on intent='review' + open_loop=true: a retry with the same

package/dist/core/schema.js

@@ -154,6 +154,11 @@ export const DecisionSchema = z.object({
     related_paths: z.array(z.string()).optional(),
     plan_id: z.string().optional(),
     tags: TagsSchema,
+    // pln#530 — anti-staleness: ISO timestamp this fact was last empirically
+    // verified, and an optional command to re-confirm it. For fast-perishable
+    // facts (tool behaviour, config values), probe before trusting the memory.
+    verified_at: z.string().optional(),
+    verify_cmd: z.string().optional(),
     provenance: ProvenancePassthroughSchema,
 });
 export const TrapSchema = z.object({
@@ -177,6 +182,11 @@ export const TrapSchema = z.object({
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
     platform_scope: z.string().optional(),
+    // pln#530 — anti-staleness (see DecisionSchema): when did we last verify this
+    // is still true, and how to re-confirm it. Critical for environment/tool-fix
+    // traps that go stale (e.g. a service_tier value that the API later rejects).
+    verified_at: z.string().optional(),
+    verify_cmd: z.string().optional(),
     provenance: ProvenancePassthroughSchema,
 });
 export const HandoffContractSchema = z.object({
@@ -856,6 +866,7 @@ export const RuntimeEventTypeSchema = z.enum([
     'plan_cascade_to_done',
     'candidate_harvested',
     'lane_result_harvested',
+    'lane_integrated',
 ]);
 /**
  * pln#526 — LANE-RESULT convention. A dispatched worker writes a single

package/dist/core/spawn-check.js

@@ -17,14 +17,33 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { buildInvokeCommand, getSpawnableAgents, getCapabilityProfile, } from './agent-capability.js';
 import { defaultExecutionAdapter, resolveBinaryOnPath } from './execution-adapters.js';
 import { signalExists, readLogTail } from './runtime-signals.js';
+import { recognizeStderrSignature } from './dispatch-status.js';
 const DEFAULT_PROBE_TIMEOUT_MS = 15_000;
 const DEFAULT_PROBE_PROMPT = 'Reply with exactly: OK';
 async function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+/**
+ * Make the probe's temp dir a real (empty) git repo so the round-trip is
+ * representative of a real dispatch (workers always run inside a git worktree)
+ * and so CLIs with a boot-time git-repo / trusted-directory check don't refuse
+ * it (pln#533 fix). Best-effort: if git is unavailable the probe still runs.
+ */
+function initProbeGitRepo(root) {
+    try {
+        const run = (...args) => spawnSync('git', args, { cwd: root, encoding: 'utf-8', timeout: 5000 });
+        run('init', '-q');
+        run('config', 'user.email', 'spawn-check@brainclaw.local');
+        run('config', 'user.name', 'brainclaw spawn-check');
+        run('config', 'commit.gpgsign', 'false');
+        run('commit', '--allow-empty', '-q', '-m', 'spawn-check probe');
+    }
+    catch { /* git absent or failed — probe proceeds without it */ }
+}
 /** Check one agent's spawn round-trip. Exposed for focused testing. */
 export async function checkAgentSpawn(agent, options = {}) {
     const start = Date.now();
@@ -43,6 +62,11 @@ export async function checkAgentSpawn(agent, options = {}) {
     }
     // Isolated signals root so the probe never pollutes the project's runtime dir.
     const root = fs.mkdtempSync(path.join(os.tmpdir(), `bclaw-spawncheck-${agent}-`));
+    // pln#533 fix: make the probe dir a real git repo. Real workers run inside a
+    // git worktree, and some CLIs refuse a non-git / untrusted dir at boot (codex:
+    // "Not inside a trusted directory and --skip-git-repo-check was not specified")
+    // — a non-git temp dir would otherwise produce a false-negative spawn failure.
+    initProbeGitRepo(root);
     const assignmentId = 'spawn_check';
     try {
         defaultExecutionAdapter.start(invoke, { agent, assignmentId, ackRoot: root, worktreePath: root });
@@ -59,17 +83,21 @@ export async function checkAgentSpawn(agent, options = {}) {
         const completed = signalExists(root, assignmentId, 'completed');
         const failed = signalExists(root, assignmentId, 'failed');
         const duration_ms = Date.now() - start;
+        // Capture the stderr tail once (used both for the detail string and for
+        // pln#533 boot-signature recognition on the preflight path).
+        const stderrRaw = readLogTail(root, assignmentId, 'stderr', 800).trim();
+        const stderrTail = stderrRaw ? stderrRaw.split(/\r?\n/).filter(Boolean) : undefined;
         if (completed) {
             return { agent, binary, status: 'ok', delivered, completed: true, duration_ms, detail: 'ack + completed round-trip' };
         }
         if (failed) {
-            const tail = readLogTail(root, assignmentId, 'stderr', 400).trim() || readLogTail(root, assignmentId, 'stdout', 400).trim();
-            return { agent, binary, status: 'failed', delivered, completed: false, duration_ms, detail: `wrapper reported failure${tail ? ` — ${tail.replace(/\s+/g, ' ').slice(0, 200)}` : ''}` };
+            const tail = stderrRaw || readLogTail(root, assignmentId, 'stdout', 400).trim();
+            return { agent, binary, status: 'failed', delivered, completed: false, duration_ms, detail: `wrapper reported failure${tail ? ` — ${tail.replace(/\s+/g, ' ').slice(0, 200)}` : ''}`, stderr_tail: stderrTail };
         }
         if (delivered) {
-            return { agent, binary, status: 'delivered_no_completion', delivered: true, completed: false, duration_ms, detail: `spawned + ack but no completion within ${timeout}ms (silent-death symptom)` };
+            return { agent, binary, status: 'delivered_no_completion', delivered: true, completed: false, duration_ms, detail: `spawned + ack but no completion within ${timeout}ms (silent-death symptom)`, stderr_tail: stderrTail };
         }
-        return { agent, binary, status: 'failed', delivered: false, completed: false, duration_ms, detail: `no ack within ${timeout}ms — delivery failed` };
+        return { agent, binary, status: 'failed', delivered: false, completed: false, duration_ms, detail: `no ack within ${timeout}ms — delivery failed`, stderr_tail: stderrTail };
     }
     finally {
         try {
@@ -122,4 +150,82 @@ export function renderSpawnCheckReport(report) {
     }
     return lines.join('\n');
 }
+/**
+ * Pre-flight a single target agent. Pass criteria:
+ *   - `ok` (ack + completed) → pass.
+ *   - `delivered_no_completion` (ack but the trivial probe didn't finish in the
+ *     short window) → PASS: the ack proves spawn + wrapper + delivery work; a
+ *     boot death never acks. We don't want a slow-but-healthy agent to block.
+ *   - `failed` / no-ack → BLOCK with a reason (enriched by a recognized boot
+ *     signature when the stderr matches one).
+ *   - `not_installed` / `no_template` → BLOCK: the agent cannot be spawned here,
+ *     so opening a loop on it would only time out.
+ * When BRAINCLAW_NO_SPAWN is set (tests/CI), pre-flight is skipped (ok:true).
+ */
+/**
+ * Pure mapper: SpawnCheckEntry → PreflightResult. No spawning — exposed so the
+ * pass/block policy (and the boot-signature enrichment) can be unit-tested with
+ * synthetic entries.
+ */
+export function preflightResultFromEntry(entry) {
+    const agent = entry.agent;
+    if (entry.status === 'ok' || entry.status === 'delivered_no_completion') {
+        return { agent, ok: true, status: entry.status, reason: entry.detail };
+    }
+    if (entry.status === 'not_installed') {
+        return {
+            agent, ok: false, status: entry.status,
+            reason: `${agent} binary not on PATH — cannot spawn it here`,
+            recommended_next_action: `Install the ${agent} CLI (or target a different agent), then retry.`,
+        };
+    }
+    if (entry.status === 'no_template') {
+        return {
+            agent, ok: false, status: entry.status,
+            reason: `${agent} has no CLI spawn template — it cannot be auto-dispatched (IDE-only?)`,
+            recommended_next_action: `Target a CLI-spawnable agent, or hand this work to ${agent} interactively.`,
+        };
+    }
+    // failed (or no-ack) — try to attach a recognized boot signature.
+    const sig = recognizeStderrSignature(entry.stderr_tail);
+    return {
+        agent, ok: false, status: entry.status,
+        reason: sig?.summary ?? `${agent} failed its pre-flight spawn — ${entry.detail}`,
+        recommended_next_action: sig?.recommended_next_action
+            ?? `Inspect the ${agent} CLI config/auth (run \`brainclaw doctor --spawn-check\` for detail), fix it, then retry.`,
+    };
+}
+export async function preflightAgentSpawn(agent, options = {}) {
+    if (process.env.BRAINCLAW_NO_SPAWN === '1') {
+        return { agent, ok: true, status: 'skipped', reason: 'pre-flight skipped (BRAINCLAW_NO_SPAWN)' };
+    }
+    // Pre-flight uses a tighter window than the full doctor round-trip: a boot
+    // death fails fast, and an ack is enough to pass, so we don't need to wait
+    // out a healthy agent's full probe completion.
+    const entry = await checkAgentSpawn(agent, { timeoutMs: 8_000, ...options });
+    return preflightResultFromEntry(entry);
+}
+/**
+ * Pre-flight a set of target agents (deduped), one trivial probe each. Returns
+ * the per-agent results plus `blocked` (the agents that failed). Callers use
+ * `blocked` to skip those agents and surface their reasons instead of opening a
+ * loop / dispatching work that would only time out.
+ */
+export async function preflightAgents(agents, options = {}) {
+    const unique = [...new Set(agents)];
+    const results = [];
+    for (const agent of unique) {
+        try {
+            results.push(await preflightAgentSpawn(agent, options));
+        }
+        catch (err) {
+            results.push({
+                agent, ok: false, status: 'failed',
+                reason: `pre-flight threw: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    const blocked = results.filter((r) => !r.ok);
+    return { results, blocked, all_ok: blocked.length === 0 };
+}
 //# sourceMappingURL=spawn-check.js.map

package/dist/core/staleness.js

@@ -100,6 +100,41 @@ export function detectExpiredTraps(traps, nowIso = new Date().toISOString(), now
     }
     return warnings;
 }
+/** pln#530 — a perishable fact unverified for longer than this reads as stale. */
+const VERIFIED_STALE_DAYS = 30;
+/**
+ * pln#530 — flag perishable memories (traps that opted in by carrying a
+ * `verify_cmd` and/or `verified_at`) whose last empirical verification is stale
+ * or never happened, so an agent re-probes the live system instead of trusting a
+ * value that may have drifted (the LeaseUp `service_tier` trap that the API later
+ * rejected is the motivating case). Only traps with these fields are considered —
+ * durable facts are untouched.
+ */
+export function detectUnverifiedMemory(traps, nowMs = Date.now()) {
+    const warnings = [];
+    for (const trap of traps) {
+        if (trap.status !== 'active')
+            continue;
+        if (!trap.verify_cmd && !trap.verified_at)
+            continue; // opt-in: only perishable facts
+        const age = trap.verified_at ? ageDays(trap.verified_at, nowMs) : Infinity;
+        if (trap.verified_at && age < VERIFIED_STALE_DAYS)
+            continue; // freshly verified
+        warnings.push({
+            id: trap.id,
+            entity: 'trap',
+            text: truncate(trap.text),
+            age_days: Number.isFinite(age) ? age : 9999,
+            reason: trap.verified_at
+                ? `Perishable fact last verified ${age} day${age === 1 ? '' : 's'} ago — re-confirm against the live system before trusting`
+                : `Perishable fact never empirically verified (verify_cmd set) — confirm before trusting`,
+            suggested_action: trap.verify_cmd
+                ? `Run \`${trap.verify_cmd}\`, then bclaw_update(trap, ${trap.short_label ?? trap.id}, { verified_at: <now> })`
+                : `Re-verify against the live system, then set verified_at via bclaw_update`,
+        });
+    }
+    return warnings;
+}
 /**
  * Detect open handoffs that have not been acted on for a long time.
  */
@@ -207,12 +242,14 @@ export function detectStaleness(plans, traps, handoffs, candidates, nowMs = Date
     const nowIso = new Date(nowMs).toISOString();
     const planWarnings = detectStalePlans(plans, nowMs);
     const trapWarnings = detectExpiredTraps(traps, nowIso, nowMs);
+    const unverifiedWarnings = detectUnverifiedMemory(traps, nowMs); // pln#530
     const handoffWarnings = detectStaleHandoffs(handoffs, nowMs);
     const candidateWarnings = detectStaleCandidates(candidates, nowMs);
     const noteWarnings = detectStaleRuntimeNotes(runtimeNotes, nowMs);
     const warnings = [
         ...planWarnings,
         ...trapWarnings,
+        ...unverifiedWarnings,
         ...handoffWarnings,
         ...candidateWarnings,
         ...noteWarnings,

package/dist/core/worktree.js

@@ -176,6 +176,104 @@ export function hasGitLock(cwd) {
     const lockPath = path.join(gitDir.stdout.trim(), 'index.lock');
     return fs.existsSync(lockPath);
 }
+/**
+ * True when `worktreePath` is a LINKED git worktree (created by `git worktree
+ * add`), NOT the main repository. The key invariant for pln#534's commit-on-
+ * behalf: brainclaw must NEVER commit into the integration repo, only into the
+ * isolated worktree it dispatched.
+ *
+ * Detection uses the canonical, platform-stable signal: in a linked worktree
+ * the entry at `<worktree>/.git` is a FILE (a `gitdir: …` pointer into the main
+ * repo's `.git/worktrees/<name>`), whereas the main repository's `.git` is a
+ * DIRECTORY. (An earlier implementation compared `git rev-parse
+ * --absolute-git-dir` against `--git-common-dir`, but those returned
+ * differently-normalized paths on the Windows CI runner — short 8.3 names /
+ * drive-letter case — so the main repo was misread as linked. The file-vs-dir
+ * check needs no path normalization.)
+ */
+export function isLinkedWorktree(worktreePath) {
+    if (!fs.existsSync(worktreePath))
+        return false;
+    try {
+        const dotGit = path.join(worktreePath, '.git');
+        const st = fs.statSync(dotGit);
+        // main repo → .git is a directory; linked worktree → .git is a file pointer.
+        return st.isFile();
+    }
+    catch {
+        return false; // no .git entry → not a git worktree
+    }
+}
+/**
+ * pln#534 (worktree-as-contract) — commit the uncommitted diff of a dispatched
+ * worktree ON BEHALF of a worker that cannot commit itself (a sandboxed agent
+ * whose root excludes `.git`, i.e. `dispatchCanCommit=false`). The worker's only
+ * contract is "edit files in this worktree + drop LANE-RESULT.json"; brainclaw
+ * carries the commit so the code lands on the lane branch and propagates.
+ *
+ * GUARDS (defence-in-depth, since this writes git history):
+ *   - the path must exist and be a LINKED worktree — NEVER the main repo;
+ *   - no commit when an index.lock is present (concurrent git op);
+ *   - no commit when the worktree is clean;
+ *   - all git runs are `spawnSync('git', [...])` with `-C <worktree>` semantics
+ *     (cwd-scoped, no shell) so nothing can escape the worktree.
+ * Returns a structured result instead of throwing so callers degrade gracefully.
+ */
+export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
+    if (!fs.existsSync(worktreePath)) {
+        return { committed: false, files_changed: [], reason: `worktree path does not exist: ${worktreePath}` };
+    }
+    if (!isLinkedWorktree(worktreePath)) {
+        return { committed: false, files_changed: [], reason: `refusing to commit: ${worktreePath} is not a linked git worktree (main-repo guard)` };
+    }
+    if (hasGitLock(worktreePath)) {
+        return { committed: false, files_changed: [], reason: 'git index.lock present — another git operation is in progress' };
+    }
+    const status = runGit(['status', '--porcelain'], worktreePath);
+    if (!status.ok) {
+        return { committed: false, files_changed: [], reason: `git status failed: ${status.stderr.trim()}` };
+    }
+    if (status.stdout.trim().length === 0) {
+        return { committed: false, files_changed: [], reason: 'worktree clean — nothing to commit' };
+    }
+    // Stage everything, then UNSTAGE the transient files that must never land on
+    // the lane branch: the worker's own `LANE-RESULT.json` report and any
+    // `.brainclaw/` coordination state. Committing those would pollute the branch
+    // (and master, on merge) with non-deliverable artefacts.
+    const add = runGit(['add', '-A'], worktreePath);
+    if (!add.ok) {
+        return { committed: false, files_changed: [], reason: `git add failed: ${add.stderr.trim()}` };
+    }
+    runGit(['reset', '-q', '--', 'LANE-RESULT.json', '.brainclaw'], worktreePath);
+    // The files actually staged for this commit (post-exclusion) — also the
+    // truthful files_changed report.
+    const staged = runGit(['diff', '--cached', '--name-only'], worktreePath);
+    const files = staged.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    if (files.length === 0) {
+        // Only transient files changed — nothing deliverable to commit. Restore the
+        // index so the worktree is left exactly as the worker left it.
+        runGit(['reset', '-q'], worktreePath);
+        return { committed: false, files_changed: [], reason: 'no committable changes (only transient LANE-RESULT.json / .brainclaw)' };
+    }
+    const authorName = options.authorName ?? 'brainclaw (on behalf)';
+    const authorEmail = options.authorEmail ?? 'brainclaw@on-behalf.local';
+    const commit = runGit([
+        '-c', `user.name=${authorName}`,
+        '-c', `user.email=${authorEmail}`,
+        '-c', 'commit.gpgsign=false',
+        'commit', '-m', message,
+    ], worktreePath);
+    if (!commit.ok) {
+        return { committed: false, files_changed: files, reason: `git commit failed: ${commit.stderr.trim()}` };
+    }
+    const head = runGit(['rev-parse', 'HEAD'], worktreePath);
+    return {
+        committed: true,
+        sha: head.ok ? head.stdout.trim() : undefined,
+        files_changed: files,
+        reason: 'committed on behalf of worker',
+    };
+}
 /**
  * Re-points an EXISTING worktree to `ref` via a hard reset of its checked-out
  * branch + working tree. Used when a dispatch reuses an existing claim/worktree

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.7.5 on 2026-06-09T05:31:24.417Z
+// Source: brainclaw v1.8.0 on 2026-06-09T07:31:59.599Z
 export const FACTS = {
-  "version": "1.7.5",
-  "generated_at": "2026-06-09T05:31:24.417Z",
+  "version": "1.8.0",
+  "generated_at": "2026-06-09T07:31:59.599Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.5",
-  "generated_at": "2026-06-09T05:31:24.417Z",
+  "version": "1.8.0",
+  "generated_at": "2026-06-09T07:31:59.599Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/docs/concepts/dispatch-lifecycle.md

@@ -150,6 +150,23 @@ You called `bclaw_coordinate(intent="review", open_loop=true, …)` and got back
 
 ---
 
+## Worktree-as-contract harvest
+
+Some dispatched workers cannot self-commit or call MCP. For example, a sandboxed Codex run may have `dispatchCanCommit=false` because its writable root is the linked worktree, while `.git` lives outside that root. In that case the worker contract is intentionally small:
+
+1. Edit files inside the dispatched worktree.
+2. Write `LANE-RESULT.json` at the worktree root.
+
+The worker does not need to commit, call `bclaw_assignment_update`, or release the claim itself. The worktree is the contract.
+
+When the coordinator runs `brainclaw harvest <assignment_id> --integrate`, brainclaw reads the worker's `LANE-RESULT.json`, commits the linked worktree diff on the worker's behalf onto the lane branch, then completes the assignment and releases the claim, including the normal plan-status cascade.
+
+The on-behalf commit is guarded by the linked-worktree check (`isLinkedWorktree`): integration only targets the worktree associated with the assignment, never the main repository. This keeps sandboxed-worker harvesting from turning into an accidental main-repo commit path.
+
+Integration is strictly additive and opt-in. Plain `brainclaw harvest <assignment_id>` remains report-only; it reads and reports the lane result without committing or mutating assignment / claim state. The on-behalf commit and lifecycle completion happen only when the coordinator passes `--integrate`.
+
+---
+
 ## Diagnostic playbook
 
 When a dispatch hangs, work top-down through these checks. For the symptom-driven variant see [troubleshooting.md#inbox-messages-stuck--brief-ack-never-arrived](troubleshooting.md#inbox-messages-stuck--brief-ack-never-arrived).

package/docs/mcp-schema-changelog.md

@@ -19,7 +19,7 @@ guarantees this changelog follows.
   to `sha256:860fbaa30a486093` (zod 4). No tool was added, removed,
   renamed, or had its required arguments change.
 
-**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
+**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
 - New optional field `allow_orphan: boolean` on `BclawLoopOpenSchema`.
 - Default (absent / `false`) — handler rejects with `validation_error`
   and points to `bclaw_coordinate(intent: 'review', open_loop: true)`
@@ -28,20 +28,20 @@ guarantees this changelog follows.
   out in `CLAUDE.md`.
 - `allow_orphan: true` — explicit acknowledgement that the caller
   will drive `turn()` + dispatch manually (advanced / test use only).
-- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
-  affected — they bypass `handleBclawLoop` and invoke the core
-  `openLoop()` directly.
-
-**Changed — sequence tools promoted to default discovery (pln#522)**
-- `bclaw_list_sequences`, `bclaw_create_sequence`,
-  `bclaw_update_sequence`, and `bclaw_delete_sequence` move from
-  `advanced` to `standard`, so fresh agents see them in the default
-  `tools/list` catalog. Sequences are a core agent-first coordination
-  primitive for parallel dispatch, not an advanced-only admin surface.
-- `bclaw_create_sequence.items` and `bclaw_update_sequence.items` now
-  expose the full item shape in JSON Schema: `planId`, optional
-  `stepId`, `rank`, `hard_after`, `soft_after`, `lane`, `scope_hint`,
-  and `rationale`.
+- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
+  affected — they bypass `handleBclawLoop` and invoke the core
+  `openLoop()` directly.
+
+**Changed — sequence tools promoted to default discovery (pln#522)**
+- `bclaw_list_sequences`, `bclaw_create_sequence`,
+  `bclaw_update_sequence`, and `bclaw_delete_sequence` move from
+  `advanced` to `standard`, so fresh agents see them in the default
+  `tools/list` catalog. Sequences are a core agent-first coordination
+  primitive for parallel dispatch, not an advanced-only admin surface.
+- `bclaw_create_sequence.items` and `bclaw_update_sequence.items` now
+  expose the full item shape in JSON Schema: `planId`, optional
+  `stepId`, `rank`, `hard_after`, `soft_after`, `lane`, `scope_hint`,
+  and `rationale`.
 
 ---
 
@@ -93,11 +93,15 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:a1881ff57ddce377`
-  (updated 2026-05-27: added the `ref` property to the bclaw_coordinate
-  inputSchema — pln#520 Tier 2 / trp#371, the scope-aware dirty guard;
-  `ref` lets a dispatch build its worktree from an explicit git ref.
-  Prior value `sha256:0a4ba280aeff142b` exposed `allow_dirty` in the
+- MCP public surface fingerprint: `sha256:333be7c3cda7e166`
+  (updated 2026-06-09: added the `preflight` boolean to the bclaw_coordinate
+  inputSchema — pln#533, the pre-flight spawn validation for open_loop reviews
+  (run one trivial validation spawn per reviewer before opening the loop so an
+  environment death surfaces with a clear reason instead of a generic timeout).
+  Prior value `sha256:a1881ff57ddce377` added the `ref` property to the
+  bclaw_coordinate inputSchema (2026-05-27, pln#520 Tier 2 / trp#371, the
+  scope-aware dirty guard; `ref` lets a dispatch build its worktree from an
+  explicit git ref). `sha256:0a4ba280aeff142b` exposed `allow_dirty` in the
   bclaw_coordinate inputSchema. `sha256:e88c1a97fc29cfd1` came from the
   pln#520 LoopPhase/LoopSlotInput schema resync, which itself reconciled
   earlier unrecorded drift from `sha256:724085642dc3e2d7`.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.7.5",
+  "version": "1.8.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {