brainclaw 1.14.0 → 1.16.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,10 +147,16 @@ 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,
@@ -693,25 +699,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';

package/dist/core/agent-registry.js

@@ -140,8 +140,17 @@ function ensureParentDir(filepath) {
         fs.mkdirSync(dir, { recursive: true });
     }
 }
-function fingerprintPublicKey(publicKey) {
-    return crypto.createHash('sha256').update(publicKey).digest('hex');
+/**
+ * Canonical Ed25519 public-key fingerprint (pln#101): sha256 over the PEM with
+ * carriage returns stripped and surrounding whitespace trimmed, so a trailing
+ * newline or CRLF (e.g. introduced by copy-paste through the cloud UI) does NOT
+ * change the fingerprint. The cloud computes the same canonical value — see
+ * brainclaw-cloud/src/handlers/agents.ts fingerprintPem — so a local↔remote
+ * match is a reliable proof of the same key regardless of PEM formatting.
+ */
+export function fingerprintPublicKeyPem(publicKeyPem) {
+    const canonical = publicKeyPem.replace(/\r/g, '').trim();
+    return crypto.createHash('sha256').update(canonical).digest('hex');
 }
 function buildIdentityKey(agentId, env = process.env, forceRegenerate = false) {
     migrateLegacyAgentKey(agentId, env);
@@ -168,10 +177,49 @@ function buildIdentityKey(agentId, env = process.env, forceRegenerate = false) {
     return {
         algorithm: 'ed25519',
         public_key: publicKeyPem,
-        fingerprint: fingerprintPublicKey(publicKeyPem),
+        fingerprint: fingerprintPublicKeyPem(publicKeyPem),
         created_at: createdAt,
     };
 }
+/**
+ * Load an agent's Ed25519 signing material for cloud request signing (pln#100).
+ *
+ * Reads the private key from the neutral key store (~/.brainclaw/keys/),
+ * migrating from the legacy CODEX_HOME location if needed, and derives the SPKI
+ * public-key PEM plus its fingerprint — the same sha256(pem) the cloud stores as
+ * agents.key_fingerprint, so a local↔remote fingerprint match is a byte-for-byte
+ * proof of the same key. Returns undefined when no key has been generated yet:
+ * signing NEVER silently mints a key (the public key must be registered with the
+ * cloud first). Use registerAgentIdentity({ generateFingerprint: true }) to mint one.
+ */
+export function loadAgentSigningKey(agentId, env = process.env) {
+    migrateLegacyAgentKey(agentId, env);
+    const filepath = agentKeyPath(agentId);
+    if (!fs.existsSync(filepath))
+        return undefined;
+    const privateKeyPem = fs.readFileSync(filepath, 'utf-8');
+    const privateKey = crypto.createPrivateKey(privateKeyPem);
+    // @types/node 26 dropped the KeyObject overload from createPublicKey's signature
+    // (see buildIdentityKey) — cast to a parameter type the .d.ts still accepts.
+    const publicKeyPem = crypto
+        .createPublicKey(privateKey)
+        .export({ type: 'spki', format: 'pem' })
+        .toString();
+    return { privateKeyPem, publicKeyPem, fingerprint: fingerprintPublicKeyPem(publicKeyPem) };
+}
+/**
+ * Ensure an agent has an Ed25519 signing key, WITHOUT rotating an existing one
+ * (pln#101). Generates the keypair on first call, returns the existing key on
+ * subsequent calls — so it is safe to run after the public key has been
+ * approved in the cloud (rotating would break the fingerprint match). Returns
+ * the SPKI public-key PEM + its sha256(pem) fingerprint.
+ */
+export function ensureAgentSigningKey(agentId, env = process.env) {
+    const key = buildIdentityKey(agentId, env, false);
+    if (!key)
+        throw new Error(`Failed to derive signing key for agent ${agentId}`);
+    return { publicKeyPem: key.public_key, fingerprint: key.fingerprint };
+}
 function withIdentityKey(agent, env = process.env, forceRegenerate = false) {
     return {
         ...agent,

package/dist/core/claims.js

@@ -14,6 +14,7 @@ import { loadSessionById } from './identity.js';
 import { loadState, persistState } from './state.js';
 import { createRuntimeEvent } from './events.js';
 import { emitRegistryPostImage, registryFaultPoint } from './events/registry-post-image.js';
+import { maybeEnqueueClaimTransition, isFederationEnqueueActive } from './federation-outbox.js';
 /** Parse duration string like '4h', '30m' to ms. */
 function parseTtl(value) {
     const match = /^(\d+)([mhd])$/i.exec(value.trim());
@@ -69,9 +70,26 @@ function saveClaimUnlocked(claim, cwd, options) {
     // pln#568 (I2): journal the post-image BEFORE the projection write, so a
     // crash can only leave the journal ahead of the projection, never behind.
     const created = !store.exists(parsed.id);
+    // Federation (pln#101): capture the PREVIOUS status BEFORE the write so we can
+    // diff it after (create or active↔terminal transition ⇒ enqueue for cloud
+    // sync). Only pay the prev-load when federation is actually active; this whole
+    // block runs under the store mutation mutex, which serializes rev reservation.
+    const fedActive = isFederationEnqueueActive(cwd, options?.federation?.suppressEnqueue);
+    let fedPrevStatus;
+    if (fedActive) {
+        try {
+            fedPrevStatus = loadClaimFromAnyDir(parsed.id, cwd).status;
+        }
+        catch {
+            fedPrevStatus = undefined;
+        }
+    }
     emitRegistryPostImage('claim', parsed, { created, agent: parsed.agent, agent_id: parsed.agent_id, session_id: parsed.session_id, cwd });
     registryFaultPoint('after_registry_journal');
     store.save(parsed);
+    if (fedActive) {
+        maybeEnqueueClaimTransition(parsed, fedPrevStatus, fedPrevStatus === undefined, cwd, options?.federation?.suppressEnqueue);
+    }
     const writeDir = claimsDir(cwd, 'write');
     for (const dirPath of claimDirs(cwd)) {
         if (dirPath === writeDir)

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

@@ -307,9 +307,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 +470,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 +530,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 +910,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 {