brainclaw 1.19.1 → 1.20.0

package/dist/commands/mcp-write-claims.js

@@ -12,11 +12,9 @@
  *
  * @module
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import { getTriggeredItems, renderTriggeredItems } from '../core/lifecycle.js';
 import { buildContext } from '../core/context.js';
-import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
+import { checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
 import { generateClaimId, loadClaim, saveClaim, adoptClaimSession, releaseClaimWithCascade, claimBaselineFields } from '../core/claims.js';
 import { releaseClaimNextActions } from '../core/next-actions.js';
@@ -346,24 +344,14 @@ export async function handleBclawSessionStart(payload, ctx) {
     const sessionUpdateConfig = loadConfig(cwd);
     const sessionUpdateCheck = checkBrainclawInstallableUpdate(sessionUpdateConfig, cwd, { useDefaultNpmSource: true });
     const sessionUpdateNotice = renderBrainclawInstallableUpdateNotice(sessionUpdateCheck);
-    // Stale instructions guardrail: check if agent files match current version
-    let staleInstructionsWarn = '';
-    {
-        const currentVersion = getInstalledBrainclawVersion();
-        const agentFilesToCheck = ['CLAUDE.md', 'AGENTS.md', '.github/copilot-instructions.md'];
-        for (const relPath of agentFilesToCheck) {
-            try {
-                const fullPath = path.join(cwd, relPath);
-                const content = fs.readFileSync(fullPath, 'utf-8').slice(0, 200);
-                const match = content.match(/brainclaw v(\d+\.\d+\.\d+)/);
-                if (match && match[1] !== currentVersion) {
-                    staleInstructionsWarn = `\n⚠️ Agent instruction files are stale (generated by v${match[1]}, current is v${currentVersion}). Run: brainclaw export --all`;
-                    break;
-                }
-            }
-            catch { /* file doesn't exist, skip */ }
-        }
-    }
+    // Stale-surfaces advisory. This REPLACES a hand-rolled guardrail that lived
+    // here: a regex over the first 200 chars of 3 hardcoded files. That was a
+    // second, divergent freshness check running next to the proper one — the same
+    // dual-source drift class as the two LANE-RESULT shapes (pln#638 PR-4). The
+    // pln#638 2b reconcile in startSession covers ~25 registry-derived paths with
+    // a real parser; its result was computed by this very call and then dropped
+    // from the response (Fable audit P0.2). Now it IS the guardrail.
+    const staleInstructionsWarn = result.stale_surfaces ? `\n⚠️ ${result.stale_surfaces.message}` : '';
     // Claim adoption: if BRAINCLAW_CLAIM_ID is set (spawned by dispatcher),
     // adopt the claim by writing session_id into it. This links claim→session.
     let adoptedClaimId;
@@ -383,6 +371,10 @@ export async function handleBclawSessionStart(payload, ctx) {
     }
     if (adoptedClaimId)
         sessionStartMsgParts.push(`\n🔗 Adopted claim ${adoptedClaimId} — use bclaw_read_inbox with claimId to see your assignment.`);
+    if (result.shared_checkout_warning) {
+        const others = result.shared_checkout_warning.other_sessions.map((s) => s.agent).join(', ');
+        sessionStartMsgParts.push(`\n⚠️ Shared checkout: ${others} also working in this worktree — claim your scope before editing.`);
+    }
     if (staleInstructionsWarn)
         sessionStartMsgParts.push(staleInstructionsWarn);
     if (sessionUpdateNotice)
@@ -410,6 +402,15 @@ export async function handleBclawSessionStart(payload, ctx) {
         inbox_pending: inboxPending,
         ...(result.auto_registered ? { auto_registered: true } : {}),
         ...(result.memory_pressure ? { memory_pressure: result.memory_pressure } : {}),
+        // pln#638 2b — the field startSession computes; it was previously dropped
+        // here, making the whole feature reachable only via CLI --json.
+        ...(result.stale_surfaces
+            ? { warnings: [result.stale_surfaces.message], warning_details: [result.stale_surfaces] }
+            : {}),
+        // Fifth computed-then-dropped field, caught by the seam guard: other live
+        // sessions on the same checkout. An agent about to edit needs this more
+        // than a human does.
+        ...(result.shared_checkout_warning ? { shared_checkout_warning: result.shared_checkout_warning } : {}),
     };
     if (args.includeContext) {
         const contextAgent = resolved.identity?.agent_name ?? result.agent;
@@ -502,6 +503,13 @@ export async function handleBclawSessionEnd(payload, ctx) {
         parts.push(endUpdateNotice);
     if (preSessionEndText)
         parts.push(preSessionEndText);
+    // pln#636 C2 session-end sweep — the backstop trigger. endSession computed
+    // these and this handler dropped them (Fable audit P1): of the four C2
+    // boundaries, this one emitted nowhere. Text part + structured channel below.
+    if (result.scope_warnings?.length) {
+        for (const w of result.scope_warnings)
+            parts.push(`\n⚠️ ${w.message}`);
+    }
     if (result.reflection_prompt) {
         parts.push('\n📝 Session reflection — please answer these questions:');
         for (let i = 0; i < result.reflection_prompt.questions.length; i++) {
@@ -519,6 +527,12 @@ export async function handleBclawSessionEnd(payload, ctx) {
             triggered_items: preSessionEndItems,
             ...(result.handoff ? { handoff: result.handoff } : {}),
             ...(result.reflection_prompt ? { reflection_prompt: result.reflection_prompt } : {}),
+            ...(result.scope_warnings?.length
+                ? {
+                    warnings: result.scope_warnings.map((w) => w.message),
+                    warning_details: result.scope_warnings,
+                }
+                : {}),
         }),
         nextConnectionSessionId: null,
     };

package/dist/commands/mcp-write-coordination.js

@@ -626,6 +626,11 @@ export async function handleBclawCoordinate(args, ctx) {
             scope: options?.scope,
             worktreePath: options?.worktreePath,
             assignmentId: options?.assignmentId,
+            // pln#638 PR-6b — the envelope must read the TARGET project's store: on a
+            // cross-project dispatch, defaulting to process.cwd() would inline the
+            // WRONG project's constraints/traps into the worker's brief.
+            cwd: dispatchCwd,
+            contextEnvelope: options?.contextEnvelope,
         });
     };
     const toMessageSummary = (deliveryPlan) => deliveryPlan.map((entry) => ({
@@ -1750,6 +1755,12 @@ export async function handleBclawCoordinate(args, ctx) {
                                 scope: criticScope,
                                 worktreePath: claimResult.worktreePath,
                                 assignmentId: criticAssignmentId,
+                                // The ideation brief above already inlines a BM25-selected,
+                                // budget-managed memory bundle (with its own truncation warning).
+                                // The generic context envelope would double-carry the same traps
+                                // and break the documented ~48K content cap + dispatch-envelope
+                                // math pinned by ideation-loop-e2e.
+                                contextEnvelope: false,
                             });
                             const queued = queueCoordinateMessage({
                                 agent: slot.agent,

package/dist/commands/mcp.js

@@ -1238,6 +1238,9 @@ async function _executeMcpToolCallInner(payload) {
             const targetCwd = resolveProjectCwd(workReq.project, cwd);
             const useCompact = workReq.compact !== false; // default true
             const warnings = [];
+            // pln#635 structured channel — populated alongside `warnings` and attached
+            // to the response only when non-empty.
+            const warningDetails = [];
             // Step 1: implicit session start (handles auto-registration internally)
             let sessionResult;
             try {
@@ -1254,6 +1257,21 @@ async function _executeMcpToolCallInner(payload) {
             if (sessionResult.auto_registered) {
                 warnings.push(`Agent '${sessionResult.agent}' was auto-registered (first use). Run \`brainclaw register-agent ${sessionResult.agent}\` to set capabilities and trust level.`);
             }
+            // pln#638 2b — surface the stale-surfaces advisory on the CANONICAL entry
+            // point. Until the Fable audit, bclaw_work could never even compute this
+            // (startSession defaulted to 'fast' and the check was gated on 'full'),
+            // so the feature shipped in 1.19.0 unreachable from the one call the
+            // session protocol tells every agent to make first.
+            if (sessionResult.stale_surfaces) {
+                warnings.push(sessionResult.stale_surfaces.message);
+                warningDetails.push(sessionResult.stale_surfaces);
+            }
+            // Same seam, same fix: other live sessions on this checkout is exactly
+            // what an agent entering via bclaw_work must hear before it edits.
+            if (sessionResult.shared_checkout_warning) {
+                const others = sessionResult.shared_checkout_warning.other_sessions.map((s) => s.agent).join(', ');
+                warnings.push(`Shared checkout: ${others} also working in ${sessionResult.shared_checkout_warning.worktree_path} — claim your scope before editing.`);
+            }
             // Step 2: build context for requested scope. The "what's new" diff is
             // surfaced for ALL intents (pln#390 regression fix): intent='resume'
             // anchors it on the agent's previous session; every other intent gets
@@ -1530,6 +1548,7 @@ async function _executeMcpToolCallInner(payload) {
                 claim_status: claimStatus,
                 session_id: sessionResult.session_id,
                 warnings,
+                ...(warningDetails.length ? { warning_details: warningDetails } : {}),
                 duration_ms: Date.now() - startMs,
                 bootstrap_recommended: bootstrapRecommended,
                 bootstrap_verdict: bootstrapVerdict,

package/dist/commands/session-end.js

@@ -107,6 +107,13 @@ export async function runSessionEnd(options = {}) {
         if (result.compaction_hint) {
             console.log(`  💡 ${result.compaction_hint}`);
         }
+        // pln#636 C2 backstop — computed since 1.19.0, printed nowhere until the
+        // Fable audit (P1): the human output skipped it, so it was --json only.
+        if (result.scope_warnings?.length) {
+            for (const w of result.scope_warnings) {
+                console.warn(`⚠ ${w.message}`);
+            }
+        }
         if (result.reflection_prompt) {
             console.log('\n📝 Session reflection:');
             for (let i = 0; i < result.reflection_prompt.questions.length; i++) {

package/dist/commands/session-start.js

@@ -97,6 +97,21 @@ export async function runSessionStart(options = {}) {
                 console.warn(`  ${c.agent} → ${c.scope}`);
             }
         }
+        // pln#638 2b, wired for humans too (Fable audit P0.3): the field existed on
+        // the result but the human output never printed it — visible only via --json.
+        if (snapshot.stale_surfaces) {
+            console.warn(`⚠ ${snapshot.stale_surfaces.message}`);
+        }
+        // Fifth instance of the computed-then-dropped class, caught by the new seam
+        // guard on its first run: built since the shared-checkout detection landed,
+        // read by nothing. Two agents editing one checkout is precisely what a human
+        // at the terminal needs to hear about.
+        if (snapshot.shared_checkout_warning) {
+            const others = snapshot.shared_checkout_warning.other_sessions
+                .map((s) => `${s.agent} (${s.session_id}${s.branch ? `, ${s.branch}` : ''})`)
+                .join(', ');
+            console.warn(`⚠ Shared checkout: ${others} ${snapshot.shared_checkout_warning.other_sessions.length === 1 ? 'is' : 'are'} also working in ${snapshot.shared_checkout_warning.worktree_path}. Claim your scope before editing.`);
+        }
     }
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
@@ -291,15 +306,20 @@ export async function startSession(options = {}) {
     // daemon, no watcher (feedback_lazy_reconcile_pattern). Advisory only: nothing
     // is regenerated here, because regeneration is an explicit act and silently
     // rewriting a file the operator may have edited would be worse than a warning.
+    // NOT gated on maintenanceMode — deliberately, and this is a fix, not an
+    // oversight (Fable audit P0). The check is ~25 existsSync + a few 4KB head
+    // reads, nothing like the sweeps/federation/GC that justify the 'full' gate.
+    // Gating it on 'full' made it unreachable from `bclaw_work`, which calls
+    // startSession without maintenanceMode (→ 'fast') and is the entry point the
+    // session protocol tells every agent to use — so the warning shipped in
+    // 1.19.0 and never fired for the population it was built for.
     let staleSurfaces;
-    if (maintenanceMode === 'full') {
-        try {
-            const currentVersion = getInstalledBrainclawVersion();
-            const freshness = reconcileSurfaceFreshness(options.cwd ?? process.cwd(), currentVersion);
-            staleSurfaces = staleSurfaceWarning(freshness, currentVersion);
-        }
-        catch { /* non-fatal */ }
+    try {
+        const currentVersion = getInstalledBrainclawVersion();
+        const freshness = reconcileSurfaceFreshness(options.cwd ?? process.cwd(), currentVersion);
+        staleSurfaces = staleSurfaceWarning(freshness, currentVersion);
     }
+    catch { /* non-fatal */ }
     // Materialize incoming federation signals from linked projects (Phase 0 — local)
     if (maintenanceMode === 'full') {
         try {

package/dist/commands/watch.js

@@ -4,7 +4,7 @@ import { loadState } from '../core/state.js';
 import { listRuntimeNotes } from '../core/runtime.js';
 import { listCandidates } from '../core/candidates.js';
 import { readAuditLog } from '../core/audit.js';
-import { listClaims, saveClaim, generateClaimId, ensureClaimsDir } from '../core/claims.js';
+import { listClaims, saveClaim, generateClaimId, ensureClaimsDir, claimBaselineFields } from '../core/claims.js';
 import { resolveCurrentAgentName } from '../core/agent-registry.js';
 function emit(event) {
     process.stdout.write(JSON.stringify(event) + '\n');
@@ -197,6 +197,11 @@ export function runWatch(options = {}) {
                     description: `auto-claim: ${filename}`,
                     created_at: new Date().toISOString(),
                     status: 'active',
+                    // pln#636 C0-b / trp#1292 — the FIFTH creation path, missed by the
+                    // 1.19.1 fix and invisible to its guard test: this one assigns the
+                    // literal to a variable, so a scan looking for `saveClaim({` never saw
+                    // it. Found by the ideation critic that reviewed the guard.
+                    ...claimBaselineFields(),
                 };
                 try {
                     saveClaim(claim);

package/dist/core/dispatcher.js

@@ -326,6 +326,88 @@ export function buildWorkingDefaultsSection(opts) {
         '',
     ].join('\n');
 }
+/**
+ * pln#638 PR-4 — the transport section, for BOTH declared-MCP and MCP-less agents.
+ *
+ * WHY THIS EXISTS AS ONE FUNCTION. The MCP-less block was duplicated verbatim in
+ * `generateBrief` and `generateDispatchBrief`; that duplication is exactly what
+ * lets two brief paths drift, which is the class of bug PR-3 just fixed one layer
+ * up. One function, two callers.
+ *
+ * WHY A DECLARED-MCP AGENT ALSO GETS A SECTION — the part that was missing. A
+ * profile's `runtime.mcp_direct` is a STATIC flag: it asserts nothing about
+ * whether the config exists on this machine, whether the server started, or
+ * whether stdio came up. Proven in production during pln#638's own ideation: a
+ * codex critic ran with `mcp_direct=true` and NO reachable MCP. Its 3654-character
+ * critique survived only because the brief happened to spell out a file fallback
+ * by hand. So the brief must never ASSERT the capability — it states the
+ * expectation and names the fallback, and the worker decides from what it
+ * actually observes.
+ *
+ * The store path is deliberately NOT mentioned. `.brainclaw/` is gitignored
+ * (.gitignore:10), so it does not exist in a worker's worktree — the previous
+ * wording told workers to write candidates into a directory they cannot see.
+ */
+/**
+ * The ONE LANE-RESULT shape every brief quotes.
+ *
+ * There used to be two. `buildProtocolSection` has emitted a fallback since
+ * pln#526 with `{summary, files_changed, artifacts}` and NO `body`, while the
+ * transport section below asked for `body`. A full-mode worker with an assignment
+ * id received both and had to pick — and a worker that followed the older one
+ * recreated trp_8efdbf9d (a substantial review collapsed into a one-line summary
+ * because the contract had nowhere to put the reasoning). Caught in review by
+ * Fable before this shipped.
+ */
+export function laneResultShape(assignmentId) {
+    const asgn = assignmentId ?? '<assignment_id>';
+    return `{"assignment_id":"${asgn}","status":"completed|blocked|failed","summary":"<one line>","body":"<your full output — the reasoning, not just a label>","files_changed":["..."],"artifacts":["..."]}`;
+}
+export function buildTransportSection(opts) {
+    const laneResult = `write LANE-RESULT.json at the worktree ROOT: ${laneResultShape(opts.assignmentId)}`;
+    if (!opts.hasMcp) {
+        return [
+            '## ⚠ Transport: no MCP (file protocol only)',
+            'Your runtime has no brainclaw MCP access — any `bclaw_*` instruction above does NOT apply to you. Report your outcome via the FILE protocol only; it is authoritative for this run:',
+            `- When done, ${laneResult}.`,
+            // RESTORED after review. Removing this orphaned a real, shipped consumer:
+            // `collectWorktreeCandidateFiles` (harvest.ts:191-205) scans exactly this
+            // directory inside WORKER worktrees, and `bclaw_harvest_candidates` exposes
+            // it. My removal rested on a wrong inference — `.gitignore:10` means the
+            // path is not CHECKED OUT, not that a worker cannot create it. Being
+            // gitignored is the feature: candidates never pollute worker commits.
+            '- Capture decisions/traps as candidate JSON under `.brainclaw/coordination/inbox/` in your worktree — create the directory if it does not exist (it is gitignored, so a fresh worktree will not have it). The coordinator harvests them.',
+            '- Do NOT call bclaw_* tools — they are unavailable here. The coordinator harvests your result and integrates it.',
+            '',
+        ].join('\n');
+    }
+    return [
+        '## Transport: MCP expected, file fallback if not',
+        'Your profile declares brainclaw MCP access, but that is a DECLARATION, not a verified fact — the config may be absent on this machine or the server may not have started. Decide from what you actually observe:',
+        '- If `bclaw_*` tools respond: use them, as instructed above.',
+        `- If they are unavailable or error: do not stop and do not discard your work — ${laneResult}. The coordinator harvests it.`,
+        '',
+    ].join('\n');
+}
+/**
+ * pln#638 PR-6 — lane lifecycle doctrine (settled by loop lop_2d838a638b1e2956):
+ *
+ *   Native hooks = interactive agents. Dispatched workers = dispatcher-owned
+ *   lifecycle. A lane's unit of identity is assignment + claim + AgentRun —
+ *   NEVER a session. Sessions carry interactive side-effects (auto-release
+ *   frees ALL of an agent's claims at session_end) that would leak across
+ *   lanes, and N parallel lanes would contend on the session lock (observed:
+ *   a worker's global hook stalled 5s on a session LOCK, not on a missing
+ *   store).
+ *
+ *   The three lifecycle needs hooks used to cover are met elsewhere:
+ *   - shared context at start  → inlined ContextEnvelope in the brief
+ *     (buildContextEnvelopeSection — MCP is a refresh, not a prerequisite);
+ *   - progress/closure         → bclaw_assignment_update + the wrapper's
+ *     mechanical completed/failed sentinels (see attemptExecution);
+ *   - business closure         → the coordinator's harvest/report path.
+ *     Transport completion never releases claims or triggers review.
+ */
 export function buildProtocolSection(options) {
     const parts = [];
     parts.push('## Protocol');
@@ -395,30 +477,37 @@ export function buildProtocolSection(options) {
         // fails in your environment. pln#628 Focus 4A: sandbox is NO LONGER a reason
         // MCP is unavailable (dec#133), so this is framed as a generic fallback, not a
         // sandbox instruction. The coordinator ingests it with `brainclaw harvest`.
-        parts.push(`Final fallback (if bclaw_assignment_update / MCP is unavailable in your environment): write LANE-RESULT.json at the worktree root — {"assignment_id":"${options.assignmentId}","status":"completed|blocked|failed","summary":"<what you did>","files_changed":["..."],"artifacts":["..."]}. The coordinator harvests it via \`brainclaw harvest ${options.assignmentId}\`.`);
+        // Quotes the SHARED shape (laneResultShape) so this and the transport section
+        // cannot disagree about what a worker should write — they used to.
+        parts.push(`Final fallback (if bclaw_assignment_update / MCP is unavailable in your environment): write LANE-RESULT.json at the worktree root — ${laneResultShape(options.assignmentId)}. The coordinator harvests it via \`brainclaw harvest ${options.assignmentId}\`.`);
     }
     else if (options?.claimId) {
-        parts.push('1. Call bclaw_session_start to register your session');
+        // pln#638 PR-6a — NO session lifecycle in a dispatched lane's brief. The
+        // ideation loop settled this (design of record: pln638-pr6 synthesis): a
+        // session is an AGENT's lifecycle and its effects overflow the lane —
+        // `session-end --auto-release` releases ALL of the agent's active claims and
+        // the handoff aggregates ALL its commits, so one finishing lane could tear
+        // down its siblings' work. The engine already agrees: SESSION_ID is
+        // deliberately scrubbed from the worker env (execution-profile.ts). The
+        // lane's lifecycle is the claim (+ assignment when present), nothing more.
         if (options.worktreePath) {
-            parts.push(`2. cd into the worktree: ${options.worktreePath}`);
+            parts.push(`1. cd into the worktree: ${options.worktreePath}`);
         }
-        parts.push(`${options.worktreePath ? '3' : '2'}. Work on the assigned scope (claim already active)`);
-        parts.push(`${options.worktreePath ? '4' : '3'}. Release the claim: bclaw_release_claim(id: "${options.claimId}", planStatus: "done") — required for hard_after gating to unblock downstream tasks`);
-        parts.push(`${options.worktreePath ? '5' : '4'}. Call bclaw_session_end with a narrative when done`);
+        parts.push(`${options.worktreePath ? '2' : '1'}. Work on the assigned scope (claim already active)`);
+        parts.push(`${options.worktreePath ? '3' : '2'}. Release the claim: bclaw_release_claim(id: "${options.claimId}", planStatus: "done") — required for hard_after gating to unblock downstream tasks`);
+        parts.push('Do NOT call bclaw_session_start / bclaw_session_end: sessions belong to interactive agents, and session-end tears down claims beyond this lane.');
     }
     else {
-        parts.push('1. Call bclaw_session_start to register your session');
-        parts.push('2. Call bclaw_claim to claim the scope before editing');
-        parts.push('3. Work in the worktree created by the claim');
-        parts.push('4. Release the claim when done: bclaw_release_claim(id: "clm_xxx", planStatus: "done") — required for hard_after sequence gating to unlock the next step');
-        parts.push('5. Call bclaw_session_end with a narrative when done');
+        parts.push('1. Call bclaw_claim to claim the scope before editing');
+        parts.push('2. Work in the worktree created by the claim');
+        parts.push('3. Release the claim when done: bclaw_release_claim(id: "clm_xxx", planStatus: "done") — required for hard_after sequence gating to unlock the next step');
+        parts.push('Do NOT call bclaw_session_start / bclaw_session_end: sessions belong to interactive agents, and session-end tears down claims beyond this lane.');
     }
     parts.push('');
     parts.push('## Available tools');
     if (options?.assignmentId) {
         parts.push('- bclaw_assignment_update (report lifecycle: accepted/started/progress/completed/failed/blocked)');
     }
-    parts.push('- bclaw_session_start, bclaw_session_end (session lifecycle)');
     if (!options?.claimId) {
         parts.push('- bclaw_claim, bclaw_release_claim (scope ownership)');
     }
@@ -498,6 +587,10 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     }
     // pln#554 step 4 — working defaults (incremental commits + validation bar).
     parts.push(buildWorkingDefaultsSection({ canCommit: briefProfile ? dispatchCanCommit(briefProfile) : true }));
+    // pln#638 PR-6b — survival context rides in the brief; MCP is a refresh.
+    const envelope = buildContextEnvelopeSection(cwd);
+    if (envelope)
+        parts.push(envelope);
     // Steps if any
     if (plan.steps?.length) {
         parts.push('## Steps');
@@ -566,14 +659,19 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     // call bclaw_*" note: their coherent message is carried by the Protocol section
     // (MCP primary + LANE-RESULT.json fallback) and working-defaults (canCommit=
     // false → the coordinator commits their worktree at harvest).
-    if (briefProfile && !dispatchHasMcp(briefProfile)) {
-        parts.push('## ⚠ Transport: no MCP (file protocol only)');
-        parts.push('Your runtime has no brainclaw MCP access — any `bclaw_*` instruction above does NOT apply to you. Report your outcome via the FILE protocol only; it is authoritative for this run:');
-        const asgn = options?.assignmentId ?? '<assignment_id>';
-        parts.push(`- When done, write LANE-RESULT.json at the worktree root: {"assignment_id":"${asgn}","status":"completed|blocked|failed","summary":"<what you did>","files_changed":["..."]}.`);
-        parts.push('- Capture decisions/traps as candidate JSON under .brainclaw/coordination/inbox/ (the coordinator harvests them).');
-        parts.push('- Do NOT call bclaw_* tools — they are unavailable here. The coordinator harvests your result and integrates it.');
-        parts.push('');
+    // pln#638 PR-4 — emitted for EVERY agent, not only MCP-less ones: a declared-MCP
+    // worker needs the conditional fallback too (see buildTransportSection for the
+    // production incident that proved it).
+    //
+    // An UNRESOLVED profile gets the conditional form rather than silence — review
+    // caught that gating on a truthy profile left an unknown agent with a
+    // fully-MCP-asserting brief and no fallback, which is the case the principle
+    // "never assert an unverifiable capability" exists for.
+    if (options?.agent) {
+        parts.push(buildTransportSection({
+            hasMcp: briefProfile ? dispatchHasMcp(briefProfile) : true,
+            assignmentId: options.assignmentId,
+        }));
     }
     // Codex-specific constraints: focus and speed guidance for sandboxed runs.
     // Gated on agent identity (not brief mode) so future non-codex compact consumers
@@ -586,6 +684,68 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     }
     return parts.join('\n');
 }
+/** Character budget for the inlined context envelope — bounded by design
+ *  (trp#179: oversized payloads), and deliberately small: this is the survival
+ *  kit, not the library. */
+const CONTEXT_ENVELOPE_MAX_CHARS = 3000;
+const CONTEXT_ENVELOPE_ITEM_MAX_CHARS = 220;
+const CONTEXT_ENVELOPE_TOP_K = 6;
+/**
+ * pln#638 PR-6b — the ContextEnvelope: constraints/traps/decisions INLINED into
+ * the dispatch brief, bounded and deterministic.
+ *
+ * Why inline instead of "call bclaw_context": that instruction assumes the MCP
+ * is reachable, and the whole PR-6 design was forced by a production run where
+ * the declared-MCP flag was true and the server was not there (critic A of
+ * lop_2d838a638b1e2956 lost its context channel and worked blind). The brief is
+ * the ONE artifact every tier demonstrably receives — so the survival context
+ * rides in it, and MCP remains an optional refresh, never a precondition.
+ *
+ * Deterministic: newest-first by created_at (tie-broken by id), fixed caps, no
+ * clock reads — the same store state always renders the same envelope.
+ * NOT scope-filtered, deliberately: relevance guessing risks hiding the one
+ * trap that mattered (the inverted-default lesson of claim-scope, applied to
+ * context selection). Bounded instead.
+ */
+export function buildContextEnvelopeSection(cwd) {
+    let state;
+    try {
+        state = loadState(cwd);
+    }
+    catch {
+        return ''; // no store, no envelope — never block a brief on context
+    }
+    const newestFirst = (items) => [...items].sort((a, b) => (b.created_at ?? '').localeCompare(a.created_at ?? '') || (a.id ?? '').localeCompare(b.id ?? ''));
+    const clip = (text) => text.length > CONTEXT_ENVELOPE_ITEM_MAX_CHARS ? `${text.slice(0, CONTEXT_ENVELOPE_ITEM_MAX_CHARS - 1)}…` : text;
+    const constraints = newestFirst(state.active_constraints ?? []);
+    const traps = newestFirst(state.known_traps ?? []).slice(0, CONTEXT_ENVELOPE_TOP_K);
+    const decisions = newestFirst(state.recent_decisions ?? []).slice(0, CONTEXT_ENVELOPE_TOP_K);
+    if (constraints.length === 0 && traps.length === 0 && decisions.length === 0)
+        return '';
+    const lines = [
+        '## Project context (inlined — MCP is a refresh, not a prerequisite)',
+        `Snapshot: ${constraints.length} constraint(s), ${traps.length}/${(state.known_traps ?? []).length} trap(s), ${decisions.length}/${(state.recent_decisions ?? []).length} decision(s), newest-first.`,
+    ];
+    const push = (title, items) => {
+        if (items.length === 0)
+            return;
+        lines.push(`### ${title}`);
+        for (const item of items)
+            lines.push(`- [${item.id ?? '?'}] ${clip((item.text ?? '').replace(/\s+/g, ' ').trim())}`);
+    };
+    push('Active constraints (binding)', constraints);
+    push('Known traps', traps);
+    push('Recent decisions', decisions);
+    lines.push('');
+    // Enforce the total budget by dropping whole trailing lines — a clipped list
+    // stays valid markdown, a mid-line cut does not.
+    let text = lines.join('\n');
+    while (text.length > CONTEXT_ENVELOPE_MAX_CHARS && lines.length > 2) {
+        lines.splice(lines.length - 2, 1); // drop the last content line, keep the trailing ''
+        text = lines.join('\n');
+    }
+    return text;
+}
 export function generateDispatchBrief(options) {
     const briefMode = resolveBriefMode(options.agent);
     const parts = [];
@@ -607,6 +767,13 @@ export function generateDispatchBrief(options) {
     }
     // pln#554 step 4 — working defaults (incremental commits + validation bar).
     parts.push(buildWorkingDefaultsSection({ canCommit: taskBriefProfile ? dispatchCanCommit(taskBriefProfile) : true }));
+    // pln#638 PR-6b — same envelope as generateBrief (see buildContextEnvelopeSection).
+    // Suppressed only when the content curates its own memory (contextEnvelope: false).
+    if (options.contextEnvelope !== false) {
+        const taskEnvelope = buildContextEnvelopeSection(options.cwd);
+        if (taskEnvelope)
+            parts.push(taskEnvelope);
+    }
     if (briefMode === 'full') {
         parts.push(buildProtocolSection({
             claimId: options.claimId,
@@ -618,14 +785,14 @@ export function generateDispatchBrief(options) {
     // (see generateBrief for the full rationale + dec#133). Fires only for
     // genuinely MCP-less agents; sandboxed-but-MCP-capable codex no longer gets a
     // self-contradictory "no MCP / Do NOT call bclaw_*" note.
-    if (taskBriefProfile && !dispatchHasMcp(taskBriefProfile)) {
-        parts.push('## ⚠ Transport: no MCP (file protocol only)');
-        parts.push('Your runtime has no brainclaw MCP access — any `bclaw_*` instruction above does NOT apply to you. Report your outcome via the FILE protocol only; it is authoritative for this run:');
-        const asgn = options.assignmentId ?? '<assignment_id>';
-        parts.push(`- When done, write LANE-RESULT.json at the worktree root: {"assignment_id":"${asgn}","status":"completed|blocked|failed","summary":"<what you did>","files_changed":["..."]}.`);
-        parts.push('- Capture decisions/traps as candidate JSON under .brainclaw/coordination/inbox/ (the coordinator harvests them).');
-        parts.push('- Do NOT call bclaw_* tools — they are unavailable here. The coordinator harvests your result and integrates it.');
-        parts.push('');
+    // pln#638 PR-4 — same shared section as generateBrief; the wording used to be
+    // duplicated verbatim in both builders, which is how they drift. Unresolved
+    // profile → conditional form, never silence (see generateBrief for why).
+    if (options.agent) {
+        parts.push(buildTransportSection({
+            hasMcp: taskBriefProfile ? dispatchHasMcp(taskBriefProfile) : true,
+            assignmentId: options.assignmentId,
+        }));
     }
     // Codex-specific constraints: focus and speed guidance for sandboxed runs
     if (options.agent === 'codex') {
@@ -911,7 +1078,15 @@ export async function dispatch(options, cwd) {
         // --- Dry-run path: skip assignment creation and message sending ---
         if (options.dryRun) {
             const briefMode = resolveBriefMode(targetAgent);
-            const brief = generateBrief(readyItem.plan, readyItem.item, cwd, briefMode, { claimId, worktreePath });
+            // pln#638 PR-3 — `agent` MUST be passed here, exactly as the real dispatch
+            // path below does. Without it `generateBrief` cannot resolve the capability
+            // profile, and THREE things silently diverge from what would actually be
+            // sent: working-defaults claims `canCommit: true` (wrong, and dangerous, for
+            // a sandboxed worker whose .git is read-only), the MCP-less LANE-RESULT
+            // section is omitted for a tier-C agent, and the liveness section loses its
+            // `sandboxed` flag. A --dry-run that previews a DIFFERENT brief than the one
+            // that ships is worse than no preview.
+            const brief = generateBrief(readyItem.plan, readyItem.item, cwd, briefMode, { claimId, worktreePath, agent: targetAgent });
             const invokeCmd = buildInvokeCommand(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) });
             if (invokeCmd) {
                 const cmdPrefix = buildEnvPrefix(claimId);

package/dist/core/execution.js

@@ -138,6 +138,14 @@ export function executeDispatchedCommand(invoke, options) {
  * - If autoExecute=true and agent is spawnable: spawn and return delivered_and_started
  * - If autoExecute=false or not spawnable: return command_ready_manual with command string
  * - If spawn fails: log warning, fallback to command_ready_manual
+ *
+ * pln#638 PR-6 — lifecycle boundary (the other half lives on
+ * buildProtocolSection in dispatcher.ts): the wrapper spawned here emits
+ * ack/heartbeat/completed/failed sentinels MECHANICALLY from the process exit
+ * code. That is TRANSPORT completion only. It never opens or closes sessions
+ * (lanes have none), never releases the lane's claim, and never triggers a
+ * review — business completion is proven exclusively by the coordinator's
+ * harvest/report path reading LANE-RESULT or bclaw_assignment_update.
  */
 export async function attemptExecution(invoke, options) {
     const adapter = options.adapter ?? defaultExecutionAdapter;

package/dist/core/loops/brief-assembly.js

@@ -19,6 +19,7 @@
  * — N items dropped)" tail so the operator can see when content was
  * dropped.
  */
+import { deriveWorkerReplyContract, renderWorkerReplyProse } from './worker-reply-contract.js';
 const DEFAULT_MAX_CHARS = 48_000;
 const DEFAULT_TOP_K_PER_CATEGORY = 8;
 /**
@@ -73,14 +74,24 @@ export function buildIdeationBrief(input) {
     const proposalBlock = renderProposalBlock(proposalText);
     const memoryBlock = renderMemoryBlock(fetchedItemsByCategory);
     const closing = renderClosingInstructions(slotRole, thread.current_phase);
-    // Compose with truncation. The proposal seed and header are fixed;
-    // memory + prior artifacts share the remaining budget. Memory before
-    // prior-artifacts so the critic always sees fresh adversarial pressure.
-    const fixedParts = [header, proposalBlock, closing];
+    // pln#638 PR-5 — the deliverable contract, derived from the CURRENT phase's
+    // gate and frozen into the brief at dispatch time. This is the structural fix
+    // for proof #1 (a critic typed `coverage_gap`, invisible to the critique gate):
+    // the expected type was always known here; it just never travelled. FIXED
+    // part, never truncated — a brief that keeps its memory bundle but loses its
+    // reply contract would recreate the bug the section exists to prevent.
+    const contract = deriveWorkerReplyContract(thread);
+    const contractBlock = contract ? renderWorkerReplyProse(contract) : '';
+    // Compose with truncation. The proposal seed, header, closing and contract
+    // are fixed; memory + prior artifacts share the remaining budget. Memory
+    // before prior-artifacts so the critic always sees fresh adversarial pressure.
+    const fixedParts = [header, proposalBlock, closing, contractBlock];
     const fixedSize = fixedParts.reduce((n, s) => n + s.length, 0);
     const remainingBudget = Math.max(0, maxChars - fixedSize);
     const { text: truncatedMemory, truncated, droppedItems, includedItems } = truncateToBudget([memoryBlock, priorArtifactsBlock].filter((s) => s.length > 0), fetchedItemsByCategory, remainingBudget);
-    const text = [header, proposalBlock, truncatedMemory, closing]
+    // The contract closes the brief: the last thing a worker reads is how to
+    // reply so its work counts.
+    const text = [header, proposalBlock, truncatedMemory, closing, contractBlock]
         .filter((s) => s.length > 0)
         .join('\n\n');
     return { text, truncated, includedItems, droppedItems, categoriesUsed };

package/dist/core/loops/index.js

@@ -11,4 +11,5 @@ export { readSurveySources, } from './hooks/survey-source-reader.js';
 export { buildSurveySignalsBaseline, } from './hooks/survey-signals-baseline.js';
 export { acquireLock, hashRequest, recordConflict, withLoopLock, DEFAULT_MAX_MUTATION_DURATION_MS, IDEMPOTENCY_TTL_MS, LEASE_GRACE_MS, LEASE_WINDOW_MS, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, LockLostError, LockTimeoutError, VersionConflictError, } from './lock.js';
 export { acquireBootstrapLoop, findExistingBootstrapLoop, BootstrapCoordinationInProgressError, } from './bootstrap-acquire.js';
+export { deriveWorkerReplyContract, renderWorkerReplyProse, workerReplyNextAction, } from './worker-reply-contract.js';
 //# sourceMappingURL=index.js.map

package/dist/core/loops/worker-reply-contract.js

@@ -0,0 +1,93 @@
+import { LOOP_ARTIFACT_BODY_MAX_BYTES } from './types.js';
+/** Recursively extract artifact requirements from a gate, preserving all/any. */
+function extractFromGate(gate) {
+    switch (gate.kind) {
+        case 'min_artifacts_by_type':
+            return { requirements: [{ type: gate.type, n: gate.n, scope: gate.scope }], other: [], composition: 'single' };
+        case 'artifact_produced':
+            return { requirements: [{ type: gate.type }], other: [], composition: 'single' };
+        case 'all':
+        case 'any': {
+            const parts = gate.conditions.map(extractFromGate);
+            const requirements = parts.flatMap((p) => p.requirements);
+            const other = parts.flatMap((p) => p.other);
+            // Nested compositions collapse to the OUTER combinator for prose purposes;
+            // the exact tree is the engine's business, the worker only needs to know
+            // whether one deliverable suffices or all are needed.
+            return {
+                requirements,
+                other,
+                composition: requirements.length > 1 ? gate.kind : 'single',
+            };
+        }
+        default:
+            // reviewer_green, no_open_questions, iterations, manual, phase_reached —
+            // conditions a worker cannot satisfy by typing an artifact correctly.
+            return { requirements: [], other: [gate.kind], composition: 'single' };
+    }
+}
+/**
+ * Derive the contract for the loop's CURRENT phase, or undefined when the phase
+ * has no artifact-typed gate — in which case no section is emitted and no
+ * obligation is invented (silence over fabrication, as everywhere else).
+ */
+export function deriveWorkerReplyContract(thread) {
+    const phaseDef = thread.phases.find((p) => p.name === thread.current_phase);
+    const gate = phaseDef?.advance_gate;
+    if (!gate)
+        return undefined;
+    const { requirements, other, composition } = extractFromGate(gate);
+    if (requirements.length === 0)
+        return undefined;
+    return {
+        loop_id: thread.id,
+        phase: thread.current_phase,
+        requirements,
+        composition,
+        other_conditions: [...new Set(other)],
+        loop_version: thread.version,
+        body_max_bytes: LOOP_ARTIFACT_BODY_MAX_BYTES,
+    };
+}
+/**
+ * The {tool, args, when} a worker with MCP should call — derived from the SAME
+ * contract the prose renders, so the two cannot disagree.
+ */
+export function workerReplyNextAction(contract) {
+    const primary = contract.requirements[0];
+    return {
+        tool: 'bclaw_loop',
+        args: {
+            intent: 'add_artifact',
+            loop_id: contract.loop_id,
+            artifact: {
+                phase: contract.phase,
+                type: primary.type,
+                body: '<your full output — non-empty, or it does not count toward the gate>',
+            },
+        },
+        when: `your ${primary.type} is ready — the phase gate only counts artifacts of this exact type`,
+    };
+}
+/** Render the brief section. Every value comes off the contract object. */
+export function renderWorkerReplyProse(contract) {
+    const action = workerReplyNextAction(contract);
+    const typeList = contract.requirements
+        .map((r) => `\`${r.type}\`${r.n ? ` (n≥${r.n}, ${r.scope ?? 'phase'} scope)` : ''}`)
+        .join(contract.composition === 'any' ? ' OR ' : ' AND ');
+    const lines = [
+        `## Deliverable contract — loop ${contract.loop_id}, phase "${contract.phase}"`,
+        `The phase gate counts artifact type(s): ${typeList}. Any other type — however good the content — is INVISIBLE to the gate and stalls the loop.`,
+        `- MCP path: call \`${action.tool}\` with ${JSON.stringify(action.args)}`,
+        `- The body must be NON-EMPTY: an artifact without usable content does not count toward the gate.`,
+        `- Body cap: ${contract.body_max_bytes} bytes. If your output is larger, write the full version to a markdown file in your worktree and put a dense summary plus the file path in the body.`,
+        `- File fallback (no MCP): in LANE-RESULT.json set "artifact_type":"${contract.requirements[0].type}" and put your full output in "body" — the harvester records it under this contract.`,
+        `- This contract is FROZEN for loop version ${contract.loop_version}, phase "${contract.phase}". If your submit reports a version conflict or the loop has advanced, your work is still recorded under phase "${contract.phase}" — do not re-target a newer phase.`,
+    ];
+    if (contract.other_conditions.length > 0) {
+        lines.push(`- Note: the gate also requires ${contract.other_conditions.join(', ')} — producing artifacts alone may not advance the phase; that part is the coordinator's to satisfy.`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=worker-reply-contract.js.map

package/dist/core/review-loop-turn-dispatch.js

@@ -366,6 +366,7 @@ export async function dispatchReviewLoopTurn(input) {
             scope,
             worktreePath: claimResult.worktreePath,
             assignmentId,
+            cwd, // pln#638 PR-6b — the context envelope reads the store
         });
         const msg = sendMessage({
             from: input.dispatcherAgent,

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.19.1 on 2026-08-02T07:16:39.143Z
+// Source: brainclaw v1.20.0 on 2026-08-02T17:17:41.989Z
 export const FACTS = {
-  "version": "1.19.1",
-  "generated_at": "2026-08-02T07:16:39.143Z",
+  "version": "1.20.0",
+  "generated_at": "2026-08-02T17:17:41.989Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-02T07:16:37.042Z",
+    "generated_at": "2026-08-02T17:17:40.300Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 81,
+        "duration_ms_median": 65,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,15 +491,15 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 123,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 101,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 12,
+        "duration_ms_median": 10,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.19.1",
-  "generated_at": "2026-08-02T07:16:39.143Z",
+  "version": "1.20.0",
+  "generated_at": "2026-08-02T17:17:41.989Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-02T07:16:37.042Z",
+    "generated_at": "2026-08-02T17:17:40.300Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 81,
+        "duration_ms_median": 65,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,15 +489,15 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 123,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 101,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 12,
+        "duration_ms_median": 10,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/mcp-schema-changelog.md

@@ -8,6 +8,20 @@ guarantees this changelog follows.
 
 ---
 
+## [1.20.0] — 2026-08-02
+
+**Fixed — 1.19.0 contract entries now actually emitted (#158)**
+- `generated_surfaces_stale` (surfaced as `stale_surfaces`) and session-end
+  `scope_warnings` were documented below in 1.19.0 but computed-then-dropped
+  before the MCP boundary on the surfaces agents actually call. They now reach
+  `bclaw_session_start`, `bclaw_session_end` and `bclaw_work` responses as
+  `warnings` + `warning_details`. `shared_checkout_warning` (session-start)
+  rides the same seam.
+- Read contract only: no tool added/removed/renamed, no inputSchema change,
+  no surface-fingerprint movement. The dispatch-brief changes this release
+  (transport section, context envelope, worker reply contract, lane session
+  prohibition) are payload text, not protocol.
+
 ## [1.19.0] — 2026-08-01
 
 **Added — `warning_details` on the facade response contract (pln#635)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.19.1",
+  "version": "1.20.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {