brainclaw 1.17.0 → 1.18.0

package/dist/core/dispatcher.js

@@ -34,9 +34,10 @@
  * @module
  */
 import { buildClaimEnvPrefix } from './execution-profile.js';
-import { getActiveSequence } from './sequence.js';
+import { getActiveSequence, listSequences } from './sequence.js';
 import { loadState, persistState } from './state.js';
 import { listClaims, createCoordinatorClaim, attachAssignmentMessageToClaim, linkClaimToAssignment, assessClaimLiveness } from './claims.js';
+import { sanitizeBranchComponent, isBranchMergedByContent, probeLocalBranch, isGitRepo } from './worktree.js';
 import { listAgentIdentities, ensureAgentRegisteredForDispatch } from './agent-registry.js';
 import { sendMessage, hasActiveAssignment } from './messaging.js';
 import { memoryDir } from './io.js';
@@ -64,14 +65,23 @@ function buildEnvPrefix(claimId) {
 }
 // ── Lane Analysis ───────────────────────────────────────────
 /**
- * Analyze the active sequence and categorize each item as ready, active, blocked, or done.
+ * Analyze a sequence and categorize each item as ready, active, blocked, or done.
+ *
+ * `sequenceId` (pln#632 impl-loop bind) targets a SPECIFIC sequence by id instead of
+ * the project's active one — so an implementation loop can dispatch its own linked
+ * sequence without hijacking the global active-sequence pointer. Omitted → the active
+ * sequence (byte-identical to the historical behaviour; the resolver is non-throwing,
+ * so an unknown id yields `null` exactly like "no active sequence").
  */
-export function analyzeSequence(cwd) {
-    const sequence = getActiveSequence(cwd);
+export function analyzeSequence(cwd, sequenceId) {
+    const sequence = sequenceId
+        ? listSequences(cwd).find((s) => s.id === sequenceId)
+        : getActiveSequence(cwd);
     if (!sequence)
         return null;
     const state = loadState(cwd);
-    const claims = listClaims(cwd).filter(c => c.status === 'active');
+    const allClaimsSnapshot = listClaims(cwd);
+    const claims = allClaimsSnapshot.filter(c => c.status === 'active');
     const agents = listAgentIdentities(cwd);
     // Index plans by ID for fast lookup
     const planIndex = new Map();
@@ -80,12 +90,36 @@ export function analyzeSequence(cwd) {
         if (p.short_label)
             planIndex.set(p.short_label, p);
     }
-    // Collect plan IDs that are done or dropped (terminal states)
+    // pln#529 — index sequence items by planId (scope_hint fallback for branch
+    // derivation).
+    const itemByPlanId = new Map();
+    for (const it of sequence.items)
+        itemByPlanId.set(it.planId, it);
+    // pln#529 (review Finding 1) — GROUND-TRUTH predecessor branch resolution: a
+    // predecessor lane's branch was created by createCoordinatorClaim from its
+    // CLAIM scope (which is stable across the coordinate/assign paths + survives a
+    // later scope_hint edit + persists on release). Re-deriving from live sequence
+    // metadata probes the wrong branch and silently defaults to HEAD. So resolve
+    // the predecessor's scope from its persisted claim (any claim for the plan;
+    // retries reuse the scope), falling back to the sequence item only when no
+    // claim exists.
+    const claimByPlanId = new Map();
+    for (const c of allClaimsSnapshot) {
+        if (c.plan_id)
+            claimByPlanId.set(c.plan_id, c);
+    }
+    const canonicalPlanId = (id) => planIndex.get(id)?.id ?? id;
+    const scopeForPred = (predId) => claimByPlanId.get(canonicalPlanId(predId))?.scope ?? itemByPlanId.get(predId)?.scope_hint ?? predId;
+    // Collect plan IDs that are done or dropped (terminal → gate-open) and the
+    // dropped subset (excluded from socle-fork: never propagate abandoned code —
+    // review Finding 6).
     const terminalPlanIds = new Set();
+    const droppedPlanIds = new Set();
     for (const p of state.plan_items) {
-        if (p.status === 'done' || p.status === 'dropped') {
+        if (p.status === 'done' || p.status === 'dropped')
             terminalPlanIds.add(p.id);
-        }
+        if (p.status === 'dropped')
+            droppedPlanIds.add(p.id);
     }
     // Collect plan IDs with active claims
     const claimedPlanIds = new Map();
@@ -150,16 +184,40 @@ export function analyzeSequence(cwd) {
             });
             continue;
         }
+        // pln#529 (dec#122 B+A) — for a gated lane, readiness ≠ code-availability:
+        // resolve the fork base by CONTENT. A ≥2-unintegrated diamond keeps the gate
+        // CLOSED (A); otherwise the lane is ready with its resolved base (HEAD, or a
+        // predecessor branch when the socle isn't on HEAD yet — B).
+        if (item.hard_after.length > 0) {
+            // Socle-fork considers DONE predecessors only — a dropped predecessor still
+            // satisfies the gate but its abandoned code must not be propagated (#6).
+            const socleDeps = item.hard_after.filter((id) => !droppedPlanIds.has(canonicalPlanId(id)));
+            const base = resolveGatedLaneBase(socleDeps, scopeForPred, cwd);
+            if (base.gateBlocked) {
+                blocked.push({
+                    item,
+                    plan,
+                    lane: item.lane,
+                    reason: base.gateBlocked.reason,
+                    blocked_by: base.gateBlocked.unintegrated,
+                });
+                continue;
+            }
+            ready.push({
+                item,
+                plan,
+                lane: item.lane,
+                reason: `All hard dependencies met${softNote}`,
+                worktreeBase: base,
+                code_propagation_note: base.reason,
+            });
+            continue;
+        }
         ready.push({
             item,
             plan,
             lane: item.lane,
             reason: `All hard dependencies met${softNote}`,
-            // pln#529 — readiness ≠ code-availability for gated lanes.
-            ...(item.hard_after.length > 0 ? {
-                code_propagation_note: `Unblocked by hard_after [${item.hard_after.join(', ')}]. Ensure that work is committed AND on the dispatch base (HEAD), ` +
-                    `or dispatch this lane with ref=<predecessor branch> — otherwise the worker spawns from HEAD without it.`,
-            } : {}),
         });
     }
     // Build capacity summary per agent (multi-instance aware)
@@ -631,20 +689,113 @@ function countCycleByResource(cycleAssignments, resourceKey) {
     }
     return total;
 }
-export function selectWorktreeBaseForReadyLane(item, analysis) {
-    const hardAfter = item.hard_after ?? [];
+/**
+ * pln#529 (dec#122 B+A) — resolve the fork base for a gated lane whose hard_after
+ * predecessors are all DONE (dropped predecessors are excluded by the caller —
+ * their abandoned code must not be propagated). "Readiness ≠ code-availability":
+ * a done predecessor's code may be committed on its own branch but NOT integrated
+ * on HEAD (the standard squash-merge breaks ancestry — trp#926 — so integration
+ * is detected by CONTENT via `isBranchMergedByContent`, patch-id + file-content,
+ * not ancestry).
+ *
+ * `scopeFor(predId)` MUST return the GROUND-TRUTH scope the predecessor's branch
+ * was created from — its persisted claim scope (review Finding 1). Re-deriving
+ * the branch from live/mutable sequence metadata probes the wrong branch under
+ * the coordinate(assign) path or an edited scope_hint, and the miss silently
+ * defaults to HEAD — the very socle-drop this feature closes.
+ *
+ * `cwd` MUST be the project's MAIN git worktree (HEAD = the integration target);
+ * `analyzeSequence` is the sole production caller and passes the coordinator root.
+ *
+ * Per predecessor (branch = `feat/<sanitized scope>`), by tri-state probe:
+ *   - present + content-merged → verified on HEAD;
+ *   - present + NOT merged     → committed-but-unintegrated (fork candidate);
+ *   - absent (clean not-found) → ASSUMED on HEAD (merged + branch cleaned up) —
+ *     honestly labelled "assumed", never claimed "verified";
+ *   - unknown (git probe FAILED) → unverifiable → fail SAFE (gateBlocked), never
+ *     silently "on HEAD" (review Finding 3).
+ * Then: any unverifiable, or ≥2 fork-candidates → gateBlocked (A); exactly 1
+ * fork-candidate → fork from it (B); else baseRef HEAD (A satisfied).
+ */
+export function resolveGatedLaneBase(hardAfter, scopeFor, cwd) {
     if (hardAfter.length === 0)
         return {};
-    const donePlanIds = new Set(analysis.done.map((entry) => entry.planId));
-    const allHardDepsDone = hardAfter.every((planId) => donePlanIds.has(planId));
-    if (!allHardDepsDone)
-        return {};
+    // Non-git project → branch/worktree socle propagation is inapplicable; keep the
+    // legacy HEAD base (the tri-state "unknown" fail-safe is ONLY for a git repo
+    // whose branch probe transiently failed, not for a project that has no git at
+    // all — otherwise every non-git gated lane would wrongly gate-block).
+    if (!isGitRepo(cwd)) {
+        return { baseRef: 'HEAD', resetExistingBranch: true, reason: 'non-git project — socle propagation not applicable; base = HEAD' };
+    }
+    const unintegrated = [];
+    const unverifiable = [];
+    const verifiedOnHead = [];
+    const assumedOnHead = [];
+    for (const predId of hardAfter) {
+        const branch = `feat/${sanitizeBranchComponent(scopeFor(predId))}`;
+        const probe = probeLocalBranch(cwd, branch);
+        if (probe === 'unknown') {
+            unverifiable.push({ planId: predId, branch });
+            continue;
+        }
+        if (probe === 'absent') {
+            assumedOnHead.push(predId);
+            continue;
+        } // merged + branch GC'd
+        if (isBranchMergedByContent(cwd, branch, 'HEAD')) {
+            verifiedOnHead.push(predId);
+            continue;
+        }
+        unintegrated.push({ planId: predId, branch });
+    }
+    // Fail SAFE: a git probe we could not complete must NOT open the gate on a
+    // "HEAD is fine" assumption. Combine with the ≥2-fork-candidate diamond.
+    if (unverifiable.length > 0 || unintegrated.length >= 2) {
+        const parts = [
+            ...unintegrated.map((u) => `${u.planId}→${u.branch} (committed, not on HEAD)`),
+            ...unverifiable.map((u) => `${u.planId}→${u.branch} (integration UNVERIFIABLE — git probe failed)`),
+        ];
+        return {
+            gateBlocked: {
+                reason: `pln#529(A): cannot safely resolve a single fork base for this gated lane — ${parts.join('; ')}. Integrate the un-integrated predecessors onto HEAD (merge/squash), or retry once git is reachable; a single worktree cannot fork from multiple bases without silently dropping a predecessor's code.`,
+                unintegrated: [...unintegrated, ...unverifiable].map((u) => u.planId),
+            },
+        };
+    }
+    const headNote = (verb) => `${verb}${verifiedOnHead.length ? ` content-verified on HEAD: ${verifiedOnHead.join(', ')}` : ''}` +
+        `${assumedOnHead.length ? `${verifiedOnHead.length ? '; ' : ' '}assumed on HEAD (branch absent — merged + cleaned, unverifiable): ${assumedOnHead.join(', ')}` : ''}`;
+    if (unintegrated.length === 1) {
+        const u = unintegrated[0];
+        return {
+            baseRef: u.branch,
+            resetExistingBranch: true,
+            reason: `pln#529(B): predecessor ${u.planId} is committed on ${u.branch} but not yet integrated on HEAD — the dependent lane forks from that branch so it carries the socle code. (${headNote('Other predecessors:')})`,
+        };
+    }
     return {
         baseRef: 'HEAD',
         resetExistingBranch: true,
-        reason: `hard_after dependencies already integrated: ${hardAfter.join(', ')}`,
+        reason: `pln#529: ${headNote('hard_after predecessors —')}`,
     };
 }
+/**
+ * @deprecated pln#529 — superseded by `resolveGatedLaneBase` (content + claim
+ * aware). Retained for callers that only have `(item, analysis)`; forwards using
+ * the analysis's done set for scope fallback (no claim access). Prefer the
+ * pre-computed `ReadyLane.worktreeBase`.
+ */
+export function selectWorktreeBaseForReadyLane(item, analysis, cwd = process.cwd()) {
+    const hardAfter = item.hard_after ?? [];
+    if (hardAfter.length === 0)
+        return {};
+    const donePlanIds = new Set(analysis.done.map((entry) => entry.planId));
+    if (!hardAfter.every((planId) => donePlanIds.has(planId)))
+        return {};
+    const itemByPlanId = new Map();
+    for (const entry of analysis.done)
+        itemByPlanId.set(entry.planId, entry);
+    return resolveGatedLaneBase(hardAfter, (predId) => itemByPlanId.get(predId)?.scope_hint ?? predId, cwd);
+}
 /**
  * Run a dispatch cycle: analyze the sequence, generate briefs, send assignments.
  */
@@ -654,7 +805,7 @@ export async function dispatch(options, cwd) {
         sweepAssignments(cwd, { actor: options.dispatcherAgent });
     }
     catch { /* best-effort */ }
-    const analysis = analyzeSequence(cwd);
+    const analysis = analyzeSequence(cwd, options.sequenceId);
     if (!analysis)
         return null;
     const result = { delivery_plan: [], messages_sent: [], commands: [], skipped: [], warnings: [] };
@@ -728,7 +879,10 @@ export async function dispatch(options, cwd) {
         let claimId = '(dry-run)';
         let worktreePath;
         if (!options.dryRun) {
-            const worktreeBase = selectWorktreeBaseForReadyLane(readyItem.item, analysis);
+            // pln#529 — use the content-aware base resolved during analyzeSequence
+            // (HEAD when the socle is integrated, else the predecessor branch). Fall
+            // back to a fresh resolution for direct callers that bypassed analyze.
+            const worktreeBase = readyItem.worktreeBase ?? selectWorktreeBaseForReadyLane(readyItem.item, analysis, cwd);
             const claimResult = createCoordinatorClaim({
                 agent: targetAgent,
                 scope: claimScope,

package/dist/core/execution-adapters.js

@@ -5,13 +5,39 @@ import { buildClaimEnvPrefix, buildWorkerIdentityEnv } from './execution-profile
 import { getCapabilityProfile } from './agent-capability.js';
 import { nowISO } from './ids.js';
 import { ensureRuntimeDirs, getRuntimeLogPath, getRuntimeSignalPath, } from './runtime-signals.js';
-export function buildAckWrapCommand(bashCommand, paths, isWin32) {
+// The turn-echo values are raw-embedded into a shell one-liner (see marker()),
+// so the `[A-Za-z0-9_-]` safety invariant documented on TurnEcho is LOAD-BEARING,
+// not cosmetic. A stray `"` desyncs cmd.exe quote-parity (no sentinel file is
+// written → the turn-owned run never converges under read-strict acceptance —
+// exactly the §13 D2 non-convergence this feature prevents); a `'` breaks out of
+// the POSIX `printf '…'` wrapper. All real sources (deriveTurnId/deriveChildIds
+// hex, crypto.randomUUID nonce) satisfy it, so this guard never fires in
+// production — it exists to turn a future out-of-class caller's SILENT corruption
+// into a loud, fast failure at the embed site.
+const TURN_ECHO_SAFE = /^[A-Za-z0-9_-]+$/;
+export function buildAckWrapCommand(bashCommand, paths, isWin32, turnEcho) {
+    if (turnEcho) {
+        for (const [field, value] of Object.entries(turnEcho)) {
+            if (!TURN_ECHO_SAFE.test(value)) {
+                throw new Error(`buildAckWrapCommand: turnEcho.${field} must match ${TURN_ECHO_SAFE} to be shell-safe for the completion sentinel (got ${JSON.stringify(value)})`);
+            }
+        }
+    }
     const touch = isWin32
         ? (p) => `type nul > "${p}"`
         : (p) => `touch "${p}"`;
+    // completed/failed marker: a turn-keyed JSON body when turnEcho is present,
+    // else the legacy empty touch (byte-for-byte unchanged for non-turn-owned
+    // spawns — full back-compat).
+    const marker = (p, status) => {
+        if (!turnEcho)
+            return touch(p);
+        const body = JSON.stringify({ turn_id: turnEcho.turn_id, run_id: turnEcho.run_id, nonce: turnEcho.nonce, status });
+        return isWin32 ? `echo ${body}>"${p}"` : `printf '%s' '${body}' > "${p}"`;
+    };
     const redirected = `${bashCommand} > "${paths.stdoutLog}" 2> "${paths.stderrLog}"`;
     return (`${touch(paths.ackPath)} && ` +
-        `( ${redirected} && ${touch(paths.completedPath)} || ${touch(paths.failedPath)} )`);
+        `( ${redirected} && ${marker(paths.completedPath, 'completed')} || ${marker(paths.failedPath, 'failed')} )`);
 }
 /**
  * Check if a binary is resolvable on the system PATH.
@@ -148,7 +174,7 @@ export class CliExecutionAdapter {
                 failedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'failed'),
                 stdoutLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stdout'),
                 stderrLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stderr'),
-            }, isWin32);
+            }, isWin32, options.turnEcho);
             child = spawn(wrappedCmd, [], {
                 detached: !isWin32,
                 shell: true,

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

@@ -0,0 +1,124 @@
+import { getLoop } from './loops/store.js';
+import { complete_turn, advance, evaluatePhaseAdvanceGate } from './loops/verbs.js';
+import { withLoopLock } from './loops/lock.js';
+import { LOOP_ARTIFACT_BODY_MAX_BYTES } from './loops/types.js';
+/** ideate-loop:lop_xxx[:slot] → the loop id (dispatch sets `ideate-loop:${loopId}:${slotId}`). */
+const IDEATE_LOOP_SCOPE_RE = /^ideate-loop:(lop_[0-9a-z]+)/;
+const LOOP_TERMINAL = new Set(['completed', 'cancelled', 'blocked']);
+/** Byte-cap a critique body (keep the head) so complete_turn's 4 KiB artifact-body limit
+ *  can't reject a long critique. Leaves envelope headroom for the artifact JSON. */
+function capCritique(body) {
+    const MAX = LOOP_ARTIFACT_BODY_MAX_BYTES - 512;
+    if (Buffer.byteLength(body, 'utf8') <= MAX)
+        return body;
+    let end = body.length;
+    while (end > 0 && Buffer.byteLength(body.slice(0, end), 'utf8') > MAX)
+        end -= 64;
+    return `${body.slice(0, Math.max(0, end))}…[truncated]`;
+}
+/**
+ * Resolve the critic slot to complete. STRICT by assignment_id (bound since pln#629), so
+ * multi-critic loops complete the right slot; never steal a slot bound to a DIFFERENT
+ * assignment. Legacy unbound slots fall back to agent / single-active.
+ */
+function resolveCriticSlot(loop, assignment) {
+    // role === 'critic' is LOAD-BEARING (review F-A): a coordinate-opened ideation loop
+    // also has an unbound `champion` slot that lane-harvest never completes; without this
+    // filter the single-active fallback below would select the CHAMPION after the critics
+    // finish, corrupting the loop. Mirrors resolveReviewerSlot's role filter.
+    const active = loop.slots.filter((s) => s.role === 'critic' && s.status !== 'done' && s.status !== 'cancelled' && s.status !== 'failed');
+    if (active.length === 0)
+        return undefined;
+    if (assignment.id) {
+        const bound = active.find((s) => s.assignment_id === assignment.id);
+        if (bound)
+            return bound;
+        if (active.some((s) => s.assignment_id !== undefined))
+            return undefined; // bound elsewhere → don't steal
+    }
+    if (active.length === 1)
+        return active[0];
+    const byAgent = assignment.agent ? active.find((s) => s.agent === assignment.agent) : undefined;
+    return byAgent ?? active[0];
+}
+/**
+ * Map a harvested critic lane onto its ideation loop and converge it. Fires ONLY on an
+ * `ideate-loop:<lop>` scope + a completed lane; otherwise returns undefined and harvest
+ * proceeds unchanged. Idempotent (a terminal/absent slot → noop), defensive (any
+ * loop-verb / lock error is swallowed into a noop so a convergence failure never breaks
+ * harvest — mirrors closeReviewLoopFromLaneResult).
+ */
+export function closeIdeationLoopFromLaneResult(assignment, lane, actor, cwd) {
+    const m = assignment.scope?.match(IDEATE_LOOP_SCOPE_RE);
+    if (!m)
+        return undefined;
+    if (lane.status !== 'completed')
+        return undefined; // only a completed critic converges
+    const loopId = m[1];
+    const noop = (reason, loop_status) => ({
+        loop_id: loopId, action: 'noop', reason, loop_status,
+    });
+    try {
+        return withLoopLock({
+            cwd, intent: 'ideate-harvest-close', agentId: actor, scope: { kind: 'loop', loopId },
+            work: () => {
+                const loop = getLoop(loopId, cwd);
+                if (!loop)
+                    return noop('loop not found');
+                if (LOOP_TERMINAL.has(loop.status))
+                    return noop(`loop already ${loop.status}`, loop.status);
+                // Advance, treating ONLY phase_advance_blocked as the expected gate-not-met case;
+                // re-throw any OTHER advance error to the outer catch so a real failure becomes a
+                // noop carrying the actual message, NEVER a misreported success (review F-C).
+                const tryAdvance = (recorded) => {
+                    try {
+                        const advanced = advance({ id: loopId, actor }, cwd);
+                        return {
+                            loop_id: loopId,
+                            action: advanced.auto_closed ? 'closed' : 'advanced',
+                            reason: `critique gate met → phase "${advanced.loop.current_phase}"`,
+                            loop_status: advanced.loop.status,
+                        };
+                    }
+                    catch (err) {
+                        if (err instanceof Error && /phase_advance_blocked/.test(err.message)) {
+                            return recorded
+                                ? { loop_id: loopId, action: 'critique_recorded', reason: 'critique recorded; gate not yet met (more critics needed)', loop_status: getLoop(loopId, cwd)?.status }
+                                : noop('no active critic slot; critique gate not yet met (idempotent)', getLoop(loopId, cwd)?.status);
+                        }
+                        throw err; // a REAL advance error → outer catch → noop with the message
+                    }
+                };
+                const slot = resolveCriticSlot(loop, assignment);
+                if (!slot) {
+                    // No active critic slot: either already processed, OR a prior pass recorded the
+                    // critique(s) and crashed BEFORE advancing → the loop is stuck at a satisfied
+                    // critique gate. RESUME only in that precise case (review F-B) — the current
+                    // phase's gate must be a critique gate that now evaluates MET — so we never
+                    // over-advance a loop that already moved on to revision/synthesis.
+                    const gate = loop.phases.find((p) => p.name === loop.current_phase)?.advance_gate;
+                    const stuckAtCritiqueGate = gate?.kind === 'min_artifacts_by_type' && gate.type === 'critique' && evaluatePhaseAdvanceGate(loop, gate).advance;
+                    return stuckAtCritiqueGate ? tryAdvance(false) : noop('no active critic slot; nothing to resume', loop.status);
+                }
+                // A critic's LANE-RESULT carries free-form summary/notes (no structured
+                // critiques[] field) → ONE critique artifact. A bare lane with no critique
+                // content FAILS the slot (mirror ideationReducer: no fake gate progress).
+                const critique = [lane.summary, lane.notes]
+                    .map((s) => (s ?? '').trim())
+                    .filter(Boolean)
+                    .join('\n\n')
+                    .trim();
+                if (!critique) {
+                    complete_turn({ id: loopId, slot_id: slot.slot_id, actor, outcome: 'failed', failure_reason: 'critic lane produced no critique content (bare summary)' }, cwd);
+                    return { loop_id: loopId, action: 'failed', reason: 'bare critic lane → slot failed; critique gate unchanged', loop_status: getLoop(loopId, cwd)?.status };
+                }
+                complete_turn({ id: loopId, slot_id: slot.slot_id, actor, outcome: 'done', artifact: { phase: loop.current_phase, type: 'critique', body: capCritique(critique) } }, cwd);
+                return tryAdvance(true);
+            },
+        });
+    }
+    catch (err) {
+        return noop(`ideation close error (swallowed): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=ideation-loop-close.js.map

package/dist/core/loops/artifact-resolver.js

@@ -0,0 +1,197 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryDir } from '../io.js';
+/**
+ * Safe canonical artifact resolver (pln#630 §7).
+ *
+ * The single central resolver every loop-artifact reader/writer must use. It
+ * replaces the ad-hoc `path.join(dir, body.ref)` (hooks/bootstrap-write.ts) that
+ * joined a WORKER-CONTROLLED `ref` straight onto a store dir — a path-traversal
+ * hole (`ref: "../../../etc/passwd"` escaped the artifacts dir).
+ *
+ * The safety protocol, mandatory before any state mutation (§7):
+ *   1. Brainclaw-generated target basenames — `<artifact_id>.<ext>`, never a
+ *      worker-supplied name.
+ *   2. Worker source paths validated by `realpath` CONTAINMENT (reject `../`
+ *      escapes and symlink-out) before any read.
+ *   3. Atomic temp-copy + fsync + rename into the canonical store.
+ *   4. size + sha256 validation against the attempt's expected_artifacts.
+ *   5. Deterministic (artifact_id-keyed) target + hash check = per-turn
+ *      idempotency: a crash between copy and the artifact/event write retries
+ *      without duplicating (re-copy of an identical payload is a no-op).
+ *
+ * Canonical home (unifies the two conflicting doc paths §7):
+ *   .brainclaw/loops/artifacts/<lop_id>/<artifact_id>.<ext>
+ * Migration is new-then-legacy on READ, reject-on-hash-mismatch; writes go to the
+ * new path only.
+ */
+export class ArtifactResolverError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ArtifactResolverError';
+    }
+}
+/** Legacy on-disk home for ref-based payloads (pre-§7). Read fallback only. */
+function legacyArtifactsDir(loopId, cwd) {
+    return path.join(memoryDir(cwd ?? process.cwd()), 'loops', 'threads', loopId, 'artifacts');
+}
+/** Canonical home for a loop's artifact payloads (§7). */
+export function canonicalArtifactsDir(loopId, cwd) {
+    return path.join(memoryDir(cwd ?? process.cwd()), 'loops', 'artifacts', loopId);
+}
+/**
+ * The canonical absolute path for a brainclaw-owned artifact payload. The
+ * basename is derived ENTIRELY from brainclaw-generated ids (never a worker
+ * string), so it cannot traverse. `ext` is sanitized to a bare alnum extension.
+ */
+export function canonicalArtifactPath(loopId, artifactId, ext, cwd) {
+    const safeExt = ext.replace(/^\.+/, '').replace(/[^A-Za-z0-9]/g, '') || 'txt';
+    return path.join(canonicalArtifactsDir(loopId, cwd), `${artifactId}.${safeExt}`);
+}
+/**
+ * Validate that a worker-relative path resolves to a real file CONTAINED within
+ * `workerRoot` (no `../` escape, no symlink pointing outside). Returns the
+ * validated absolute path; throws `containment_violation` / `source_missing`
+ * otherwise. This is the mandatory gate before ANY read of a worker-produced
+ * artifact (§7 / invariant #7).
+ */
+export function resolveContainedWorkerPath(workerRoot, workerRelPath, _cwd) {
+    // realpath the containment ROOT first (it must exist and be a directory).
+    let rootReal;
+    try {
+        rootReal = fs.realpathSync(workerRoot);
+    }
+    catch {
+        throw new ArtifactResolverError('source_missing', `resolveContainedWorkerPath: worker root ${workerRoot} does not resolve`);
+    }
+    // Reject an absolute worker path outright — an expected artifact is always
+    // worker-RELATIVE; an absolute path is a red flag we never join.
+    if (path.isAbsolute(workerRelPath)) {
+        throw new ArtifactResolverError('containment_violation', `resolveContainedWorkerPath: absolute worker path "${workerRelPath}" rejected`);
+    }
+    const joined = path.resolve(rootReal, workerRelPath);
+    // Lexical containment check on the joined path BEFORE touching the FS (guards
+    // the case where the target itself does not exist yet).
+    const rootWithSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
+    if (joined !== rootReal && !joined.startsWith(rootWithSep)) {
+        throw new ArtifactResolverError('containment_violation', `resolveContainedWorkerPath: "${workerRelPath}" escapes worker root`);
+    }
+    // realpath the target and re-check containment — defeats a symlink inside the
+    // root that points outside it (lexical check alone would pass).
+    let targetReal;
+    try {
+        targetReal = fs.realpathSync(joined);
+    }
+    catch {
+        throw new ArtifactResolverError('source_missing', `resolveContainedWorkerPath: "${workerRelPath}" does not resolve to a file under the worker root`);
+    }
+    if (targetReal !== rootReal && !targetReal.startsWith(rootWithSep)) {
+        throw new ArtifactResolverError('containment_violation', `resolveContainedWorkerPath: "${workerRelPath}" resolves (via symlink) outside the worker root`);
+    }
+    return targetReal;
+}
+function sha256OfFile(absPath) {
+    const buf = fs.readFileSync(absPath);
+    return { sha256: crypto.createHash('sha256').update(buf).digest('hex'), byte_count: buf.length };
+}
+/**
+ * Copy a containment-validated worker source into the canonical store — atomically
+ * (temp + fsync + rename), with size/sha256 validation and per-turn idempotency
+ * (§7). Idempotent: if the deterministic target already holds the same bytes, this
+ * is a no-op; if it holds DIFFERENT bytes, that is a hard `canonical_hash_conflict`
+ * (a deterministic-id collision or corruption — never silently overwrite).
+ */
+export function copyArtifactToCanonicalStore(input) {
+    const { loopId, artifactId, ext, sourceAbsPath, expectedSha256, expectedByteCount, cwd } = input;
+    if (!fs.existsSync(sourceAbsPath)) {
+        throw new ArtifactResolverError('source_missing', `copyArtifactToCanonicalStore: source ${sourceAbsPath} missing`);
+    }
+    // Read the source EXACTLY ONCE (review Finding 4): hash + validate + write the
+    // SAME buffer, so a source mutation between a validate-read and a copy-read can
+    // never let bytes whose hash differs from the reported/validated sha256 become
+    // canonical state.
+    const buf = fs.readFileSync(sourceAbsPath);
+    const sha256 = crypto.createHash('sha256').update(buf).digest('hex');
+    const byte_count = buf.length;
+    // Validate against the attempt's declared expectations BEFORE any write.
+    if (expectedSha256 !== undefined && expectedSha256 !== sha256) {
+        throw new ArtifactResolverError('sha256_mismatch', `copyArtifactToCanonicalStore: sha256 ${sha256} != expected ${expectedSha256}`);
+    }
+    if (expectedByteCount !== undefined && expectedByteCount !== byte_count) {
+        throw new ArtifactResolverError('byte_count_mismatch', `copyArtifactToCanonicalStore: byte_count ${byte_count} != expected ${expectedByteCount}`);
+    }
+    const canonicalPath = canonicalArtifactPath(loopId, artifactId, ext, cwd);
+    // Idempotency: a matching target is a no-op; a mismatching target is a conflict.
+    if (fs.existsSync(canonicalPath)) {
+        const existing = sha256OfFile(canonicalPath);
+        if (existing.sha256 === sha256) {
+            return { canonicalPath, sha256, byte_count, idempotent: true };
+        }
+        throw new ArtifactResolverError('canonical_hash_conflict', `copyArtifactToCanonicalStore: ${canonicalPath} already exists with a DIFFERENT hash (${existing.sha256} vs ${sha256}) — refusing to overwrite`);
+    }
+    const dir = path.dirname(canonicalPath);
+    fs.mkdirSync(dir, { recursive: true });
+    // Atomic temp-copy + fsync + rename of the ALREADY-HASHED buffer. The temp name
+    // is process/id-scoped so concurrent copies of distinct artifacts never collide.
+    const tmpPath = path.join(dir, `.${artifactId}.${process.pid}.tmp`);
+    const fd = fs.openSync(tmpPath, 'w');
+    try {
+        let off = 0;
+        while (off < buf.length)
+            off += fs.writeSync(fd, buf, off, buf.length - off);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.renameSync(tmpPath, canonicalPath);
+    }
+    catch (err) {
+        // A racing writer may have created the target between our existence check and
+        // the rename. Re-check idempotency rather than clobbering.
+        fs.rmSync(tmpPath, { force: true });
+        if (fs.existsSync(canonicalPath) && sha256OfFile(canonicalPath).sha256 === sha256) {
+            return { canonicalPath, sha256, byte_count, idempotent: true };
+        }
+        throw err;
+    }
+    return { canonicalPath, sha256, byte_count, idempotent: false };
+}
+/**
+ * Read an artifact payload from the canonical store, falling back to the legacy
+ * `loops/threads/<loop_id>/artifacts/<ref>` path for pre-§7 artifacts. When BOTH
+ * exist, their hashes MUST match (reject-on-mismatch migration safety §7). An
+ * `expectedSha256` is validated against whichever copy is returned.
+ */
+export function readCanonicalArtifact(loopId, artifactId, ext, opts = {}) {
+    const { legacyRef, expectedSha256, cwd } = opts;
+    const canonicalPath = canonicalArtifactPath(loopId, artifactId, ext, cwd);
+    const legacyPath = legacyRef ? path.join(legacyArtifactsDir(loopId, cwd), legacyRef) : undefined;
+    const canonicalExists = fs.existsSync(canonicalPath);
+    const legacyExists = legacyPath !== undefined && fs.existsSync(legacyPath);
+    if (!canonicalExists && !legacyExists) {
+        throw new ArtifactResolverError('artifact_missing', `readCanonicalArtifact: ${artifactId} not found (canonical nor legacy)`);
+    }
+    if (canonicalExists && legacyExists) {
+        // Migration overlap — both must agree, else refuse (never trust a divergent legacy copy).
+        const c = sha256OfFile(canonicalPath);
+        const l = sha256OfFile(legacyPath);
+        if (c.sha256 !== l.sha256) {
+            throw new ArtifactResolverError('canonical_hash_conflict', `readCanonicalArtifact: ${artifactId} canonical/legacy hash mismatch (${c.sha256} vs ${l.sha256})`);
+        }
+    }
+    const readPath = canonicalExists ? canonicalPath : legacyPath;
+    const buf = fs.readFileSync(readPath);
+    if (expectedSha256 !== undefined) {
+        const actual = crypto.createHash('sha256').update(buf).digest('hex');
+        if (actual !== expectedSha256) {
+            throw new ArtifactResolverError('sha256_mismatch', `readCanonicalArtifact: ${artifactId} sha256 ${actual} != expected ${expectedSha256}`);
+        }
+    }
+    return buf;
+}
+//# sourceMappingURL=artifact-resolver.js.map