brainclaw 1.5.5 → 1.6.0

package/dist/core/schema.js

@@ -232,6 +232,17 @@ export const HandoffSchema = z.object({
      */
     superseded_by: z.string().optional(),
     supersedes: z.string().optional(),
+    /**
+     * pln#365 finalization: opt-in cloud federation. Optional (no default) so
+     * existing on-disk handoffs without the field continue to parse, AND so
+     * an unset value means "stay local" rather than "implicitly shared". To
+     * opt a handoff into cloud push, set `visibility: 'shared'` explicitly
+     * when building it. Session-end push uses literal `visibility === 'shared'`
+     * (cf. session-end.ts:isExplicitlyShared). Risk it mitigates: a session
+     * handoff with `snapshot.diff` carrying secrets would otherwise leak the
+     * moment cloud_sync flips on, by virtue of being created at all.
+     */
+    visibility: MemoryVisibilitySchema.optional(),
 });
 export const PlanStatusSchema = z.enum(['todo', 'in_progress', 'blocked', 'done', 'dropped']);
 export const PlanStepStatusSchema = z.enum(['todo', 'in_progress', 'testing', 'done', 'blocked']);
@@ -243,7 +254,8 @@ export const PlanStepSchema = z.object({
     created_at: z.string(),
     updated_at: z.string(),
 });
-export const PlanTypeSchema = z.enum(['feat', 'fix', 'chore', 'spike', 'doc']).default('feat');
+export const PlanTypeEnumSchema = z.enum(['feat', 'fix', 'chore', 'spike', 'doc']);
+export const PlanTypeSchema = PlanTypeEnumSchema.default('feat');
 export const PlanItemSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     id: z.string(),
@@ -532,6 +544,13 @@ export const CandidateSchema = z.preprocess(candidatePreprocess, z.object({
     resolved_by: z.string().optional(),
     resolution_reason: z.string().optional(),
     provenance: ProvenancePassthroughSchema,
+    /**
+     * pln#365 finalization: opt-in cloud federation. Mirrors HandoffSchema —
+     * optional (no default) so unset means "stay local" and an agent must
+     * explicitly set `visibility: 'shared'` to opt a candidate into cloud
+     * push. Conservative because candidate.text can carry secrets.
+     */
+    visibility: MemoryVisibilitySchema.optional(),
 }));
 export const ReflectiveMemoryConfigSchema = z.object({
     enabled: z.boolean().default(true),
@@ -756,6 +775,7 @@ export const ActionRequiredSchema = z.object({
     tags: TagsWithDefaultSchema,
 });
 // --- Runtime notes schemas ---
+export const RuntimeNoteTypeSchema = z.enum(['observation', 'session_start', 'session_end']);
 export const RuntimeNoteSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     id: z.string(),
@@ -771,7 +791,7 @@ export const RuntimeNoteSchema = z.object({
     visibility: MemoryVisibilitySchema.default('shared'),
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
-    note_type: z.enum(['observation', 'session_start', 'session_end']).default('observation'),
+    note_type: RuntimeNoteTypeSchema.default('observation'),
     model: z.string().optional(),
     provenance: ProvenancePassthroughSchema,
 });
@@ -937,6 +957,11 @@ export const RemoteSyncSchema = z.object({
     ssh_key_path: z.string().optional(),
     sync_strategy: z.enum(['pull-only', 'push-pull', 'pr-based']).default('push-pull'),
 });
+export const CloudSyncConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    endpoint: z.string().default('https://app.brainclaw.dev'),
+    api_key: z.string().optional(),
+});
 export const SessionSnapshotSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     session_id: z.string(),
@@ -1232,6 +1257,7 @@ export const ConfigSchema = z.object({
     target_audience: z.enum(['human', 'agent']).optional().default('human'),
     openclaw_bridge: z.boolean().optional().default(false),
     remote_sync: RemoteSyncSchema.optional(),
+    cloud_sync: CloudSyncConfigSchema.optional(),
     telemetry: z.literal(false),
     allow_network: z.literal(false),
     redaction: RedactionConfigSchema,

package/dist/core/state.js

@@ -37,6 +37,68 @@ function loadDirectoryItems(dirPath, schema, documentType) {
     }
     return items;
 }
+const ENTITY_LOAD_CONFIG = {
+    constraint: { subdir: 'constraints', documentType: 'constraint', recursive: false },
+    decision: { subdir: 'decisions', documentType: 'decision', recursive: false },
+    trap: { subdir: 'traps', documentType: 'trap', recursive: false },
+    handoff: { subdir: 'handoffs', documentType: 'handoff', recursive: false },
+    plan: { subdir: 'plans', documentType: 'plan', recursive: false },
+    candidate: { subdir: 'inbox', documentType: 'candidate', recursive: false },
+    claim: { subdir: 'claims', documentType: 'claim', recursive: false },
+    assignment: { subdir: 'assignments', documentType: 'assignment', recursive: false },
+    agent_run: { subdir: 'runs', documentType: 'agent_run', recursive: false },
+    action: { subdir: 'actions', documentType: 'action_required', recursive: false },
+    runtime_note: { subdir: 'runtime', documentType: 'runtime_note', recursive: true },
+};
+function listJsonFiles(dirPath, recursive) {
+    if (!fs.existsSync(dirPath))
+        return [];
+    const files = [];
+    for (const entry of fs.readdirSync(dirPath).sort()) {
+        const fullPath = path.join(dirPath, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            if (recursive)
+                files.push(...listJsonFiles(fullPath, true));
+            continue;
+        }
+        if (entry.endsWith('.json'))
+            files.push(fullPath);
+    }
+    return files;
+}
+function validationErrorsFrom(error) {
+    if (error && typeof error === 'object' && 'issues' in error && Array.isArray(error.issues)) {
+        return (error.issues).map((issue) => {
+            const issuePath = Array.isArray(issue.path) && issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
+            return `${issuePath}${issue.message ?? 'validation failed'}`;
+        });
+    }
+    return [error instanceof Error ? error.message : String(error)];
+}
+export function collectLoadValidationWarnings(entity, cwd) {
+    const config = ENTITY_LOAD_CONFIG[entity];
+    if (!config)
+        return [];
+    const effectiveCwd = cwd ?? process.cwd();
+    const dirPath = resolveEntityDir(config.subdir, effectiveCwd, 'read');
+    return listJsonFiles(dirPath, config.recursive).flatMap((filepath) => {
+        try {
+            loadVersionedJsonFile(config.documentType, filepath);
+            return [];
+        }
+        catch (error) {
+            return [{
+                    entity_id: path.basename(filepath, '.json'),
+                    validation_errors: validationErrorsFrom(error),
+                    path: filepath,
+                }];
+        }
+    });
+}
+export function findLoadValidationWarning(entity, id, cwd) {
+    return collectLoadValidationWarnings(entity, cwd).find((warning) => warning.entity_id === id);
+}
 export function loadState(cwd) {
     // Load from entity-aligned directories (with legacy fallback)
     const effectiveCwd = cwd ?? process.cwd();

package/dist/facts.js

@@ -1,11 +1,11 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.5.5 on 2026-05-13T19:24:16.549Z
+// Source: brainclaw v1.6.0 on 2026-05-22T22:24:08.363Z
 export const FACTS = {
-  "version": "1.5.5",
-  "generated_at": "2026-05-13T19:24:16.549Z",
+  "version": "1.6.0",
+  "generated_at": "2026-05-22T22:24:08.363Z",
   "tools": {
-    "count": 60,
-    "published_count": 59,
+    "count": 62,
+    "published_count": 61,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -30,10 +30,12 @@ export const FACTS = {
       "bclaw_check_security",
       "bclaw_read_inbox",
       "bclaw_get_thread",
+      "bclaw_dispatch_status",
       "bclaw_dispatch",
       "bclaw_send_message",
       "bclaw_ack_message",
       "bclaw_setup",
+      "bclaw_init_project",
       "bclaw_write_note",
       "bclaw_quick_capture",
       "bclaw_claim",

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.5.5",
-  "generated_at": "2026-05-13T19:24:16.549Z",
+  "version": "1.6.0",
+  "generated_at": "2026-05-22T22:24:08.363Z",
   "tools": {
-    "count": 60,
-    "published_count": 59,
+    "count": 62,
+    "published_count": 61,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -28,10 +28,12 @@
       "bclaw_check_security",
       "bclaw_read_inbox",
       "bclaw_get_thread",
+      "bclaw_dispatch_status",
       "bclaw_dispatch",
       "bclaw_send_message",
       "bclaw_ack_message",
       "bclaw_setup",
+      "bclaw_init_project",
       "bclaw_write_note",
       "bclaw_quick_capture",
       "bclaw_claim",

package/docs/concepts/dispatch-lifecycle.md

@@ -0,0 +1,228 @@
+# Dispatch lifecycle
+
+When brainclaw routes work to another agent — `bclaw_coordinate(intent="assign"|"review"|"consult")`, `bclaw_dispatch(intent="execute")`, or a multi-turn `bclaw_loop` — it spins up **up to six related entities** plus an on-disk **brief-ack sentinel** and (since pln#504) **per-assignment stdout/stderr log files**. Knowing what each one means lets you tell at a glance whether a dispatch is alive, dead, or merely slow.
+
+This doc is the consolidated reference. It complements:
+- [multi-agent-workflows.md](multi-agent-workflows.md) — happy-path coordination patterns
+- [troubleshooting.md](troubleshooting.md) — symptom-driven diagnostic playbooks
+- [loop-engine.md](loop-engine.md) — multi-turn loop protocol details
+- [../integrations/codex.md](../integrations/codex.md), [../integrations/claude-code.md](../integrations/claude-code.md), etc. — per-agent spawn semantics
+
+---
+
+## The six entities
+
+A single `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[codex])` creates:
+
+```
+                         ┌─────────────────┐
+                         │   candidate     │  cnd_…  (review payload)
+                         └────────┬────────┘
+                                  │ references
+              ┌───────────────────┼──────────────────┐
+              ▼                   ▼                  ▼
+        ┌──────────┐       ┌─────────────┐    ┌──────────┐
+        │   loop   │ ◄────►│ assignment  │    │ message  │
+        │  lop_…   │       │  asgn_…     │    │  msg_…   │
+        └──────────┘       └──────┬──────┘    └──────────┘
+                                  │
+                                  │ owned-by
+                                  ▼
+                           ┌──────────────┐
+                           │    claim     │  clm_…  (worktree lock)
+                           └──────┬───────┘
+                                  │ triggers
+                                  ▼
+                           ┌──────────────┐
+                           │  agent_run   │  run_…  (the OS-level spawn)
+                           └──────┬───────┘
+                                  │
+              ┌───────────────────┼─────────────────┐
+              ▼                   ▼                 ▼
+        ┌──────────┐       ┌─────────────┐   ┌────────────┐
+        │ ack file │       │ stdout log  │   │ stderr log │
+        │ .ack     │       │ .stdout.log │   │ .stderr.log│
+        └──────────┘       └─────────────┘   └────────────┘
+        (pln#476)          (pln#504)         (pln#504)
+```
+
+| Entity | Prefix | Created by | Owner | Purpose |
+|---|---|---|---|---|
+| `candidate` | `cnd_` | the coordinate facade (review/ideate) | the dispatcher agent | Review payload that the loop references. Stays after the loop closes. |
+| `loop` | `lop_` | `bclaw_coordinate(open_loop=true)` or `bclaw_loop(intent="open")` | the dispatcher | Multi-turn thread of structured work. Has its own FSM. |
+| `assignment` | `asgn_` | dispatcher when targeting an agent | the **target** agent | Lifecycle event for that agent's turn. The only entity whose FSM tracks the WORKER's progress. |
+| `message` | `msg_` | dispatcher | the dispatcher | The brief delivered to the target's inbox. |
+| `claim` | `clm_` | dispatcher (or `bclaw_claim` directly) | the target agent | Worktree advisory lock. Released when the work is done or the agent gives up. |
+| `agent_run` | `run_` | the CLI execution adapter, only when an OS-level spawn actually happens | the target agent | OS-level subprocess record. Status FSM tracks the LIFETIME of the process — but only the parts brainclaw can observe (see [§Liveness limits](#liveness-limits) below). |
+
+Plus two filesystem-only artefacts created by the worker shell wrapper:
+
+- **Brief-ack sentinel**: `.brainclaw/coordination/runtime/ack/<assignment_id>.ack` — touched by the spawn wrapper BEFORE the agent binary runs (pln#476). Proves the spawn shell got far enough to execute `touch`. Does NOT prove the agent binary itself succeeded.
+- **stdout/stderr logs** (pln#504): `.brainclaw/coordination/runtime/log/<assignment_id>.{stdout,stderr}.log` — opened by the parent before the spawn, the child inherits dup'd fds and writes its streams there. This is the only window onto what a sandboxed worker actually said before dying.
+
+---
+
+## FSM cheatsheet
+
+### `loop.status`
+
+```
+open ──▶ paused ──▶ open       (pause / resume)
+  │
+  ├──▶ completed                (stop_condition met)
+  ├──▶ cancelled                (manual close — use when the loop dies abnormally)
+  └──▶ blocked                  (external blocker; intent to resume later)
+```
+
+`bclaw_loop(intent="close")` accepts **only** `completed | cancelled | blocked` as `status`. **Not `failed`** — map crashed/dead loops to `cancelled` with a `reason`.
+
+### `assignment.status`
+
+```
+created ──▶ offered ──▶ accepted ──▶ started ──▶ completed
+   │            │            │            │           
+   │            │            │            └──▶ failed (worker self-reported)
+   │            │            │            └──▶ blocked (worker needs supervisor)
+   │            │            │            └──▶ cancelled (rerouted away)
+   │            │            └──▶ acceptance_ttl expired (default 15min) → cancelled
+   │            └──▶ heartbeat_ttl expired (default 30min while running) → cancelled
+   └──▶ removed by `bclaw_assignment_admin` (rare)
+```
+
+Transitions past `offered` require the assigned agent itself (or `bclaw_assignment_admin`). A coordinator that didn't create the assignment **cannot** update it — `Agent X cannot update assignment owned by Y` is the canonical rejection.
+
+### `agent_run.status`
+
+```
+launching ──▶ running ──▶ completed
+                  │           ──▶ failed (non-zero exit, worker reported)
+                  │           ──▶ interrupted (TTL/heartbeat expiry, see below)
+                  │
+                  └──▶ failed (spawn returned no pid, brief-ack timeout)
+```
+
+**Liveness limits** {#liveness-limits}: `last_event_at` is bumped only when the worker writes a lifecycle event (via MCP or via the wrap shell). A worker that crashes before its first output keeps `status=running` and `last_event_at == launched_at` until reconciled. Since pln#503 phase 3.2, **any read of `agent_run` via `bclaw_find` / `bclaw_get` triggers a lazy reconciliation pass**: open runs past the 60s grace window get their pid checked, and dead workers transition to `failed` (`status_reason='silent_termination_no_evidence'`) once past the 30min stale threshold.
+
+For a single consolidated check (run + assignment + claim + loop + pid + log tails + verdict in one response), use **`bclaw_dispatch_status(target_id)`** (pln#503 phase 3.1).
+
+### `claim.status`
+
+```
+active ──▶ released
+   │
+   └──▶ adopted (another session inherited the claim, e.g. reconnect)
+```
+
+Releasing a claim does NOT cancel its assignment / agent_run / loop — those are independent entities. You generally need to clean up all of them together when aborting a dispatch.
+
+---
+
+## Observability decision tree
+
+You called `bclaw_coordinate(intent="review", open_loop=true, …)` and got back `execution_status: "delivered_and_started"`. What does that actually mean?
+
+**Fast path** (recommended since pln#503 phase 3.1): call `bclaw_dispatch_status(target_id="<asgn_…>")` and read its `diagnosis.health` + `diagnosis.recommended_next_action`. The tool consolidates the steps below into a single response — entity fan-out, pid liveness, log tails, verdict, recommended next action.
+
+**Long path** (for understanding or when the tool isn't available):
+
+```
+1. execution_status = "delivered_and_started"
+   ├──▶ Means: the spawn wrapper touched the brief-ack sentinel
+   └──▶ Does NOT mean: the worker is doing useful work
+
+2. Verify the spawn is alive — check the agent_run record
+   bclaw_find(entity="agent_run", filter={assignment_id: "<asgn>"})
+   ├──▶ status="running" AND pid alive on OS AND last_event_at < 5min ago → healthy
+   ├──▶ status="running" AND pid alive AND last_event_at == launched_at → stalled (worker never produced output)
+   ├──▶ status="running" AND pid dead → silently died (see logs)
+   └──▶ status="completed" / "failed" / "interrupted" → terminal, read status_reason
+
+3. If silent, read the logs (pln#504)
+   cat .brainclaw/coordination/runtime/log/<asgn>.stderr.log
+   cat .brainclaw/coordination/runtime/log/<asgn>.stdout.log
+   ├──▶ Contains an error → root cause found
+   └──▶ Empty → worker died before any write OR launched without log capture (legacy path)
+
+4. If the worker is alive but doing nothing useful for 15+ min
+   → most likely sandbox / MCP / capability mismatch with the brief
+   → see ../integrations/<agent>.md "Caveats" for per-agent gotchas
+```
+
+---
+
+## Diagnostic playbook
+
+When a dispatch hangs, work top-down through these checks. For the symptom-driven variant see [troubleshooting.md#inbox-messages-stuck--brief-ack-never-arrived](troubleshooting.md#inbox-messages-stuck--brief-ack-never-arrived).
+
+### Quick triage (≤5s)
+
+```bash
+# Single call covers process liveness + ack + log tails + entity state + verdict
+bclaw_dispatch_status(target_id="<asgn>")        # or clm_/lop_/run_
+```
+
+Read `diagnosis.health` (`healthy` | `stalled` | `silent_death` | `terminal` | `not_dispatched` | `unknown`) and `diagnosis.recommended_next_action` — usually that's all you need.
+
+### Manual triage (≤30s — when `bclaw_dispatch_status` isn't available)
+
+```bash
+# 1. Is the OS-level process alive?
+Get-Process -Id <pid>          # Windows
+ps -p <pid>                    # POSIX
+
+# 2. Did the spawn wrapper actually run?
+ls .brainclaw/coordination/runtime/ack/<asgn>.ack
+
+# 3. What did the worker say? (pln#504)
+cat .brainclaw/coordination/runtime/log/<asgn>.stderr.log
+cat .brainclaw/coordination/runtime/log/<asgn>.stdout.log
+```
+
+### Deeper (1-5min)
+
+```bash
+# Full entity state — same fan-out bclaw_dispatch_status does for you
+bclaw_get(entity="assignment", id="<asgn>")     # owner, ttls, status_reason
+bclaw_get(entity="agent_run", id="<run>")       # pid, started_at, last_event_at
+bclaw_get(entity="claim", id="<clm>")           # worktree, agent
+bclaw_get(entity="loop", id="<lop>")            # current_phase, slot states
+
+# Worktree activity
+git -C <worktree> log --oneline -5              # any new commits?
+git -C <worktree> status                        # uncommitted work?
+ls <worktree>/REVIEW_FINDINGS.md                # for review loops
+```
+
+### Abort a dispatch cleanly
+
+A dead dispatch needs four cleanup steps (no single facade does all of them today):
+
+```text
+1. Stop-Process -Id <pid>                                   # if pid still alive
+2. bclaw_loop(intent="close", loop_id="<lop>", status="cancelled", reason="...")
+3. bclaw_release_claim(id="<clm>")
+4. (optional) bclaw_assignment_admin or leave assignment as `offered`
+   — only the owning agent can transition assignment.status, and a
+     released claim already makes it effectively orphan
+```
+
+---
+
+## Per-agent spawn semantics
+
+Spawn behaviour varies by agent. The capability profile in `src/core/agent-capability.ts` describes each agent's prompt delivery, sandbox model, and MCP availability. Per-agent caveats:
+
+- [codex.md](../integrations/codex.md#caveats) — `--sandbox workspace-write` required; spawned codex may not have brainclaw MCP wired; stdin_pipe prompt delivery; brief-ack required for headless dispatch detection.
+- [claude-code.md](../integrations/claude-code.md) — interactive vs `-p` headless modes; tools whitelist.
+- [copilot.md](../integrations/copilot.md), [windsurf.md](../integrations/windsurf.md), [cline.md](../integrations/cline.md), [opencode.md](../integrations/opencode.md), [roo.md](../integrations/roo.md), [kilocode.md](../integrations/kilocode.md), [continue.md](../integrations/continue.md) — per-agent specifics.
+- [mistral-vibe.md](../integrations/mistral-vibe.md) — EU/GDPR self-hosted option.
+
+---
+
+## See also
+
+- [troubleshooting.md](troubleshooting.md) — symptom-driven diagnostic playbooks
+- [loop-engine.md](loop-engine.md) — multi-turn loop protocol, locks, advance gates
+- [multi-agent-workflows.md](multi-agent-workflows.md) — high-level coordination scenarios
+- [../integrations/overview.md](../integrations/overview.md) — index of supported agents
+- [../integrations/mcp.md](../integrations/mcp.md) — full MCP tool catalog

package/docs/concepts/loop-engine.md

@@ -163,6 +163,60 @@ interface LoopConflictRecord {
 }
 ```
 
+## Artifact body shapes
+
+`LoopArtifact.body` has two known shape categories. Ref-based bodies keep large
+content out of the loop thread JSON and store only file metadata in `body`.
+Inline bodies keep the whole structured payload in `body` for small artifacts
+such as operator questions and answers.
+
+Ref-based bodies are JSON encoded as `RefBasedArtifactBody`:
+
+- `ref`: string filename within the loop's `artifacts/` directory.
+- `byte_count`: exact byte length of the referenced file at attach time.
+- `sha256`: lowercase hex SHA-256 digest of the referenced file content.
+
+The referenced file lives at
+`.brainclaw/loops/threads/<loop_id>/artifacts/<ref>`. The champion or driver
+code that calls `complete_turn` / `add_artifact` is responsible for writing the
+file before or during the attach call, then attaching only
+`JSON.stringify({ ref, byte_count, sha256 })` as the artifact body.
+
+These artifact types use the ref-based shape:
+
+- `signals_report`: structured discovery or bootstrap signals, often larger
+  than the inline body cap.
+- `project_md_draft`: draft `PROJECT.md` content prepared by a loop slot.
+- `project_md_final`: final `PROJECT.md` content accepted by the loop.
+- `file_diff`: unified diff or patch content produced for review or apply.
+
+Typical attach flow:
+
+```ts
+const body = '<content>';
+const ref = `<artifact-id>.<ext>`;
+const artifactsDir = path.join(memoryDir(cwd), 'loops', 'threads', loopId, 'artifacts');
+fs.mkdirSync(artifactsDir, { recursive: true });
+fs.writeFileSync(path.join(artifactsDir, ref), body, 'utf8');
+const byte_count = Buffer.byteLength(body, 'utf8');
+const sha256 = crypto.createHash('sha256').update(body, 'utf8').digest('hex');
+complete_turn(
+  {
+    ...,
+    artifact: {
+      phase,
+      type,
+      body: JSON.stringify({ ref, byte_count, sha256 }),
+    },
+  },
+  cwd,
+);
+```
+
+`RefBasedArtifactBodySchema` in `src/core/loops/types.ts` is the authoritative
+validator for this metadata shape. `KNOWN_ARTIFACT_BODY_SCHEMAS` in the same
+file lists which artifact types are ref-based and which use inline JSON bodies.
+
 ## Lifecycle verbs
 
 The engine exposes four active verbs. Each one mutates state, appends an event, and returns the updated `LoopThread`. **All verbs are strictly synchronous-on-state and asynchronous-on-work**: any downstream dispatch (spawning a CLI, calling another MCP tool) is fire-and-forget from the commit window, so the per-loop lock is always released quickly.
@@ -450,6 +504,7 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 
 - [plans-and-claims.md](plans-and-claims.md)
 - [coordination.md](coordination.md)
+- [dispatch-lifecycle.md](dispatch-lifecycle.md) — entity FSMs (loop / assignment / agent_run / claim), brief-ack semantics, log-file diagnostic playbook
 - [runtime-notes.md](runtime-notes.md)
 - pln#394 `feat/loop-engine-mvp`
 - pln#395 `feat/review-loop-protocol`