brainclaw 0.29.2 → 1.5.4

package/dist/core/execution-context.js

@@ -38,6 +38,8 @@ export function buildExecutionContext(options = {}) {
         branch,
         git_status: gitStatus,
         has_remote: hasRemote,
+        git_worktree: detectGitWorktree(cwd, runner),
+        commits_behind_main: branch ? detectCommitsBehindMain(cwd, branch, runner) : undefined,
         toolchains: detectToolchains(cwd, runner),
         env_signals: captureEnvSignals(env),
     };
@@ -50,6 +52,7 @@ export function compactExecutionContext(snapshot) {
         branch: snapshot.branch,
         git_status: snapshot.git_status,
         has_remote: snapshot.has_remote,
+        commits_behind_main: snapshot.commits_behind_main,
         toolchains: snapshot.toolchains.filter((tool) => tool.available),
     };
 }
@@ -64,7 +67,17 @@ export function renderExecutionContextSummary(snapshot, includeEnvSignals = fals
         lines.push(`Git branch: ${snapshot.branch}`);
     }
     lines.push(`Git status: ${snapshot.git_status}`);
+    if ('git_worktree' in snapshot && snapshot.git_worktree) {
+        const wt = snapshot.git_worktree;
+        lines.push(`Git worktree: ${wt.worktree_path}${wt.is_linked_worktree ? ' (linked)' : ' (main)'}`);
+        if (wt.is_linked_worktree) {
+            lines.push(`Main worktree: ${wt.main_worktree_path}`);
+        }
+    }
     lines.push(`Git remote: ${snapshot.has_remote ? 'configured' : 'none'}`);
+    if ('commits_behind_main' in snapshot && snapshot.commits_behind_main && snapshot.commits_behind_main > 0) {
+        lines.push(`⚠ Branch is ${snapshot.commits_behind_main} commit(s) behind master. Consider rebasing before editing.`);
+    }
     const availableToolchains = snapshot.toolchains.filter((tool) => tool.available);
     if (availableToolchains.length > 0) {
         lines.push(`Toolchains: ${availableToolchains.map((tool) => `${tool.name}${tool.version ? ` ${tool.version}` : ''}`).join(', ')}`);
@@ -95,6 +108,33 @@ function detectGitBranch(cwd, runner) {
     const branch = result.stdout.trim();
     return branch && branch !== 'HEAD' ? branch : undefined;
 }
+function detectGitWorktree(cwd, runner) {
+    const gitDir = runner('git', ['rev-parse', '--git-dir'], cwd);
+    const toplevel = runner('git', ['rev-parse', '--show-toplevel'], cwd);
+    if (gitDir.status !== 0 || toplevel.status !== 0)
+        return undefined;
+    const gitDirPath = path.resolve(cwd, gitDir.stdout.trim());
+    const worktreePath = toplevel.stdout.trim();
+    // Main worktree: resolve via git-common-dir (points to the shared .git for linked worktrees)
+    const commonDir = runner('git', ['rev-parse', '--git-common-dir'], cwd);
+    let mainWorktreePath = worktreePath;
+    let isLinked = false;
+    if (commonDir.status === 0) {
+        const commonDirPath = path.resolve(cwd, commonDir.stdout.trim());
+        // For linked worktrees, git-common-dir !== git-dir
+        if (path.normalize(commonDirPath) !== path.normalize(gitDirPath)) {
+            isLinked = true;
+            // The main worktree is the parent of the common .git directory
+            mainWorktreePath = path.dirname(commonDirPath);
+        }
+    }
+    return {
+        git_dir: gitDirPath,
+        worktree_path: worktreePath,
+        main_worktree_path: mainWorktreePath,
+        is_linked_worktree: isLinked,
+    };
+}
 function detectGitStatus(cwd, runner) {
     const result = runner('git', ['status', '--porcelain'], cwd);
     if (result.status !== 0) {
@@ -109,6 +149,29 @@ function detectGitRemote(cwd, runner) {
     }
     return result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).length > 0;
 }
+/**
+ * Detect how many commits the current branch is behind the main branch.
+ * Tries master then main as the reference branch.
+ * Returns undefined if not in a git repo or on the main branch itself.
+ */
+function detectCommitsBehindMain(cwd, currentBranch, runner) {
+    // Don't check if already on main branch
+    if (currentBranch === 'master' || currentBranch === 'main')
+        return undefined;
+    // Try both master and main, return the highest count found.
+    // This handles repos where both branches exist but only one is the real reference.
+    let maxBehind;
+    for (const mainBranch of ['master', 'main']) {
+        const result = runner('git', ['rev-list', '--count', `${currentBranch}..${mainBranch}`], cwd);
+        if (result.status === 0) {
+            const count = parseInt(result.stdout.trim(), 10);
+            if (!isNaN(count) && (maxBehind === undefined || count > maxBehind)) {
+                maxBehind = count;
+            }
+        }
+    }
+    return maxBehind;
+}
 function detectToolchains(cwd, runner) {
     if (runner === defaultRunner && cachedToolchains) {
         return cachedToolchains;

package/dist/core/execution-profile.js

@@ -0,0 +1,270 @@
+/**
+ * Agent execution profile (pln#496 step stp_0339a439).
+ *
+ * The dispatch system needs to know how to spawn each agent on each host:
+ *   - which shell to invoke (`set X=...` for cmd, `$env:X=...` for pwsh,
+ *     `X=...` for bash/zsh)
+ *   - which OS we are on (path quoting, sandbox semantics)
+ *   - where Node lives if we have to invoke the CLI binary directly
+ *   - which spawn mechanism (fresh CLI, long-running app-server, IDE
+ *     extension IPC) is right for this agent
+ *   - how to set the working directory (just spawn from cwd, cd into a
+ *     worktree first, or rely solely on env vars)
+ *   - which sandbox profile to ask the agent for (codex needs
+ *     `workspace-write` on local-only commits per
+ *     trap_review_sandbox_blocks_source_access)
+ *
+ * Today the dispatcher hardcodes most of this in OS-specific branches
+ * (`set X=...` strings inside a Windows-only branch, etc.). The agent
+ * registry has the right level of granularity but no place to record
+ * execution-relevant facts. This module fills that gap.
+ *
+ * Design choices:
+ *
+ * 1. **Host vs per-agent fields.** The host detection is one value
+ *    (this machine is Windows + pwsh + nodejs). Each agent inherits the
+ *    host context and may override individual fields (e.g. an agent that
+ *    needs bash even on Windows would override `shell`). Lookup uses
+ *    `getExecutionProfile(agentName, inventory)` which merges host +
+ *    agent override and supplies safe defaults so the dispatcher never
+ *    receives undefined for required fields.
+ *
+ * 2. **Backward-compatible.** Both the host record and the per-agent
+ *    override are optional. Inventories written before this module
+ *    deserialize cleanly; the dispatcher applies defaults via
+ *    `getExecutionProfile`. The OS-aware spawn step (stp_a9afe59d)
+ *    consumes these fields in a follow-up commit.
+ *
+ * 3. **No assumption about sandbox semantics.** `sandbox_profile` is a
+ *    hint to the agent invocation template; not every agent honours it,
+ *    and brainclaw does not enforce sandbox at the OS level. The default
+ *    is 'none' so legacy invocations stay literally identical.
+ *
+ * @module
+ */
+import { spawnSync } from 'node:child_process';
+// ── Types ──────────────────────────────────────────────────────────────────
+/** Shells brainclaw knows how to emit env-set syntax for. */
+export const SHELLS = ['bash', 'pwsh', 'cmd', 'sh', 'zsh'];
+/** Coarse OS family. Matches process.platform's coverage of brainclaw's tier-A platforms. */
+export const OPERATING_SYSTEMS = ['win', 'mac', 'linux'];
+/** Spawn mechanism the dispatcher should use for this agent. */
+export const SPAWN_METHODS = ['cli', 'app-server', 'extension-ipc', 'cli_spawn_legacy'];
+/** Working-directory strategy at spawn time. */
+export const WORKING_DIR_STRATEGIES = ['cwd', 'worktree-cd', 'env-only'];
+/** Sandbox hint passed to the agent invocation template. */
+export const SANDBOX_PROFILES = ['workspace-write', 'read-only', 'none'];
+// ── Detection ──────────────────────────────────────────────────────────────
+/**
+ * Map process.platform onto our coarse OS enum. Anything outside the
+ * tier-A trio resolves to 'linux' as the most permissive default — it
+ * does not lie about what the host is, but it lets the dispatcher pick
+ * a working set of shell-syntax decisions instead of refusing to spawn.
+ */
+function detectOs(platform = process.platform) {
+    if (platform === 'win32')
+        return 'win';
+    if (platform === 'darwin')
+        return 'mac';
+    return 'linux';
+}
+/**
+ * Sniff the host shell from environment variables. POSIX uses $SHELL;
+ * Windows has neither $SHELL nor a single canonical answer — we look at
+ * COMSPEC (cmd) and PSModulePath (pwsh) and prefer pwsh when both are
+ * set since modern Windows agent integrations rely on it (codex CLI
+ * resolves through pwsh.exe on Windows per pln#475).
+ */
+function detectShell(env = process.env, platform = process.platform) {
+    // Windows first because it lacks $SHELL and uses different env vars.
+    if (platform === 'win32') {
+        if (env.PSModulePath)
+            return 'pwsh';
+        if (env.COMSPEC)
+            return 'cmd';
+        // Fallback: assume pwsh on modern Windows. Empirically more agents
+        // tolerate pwsh than cmd, and this matches the brainclaw dispatch
+        // template that ships today.
+        return 'pwsh';
+    }
+    const shellEnv = env.SHELL;
+    if (shellEnv) {
+        const lower = shellEnv.toLowerCase();
+        if (lower.endsWith('/zsh') || lower.endsWith('\\zsh'))
+            return 'zsh';
+        if (lower.endsWith('/bash') || lower.endsWith('\\bash'))
+            return 'bash';
+        if (lower.endsWith('/sh') || lower.endsWith('\\sh'))
+            return 'sh';
+        // Other shells (fish, csh, …) — bash is the safest fallback for
+        // brainclaw's `X=value cmd` env-set pattern.
+        return 'bash';
+    }
+    // POSIX without $SHELL — extremely rare but bash is the canonical default.
+    return 'bash';
+}
+/**
+ * Best-effort path to the running Node binary.
+ *
+ * `process.execPath` is the canonical answer for the current process —
+ * it always points to the Node that's running brainclaw, which is the
+ * Node any spawned agent should also see if PATH is misconfigured.
+ *
+ * On Windows this is a `.exe`; on POSIX it's a binary. Either way, the
+ * dispatcher can fall back to it when `node` is not on PATH.
+ */
+function detectNodePath() {
+    try {
+        return process.execPath || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function detectHostExecutionProfile(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    return {
+        shell: detectShell(env, platform),
+        os: detectOs(platform),
+        node_path: detectNodePath(),
+        spawn_method: 'cli',
+        working_dir_strategy: 'cwd',
+        sandbox_profile: 'none',
+    };
+}
+// ── Resolution ─────────────────────────────────────────────────────────────
+/**
+ * Hard-coded defaults that apply when neither the host record nor the
+ * per-agent override specify a field. Kept centralised here so the
+ * dispatcher never has to encode them.
+ */
+const DEFAULT_PROFILE = {
+    shell: 'bash',
+    os: 'linux',
+    node_path: undefined,
+    spawn_method: 'cli',
+    working_dir_strategy: 'cwd',
+    sandbox_profile: 'none',
+};
+/**
+ * Merge host + per-agent override + module defaults. The agent override
+ * takes priority over the host, the host takes priority over module
+ * defaults. Missing fields cascade silently — no exception is ever
+ * thrown for a partially populated input, which matters because
+ * inventories saved before this module gained the new fields must still
+ * resolve cleanly.
+ */
+export function resolveExecutionProfile(host, agentOverride) {
+    return {
+        shell: agentOverride?.shell ?? host?.shell ?? DEFAULT_PROFILE.shell,
+        os: agentOverride?.os ?? host?.os ?? DEFAULT_PROFILE.os,
+        node_path: agentOverride?.node_path ?? host?.node_path ?? DEFAULT_PROFILE.node_path,
+        spawn_method: agentOverride?.spawn_method ?? host?.spawn_method ?? DEFAULT_PROFILE.spawn_method,
+        working_dir_strategy: agentOverride?.working_dir_strategy ?? host?.working_dir_strategy ?? DEFAULT_PROFILE.working_dir_strategy,
+        sandbox_profile: agentOverride?.sandbox_profile ?? host?.sandbox_profile ?? DEFAULT_PROFILE.sandbox_profile,
+    };
+}
+// ── Env-set rendering ──────────────────────────────────────────────────────
+/**
+ * Render a single `KEY=VALUE` environment assignment in the syntax of
+ * the named shell. Used by the OS-aware spawn step (stp_a9afe59d) to
+ * generate spawn commands the host shell will actually parse.
+ *
+ *   bash/zsh/sh   →  KEY="VALUE"
+ *   pwsh          →  $env:KEY="VALUE"
+ *   cmd           →  set KEY=VALUE
+ *
+ * Values are double-quoted in shells that support it; cmd uses the bare
+ * `set NAME=VALUE` form because cmd's quoting rules are pathological for
+ * embedded equals/quotes. Callers who need cmd-safe values must escape
+ * upstream — this helper is intentionally thin.
+ */
+export function renderEnvSet(shell, key, value) {
+    switch (shell) {
+        case 'pwsh': return `$env:${key}="${value}"`;
+        case 'cmd': return `set ${key}=${value}`;
+        case 'bash':
+        case 'zsh':
+        case 'sh':
+        default: return `${key}="${value}"`;
+    }
+}
+// ── Spawn prefix (used by dispatcher + execution adapters) ─────────────────
+/**
+ * Build a shell-correct prefix for an inline env-var set followed by a
+ * command. Centralises what dispatcher.ts:buildEnvPrefix,
+ * execution-adapters.ts:buildManualEnvPrefix, and the inline branch in
+ * mcp.ts spawn dispatch were duplicating before pln#496 step
+ * stp_a9afe59d.
+ *
+ * Output by shell (legacy bytes preserved for bash and cmd — see codex
+ * review findings on commit 87a9f73, asgn_02c3c742):
+ *   bash / zsh / sh : `BRAINCLAW_CLAIM_ID=clm_xxx `      (unquoted, legacy)
+ *   pwsh            : `$env:BRAINCLAW_CLAIM_ID="clm_xxx"; `
+ *   cmd             : `set BRAINCLAW_CLAIM_ID=clm_xxx && `
+ *
+ * The unquoted bash form matches the pre-pln#496 dispatcher.ts:buildEnvPrefix
+ * output exactly, so any caller string-matching the legacy bytes keeps
+ * working. `renderEnvSet` still emits the quoted form for general use.
+ *
+ * Returns an empty string when claimId is empty or the dry-run sentinel —
+ * callers use the prefix as `${prefix}<command>` so concatenation stays
+ * safe.
+ *
+ * Defaults: when `shell` is omitted:
+ *   - On Windows hosts → `cmd`. The historical brainclaw behaviour
+ *     unconditionally used `set X=Y && ` on Windows regardless of whether
+ *     pwsh was available. Picking pwsh based on PSModulePath sniffing
+ *     would be a regression for hosts whose dispatch pipeline runs
+ *     through child_process.spawn(shell:true) — Windows resolves that
+ *     to cmd, not pwsh, so a pwsh prefix would not parse. Pwsh becomes
+ *     opt-in via explicit `{ shell: 'pwsh' }` (used by Phase 3 app-server
+ *     integrations that already speak pwsh natively).
+ *   - On POSIX hosts → host detection (bash / zsh / sh / default bash).
+ */
+export function buildClaimEnvPrefix(claimId, options) {
+    if (!claimId || claimId === '(dry-run)')
+        return '';
+    let shell;
+    if (options?.shell) {
+        shell = options.shell;
+    }
+    else {
+        // Pre-pln#496 default: Windows always emits cmd syntax. The smart
+        // detector exists for explicit callers (Phase 3 app-server) that
+        // know they want pwsh. See codex review on commit 87a9f73 — the
+        // PSModulePath sniff was a regression when used as the host
+        // default for the legacy spawn pipeline.
+        shell = process.platform === 'win32' ? 'cmd' : detectHostExecutionProfile().shell;
+    }
+    switch (shell) {
+        case 'cmd': return `set BRAINCLAW_CLAIM_ID=${claimId} && `;
+        case 'pwsh': return `$env:BRAINCLAW_CLAIM_ID="${claimId}"; `;
+        case 'bash':
+        case 'zsh':
+        case 'sh':
+        default: return `BRAINCLAW_CLAIM_ID=${claimId} `;
+    }
+}
+// ── Verification helper (used by setup / doctor) ───────────────────────────
+/**
+ * Try `node --version` from the resolved profile's `node_path` to confirm
+ * the binary actually executes. Returns the version string when it does,
+ * undefined otherwise. Cheap enough to call from setup; not called from
+ * the dispatch hot path.
+ */
+export function verifyNodeBinary(nodePath, timeoutMs = 5000) {
+    if (!nodePath)
+        return undefined;
+    try {
+        const result = spawnSync(nodePath, ['--version'], { encoding: 'utf-8', timeout: timeoutMs, windowsHide: true });
+        if (result.status !== 0)
+            return undefined;
+        return (result.stdout ?? '').trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=execution-profile.js.map

package/dist/core/execution.js

@@ -0,0 +1,255 @@
+/**
+ * E2E dispatch execution — spawn agent processes after claim+inbox delivery.
+ *
+ * This module bridges the gap between dispatch (claim + inbox + brief) and
+ * actual agent execution. It detects whether the coordinator can spawn CLI
+ * processes and, if so, launches the agent in a detached subprocess.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getCapabilityProfile } from './agent-capability.js';
+import { appendAuditEntry } from './audit.js';
+import { loadAllSessions } from './identity.js';
+import { loadConfig } from './config.js';
+import { loadAssignment } from './assignments.js';
+import { defaultExecutionAdapter, } from './execution-adapters.js';
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Compute the brief-ack sentinel file path for an assignment.
+ *
+ * pln#476 — half-2 of trp#59. The dispatcher prefixes the spawn command
+ * with a shell `touch`/`type nul >` step that creates this file BEFORE
+ * the agent binary executes. Its existence proves the spawn actually
+ * started doing work — independent of whether the agent has the
+ * brainclaw MCP wired (codex spawned without MCP cannot call
+ * bclaw_assignment_update; the ack file lets us recognize a healthy
+ * spawn anyway).
+ */
+export function getAssignmentAckPath(cwd, assignmentId) {
+    return path.join(cwd, '.brainclaw', 'coordination', 'runtime', 'ack', `${assignmentId}.ack`);
+}
+function isAssignmentAcked(assignmentId, cwd) {
+    // Fast path: the brief-ack sentinel was written by the worker shell.
+    if (fs.existsSync(getAssignmentAckPath(cwd, assignmentId)))
+        return true;
+    // Standard path: the worker called bclaw_assignment_update via MCP and
+    // moved the assignment past the offered/created state.
+    const assignment = loadAssignment(assignmentId, cwd);
+    return !!assignment && assignment.status !== 'created' && assignment.status !== 'offered';
+}
+async function waitForAssignmentHandshake(assignmentId, cwd, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (isAssignmentAcked(assignmentId, cwd))
+            return true;
+        await sleep(100);
+    }
+    return isAssignmentAcked(assignmentId, cwd);
+}
+// ── Helpers ────────────────────────────────────────────────
+/** Parse a duration string like '4h', '30m', '1d' to milliseconds. */
+function parseDurationMs(value) {
+    const match = /^(\d+)([mhd])$/i.exec(value.trim());
+    if (!match)
+        return 4 * 3_600_000; // default 4h
+    const amount = parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    if (unit === 'm')
+        return amount * 60_000;
+    if (unit === 'h')
+        return amount * 3_600_000;
+    return amount * 86_400_000;
+}
+export function checkActiveInstance(agentName, cwd) {
+    const sessions = loadAllSessions(cwd);
+    let ttlStr = '4h';
+    try {
+        ttlStr = loadConfig(cwd).implicit_session_ttl ?? '4h';
+    }
+    catch { /* use default */ }
+    const SESSION_STALE_MS = parseDurationMs(ttlStr);
+    const now = Date.now();
+    const activeSessions = [];
+    for (const session of sessions) {
+        if (session.agent !== agentName)
+            continue;
+        const lastSeen = new Date(session.last_seen_at).getTime();
+        if (isNaN(lastSeen))
+            continue;
+        if (now - lastSeen < SESSION_STALE_MS) {
+            activeSessions.push(session.session_id);
+        }
+    }
+    const profile = getCapabilityProfile(agentName);
+    const maxAllowed = profile?.max_concurrent_tasks ?? 1;
+    const activeCount = activeSessions.length;
+    const canSpawnMore = activeCount < maxAllowed;
+    return {
+        active: !canSpawnMore, // backward compat: active=true means "cannot spawn more"
+        canSpawnMore,
+        activeCount,
+        maxAllowed,
+        reason: canSpawnMore
+            ? `Agent ${agentName} has capacity (${activeCount}/${maxAllowed} slots used)`
+            : `Agent ${agentName} at capacity (${activeCount}/${maxAllowed} slots used)`,
+        activeSessions,
+    };
+}
+// ── Spawn detection ─────────────────────────────────────────
+/**
+ * Check if the coordinator can spawn an agent as a CLI subprocess.
+ *
+ * Returns canSpawn=true when:
+ * 1. The target agent has runtime.canBeSpawnedCli = true in its profile
+ * 2. The current process is NOT running inside an MCP stdio sandbox
+ *    (heuristic: stdin is a TTY, or BRAINCLAW_CAN_SPAWN env is set)
+ */
+export function canSpawnAgent(agentName) {
+    return defaultExecutionAdapter.canSpawn(agentName);
+}
+// ── Process spawning ────────────────────────────────────────
+/**
+ * Spawn an agent CLI process in a detached, fire-and-forget mode.
+ *
+ * The spawned process is fully detached from the parent — it won't block
+ * the coordinator and survives parent exit. The PID is returned for
+ * tracking purposes.
+ */
+export function executeDispatchedCommand(invoke, options) {
+    return defaultExecutionAdapter.start(invoke, options);
+}
+// ── Execution orchestrator ──────────────────────────────────
+/**
+ * Attempt E2E execution after dispatch delivery.
+ *
+ * This is the main entry point called by bclaw_coordinate and bclaw_dispatch
+ * after claim+inbox+brief delivery is complete.
+ *
+ * - 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
+ */
+export async function attemptExecution(invoke, options) {
+    const adapter = options.adapter ?? defaultExecutionAdapter;
+    // No invoke command available (IDE-only agents, etc.)
+    if (!invoke) {
+        return { execution_status: 'inbox_only' };
+    }
+    const spawnCheck = adapter.canSpawn(options.agent);
+    // Opt-out or can't spawn: return command for manual execution
+    // Prepend BRAINCLAW_CLAIM_ID so manual copy-paste still routes correctly
+    if (!options.autoExecute || !spawnCheck.canSpawn) {
+        const manual = adapter.prepareManualCommand(invoke, options);
+        return {
+            execution_status: 'command_ready_manual',
+            command: manual.command,
+            shell: manual.shell,
+        };
+    }
+    // Capacity guard: skip if agent is at max concurrent tasks
+    if (options.cwd) {
+        const instanceCheck = checkActiveInstance(options.agent, options.cwd);
+        if (!instanceCheck.canSpawnMore) {
+            appendAuditEntry({
+                actor: options.dispatcherAgent,
+                actor_id: options.dispatcherAgentId,
+                action: 'spawn_failed',
+                item_id: options.claimId,
+                item_type: 'claim',
+                scope: options.agent,
+                after: { reason: instanceCheck.reason, active_sessions: instanceCheck.activeSessions, skipped: true },
+            }, options.cwd);
+            const manual = adapter.prepareManualCommand(invoke, options);
+            return {
+                execution_status: 'command_ready_manual',
+                command: manual.command,
+                shell: manual.shell,
+                error: `Spawn skipped: ${instanceCheck.reason}. Use the command manually.`,
+                failure_kind: 'spawn_capacity',
+            };
+        }
+    }
+    // Attempt spawn (await handles both sync and async adapters)
+    try {
+        // pln#476: pass ackRoot=options.cwd so the spawn wrap writes the
+        // brief-ack sentinel under the project's coordination dir (not the
+        // worktree's local store), where waitForAssignmentHandshake reads.
+        const result = await adapter.start(invoke, { ...options, ackRoot: options.cwd });
+        if (options.assignmentId && options.cwd) {
+            // pln#475: TTL bumped from 5000 → 30000ms. Real workers (claude-code,
+            // codex) take 8–15s to load the runtime + open the inbox + call
+            // bclaw_assignment_update(accepted). 5s caused legitimate spawns to be
+            // marked failed (trp#59 — observed during P1 dispatch on 2026-04-25).
+            // Override with BRAINCLAW_HANDSHAKE_TIMEOUT_MS for very fast / very slow
+            // environments. options.handshakeTimeoutMs (programmatic) wins over env.
+            const envTimeout = process.env.BRAINCLAW_HANDSHAKE_TIMEOUT_MS;
+            const parsedEnvTimeout = envTimeout ? Number.parseInt(envTimeout, 10) : NaN;
+            const handshakeTimeoutMs = options.handshakeTimeoutMs ??
+                (Number.isFinite(parsedEnvTimeout) && parsedEnvTimeout > 0 ? parsedEnvTimeout : 30_000);
+            const handshakeOk = await waitForAssignmentHandshake(options.assignmentId, options.cwd, handshakeTimeoutMs);
+            if (!handshakeOk) {
+                appendAuditEntry({
+                    actor: options.dispatcherAgent,
+                    actor_id: options.dispatcherAgentId,
+                    action: 'spawn_failed',
+                    item_id: options.claimId,
+                    item_type: 'claim',
+                    scope: options.agent,
+                    after: { reason: `No assignment handshake within ${handshakeTimeoutMs}ms`, pid: result.pid, command: invoke.bashCommand },
+                }, options.cwd);
+                const manual = adapter.prepareManualCommand(invoke, options);
+                return {
+                    execution_status: 'command_ready_manual',
+                    command: manual.command,
+                    shell: manual.shell,
+                    error: `Spawn launched (pid ${result.pid}) but assignment ${options.assignmentId} did not acknowledge within ${handshakeTimeoutMs}ms`,
+                    failure_kind: 'spawn_no_handshake',
+                    pid: result.pid,
+                };
+            }
+        }
+        // Audit success
+        appendAuditEntry({
+            actor: options.dispatcherAgent,
+            actor_id: options.dispatcherAgentId,
+            action: 'agent_spawned',
+            item_id: options.claimId,
+            item_type: 'claim',
+            scope: options.agent,
+            after: { pid: result.pid, command: invoke.bashCommand, worktree_path: options.worktreePath },
+        }, options.cwd);
+        return {
+            execution_status: 'delivered_and_started',
+            pid: result.pid,
+            command: invoke.bashCommand,
+            started_at: result.started_at,
+        };
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        // Audit failure
+        appendAuditEntry({
+            actor: options.dispatcherAgent,
+            actor_id: options.dispatcherAgentId,
+            action: 'spawn_failed',
+            item_id: options.claimId,
+            item_type: 'claim',
+            scope: options.agent,
+            after: { error: errorMsg, command: invoke.bashCommand },
+        }, options.cwd);
+        // Graceful fallback — include BRAINCLAW_CLAIM_ID for manual routing
+        const manual = adapter.prepareManualCommand(invoke, options);
+        return {
+            execution_status: 'command_ready_manual',
+            command: manual.command,
+            shell: manual.shell,
+            error: `Spawn failed (${errorMsg}), falling back to manual execution`,
+            failure_kind: 'spawn_failed',
+        };
+    }
+}
+//# sourceMappingURL=execution.js.map