brainclaw 1.17.0 → 1.18.0

package/dist/core/loops/reconcile-turn.js

@@ -0,0 +1,369 @@
+import path from 'node:path';
+import { getReservation, evidenceMatchesAttempt, currentNonce, deriveTurnId, launchGrant } from './attempt-reservation.js';
+import { getLoop } from './store.js';
+import { complete_turn, add_artifact, advance } from './verbs.js';
+import { reducerForKind } from './result-reducers.js';
+import { loadAgentRun, transitionAgentRun } from '../agentruns.js';
+import { loadAssignment, transitionAssignment } from '../assignments.js';
+import { loadClaim, releaseClaim } from '../claims.js';
+import { createRuntimeEvent } from '../events.js';
+import { readCompletionSignals } from '../runtime-signals.js';
+import { buildFixCycleTask } from '../review-loop-close.js';
+import { withLoopLock, LockTimeoutError, LockLostError } from './lock.js';
+// The terminal loop statuses (LOOP_STATUSES = open|paused|completed|blocked|cancelled).
+// 'blocked' is LOAD-BEARING (pln#630 PR3b): the iteration cap closes a fix cycle to
+// `blocked`, and a blocked loop must be treated as terminal both by the idempotent
+// early-return below and by the fix-cycle already-bumped branch. (The legacy 'closed'/
+// 'abandoned' entries are not real loop statuses — kept as harmless historical aliases.)
+const LOOP_TERMINAL = new Set(['closed', 'cancelled', 'completed', 'abandoned', 'blocked']);
+/** Move a turn-owned run to `completed` via `running` if it never got there. Best-effort. */
+function settleRunCompleted(runId, actor, cwd) {
+    try {
+        const run = loadAgentRun(runId, cwd);
+        if (!run || run.status === 'completed')
+            return;
+        // created/launching/waiting_input/blocked can't go straight to completed —
+        // route through running first (matrix allows created→running, running→completed).
+        if (run.status !== 'running') {
+            try {
+                transitionAgentRun(runId, 'running', { actor, status_reason: 'reconcileTurn: settling for completion' }, cwd);
+            }
+            catch { /* already past running, or terminal — fall through */ }
+        }
+        const after = loadAgentRun(runId, cwd);
+        if (after && after.status === 'running') {
+            transitionAgentRun(runId, 'completed', { actor, status_reason: 'reconcileTurn: turn-keyed completion accepted' }, cwd);
+        }
+    }
+    catch { /* best-effort — loop convergence does not depend on run status */ }
+}
+/** Complete this turn's assignment (idempotent, best-effort). The re-dispatch of a fix
+ *  cycle mints a FRESH assignment, so completing the old one is always correct. */
+function settleAssignment(assignmentId, actor, cwd) {
+    try {
+        const asg = loadAssignment(assignmentId, cwd);
+        if (asg && asg.status !== 'completed' && asg.status !== 'cancelled') {
+            try {
+                transitionAssignment(assignmentId, 'completed', { actor }, cwd);
+            }
+            catch { /* transition may be illegal from current state — best-effort */ }
+        }
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Release the coordinator claim (idempotent, best-effort). pln#630 PR3b: DEFERRED until
+ * after the advance decision and skipped when the fix cycle retains the claim/worktree. The
+ * caller passes the AUTHORITATIVE claim the slot/assignment is bound to (dec#149 #3) — NOT
+ * reservation.claim_id, which is the dead first-reserver claim in the recovery-winner path.
+ */
+function releaseCoordinatorClaim(claimId, cwd) {
+    if (!claimId)
+        return;
+    try {
+        const claim = loadClaim(claimId, cwd);
+        if (claim && claim.status === 'active')
+            releaseClaim(claimId, cwd);
+    }
+    catch { /* best-effort */ }
+}
+export function reconcileTurn(input) {
+    const { turn_id, lane, cwd } = input;
+    const actor = input.actor ?? 'reconciler';
+    const reservation = getReservation(turn_id, cwd);
+    if (!reservation)
+        return { reconciled: false, reason: `unknown turn_id ${turn_id}` };
+    // ── Containment gate (§8 Q6): the reservation must belong to the store we are
+    // operating on. Before any mutation / on-behalf convergence, refuse to reconcile
+    // a reservation whose store_root resolves to a DIFFERENT project than `cwd` — a
+    // cross-project reconcile must never converge another store's loop/claim.
+    // Case-folded on win32 (review Finding 2) so a `C:\`-vs-`c:\` casing difference
+    // between the reserve-time cwd and the reconcile cwd never false-rejects on the
+    // Windows-primary target. ──
+    const operatingRoot = path.resolve(cwd ?? process.cwd());
+    const reservationRoot = path.resolve(reservation.store_root);
+    const sameStore = process.platform === 'win32'
+        ? reservationRoot.toLowerCase() === operatingRoot.toLowerCase()
+        : reservationRoot === operatingRoot;
+    if (!sameStore) {
+        return { reconciled: false, reason: `containment: reservation store_root ${reservation.store_root} != operating store ${operatingRoot}` };
+    }
+    // ── §2 read-strict evidence gate: the LANE must be turn-keyed to THIS attempt's
+    // current launch generation. A stale/mismatched result never converges the loop. ──
+    if (!evidenceMatchesAttempt(reservation, { turn_id: lane.turn_id, run_id: lane.run_id, nonce: lane.nonce })) {
+        const nonce = currentNonce(reservation);
+        return {
+            reconciled: false,
+            reason: nonce === undefined
+                ? 'no live launch generation (revoked/never-armed) — cannot accept evidence'
+                : `lane evidence (turn=${lane.turn_id} run=${lane.run_id} nonce=${lane.nonce}) does not match attempt ${turn_id}`,
+        };
+    }
+    // ── §13 R4 contradiction: a turn-keyed FAILED sentinel present alongside a
+    // completed result (the lane or a completed sentinel) → WITHHOLD convergence,
+    // journal a conflict (never silently accept). Compared against the LANE's
+    // completed status too (review Finding 5): a worker that wrote a completed
+    // LANE-RESULT then exited non-zero (turn-keyed failed sentinel) is a conflict,
+    // not a clean close. ──
+    try {
+        const bodies = readCompletionSignals(cwd ?? process.cwd(), reservation.child_ids.assignment_id);
+        const matchedCompleted = bodies.completed?.status === 'completed' && evidenceMatchesAttempt(reservation, bodies.completed);
+        const matchedFailed = bodies.failed?.status === 'failed' && evidenceMatchesAttempt(reservation, bodies.failed);
+        if (matchedFailed && (matchedCompleted || lane.status === 'completed')) {
+            try {
+                createRuntimeEvent({
+                    agent: actor,
+                    event_type: 'run_blocked',
+                    text: `reconcileTurn: turn ${turn_id} has a completed(lane/sentinel)+failed(sentinel) contradiction — auto-stop WITHHELD (§13 R4), escalating to human`,
+                    tags: ['loops', 'reconcile', 'conflict', 'turn-attempt'],
+                    assignment_id: reservation.child_ids.assignment_id,
+                    run_id: reservation.child_ids.run_id,
+                    status_reason: 'turn_evidence_contradiction',
+                }, cwd);
+            }
+            catch { /* conflict-journal best-effort */ }
+            return { reconciled: false, conflict: true, reason: 'completed+failed contradiction — convergence withheld (§13 R4)' };
+        }
+    }
+    catch { /* signal read best-effort — absence of sentinels is not a contradiction */ }
+    // pln#630 PR3b (adversarial review Finding 1) — the guard-read + advance + release compound
+    // MUST be atomic + serialized. Without a lock two concurrent reconciles of the same turn each
+    // pass the iteration-equality bump guard on a STALE snapshot and each advance from a fresh
+    // read → i→i+1 and i+1→i+2 → two turn_ids → the launch fence spawns BOTH rounds. Run the
+    // mutation under the loop lock (re-reading the loop INSIDE), mirroring the legacy closer's
+    // BLOCKING-3 fix. Lock contention → reconciled:false (a later trigger retries); a REAL error
+    // still propagates (Finding 6), never silently swallowed.
+    try {
+        return withLoopLock({
+            cwd,
+            intent: 'reconcile-turn',
+            agentId: actor,
+            scope: { kind: 'loop', loopId: reservation.loop_id },
+            work: () => convergeLockedTurn(reservation, input, actor, cwd),
+        });
+    }
+    catch (err) {
+        if (err instanceof LockTimeoutError || err instanceof LockLostError) {
+            return { reconciled: false, reason: `reconcile deferred (${err.name}); a later trigger retries` };
+        }
+        throw err;
+    }
+}
+/**
+ * The locked convergence body of reconcileTurn (pln#630 PR3b). Runs INSIDE withLoopLock so the
+ * iteration-equality bump guard and the advance observe ONE serialized snapshot — the loop is
+ * re-read here as the fresh in-lock read. Logic is otherwise identical to the pre-lock inline
+ * version (plus the terminal-early-return claim release, review Finding 2).
+ */
+function convergeLockedTurn(reservation, input, actor, cwd) {
+    const { turn_id, lane } = input;
+    const loop = getLoop(reservation.loop_id, cwd);
+    if (!loop)
+        return { reconciled: false, reason: `loop ${reservation.loop_id} not found` };
+    const slot = loop.slots.find((s) => s.slot_id === reservation.slot_id);
+    if (!slot)
+        return { reconciled: false, reason: `slot ${reservation.slot_id} not in loop ${reservation.loop_id}` };
+    // ── Superseded-turn guard (PR4 / review round-2 follow-up). A NEWER turn has
+    // taken over this slot when `slot.current_turn_id` is set and points elsewhere
+    // (each dispatch's turn() rebinds the slot pointer). A late/duplicate reconcile
+    // of the OLD turn must then NOT re-terminalize the slot or advance on a stale
+    // outcome — the slot has moved on. No-op. (When current_turn_id is unset — a
+    // direct reconcile with no preceding turn() — this does not fire, so the
+    // primitive stays testable in isolation.) This is safe against
+    // crossed_not_revocable: we never try to revoke the old crossed grant; we just
+    // decline to converge a superseded turn. ──
+    if (slot.current_turn_id !== undefined && slot.current_turn_id !== turn_id) {
+        return { reconciled: false, reason: `turn ${turn_id} superseded by current turn ${slot.current_turn_id} on slot ${slot.slot_id}` };
+    }
+    // A terminal loop already converged → idempotent no-op (any trigger may fire us). Still
+    // release the claim (review Finding 2): a cap-blocked loop that crashed AFTER the block
+    // transition but BEFORE its own deferred release would otherwise leak the retained claim
+    // until the staleness sweep — releaseCoordinatorClaim is idempotent (no-op if not active).
+    if (LOOP_TERMINAL.has(loop.status)) {
+        releaseCoordinatorClaim(loadAssignment(reservation.child_ids.assignment_id, cwd)?.claim_id ?? reservation.claim_id, cwd);
+        return { reconciled: true, reason: `loop already ${loop.status} (idempotent no-op)`, artifacts_added: 0, loop_status: loop.status };
+    }
+    // ── Idempotency (review Findings 1+2): a TERMINAL slot durably means this turn's
+    // verdict was already recorded — complete_turn sets the slot terminal ATOMICALLY
+    // with its artifact via the crash-atomic WAL, so a terminal slot is the
+    // recorded-marker (each new turn resets its slot to `assigned` first, so a
+    // terminal slot can only be THIS turn's own convergence). Re-running the reducer
+    // /complete_turn would double-record (Finding 2). So SKIP recording when
+    // terminal — but STILL fall through to advance below (Finding 1: a crash between
+    // complete_turn and advance must still close the loop on the next trigger). ──
+    const slotTerminal = slot.status === 'done' || slot.status === 'failed' || slot.status === 'cancelled';
+    let slot_outcome;
+    let artifacts_added = 0;
+    if (slotTerminal) {
+        slot_outcome = slot.status === 'done' ? 'done' : 'failed';
+    }
+    else {
+        // ── §6 reducer: validated result → loop artifacts + slot outcome. ──
+        const reducerInput = { lane, phase: reservation.phase, critiques: input.critiques };
+        const reduced = reducerForKind(loop.kind)(reducerInput, reservation);
+        artifacts_added = reduced.artifacts.length;
+        slot_outcome = reduced.slot_outcome;
+        // Record artifacts + complete the turn (crash-atomic WAL via complete_turn).
+        // Guarded: a body-cap/schema error becomes a graceful reconciled:false rather
+        // than an unhandled throw out of reconcileTurn (review Finding 3 defense).
+        try {
+            const [primary, ...extras] = reduced.artifacts;
+            for (const a of extras) {
+                try {
+                    add_artifact({ id: loop.id, actor, artifact: { phase: a.phase, type: a.type, body: a.body, produced_by: a.produced_by } }, cwd);
+                }
+                catch { /* an extra artifact failing must not abort convergence */ }
+            }
+            complete_turn({
+                id: loop.id,
+                slot_id: slot.slot_id,
+                actor,
+                outcome: reduced.slot_outcome,
+                failure_reason: reduced.failure_reason,
+                ...(primary ? { artifact: { phase: primary.phase, type: primary.type, body: primary.body } } : {}),
+            }, cwd);
+        }
+        catch (err) {
+            return { reconciled: false, reason: `complete_turn failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        // ── pln#521 P4 — observability: the turn's artifact was harvested + integrated
+        // into the loop. Best-effort (never aborts a successful convergence). ──
+        try {
+            createRuntimeEvent({
+                agent: actor,
+                event_type: 'loop_artifact_harvested',
+                text: `reconcileTurn: harvested turn ${turn_id} on slot ${slot.slot_id} → loop ${loop.id} (${slot_outcome}, ${artifacts_added} artifact(s), phase ${reservation.phase})`,
+                tags: ['loops', 'reconcile', 'harvest', 'turn-attempt'],
+                assignment_id: reservation.child_ids.assignment_id,
+                run_id: reservation.child_ids.run_id,
+                status_reason: `harvested_${slot_outcome}`,
+            }, cwd);
+        }
+        catch {
+            /* observability best-effort — a telemetry failure must not undo the harvest */
+        }
+    }
+    // ── Secondary convergence (best-effort + idempotent): run + assignment. The CLAIM
+    // release is DEFERRED to after the advance decision (pln#630 PR3b) so a fix-cycle round
+    // can RETAIN the claim/worktree. Run + assignment settle unconditionally on both paths
+    // (a crash that recorded the turn but not the settle still converges on replay; the
+    // fix-cycle re-dispatch mints a fresh run/assignment, so completing the old is correct). ──
+    settleRunCompleted(reservation.child_ids.run_id, actor, cwd);
+    settleAssignment(reservation.child_ids.assignment_id, actor, cwd);
+    // ── Advance / stop decision. On a `done` outcome we either drive a deterministic stop
+    // (reviewer_green / gate → close), continue a symmetric fix cycle (bump the round + retain
+    // the claim + emit next_turn), or leave the loop open (asymmetric / no successor). ──
+    let auto_closed = false;
+    let retainClaim = false;
+    let next_turn;
+    // Build the fix-cycle re-dispatch descriptor for a given round (shared by the bump arm and
+    // the strand self-heal below so the reviewer brief + slot binding never drift).
+    const mkNextTurn = (phase, iteration) => ({
+        slot_id: slot.slot_id,
+        role: slot.role ?? 'reviewer',
+        agent: slot.agent ?? '',
+        ...(slot.agent_id ? { agent_id: slot.agent_id } : {}),
+        phase,
+        iteration,
+        task: buildFixCycleTask(lane.review_summary ?? lane.summary ?? '', iteration),
+    });
+    if (slot_outcome === 'done') {
+        // symmetricRC detection is INDEPENDENT of the bump guard below (safety race 2): a
+        // re-reconcile in the pre-redispatch window must NOT fall into the approve/asymmetric
+        // arm, which would advance the phase FORWARD (to author_response) and corrupt the cycle.
+        const symmetricRC = loop.kind === 'review' &&
+            lane.review_verdict === 'request_changes' &&
+            loop.protocol?.review_mode === 'symmetric';
+        if (symmetricRC) {
+            // EXACTLY-ONCE bump (the one non-negotiable safety guard): each bump changes
+            // deriveTurnId(loop, slot, iteration), so a DOUBLE bump would mint two turn_ids and
+            // the launch fence would spawn BOTH rounds. Bump only when this turn's round is still
+            // current; a re-reconcile after the bump takes the else-branch (no re-bump, no re-emit).
+            if (loop.iteration_count === reservation.iteration) {
+                // Legacy backward-bump (advance to the SAME phase → iteration_count += 1). The
+                // post-advance stop check closes to `blocked` when the max_iterations cap is hit.
+                const adv = advance({ id: loop.id, to_phase: loop.current_phase, actor }, cwd);
+                if (adv.auto_closed || LOOP_TERMINAL.has(adv.loop.status)) {
+                    auto_closed = true; // iteration cap → blocked/terminal → release the claim below
+                }
+                else {
+                    retainClaim = true; // keep the coordinator claim + worktree for the re-dispatch
+                    next_turn = mkNextTurn(adv.loop.current_phase, adv.loop.iteration_count);
+                }
+            }
+            else {
+                // Already bumped by a prior pass. Distinguish a benign re-reconcile (the next round
+                // WAS dispatched) from a genuine STRAND (pln#630 PR4, closes dec#149 #2/F3): the pass
+                // that bumped crashed BEFORE harvest re-dispatched, so the loop sits open with the
+                // claim retained and NO worker in flight. Detect it precisely — is there a reservation
+                // for the bumped round's deterministic turn_id? If NOT → strand → RE-EMIT next_turn to
+                // self-heal (the launch fence dedups, so a benign duplicate is DENIED, never a
+                // double-spawn) and journal a recovery event. If a reservation exists → the next round
+                // is already in flight → just retain, no re-emit (no churn on benign re-reconciles).
+                const cur = getLoop(loop.id, cwd);
+                if (cur && !LOOP_TERMINAL.has(cur.status)) {
+                    retainClaim = true;
+                    // The bumped round is LIVE only if its reservation exists AND its launch grant is
+                    // armed (dispatch in flight, pre-spawn) or crossed (spawned). A REVOKED grant
+                    // (reserved_never_launched — crash between arm and consume + the expiry sweep) or an
+                    // absent reservation is a STRAND (dec#149 R1): re-emit to self-heal. The re-dispatch's
+                    // prepare re-arms a revoked grant at a higher epoch, so this round can actually relaunch.
+                    const bumpedTurnId = deriveTurnId(loop.id, slot.slot_id, cur.iteration_count);
+                    const bumpedGrant = launchGrant(bumpedTurnId, cwd);
+                    const bumpedLive = getReservation(bumpedTurnId, cwd) !== undefined &&
+                        (bumpedGrant?.status === 'armed' || bumpedGrant?.status === 'crossed');
+                    if (!bumpedLive) {
+                        next_turn = mkNextTurn(cur.current_phase, cur.iteration_count);
+                        try {
+                            createRuntimeEvent({
+                                agent: actor,
+                                event_type: 'run_blocked',
+                                text: `reconcileTurn: fix-cycle round ${cur.iteration_count} of loop ${loop.id} was bumped but never dispatched (turn ${turn_id} strand) — re-emitting next_turn to self-heal`,
+                                tags: ['loops', 'reconcile', 'turn-owned', 'strand-recovery'],
+                                assignment_id: reservation.child_ids.assignment_id,
+                                run_id: reservation.child_ids.run_id,
+                                status_reason: 'fix_cycle_strand_reemit',
+                            }, cwd);
+                        }
+                        catch { /* observability best-effort */ }
+                    }
+                }
+                else {
+                    auto_closed = true;
+                }
+            }
+        }
+        else {
+            // approve OR asymmetric request_changes — unchanged PR3a / legacy-asymmetric behavior.
+            // Benign "cannot advance/close now" → loop stays open awaiting the next turn; any
+            // OTHER throw is a REAL error and must propagate, never be silently swallowed (Finding 6).
+            try {
+                auto_closed = advance({ id: loop.id, actor }, cwd).auto_closed;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (!/phase_advance_blocked|already at last phase|no post-cycle successor/.test(msg))
+                    throw err;
+            }
+        }
+    }
+    // Release the coordinator claim now — UNLESS a fix-cycle round retained it. Target the
+    // authoritative claim the assignment is bound to, not reservation.claim_id (dec#149 #3).
+    if (!retainClaim) {
+        const authoritativeClaimId = loadAssignment(reservation.child_ids.assignment_id, cwd)?.claim_id ?? reservation.claim_id;
+        releaseCoordinatorClaim(authoritativeClaimId, cwd);
+    }
+    const loop_status = getLoop(loop.id, cwd)?.status ?? loop.status;
+    return {
+        reconciled: true,
+        reason: next_turn
+            ? `turn ${turn_id} → request_changes round ${next_turn.iteration}: claim retained, next fix turn emitted for re-dispatch`
+            : slotTerminal ? `turn ${turn_id} already recorded; advance re-attempted (${slot_outcome})` : `turn ${turn_id} reconciled (${slot_outcome})`,
+        slot_outcome,
+        artifacts_added,
+        auto_closed,
+        loop_status,
+        ...(next_turn ? { next_turn } : {}),
+    };
+}
+//# sourceMappingURL=reconcile-turn.js.map

package/dist/core/loops/result-reducers.js

@@ -0,0 +1,88 @@
+import { LOOP_ARTIFACT_BODY_MAX_BYTES } from './types.js';
+/**
+ * Cap an artifact body to LOOP_ARTIFACT_BODY_MAX_BYTES (review Finding 3).
+ * `review_summary`/`summary` are worker-controlled and unbounded, but
+ * LoopArtifactSchema hard-rejects a body over the cap — an un-truncated body
+ * would make complete_turn throw and crash reconcileTurn. Byte-aware, drops any
+ * partial trailing multibyte char.
+ */
+function capBody(s) {
+    if (Buffer.byteLength(s, 'utf8') <= LOOP_ARTIFACT_BODY_MAX_BYTES)
+        return s;
+    const marker = '…[truncated]';
+    const room = LOOP_ARTIFACT_BODY_MAX_BYTES - Buffer.byteLength(marker, 'utf8');
+    return Buffer.from(s, 'utf8').subarray(0, room).toString('utf8').replace(/�+$/, '') + marker;
+}
+/**
+ * review reducer (§6). `approve` → one `verdict` artifact whose body begins
+ * `accepted…` — EXACTLY what `isVerdictAccepted`/`reviewer_green` matches
+ * (verbs.ts) so the loop auto-closes; `request_changes` → a `changes-requested`
+ * verdict that does NOT fire reviewer_green (the symmetric fix cycle continues).
+ * A lane that did not complete, or completed with no verdict, fails the slot
+ * (no fake green).
+ */
+export const reviewReducer = (input, attempt) => {
+    const { lane, phase } = input;
+    if (lane.status !== 'completed') {
+        return { artifacts: [], slot_outcome: 'failed', failure_reason: `review lane status is ${lane.status}, not completed` };
+    }
+    if (!lane.review_verdict) {
+        return { artifacts: [], slot_outcome: 'failed', failure_reason: 'review lane completed without a review_verdict — cannot converge the loop' };
+    }
+    const summary = (lane.review_summary ?? '').trim();
+    const body = capBody(lane.review_verdict === 'approve'
+        ? `accepted${summary ? `: ${summary}` : ''}`
+        : `changes-requested${summary ? `: ${summary}` : ''}`);
+    return {
+        artifacts: [{ phase, type: 'verdict', body, produced_by: attempt.agent }],
+        slot_outcome: 'done',
+    };
+};
+/**
+ * ideation reducer (§6). A `critique_batch` → N `critique` artifacts (so
+ * `min_artifacts_by_type` can open the next phase). A bare summary with no
+ * critique body → slot `failed`, gate stays shut (correct: no fake progress from
+ * a lane that produced no critiques).
+ */
+export const ideationReducer = (input, attempt) => {
+    const { lane, phase, critiques } = input;
+    if (lane.status !== 'completed') {
+        return { artifacts: [], slot_outcome: 'failed', failure_reason: `ideation lane status is ${lane.status}, not completed` };
+    }
+    if (!critiques || critiques.length === 0) {
+        return { artifacts: [], slot_outcome: 'failed', failure_reason: 'ideation lane produced no critiques (bare summary) — gate stays shut' };
+    }
+    return {
+        artifacts: critiques.map((c) => ({
+            phase, type: 'critique', body: capBody(c.body), produced_by: attempt.agent,
+            ...(c.addresses_critique ? { addresses_critique: c.addresses_critique } : {}),
+        })),
+        slot_outcome: 'done',
+    };
+};
+/**
+ * Default reducer for loop kinds without a specialized one (implementation /
+ * research / debug / bootstrap): a completed lane → one generic `lane_result`
+ * artifact carrying the summary; a non-completed lane → slot failed. Keeps
+ * convergence sensible without fabricating structured artifacts a kind never
+ * declared.
+ */
+export const defaultReducer = (input, attempt) => {
+    const { lane, phase } = input;
+    if (lane.status !== 'completed') {
+        return { artifacts: [], slot_outcome: 'failed', failure_reason: `lane status is ${lane.status}, not completed` };
+    }
+    return {
+        artifacts: [{ phase, type: 'lane_result', body: capBody(lane.summary), produced_by: attempt.agent }],
+        slot_outcome: 'done',
+    };
+};
+const RESULT_REDUCERS = {
+    review: reviewReducer,
+    ideation: ideationReducer,
+};
+/** The reducer for a loop kind — a specialized one when registered, else the default. */
+export function reducerForKind(kind) {
+    return RESULT_REDUCERS[kind] ?? defaultReducer;
+}
+//# sourceMappingURL=result-reducers.js.map

package/dist/core/loops/store.js

@@ -9,6 +9,7 @@ import { logCascadeReleaseResult, releaseClaimsCascade } from '../claims.js';
 import { gcWorktreeIfHarvested } from '../worktree.js';
 import { writeProjectMdSafe } from './hooks/bootstrap-write.js';
 import { notifyOperatorOnInputRequested } from './hooks/notify-operator.js';
+import { reconstructConsistentThread } from './commit-intent.js';
 import { DEFAULT_PROTOCOLS, LoopArtifactSchema, LoopEventSchema, LoopThreadSchema, } from './types.js';
 function loopsDir(cwd) {
     return path.join(memoryDir(cwd ?? process.cwd()), 'loops');
@@ -86,7 +87,21 @@ export function appendEvent(loopId, event, cwd,
 threadSnapshot) {
     const parsed = LoopEventSchema.parse(event);
     ensureLoopsDir(cwd);
-    fs.appendFileSync(eventsPath(loopId, cwd), `${JSON.stringify(parsed)}\n`);
+    // pln#630 PR1b — fsync the journal append so a materialized projection can
+    // never be durable ahead of the event that explains it (trp_8b17c2d0).
+    const fd = fs.openSync(eventsPath(loopId, cwd), 'a');
+    try {
+        // Loop the write to completion so a short/partial write never leaves a torn
+        // final record for the next append to fuse with (PR #102 review round 2).
+        const buf = Buffer.from(`${JSON.stringify(parsed)}\n`, 'utf8');
+        let off = 0;
+        while (off < buf.length)
+            off += fs.writeSync(fd, buf, off, buf.length - off);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
     // pln#513 step 4 — best-effort OS notification on input_requested events.
     // Prefer the in-memory snapshot from the caller (carries the freshly-
     // added operator_question). Fall back to a disk read so any direct
@@ -125,7 +140,12 @@ export function openLoop(input, cwd) {
     // presets) wins over the kind/mode-derived default. When no override
     // is supplied, fall back to the legacy resolveProtocol() path so
     // existing callers (review, default ideation) are unaffected.
-    const protocol = input.protocol ?? resolveProtocol(input.kind, input.mode);
+    let protocol = input.protocol ?? resolveProtocol(input.kind, input.mode);
+    // pln#632 — merge an opener-provided verify command onto the resolved protocol (adds
+    // the engine-run command_green gate without discarding the kind-default iteration).
+    if (input.verify && !protocol?.verify) {
+        protocol = { ...(protocol ?? {}), verify: input.verify };
+    }
     const thread = {
         schema_version: 1,
         id,
@@ -166,10 +186,14 @@ export function openLoop(input, cwd) {
 }
 export function getLoop(id, cwd) {
     const filePath = threadPath(id, cwd);
-    if (!fs.existsSync(filePath))
-        return undefined;
-    const raw = fs.readFileSync(filePath, 'utf8');
-    return LoopThreadSchema.parse(JSON.parse(raw));
+    const onDisk = fs.existsSync(filePath)
+        ? LoopThreadSchema.parse(JSON.parse(fs.readFileSync(filePath, 'utf8')))
+        : undefined;
+    // pln#630 PR1b — if a durable-but-not-yet-applied commit intent is ahead of
+    // the on-disk thread, return the reconstructed consistent view. The mutation
+    // is durable in the intent; persistence catches up at the next lock-entry
+    // recovery (never a write on this read path — cf. trp_fdf3e590 / dec#137).
+    return reconstructConsistentThread(id, onDisk, cwd);
 }
 export function listLoops(filters = {}, cwd) {
     const dir = threadsDir(cwd);
@@ -199,7 +223,22 @@ export function listLoopEvents(id, cwd) {
     if (!fs.existsSync(filePath))
         return [];
     const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
-    return lines.map((line) => LoopEventSchema.parse(JSON.parse(line)));
+    const events = [];
+    for (let i = 0; i < lines.length; i++) {
+        try {
+            events.push(LoopEventSchema.parse(JSON.parse(lines[i])));
+        }
+        catch (err) {
+            // pln#630 PR1b — a non-empty unparseable FINAL line is an uncommitted
+            // torn-append fragment (durably repaired at the next lock-entry recovery,
+            // commit-intent.ts). Tolerate it on read so seq allocation / reads never
+            // wedge on a torn tail. An EARLIER unparseable line is real corruption.
+            if (i === lines.length - 1)
+                break;
+            throw err;
+        }
+    }
+    return events;
 }
 /**
  * pln#512 step 2 — sentinel thrown by closeLoop when the bootstrap close