brainclaw 1.7.1 → 1.7.3

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/schema.js

@@ -855,7 +855,25 @@ export const RuntimeEventTypeSchema = z.enum([
     'run_interrupted',
     'plan_cascade_to_done',
     'candidate_harvested',
+    'lane_result_harvested',
 ]);
+/**
+ * pln#526 — LANE-RESULT convention. A dispatched worker writes a single
+ * `LANE-RESULT.json` at its worktree root as its final step (a fallback that
+ * works even when bclaw_assignment_update / MCP is unavailable, e.g. sandboxed
+ * agents). The coordinator ingests it with `brainclaw harvest <assignment_id>`.
+ */
+export const LaneResultSchema = z.object({
+    assignment_id: z.string(),
+    status: z.enum(['completed', 'blocked', 'failed']),
+    summary: z.string(),
+    /** Paths or refs the worker produced (commits, files, docs). */
+    artifacts: z.array(z.string()).optional(),
+    /** Files the worker changed in the worktree. */
+    files_changed: z.array(z.string()).optional(),
+    /** Free-form notes (blockers, follow-ups). */
+    notes: z.string().optional(),
+});
 export const RuntimeEventSchema = z.object({
     id: z.string(),
     agent: z.string(),

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/core/worktree.js

@@ -3,6 +3,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import yaml from 'yaml';
+import { logger } from './logger.js';
+import { parsePorcelainZ, isSystemDirtyPath } from './dirty-scope.js';
 /** Normalizes a path for use in git CLI arguments (forward slashes on Windows). */
 function gitPath(p) {
     return p.replace(/\\/g, '/');
@@ -37,6 +40,85 @@ export function detectStackSharedPaths(projectRoot) {
     }
     return [...result];
 }
+/**
+ * pln#523 — read declared monorepo workspace globs from npm/yarn/bun
+ * `workspaces` (package.json) and pnpm-workspace.yaml. Returns the raw
+ * patterns (e.g. "packages/*", "apps/api"); empty when the project is not a
+ * workspace root or the manifests are absent/invalid.
+ */
+export function readWorkspacePatterns(projectRoot) {
+    const patterns = [];
+    // npm / yarn / bun: package.json "workspaces" (array, or { packages: [...] })
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8'));
+        const ws = pkg.workspaces;
+        if (Array.isArray(ws))
+            patterns.push(...ws);
+        else if (ws && Array.isArray(ws.packages))
+            patterns.push(...ws.packages);
+    }
+    catch { /* no / invalid package.json — not a node workspace root */ }
+    // pnpm: pnpm-workspace.yaml "packages"
+    try {
+        const parsed = yaml.parse(fs.readFileSync(path.join(projectRoot, 'pnpm-workspace.yaml'), 'utf-8'));
+        if (parsed && Array.isArray(parsed.packages))
+            patterns.push(...parsed.packages);
+    }
+    catch { /* no pnpm workspace file */ }
+    return [...new Set(patterns)];
+}
+/**
+ * pln#523 — resolve monorepo workspace globs to the per-package `node_modules`
+ * directories that actually exist on disk. Hoisted monorepos (all deps at the
+ * root) need only the root link from detectStackSharedPaths; this additionally
+ * covers packages that keep a LOCAL node_modules (pnpm, nohoist, partial
+ * hoisting) so a dispatched worker can build/typecheck a sub-package, not just
+ * the root — the exact gap behind a worker stalling on `tsc` in a worktree.
+ *
+ * Pattern shapes supported without a glob dependency (zero-runtime-dep policy):
+ *   - exact dir:       "apps/api"
+ *   - single wildcard: "packages/*"   → immediate child directories
+ *   - deep wildcard:   "packages/**"  → treated as one level ("packages/*")
+ * Negations ("!pkg/excluded") are skipped — they only narrow coverage and a
+ * missing link degrades gracefully to central validation.
+ *
+ * Returns relative paths with forward slashes (e.g. "apps/api/node_modules").
+ */
+export function detectWorkspaceNodeModules(projectRoot) {
+    const patterns = readWorkspacePatterns(projectRoot);
+    if (patterns.length === 0)
+        return [];
+    const result = new Set();
+    const addIfHasNodeModules = (relPkgDir) => {
+        const rel = `${relPkgDir.replace(/\\/g, '/').replace(/\/+$/, '')}/node_modules`;
+        if (fs.existsSync(path.join(projectRoot, rel)))
+            result.add(rel);
+    };
+    for (const raw of patterns) {
+        const pattern = raw.trim();
+        if (!pattern || pattern.startsWith('!'))
+            continue;
+        const wildcardIdx = pattern.indexOf('*');
+        if (wildcardIdx === -1) {
+            addIfHasNodeModules(pattern);
+            continue;
+        }
+        // Base dir = the path segment before the first wildcard.
+        const base = pattern.slice(0, wildcardIdx).replace(/\/+$/, '');
+        let children = [];
+        try {
+            children = fs
+                .readdirSync(path.join(projectRoot, base), { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .map((d) => d.name);
+        }
+        catch { /* base dir absent — skip this pattern */ }
+        for (const child of children) {
+            addIfHasNodeModules(base ? `${base}/${child}` : child);
+        }
+    }
+    return [...result];
+}
 function canonicalizeScopePath(target) {
     let resolved;
     try {
@@ -191,6 +273,7 @@ export function findWorktreePathForBranch(worktrees, branchName) {
  * Returns the absolute path to the newly created worktree.
  */
 export function createWorktree(mainWorktreePath, branchName, options = {}) {
+    const symlinkWarnings = [];
     const trySymlinkSharedPath = (entryName) => {
         const sourcePath = path.join(mainWorktreePath, entryName);
         const linkPath = path.join(targetPath, entryName);
@@ -205,8 +288,20 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
             }
             fs.symlinkSync(sourcePath, linkPath, 'junction');
         }
-        catch {
-            // Non-fatal - shared paths are an optimization for agent worktrees
+        catch (err) {
+            // pln#523: do NOT swallow silently. A missing node_modules junction is
+            // exactly what leaves a dispatched worker unable to build/typecheck in its
+            // worktree (it then stalls on `tsc` or npm scripts). Record a structured
+            // warning — surfaced in the worktree sidecar + logger — instead of an
+            // invisible degradation. Linking remains best-effort (non-fatal).
+            const sameVolume = path.parse(sourcePath).root.toLowerCase() === path.parse(targetPath).root.toLowerCase();
+            const reason = err instanceof Error ? err.message : String(err);
+            const hint = sameVolume
+                ? ''
+                : ' (source and worktree are on different volumes — directory junctions require the same volume; deps cannot be linked here, validate builds centrally)';
+            const msg = `Failed to link '${entryName}' into worktree: ${reason}${hint}`;
+            symlinkWarnings.push(msg);
+            logger.warn(`[worktree] ${msg}`);
         }
     };
     // Guard: bare repos have no working tree
@@ -256,7 +351,15 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     // pln#480: auto-detect shared paths from stack markers + config overrides.
     // `dist` intentionally excluded — build outputs must be per-worktree
     // (EBUSY during clean:dist when MCP/extension holds a handle on junction target).
-    const detected = detectStackSharedPaths(mainWorktreePath);
+    // pln#523: also link per-package node_modules for JS/TS monorepos so workers
+    // can build/typecheck sub-packages, not just the root. Set
+    // BRAINCLAW_NO_LINK_DEPS=1 to disable auto dependency linking (e.g. when the
+    // worktree lives on a different volume and central validation is preferred);
+    // explicit options.sharedPaths are still honored.
+    const linkDepsDisabled = process.env.BRAINCLAW_NO_LINK_DEPS === '1';
+    const detected = linkDepsDisabled
+        ? []
+        : [...detectStackSharedPaths(mainWorktreePath), ...detectWorkspaceNodeModules(mainWorktreePath)];
     const extra = options.sharedPaths ?? [];
     const excluded = new Set(options.excludeShared ?? []);
     const sharedPaths = [...new Set([...detected, ...extra])].filter((p) => !excluded.has(p));
@@ -282,6 +385,10 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
         base_ref: baseRef,
         reset_existing_branch: options.resetExistingBranch === true,
         git_advice: 'git add ONLY specific files, NEVER git add -A.',
+        // pln#523: surface any shared-path link failures (e.g. node_modules junction
+        // that could not be created) so the worker / supervisor can see why a build
+        // might fail, instead of an invisible degradation.
+        ...(symlinkWarnings.length > 0 ? { symlink_warnings: symlinkWarnings } : {}),
     };
     fs.writeFileSync(path.join(targetPath, '.brainclaw-worktree.json'), JSON.stringify(meta, null, 2));
     return targetPath;
@@ -510,6 +617,30 @@ export function removeWorktree(mainWorktreePath, worktreePath, options = {}) {
 export function pruneWorktrees(mainWorktreePath) {
     runGit(['worktree', 'prune'], mainWorktreePath);
 }
+/**
+ * Files brainclaw itself writes into a worktree AT BIRTH — they are never user
+ * work and must not count as "uncommitted changes" when deciding whether a
+ * merged worktree can be GC'd:
+ *   - `.gitignore`            — copied from the main repo by createWorktree; on
+ *                               Windows autocrlf flags it as ` M .gitignore`,
+ *                               which previously made EVERY brainclaw worktree
+ *                               look dirty and skipped the clean forever.
+ *   - `.brainclaw-worktree.json` — the sidecar metadata createWorktree writes.
+ * Combined with isSystemDirtyPath (.brainclaw/, .git/, agent config dirs).
+ */
+const WORKTREE_BIRTH_NOISE = new Set(['.gitignore', '.brainclaw-worktree.json']);
+/**
+ * True when a worktree's `git status --porcelain=v1 -z` output contains ONLY
+ * brainclaw birth artifacts / coordination-store noise — i.e. no real user work
+ * would be lost by removing it. Empty output (fully clean) also returns true.
+ */
+export function worktreeHasOnlyBirthNoise(statusZStdout) {
+    const paths = parsePorcelainZ(statusZStdout);
+    return paths.every((p) => {
+        const norm = p.replace(/\\/g, '/');
+        return WORKTREE_BIRTH_NOISE.has(norm) || isSystemDirtyPath(norm);
+    });
+}
 /**
  * Removes worktrees whose branch has been fully merged into the current branch
  * (typically master/main after a merge). Also removes brainclaw-managed
@@ -539,10 +670,13 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
         if (!isMerged) {
             continue;
         }
-        // Check for uncommitted changes
+        // Check for uncommitted changes — but ignore brainclaw birth-noise
+        // (.gitignore autocrlf, the sidecar, coordination store). Without this,
+        // every merged brainclaw worktree looked dirty and was skipped forever,
+        // so `worktree clean` removed nothing and worktrees accumulated (pln#525).
         if (!options.force) {
-            const status = runGit(['status', '--porcelain'], wt.path);
-            if (status.ok && status.stdout.trim().length > 0) {
+            const status = runGit(['status', '--porcelain=v1', '-z', '--untracked-files=normal'], wt.path);
+            if (status.ok && !worktreeHasOnlyBirthNoise(status.stdout)) {
                 result.skipped.push({ path: wt.path, reason: 'uncommitted changes' });
                 continue;
             }
@@ -552,7 +686,12 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
             continue;
         }
         try {
-            removeWorktree(mainWorktreePath, wt.path, { force: options.force });
+            // Reaching here means EITHER options.force OR the birth-noise gate above
+            // passed (no real user work). In both cases git's own `worktree remove`
+            // must be forced: otherwise it refuses on the untracked sidecar /
+            // autocrlf .gitignore that we already classified as discardable noise
+            // (pln#525 — the refusal that left every merged worktree un-GC-able).
+            removeWorktree(mainWorktreePath, wt.path, { force: true });
             result.removed.push(wt.path);
         }
         catch {

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.1 on 2026-06-02T10:24:49.702Z
+// Source: brainclaw v1.7.3 on 2026-06-05T21:43:11.193Z
 export const FACTS = {
-  "version": "1.7.1",
-  "generated_at": "2026-06-02T10:24:49.702Z",
+  "version": "1.7.3",
+  "generated_at": "2026-06-05T21:43:11.193Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.1",
-  "generated_at": "2026-06-02T10:24:49.702Z",
+  "version": "1.7.3",
+  "generated_at": "2026-06-05T21:43:11.193Z",
   "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" }`.
 
 ---
 

package/docs/integrations/mcp.md

@@ -43,10 +43,10 @@ All 59 published MCP tools are discoverable via `tools/list`. Each tool carries
 Every tool has one of three tiers in its `annotations.tier` field:
 
 - **facade** — High-level entry points for agents that don't need granular access. Start here.
-- **standard** — Day-to-day coordination tools: plans, claims, messaging, dispatch, review, memory. Returned by default alongside facades.
-- **advanced** — Specialized governance, audit, registry, sequences, and power tools.
-
-By default, `tools/list` returns **facade + standard** tools (34 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
+- **standard** — Day-to-day coordination tools: plans, claims, messaging, sequences, dispatch, review, memory. Returned by default alongside facades.
+- **advanced** — Specialized governance, audit, registry, and power tools.
+
+By default, `tools/list` returns **facade + standard** tools (38 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
 
 Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
 
@@ -90,9 +90,13 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_session_end` | session | End session, optionally auto-reflect notes or handoffs |
 | `bclaw_add_step` | coordination | Add a sub-step to a plan item |
 | `bclaw_complete_step` | coordination | Mark a plan sub-step as done |
-| `bclaw_update_step` | coordination | Update a plan sub-step's status, text, or assignee |
-| `bclaw_delete_step` | coordination | Remove a sub-step from a plan |
-| `bclaw_correct_handoff` | coordination | Write an immutable correction handoff that supersedes an earlier one |
+| `bclaw_update_step` | coordination | Update a plan sub-step's status, text, or assignee |
+| `bclaw_delete_step` | coordination | Remove a sub-step from a plan |
+| `bclaw_list_sequences` | coordination | Coordination sequence listing |
+| `bclaw_create_sequence` | coordination | Create a coordination sequence |
+| `bclaw_update_sequence` | coordination | Update a sequence's status, metadata, or items |
+| `bclaw_delete_sequence` | coordination | Delete a sequence by ID |
+| `bclaw_correct_handoff` | coordination | Write an immutable correction handoff that supersedes an earlier one |
 | `bclaw_assignment_update` | coordination | Report assignment lifecycle status |
 | `bclaw_assignment_action` | coordination | Resolve or reject a pending ActionRequired item |
 | `bclaw_harvest_candidates` | coordination | Harvest sandboxed worktree candidate files into the main project store |
@@ -123,13 +127,9 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_who` | discovery | List active agent sessions on workspace |
 | `bclaw_add_capability` | discovery | Register a project capability |
 | `bclaw_add_tool` | discovery | Register a project tool |
-| `bclaw_list_sequences` | coordination | Coordination sequence listing |
-| `bclaw_create_sequence` | coordination | Create a coordination sequence |
-| `bclaw_update_sequence` | coordination | Update a sequence's status, metadata, or items |
-| `bclaw_get_thread` | coordination | Get all messages in a thread across inboxes |
-| `bclaw_delete_plan` | coordination | Delete a plan item by ID |
-| `bclaw_delete_sequence` | coordination | Delete a sequence by ID |
-| `bclaw_delete_memory` | memory | Delete a memory item by ID |
+| `bclaw_get_thread` | coordination | Get all messages in a thread across inboxes |
+| `bclaw_delete_plan` | coordination | Delete a plan item by ID |
+| `bclaw_delete_memory` | memory | Delete a memory item by ID |
 | `bclaw_update_memory` | memory | Update a memory item's text or metadata |
 | `bclaw_compact` | memory | LLM-driven semantic memory compaction (two-phase) |
 
@@ -157,11 +157,44 @@ for the full 1.0.0 changelog.
 | `bclaw_transition(entity, id, to, reason?)` | State machine transition with side-effect tags | `bclaw_accept`, `bclaw_reject`, status-update flows |
 
 Supported entities: plan, decision, constraint, trap, handoff,
-runtime_note, candidate, claim, action, assignment, agent_run
+runtime_note, candidate, sequence, claim, action, assignment, agent_run
 (with assignment lifecycle now writable through `bclaw_transition` and
 `bclaw_remove`; `agent_run` remains read-only). Declarative transition matrix +
 updatable field list live in [src/core/entity-registry.ts](../../src/core/entity-registry.ts).
 
+#### Sequence workflow
+
+Sequences are in the default catalog because they are the normal path
+for parallel agent work. Use the specialized sequence tools when
+building lanes; the canonical grammar can still read or patch the same
+entity when that is more convenient.
+
+Sequence items use this shape:
+
+```json
+{
+  "planId": "pln_xxx",
+  "stepId": "stp_xxx",
+  "rank": 1,
+  "hard_after": [],
+  "soft_after": [],
+  "lane": "api",
+  "scope_hint": "src/api/**",
+  "rationale": "Independent API lane"
+}
+```
+
+`planId` and `rank` are required. `stepId` is optional and narrows the
+sequence item to a specific plan step. `hard_after` blocks readiness
+until predecessor items complete; `soft_after` is advisory.
+
+Typical MCP flow:
+
+1. `bclaw_create_sequence({ name, status: "draft", items })`
+2. `bclaw_update_sequence({ id, status: "active" })`
+3. `bclaw_dispatch({ intent: "analysis" })`
+4. `bclaw_dispatch({ intent: "execute", agents: [...] })`
+
 For assignments specifically:
 - `bclaw_transition(entity="assignment", id=..., to="cancelled", reason=...)` is the canonical supervisor/admin cancel path.
 - `bclaw_remove(entity="assignment", id=...)` archives by cancelling the assignment.