brainclaw 1.18.0 → 1.19.0

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}"`;

package/dist/core/next-actions.js

@@ -0,0 +1,157 @@
+/**
+ * Verifying a spawned worker: always `bclaw_dispatch_status`, never
+ * `bclaw_find(agent_run)` + a pid check. On Windows an ack-wrapped spawn runs
+ * under cmd.exe, so `agent_run.pid` is the wrapper (which exits by design) and
+ * reads dead while the worker is alive (trp_7fc3e3c4). `dispatch_status`
+ * returns a sentinel-based verdict instead.
+ */
+export function verifyDispatchAction(targetId, note) {
+    return {
+        tool: 'bclaw_dispatch_status',
+        args: { target_id: targetId },
+        when: note
+            ? `${note} — sentinel-based liveness verdict (do NOT judge from agent_run.pid)`
+            : 'verify the spawned worker is actually alive — sentinel-based verdict (do NOT judge from agent_run.pid)',
+    };
+}
+/** Cap on repeated per-target actions, so a wide fan-out cannot flood the field. */
+const FANOUT_CAP = 3;
+function verifyActions(targetIds, note) {
+    const shown = targetIds.slice(0, FANOUT_CAP);
+    const actions = shown.map((id) => verifyDispatchAction(id, note));
+    if (targetIds.length > shown.length) {
+        // Say what was dropped rather than silently truncating.
+        actions.push({
+            tool: 'bclaw_dispatch_status',
+            args: { target_id: '<one of the remaining targets>' },
+            when: `${targetIds.length - shown.length} further target(s) were dispatched — verify each one the same way`,
+        });
+    }
+    return actions;
+}
+/**
+ * After a release, the follow-up depends entirely on what the cascade decided:
+ * a blocked plan transition needs the other claim holders inspected, a
+ * completed plan is ready for review, and a plain release has no next step at
+ * all.
+ */
+export function releaseClaimNextActions(outcome) {
+    const actions = [];
+    if (outcome.planWarning && outcome.planId) {
+        // The cascade refused: other claims still hold the plan. Both the diagnosis
+        // and the eventual manual transition are real MCP calls.
+        actions.push({
+            tool: 'bclaw_find',
+            args: { entity: 'claim', filter: { plan_id: outcome.planId, status: 'active' } },
+            when: 'the plan was NOT transitioned because other claims are still active — see who else holds it',
+        });
+        actions.push({
+            tool: 'bclaw_transition',
+            args: { entity: 'plan', id: outcome.planId, to: outcome.requestedPlanStatus ?? 'done' },
+            when: 'once the other claims are released, transition the plan yourself',
+        });
+        return actions;
+    }
+    if (outcome.planTransitioned && outcome.planId) {
+        // Documented workflow: implement → release → review.
+        actions.push({
+            tool: 'bclaw_coordinate',
+            args: {
+                intent: 'review',
+                task: `Review the work delivered under plan ${outcome.planId}`,
+                open_loop: true,
+            },
+            when: 'the plan is done — the next workflow stage is review',
+        });
+    }
+    return actions;
+}
+/**
+ * Only two transitions imply an unambiguous next call. Everything else
+ * (candidate accepted, plan done, trap retired, …) is terminal for the caller,
+ * so it returns nothing rather than inventing busywork.
+ */
+export function transitionNextActions(outcome) {
+    if (outcome.entity === 'plan' && outcome.to === 'in_progress') {
+        return [{
+                tool: 'bclaw_work',
+                args: { intent: 'execute', planId: outcome.id, scope: '<scope you are about to edit>' },
+                when: 'the plan is in progress — claim the scope before editing',
+            }];
+    }
+    if (outcome.entity === 'plan' && outcome.to === 'blocked') {
+        return [{
+                tool: 'bclaw_quick_capture',
+                args: { text: '<what blocks this plan>', type: 'trap' },
+                when: 'record WHY it is blocked so the next agent does not rediscover it',
+            }];
+    }
+    return [];
+}
+/**
+ * Coordinate's follow-up is driven by whether anything actually spawned, not by
+ * the intent alone: the same `intent='assign'` needs verification when it
+ * spawned and nothing MCP-callable when it produced manual commands.
+ */
+export function coordinateNextActions(outcome) {
+    const actions = [];
+    const spawned = outcome.executionStatus === 'delivered_and_started';
+    if (spawned && outcome.assignmentIds.length > 0) {
+        actions.push(...verifyActions(outcome.assignmentIds));
+    }
+    if (outcome.loopId) {
+        actions.push({
+            tool: 'bclaw_loop',
+            args: { intent: 'get', loop_id: outcome.loopId },
+            when: spawned
+                ? 'inspect loop state — its `next_expected` names the turn the loop is waiting on'
+                : 'the loop is open but nothing spawned — inspect it and drive the turn yourself',
+        });
+    }
+    // Manual-handoff spawning intents: the launch commands are in the text body
+    // (not MCP-callable), so the only real MCP follow-up is verification AFTER
+    // the operator runs them.
+    if (!spawned && outcome.executionStatus === 'command_ready_manual' && outcome.assignmentIds.length > 0) {
+        actions.push(verifyActions(outcome.assignmentIds, 'once you have run the launch command(s) printed above')[0]);
+    }
+    return actions;
+}
+export function dispatchNextActions(outcome) {
+    if (outcome.dryRun) {
+        return [{
+                tool: 'bclaw_dispatch',
+                args: { intent: 'execute' },
+                when: 'this was a dry run — nothing was dispatched; re-run without dryRun to actually spawn',
+            }];
+    }
+    const actions = [];
+    if (outcome.spawnedTargets.length > 0) {
+        actions.push(...verifyActions(outcome.spawnedTargets));
+    }
+    if (outcome.blockedCount > 0) {
+        actions.push({
+            tool: 'bclaw_dispatch',
+            args: { intent: 'analysis' },
+            when: `${outcome.blockedCount} lane(s) are blocked — analysis explains which gate holds each one`,
+        });
+    }
+    return actions;
+}
+export function createEntityNextActions(outcome) {
+    if (outcome.entity === 'plan') {
+        return [{
+                tool: 'bclaw_add_step',
+                args: { planId: outcome.id, data: { text: '<first unit of work>' } },
+                when: 'break the plan into steps so progress is trackable',
+            }];
+    }
+    if (outcome.entity === 'sequence') {
+        return [{
+                tool: 'bclaw_dispatch',
+                args: { intent: 'analysis' },
+                when: 'inspect lane readiness before dispatching the sequence',
+            }];
+    }
+    return [];
+}
+//# sourceMappingURL=next-actions.js.map

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

@@ -1,9 +1,19 @@
 import { getLoop } from './loops/store.js';
 import { complete_turn, advance } from './loops/verbs.js';
 import { withLoopLock } from './loops/lock.js';
+import { LOOP_ARTIFACT_BODY_MAX_BYTES } from './loops/types.js';
 /** review-loop:lop_xxx → the loop id (mirrors assignment-reconciler.ts). */
 const REVIEW_LOOP_SCOPE_RE = /^review-loop:(lop_[0-9a-z]+)/;
 const LOOP_TERMINAL = new Set(['completed', 'cancelled', 'blocked']);
+/** Keep the loop-facing verdict valid while the full worker body stays durable in harvest metadata. */
+function capVerdictBody(prefix, detail) {
+    const full = `${prefix}${detail ? `: ${detail}` : ''}`;
+    if (Buffer.byteLength(full, 'utf8') <= LOOP_ARTIFACT_BODY_MAX_BYTES)
+        return full;
+    const marker = '…[truncated; full body retained in lane harvest event]';
+    const room = LOOP_ARTIFACT_BODY_MAX_BYTES - Buffer.byteLength(prefix, 'utf8') - Buffer.byteLength(': ', 'utf8') - Buffer.byteLength(marker, 'utf8');
+    return `${prefix}: ${Buffer.from(detail, 'utf8').subarray(0, Math.max(0, room)).toString('utf8').replace(/�+$/, '')}${marker}`;
+}
 /** Build the fix+re-review brief for a request_changes cycle turn (symmetric).
  *  Exported so the turn-owned reconcile path (pln#630 PR3b) reuses the identical
  *  wording — the reviewer contract must not drift between the legacy and turn-owned
@@ -78,14 +88,21 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                     return noop(`loop already ${loop.status}`, loop.status);
                 const slot = resolveReviewerSlot(loop, assignment);
                 const acceptedVerdictExists = loop.artifacts.some(isAcceptedVerdict);
-                const summary = (lane.review_summary ?? '').trim();
+                const detail = (lane.body ?? lane.review_summary ?? '').trim();
                 // ── approve → close on reviewer_green ───────────────────────────────
                 if (verdict === 'approve') {
                     if (slot) {
                         // isVerdictAccepted fires reviewer_green ONLY on an "accepted…" body.
                         complete_turn({
                             id: loopId, slot_id: slot.slot_id, actor,
-                            artifact: { phase: loop.current_phase, type: 'verdict', body: `accepted${summary ? `: ${summary}` : ''}` },
+                            // pln#639 BUG-2 — the phase the slot was DISPATCHED in, not the
+                            // loop's phase at close time. Same defect as the ideation closer;
+                            // fixed here too because this is the far more travelled path.
+                            // Safe for the approve flow: `reviewer_green` scans every artifact
+                            // via isVerdictAccepted regardless of phase, and no gate in the
+                            // engine keys on `type: 'verdict'` — so this changes attribution
+                            // truth without changing a single gate outcome.
+                            artifact: { phase: slot.phase ?? loop.current_phase, type: 'verdict', body: capVerdictBody('accepted', detail) },
                         }, cwd);
                     }
                     else if (!acceptedVerdictExists) {
@@ -130,7 +147,8 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                 const symmetric = loop.protocol?.review_mode === 'symmetric';
                 complete_turn({
                     id: loopId, slot_id: slot.slot_id, actor,
-                    artifact: { phase: loop.current_phase, type: 'verdict', body: `changes-requested${summary ? `: ${summary}` : ''}` },
+                    // pln#639 BUG-2 — dispatch phase, not close-time phase (see above).
+                    artifact: { phase: slot.phase ?? loop.current_phase, type: 'verdict', body: capVerdictBody('changes-requested', detail) },
                 }, cwd);
                 if (!symmetric) {
                     const advancedAsym = advance({ id: loopId, actor }, cwd);
@@ -174,7 +192,7 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                         agent_id: slot.agent_id,
                         phase: advanced.loop.current_phase,
                         iteration: advanced.loop.iteration_count,
-                        task: buildFixCycleTask(summary, advanced.loop.iteration_count),
+                        task: buildFixCycleTask(detail, advanced.loop.iteration_count),
                     },
                 };
             },