brainclaw 1.26.2 → 1.28.0

package/dist/core/runtime-signals.js

@@ -36,15 +36,17 @@ function runtimeDir(root) {
  * `runtime/ack/<id>.ack` location (pln#476); the liveness signals live under
  * `runtime/signal/<id>.<signal>`.
  */
-export function getRuntimeSignalPath(root, assignmentId, signal) {
+export function getRuntimeSignalPath(root, assignmentId, signal, runId) {
+    const key = runId ? `${assignmentId}.${runId}` : assignmentId;
     if (signal === 'ack') {
-        return path.join(runtimeDir(root), 'ack', `${assignmentId}.ack`);
+        return path.join(runtimeDir(root), 'ack', `${key}.ack`);
     }
-    return path.join(runtimeDir(root), 'signal', `${assignmentId}.${signal}`);
+    return path.join(runtimeDir(root), 'signal', `${key}.${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`);
+export function getRuntimeLogPath(root, assignmentId, stream, runId) {
+    const key = runId ? `${assignmentId}.${runId}` : assignmentId;
+    return path.join(runtimeDir(root), 'log', `${key}.${stream}.log`);
 }
 /**
  * Worktree-local heartbeat path (sprint 1.5). The project-root signal path is
@@ -55,8 +57,8 @@ export function getRuntimeLogPath(root, assignmentId, stream) {
  * write, so briefs point step-0 here, and every heartbeat reader checks BOTH
  * locations.
  */
-export function getWorktreeHeartbeatPath(worktreePath, assignmentId) {
-    return path.join(worktreePath, `.brainclaw-heartbeat-${assignmentId}`);
+export function getWorktreeHeartbeatPath(worktreePath, assignmentId, runId) {
+    return path.join(worktreePath, `.brainclaw-heartbeat-${assignmentId}${runId ? `-${runId}` : ''}`);
 }
 /** Ensure the ack / signal / log directories exist (best-effort, recursive). */
 export function ensureRuntimeDirs(root) {
@@ -65,14 +67,43 @@ export function ensureRuntimeDirs(root) {
         fs.mkdirSync(path.join(base, sub), { recursive: true });
     }
 }
-export function signalExists(root, assignmentId, signal) {
+export function signalExists(root, assignmentId, signal, runId) {
     try {
-        return fs.existsSync(getRuntimeSignalPath(root, assignmentId, signal));
+        return fs.existsSync(getRuntimeSignalPath(root, assignmentId, signal, runId));
     }
     catch {
         return false;
     }
 }
+/** Read the bootstrap's effective-environment attestation. Empty legacy acks return undefined. */
+export function readContractAck(root, assignmentId, runId) {
+    try {
+        const raw = fs.readFileSync(getRuntimeSignalPath(root, assignmentId, 'ack', runId), 'utf8').trim();
+        if (!raw)
+            return undefined;
+        const parsed = JSON.parse(raw);
+        if ((parsed.status === 'accepted' || parsed.status === 'rejected')
+            && typeof parsed.turn_id === 'string'
+            && typeof parsed.run_id === 'string'
+            && typeof parsed.nonce === 'string'
+            && typeof parsed.contract_hash === 'string'
+            && typeof parsed.capability_snapshot_hash === 'string') {
+            return {
+                status: parsed.status,
+                turn_id: parsed.turn_id,
+                run_id: parsed.run_id,
+                nonce: parsed.nonce,
+                contract_hash: parsed.contract_hash,
+                capability_snapshot_hash: parsed.capability_snapshot_hash,
+                ...(typeof parsed.attempt_epoch === 'number' ? { attempt_epoch: parsed.attempt_epoch } : {}),
+                ...(typeof parsed.workspace_digest === 'string' ? { workspace_digest: parsed.workspace_digest } : {}),
+                ...(typeof parsed.cwd === 'string' ? { cwd: parsed.cwd } : {}),
+            };
+        }
+    }
+    catch { /* absent, legacy or malformed */ }
+    return undefined;
+}
 function readHeartbeatFile(p) {
     try {
         const stat = fs.statSync(p);
@@ -103,10 +134,10 @@ function readHeartbeatFile(p) {
  * worktree-local heartbeat — sandboxed workers can only write the latter. When
  * both exist, the freshest mtime wins.
  */
-export function readHeartbeat(root, assignmentId, worktreePath) {
-    const projectInfo = readHeartbeatFile(getRuntimeSignalPath(root, assignmentId, 'heartbeat'));
+export function readHeartbeat(root, assignmentId, worktreePath, runId) {
+    const projectInfo = readHeartbeatFile(getRuntimeSignalPath(root, assignmentId, 'heartbeat', runId));
     const worktreeInfo = worktreePath
-        ? readHeartbeatFile(getWorktreeHeartbeatPath(worktreePath, assignmentId))
+        ? readHeartbeatFile(getWorktreeHeartbeatPath(worktreePath, assignmentId, runId))
         : { exists: false };
     if (!projectInfo.exists)
         return worktreeInfo;
@@ -120,17 +151,17 @@ export function readHeartbeat(root, assignmentId, worktreePath) {
  * still produces a legacy presence-only marker, which stays a valid life-sign
  * via signalExists but is NOT accepted as turn-owned evidence (PR2b-c).
  */
-export function writeCompletionSignal(root, assignmentId, body) {
-    const p = getRuntimeSignalPath(root, assignmentId, body.status);
+export function writeCompletionSignal(root, assignmentId, body, runId) {
+    const p = getRuntimeSignalPath(root, assignmentId, body.status, runId);
     fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, JSON.stringify(body), 'utf-8');
 }
 /** Parse ONE turn-keyed sentinel body, or undefined if absent / legacy
  *  presence-only / non-JSON / missing correlation keys. Never throws. */
-function readOneCompletionSignal(root, assignmentId, status) {
+function readOneCompletionSignal(root, assignmentId, status, runId) {
     let raw;
     try {
-        raw = fs.readFileSync(getRuntimeSignalPath(root, assignmentId, status), 'utf-8').trim();
+        raw = fs.readFileSync(getRuntimeSignalPath(root, assignmentId, status, runId), 'utf-8').trim();
     }
     catch {
         return undefined; // sentinel absent
@@ -147,6 +178,12 @@ function readOneCompletionSignal(root, assignmentId, status) {
                 turn_id: parsed.turn_id,
                 run_id: parsed.run_id,
                 nonce: parsed.nonce,
+                ...(typeof parsed.contract_hash === 'string' ? { contract_hash: parsed.contract_hash } : {}),
+                ...(typeof parsed.capability_snapshot_hash === 'string'
+                    ? { capability_snapshot_hash: parsed.capability_snapshot_hash }
+                    : {}),
+                ...(typeof parsed.attempt_epoch === 'number' ? { attempt_epoch: parsed.attempt_epoch } : {}),
+                ...(typeof parsed.workspace_digest === 'string' ? { workspace_digest: parsed.workspace_digest } : {}),
                 status: parsed.status,
                 at: typeof parsed.at === 'string' ? parsed.at : '',
             };
@@ -162,10 +199,10 @@ function readOneCompletionSignal(root, assignmentId, status) {
  * and WITHHOLD an irreversible auto-stop (spec §13 R4), rather than silently
  * collapsing to one. Legacy presence-only markers read as absent here.
  */
-export function readCompletionSignals(root, assignmentId) {
+export function readCompletionSignals(root, assignmentId, runId) {
     const out = {};
-    const completed = readOneCompletionSignal(root, assignmentId, 'completed');
-    const failed = readOneCompletionSignal(root, assignmentId, 'failed');
+    const completed = readOneCompletionSignal(root, assignmentId, 'completed', runId);
+    const failed = readOneCompletionSignal(root, assignmentId, 'failed', runId);
     if (completed)
         out.completed = completed;
     if (failed)
@@ -178,8 +215,8 @@ export function readCompletionSignals(root, assignmentId) {
  * CALLERS THAT ACT IRREVERSIBLY must use {@link readCompletionSignals} instead
  * so a completed+failed contradiction is not hidden (spec §13 R4).
  */
-export function readCompletionSignal(root, assignmentId) {
-    const both = readCompletionSignals(root, assignmentId);
+export function readCompletionSignal(root, assignmentId, runId) {
+    const both = readCompletionSignals(root, assignmentId, runId);
     return both.completed ?? both.failed;
 }
 /**
@@ -212,9 +249,9 @@ export function decodeOemAwareBuffer(buf) {
     return out;
 }
 /** Read the tail of a captured stream log (for failed_silent diagnostics). */
-export function readLogTail(root, assignmentId, stream, maxBytes = 2000) {
+export function readLogTail(root, assignmentId, stream, maxBytes = 2000, runId) {
     try {
-        const p = getRuntimeLogPath(root, assignmentId, stream);
+        const p = getRuntimeLogPath(root, assignmentId, stream, runId);
         const buf = fs.readFileSync(p);
         let slice = buf.length > maxBytes ? buf.subarray(buf.length - maxBytes) : buf;
         // A byte-offset tail can start mid-UTF-8-sequence; dropping leading
@@ -285,7 +322,7 @@ export function latestWorktreeFileMtimeMs(worktreePath, maxDepth = 4) {
  * fixing the false-`stalled` verdict (field debrief P1#1). Returns undefined
  * when nothing is observable.
  */
-export function latestActivityMs(root, assignmentId, worktreePath) {
+export function latestActivityMs(root, assignmentId, worktreePath, runId) {
     let latest;
     const bump = (ms) => {
         if (ms !== undefined && (latest === undefined || ms > latest))
@@ -293,7 +330,7 @@ export function latestActivityMs(root, assignmentId, worktreePath) {
     };
     for (const stream of ['stdout', 'stderr']) {
         try {
-            bump(fs.statSync(getRuntimeLogPath(root, assignmentId, stream)).mtimeMs);
+            bump(fs.statSync(getRuntimeLogPath(root, assignmentId, stream, runId)).mtimeMs);
         }
         catch { /* no log */ }
     }

package/dist/core/schema.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { CapabilitySnapshotSchema, ExecutionContractRefSchema, RuntimeCapabilityObservationSchema } from './execution-contract.js';
 // --- Helpers ---
 /** Coerce legacy effort strings ("30min", "2h", "1d") to integer minutes for migration.
  *  Already-numeric values pass through unchanged. Unparseable strings → undefined. */
@@ -797,6 +798,9 @@ export const AssignmentSchema = z.object({
     description: z.string(),
     lane: z.string().optional(),
     worktree_path: z.string().optional(),
+    /** Immutable attempt contract identity; optional for legacy records. */
+    execution_contract_ref: ExecutionContractRefSchema.optional(),
+    capability_snapshot: CapabilitySnapshotSchema.optional(),
     // Status FSM
     status: AssignmentStatusSchema,
     status_reason: z.string().optional(),
@@ -873,6 +877,26 @@ export const AgentRunSchema = z.object({
     shell: z.string().optional(),
     pid: z.number().int().positive().optional(),
     provider_run_id: z.string().optional(),
+    /** Immutable attempt contract identity; optional for legacy records. */
+    execution_contract_ref: ExecutionContractRefSchema.optional(),
+    capability_snapshot: CapabilitySnapshotSchema.optional(),
+    /** Runtime observation is additive and never mutates the hashed capability snapshot. */
+    runtime_capability_observation: RuntimeCapabilityObservationSchema.optional(),
+    harness_exit_diagnostic: z.object({
+        adapter_id: z.string().min(1),
+        adapter_version: z.string().min(1),
+        transport_status: z.enum(['completed', 'failed', 'timed_out', 'cancelled']),
+        protocol_status: z.enum(['valid', 'invalid', 'partial', 'absent']),
+        message: z.string().min(1).optional(),
+    }).optional(),
+    /** Monotone fence: once present, no reconciler may auto-converge or respawn this generation. */
+    execution_contract_anomaly: z.object({
+        detected_at: z.string().min(1),
+        source: z.enum(['bootstrap_ack', 'completion_signal', 'lane_result', 'reconciler']),
+        reason: z.string().min(1),
+        accepted_contract_hash: z.string().optional(),
+        accepted_capability_snapshot_hash: z.string().optional(),
+    }).optional(),
     created_at: z.string(),
     updated_at: z.string().optional(),
     launched_at: z.string().optional(),
@@ -1012,6 +1036,9 @@ export const RuntimeEventTypeSchema = z.enum([
     // pln#521 P4 — a turn-owned loop artifact was harvested + integrated into the loop
     // by reconcileTurn (observability for the harvest path).
     'loop_artifact_harvested',
+    // AttemptAuthority v2 — causal takeover telemetry. The immutable close cell
+    // remains authoritative; this event is an operator-facing projection only.
+    'attempt_takeover',
 ]);
 /**
  * pln#526 — LANE-RESULT convention. A dispatched worker writes a single
@@ -1038,6 +1065,12 @@ export const LaneResultSchema = z.object({
     turn_id: z.string().optional(),
     run_id: z.string().optional(),
     nonce: z.string().optional(),
+    /** AttemptAuthority v2 full-fence coordinates (required by v2 acceptance). */
+    attempt_epoch: z.number().int().nonnegative().optional(),
+    workspace_digest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    /** ExecutionContract v1 acceptance echoed by the worker/bootstrap. */
+    execution_contract_hash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    capability_snapshot_hash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     status: z.enum(['completed', 'blocked', 'failed']),
     summary: z.string(),
     /** Paths or refs the worker produced (commits, files, docs). */
@@ -1058,6 +1091,11 @@ export const LaneResultSchema = z.object({
      * reconcile this to its phase's required artifact type.
      */
     artifact_type: z.string().min(1).optional(),
+    /** Synthesis-only executable acceptance policy for the downstream implementation loop. */
+    implementation_verify: z.object({
+        command: z.array(z.string().min(1)).min(1),
+        timeout_ms: z.number().int().positive().max(15 * 60 * 1000).optional(),
+    }).optional(),
     /**
      * pln#628 Focus 4B — review-loop verdict. A worker running a review-loop turn
      * sets this to signal whether the change is good to merge (`approve`) or needs
@@ -1087,6 +1125,8 @@ export const RuntimeEventSchema = z.object({
     // `run_id` already present above; `nonce` == launch-generation token.
     turn_id: z.string().optional(),
     nonce: z.string().optional(),
+    attempt_epoch: z.number().int().nonnegative().optional(),
+    workspace_digest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     claim_id: z.string().optional(),
     message_id: z.string().optional(),
     plan_id: z.string().optional(),

package/dist/core/spawn-check.js

@@ -18,7 +18,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { buildInvokeCommand, getSpawnableAgents, getCapabilityProfile, } from './agent-capability.js';
+import { getSpawnableAgents, getCapabilityProfile, } from './agent-capability.js';
+import { buildHarnessInvocation } from './harness-adapters/index.js';
 import { defaultExecutionAdapter, resolveBinaryOnPath } from './execution-adapters.js';
 import { signalExists, readLogTail } from './runtime-signals.js';
 import { recognizeStderrSignature } from './dispatch-status.js';
@@ -63,7 +64,7 @@ export async function checkAgentSpawn(agent, options = {}) {
         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' });
+        ?? buildHarnessInvocation(agent, options.probePrompt ?? DEFAULT_PROBE_PROMPT, { mode: 'consult' })?.invoke;
     if (!invoke) {
         return { agent, binary, status: 'no_template', delivered: false, completed: false, duration_ms: 0, detail: 'could not build invoke command' };
     }

package/dist/core/upgrades/backup.js

@@ -6,6 +6,29 @@ export const BACKUP_DIR_PREFIX = '.brainclaw.bak-';
 export const BACKUP_MANIFEST_FILENAME = 'backup.json';
 export const ROLLBACK_PARKED_PREFIX = '.brainclaw.rollback-';
 export const ROLLBACK_STAGING_PREFIX = '.brainclaw.restoring-';
+const RETRYABLE_RENAME_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_ATTEMPTS = 6;
+const RENAME_RETRY_DELAY_MS = 25;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** NTFS/Defender can transiently deny an otherwise valid directory rename. */
+function renameWithRetry(from, to) {
+    for (let attempt = 0; attempt < RENAME_ATTEMPTS; attempt += 1) {
+        try {
+            fs.renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error instanceof Error && 'code' in error
+                ? error.code
+                : undefined;
+            if (!code || !RETRYABLE_RENAME_CODES.has(code) || attempt === RENAME_ATTEMPTS - 1)
+                throw error;
+            sleepSync(RENAME_RETRY_DELAY_MS * (attempt + 1));
+        }
+    }
+}
 export const BackupManifestSchema = z.object({
     schema_version: z.literal(1),
     created_at: z.string().datetime(),
@@ -74,7 +97,7 @@ export function createBackup(options) {
     };
     fs.writeFileSync(path.join(stagingPath, BACKUP_MANIFEST_FILENAME), JSON.stringify(manifest, null, 2), 'utf-8');
     try {
-        fs.renameSync(stagingPath, finalPath);
+        renameWithRetry(stagingPath, finalPath);
     }
     catch (error) {
         try {
@@ -198,7 +221,7 @@ export function restoreBackup(options) {
     let parked = false;
     if (fs.existsSync(storePath)) {
         try {
-            fs.renameSync(storePath, parkedPath);
+            renameWithRetry(storePath, parkedPath);
             parked = true;
         }
         catch (error) {
@@ -209,7 +232,7 @@ export function restoreBackup(options) {
     // Step 4: swap staging → live. On failure, un-park so the store
     // is never left missing; staging dir is cleaned.
     try {
-        fs.renameSync(stagingPath, storePath);
+        renameWithRetry(stagingPath, storePath);
     }
     catch (error) {
         const swapMessage = error.message;
@@ -218,7 +241,7 @@ export function restoreBackup(options) {
             throw new BackupError('restore_swap_failed', `Could not swap staging into live path: ${swapMessage}`);
         }
         try {
-            fs.renameSync(parkedPath, storePath);
+            renameWithRetry(parkedPath, storePath);
         }
         catch (unparkError) {
             throw new BackupError('restore_catastrophic', `Could not swap staging into live path: ${swapMessage}; also failed to restore parked live store: ${unparkError.message}. ` +

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.26.2 on 2026-08-22T12:18:05.969Z
+// Source: brainclaw v1.28.0 on 2026-08-24T07:09:07.814Z
 export const FACTS = {
-  "version": "1.26.2",
-  "generated_at": "2026-08-22T12:18:05.969Z",
+  "version": "1.28.0",
+  "generated_at": "2026-08-24T07:09:07.814Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -231,7 +231,8 @@ export const FACTS = {
         "mcp_config_scope": "machine",
         "role_capabilities": [
           "execute",
-          "review"
+          "review",
+          "consult"
         ],
         "max_concurrent_tasks": 5
       },
@@ -477,7 +478,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-22T12:18:03.871Z",
+    "generated_at": "2026-08-24T07:09:05.728Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -486,7 +487,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 76,
+        "duration_ms_median": 81,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -494,7 +495,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 123,
+        "duration_ms_median": 120,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -502,7 +503,7 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 11,
+        "duration_ms_median": 13,
         "payload_chars_median": 1305,
         "payload_tokens_est_median": 326
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.26.2",
-  "generated_at": "2026-08-22T12:18:05.969Z",
+  "version": "1.28.0",
+  "generated_at": "2026-08-24T07:09:07.814Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -229,7 +229,8 @@
         "mcp_config_scope": "machine",
         "role_capabilities": [
           "execute",
-          "review"
+          "review",
+          "consult"
         ],
         "max_concurrent_tasks": 5
       },
@@ -475,7 +476,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-22T12:18:03.871Z",
+    "generated_at": "2026-08-24T07:09:05.728Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -484,7 +485,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 76,
+        "duration_ms_median": 81,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -492,7 +493,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 123,
+        "duration_ms_median": 120,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -500,7 +501,7 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 11,
+        "duration_ms_median": 13,
         "payload_chars_median": 1305,
         "payload_tokens_est_median": 326
       }

package/docs/cli.md

@@ -1003,6 +1003,54 @@ brainclaw run claude-code        # run the claude-code profile
 brainclaw run claude-code --dry  # preview the resolved command
 ```
 
+### `brainclaw loop <subcommand>`
+
+Operator wrappers for the state-changing Loop verbs most useful from a shell.
+They drive the same shared runtime for review, ideation, implementation,
+research, and debug; they are not a review-only command group.
+
+| Subcommand | Required arguments/options | Purpose |
+|---|---|---|
+| `turn <loop_id>` | `--slot <slot_id>` | Record a turn assignment. The CLI wrapper is state-only; MCP `turn` additionally supports trusted `dispatch:true`. |
+| `complete-turn <loop_id>` | `--slot <slot_id> --outcome <done\|failed\|cancelled>` | Complete a manually driven slot turn; optional `--artifact <json>`. AttemptAuthority v2 workers must also pass the full fence: `--assignment-id`, `--turn-id`, `--run-id`, `--nonce`, `--attempt-epoch`, `--execution-contract-hash`, and `--workspace-digest`. |
+| `takeover <loop_id>` | slot, turn, expected epoch, cause, liveness evidence, external-effect policy, next workspace and coordinator identity | Fence one physical generation and arm a successor without changing the logical Assignment. |
+| `advance <loop_id>` | — | Advance through the protocol; optional `--to-phase`, `--force`, `--reason`. |
+| `add-artifact <loop_id>` | `--phase --type --body` | Attach a typed artifact; optional producer and ref. |
+
+```bash
+brainclaw loop advance lop_abc --json
+brainclaw loop takeover lop_abc \
+  --slot lsl_abc --turn-id tat_abc --expected-epoch 0 \
+  --cause "worker is no longer live" \
+  --liveness-evidence "wrapper exited; heartbeat stale" \
+  --external-effect-policy idempotent \
+  --next-workspace-path ../brainclaw-retry --agent coordinator
+```
+
+The full public lifecycle (`open`, `get`, `list`, `pause`, `resume`, `close`,
+`bind`, `verify`, `request_input`, `provide_input`, and the verbs above) is the
+MCP `bclaw_loop(intent)` facade. Direct MCP `open` requires
+`allow_orphan=true`; review and ideation normally start through
+`bclaw_coordinate` so opening and dispatch stay one operation. See the
+[Loop Engine](concepts/loop-engine.md) and its five [protocol guides](loops/).
+
+### `brainclaw attempt-authority <subcommand>`
+
+Two-release activation surface for AttemptAuthority v2 writers:
+
+| Subcommand | Purpose |
+|---|---|
+| `status [--json]` | Inspect writer version, local authority home and active membership. |
+| `prepare --writers <agent_ids...>` | Publish a Release-A membership guard; optional epoch and audited actor. |
+| `ack --membership-epoch <n> --agent-id <id>` | Publish the named writer's signed immutable ACK. Writers may ACK in parallel. |
+| `activate --membership-epoch <n>` | Activate a fully acknowledged membership epoch. |
+
+Do not use `activate` as the first rollout step. Drain old writers, create and
+verify a private store snapshot, complete every ACK, then canary Release B on
+the authority home. After the first v2 generation cell, direct downgrade is
+refused; use the controlled export/restore procedure in
+[Attempt authority](concepts/attempt-authority.md#migration-and-rollout-runbook).
+
 ### `brainclaw plan create <text>`
 
 Create a shared work item.
@@ -1984,7 +2032,7 @@ The default catalog is intentionally small and centred on the canonical grammar.
 |---|---|
 | `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)` | Open, inspect, or drive a multi-turn loop. The public lifecycle is `open`, `get`, `list`, `turn`, `complete_turn`, `advance`, `add_artifact`, `pause`, `resume`, and `close`; implementation loops also add `bind` and `verify`, and any kind may use `request_input` / `provide_input`. `bclaw_coordinate` / `bclaw_dispatch` remain the ergonomic review and ideation shortcuts. A direct `open` must include `allow_orphan: true` to acknowledge that the caller will dispatch or drive it. |
+| `bclaw_loop(intent)` | Open, inspect, or drive a multi-turn loop. The public lifecycle is `open`, `get`, `list`, `turn`, `complete_turn`, `advance`, `add_artifact`, `pause`, `resume`, and `close`; implementation loops also add engine-only `bind` (validate the linked sequence and enter `execute`, never spawn) and `verify`, and any kind may use `request_input` / `provide_input`. Trusted `turn(dispatch=true)` is the common worker launch path. `bclaw_coordinate` / `bclaw_dispatch` remain ergonomic shortcuts. A direct `open` must include `allow_orphan: true` to acknowledge that the caller will dispatch or drive it. |
 
 **Sequences**: