brainclaw 1.17.0 → 1.19.0

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

@@ -0,0 +1,152 @@
+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 expectedArtifactType = 'critique';
+                // Prefer the typed envelope, but honor the legacy artifacts labels too:
+                // coverage_gap used to be silently invisible to a critique gate.
+                const reportedArtifactType = lane.artifact_type?.trim()
+                    ?? lane.artifacts?.find((label) => /^[a-z][a-z0-9_]*$/.test(label) && label !== expectedArtifactType);
+                const body = lane.body?.trim();
+                const critique = body || [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: reportedArtifactType && reportedArtifactType !== expectedArtifactType
+                            ? `reported artifact type "${reportedArtifactType}" has no usable body; expected "${expectedArtifactType}"`
+                            : 'bare critic lane → slot failed; critique gate unchanged',
+                        loop_status: getLoop(loopId, cwd)?.status };
+                }
+                // pln#639 BUG-2 — attribute the artifact to the phase the slot was
+                // DISPATCHED in, not the loop's phase at close time.
+                //
+                // `turn()` stamps `slot.phase = current_phase` when the slot is handed
+                // out (loops/verbs.ts). Using `loop.current_phase` here instead means a
+                // lane that returns AFTER a phase advance has its work filed under the
+                // new phase: a critique landing 90 seconds late is recorded in
+                // `revision`, where the critique gate cannot see it and where it
+                // misrepresents what the agent was asked to do. Reproduced in the
+                // pln#638 1a/1b ideation, which advanced ~90s after its last critic.
+                //
+                // Truthful attribution is also the fix for "don't count it": the gate
+                // filters on `artifact.phase === current_phase`, so an out-of-phase
+                // artifact stops satisfying the current gate by construction — no
+                // separate refusal path, and the content is preserved rather than lost.
+                const dispatchPhase = slot.phase ?? loop.current_phase;
+                complete_turn({ id: loopId, slot_id: slot.slot_id, actor, outcome: 'done', artifact: { phase: dispatchPhase, type: 'critique', body: capCritique(critique) } }, cwd);
+                const advanced = tryAdvance(true);
+                return reportedArtifactType && reportedArtifactType !== expectedArtifactType
+                    ? { ...advanced, reason: `reconciled reported artifact type "${reportedArtifactType}" to expected "${expectedArtifactType}"; ${advanced.reason}` }
+                    : advanced;
+            },
+        });
+    }
+    catch (err) {
+        return noop(`ideation close error (swallowed): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=ideation-loop-close.js.map

package/dist/core/instruction-templates.js

@@ -217,10 +217,18 @@ function renderHeader(input) {
         `> Regenerate: brainclaw export --format ${formatForAgent(input.profile.name)} --write`,
     ].join('\n');
 }
-function renderLiveHeader(_input) {
+function renderLiveHeader(input) {
+    // pln#638 volet 2a — HONESTY FIX. This header used to say "auto-refreshed",
+    // but regeneration is EXPLICIT: it happens on session-end, handoff, and
+    // `export --write`. An agent tier that never fires those events (no hooks, no
+    // MCP) read a file claiming to be fresh while being arbitrarily stale. A claim
+    // that is false for half the tiers is worse than no claim, so the header now
+    // names the actual triggers and tells the reader how to force a refresh.
+    // Guarded by tests/unit/guidance-engine-consistency.test.ts.
     return [
-        `> Brainclaw live state — auto-refreshed, do not edit.`,
-        `> Last updated: ${new Date().toISOString().slice(0, 19)}`,
+        `> Brainclaw live state — do not edit. Regenerated on: session-end, handoff, \`brainclaw export --write\`.`,
+        `> Written by brainclaw v${input.brainclawVersion} at ${new Date().toISOString().slice(0, 19)}`,
+        `> Older than your last session? It is stale — run \`brainclaw export --write\` to refresh.`,
     ].join('\n');
 }
 // Kept deliberately small (pln#542): entry point + grammar + escalation

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