brainclaw 1.18.0 → 1.19.1

package/dist/core/claims.js

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -13,6 +14,7 @@ import { refreshLiveCompanions } from '../commands/export.js';
 import { loadSessionById } from './identity.js';
 import { loadState, persistState } from './state.js';
 import { createRuntimeEvent } from './events.js';
+import { latestActivityMs, readHeartbeat } from './runtime-signals.js';
 import { emitRegistryPostImage, registryFaultPoint } from './events/registry-post-image.js';
 import { maybeEnqueueClaimTransition, isFederationEnqueueActive } from './federation-outbox.js';
 /** Parse duration string like '4h', '30m' to ms. */
@@ -119,6 +121,63 @@ export function saveClaim(claim, cwd) {
         saveClaimUnlocked(claim, cwd);
     });
 }
+/**
+ * pln#636 C0-b — resolve the commit a claim starts from.
+ *
+ * Recorded once, at creation, and never updated: it is the fixed point a later
+ * "what did this claim actually touch?" comparison needs. The design review
+ * rejected both alternatives — neither HEAD-at-read-time nor the worktree dirty
+ * set is authoritative once a lane commits mid-work.
+ *
+ * BEST-EFFORT BY CONSTRUCTION. A non-git project, a detached state, or a missing
+ * git binary yields `undefined`, and a claim without a baseline is simply
+ * `unverifiable` downstream. Claim acquisition must never fail because a
+ * conformity nicety could not be computed.
+ */
+export function resolveClaimBaseSha(cwd) {
+    try {
+        const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+            cwd: cwd ?? process.cwd(),
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
+        if (result.status !== 0)
+            return undefined;
+        const sha = result.stdout.trim();
+        return /^[0-9a-f]{7,40}$/i.test(sha) ? sha : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The baseline fields every NEW claim must carry, ready to spread into a claim
+ * literal: `{ ...claimBaselineFields(cwd) }`.
+ *
+ * WHY A HELPER AND NOT AN INLINE CALL. `base_sha` shipped in 1.19.0 stamped from
+ * exactly ONE place — inside `acquireClaimScope` — and it turned out nothing
+ * user-facing calls that function. All four real creation paths
+ * (`bclaw_work(execute)`, `bclaw_claim`, the CLI `claim create`, and
+ * `createCoordinatorClaim`) build their claim literal inline and call `saveClaim`
+ * directly, so NO real claim ever got a baseline and the whole conformity
+ * reconcile that depends on it was inert (trp#1292). A named, greppable helper is
+ * what makes "did this creation path stamp the baseline?" answerable, and it is
+ * asserted per surface rather than only on the core function — testing
+ * `acquireClaimScope` directly is exactly what hid the gap.
+ *
+ * Returns an EMPTY object rather than `{ base_sha: undefined }` so a claim created
+ * outside a git repo has no such key at all, matching the "optional, never
+ * backfilled" contract the schema documents.
+ *
+ * Deliberately NOT applied inside `saveClaim`: that function also persists
+ * UPDATES (release, patch, adoption), and the baseline must be a fixed point —
+ * re-stamping it on every save is precisely the moving-ground failure that made
+ * `git diff HEAD` unusable in the first place.
+ */
+export function claimBaselineFields(cwd) {
+    const base_sha = resolveClaimBaseSha(cwd);
+    return base_sha ? { base_sha } : {};
+}
 /**
  * Atomically check for an active claim on `scope` and save a new one if absent.
  *
@@ -126,6 +185,10 @@ export function saveClaim(claim, cwd) {
  * the mutation-pipeline mutex serializes filesystem writes on the claims store.
  */
 export function acquireClaimScope(input, cwd) {
+    // Resolved OUTSIDE the mutate callback: one git call per acquisition, and it
+    // stays off the critical section (mutate serializes filesystem writes on the
+    // claims store, so a subprocess spawn inside it would widen the lock window).
+    const baseline = claimBaselineFields(cwd);
     return mutate({ cwd }, () => {
         const conflictingClaim = listClaims(cwd).find((claim) => claim.status === 'active' && claim.scope === input.scope);
         if (conflictingClaim) {
@@ -143,6 +206,10 @@ export function acquireClaimScope(input, cwd) {
             status: 'active',
             plan_id: input.plan_id,
             model: input.model,
+            // pln#636 C0-b — capture the baseline while we know it. Absent when the
+            // project is not a git repo; downstream treats that as unverifiable.
+            ...baseline,
+            ...(input.paths?.length ? { paths: input.paths } : {}),
         };
         saveClaimUnlocked(claim, cwd);
         return { acquired: true, claim };
@@ -502,11 +569,82 @@ const DEFAULT_STALE_HOURS = 24;
  * even if it has no session yet (coordinator claims are created before the worker session starts).
  */
 const YOUNG_CLAIM_THRESHOLD_MS = 30 * 60_000; // 30 minutes
+/** Default freshness window for file evidence — matches the default `heartbeat_ttl_ms`. */
+const DEFAULT_EVIDENCE_TTL_MS = 30 * 60_000;
 /**
- * Assess the liveness of an active claim against session state.
+ * How far into the future a file timestamp may sit before we stop trusting it.
+ *
+ * WHY THIS TOLERANCE EXISTS, and why the naive `age < 0 → ignore` was wrong.
+ * `fs.stat().mtimeMs` is sub-millisecond on NTFS while `Date.now()` is coarser,
+ * so a heartbeat written microseconds ago routinely stats as *newer than now* —
+ * i.e. the freshest evidence possible was the evidence most likely to be thrown
+ * away. That reproduced as a nondeterministic liveness verdict: the same claim
+ * read `live` on an idle machine and `never-adopted` under load.
+ *
+ * A file dated slightly ahead is therefore clamped to age 0 (maximally fresh),
+ * while one dated grossly ahead is discarded — that is a genuinely wrong clock or
+ * a hand-forged timestamp, and inventing liveness from it would let a dead
+ * worker hold a claim forever.
+ */
+const FUTURE_EVIDENCE_TOLERANCE_MS = 5 * 60_000;
+/**
+ * pln#636 — age of the freshest FILE evidence that this claim's worker is alive.
+ *
+ * WHY FILE EVIDENCE AND NOT A SESSION. A sandboxed spawned worker cannot reach
+ * MCP, so it cannot maintain any server-side liveness record — which is exactly
+ * why the project moved proof-of-life to filesystem sentinels: the dispatcher
+ * injects a "Liveness — DO THIS FIRST" step into every brief, and the worker
+ * writes/refreshes a heartbeat in the ONE location a sandbox can write (its own
+ * worktree). `assignment-sweeper` already honours that evidence; claims did not,
+ * which meant a demonstrably-alive sandboxed worker kept its assignment but had
+ * its CLAIM aged out on wall-clock alone (trp_4d0fc2ef). This closes that
+ * asymmetry by reading the same signals.
+ *
+ * Deliberately reads the leaf `runtime-signals` module rather than
+ * `collectEvidence`: agentrun-reconciler imports `loadClaim` from here, so
+ * importing it back would create a cycle.
+ *
+ * Returns undefined when there is nothing to read — no assignment, no signals —
+ * and never throws.
+ */
+function freshestEvidenceAgeMs(claim, nowMs, cwd) {
+    if (!claim.assignment_id)
+        return undefined;
+    const root = cwd ?? process.cwd();
+    let freshest;
+    const consider = (ms) => {
+        if (ms === undefined)
+            return;
+        const age = nowMs - ms;
+        // Slightly-future timestamps are a clock-granularity artefact, not skew —
+        // clamp them to "just now". Grossly-future ones are untrustworthy: ignore
+        // rather than invent liveness. See FUTURE_EVIDENCE_TOLERANCE_MS.
+        if (age < -FUTURE_EVIDENCE_TOLERANCE_MS)
+            return;
+        const normalised = age < 0 ? 0 : age;
+        if (freshest === undefined || normalised < freshest)
+            freshest = normalised;
+    };
+    try {
+        const hb = readHeartbeat(root, claim.assignment_id, claim.worktree_path);
+        if (hb.exists)
+            consider(hb.mtimeMs);
+    }
+    catch { /* evidence is best-effort */ }
+    try {
+        consider(latestActivityMs(root, claim.assignment_id, claim.worktree_path));
+    }
+    catch { /* evidence is best-effort */ }
+    return freshest;
+}
+/**
+ * Assess the liveness of an active claim.
  *
  * Decision tree:
- *  1. Young (< 30 min) → never auto-release — dispatcher may not have sent the worker yet.
+ *  0. Young (< 30 min) → never auto-release — dispatcher may not have sent the worker yet.
+ *  1. FRESH FILE EVIDENCE → 'live', whatever the session says. This branch comes
+ *     first because it is the only proof a sandboxed, MCP-less worker can
+ *     produce, and it is the same evidence the assignment sweeper trusts.
  *  2. Has session_id + session alive → 'live' — long-running work; do NOT release.
  *  3. Has session_id + adopted_at + session dead → 'orphaned' — crash recovery scenario.
  *  4. Has session_id + no adopted_at + session dead → 'stale' — direct agent claim, session ended.
@@ -525,6 +663,21 @@ export function assessClaimLiveness(claim, options = {}) {
             ageMs,
         };
     }
+    // 1. FILE EVIDENCE FIRST (pln#636, trp_4d0fc2ef). A sandboxed worker proves
+    //    life by writing a heartbeat into its worktree — the only place it can
+    //    write — and by touching files there. That evidence outranks any session
+    //    reasoning: a worker actively committing is alive whether or not a session
+    //    record exists, and a coordinator-created claim has no session_id at all.
+    const evidenceAgeMs = freshestEvidenceAgeMs(claim, nowMs, options.cwd);
+    const evidenceTtlMs = options.evidenceTtlMs ?? DEFAULT_EVIDENCE_TTL_MS;
+    if (evidenceAgeMs !== undefined && evidenceAgeMs < evidenceTtlMs) {
+        return {
+            status: 'live',
+            reason: `File evidence is fresh (${Math.round(evidenceAgeMs / 60_000)}min ago) — the worker is demonstrably active`,
+            ageMs,
+            evidenceAgeMs,
+        };
+    }
     // 2–4. Has a session_id — check session liveness
     if (claim.session_id) {
         let sessionAgeMs;
@@ -729,6 +882,10 @@ export function createCoordinatorClaim(options) {
         };
     }
     const claimId = generateClaimId();
+    // Resolved OUTSIDE the lock below, for the same reason acquireClaimScope does
+    // it: a subprocess spawn inside the mutate callback would widen the critical
+    // section that serializes writes on the claims store.
+    const baseline = claimBaselineFields(options.cwd);
     let worktreePath;
     let worktreeWarning;
     // Create isolated worktree (matching bclaw_claim MCP handler behavior).
@@ -780,6 +937,7 @@ export function createCoordinatorClaim(options) {
             created_at: nowISO(),
             status: 'active',
             worktree_path: worktreePath,
+            ...baseline, // pln#636 C0-b / trp#1292 — dispatched lanes need it most
         }, options.cwd);
         return { claimId, worktreePath, worktreeWarning, reusedExisting: false };
     });

package/dist/core/facade-schema.js

@@ -167,6 +167,26 @@ export const NextActionSchema = z.object({
     /** When this action applies, e.g. "when implementation is complete". */
     when: z.string().optional(),
 });
+/**
+ * pln#635 — structured warning. ADDITIVE sibling of `warnings: string[]`, which
+ * keeps its type and its exact historical contents (the legacy string is
+ * derived from this record — see core/warnings.ts). Five handler sites were
+ * already encoding structure into a string via JSON.stringify because there was
+ * nowhere else to put it; this is that nowhere.
+ *
+ * `next_actions` is what the string channel could never carry: the recovery
+ * path. A warning an agent cannot act on is just noise it learns to skip.
+ */
+export const WarningDetailSchema = z.object({
+    /** Stable machine-readable identifier, e.g. "scope_already_claimed". */
+    code: z.string(),
+    /** Human-readable prose. Also the legacy string for non-JSON codes. */
+    message: z.string(),
+    /** Structured payload (ids, agents, scopes) the prose mentions. */
+    data: z.record(z.string(), z.unknown()).optional(),
+    /** How to resolve it — same contract as the response-level next_actions. */
+    next_actions: z.array(NextActionSchema).optional(),
+});
 export const FacadeResponseSchema = z.object({
     status: z.enum(['ok', 'error', 'partial']),
     intent: z.string(),
@@ -222,6 +242,18 @@ export const FacadeResponseSchema = z.object({
      * remains for the bootstrap hint; new consumers should read this array.
      */
     next_actions: z.array(NextActionSchema).optional(),
+    /**
+     * pln#635 — structured warnings carrying a stable `code`, the `data` the prose
+     * refers to, and the recovery `next_actions`. Optional and additive:
+     * `warnings` keeps byte-identical contents, so a consumer ignoring this field
+     * is unaffected.
+     *
+     * This is a structured **SUBSET**, not a mirror — `warnings` remains the
+     * complete channel (see core/warnings.ts for why: handlers thread the string
+     * array into helpers by reference). Read `warnings` for completeness; read
+     * `warning_details` for the codes that carry a recovery path.
+     */
+    warning_details: z.array(WarningDetailSchema).optional(),
     /**
      * Code Map P0 (spec §10): opt-in, present ONLY when the project's Code Map
      * manifest carries `code_map_enabled: true`. Absent for every project that

package/dist/core/guidance-telemetry.js

@@ -0,0 +1,197 @@
+/**
+ * pln#634 PR2 — guidance adherence telemetry.
+ *
+ * brainclaw emits `next_actions` and `warning_details[].next_actions` on more and
+ * more surfaces (PR1, pln#635) but has never measured whether an agent's NEXT
+ * call follows the suggestion. Without that number the whole guidance backlog
+ * (pln#636/#637/#638) is prioritised on opinion: we cannot tell "the signal is
+ * missing" from "the signal is ignored", and those two diagnoses have opposite
+ * remedies — add more channels vs. stop adding channels and converge state
+ * server-side instead.
+ *
+ * MECHANISM. `executeMcpToolCall` is the single seam every MCP call passes
+ * through. After a response is built we remember which tools it suggested; on
+ * the next call in the same session we compare. One observation per
+ * suggestion→call pair.
+ *
+ * WHAT IS RECORDED: tool NAMES and a timestamp. Never arguments, never content,
+ * never file paths — the adherence question needs no payload, and a telemetry
+ * file that accumulated payloads would become a redaction problem
+ * (trp_0d79711e). This is also why it is safe to keep on by default.
+ *
+ * COST. Observations accumulate in memory and flush in batches, so a session of
+ * N calls costs ~N/BATCH writes rather than N. No daemon, no store mutation, no
+ * journal noise: the file lives beside the other machine-local runtime
+ * artifacts (ack/log sentinels).
+ *
+ * Opt out with `BRAINCLAW_GUIDANCE_TELEMETRY=0` (also false/off/no).
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { MEMORY_DIR } from './io.js';
+const TELEMETRY_FILE = 'guidance-adherence.jsonl';
+/** Flush every N observations — bounds writes without risking much on a crash. */
+const FLUSH_EVERY = 20;
+/** Rotate past this size so the file cannot grow without bound. */
+const MAX_BYTES = 512 * 1024;
+/** Per-session pending suggestion. Process-scoped: one MCP server per connection. */
+const pending = new Map();
+/** Buffered observations awaiting flush, keyed by target store cwd. */
+const buffered = new Map();
+function enabled() {
+    const raw = process.env.BRAINCLAW_GUIDANCE_TELEMETRY?.trim().toLowerCase();
+    return !(raw === '0' || raw === 'false' || raw === 'off' || raw === 'no');
+}
+function sessionKey(sessionId) {
+    return sessionId?.trim() || 'no-session';
+}
+/**
+ * Pull suggested tool names out of a built response.
+ *
+ * Deliberately a SHALLOW scan of the two places affordances actually live —
+ * top level (handlers that spread fields into `toolResponse`) and
+ * `structuredContent` (facade responses) — plus the per-warning nests. A deep
+ * recursive walk would cost more than the signal is worth and would pick up
+ * unrelated `next_actions` echoed inside payload data.
+ */
+export function extractSuggestedTools(response) {
+    if (!response || typeof response !== 'object')
+        return [];
+    const tools = [];
+    const collect = (value) => {
+        if (!Array.isArray(value))
+            return;
+        for (const entry of value) {
+            if (entry && typeof entry === 'object' && typeof entry.tool === 'string') {
+                tools.push(entry.tool);
+            }
+        }
+    };
+    const collectWarningNests = (value) => {
+        if (!Array.isArray(value))
+            return;
+        for (const entry of value) {
+            if (entry && typeof entry === 'object')
+                collect(entry.next_actions);
+        }
+    };
+    const top = response;
+    collect(top.next_actions);
+    collectWarningNests(top.warning_details);
+    const structured = top.structuredContent;
+    if (structured && typeof structured === 'object') {
+        const inner = structured;
+        collect(inner.next_actions);
+        collectWarningNests(inner.warning_details);
+    }
+    return [...new Set(tools)];
+}
+/**
+ * Observe a tool call against the suggestion left by the previous call.
+ *
+ * Returns the observation (for tests) or undefined when there was nothing
+ * pending. Consuming the pending entry is intentional: one suggestion set is
+ * judged exactly once, by the call that immediately follows it.
+ */
+export function observeToolCall(input) {
+    if (!enabled())
+        return undefined;
+    const key = sessionKey(input.sessionId);
+    const prior = pending.get(key);
+    if (!prior)
+        return undefined;
+    pending.delete(key);
+    const observation = {
+        at: input.now ?? new Date().toISOString(),
+        suggested_by: prior.suggestedBy,
+        suggested: prior.suggested,
+        called: input.tool,
+        followed: prior.suggested.includes(input.tool),
+    };
+    const list = buffered.get(input.cwd) ?? [];
+    list.push(observation);
+    buffered.set(input.cwd, list);
+    if (list.length >= FLUSH_EVERY)
+        flushAdherence(input.cwd);
+    return observation;
+}
+/** Remember what a response suggested, so the next call can be judged. */
+export function recordSuggestion(input) {
+    if (!enabled())
+        return;
+    const key = sessionKey(input.sessionId);
+    if (input.suggested.length === 0) {
+        // No suggestion means nothing to judge — clear rather than leave a stale
+        // set that a later call would be measured against unfairly.
+        pending.delete(key);
+        return;
+    }
+    pending.set(key, { suggestedBy: input.tool, suggested: input.suggested });
+}
+function telemetryPath(cwd) {
+    return path.join(cwd, MEMORY_DIR, 'coordination', 'runtime', TELEMETRY_FILE);
+}
+/** Write buffered observations. Best-effort by construction: never throws. */
+export function flushAdherence(cwd) {
+    const list = buffered.get(cwd);
+    if (!list || list.length === 0)
+        return;
+    buffered.set(cwd, []);
+    try {
+        const file = telemetryPath(cwd);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        try {
+            if (fs.statSync(file).size > MAX_BYTES) {
+                // Keep the newest half; adherence is a trend, not an archive.
+                const kept = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+                fs.writeFileSync(file, kept.slice(Math.floor(kept.length / 2)).join('\n') + '\n', 'utf-8');
+            }
+        }
+        catch { /* absent file — nothing to rotate */ }
+        fs.appendFileSync(file, list.map((o) => JSON.stringify(o)).join('\n') + '\n', 'utf-8');
+    }
+    catch {
+        /* telemetry must never break a tool call */
+    }
+}
+/** Read the recorded observations and summarise. Never throws. */
+export function readAdherence(cwd) {
+    let persisted = [];
+    try {
+        persisted = fs.readFileSync(telemetryPath(cwd), 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        /* absent or unreadable — an empty history, not an error */
+    }
+    // Include anything still buffered so a read right after a call is not stale.
+    const observations = [...persisted, ...(buffered.get(cwd) ?? [])];
+    const followed = observations.filter((o) => o.followed).length;
+    const perTool = new Map();
+    for (const o of observations) {
+        const entry = perTool.get(o.suggested_by) ?? { total: 0, followed: 0 };
+        entry.total += 1;
+        if (o.followed)
+            entry.followed += 1;
+        perTool.set(o.suggested_by, entry);
+    }
+    return {
+        total: observations.length,
+        followed,
+        ignored: observations.length - followed,
+        ...(observations.length > 0 ? { rate: followed / observations.length } : {}),
+        by_tool: [...perTool.entries()]
+            .map(([tool, v]) => ({ tool, total: v.total, followed: v.followed, rate: v.followed / v.total }))
+            .sort((a, b) => a.rate - b.rate),
+    };
+}
+/** Test hook — the maps are process-scoped by design. */
+export function __resetAdherenceForTests() {
+    pending.clear();
+    buffered.clear();
+}
+//# sourceMappingURL=guidance-telemetry.js.map

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

@@ -103,17 +103,45 @@ export function closeIdeationLoopFromLaneResult(assignment, lane, actor, cwd) {
                 // 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]
+                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: 'bare critic lane → slot failed; critique gate unchanged', loop_status: getLoop(loopId, cwd)?.status };
+                    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 };
                 }
-                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);
+                // 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;
             },
         });
     }

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/verbs.js

@@ -39,6 +39,31 @@ function isVerdictAccepted(artifact) {
     const body = (artifact.body ?? '').trim().toLowerCase();
     return /^accepted(?:\b|[:\s])/.test(body);
 }
+/**
+ * pln#639 BUG-1 — does this artifact carry anything a reader could USE?
+ *
+ * `body` is optional in both the input schema (loops/facade-schema.ts) and
+ * `LoopArtifactSchema`, so `{phase, type}` alone is schema-valid. Without this
+ * predicate such an artifact counted toward `min_artifacts_by_type`, which means
+ * a phase gate — the mechanism whose entire job is to prove the phase produced
+ * real work — could be opened by producing nothing at all.
+ *
+ * THE INVARIANT ALREADY EXISTED, one layer too low. `ideationReducer` states it
+ * verbatim: "a bare summary with no critique body → slot failed, gate stays shut
+ * (correct: no fake progress from a lane that produced no critiques)". That guard
+ * only covers the LANE-RESULT reducer path; a direct `add_artifact` /
+ * `complete_turn` MCP call bypassed it entirely. Enforcing it in the evaluator
+ * makes it hold for every entry path.
+ *
+ * A `ref` counts as content: ref-based artifacts legitimately carry no inline
+ * body (the payload lives in the referenced entity), so the rule is "no usable
+ * content" — NOT "body required", which would break them.
+ */
+function hasUsableContent(artifact) {
+    if ((artifact.body ?? '').trim().length > 0)
+        return true;
+    return artifact.ref !== undefined;
+}
 export function evaluateStopCondition(thread, condition) {
     if (!condition)
         return false;
@@ -65,6 +90,9 @@ export function evaluateStopCondition(thread, condition) {
             const matches = thread.artifacts.filter((artifact) => {
                 if (artifact.type !== condition.type)
                     return false;
+                // pln#639 BUG-1 — an artifact with no usable content never counts.
+                if (!hasUsableContent(artifact))
+                    return false;
                 if (condition.scope === 'phase') {
                     if (artifact.phase !== thread.current_phase)
                         return false;
@@ -125,6 +153,11 @@ function describeUnmetGate(thread, gate) {
             const matches = thread.artifacts.filter((artifact) => {
                 if (artifact.type !== gate.type)
                     return false;
+                // pln#639 BUG-1 — same content filter as the evaluator, for the same
+                // reason the iteration filter is mirrored here: a message reporting a
+                // count the evaluator never saw sends the operator hunting a phantom.
+                if (!hasUsableContent(artifact))
+                    return false;
                 if (gate.scope === 'phase') {
                     if (artifact.phase !== thread.current_phase)
                         return false;
@@ -137,7 +170,13 @@ function describeUnmetGate(thread, gate) {
                 }
                 return true;
             });
-            return `min_artifacts_by_type unmet: ${gate.scope}-scope count of type "${gate.type}" = ${matches.length} < n=${gate.n}`;
+            // Name the empty-artifact case explicitly: "count = 2 < n = 3" is baffling
+            // when the operator can see three artifacts of the right type in the thread.
+            const emptyOfType = thread.artifacts.filter((a) => a.type === gate.type && !hasUsableContent(a)).length;
+            const emptyNote = emptyOfType > 0
+                ? ` (${emptyOfType} artifact(s) of this type carry no usable content and do not count)`
+                : '';
+            return `min_artifacts_by_type unmet: ${gate.scope}-scope count of type "${gate.type}" = ${matches.length} < n=${gate.n}${emptyNote}`;
         }
         case 'phase_reached':
             return `phase_reached unmet: current_phase="${thread.current_phase}" expected="${gate.phase}"`;