brainclaw 1.15.0 → 1.17.0

package/dist/commands/update-handoff.js

@@ -1,6 +1,6 @@
 import { loadState, persistState } from '../core/state.js';
 import { memoryExists } from '../core/io.js';
-import { nowISO } from '../core/ids.js';
+import { mergeHandoffReview } from '../core/handoff-review.js';
 export function applyHandoffUpdates(handoff, options = {}) {
     if (options.status)
         handoff.status = options.status;
@@ -18,47 +18,33 @@ export function applyHandoffUpdates(handoff, options = {}) {
     if (Object.keys(contractUpdates).length > 0) {
         handoff.contract = { ...handoff.contract, ...contractUpdates };
     }
-    const hasReviewUpdate = options.reviewer !== undefined ||
-        options.requester !== undefined ||
-        options.requested_at !== undefined ||
-        options.review_thread_id !== undefined ||
-        options.review_message_id !== undefined ||
-        options.review_verdict !== undefined ||
-        options.reviewed_by !== undefined ||
-        options.review_summary !== undefined ||
-        options.blocking_issues !== undefined ||
-        options.suggestions !== undefined;
-    if (hasReviewUpdate) {
-        const review = { ...(handoff.review ?? {}) };
-        if (options.reviewer !== undefined)
-            review.reviewer = options.reviewer;
-        if (options.requester !== undefined)
-            review.requester = options.requester;
-        if (options.requested_at !== undefined)
-            review.requested_at = options.requested_at;
-        if (options.review_thread_id !== undefined)
-            review.thread_id = options.review_thread_id;
-        if (options.review_message_id !== undefined)
-            review.message_id = options.review_message_id;
-        if (options.review_verdict !== undefined)
-            review.verdict = options.review_verdict;
-        if (options.reviewed_by !== undefined)
-            review.reviewed_by = options.reviewed_by;
-        if (options.review_summary !== undefined)
-            review.summary = options.review_summary;
-        if (options.blocking_issues !== undefined)
-            review.blocking_issues = options.blocking_issues;
-        if (options.suggestions !== undefined)
-            review.suggestions = options.suggestions;
-        const reviewCompleted = options.review_verdict !== undefined ||
-            options.reviewed_by !== undefined ||
-            options.review_summary !== undefined ||
-            options.blocking_issues !== undefined ||
-            options.suggestions !== undefined;
-        if (reviewCompleted) {
-            review.reviewed_at = nowISO();
-        }
-        handoff.review = review;
+    // Translate the flat options into a nested review patch and delegate the
+    // merge + reviewed_at stamping to the shared core helper — the SINGLE source
+    // of truth shared with updateEntity(handoff) so the two write paths cannot
+    // drift (pln#625 Phase 3, Codex review of #84).
+    const reviewPatch = {};
+    if (options.reviewer !== undefined)
+        reviewPatch.reviewer = options.reviewer;
+    if (options.requester !== undefined)
+        reviewPatch.requester = options.requester;
+    if (options.requested_at !== undefined)
+        reviewPatch.requested_at = options.requested_at;
+    if (options.review_thread_id !== undefined)
+        reviewPatch.thread_id = options.review_thread_id;
+    if (options.review_message_id !== undefined)
+        reviewPatch.message_id = options.review_message_id;
+    if (options.review_verdict !== undefined)
+        reviewPatch.verdict = options.review_verdict;
+    if (options.reviewed_by !== undefined)
+        reviewPatch.reviewed_by = options.reviewed_by;
+    if (options.review_summary !== undefined)
+        reviewPatch.summary = options.review_summary;
+    if (options.blocking_issues !== undefined)
+        reviewPatch.blocking_issues = options.blocking_issues;
+    if (options.suggestions !== undefined)
+        reviewPatch.suggestions = options.suggestions;
+    if (Object.keys(reviewPatch).length > 0) {
+        handoff.review = mergeHandoffReview(handoff.review, reviewPatch);
     }
     return handoff;
 }

package/dist/core/agent-capability.js

@@ -147,16 +147,27 @@ const PROFILES = {
         invoke_binary: 'opencode',
         invoke_review_template: 'opencode "{prompt}"',
     },
-    // Sandbox note: when running under --sandbox workspace-write, Codex cannot reach
-    // the main project store via MCP. Use filesystem-direct writes instead:
-    // write candidates to .brainclaw/coordination/inbox/cnd_<id>.json in the active
-    // worktree. The coordinator then syncs them via bclaw_harvest_candidates.
+    // Sandbox note (CORRECTED — dec#133, empirical probe codex 0.144.4, 2026-07-18):
+    // the earlier belief that `--sandbox workspace-write` blocks brainclaw MCP was
+    // FALSE and never re-verified. The MCP server runs as a SEPARATE process outside
+    // the sandbox, and `approval_policy=never` (baked into the invoke template below)
+    // auto-approves every tool call in headless mode — so MCP reads/writes are
+    // reachable from a sandboxed codex run. The REAL residual constraint is `git
+    // commit`: the sandbox root excludes `.git`, so the coordinator commits the
+    // worktree diff at harvest time (see dispatchCanCommit / harvest.ts). Candidates
+    // can still be dropped as filesystem JSON as a fallback, but MCP is not the
+    // blocker.
     codex: {
         name: 'codex', category: 'code-agent', workflowModel: 'task-based',
-        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: true,
+        // hooks: Codex gained a native lifecycle hook surface (SessionStart /
+        // UserPromptSubmit / Stop / PreToolUse / … via .codex/hooks.json or [hooks]
+        // in config.toml; developers.openai.com/codex/hooks, verified 2026-07 —
+        // trp_fe75dafc). brainclaw writes .codex/hooks.json (ensureCodexHooks),
+        // giving Codex the same session-lifecycle wiring as Claude Code.
+        hasMcp: true, hasHooks: true, hasAutoApprove: false, hasSkills: true, hasRules: true,
         instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'A',
         role_capabilities: ['execute', 'review'],
-        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
         max_concurrent_tasks: 5,
         // pln#475: prefer stdin_pipe to avoid Windows cmd.exe arg-parsing breaking
         // long prompts. codex.cmd resolves through cmd shell, where embedded
@@ -693,25 +704,36 @@ export function resolveBriefMode(agentName) {
  * pln#528 — capability matrix DERIVED from the spawn template, so it stays in
  * sync with how each agent is actually invoked (no per-profile duplication).
  *
- * The motivating reality (a cross-project field debrief): codex is spawned with
- * `--sandbox workspace-write`, which (a) does NOT wire the brainclaw MCP server
- * and (b) puts `.git` outside the sandbox root — so a sandboxed worker can
- * neither call `bclaw_*` nor `git commit`, regardless of the profile's nominal
- * `runtime.mcp_direct` flag. These helpers expose that so the brief / handoff /
- * harvest logic can adapt to the transport instead of issuing instructions the
- * worker cannot follow.
+ * pln#628 Focus 4A CORRECTION (dec#133, empirical probe codex 0.144.4): the
+ * original pln#528 belief — that a `--sandbox` spawn "does NOT wire the brainclaw
+ * MCP server" — was a FALSE premise that was never re-verified. In reality the MCP
+ * server is a separate out-of-sandbox process and `approval_policy=never`
+ * auto-approves every tool call, so MCP is reachable from a sandboxed run. The
+ * ONE residual constraint the sandbox actually imposes is `git commit` (.git sits
+ * outside the writable root). So the two capabilities are now decoupled: sandbox
+ * ⇏ no-MCP, sandbox ⇒ no-commit.
  */
 export function isSandboxedSpawn(profile) {
     return /--sandbox\b/.test(profile.invoke_template ?? '');
 }
-/** Whether the agent, AS SPAWNED by the dispatcher, can reach brainclaw MCP. */
+/**
+ * Whether the agent, AS SPAWNED by the dispatcher, can reach brainclaw MCP.
+ *
+ * pln#628 Focus 4A: this is NO LONGER gated by isSandboxedSpawn. dec#133 proved
+ * empirically that a sandboxed codex run reaches MCP (both whitelisted and
+ * non-whitelisted tools fired) — the sandbox does not sever MCP, it only makes
+ * `.git` read-only. MCP reachability therefore tracks `runtime.mcp_direct` alone;
+ * the commit constraint is expressed separately by dispatchCanCommit.
+ */
 export function dispatchHasMcp(profile) {
-    return profile.runtime.mcp_direct && !isSandboxedSpawn(profile);
+    return profile.runtime.mcp_direct;
 }
 /**
  * Whether the spawned worker can `git commit`. A sandbox whose root excludes
  * `.git` cannot — the coordinator must integrate the worker's output instead of
- * relying on a self-commit handoff.
+ * relying on a self-commit handoff. NOTE (dec#133): commit-from-sandbox was NOT
+ * verified to work even on Windows, so this stays conservative (sandbox ⇒ no
+ * commit); do not relax it to a platform check without an empirical probe.
  */
 export function dispatchCanCommit(profile) {
     return !isSandboxedSpawn(profile);

package/dist/core/agent-files.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
-import { MCP_HEADLESS_AUTO_TOOL_NAMES, MCP_CANONICAL_GRAMMAR_TOOL_NAMES, REMOVED_IN_V1_TOOLS } from '../commands/mcp.js';
+import { MCP_HEADLESS_AUTO_TOOL_NAMES, MCP_CANONICAL_GRAMMAR_TOOL_NAMES, REMOVED_IN_V1_TOOLS } from './protocol-tool-policy.js';
 import { renderToml, tomlArrayTableHasEntry } from './toml-writer.js';
 import { PROTOCOL_SKILLS, renderProtocolSkill } from './protocol-skills.js';
 import { getInstalledBrainclawVersion } from './brainclaw-version.js';
@@ -314,6 +314,7 @@ const ANTIGRAVITY_MCP_RELATIVE_PATH = '.gemini/antigravity/mcp_config.json';
 const ANTIGRAVITY_HOOKS_RELATIVE_PATH = '.gemini/antigravity/hooks.json';
 const CURSOR_HOOKS_RELATIVE_PATH = '.cursor/hooks.json';
 const COPILOT_HOOKS_RELATIVE_PATH = '.github/copilot/hooks.json';
+const CODEX_HOOKS_RELATIVE_PATH = '.codex/hooks.json';
 const OPENCLAW_MCP_RELATIVE_PATH = '.openclaw/mcp.json';
 const VSCODE_EXTENSIONS_RELATIVE_PATH = '.vscode/extensions.json';
 const UNIVERSAL_SKILL_RELATIVE_PATH = '.agents/skills/brainclaw/SKILL.md';
@@ -1686,7 +1687,10 @@ export function ensureCodexMcpConfig(homeDir, env = process.env) {
         '\n[mcp_servers.brainclaw]',
         `command = "${normalizedCommand}"`,
         `args = [${normalizedArgs.map(a => `"${a}"`).join(', ')}]`,
-        'startup_timeout_ms = 20000',
+        // Codex renamed this field to `_sec` (developers.openai.com/codex/extend/mcp;
+        // the docs note "uses _sec, not _ms"). The old `startup_timeout_ms` is an
+        // unrecognized key → Codex silently falls back to its default startup timeout.
+        'startup_timeout_sec = 20',
         '',
         '[mcp_servers.brainclaw.env]',
         'BRAINCLAW_AGENT = "codex"',
@@ -2115,6 +2119,53 @@ export function ensureAntigravityHooks(homeDir) {
         relativePath: ANTIGRAVITY_HOOKS_RELATIVE_PATH,
     };
 }
+/**
+ * Writes `.codex/hooks.json` — Codex CLI's native lifecycle hooks config
+ * (project scope). Codex gained a full hook surface (developers.openai.com/codex/hooks,
+ * verified 2026-07 — trp_fe75dafc); this wires brainclaw's session lifecycle to it,
+ * mirroring the Claude Code / Antigravity hook writers.
+ *
+ * Events (PascalCase, per the Codex schema): `SessionStart` loads shared context,
+ * `UserPromptSubmit` surfaces the context diff, `Stop` runs session-end cleanup.
+ * File shape: `{ "hooks": { "<Event>": [ { "matcher": "", "hooks": [ { "type": "command", "command": "…" } ] } ] } }`
+ * — the top-level `hooks` wrapper + per-entry `hooks` array (`matcher: ""` = match all).
+ *
+ * brainclaw OWNS these three event arrays (overwrite, not merge) — the same
+ * contract as the Cursor / Antigravity `hooks.json` writers. This is
+ * unconditionally idempotent regardless of how the CLI path resolves, with no
+ * cross-upgrade pile-up. It deliberately does NOT use command-recognition to
+ * preserve user entries within these events: recognizing brainclaw's own hook
+ * path-independently requires matching bare CLI subcommands, which over-matches
+ * legitimate user hooks that merely pass `session-start`/etc. as an argument
+ * (Codex review of #94, round 2). Other events the user defines are untouched
+ * (only these three keys are set).
+ */
+export function ensureCodexHooks(cwd) {
+    const filePath = path.join(cwd, CODEX_HOOKS_RELATIVE_PATH);
+    const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('rule', 'Codex session hooks', filePath, CODEX_HOOKS_RELATIVE_PATH);
+    }
+    const hooks = isJsonObject(existing.hooks) ? { ...existing.hooks } : {};
+    const sessionStartCmd = buildHookCommand(['session-start', '--include-context']);
+    const contextDiffCmd = buildHookCommand(['context-diff']);
+    const sessionEndCmd = buildHookCommand(['session-end', '--auto-release', '--reflect', '--reflect-handoff', '--dispatch-review']);
+    hooks.SessionStart = [buildCommandHookEntry(sessionStartCmd)];
+    hooks.UserPromptSubmit = [buildCommandHookEntry(contextDiffCmd)];
+    hooks.Stop = [buildCommandHookEntry(sessionEndCmd)];
+    const { created, updated } = writeJsonFileIfChanged(filePath, {
+        ...existing,
+        hooks,
+    });
+    return {
+        kind: 'rule',
+        label: 'Codex session hooks',
+        created,
+        updated,
+        filePath,
+        relativePath: CODEX_HOOKS_RELATIVE_PATH,
+    };
+}
 /**
  * Writes `.github/copilot/hooks.json` — GitHub Copilot's native hooks config.
  * Events: sessionStart, userPromptSubmitted, sessionEnd (camelCase).
@@ -2284,7 +2335,7 @@ export const AGENT_WIRING_REGISTRY = {
             writeProtocolSkills,
         ],
         userWriters: [(ctx) => ensureCodexMcpConfig(ctx.homeDir, ctx.env)],
-        hookWriters: [],
+        hookWriters: [(ctx) => ensureCodexHooks(ctx.cwd)],
     },
     continue: {
         workspaceWriters: [(ctx) => ensureContinueMcpConfig(ctx.cwd)],

package/dist/core/agent-integrations.js

@@ -61,6 +61,7 @@ const DEFAULT_SURFACES = {
     'codex': [
         { kind: 'instructions', location: 'workspace', path: 'AGENTS.md' },
         { kind: 'mcp', location: 'machine', path: '.codex/config.toml' },
+        { kind: 'hook', location: 'workspace', path: '.codex/hooks.json' },
         { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
     'opencode': [

package/dist/core/coordination.js

@@ -288,8 +288,11 @@ function buildIncomingSignalsSummary(cwd) {
         return {
             id: signal.id,
             entity_type: signal.entity_type,
-            from_project: signal.from_project.name,
-            from_agent: signal.from_agent.name,
+            // Defence-in-depth: listIncomingCrossProjectSignals already filters
+            // wrong-shape envelopes, but never let a single missing field crash the
+            // whole board render (trp_e90b3198).
+            from_project: signal.from_project?.name ?? '?',
+            from_agent: signal.from_agent?.name ?? '?',
             created_at: signal.created_at,
             preview: text.length > 120 ? text.slice(0, 117) + '...' : text,
         };

package/dist/core/cross-project.js

@@ -128,6 +128,33 @@ export function writeCrossProjectSignal(target, entityType, payload, sourceCwd)
     fs.writeFileSync(filepath, JSON.stringify(signal, null, 2) + '\n', 'utf-8');
     return signal;
 }
+/**
+ * Runtime shape guard for a cross-project signal envelope. A second signaling
+ * subsystem can drop schema-incompatible (but valid-JSON) files into the same
+ * directory; without this guard a consumer that reads envelope.from_project.name
+ * / from_agent.name / created_at crashes with a TypeError on every read
+ * (e.g. bclaw_context board — reachable purely locally). Guarding here — the
+ * single source of these envelopes — keeps every consumer safe.
+ */
+const CROSS_PROJECT_SIGNAL_ENTITIES = new Set(['candidate', 'handoff', 'runtime_note']);
+function isCrossProjectSignalEnvelope(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    const fromProject = v.from_project;
+    const fromAgent = v.from_agent;
+    return typeof v.id === 'string'
+        && typeof v.entity_type === 'string'
+        // entity_type must be one of ours — a foreign subsystem's value would flow
+        // downstream as a bogus type.
+        && CROSS_PROJECT_SIGNAL_ENTITIES.has(v.entity_type)
+        && typeof v.created_at === 'string'
+        && typeof fromProject?.name === 'string'
+        && typeof fromAgent?.name === 'string'
+        // payload MUST be a non-null object: the consumer does `'text' in payload`,
+        // which throws a TypeError on a primitive/null payload (Codex review of #85).
+        && typeof v.payload === 'object' && v.payload !== null;
+}
 /**
  * Lists cross-project signals materialized in the local inbox.
  */
@@ -142,7 +169,14 @@ export function listIncomingCrossProjectSignals(cwd) {
             continue;
         const filepath = path.join(dir, entry);
         try {
-            signals.push(JSON.parse(fs.readFileSync(filepath, 'utf-8')));
+            const parsed = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+            // Skip files that are valid JSON but not our envelope shape (schema drift
+            // from another signaling subsystem sharing this directory) — matching the
+            // existing "ignore malformed" intent, but for wrong-shape as well as
+            // wrong-syntax.
+            if (isCrossProjectSignalEnvelope(parsed)) {
+                signals.push(parsed);
+            }
         }
         catch {
             // Ignore malformed signal files.

package/dist/core/dispatcher.js

@@ -279,13 +279,39 @@ export function buildProtocolSection(options) {
     }
     if (options?.worktreePath) {
         parts.push(`Worktree: ${options.worktreePath}`);
-        // pln#523: tell the worker how dependencies are provisioned so it does not
-        // stall trying to install them. node_modules (and per-package node_modules in
-        // monorepos) are junction-linked from the main repo — run builds/typecheck
-        // directly. If they are missing, do NOT `npm install` in the worktree: check
-        // `.brainclaw-worktree.json` → `symlink_warnings` (a link may have failed,
-        // e.g. cross-volume) and validate the build centrally with the coordinator.
-        parts.push('Dependencies: node_modules is linked from the main repo (incl. monorepo per-package). Build/typecheck directly; if deps are missing, do NOT npm install here — see .brainclaw-worktree.json symlink_warnings and validate centrally.');
+        // pln#523 / trp_37b05a15: tell the worker how dependencies are provisioned so
+        // it does not stall trying to (re)install them. The authoritative record is
+        // the worktree's `.brainclaw-worktree.json` → `deps_mode` (absent ⇒ `link`).
+        //   - link (default): node_modules (incl. monorepo per-package) is
+        //     junction-linked from the main repo — build/typecheck directly; do NOT
+        //     `npm install`. An out-of-root symlink, so `next dev`/Turbopack rejects
+        //     it (build/tsc/vitest are fine).
+        //   - install/copy: node_modules is a REAL in-root directory — everything,
+        //     including a dev server, works directly; no reinstall needed.
+        //   - none: no deps provisioned — run the project's install first.
+        let depsMode = 'link';
+        let depsProvisioned;
+        try {
+            const sidecar = JSON.parse(fs.readFileSync(path.join(options.worktreePath, '.brainclaw-worktree.json'), 'utf-8'));
+            if (sidecar.deps_mode)
+                depsMode = sidecar.deps_mode;
+            depsProvisioned = sidecar.deps_provisioned;
+        }
+        catch { /* sidecar absent/unreadable — assume the default `link` */ }
+        if ((depsMode === 'install' || depsMode === 'copy') && depsProvisioned === false) {
+            // Codex review P1: provisioning was ATTEMPTED but FAILED (best-effort, non-fatal).
+            // Do not claim node_modules is usable — tell the worker to install it.
+            parts.push(`Dependencies: in-root provisioning was attempted (deps_mode=${depsMode}) but FAILED — node_modules may be missing or incomplete. Run the project's install (npm/pnpm/yarn/bun) in the worktree before building; see .brainclaw-worktree.json symlink_warnings for the failure.`);
+        }
+        else if (depsMode === 'install' || depsMode === 'copy') {
+            parts.push(`Dependencies: node_modules is a real in-root directory (deps_mode=${depsMode}) — build, typecheck, and dev server all work directly; do NOT reinstall. If anything is missing, see .brainclaw-worktree.json symlink_warnings.`);
+        }
+        else if (depsMode === 'none') {
+            parts.push('Dependencies: none were provisioned (deps_mode=none) — run the project\'s install (npm/pnpm/yarn/bun) in the worktree before building.');
+        }
+        else {
+            parts.push('Dependencies: node_modules is linked from the main repo (incl. monorepo per-package). Build/typecheck directly; if deps are missing, do NOT npm install here — see .brainclaw-worktree.json symlink_warnings and validate centrally. (Out-of-root symlink: next dev/Turbopack needs deps_mode=install.)');
+        }
     }
     parts.push('');
     // Assignment lifecycle protocol (Agent SDK)
@@ -307,9 +333,11 @@ export function buildProtocolSection(options) {
         if (options.worktreePath) {
             parts.push('**Compile check**: before every commit, `tsc --noEmit` (or the project build) must pass — a per-worktree pre-commit gate may enforce this and reject the commit otherwise. Do not bypass with --no-verify unless you intend to hand off a known-broken state.');
         }
-        // pln#526: standard fallback channel — works even when MCP is unreachable
-        // (sandboxed agents). The coordinator ingests it with `brainclaw harvest`.
-        parts.push(`Final fallback (if bclaw_assignment_update / MCP is unavailable, e.g. a sandboxed agent): 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}\`.`);
+        // pln#526: standard fallback channel — works even if bclaw_assignment_update
+        // 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}\`.`);
     }
     else if (options?.claimId) {
         parts.push('1. Call bclaw_session_start to register your session');
@@ -468,22 +496,25 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     if (mode === 'full') {
         parts.push(buildProtocolSection(options));
     }
-    // pln#528 — transport-aware addendum (field debrief P1#2). When the agent is
-    // spawned sandboxed (no MCP + no git commit — e.g. codex --sandbox
-    // workspace-write), the MCP lifecycle lines in the Protocol section do NOT
-    // apply. Say so explicitly and make the FILE protocol authoritative, so the
-    // worker never receives instructions it cannot follow nor has to guess the
-    // fallback. (Note: resolveBriefMode still returns 'full' for codex per pln#496
-    // so the reconciler-independent path is preserved; this addendum disambiguates
-    // the transport rather than stripping the section — the full compact reversal
-    // is a separate human-owned call on the May-vs-June MCP-availability conflict.)
+    // pln#628 Focus 4A — transport addendum, now keyed to the ACTUAL missing
+    // capability. Originally (pln#528) this fired for any sandboxed spawn and
+    // claimed "no MCP + no commit". dec#133 proved the "no MCP" half FALSE: a
+    // sandboxed codex reaches MCP (separate out-of-sandbox process +
+    // approval_policy=never). dispatchHasMcp now tracks runtime.mcp_direct alone,
+    // so this block only fires for genuinely MCP-less agents (nanoclaw/nemoclaw/
+    // zeroclaw). For them the Protocol section's MCP lifecycle does not apply and
+    // the file protocol is the sole channel. Sandboxed-but-MCP-capable agents
+    // (codex) no longer receive a self-contradictory "MCP NOT reachable / Do NOT
+    // 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: sandboxed run (no MCP, no commit)');
-        parts.push('Your runtime is sandboxed — the brainclaw MCP server is NOT reachable and `git commit` is unavailable (.git is outside the sandbox root). Any `bclaw_*` MCP instruction above does NOT apply to you. Report your outcome via the FILE protocol only — it is authoritative for this run:');
+        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/commits it.');
+        parts.push('- Do NOT call bclaw_* tools — they are unavailable here. The coordinator harvests your result and integrates it.');
         parts.push('');
     }
     // Codex-specific constraints: focus and speed guidance for sandboxed runs.
@@ -525,14 +556,17 @@ export function generateDispatchBrief(options) {
             assignmentId: options.assignmentId,
         }));
     }
-    // pln#528 — transport-aware addendum for sandboxed agents (see generateBrief).
+    // pln#628 Focus 4A — transport addendum keyed to the ACTUAL missing capability
+    // (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: sandboxed run (no MCP, no commit)');
-        parts.push('Your runtime is sandboxed — the brainclaw MCP server is NOT reachable and `git commit` is unavailable (.git is outside the sandbox root). Any `bclaw_*` MCP instruction above does NOT apply to you. Report your outcome via the FILE protocol only — it is authoritative for this run:');
+        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/commits it.');
+        parts.push('- Do NOT call bclaw_* tools — they are unavailable here. The coordinator harvests your result and integrates it.');
         parts.push('');
     }
     // Codex-specific constraints: focus and speed guidance for sandboxed runs
@@ -902,13 +936,19 @@ export async function dispatch(options, cwd) {
                 requireWorktree: true, // pln#531: never spawn a worker in the integration repo
             });
             entry.execution_status = execResult.execution_status;
+            // pln#626 Phase 1 — mirror the coordinate path: carry the reason so a
+            // command_ready_manual sequence item says WHY it didn't spawn.
+            if (execResult.execution_reason)
+                entry.execution_reason = execResult.execution_reason;
+            if (execResult.failure_kind)
+                entry.failure_kind = execResult.failure_kind;
             if (execResult.pid)
                 entry.pid = execResult.pid;
             if (execResult.execution_status === 'delivered_and_started') {
                 entry.channel = 'spawned_cli';
             }
             if (execResult.error)
-                result.warnings.push(execResult.error);
+                result.warnings.push(`${entry.agent}: ${execResult.error}`);
             if (entry.assignment_id && entry.claim_id) {
                 if (execResult.failure_kind === 'spawn_no_handshake') {
                     try {