brainclaw 1.7.0 → 1.7.2

package/dist/core/execution-adapters.js

@@ -4,12 +4,21 @@ import path from 'node:path';
 import { buildClaimEnvPrefix } from './execution-profile.js';
 import { getCapabilityProfile } from './agent-capability.js';
 import { nowISO } from './ids.js';
+import { ensureRuntimeDirs, getRuntimeLogPath, getRuntimeSignalPath, } from './runtime-signals.js';
+export function buildAckWrapCommand(bashCommand, paths, isWin32) {
+    const touch = isWin32
+        ? (p) => `type nul > "${p}"`
+        : (p) => `touch "${p}"`;
+    const redirected = `${bashCommand} > "${paths.stdoutLog}" 2> "${paths.stderrLog}"`;
+    return (`${touch(paths.ackPath)} && ` +
+        `( ${redirected} && ${touch(paths.completedPath)} || ${touch(paths.failedPath)} )`);
+}
 /**
  * Check if a binary is resolvable on the system PATH.
  * On Windows, `spawn({shell:true})` always succeeds (launches cmd.exe),
  * masking ENOENT for missing binaries. This pre-check catches that.
  */
-function resolveBinaryOnPath(binary) {
+export function resolveBinaryOnPath(binary) {
     // Absolute or relative path — check directly
     if (binary.includes('/') || binary.includes('\\')) {
         return fs.existsSync(binary) ? binary : undefined;
@@ -90,48 +99,32 @@ export class CliExecutionAdapter {
         const spawnExecutable = resolvedExecutable ?? invoke.executable;
         const useShell = isWin32 && /\.(cmd|bat)$/i.test(spawnExecutable);
         const needsStdin = invoke.promptDelivery === 'stdin_pipe' && invoke.promptText;
-        // pln#504: open per-assignment log files for stdout/stderr capture so silent
-        // worker deaths (trp#292) become diagnosable. Previously stdio used 'ignore'
-        // for stdout+stderr — anything the worker said vanished. Best-effort: on
-        // failure to open log files we fall back to the legacy 'ignore' behaviour
-        // rather than abort the spawn.
+        // pln#520 step 4: when we ack-wrap, the SHELL redirects stdout/stderr to the
+        // per-assignment log files (fds passed via stdio are NOT inherited through
+        // the cmd.exe → .cmd → node shim — the empty-logs bug of can_f792cacd), and
+        // the wrapper emits completed/failed sentinels mechanically. So the spawned
+        // process just ignores stdout/stderr here. stdin stays a pipe when the
+        // prompt is delivered that way (the grouped agent command inherits it).
         const useAckWrap = !!(options.assignmentId && (options.ackRoot ?? options.worktreePath));
-        let logFds;
-        if (useAckWrap) {
-            try {
-                const logRoot = options.ackRoot ?? options.worktreePath;
-                const logDir = path.join(logRoot, '.brainclaw', 'coordination', 'runtime', 'log');
-                fs.mkdirSync(logDir, { recursive: true });
-                logFds = {
-                    stdout: fs.openSync(path.join(logDir, `${options.assignmentId}.stdout.log`), 'a'),
-                    stderr: fs.openSync(path.join(logDir, `${options.assignmentId}.stderr.log`), 'a'),
-                };
-            }
-            catch {
-                // Log capture is best-effort — never block the spawn on logging issues.
-                logFds = undefined;
-            }
-        }
         const stdinTarget = needsStdin ? 'pipe' : 'ignore';
-        const stdoutTarget = logFds ? logFds.stdout : 'ignore';
-        const stderrTarget = logFds ? logFds.stderr : 'ignore';
-        const stdio = [stdinTarget, stdoutTarget, stderrTarget];
-        // pln#476: wrap the spawn command with a brief-ack step so the worker
-        // shell touches a sentinel file BEFORE the agent binary runs.
-        // waitForAssignmentHandshake checks that file as evidence the spawn
-        // executed — needed for codex (which lacks the brainclaw MCP context
-        // to call bclaw_assignment_update). When ackRoot/assignmentId are
-        // omitted, we keep the original direct-binary spawn.
+        const stdio = [stdinTarget, 'ignore', 'ignore'];
+        // pln#476 + pln#520 step 4: wrap the spawn so the worker shell touches the
+        // pre-exec `ack` sentinel, redirects logs at the shell level, and emits a
+        // completed/failed sentinel from the agent's exit code. waitForAssignmentHandshake
+        // checks the ack file; the reconciler trusts the completed/failed/heartbeat
+        // sentinels rather than the (untrustworthy) wrapper pid. When ackRoot/
+        // assignmentId are omitted, we keep the original direct-binary spawn.
         let child;
         if (useAckWrap) {
-            const ackRoot = options.ackRoot ?? options.worktreePath;
-            const ackDir = path.join(ackRoot, '.brainclaw', 'coordination', 'runtime', 'ack');
-            const ackPath = path.join(ackDir, `${options.assignmentId}.ack`);
-            fs.mkdirSync(ackDir, { recursive: true });
-            const ackStep = isWin32
-                ? `type nul > "${ackPath}"`
-                : `touch "${ackPath}"`;
-            const wrappedCmd = `${ackStep} && ${invoke.bashCommand}`;
+            const signalRoot = options.ackRoot ?? options.worktreePath;
+            ensureRuntimeDirs(signalRoot);
+            const wrappedCmd = buildAckWrapCommand(invoke.bashCommand, {
+                ackPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'ack'),
+                completedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'completed'),
+                failedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'failed'),
+                stdoutLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stdout'),
+                stderrLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stderr'),
+            }, isWin32);
             child = spawn(wrappedCmd, [], {
                 detached: !isWin32,
                 shell: true,
@@ -163,18 +156,6 @@ export class CliExecutionAdapter {
             child.stdin.end();
         }
         child.unref();
-        // Close the parent's copies of the log file descriptors. The child has its
-        // own dup'd copies and will keep writing to them after we return.
-        if (logFds) {
-            try {
-                fs.closeSync(logFds.stdout);
-            }
-            catch { /* best-effort */ }
-            try {
-                fs.closeSync(logFds.stderr);
-            }
-            catch { /* best-effort */ }
-        }
         const pid = child.pid;
         if (!pid) {
             throw new Error(`Failed to spawn agent ${options.agent}: no PID returned`);

package/dist/core/execution.js

@@ -8,8 +8,8 @@
  * @module
  */
 import fs from 'node:fs';
-import path from 'node:path';
-import { getCapabilityProfile } from './agent-capability.js';
+import { resolveConcurrencyLimit, resolveResourceKey } from './agent-capability.js';
+import { getRuntimeSignalPath } from './runtime-signals.js';
 import { appendAuditEntry } from './audit.js';
 import { loadAllSessions } from './identity.js';
 import { loadConfig } from './config.js';
@@ -30,7 +30,7 @@ function sleep(ms) {
  * spawn anyway).
  */
 export function getAssignmentAckPath(cwd, assignmentId) {
-    return path.join(cwd, '.brainclaw', 'coordination', 'runtime', 'ack', `${assignmentId}.ack`);
+    return getRuntimeSignalPath(cwd, assignmentId, 'ack');
 }
 function isAssignmentAcked(assignmentId, cwd) {
     // Fast path: the brief-ack sentinel was written by the worker shell.
@@ -73,9 +73,13 @@ export function checkActiveInstance(agentName, cwd) {
     catch { /* use default */ }
     const SESSION_STALE_MS = parseDurationMs(ttlStr);
     const now = Date.now();
+    // pln#520 step 3: pool active sessions by host-binary resource so all
+    // identities of one binary (e.g. claude-code + claude-sonnet → `claude`)
+    // count together against a shared cap.
+    const targetResource = resolveResourceKey(agentName);
     const activeSessions = [];
     for (const session of sessions) {
-        if (session.agent !== agentName)
+        if (resolveResourceKey(session.agent) !== targetResource)
             continue;
         const lastSeen = new Date(session.last_seen_at).getTime();
         if (isNaN(lastSeen))
@@ -84,18 +88,20 @@ export function checkActiveInstance(agentName, cwd) {
             activeSessions.push(session.session_id);
         }
     }
-    const profile = getCapabilityProfile(agentName);
-    const maxAllowed = profile?.max_concurrent_tasks ?? 1;
+    // Limit resolved from the chain (default unlimited for parallelizable CLI
+    // agents; structural floor for non-spawnable IDE agents). Infinity → no cap.
+    const maxAllowed = resolveConcurrencyLimit(agentName);
     const activeCount = activeSessions.length;
     const canSpawnMore = activeCount < maxAllowed;
+    const capLabel = Number.isFinite(maxAllowed) ? String(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)`,
+            ? `Agent ${agentName} has capacity (${activeCount}/${capLabel} slots used)`
+            : `Agent ${agentName} at capacity (${activeCount}/${capLabel} slots used)`,
         activeSessions,
     };
 }

package/dist/core/identity.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { detectAiAgent } from './ai-agent-detection.js';
 import { requireRegisteredAgentIdentity } from './agent-registry.js';
 import { loadConfig } from './config.js';
 import { resolveCurrentHostId } from './host.js';
@@ -75,31 +76,42 @@ export function loadCurrentSession(cwd) {
     const dir = sessionsDir(cwd);
     const currentUser = resolveCurrentUser();
     const currentAgent = resolveCurrentAgentName();
-    // 1. Look in sessions/ directory for a matching session
+    const explicitSessionId = resolveExplicitSessionId();
+    const ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
+    const now = Date.now();
+    if (explicitSessionId) {
+        const explicit = loadSessionById(explicitSessionId, cwd);
+        return explicit && isSessionAlive(explicit, ttlMs, now) ? explicit : undefined;
+    }
+    // 1. Look in sessions/ directory for the session owned by this process.
+    // Multiple parallel agents can have the same agent name/user in one repo;
+    // a live different PID is a different agent instance, not our session.
     if (fs.existsSync(dir) && currentAgent) {
         const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
-        const ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
-        const now = Date.now();
+        const legacyPidlessCandidates = [];
         for (const file of files) {
             try {
-                const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
-                const session = {
-                    ...CurrentSessionStateSchema.parse(migration.document),
-                    schema_version: migration.metadata.currentVersion,
-                };
+                const session = loadSessionFile(path.join(dir, file));
                 // Strict match: agent name must match, user must match (when both are known)
                 if (session.agent !== currentAgent)
                     continue;
                 const userMatch = !session.user || !currentUser || session.user === currentUser;
-                const alive = (now - Date.parse(session.last_seen_at)) <= ttlMs;
-                if (userMatch && alive) {
+                if (!userMatch || !isSessionAlive(session, ttlMs, now))
+                    continue;
+                if (session.pid === process.pid) {
                     return session;
                 }
+                if (session.pid === undefined) {
+                    legacyPidlessCandidates.push(session);
+                }
             }
             catch {
                 // skip invalid session files
             }
         }
+        if (legacyPidlessCandidates.length === 1) {
+            return legacyPidlessCandidates[0];
+        }
     }
     // 2. Legacy fallback: .current-session
     const legacyPath = path.join(memoryDir(cwd), LEGACY_SESSION_FILE);
@@ -246,9 +258,24 @@ function resolveCurrentUser() {
 function resolveCurrentAgentName() {
     if (process.env.BRAINCLAW_AGENT_NAME)
         return process.env.BRAINCLAW_AGENT_NAME;
-    if (process.env.CLAUDE_CODE_VERSION)
-        return 'claude-code';
-    return undefined;
+    return detectAiAgent()?.name;
+}
+function resolveExplicitSessionId(env = process.env) {
+    return env.BRAINCLAW_SESSION_ID?.trim()
+        || env.OPENCLAW_SESSION_ID?.trim()
+        || env.CLAUDE_SESSION_ID?.trim()
+        || env.COPILOT_SESSION_ID?.trim()
+        || undefined;
+}
+function loadSessionFile(filepath) {
+    const migration = loadVersionedJsonFile('current_session', filepath);
+    return {
+        ...CurrentSessionStateSchema.parse(migration.document),
+        schema_version: migration.metadata.currentVersion,
+    };
+}
+function isSessionAlive(session, ttlMs, now) {
+    return now - Date.parse(session.last_seen_at) <= ttlMs;
 }
 function loadConfigSafe(cwd) {
     try {

package/dist/core/instruction-templates.js

@@ -382,21 +382,22 @@ function renderAvailableTools() {
         '- `bclaw_remove(entity, id, purge?)` — soft-delete (or purge)',
         '- `bclaw_transition(entity, id, to)` — change status (e.g. plan todo→in_progress→done)',
         '',
-        'Entities supported by the grammar: plan, decision, constraint, trap, handoff, runtime_note, candidate, claim, action, assignment, agent_run.',
+        'Entities supported by the grammar: plan, decision, constraint, trap, handoff, runtime_note, candidate, sequence, claim, action, assignment, agent_run.',
         '',
         '**Cross-project access (pln#359):** every canonical-grammar call, `bclaw_context`, and `bclaw_coordinate` accept an optional `project: <name>` argument that routes the operation to a linked project (cross_project_links from `brainclaw link list` OR a workspace store-chain child). Identity is sourced from the caller; writes + audit land in the target. Unknown project names throw — no silent fallback. The CLI exposes the same as `--project <name>` (mutually exclusive with `--cwd`). Example: `bclaw_get(entity="trap", id="trp#36", project="brainclaw-site")`. Cross-project `bclaw_coordinate` is inbox-only — auto-spawn is force-disabled because the spawn cwd / worktree are tied to the target repo; the target agent picks the brief up async via its own `bclaw_work`.',
         '',
         '**Session + claims:** `bclaw_session_start`, `bclaw_session_end`, `bclaw_claim`, `bclaw_release_claim`',
         '**Plan steps:** `bclaw_add_step`, `bclaw_complete_step`, `bclaw_update_step`, `bclaw_delete_step`',
+        '**Sequences:** `bclaw_list_sequences`, `bclaw_create_sequence`, `bclaw_update_sequence`, `bclaw_delete_sequence` — create/activate ordered lanes for parallel dispatch. Item shape: `{ planId, stepId?, rank, hard_after?, soft_after?, lane?, scope_hint?, rationale? }`.',
         '**Inbox + handoffs:** `bclaw_read_inbox`, `bclaw_ack_message`, `bclaw_send_message`, `bclaw_correct_handoff`',
         '**Notes + search:** `bclaw_write_note`, `bclaw_quick_capture`, `bclaw_search`',
         '**Escalation (orchestrator path):**',
         '- Review / consult / assign another agent → `bclaw_coordinate(intent=review|consult|assign)` (use `open_loop=true` on review to also dispatch the reviewer turn)',
-        '- Parallel execute across a sequence\'s lanes → `bclaw_dispatch(intent=execute)`',
+        '- Parallel execute across a sequence\'s lanes → create/update an active sequence, then `bclaw_dispatch(intent=analysis)` and `bclaw_dispatch(intent=execute)`',
         '- Drive your turn in an already-opened loop → `bclaw_loop(intent=turn|complete_turn|advance|close)`',
         '**Setup + navigation:** `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`',
         '',
-        'Legacy per-entity tools (`bclaw_list_plans`, `bclaw_accept`, `bclaw_get_context`, `bclaw_dispatch_review`, …) were removed from the catalog at v1.0 — direct calls still succeed as a migration escape hatch but emit a redirect warning. See `docs/integrations/mcp.md` + `docs/concepts/mcp-governance.md` for the full catalog and stability contract; raw MCP clients can request advanced tools with `tools/list` params `{ catalog: "all" }`.',
+        'Legacy per-entity tools (`bclaw_list_plans`, `bclaw_accept`, `bclaw_get_context`, `bclaw_dispatch_review`, …) were removed from the catalog at v1.0 — direct calls still succeed as a migration escape hatch but emit a redirect warning. See `docs/integrations/mcp.md` + `docs/concepts/mcp-governance.md` for the full catalog and stability contract.',
     ].join('\n');
 }
 // ─── Live section renderers ─────────────────────────────────────────────────

package/dist/core/runtime-signals.js

@@ -0,0 +1,102 @@
+/**
+ * Runtime spawn signals (pln#520 steps 1 + 4) — the file-based, zero-MCP
+ * liveness channel between a dispatched worker and brainclaw.
+ *
+ * Why files, not the tracked pid: on Windows the ack-wrap spawn runs under
+ * `shell:true`, so `child.pid` is the cmd.exe wrapper (which dies early),
+ * NOT the real worker (cmd.exe → claude.cmd → node.exe). Reading that pid as
+ * dead produced false-negative `pid_dead_at_read` cancellations while the
+ * worker was alive and committing (can_f792cacd: 6 workers cancelled, then
+ * committed 4-7 min later). The fix is to stop trusting the wrapper pid and
+ * trust sentinels the worker / wrapper actually write:
+ *
+ *   - `ack`        — pre-exec; the spawn shell touched it BEFORE the agent ran
+ *                    (pln#476). Proves delivery, NOT that work started.
+ *   - `heartbeat`  — the worker writes `work_loop_reached{run_id,nonce}` as its
+ *                    FIRST action (step 0 of the generated brief) and refreshes
+ *                    it periodically. Distinct from `ack`: this is what flips
+ *                    execution_status to `started`.
+ *   - `completed` / `failed` — emitted MECHANICALLY by the spawn wrapper
+ *                    (`agentcmd && completed || failed`) so a dead wrapper pid
+ *                    is never misread as a silent failure.
+ *
+ * All paths are absolute under the project coordination dir so a worker in a
+ * worktree (or a sandboxed agent without MCP) can write them with a plain
+ * shell redirect.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+function runtimeDir(root) {
+    return path.join(root, '.brainclaw', 'coordination', 'runtime');
+}
+/**
+ * Absolute path for a runtime signal sentinel. `ack` keeps its historical
+ * `runtime/ack/<id>.ack` location (pln#476); the liveness signals live under
+ * `runtime/signal/<id>.<signal>`.
+ */
+export function getRuntimeSignalPath(root, assignmentId, signal) {
+    if (signal === 'ack') {
+        return path.join(runtimeDir(root), 'ack', `${assignmentId}.ack`);
+    }
+    return path.join(runtimeDir(root), 'signal', `${assignmentId}.${signal}`);
+}
+/** Absolute path for a captured stream log (`runtime/log/<id>.{stdout,stderr}.log`). */
+export function getRuntimeLogPath(root, assignmentId, stream) {
+    return path.join(runtimeDir(root), 'log', `${assignmentId}.${stream}.log`);
+}
+/** Ensure the ack / signal / log directories exist (best-effort, recursive). */
+export function ensureRuntimeDirs(root) {
+    const base = runtimeDir(root);
+    for (const sub of ['ack', 'signal', 'log']) {
+        fs.mkdirSync(path.join(base, sub), { recursive: true });
+    }
+}
+export function signalExists(root, assignmentId, signal) {
+    try {
+        return fs.existsSync(getRuntimeSignalPath(root, assignmentId, signal));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the heartbeat sentinel. The body is expected to be
+ * `work_loop_reached{run_id,nonce}` JSON, but a bare `touch` (empty file) still
+ * counts as a heartbeat — the mtime alone is a valid life-sign.
+ */
+export function readHeartbeat(root, assignmentId) {
+    const p = getRuntimeSignalPath(root, assignmentId, 'heartbeat');
+    try {
+        const stat = fs.statSync(p);
+        const info = { exists: true, mtimeMs: stat.mtimeMs };
+        try {
+            const raw = fs.readFileSync(p, 'utf-8').trim();
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed.run_id === 'string')
+                    info.runId = parsed.run_id;
+                if (typeof parsed.nonce === 'string')
+                    info.nonce = parsed.nonce;
+            }
+        }
+        catch { /* empty / non-JSON body — mtime still counts */ }
+        return info;
+    }
+    catch {
+        return { exists: false };
+    }
+}
+/** Read the tail of a captured stream log (for failed_silent diagnostics). */
+export function readLogTail(root, assignmentId, stream, maxBytes = 2000) {
+    try {
+        const p = getRuntimeLogPath(root, assignmentId, stream);
+        const content = fs.readFileSync(p, 'utf-8');
+        return content.length > maxBytes ? content.slice(content.length - maxBytes) : content;
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=runtime-signals.js.map

package/dist/core/spawn-check.js

@@ -0,0 +1,125 @@
+/**
+ * pln#520 step 2 — `brainclaw doctor --spawn-check`.
+ *
+ * A real, minimal spawn round-trip per installed agent BEFORE any real dispatch
+ * (and in CI). For each CLI-spawnable agent whose binary is on PATH, it spawns
+ * an ack-wrapped probe and waits for the ack + completed sentinels on the
+ * current host. This validates delivery + the spawn/handshake/sentinel
+ * mechanism on the actual agent×OS cell — it would have caught the 6 silent
+ * deaths of can_f792cacd before launching them (a worker that spawns but never
+ * reaches completion shows up here as `delivered_no_completion`).
+ *
+ * Uninstalled agents are skipped (`not_installed`), so this is safe to run in
+ * CI where most agent CLIs are absent.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildInvokeCommand, getSpawnableAgents, getCapabilityProfile, } from './agent-capability.js';
+import { defaultExecutionAdapter, resolveBinaryOnPath } from './execution-adapters.js';
+import { signalExists, readLogTail } from './runtime-signals.js';
+const DEFAULT_PROBE_TIMEOUT_MS = 15_000;
+const DEFAULT_PROBE_PROMPT = 'Reply with exactly: OK';
+async function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** Check one agent's spawn round-trip. Exposed for focused testing. */
+export async function checkAgentSpawn(agent, options = {}) {
+    const start = Date.now();
+    const profile = getCapabilityProfile(agent);
+    if (!profile?.invoke_template || !profile?.invoke_binary || !profile.runtime.canBeSpawnedCli) {
+        return { agent, status: 'no_template', delivered: false, completed: false, duration_ms: 0, detail: 'no CLI invoke template' };
+    }
+    const binary = resolveBinaryOnPath(profile.invoke_binary);
+    if (!binary) {
+        return { agent, binary: profile.invoke_binary, status: 'not_installed', delivered: false, completed: false, duration_ms: 0, detail: `binary '${profile.invoke_binary}' not on PATH` };
+    }
+    const invoke = options.probeFor?.(agent)
+        ?? buildInvokeCommand(agent, options.probePrompt ?? DEFAULT_PROBE_PROMPT, { mode: 'consult' });
+    if (!invoke) {
+        return { agent, binary, status: 'no_template', delivered: false, completed: false, duration_ms: 0, detail: 'could not build invoke command' };
+    }
+    // Isolated signals root so the probe never pollutes the project's runtime dir.
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), `bclaw-spawncheck-${agent}-`));
+    const assignmentId = 'spawn_check';
+    try {
+        defaultExecutionAdapter.start(invoke, { agent, assignmentId, ackRoot: root, worktreePath: root });
+        const timeout = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+        const deadline = Date.now() + timeout;
+        while (Date.now() < deadline) {
+            if (signalExists(root, assignmentId, 'completed'))
+                break;
+            if (signalExists(root, assignmentId, 'failed'))
+                break;
+            await sleep(100);
+        }
+        const delivered = signalExists(root, assignmentId, 'ack');
+        const completed = signalExists(root, assignmentId, 'completed');
+        const failed = signalExists(root, assignmentId, 'failed');
+        const duration_ms = Date.now() - start;
+        if (completed) {
+            return { agent, binary, status: 'ok', delivered, completed: true, duration_ms, detail: 'ack + completed round-trip' };
+        }
+        if (failed) {
+            const tail = readLogTail(root, assignmentId, 'stderr', 400).trim() || readLogTail(root, assignmentId, 'stdout', 400).trim();
+            return { agent, binary, status: 'failed', delivered, completed: false, duration_ms, detail: `wrapper reported failure${tail ? ` — ${tail.replace(/\s+/g, ' ').slice(0, 200)}` : ''}` };
+        }
+        if (delivered) {
+            return { agent, binary, status: 'delivered_no_completion', delivered: true, completed: false, duration_ms, detail: `spawned + ack but no completion within ${timeout}ms (silent-death symptom)` };
+        }
+        return { agent, binary, status: 'failed', delivered: false, completed: false, duration_ms, detail: `no ack within ${timeout}ms — delivery failed` };
+    }
+    finally {
+        try {
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+}
+export async function runSpawnCheck(options = {}) {
+    const agentNames = options.agents ?? getSpawnableAgents().map((a) => a.name);
+    const entries = [];
+    for (const agent of agentNames) {
+        try {
+            entries.push(await checkAgentSpawn(agent, options));
+        }
+        catch (err) {
+            entries.push({
+                agent, status: 'failed', delivered: false, completed: false, duration_ms: 0,
+                detail: `spawn-check threw: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    const installed = entries.filter((e) => e.status !== 'not_installed' && e.status !== 'no_template');
+    const ok = installed.filter((e) => e.status === 'ok').length;
+    const failures = installed.filter((e) => e.status === 'failed' || e.status === 'delivered_no_completion').length;
+    const not_installed = entries.filter((e) => e.status === 'not_installed').length;
+    return {
+        host_os: process.platform,
+        total: entries.length,
+        ok,
+        failures,
+        not_installed,
+        entries,
+        exit_code: failures > 0 ? 1 : 0,
+    };
+}
+export function renderSpawnCheckReport(report) {
+    const lines = [];
+    lines.push(`Spawn-check — ${report.ok} ok / ${report.failures} failed / ${report.not_installed} not installed (host: ${report.host_os})`);
+    lines.push('');
+    for (const e of report.entries) {
+        const icon = e.status === 'ok' ? '✔'
+            : e.status === 'not_installed' || e.status === 'no_template' ? '·'
+                : '✗';
+        lines.push(`  ${icon} ${e.agent.padEnd(16)} ${e.status}${e.duration_ms ? ` (${e.duration_ms}ms)` : ''} — ${e.detail}`);
+    }
+    if (report.failures > 0) {
+        lines.push('');
+        lines.push('✗ One or more installed agents failed their spawn round-trip — fix before dispatching.');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=spawn-check.js.map

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.7.0 on 2026-05-28T00:12:31.140Z
+// Source: brainclaw v1.7.2 on 2026-06-04T21:46:11.832Z
 export const FACTS = {
-  "version": "1.7.0",
-  "generated_at": "2026-05-28T00:12:31.140Z",
+  "version": "1.7.2",
+  "generated_at": "2026-06-04T21:46:11.832Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.0",
-  "generated_at": "2026-05-28T00:12:31.140Z",
+  "version": "1.7.2",
+  "generated_at": "2026-06-04T21:46:11.832Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/docs/cli.md

@@ -1933,7 +1933,7 @@ The default catalog is intentionally small and centred on the canonical grammar.
 | `bclaw_work(intent)` | Start a session, load context, and (for `intent="execute"`) claim a scope in one call. Returns a compact payload by default (pass `compact: false` for the full context). |
 | `bclaw_context(kind)` | Unified context read: `kind` is one of `memory`, `execution`, `board`, `board_summary`, or `delta`. |
 
-**Canonical grammar** — your main tool for working with memory entities (plan, decision, constraint, trap, handoff, runtime_note, candidate, claim, action, assignment, agent_run):
+**Canonical grammar** — your main tool for working with memory entities (plan, decision, constraint, trap, handoff, runtime_note, candidate, sequence, claim, action, assignment, agent_run):
 
 | Tool | Purpose |
 |---|---|
@@ -1944,13 +1944,17 @@ The default catalog is intentionally small and centred on the canonical grammar.
 | `bclaw_remove(entity, id, purge?)` | Soft-delete (or purge) an entity. |
 | `bclaw_transition(entity, id, to)` | Change an entity's status (e.g. plan `todo` → `in_progress` → `done`, candidate `pending` → `accepted`). |
 
-**Multi-agent coordination** (escalation path when delegating to other agents):
+**Multi-agent coordination** (escalation path when delegating to other agents):
 
 | Tool | Purpose |
 |---|---|
 | `bclaw_coordinate(intent)` | Assign, consult, review, reroute, or summarize across agents. Pass `open_loop: true` on `intent="review"` to also dispatch the reviewer turn. |
 | `bclaw_dispatch(intent)` | Parallelize execute across a sequence's lanes (analysis / execute / review). |
-| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
+| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
+
+**Sequences**:
+
+`bclaw_list_sequences`, `bclaw_create_sequence`, `bclaw_update_sequence`, `bclaw_delete_sequence`. Sequence items use `{ planId, stepId?, rank, hard_after?, soft_after?, lane?, scope_hint?, rationale? }`. Create/update a sequence to `active`, inspect readiness with `bclaw_dispatch(intent="analysis")`, then dispatch ready lanes with `bclaw_dispatch(intent="execute")`.
 
 **Session, claims, plans, handoffs**:
 
@@ -1960,7 +1964,7 @@ The default catalog is intentionally small and centred on the canonical grammar.
 
 `bclaw_write_note`, `bclaw_quick_capture`, `bclaw_search`, `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`, `bclaw_doctor`.
 
-**Legacy per-entity tools** (`bclaw_list_plans` / `bclaw_list_claims` / `bclaw_list_candidates` / `bclaw_list_sequences`, `bclaw_get_context` / `bclaw_get_execution_context` / `bclaw_get_agent_board`, `bclaw_create_plan` / `bclaw_create_candidate`, `bclaw_update_plan` / `bclaw_update_handoff` / `bclaw_update_memory`, `bclaw_read_handoff` / `bclaw_delete_memory`, `bclaw_accept` / `bclaw_reject`, `bclaw_dispatch_analysis` / `bclaw_dispatch_review`, and others) were removed from the discoverable catalog at v1.0. Direct calls still succeed as a migration escape hatch but emit a redirect warning pointing at the canonical grammar. The full removal list and replacement map lives in [`docs/mcp-schema-changelog.md`](mcp-schema-changelog.md) under the v1.0 "Removed" section. Raw MCP clients can request the full advanced catalog with `tools/list` params `{ catalog: "all" }`.
+**Legacy per-entity tools** (`bclaw_list_plans` / `bclaw_list_claims` / `bclaw_list_candidates`, `bclaw_get_context` / `bclaw_get_execution_context` / `bclaw_get_agent_board`, `bclaw_create_plan` / `bclaw_create_candidate`, `bclaw_update_plan` / `bclaw_update_handoff` / `bclaw_update_memory`, `bclaw_read_handoff` / `bclaw_delete_memory`, `bclaw_accept` / `bclaw_reject`, `bclaw_dispatch_analysis` / `bclaw_dispatch_review`, and others) were removed from the discoverable catalog at v1.0. Direct calls still succeed as a migration escape hatch but emit a redirect warning pointing at the canonical grammar. The full removal list and replacement map lives in [`docs/mcp-schema-changelog.md`](mcp-schema-changelog.md) under the v1.0 "Removed" section. Raw MCP clients can request the full advanced catalog with `tools/list` params `{ catalog: "all" }`.
 
 ---