brainclaw 1.16.0 → 1.18.0

package/dist/core/loops/impl-bind.js

@@ -0,0 +1,144 @@
+/**
+ * pln#632 impl-loop bind — the ENGINE action for an implementation loop's `bind` phase.
+ *
+ * The implementation protocol declares `bind` as "bind plan+sequence and dispatch" (see
+ * LOOP_PROTOCOLS.implementation in types.ts). This is that action: read the loop's linked
+ * sequence, dispatch its ready lanes via the EXISTING sequence spawner, then advance
+ * `bind → execute` so the loop enters its execute↔verify cycle.
+ *
+ * Reuses `dispatch()` ADDITIVELY via its `sequenceId` option (pln#632) so the loop drives
+ * its OWN linked sequence WITHOUT touching the project's global active-sequence pointer —
+ * no hijack of whatever sequence other bclaw_dispatch work is using. Mirrors the
+ * async-handler-spawns pattern already used by bclaw_coordinate(open_loop=true) for review
+ * loops; touches NO review/ideation dispatch. The live spawn happens only when this runs
+ * on a real loop (exactly like bclaw_dispatch) — `dryRun` previews with no spawn and no
+ * phase mutation, so the flow is unit-testable.
+ */
+import { dispatch } from '../dispatcher.js';
+import { listSequences } from '../sequence.js';
+import { getLoop } from './store.js';
+import { advance } from './verbs.js';
+import { withLoopLock } from './lock.js';
+/**
+ * Bind an implementation loop to its linked sequence and dispatch it. Async because the
+ * underlying spawn is async (the only awaited work; `dryRun` resolves synchronously).
+ *
+ * Idempotent: a loop already past `bind` returns a `noop` (never re-dispatches on a second
+ * bind after it advanced). A crash BETWEEN dispatch and advance leaves the loop in `bind`,
+ * so a retry re-dispatches only the still-unassigned lanes (dispatch skips lanes with an
+ * active assignment) and re-attempts the advance — safe crash-recovery.
+ */
+export async function runImplBind(input, cwd) {
+    const { loop_id, dispatcherAgent } = input;
+    const loop = getLoop(loop_id, cwd);
+    if (!loop)
+        throw new Error(`unknown loop_id ${loop_id}`);
+    if (loop.kind !== 'implementation') {
+        throw new Error(`bind is only valid for implementation loops (loop ${loop_id} is kind='${loop.kind}'); review/ideation loops dispatch via bclaw_coordinate`);
+    }
+    // bind SPAWNS real workers via dispatch() — never do that on a loop that is not open.
+    // A paused loop keeps current_phase='bind' (pause only flips status), and open→close
+    // leaves the phase at 'bind' too, so the phase-idempotency check below is NOT sufficient
+    // to stop a spawn on a held/terminal loop (review Finding 1). Gate on status FIRST, so
+    // no dispatch fires and we don't spawn then throw at the advance.
+    if (loop.status !== 'open') {
+        throw new Error(`bind requires an open loop; loop ${loop_id} is ${loop.status} (resume a paused loop, or reopen a terminal one, before binding)`);
+    }
+    const sequenceId = loop.linked?.sequence_ids?.[0];
+    // Idempotency: `bind` is the loop's FIRST phase. A loop already past it was bound before.
+    if (loop.current_phase !== 'bind') {
+        return {
+            loop_id,
+            sequence_id: sequenceId ?? '',
+            action: 'noop',
+            dispatch: null,
+            messages_sent: 0,
+            reason: `loop is in phase '${loop.current_phase}', not 'bind' — already bound (idempotent)`,
+        };
+    }
+    if (!sequenceId) {
+        throw new Error(`impl-bind requires a linked sequence: open the implementation loop with linked.sequence_ids=[…] (the sequence whose lanes it executes). None found on ${loop_id}.`);
+    }
+    // Validate up-front (non-throwing lookup) so a missing sequence fails with a clear
+    // message rather than a silent null dispatch.
+    const seq = listSequences(cwd).find((s) => s.id === sequenceId);
+    if (!seq)
+        throw new Error(`linked sequence ${sequenceId} not found for loop ${loop_id}`);
+    const dispatched = await dispatch({
+        sequenceId,
+        dispatcherAgent,
+        dispatcherAgentId: input.dispatcherAgentId,
+        sessionId: input.sessionId,
+        dryRun: input.dryRun,
+        lanes: input.lanes,
+        autoExecute: input.autoExecute,
+        model: input.model,
+        maxAssignments: input.maxAssignments,
+    }, cwd ?? process.cwd());
+    const result = dispatched?.result ?? null;
+    const messages_sent = result?.messages_sent.length ?? 0;
+    // Guard a race: the sequence disappeared between validation and dispatch → don't advance.
+    if (!dispatched) {
+        return {
+            loop_id,
+            sequence_id: sequenceId,
+            action: 'noop',
+            dispatch: null,
+            messages_sent: 0,
+            reason: `sequence ${sequenceId} yielded no dispatch analysis (unavailable); loop stays in 'bind'`,
+        };
+    }
+    if (input.dryRun) {
+        return {
+            loop_id,
+            sequence_id: sequenceId,
+            action: 'preview',
+            dispatch: result,
+            messages_sent,
+            reason: `dry run: ${result?.delivery_plan.length ?? 0} lane(s) would dispatch; loop stays in 'bind' (no spawn, no advance)`,
+        };
+    }
+    // Real bind: advance bind → execute so the loop enters the execute↔verify cycle. The
+    // implementation protocol's `bind` phase carries no advance_gate, so the advance is
+    // unconditional FROM bind — but the phase-check and the advance must be ATOMIC or two
+    // racing binds each advance once and push the loop bind→execute→verify with no execute
+    // work done (review Finding 2). advance() does not self-lock (its callers — the facade's
+    // withLockedLoopMutation and the ideation closer — provide the lock), so we take the loop
+    // lock here and re-check the phase under it: only the bind that still sees 'bind' advances.
+    const advanced = withLoopLock({
+        cwd,
+        intent: 'impl-bind-advance',
+        agentId: dispatcherAgent,
+        scope: { kind: 'loop', loopId: loop_id },
+        work: () => {
+            const fresh = getLoop(loop_id, cwd);
+            // Raced: a concurrent bind (or a pause/close) moved the loop out of an open 'bind'
+            // state → do NOT advance again. Idempotent by construction.
+            if (!fresh || fresh.status !== 'open' || fresh.current_phase !== 'bind')
+                return null;
+            const a = advance({ id: loop_id, actor: dispatcherAgent }, cwd);
+            return { phase: a.loop.current_phase, auto_closed: a.auto_closed };
+        },
+    });
+    if (!advanced) {
+        return {
+            loop_id,
+            sequence_id: sequenceId,
+            action: 'noop',
+            dispatch: result,
+            messages_sent,
+            reason: `dispatched ${messages_sent} assignment(s); phase already advanced out of 'bind' under a concurrent bind (idempotent — not re-advanced)`,
+        };
+    }
+    return {
+        loop_id,
+        sequence_id: sequenceId,
+        action: 'bound',
+        advanced_to: advanced.phase,
+        auto_closed: advanced.auto_closed,
+        dispatch: result,
+        messages_sent,
+        reason: `dispatched ${messages_sent} assignment(s) on sequence ${sequenceId}; advanced bind → ${advanced.phase}`,
+    };
+}
+//# sourceMappingURL=impl-bind.js.map

package/dist/core/loops/index.js

@@ -1,7 +1,7 @@
 export * from './types.js';
 export { AwaitingFileApplyApprovalError, closeLoop, ensureLoopsDir, generateLoopId, generateMutationId, generateSlotId, getLoop, listLoopEvents, listLoops, openLoop, writeThreadFile, } from './store.js';
 export { add_artifact, advance, complete_turn, evaluatePhaseAdvanceGate, evaluateStopCondition, pause, provideInput, reconcileOpenQuestions, requestInput, resume, sweepPauseTimeouts, turn, } from './verbs.js';
-export { decideNextPhase, artifactsInIteration, noNewCritiqueInIteration, hasCriticSignalInIteration, } from './iteration-engine.js';
+export { decideNextPhase, artifactsInIteration, noNewCritiqueInIteration, hasCriticSignalInIteration, hasPassingVerifyReportInIteration, } from './iteration-engine.js';
 export { computeNextExpected, } from './next-expected.js';
 export { buildIdeationBrief, } from './brief-assembly.js';
 export { BOOTSTRAP_PRESET } from './presets/bootstrap.js';

package/dist/core/loops/iteration-engine.js

@@ -92,6 +92,15 @@ export function decideNextPhase(thread, protocol) {
             reason: 'no_new_critique_artifacts',
         };
     }
+    if (iterationBlock.exit_when === 'command_green' &&
+        hasPassingVerifyReportInIteration(thread, thread.iteration_count)) {
+        return {
+            kind: 'exit_cycle',
+            target: postCycleTarget,
+            iteration: thread.iteration_count,
+            reason: 'command_green',
+        };
+    }
     // Cap check. If incrementing iteration_count would exceed the cap,
     // exit via max_iterations. (iteration_count is 0-indexed; cap=3 means
     // iterations 0, 1, 2 are allowed; refusing iteration 3 → exit.)
@@ -136,4 +145,24 @@ export function noNewCritiqueInIteration(thread, iteration) {
 export function hasCriticSignalInIteration(thread, iteration) {
     return thread.artifacts.some((a) => (a.iteration ?? 0) === iteration && a.type === 'critic_signal');
 }
+/**
+ * `exit_when='command_green'` predicate (pln#609): true when the just-finished
+ * iteration produced a PASSING `verify_report` artifact (body.passed === true).
+ * The verify command ran during the verify turn and recorded the report — this
+ * is a PURE read; no command is executed here (execution seam = verify-command.ts,
+ * Increment 2). Iteration-window scoped so a green from a prior iteration can
+ * never satisfy the current one; absence reads as false.
+ */
+export function hasPassingVerifyReportInIteration(thread, iteration) {
+    return artifactsInIteration(thread, iteration).some((a) => {
+        if (a.type !== 'verify_report')
+            return false;
+        try {
+            return JSON.parse(a.body ?? '{}').passed === true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
 //# sourceMappingURL=iteration-engine.js.map

package/dist/core/loops/lock.js

@@ -4,6 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { memoryDir } from '../io.js';
 import { nowISO } from '../ids.js';
+import { recoverPendingIntents } from './commit-intent.js';
 /**
  * Per-loop exclusive lock + idempotency + fencing helpers.
  *
@@ -298,6 +299,19 @@ export function withLoopLock(options) {
         intent: options.intent,
     });
     try {
+        // pln#630 PR1b (dec#137) — recovery-before-mutate at the loop-lock entry
+        // boundary. Any durable-but-unapplied commit intent is replayed to the
+        // journal+thread BEFORE we read the version / run the work, so a mutation
+        // never starts from a half-applied state and currentVersion() sees the
+        // caught-up thread. Not in getLoop: the loop lock is not re-entrant and
+        // verbs call getLoop while already holding it. FAILS CLOSED (PR #102 review
+        // HIGH): a genuine recovery error (torn/unreadable journal, I/O) propagates
+        // and aborts the mutation rather than proceeding against corrupt state;
+        // quarantined conflicts/corruption are handled inside recoverPendingIntents
+        // and do not throw.
+        if (options.scope.kind === 'loop') {
+            recoverPendingIntents(options.scope.loopId, options.cwd);
+        }
         // Idempotency short-circuit (inside lock).
         if (options.clientRequestId && options.requestPayload !== undefined) {
             const loopIdForKey = options.scope.kind === 'loop'

package/dist/core/loops/project-resolution.js

@@ -0,0 +1,157 @@
+/**
+ * pln#521 P1 — loop project resolution gate.
+ *
+ * A review loop that lands in the wrong store is worse than a review loop that
+ * never opened: the candidate, claim, assignment and loop all persist in a
+ * project nobody is watching, and the reviewer spawns against the wrong repo
+ * (DGX misroute, 2026-05). This module answers ONE question before any
+ * persistence happens: *which project does this loop belong to, and did anyone
+ * actually choose it?*
+ *
+ * Resolution ladder (B2 of art_18e7c6101880):
+ *   1. explicit `project` argument            → routed, source='explicit'
+ *   2. a real selector already won upstream   → routed, source=<that selector>
+ *      (env_project / session / cwd_child / global — `resolveEffectiveCwdInfo`
+ *      has already applied them by the time a handler receives its cwd)
+ *   3. bare cwd fallback in a store that can host several projects
+ *                                             → `needs_project_selection`
+ *
+ * There is deliberately NO inference from ref / scope / path: B3 was rejected
+ * (art_e29e88878209) because a wrong guess costs more than an explicit choice.
+ *
+ * @module
+ */
+import path from 'node:path';
+import { loadConfig } from '../config.js';
+import { resolveProjectCwd } from '../cross-project.js';
+import { resolvePrimaryStore } from '../store-resolution.js';
+import { scanNestedBrainclawProjects, summarizeWorkspaceProjects } from '../workspace-projects.js';
+/**
+ * Decide which project a loop belongs to, or refuse when nobody chose.
+ *
+ * Throws only when an explicit `project` cannot be resolved — that error is
+ * `resolveProjectCwd`'s (unknown project, unavailable link) and callers already
+ * surface it as a tool error rather than silently falling back.
+ */
+export function validateLoopProjectResolution(input) {
+    const sourceCwd = path.resolve(input.cwd);
+    const projectArg = input.projectArg?.trim() || undefined;
+    // 1. Explicit project wins outright and needs no ambiguity check: the caller
+    //    named it, so there is nothing left to disambiguate.
+    if (projectArg) {
+        const projectCwd = path.resolve(resolveProjectCwd(projectArg, sourceCwd));
+        return resolved(projectCwd, 'explicit', {
+            source_cwd: sourceCwd,
+            effective_cwd: projectCwd,
+            active_source: 'explicit',
+            project_arg: projectArg,
+            candidates: [],
+        });
+    }
+    // 2. A selector other than the bare cwd fallback means somebody DID choose —
+    //    `--cwd`, BRAINCLAW_PROJECT, a session switch, the physical child store,
+    //    or the workspace's active-project pointer. Honour it as-is.
+    const activeSource = input.activeSource ?? 'cwd';
+    if (activeSource !== 'cwd') {
+        return resolved(sourceCwd, activeSource, {
+            source_cwd: sourceCwd,
+            effective_cwd: sourceCwd,
+            active_source: activeSource,
+            candidates: [],
+        });
+    }
+    // 3. Bare fallback. Harmless in a single-project store (there is exactly one
+    //    answer), a misroute waiting to happen in a store that hosts children.
+    const candidates = collectCandidateProjects(sourceCwd);
+    const trace = {
+        source_cwd: sourceCwd,
+        effective_cwd: sourceCwd,
+        active_source: 'cwd',
+        candidates,
+    };
+    if (candidates.length === 0) {
+        return resolved(sourceCwd, 'cwd', trace);
+    }
+    const rendered = candidates
+        .map((c) => {
+        const label = c.name ?? (c.path ? path.basename(c.path) : '(unnamed)');
+        return `  - ${label}${c.path ? ` (${c.path})` : ''}`;
+    })
+        .join('\n');
+    return {
+        ok: false,
+        code: 'needs_project_selection',
+        message: `This store hosts ${candidates.length} project(s) and no project was selected, so the loop would land in `
+            + `${sourceCwd} by default rather than where the work is. Nothing was created.\n`
+            + `Candidates:\n${rendered}\n`
+            + `Choose one explicitly — pass project='<name>' on this call, or make it sticky with `
+            + `bclaw_switch(project='<name>'). Ref/scope/path are never used to guess (B3, art_e29e88878209).`,
+        candidates,
+        trace,
+    };
+}
+function resolved(projectCwd, source, trace) {
+    return {
+        ok: true,
+        project_cwd: projectCwd,
+        project_name: projectNameFor(projectCwd),
+        source,
+        trace,
+    };
+}
+function projectNameFor(cwd) {
+    try {
+        return loadConfig(cwd).project_name;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Sibling projects the store at `cwd` can host. Empty for an ordinary
+ * single-project repo — which is what keeps this gate a strict no-op there.
+ *
+ * Two signals, both already load-bearing elsewhere in the codebase:
+ * `project_mode === 'multi-project'` (the convention used by doctor / status /
+ * code-map) and a `workspace`-role store with nested project stores under it.
+ */
+function collectCandidateProjects(cwd) {
+    let config;
+    try {
+        config = loadConfig(cwd);
+    }
+    catch {
+        // Uninitialised store: loop creation will fail downstream on its own terms.
+        // Refusing here would only swap a clear error for a vaguer one.
+        return [];
+    }
+    const seen = new Map();
+    const add = (candidate) => {
+        // A config-declared namespace has no store of its own yet, so it is keyed
+        // by name; anything on disk is keyed by its absolute path.
+        const abs = candidate.path ? path.resolve(cwd, candidate.path) : undefined;
+        if (abs === cwd)
+            return;
+        const key = abs ?? `name:${candidate.name ?? ''}`;
+        if (seen.has(key))
+            return;
+        seen.set(key, { ...candidate, ...(abs ? { path: abs } : {}) });
+    };
+    if (config.project_mode === 'multi-project') {
+        for (const project of summarizeWorkspaceProjects(cwd, config).discovered_projects) {
+            add({
+                name: project.project_name,
+                // `config` entries carry a namespace name in `path`, not a real path.
+                ...(project.source === 'config' ? {} : { path: project.path }),
+                source: project.source,
+            });
+        }
+    }
+    if (resolvePrimaryStore(cwd)?.role === 'workspace') {
+        for (const project of scanNestedBrainclawProjects(cwd)) {
+            add({ name: project.project_name, path: project.path, source: 'store_chain' });
+        }
+    }
+    return [...seen.values()].sort((a, b) => (a.path ?? a.name ?? '').localeCompare(b.path ?? b.name ?? ''));
+}
+//# sourceMappingURL=project-resolution.js.map