brainclaw 1.7.1 → 1.7.2

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.1 on 2026-06-02T10:24:49.702Z
+// Source: brainclaw v1.7.2 on 2026-06-04T21:46:11.832Z
 export const FACTS = {
-  "version": "1.7.1",
-  "generated_at": "2026-06-02T10:24:49.702Z",
+  "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.1",
-  "generated_at": "2026-06-02T10:24:49.702Z",
+  "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" }`.
 
 ---
 

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.

package/docs/mcp-schema-changelog.md

@@ -19,7 +19,7 @@ guarantees this changelog follows.
   to `sha256:860fbaa30a486093` (zod 4). No tool was added, removed,
   renamed, or had its required arguments change.
 
-**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
+**Changed — `bclaw_loop(intent: 'open')` anti-pattern gate (pln#461)**
 - New optional field `allow_orphan: boolean` on `BclawLoopOpenSchema`.
 - Default (absent / `false`) — handler rejects with `validation_error`
   and points to `bclaw_coordinate(intent: 'review', open_loop: true)`
@@ -28,9 +28,20 @@ guarantees this changelog follows.
   out in `CLAUDE.md`.
 - `allow_orphan: true` — explicit acknowledgement that the caller
   will drive `turn()` + dispatch manually (advanced / test use only).
-- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
-  affected — they bypass `handleBclawLoop` and invoke the core
-  `openLoop()` directly.
+- Internal callers (`bclaw_coordinate`, `bclaw_dispatch`) are not
+  affected — they bypass `handleBclawLoop` and invoke the core
+  `openLoop()` directly.
+
+**Changed — sequence tools promoted to default discovery (pln#522)**
+- `bclaw_list_sequences`, `bclaw_create_sequence`,
+  `bclaw_update_sequence`, and `bclaw_delete_sequence` move from
+  `advanced` to `standard`, so fresh agents see them in the default
+  `tools/list` catalog. Sequences are a core agent-first coordination
+  primitive for parallel dispatch, not an advanced-only admin surface.
+- `bclaw_create_sequence.items` and `bclaw_update_sequence.items` now
+  expose the full item shape in JSON Schema: `planId`, optional
+  `stepId`, `rank`, `hard_after`, `soft_after`, `lane`, `scope_hint`,
+  and `rationale`.
 
 ---
 
@@ -82,7 +93,7 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:4a6f612ad952fb52`
+- MCP public surface fingerprint: `sha256:a1881ff57ddce377`
   (updated 2026-05-27: added the `ref` property to the bclaw_coordinate
   inputSchema — pln#520 Tier 2 / trp#371, the scope-aware dirty guard;
   `ref` lets a dispatch build its worktree from an explicit git ref.

package/docs/playbooks/team/index.md

@@ -48,11 +48,13 @@ These rules apply to any feature that touches this audience:
 - `bclaw_check_policy` — scope compliance with glob matching, returns blocks + warnings
 - `bclaw_who` — list all active agent sessions on the workspace
 
-### Planning & Sequencing
-- `bclaw_create(entity="plan", data)` / `bclaw_update(entity="plan", id, patch)` / `bclaw_transition(entity="plan", id, to)` — shared work planning with priority/effort/assignee/status
-- `bclaw_find(entity="plan", filter?)` — list plans
-- `bclaw_add_step` / `bclaw_complete_step` / `bclaw_update_step` / `bclaw_delete_step` — plan sub-steps for granular tracking
-- `bclaw_create_sequence` / `bclaw_list_sequences` / `bclaw_update_sequence` — multi-step coordination sequences with lane analysis
+### Planning & Sequencing
+- `bclaw_create(entity="plan", data)` / `bclaw_update(entity="plan", id, patch)` / `bclaw_transition(entity="plan", id, to)` — shared work planning with priority/effort/assignee/status
+- `bclaw_find(entity="plan", filter?)` — list plans
+- `bclaw_add_step` / `bclaw_complete_step` / `bclaw_update_step` / `bclaw_delete_step` — plan sub-steps for granular tracking
+- `bclaw_create_sequence` / `bclaw_list_sequences` / `bclaw_update_sequence` — multi-step coordination sequences with lane analysis
+
+Sequence items are explicit lane records: `{ planId, stepId?, rank, hard_after?, soft_after?, lane?, scope_hint?, rationale? }`. `planId` and `rank` are required; `stepId` lets a sequence dispatch a specific plan step instead of the whole plan. A normal parallel flow is: create sequence as `draft`, update it to `active`, run `bclaw_dispatch(intent="analysis")`, then run `bclaw_dispatch(intent="execute", agents=[...])`.
 
 ### Multi-Agent Dispatch
 - `bclaw_dispatch(intent)` — `analysis` analyses an active sequence (ready/active/blocked/done per lane), `execute` fans out parallel work across lanes, `review` dispatches code reviews for completed handoffs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {