brainclaw 1.17.0 → 1.18.0

package/dist/core/review-loop-turn-dispatch.js

@@ -19,12 +19,205 @@
  * here imports harvest or review-loop-close, so no import cycle is introduced.
  */
 import { createCoordinatorClaim, attachAssignmentMessageToClaim, linkClaimToAssignment } from './claims.js';
-import { createAssignment, transitionAssignment, generateAssignmentId, patchAssignmentMessageId } from './assignments.js';
+import { createAssignment, transitionAssignment, generateAssignmentId, patchAssignmentMessageId, loadAssignment } from './assignments.js';
 import { turn } from './loops/verbs.js';
+import { getLoop } from './loops/store.js';
 import { generateDispatchBrief } from './dispatcher.js';
 import { sendMessage } from './messaging.js';
 import { buildInvokeCommand, resolveModel } from './agent-capability.js';
 import { attemptExecution } from './execution.js';
+import { createAgentRun, loadAgentRun, transitionAgentRun } from './agentruns.js';
+import { reserve, commitReservation, armLaunch, consumeLaunchGrant, launchGrant, deriveTurnId, deriveChildIds, ReservationStateError, LaunchFenceError, } from './loops/attempt-reservation.js';
+/**
+ * pln#630 — gate for the turn-owned (exactly-once) review dispatch path.
+ *
+ * NOW DEFAULT ON (the shipped default): the finalization (PR3a), autonomous fix-cycle (PR3b),
+ * strand self-heal (PR4), and revoked-grant recovery (R1) are all merged; the §9 conformance
+ * harness + a live end-to-end (real spawn → turn-keyed sentinel → harvest → reconcileTurn →
+ * close-on-approve) validated the path. `BRAINCLAW_TURN_OWNED_REVIEW=0` is the explicit
+ * KILL-SWITCH that reverts to the legacy closer (byte-identical) if a problem surfaces in prod.
+ * Note the routing is doubly-gated: even ON, harvest only reconcile-turns a lane that OWNS a
+ * turn reservation — a legacy-dispatched lane (no reservation) still uses the legacy path.
+ */
+export function turnOwnedReviewEnabled() {
+    // Normalized kill-switch (review Finding 4): any of 0/false/off/no (case/space-insensitive)
+    // disables — so an operator reaching for it under pressure can't mis-set it. Anything else
+    // (including unset) keeps the shipped default ON.
+    const v = (process.env.BRAINCLAW_TURN_OWNED_REVIEW ?? '').trim().toLowerCase();
+    return !['0', 'false', 'off', 'no'].includes(v);
+}
+/** GRANT lease: bounds ONE launch generation's reserve→arm→consume→spawn→run-`running`
+ *  window. Long enough that a genuinely launching worker never expires under the PR2c-lease
+ *  pre-run reconciler; a live `running` run is out of that reconciler's scope. */
+const TURN_OWNED_LEASE_MS = 10 * 60_000;
+/** DISPATCH lease: how long the committed RESERVATION stays re-dispatchable. Strictly LONGER
+ *  than the grant lease (pln#630 dec#149 R1 / review Finding 1): a reserved_never_launched
+ *  round (grant lease expired → the reconciler revokes the grant) then still has a RECOVERY
+ *  WINDOW to re-arm a fresh generation before the reservation itself expires. armLaunch
+ *  enforces this bound, so a re-dispatch past it refuses arm and stays correctly stranded —
+ *  no phantom-spawn-after-lease. Decoupling the two is what makes R1 recovery actually reachable
+ *  (with a single shared lease, the grant is revoked exactly when the dispatch lease is already
+ *  expired, so re-arm was always denied). */
+const TURN_OWNED_DISPATCH_LEASE_MS = 30 * 60_000;
+/**
+ * Prepare a turn-owned review dispatch (pln#630 PR2c-b, design dec#144). Runs the
+ * exactly-once machine INLINE in the coordinator (which has store access, unlike
+ * the sandboxed worktree — trp_26e9634b): deterministic turn_id → reserve/adopt →
+ * commit → arm/adopt → consume, spawning ONLY on the winning consume.
+ *
+ * FAIL-CLOSED after `reserve`: once identity is claimed, any error aborts as
+ * `denied` (never legacy) so an ungated legacy worker can never spawn beside a
+ * live reservation (the adversarial double-spawn hole, dec#144 MUST-FIX 1). Only
+ * a failure BEFORE identity is reserved degrades to `legacy`.
+ */
+export function prepareTurnOwnedReviewDispatch(input) {
+    const { loopId, slotId, claimId, cwd } = input;
+    // ── Snapshot the loop BEFORE turn() bumps its version (dec#139 item 3). ──
+    let iteration;
+    let version;
+    try {
+        const thread = getLoop(loopId, cwd);
+        if (!thread)
+            return { kind: 'legacy' }; // loop not found — pre-identity, safe to degrade
+        iteration = thread.iteration_count;
+        version = thread.version;
+    }
+    catch {
+        return { kind: 'legacy' };
+    }
+    const turnId = deriveTurnId(loopId, slotId, iteration);
+    const { assignment_id: assignmentId, run_id: runId } = deriveChildIds(turnId);
+    // Decoupled leases (dec#149 R1): the reservation dispatch lease is longer than each grant's
+    // lease, giving a revoked (reserved_never_launched) round a window to re-arm. reserve() adopts
+    // on a re-dispatch, so the ORIGINAL (longer) dispatch lease governs re-arm eligibility.
+    const dispatchLease = new Date(Date.now() + TURN_OWNED_DISPATCH_LEASE_MS).toISOString();
+    const grantLease = new Date(Date.now() + TURN_OWNED_LEASE_MS).toISOString();
+    // ── Phase 1: claim identity. Fail-OPEN allowed ONLY here (nothing reserved yet). ──
+    try {
+        reserve({
+            turn_id: turnId,
+            loop_id: loopId,
+            slot_id: slotId,
+            target_slot_generation: iteration, // LoopSlot has no generation field — observational proxy (dec#144 #8)
+            loop_version_at_reserve: version,
+            agent: input.agent,
+            agent_id: input.agentId,
+            claim_id: claimId,
+            phase: input.phase,
+            iteration,
+            store_root: cwd,
+            cwd,
+            lease_deadline: dispatchLease,
+        }, cwd);
+    }
+    catch (err) {
+        if (err instanceof ReservationStateError && err.code === 'reservation_exists') {
+            // A concurrent dispatch already OWNS this turn_id — adopt it and fall
+            // through to the fail-closed consume path (we may still legitimately win
+            // the fence if the owner reserved-but-never-crossed; otherwise denied).
+        }
+        else {
+            // FAIL-CLOSED (review Finding 1): any other reserve outcome is
+            // INDETERMINATE — a lock timeout (a live holder mid-critical-section),
+            // lock-lost, or unknown error does NOT prove that no identity was claimed.
+            // Degrading to `legacy` here would spawn an ungated worker beside a
+            // reservation that may well exist — the exact concurrent-dispatch
+            // double-spawn MUST-FIX 1 closes. (A definitively pre-identity error is
+            // unreachable here: the lease we build is always parseable, and
+            // loop-not-found is handled before reserve.)
+            return { kind: 'denied', reason: `reserve indeterminate — fail-closed (no legacy fallback): ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    // ── Phase 2: FAIL-CLOSED. Identity is reserved; never legacy-spawn from here. ──
+    try {
+        commitReservation(turnId, cwd);
+        // Arm-or-adopt the launch grant. Arm when none exists OR when a prior generation was
+        // REVOKED (reserved_never_launched — a crash between arm and consume, then the expiry
+        // sweep): re-arm a FRESH generation at a strictly-higher epoch so a revoked round becomes
+        // re-dispatchable (pln#630 dec#149 R1 strand recovery). armLaunch permits re-arming a
+        // revoked grant and still enforces the dispatch lease, so a lease-expired reservation
+        // refuses arm and stays correctly stranded (never a phantom-spawn-after-lease). A
+        // concurrent arm surfaces as `already_armed` → adopt the incumbent grant.
+        let grant = launchGrant(turnId, cwd);
+        if (!grant || grant.status === 'revoked') {
+            const priorEpoch = grant?.epoch ?? -1; // fresh → epoch 0 (unchanged); revoked → epoch+1
+            try {
+                armLaunch(turnId, { epoch: priorEpoch + 1, lease_deadline: grantLease }, cwd);
+            }
+            catch (err) {
+                if (!(err instanceof LaunchFenceError && err.code === 'already_armed')) {
+                    // dispatch_lease_expired / lease_invalid / not_committed / epoch_mismatch → do-not-spawn.
+                    return { kind: 'denied', reason: `arm_refused: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            grant = launchGrant(turnId, cwd);
+        }
+        // A crossed grant = launch_attempted_unknown (worker already invoked, never re-spawn);
+        // still-revoked = re-arm refused (lease expired) → never-launch; absent → all do-not-spawn.
+        if (!grant || grant.status !== 'armed') {
+            return { kind: 'denied', reason: `launch_denied: grant is ${grant?.status ?? 'absent'} (not armed)` };
+        }
+        // Consume the grant — the atomic exactly-once SPAWN authority.
+        let wonTransition;
+        try {
+            ({ wonTransition } = consumeLaunchGrant(turnId, grant.token, grant.epoch, cwd));
+        }
+        catch (err) {
+            return { kind: 'denied', reason: `launch_denied: consume refused (${err instanceof Error ? err.message : String(err)})` };
+        }
+        if (!wonTransition) {
+            // Adopted — another invocation crossed the fence. MUST NOT spawn.
+            return { kind: 'denied', reason: 'launch_denied: grant already crossed by a concurrent dispatch' };
+        }
+        // ── WON: this dispatch is the SOLE spawner. Bind slot + run to MY live claim
+        // (claimId), NOT the reservation's first-reserver claim (dec#144 #3) — else a
+        // recovery-winner would bind the slot to a dead claim and break complete_turn
+        // auth. Mints are idempotent (save overwrites, so guard on load). ──
+        if (!loadAssignment(assignmentId, cwd)) {
+            createAssignment({
+                id: assignmentId,
+                short_label: assignmentId,
+                claim_id: claimId,
+                agent: input.agent,
+                dispatcher_agent: input.dispatcherAgent,
+                dispatcher_session_id: input.sessionId,
+                scope: input.scope,
+                description: input.description,
+                tags: ['coordinate', 'review', 'loop', 'turn-owned', input.isReviewer ? 're-review' : 'author-fix'],
+            }, cwd);
+        }
+        if (!loadAgentRun(runId, cwd)) {
+            createAgentRun({
+                id: runId,
+                short_label: runId,
+                assignment_id: assignmentId,
+                claim_id: claimId,
+                agent: input.agent,
+                agent_id: input.agentId,
+                transport: 'cli_spawn',
+                status: 'created',
+                scope: input.scope,
+                description: input.description,
+                worktree_path: input.worktreePath,
+                tags: ['turn-owned', 'review', 'loop'],
+            }, cwd);
+        }
+        turn({
+            id: loopId,
+            slot_id: slotId,
+            actor: input.dispatcherAgentId ?? input.dispatcherAgent,
+            input: input.task,
+            turn_id: turnId,
+            assignment_id: assignmentId,
+            claim_id: claimId,
+        }, cwd);
+        return { kind: 'won', assignmentId, runId, turnId, nonce: grant.token };
+    }
+    catch (err) {
+        // FAIL-CLOSED: identity reserved; degrade to denied, NEVER legacy.
+        return { kind: 'denied', reason: `turn-owned prep aborted after reserve: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 /**
  * The structured signal a reviewer must emit in LANE-RESULT.json so harvest can
  * map its lane back onto the loop. Shared by the initial dispatch and every
@@ -75,37 +268,94 @@ export async function dispatchReviewLoopTurn(input) {
         result.claim_id = claimResult.claimId;
         result.worktree_path = claimResult.worktreePath;
         let assignmentId;
-        try {
-            const preId = generateAssignmentId(cwd);
-            const assignment = createAssignment({
-                id: preId.id,
-                short_label: preId.short_label,
-                claim_id: claimResult.claimId,
+        let turnEcho;
+        let runLegacyProjection = true;
+        // pln#630 — turn-owned (exactly-once) dispatch, now the DEFAULT + FAIL-CLOSED after
+        // reserve. Kill-switch off (BRAINCLAW_TURN_OWNED_REVIEW=0) → runLegacyProjection stays
+        // true and this branch is a byte-identical no-op (the legacy projection below runs).
+        if (turnOwnedReviewEnabled()) {
+            const prep = prepareTurnOwnedReviewDispatch({
+                loopId,
+                slotId: slot.slot_id,
                 agent,
-                dispatcher_agent: input.dispatcherAgent,
-                dispatcher_session_id: input.sessionId,
-                scope,
+                agentId: slot.agent_id,
+                phase,
+                task: input.task,
                 description,
-                tags: ['coordinate', 'review', 'loop', isReviewer ? 're-review' : 'author-fix'],
-            }, cwd);
-            assignmentId = assignment.id;
-            result.assignment_id = assignment.id;
+                scope,
+                claimId: claimResult.claimId,
+                worktreePath: claimResult.worktreePath,
+                dispatcherAgent: input.dispatcherAgent,
+                dispatcherAgentId: input.dispatcherAgentId,
+                sessionId: input.sessionId,
+                isReviewer,
+                cwd,
+            });
+            if (prep.kind === 'denied') {
+                // The exactly-once fence says this dispatch is NOT the spawner (adopted /
+                // crossed / revoked / lease-expired). MUST NOT spawn AND MUST NOT fall back
+                // to legacy — a legacy spawn beside the live reservation is the double-spawn
+                // hole the fence exists to close (dec#144 MUST-FIX 1).
+                //
+                // Do NOT release the coordinator claim here (review Finding 2, round 2):
+                // createCoordinatorClaim dedups on scope+agent, so a same-turn concurrent
+                // dispatch SHARES one claim C1 — and claim-creation order is uncoupled from
+                // fence-crossing order (different locks), so the loser can be C1's creator
+                // while the WINNER merely reused it and bound its slot/run/assignment to C1.
+                // releaseClaim() runs unauthenticated with no active-binding guard, so ANY
+                // release in the denied path can flip a claim a live winner depends on to
+                // `released` (re-opening the slot.claim_id divergence MUST-FIX 3 closed). A
+                // genuine orphan — the rare double-failure where no dispatch wins — is
+                // low-harm and reaped by the claim staleness sweep (auto_release_after_hours);
+                // sabotaging a live winner is high-harm and not self-healing. So we leave it.
+                result.execution_status = 'inbox_only';
+                result.error = prep.reason;
+                return result;
+            }
+            if (prep.kind === 'won') {
+                // Deterministic assignment mint + slot binding already happened inside
+                // prepare; skip the legacy projection and carry the turn-keyed echo so the
+                // ack-wrapper writes a turn-keyed completion sentinel.
+                assignmentId = prep.assignmentId;
+                result.assignment_id = prep.assignmentId;
+                turnEcho = { turn_id: prep.turnId, run_id: prep.runId, nonce: prep.nonce };
+                runLegacyProjection = false;
+            }
+            // prep.kind === 'legacy' (fail-open BEFORE identity) → fall through unchanged.
         }
-        catch (asgErr) {
-            result.error = `assignment creation failed: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`;
+        if (runLegacyProjection) {
+            try {
+                const preId = generateAssignmentId(cwd);
+                const assignment = createAssignment({
+                    id: preId.id,
+                    short_label: preId.short_label,
+                    claim_id: claimResult.claimId,
+                    agent,
+                    dispatcher_agent: input.dispatcherAgent,
+                    dispatcher_session_id: input.sessionId,
+                    scope,
+                    description,
+                    tags: ['coordinate', 'review', 'loop', isReviewer ? 're-review' : 'author-fix'],
+                }, cwd);
+                assignmentId = assignment.id;
+                result.assignment_id = assignment.id;
+            }
+            catch (asgErr) {
+                result.error = `assignment creation failed: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`;
+            }
+            // Bind the slot to the new claim/assignment (PR1 BLOCKING 2 invariant): a
+            // later harvest must resolve THIS slot by assignment_id, not by agent name
+            // (which is ambiguous under symmetric multi-reviewer loops). Runs even if
+            // assignment creation failed (undefined id → legacy agent-match fallback).
+            turn({
+                id: loopId,
+                slot_id: slot.slot_id,
+                actor: input.dispatcherAgentId ?? input.dispatcherAgent,
+                input: input.task,
+                assignment_id: assignmentId,
+                claim_id: claimResult.claimId,
+            }, cwd);
         }
-        // Bind the slot to the new claim/assignment (PR1 BLOCKING 2 invariant): a
-        // later harvest must resolve THIS slot by assignment_id, not by agent name
-        // (which is ambiguous under symmetric multi-reviewer loops). Runs even if
-        // assignment creation failed (undefined id → legacy agent-match fallback).
-        turn({
-            id: loopId,
-            slot_id: slot.slot_id,
-            actor: input.dispatcherAgentId ?? input.dispatcherAgent,
-            input: input.task,
-            assignment_id: assignmentId,
-            claim_id: claimResult.claimId,
-        }, cwd);
         // Reviewer turns must carry the verdict contract; author-fix turns must not
         // (an author lane has no verdict — it's mapped by scope+slot instead).
         const briefTask = isReviewer ? input.task + REVIEW_VERDICT_BRIEF_SUFFIX : input.task;
@@ -167,12 +417,24 @@ export async function dispatchReviewLoopTurn(input) {
             dispatcherAgentId: input.dispatcherAgentId,
             cwd,
             requireWorktree: true, // never spawn a worker in the integration repo (pln#531)
+            turnEcho, // pln#630 PR2c-b — undefined on the legacy path (wrapper unchanged)
         });
         result.execution_status = execResult.execution_status;
         result.command = execResult.command;
         result.shell = execResult.shell;
         if (execResult.error && !result.error)
             result.error = execResult.error;
+        // pln#630 PR2c-b — a turn-owned run was preallocated `created`; once the
+        // worker actually spawned, move it to `running` so it leaves the PR2c-lease
+        // pre-run lease scope (created/launching) and is governed by the heartbeat
+        // reconciler instead. If it did NOT start, leave it `created` → the pre-run
+        // reconciler converges it (crossed → launch_attempted_unknown) at lease.
+        if (turnEcho && execResult.execution_status === 'delivered_and_started') {
+            try {
+                transitionAgentRun(turnEcho.run_id, 'running', { actor: input.dispatcherAgent, status_reason: 'turn-owned worker spawned' }, cwd);
+            }
+            catch { /* best-effort — the reconciler converges if this races */ }
+        }
         return result;
     }
     catch (err) {

package/dist/core/runtime-signals.js

@@ -114,6 +114,74 @@ export function readHeartbeat(root, assignmentId, worktreePath) {
         return projectInfo;
     return (worktreeInfo.mtimeMs ?? 0) > (projectInfo.mtimeMs ?? 0) ? worktreeInfo : projectInfo;
 }
+/**
+ * Write a turn-keyed completion/failed sentinel body. Used when brainclaw itself
+ * (wrapper/reconcile) writes the sentinel; the shell `&& completed` fallback
+ * still produces a legacy presence-only marker, which stays a valid life-sign
+ * via signalExists but is NOT accepted as turn-owned evidence (PR2b-c).
+ */
+export function writeCompletionSignal(root, assignmentId, body) {
+    const p = getRuntimeSignalPath(root, assignmentId, body.status);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(body), 'utf-8');
+}
+/** Parse ONE turn-keyed sentinel body, or undefined if absent / legacy
+ *  presence-only / non-JSON / missing correlation keys. Never throws. */
+function readOneCompletionSignal(root, assignmentId, status) {
+    let raw;
+    try {
+        raw = fs.readFileSync(getRuntimeSignalPath(root, assignmentId, status), 'utf-8').trim();
+    }
+    catch {
+        return undefined; // sentinel absent
+    }
+    if (!raw)
+        return undefined; // legacy presence-only (empty) marker
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.turn_id === 'string' &&
+            typeof parsed.run_id === 'string' &&
+            typeof parsed.nonce === 'string' &&
+            (parsed.status === 'completed' || parsed.status === 'failed')) {
+            return {
+                turn_id: parsed.turn_id,
+                run_id: parsed.run_id,
+                nonce: parsed.nonce,
+                status: parsed.status,
+                at: typeof parsed.at === 'string' ? parsed.at : '',
+            };
+        }
+    }
+    catch { /* non-JSON legacy body */ }
+    return undefined;
+}
+/**
+ * Read BOTH turn-keyed completion sentinels for an attempt. This is the
+ * authoritative reader for the read-strict acceptance path: it surfaces a
+ * `completed`+`failed` contradiction so the caller can raise a conflict event
+ * and WITHHOLD an irreversible auto-stop (spec §13 R4), rather than silently
+ * collapsing to one. Legacy presence-only markers read as absent here.
+ */
+export function readCompletionSignals(root, assignmentId) {
+    const out = {};
+    const completed = readOneCompletionSignal(root, assignmentId, 'completed');
+    const failed = readOneCompletionSignal(root, assignmentId, 'failed');
+    if (completed)
+        out.completed = completed;
+    if (failed)
+        out.failed = failed;
+    return out;
+}
+/**
+ * Convenience single-body reader (`completed` preferred over `failed`). Returns
+ * undefined for absent / legacy presence-only / non-JSON / missing-keys.
+ * CALLERS THAT ACT IRREVERSIBLY must use {@link readCompletionSignals} instead
+ * so a completed+failed contradiction is not hidden (spec §13 R4).
+ */
+export function readCompletionSignal(root, assignmentId) {
+    const both = readCompletionSignals(root, assignmentId);
+    return both.completed ?? both.failed;
+}
 /**
  * can_c39f0961 — CP850 high-byte table (0x80–0xFF). Windows-native console
  * tools write redirected stdout/stderr in the OEM codepage (cp850 on western

package/dist/core/schema.js

@@ -479,6 +479,13 @@ export const InboxMessageSchema = z.object({
     read_at: z.string().optional(),
     /** When the message was acknowledged */
     ack_at: z.string().optional(),
+    /** True when the body was truncated at WRITE time because it exceeded the
+     *  inline size cap (pln#627 Phase B). Unlike read-time previews, the omitted
+     *  tail is NOT stored inline — the full artifact belongs in a dedicated store
+     *  (e.g. ideation responses), with the message carrying only a pointer. */
+    truncated_at_write: z.boolean().optional(),
+    /** Original body length in characters before write-time truncation. */
+    original_text_length: z.number().int().nonnegative().optional(),
     created_at: z.string(),
     updated_at: z.string(),
     author: z.string(),
@@ -956,6 +963,9 @@ export const RuntimeEventTypeSchema = z.enum([
     'candidate_harvested',
     'lane_result_harvested',
     'lane_integrated',
+    // pln#521 P4 — a turn-owned loop artifact was harvested + integrated into the loop
+    // by reconcileTurn (observability for the harvest path).
+    'loop_artifact_harvested',
 ]);
 /**
  * pln#526 — LANE-RESULT convention. A dispatched worker writes a single
@@ -966,6 +976,16 @@ export const RuntimeEventTypeSchema = z.enum([
  */
 export const LaneResultSchema = z.object({
     assignment_id: z.string(),
+    /**
+     * pln#630 PR2b-a (§13 R2/R3) — turn-attempt correlation keys. Optional for
+     * backward compat (legacy lanes are assignment-keyed only); a loop-dispatched
+     * lane echoes all three so the read-strict acceptance path can prove WHICH
+     * attempt+generation produced this result. `nonce` == the consumed launch
+     * token (the epoch-unique generation id), NOT a turn_id-bound value.
+     */
+    turn_id: z.string().optional(),
+    run_id: z.string().optional(),
+    nonce: z.string().optional(),
     status: z.enum(['completed', 'blocked', 'failed']),
     summary: z.string(),
     /** Paths or refs the worker produced (commits, files, docs). */
@@ -999,6 +1019,10 @@ export const RuntimeEventSchema = z.object({
     tags: TagsWithDefaultSchema,
     assignment_id: z.string().optional(),
     run_id: z.string().optional(),
+    // pln#630 PR2b-a (§13 R2/R3) — turn-attempt correlation on runtime signals.
+    // `run_id` already present above; `nonce` == launch-generation token.
+    turn_id: z.string().optional(),
+    nonce: z.string().optional(),
     claim_id: z.string().optional(),
     message_id: z.string().optional(),
     plan_id: z.string().optional(),

package/dist/core/worktree.js

@@ -1360,6 +1360,30 @@ export function isBranchMergedByContent(mainWorktreePath, branchName, baseRef =
     }
     return true;
 }
+/**
+ * True when a LOCAL git branch of this exact name exists (pln#529). Lets the
+ * gated-sequence base selector distinguish "predecessor branch gone (merged +
+ * cleaned → code is on HEAD)" from "branch present but not yet integrated →
+ * fork the dependent lane from it". Returns false on any git failure.
+ */
+export function localBranchExists(mainWorktreePath, branchName) {
+    return probeLocalBranch(mainWorktreePath, branchName) === 'present';
+}
+export function probeLocalBranch(mainWorktreePath, branchName) {
+    const r = runGit(['rev-parse', '--verify', '--quiet', `refs/heads/${branchName}`], mainWorktreePath);
+    if (r.ok)
+        return 'present';
+    return r.stderr.trim() === '' ? 'absent' : 'unknown';
+}
+/**
+ * True when `cwd` is inside a git work tree. pln#529 uses this to distinguish a
+ * NON-git project (where branch/worktree propagation is inapplicable — fall back
+ * to the legacy HEAD base) from a git repo whose branch probe transiently failed
+ * (which must fail SAFE, not silently assume HEAD).
+ */
+export function isGitRepo(cwd) {
+    return runGit(['rev-parse', '--is-inside-work-tree'], cwd).ok;
+}
 /**
  * Removes worktrees whose branch has been fully merged into the current branch
  * (typically master/main after a merge). Also removes brainclaw-managed

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.17.0 on 2026-07-19T20:01:41.172Z
+// Source: brainclaw v1.18.0 on 2026-07-31T14:51:44.969Z
 export const FACTS = {
-  "version": "1.17.0",
-  "generated_at": "2026-07-19T20:01:41.172Z",
+  "version": "1.18.0",
+  "generated_at": "2026-07-31T14:51:44.969Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-19T20:01:39.038Z",
+    "generated_at": "2026-07-31T14:51:42.799Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 76,
+        "duration_ms_median": 81,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -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": 135,
+        "duration_ms_median": 142,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,9 +499,9 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 7,
-        "payload_chars_median": 442,
-        "payload_tokens_est_median": 111
+        "duration_ms_median": 12,
+        "payload_chars_median": 499,
+        "payload_tokens_est_median": 125
       }
     ]
   }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.17.0",
-  "generated_at": "2026-07-19T20:01:41.172Z",
+  "version": "1.18.0",
+  "generated_at": "2026-07-31T14:51:44.969Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-19T20:01:39.038Z",
+    "generated_at": "2026-07-31T14:51:42.799Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 76,
+        "duration_ms_median": 81,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -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": 135,
+        "duration_ms_median": 142,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,9 +497,9 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 7,
-        "payload_chars_median": 442,
-        "payload_tokens_est_median": 111
+        "duration_ms_median": 12,
+        "payload_chars_median": 499,
+        "payload_tokens_est_median": 125
       }
     ]
   }

package/docs/cli.md

@@ -2011,7 +2011,7 @@ The default catalog is intentionally small and centred on the canonical grammar.
 |---|---|
 | `bclaw_coordinate(intent)` | Assign, consult, review, reroute, or summarize across agents. Pass `open_loop: true` on `intent="review"` to also dispatch the reviewer turn. |
 | `bclaw_dispatch(intent)` | Parallelize execute across a sequence's lanes (analysis / execute / review). |
-| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
+| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`; implementation loops add `bind` to dispatch the linked sequence and `verify` to run the opener-configured `command_green` check). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
 
 **Sequences**: