brainclaw 1.7.5 → 1.9.0

package/dist/core/instruction-templates.js

@@ -7,10 +7,11 @@
  *   LIVE (gitignored, frequent refresh) — plans, claims, traps, decisions, sequences
  *
  * Tier delivery:
- *   Tier A (MCP + hooks): stable file only — live context via hooks/MCP
+ *   Tier A (managed MCP/native surface): stable file only — live context via MCP or native runtime surfaces
  *   Tier B (MCP, no hooks): stable file + live companion file
  *   Tier C (no MCP): stable file + live companion file (richer, only source)
  */
+import { resolveExportTarget } from './agent-files.js';
 /**
  * Render the STABLE brainclaw section content for an instruction file.
  * This is the versioned file that changes rarely (on upgrade, convention change).
@@ -212,7 +213,7 @@ function renderVisionSection(input) {
 }
 function renderHeader(input) {
     return [
-        `> Managed by brainclaw v${input.brainclawVersion} — do not edit manually.`,
+        `> Managed by brainclaw — do not edit manually.`,
         `> Regenerate: brainclaw export --format ${formatForAgent(input.profile.name)} --write`,
     ].join('\n');
 }
@@ -222,50 +223,30 @@ function renderLiveHeader(_input) {
         `> Last updated: ${new Date().toISOString().slice(0, 19)}`,
     ].join('\n');
 }
+// Kept deliberately small (pln#542): entry point + grammar + escalation
+// pointer. Everything else is discoverable via the `next_actions` carried by
+// every MCP response — protocol teaching moved out of this file.
 function renderSessionProtocol() {
     return [
         '## brainclaw — session protocol',
         '',
-        '1. Call `bclaw_work(intent)` to start working — it handles session, context, and claims automatically. Returns a compact payload by default; pass `compact: false` for the full context result, or use `bclaw_context(kind="memory")` after.',
-        '2. Use the canonical grammar (`bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition`) to work with memory objects (plans, decisions, constraints, traps, handoffs, claims, candidates, runtime_notes, …). Read `## brainclaw — working with memory` below for the full map.',
+        '1. Call `bclaw_work(intent)` (consult|execute|resume|review) — one call handles session, context, and claim (execute). Every response carries `next_actions` with the exact follow-up calls: follow those instead of memorizing the API.',
+        '2. Canonical grammar for memory objects: `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` (entity, …).',
         '3. Do not assume project state without reading brainclaw context first.',
         '',
-        '_Escalation path (only when you orchestrate other agents) — by goal:_',
-        '- Start a code review / consult an agent / assign a scope → `bclaw_coordinate(intent=review|consult|assign)`',
-        '- Parallelize execute across a sequence\'s lanes → `bclaw_dispatch(intent=execute)`',
-        '- Drive a turn in a loop already assigned to you → `bclaw_loop(intent=turn|complete_turn|advance|close)`',
-        '',
-        'Do NOT call `bclaw_loop(intent=open)` directly — it creates a loop structure without dispatch, so the reviewer/participant never gets the work. Use the goal entries above.',
-        '',
-        '_How to verify a dispatch actually worked:_ `execution_status="delivered_and_started"` only means the brief-ack sentinel was touched — it does NOT mean the worker is doing useful work. (1) Call `bclaw_dispatch_status(target_id=<asgn_…|clm_…|lop_…|run_…>)` — the purpose-built facade: it resolves the linked entities, reads the runtime sentinels (`ack` / `heartbeat` / `completed` / `failed`) and the captured stdout/stderr tails, checks pid liveness, and returns a single health verdict plus a recommended next action. This is the `verify_with` target named in the coordinate/dispatch response — prefer it over assembling the picture by hand. (2) Do NOT diagnose liveness from the tracked pid yourself: on Windows an ack-wrapped spawn runs under a `cmd.exe` shell, so `agent_run.pid` is the wrapper (which exits early by design), NOT the real worker — `Get-Process -Id <pid>` reads it dead while the worker is alive and committing. Trust the sentinel-derived verdict instead; the reconciler already infers `completed` from a post-start commit on the worktree branch even when the worker never called `bclaw_assignment_update`. (3) Fallback only if the facade is unavailable: `bclaw_find(entity="agent_run", filter={assignment_id})` plus the captured streams at `.brainclaw/coordination/runtime/log/<assignment_id>.{stdout,stderr}.log` — note that `claude -p` buffers stdout until exit, so an empty log mid-run is expected; use the `heartbeat` sentinel as the live progress signal, not stdout. Full FSM tables + diagnostic decision tree in `docs/concepts/dispatch-lifecycle.md`.',
+        'Escalation (only when orchestrating other agents): `bclaw_coordinate(intent=review|consult|assign)`. Verify any dispatch with `bclaw_dispatch_status(target_id)` — trust its sentinel-based verdict, not the tracked pid. Details: `docs/concepts/dispatch-lifecycle.md`.',
     ].join('\n');
 }
 function renderUserWorkflow() {
     return [
         '## brainclaw — user workflow',
         '',
-        'The intended end-to-end flow, executable by a single agent:',
-        '',
         '    ideation → plan (+ steps) → claim → implement → release claim → review → close step/plan → merge',
         '',
-        'Multi-agent coordination is optional — use the escalation path only when delegating to another agent.',
-        '`sequence` is optional: add it between plan and claim when you want parallelized lanes across agents.',
-        '',
-        '**Entity → role in the flow:**',
-        '- `plan` — intended outcome. Create with `bclaw_create(plan, …)`, decompose with `bclaw_add_step`.',
-        '- `step` — incremental unit inside a plan; mark done with `bclaw_complete_step` as you implement.',
-        '- `sequence` — ordered lanes when work can be parallelized across claims/agents (optional).',
-        '- `claim` — advisory reservation of a scope before editing; release once implementation is ready for review.',
-        '- `handoff` — immutable snapshot of what moved to the next stage (review, merge).',
-        '- `candidate` — proposed decision / constraint / trap awaiting review before entering durable memory.',
-        '- `decision` / `constraint` / `trap` / `runtime_note` — captured along the way to preserve context for future sessions.',
+        'Entities: `plan` (intended outcome) · `step` (unit inside a plan) · `sequence` (optional parallel lanes) · `claim` (advisory scope reservation) · `handoff` (stage snapshot) · `candidate` (proposed memory awaiting review) · `decision`/`constraint`/`trap`/`runtime_note` (context captured along the way).',
         '',
-        '**Review & Fix Loop (multi-turn delegation):**',
-        '- Start: `bclaw_coordinate(intent=review, open_loop=true, review_mode=symmetric|asymmetric, targetAgents=[reviewer])` — opens the loop AND dispatches the first turn to the reviewer.',
-        '- Drive: `bclaw_loop(intent=turn|complete_turn|advance|close)` for turns assigned to your slot.',
-        '- Anti-pattern: `bclaw_loop(intent=open)` alone — creates the loop structure without any dispatch, so nothing actually runs.',
-        '',
-        'Ideation / Debug / Research / Planning loops — *planned*. See `docs/product/agent-first-model.md` §3.',
+        'Review & Fix Loop: start with `bclaw_coordinate(intent=review, open_loop=true, review_mode=symmetric|asymmetric, targetAgents=[reviewer])` — opens the loop AND dispatches the first turn. Drive your turns with `bclaw_loop(intent=turn|complete_turn|advance|close)`. Parallelize a sequence\'s lanes with `bclaw_dispatch(intent=execute)`.',
+        'Ideation / Debug / Research loops — *planned* (`docs/product/agent-first-model.md` §3).',
     ].join('\n');
 }
 /**
@@ -288,51 +269,16 @@ function renderAutonomyContract() {
     return [
         '## brainclaw — autonomous workflow contract',
         '',
-        'When a brainclaw protocol prescribes the next action after the one you just',
-        'completed, **execute it. Do not ask for permission.** brainclaw\'s coordination',
-        'promise depends on this — every avoidable pause forces the human back into the',
-        'synchronization loop, which is exactly what brainclaw is built to eliminate.',
-        '',
-        '**Protocol-defined transitions you MUST execute autonomously:**',
-        '',
-        '- IF you completed a review (assigned via `bclaw_coordinate(intent=review)` or',
-        '  inbox `review_request` message) → produce findings → **send the reply with',
-        '  your verdict via `bclaw_send_message(type="reply", thread_id=…)`**. Do not',
-        '  ask whether to send.',
-        '- IF you receive a reply with an `LGTM` verdict AND you are the requester →',
-        '  **close the loop and merge the branch yourself** (when you own the merge).',
-        '  Do not pass the merge to the human.',
-        '- IF the reviewer reply contains findings → **apply the symmetric fixes you',
-        '  can make**, commit on the same branch, then reroute via',
-        '  `bclaw_send_message(type="reply", …)` for re-review. Do not stop after the',
-        '  fixes.',
-        '- IF you have an active claim and your work is complete → call',
-        '  `bclaw_release_claim(id=…, planStatus="done")`. Do not leave the claim',
-        '  active for someone else to clean up.',
-        '- IF you have an `assignment_id` (you were dispatched via `bclaw_coordinate` /',
-        '  `bclaw_dispatch`) → at end of work, call',
-        '  `bclaw_assignment_update(assignment_id=…, status="completed", artifacts=[…])`.',
-        '  The coordinator depends on this lifecycle event; without it, the loop never',
-        '  converges and the supervisor cannot tell success from silent failure.',
-        '',
-        '**Legitimate reasons to pause and ask the human:**',
+        'When a brainclaw protocol prescribes the next action, **execute it. Do not ask for permission.** (Empirical: May 2026 multi-agent review threads stalled at "should I send this reply? / merge?", forcing the human to carry context between agents.)',
         '',
-        '1. The action would be **destructive AND irreversible AND outside the',
-        '   protocol** (e.g. `git push --force` on a public branch, dropping a',
-        '   production database, deleting a non-empty memory cluster). Protocol-',
-        '   defined merges to a local branch are NOT in this category.',
-        '2. The protocol genuinely **does not specify** the next action (e.g. a',
-        '   verdict that splits the dispatched work into two new plans — needs',
-        '   scoping judgement only the human owns).',
-        '3. The user has **explicitly told you to confirm** before specific actions',
-        '   in this session.',
+        'MUST execute autonomously:',
+        '- review done → send the verdict: `bclaw_send_message(type="reply", thread_id=…)`',
+        '- LGTM received and you own the merge → close the loop and merge yourself',
+        '- findings received → apply fixes, commit, reply for re-review',
+        '- work complete → `bclaw_release_claim(id=…, planStatus="done")`',
+        '- dispatched work done → `bclaw_assignment_update(assignment_id=…, status="completed", artifacts=[…])`',
         '',
-        'Asking *"should I send the reply?"* on a protocol-defined send is a UX bug,',
-        'not safety. If the next step appears in the workflow above — do it. The',
-        'empirical cost of skipping the contract: in May 2026, multi-agent review',
-        'threads systematically stalled at "should I send this reply?" / "should I',
-        'merge?", forcing the human supervisor to manually carry context between',
-        'agents. Stop reproducing that pattern.',
+        'Pause for the human ONLY when the action is destructive AND irreversible AND outside the protocol, when the protocol does not specify the next step, or when the user explicitly asked for confirmation.',
     ].join('\n');
 }
 // ─── Constraint sections (split by category) ────────────────────────────────
@@ -371,33 +317,13 @@ function renderAvailableTools() {
     return [
         '## brainclaw — available tools',
         '',
-        'The default MCP catalog is intentionally small. Start with `bclaw_work`, then use the canonical grammar for reads/writes on any entity. Coordination facades below are an **escalation path** for agents that orchestrate other agents — not the default loop.',
+        '**Entry:** `bclaw_work(intent, compact?, budget_tokens?)` · `bclaw_context(kind=memory|execution|board|board_summary|delta)`',
+        '**Canonical grammar** (entities: plan, decision, constraint, trap, handoff, runtime_note, candidate, sequence, claim, action, assignment, agent_run): `bclaw_find`, `bclaw_get`, `bclaw_create`, `bclaw_update`, `bclaw_remove`, `bclaw_transition`. Reads accept `budget_tokens` and `project` (cross-project routing — unknown names throw).',
+        '**Session/claims:** `bclaw_session_start`, `bclaw_session_end`, `bclaw_claim`, `bclaw_release_claim` · **steps:** `bclaw_add_step`, `bclaw_complete_step`, `bclaw_update_step`, `bclaw_delete_step` · **sequences:** `bclaw_list_sequences`, `bclaw_create_sequence`, `bclaw_update_sequence`, `bclaw_delete_sequence`',
+        '**Inbox:** `bclaw_read_inbox`, `bclaw_ack_message`, `bclaw_send_message`, `bclaw_correct_handoff` · **capture:** `bclaw_write_note`, `bclaw_quick_capture(text, type?)` · **search:** `bclaw_search` · **setup:** `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`',
+        '**Escalation (orchestrators):** `bclaw_coordinate(intent=review|consult|assign|ideate)` · `bclaw_dispatch(intent=execute)` on an active sequence · `bclaw_loop(intent=turn|complete_turn|advance|close)` to drive turns · `bclaw_dispatch_status(target_id)` to verify',
         '',
-        '**Entry facades:** `bclaw_work(intent, compact?)`, `bclaw_context(kind)` — bclaw_work defaults to compact:true (minimal payload); use compact:false or bclaw_context for full memory',
-        '**Canonical grammar (standard tier) — your main tool for working with memory:**',
-        '- `bclaw_find(entity, filter?)` — list by type',
-        '- `bclaw_get(entity, id)` — read one',
-        '- `bclaw_create(entity, data)` — add a new plan / decision / constraint / trap / handoff / candidate / runtime_note',
-        '- `bclaw_update(entity, id, patch)` — edit in place',
-        '- `bclaw_remove(entity, id, purge?)` — soft-delete (or purge)',
-        '- `bclaw_transition(entity, id, to)` — change status (e.g. plan todo→in_progress→done)',
-        '',
-        'Entities supported by the grammar: plan, decision, constraint, trap, handoff, runtime_note, candidate, sequence, claim, action, assignment, agent_run.',
-        '',
-        '**Cross-project access (pln#359):** every canonical-grammar call, `bclaw_context`, and `bclaw_coordinate` accept an optional `project: <name>` argument that routes the operation to a linked project (cross_project_links from `brainclaw link list` OR a workspace store-chain child). Identity is sourced from the caller; writes + audit land in the target. Unknown project names throw — no silent fallback. The CLI exposes the same as `--project <name>` (mutually exclusive with `--cwd`). Example: `bclaw_get(entity="trap", id="trp#36", project="brainclaw-site")`. Cross-project `bclaw_coordinate` is inbox-only — auto-spawn is force-disabled because the spawn cwd / worktree are tied to the target repo; the target agent picks the brief up async via its own `bclaw_work`.',
-        '',
-        '**Session + claims:** `bclaw_session_start`, `bclaw_session_end`, `bclaw_claim`, `bclaw_release_claim`',
-        '**Plan steps:** `bclaw_add_step`, `bclaw_complete_step`, `bclaw_update_step`, `bclaw_delete_step`',
-        '**Sequences:** `bclaw_list_sequences`, `bclaw_create_sequence`, `bclaw_update_sequence`, `bclaw_delete_sequence` — create/activate ordered lanes for parallel dispatch. Item shape: `{ planId, stepId?, rank, hard_after?, soft_after?, lane?, scope_hint?, rationale? }`.',
-        '**Inbox + handoffs:** `bclaw_read_inbox`, `bclaw_ack_message`, `bclaw_send_message`, `bclaw_correct_handoff`',
-        '**Notes + search:** `bclaw_write_note`, `bclaw_quick_capture`, `bclaw_search`',
-        '**Escalation (orchestrator path):**',
-        '- Review / consult / assign another agent → `bclaw_coordinate(intent=review|consult|assign)` (use `open_loop=true` on review to also dispatch the reviewer turn)',
-        '- Parallel execute across a sequence\'s lanes → create/update an active sequence, then `bclaw_dispatch(intent=analysis)` and `bclaw_dispatch(intent=execute)`',
-        '- Drive your turn in an already-opened loop → `bclaw_loop(intent=turn|complete_turn|advance|close)`',
-        '**Setup + navigation:** `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`',
-        '',
-        'Legacy per-entity tools (`bclaw_list_plans`, `bclaw_accept`, `bclaw_get_context`, `bclaw_dispatch_review`, …) were removed from the catalog at v1.0 — direct calls still succeed as a migration escape hatch but emit a redirect warning. See `docs/integrations/mcp.md` + `docs/concepts/mcp-governance.md` for the full catalog and stability contract.',
+        'Responses are self-teaching — follow their `next_actions`. Full catalog + stability contract: `docs/integrations/mcp.md`, `docs/concepts/mcp-governance.md`.',
     ].join('\n');
 }
 // ─── Live section renderers ─────────────────────────────────────────────────
@@ -464,7 +390,7 @@ function renderOpenHandoffs(state, limit) {
     if (handoffs.length === 0)
         return undefined;
     return [
-        '## brainclaw — open handoffs',
+        '## brainclaw — open handoffs',
         '',
         ...handoffs.map((h) => {
             const plan = h.plan_id ? ` (${h.plan_id})` : '';
@@ -500,20 +426,13 @@ function priorityOrder(priority) {
         default: return 0;
     }
 }
+/**
+ * Resolve an agent name to its export format by reading AGENT_EXPORT_REGISTRY.
+ * Was a hand-maintained switch that drifted with every new agent — now derived
+ * from the same registry the export command iterates, so adding an agent in one
+ * place updates every consumer (pln#546 step 2).
+ */
 function formatForAgent(agentName) {
-    switch (agentName) {
-        case 'claude-code': return 'claude-md';
-        case 'cursor': return 'cursor-rules';
-        case 'github-copilot': return 'copilot-instructions';
-        case 'opencode':
-        case 'codex': return 'agents-md';
-        case 'antigravity': return 'gemini-md';
-        case 'windsurf': return 'windsurf';
-        case 'cline': return 'cline';
-        case 'roo': return 'roo';
-        case 'kilocode': return 'kilocode';
-        case 'continue': return 'continue';
-        default: return 'agents-md';
-    }
+    return resolveExportTarget(agentName).format;
 }
 //# sourceMappingURL=instruction-templates.js.map

package/dist/core/io.js

@@ -7,6 +7,7 @@ const STORE_LOCK_BASENAME = '.store-mutation';
 const RETRYABLE_RENAME_ERROR_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
 const DEFAULT_RENAME_RETRY_ATTEMPTS = 6;
 const DEFAULT_RENAME_RETRY_DELAY_MS = 25;
+const TMP_ORPHAN_MIN_AGE_MS = 60_000;
 /**
  * Entity-aligned directory mapping.
  * Maps legacy flat directory names to their entity-partitioned paths.
@@ -83,7 +84,9 @@ export function memoryPath(filename, cwd, preferredDirName) {
     return path.join(memoryDir(cwd, preferredDirName), filename);
 }
 export function storeLockPath(cwd, preferredDirName) {
-    const root = cwd ?? process.cwd();
+    // O3 (lop_e2d566765b8b4ce3): canonicalize so two spellings of the same store
+    // (relative vs absolute) produce one lock target / re-entrancy key.
+    const root = path.resolve(cwd ?? process.cwd());
     const dirName = preferredDirName ?? MEMORY_DIR;
     // Keep the store-wide lock alongside the store root so it survives
     // upgrade park/swap renames. Writers and upgrade/rollback all share
@@ -214,6 +217,32 @@ function makeTempPath(filepath) {
     const unique = `${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 10)}`;
     return path.join(dir, `.${base}.${unique}.tmp`);
 }
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function tempOwnerPid(entry) {
+    if (!entry.endsWith('.tmp'))
+        return undefined;
+    const parts = entry.split('.');
+    const pid = Number(parts.at(-4));
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+function shouldRemoveTmp(entry, stat) {
+    const pid = tempOwnerPid(entry);
+    if (!pid)
+        return false;
+    if (Date.now() - stat.mtimeMs < TMP_ORPHAN_MIN_AGE_MS)
+        return false;
+    return !isProcessAlive(pid);
+}
 function isRetryableRenameError(error) {
     if (!(error instanceof Error) || !('code' in error))
         return false;
@@ -261,7 +290,14 @@ export function cleanOrphanFiles(dirPath) {
     try {
         for (const entry of fs.readdirSync(dirPath)) {
             const full = path.join(dirPath, entry);
-            if (entry.endsWith('.tmp') && fs.statSync(full).isFile()) {
+            let stat;
+            try {
+                stat = fs.statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (entry.endsWith('.tmp') && stat.isFile() && shouldRemoveTmp(entry, stat)) {
                 try {
                     fs.unlinkSync(full);
                     removed++;
@@ -269,7 +305,7 @@ export function cleanOrphanFiles(dirPath) {
                 catch { /* already gone */ }
             }
             // Recurse into subdirectories
-            if (fs.statSync(full).isDirectory()) {
+            if (stat.isDirectory()) {
                 removed += cleanOrphanFiles(full);
             }
         }

package/dist/core/json-store.js

@@ -57,7 +57,16 @@ export class JsonStore {
         }
     }
     pathFor(id) {
-        return path.join(this.dirPath, `${id}.json`);
+        if (!/^[A-Za-z0-9_-]+$/.test(id)) {
+            throw new Error(`Invalid ${this.documentType} id '${id}'`);
+        }
+        const root = path.resolve(this.dirPath);
+        const filepath = path.resolve(root, `${id}.json`);
+        const relative = path.relative(root, filepath);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            throw new Error(`Invalid ${this.documentType} id '${id}'`);
+        }
+        return filepath;
     }
 }
 //# sourceMappingURL=json-store.js.map

package/dist/core/lock.js

@@ -3,16 +3,30 @@ import path from 'node:path';
 const DEFAULT_TIMEOUT_MS = 5000;
 const LOCK_RETRY_INTERVAL_MS = 50;
 const LOCK_EXPIRY_MS = 10000;
+const LOCK_REFRESH_INTERVAL_MS = Math.max(1000, Math.floor(LOCK_EXPIRY_MS / 3));
 const heldLocks = new Map();
 function lockFilePath(targetPath) {
     return targetPath + '.lock';
 }
+/**
+ * Review follow-up O3 (lop_e2d566765b8b4ce3): the re-entrancy map key must be
+ * canonical, or two spellings of the same store path (relative vs absolute,
+ * Windows drive-letter case) miss each other in `heldLocks` and the nested
+ * acquire self-deadlocks for the full timeout. Resolve + case-fold (win32) for
+ * the KEY only — the filesystem path used for I/O keeps its original spelling.
+ */
+function lockKey(lockPath) {
+    const resolved = path.resolve(lockPath);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
 function syncSleep(ms) {
     if (ms <= 0)
         return;
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
     try {
         process.kill(pid, 0);
         return true;
@@ -30,43 +44,154 @@ function readLockData(lockPath) {
         return null;
     }
 }
+function randomToken() {
+    return `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+function sameLockData(left, right) {
+    if (!left || !right)
+        return false;
+    return left.pid === right.pid
+        && left.timestamp === right.timestamp
+        && (left.token ?? '') === (right.token ?? '');
+}
+function lockIsOwnedByCurrentProcess(data, token) {
+    return Boolean(data && data.pid === process.pid && data.token === token);
+}
+function writeLockData(lockPath, data, flag) {
+    fs.writeFileSync(lockPath, JSON.stringify(data), { encoding: 'utf-8', flag });
+}
 function tryCreateLock(lockPath) {
-    const data = { pid: process.pid, timestamp: Date.now() };
+    const token = randomToken();
+    const data = { pid: process.pid, timestamp: Date.now(), token };
     try {
-        fs.writeFileSync(lockPath, JSON.stringify(data), { encoding: 'utf-8', flag: 'wx' });
-        return true;
+        writeLockData(lockPath, data, 'wx');
+        return token;
     }
     catch (err) {
         if (err instanceof Error && 'code' in err) {
             const code = err.code;
             if (code === 'EEXIST' || code === 'EPERM' || code === 'EACCES') {
-                return false;
+                return null;
             }
         }
         throw err;
     }
 }
-function tryBreakLock(lockPath) {
-    const data = readLockData(lockPath);
+function lockFileIsOld(lockPath) {
+    try {
+        const stat = fs.statSync(lockPath);
+        return Date.now() - stat.mtimeMs > LOCK_EXPIRY_MS;
+    }
+    catch {
+        return false;
+    }
+}
+function canBreakLock(lockPath, data) {
     if (!data)
+        return lockFileIsOld(lockPath);
+    if (data.pid === process.pid)
         return false;
-    const expired = Date.now() - data.timestamp > LOCK_EXPIRY_MS;
-    const ownerDead = !isProcessAlive(data.pid);
-    if (!expired && !ownerDead)
+    if (isProcessAlive(data.pid))
+        return false;
+    return true;
+}
+/**
+ * Review follow-up O2 (lop_e2d566765b8b4ce3) — accepted residual risk: a
+ * microsecond TOCTOU remains between the second read and the rename, where a
+ * third process can break+reacquire and the renamer steals a live lock. The
+ * restore branch covers it unless a FOURTH process acquires inside that gap.
+ * Decision (sprint 1.5): not closing it. The full fix is an O_EXCL token
+ * handshake protocol — a coordinated change to every lock consumer — and the
+ * residual window requires 4 racing processes inside microseconds on a lock
+ * whose owner is already dead. Strictly better than the old unlink-based break.
+ */
+function tryBreakLock(lockPath) {
+    const observed = readLockData(lockPath);
+    if (!canBreakLock(lockPath, observed))
+        return false;
+    const current = readLockData(lockPath);
+    if (!sameLockData(observed, current) && (observed || current))
+        return false;
+    if (!canBreakLock(lockPath, current))
+        return false;
+    // Dot-separated suffix with pid 4th-from-end so cleanOrphanFiles/tempOwnerPid
+    // can reclaim tombstones from crashed breakers (dash-separated names were
+    // unparseable and accumulated forever).
+    const tombstone = `${lockPath}.stale.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        fs.renameSync(lockPath, tombstone);
+    }
+    catch {
         return false;
+    }
     try {
-        fs.unlinkSync(lockPath);
+        const moved = readLockData(tombstone);
+        if ((observed || moved) && !sameLockData(observed, moved)) {
+            try {
+                if (!fs.existsSync(lockPath))
+                    fs.renameSync(tombstone, lockPath);
+            }
+            catch {
+                // If another process already acquired the lock path, leave the
+                // mismatched tombstone for orphan cleanup instead of deleting live data.
+            }
+            return false;
+        }
+        const token = tryCreateLock(lockPath);
+        try {
+            fs.unlinkSync(tombstone);
+        }
+        catch { /* best effort */ }
+        if (token) {
+            startHeldLock(lockPath, token);
+            return true;
+        }
+        return false;
     }
     catch {
+        try {
+            if (!fs.existsSync(lockPath))
+                fs.renameSync(tombstone, lockPath);
+        }
+        catch {
+            // Best effort recovery; acquisition will retry.
+        }
         return false;
     }
-    return tryCreateLock(lockPath);
+}
+function refreshLock(lockPath, token) {
+    const current = readLockData(lockPath);
+    if (!lockIsOwnedByCurrentProcess(current, token))
+        return;
+    try {
+        // 'r+' writes in place without truncating. Pad with trailing spaces (valid
+        // JSON whitespace) so a payload shorter than the on-disk file can never
+        // leave trailing garbage that would corrupt the lock for readers.
+        let payload = JSON.stringify({ ...current, timestamp: Date.now() });
+        try {
+            const existingSize = fs.statSync(lockPath).size;
+            if (Buffer.byteLength(payload, 'utf-8') < existingSize) {
+                payload = payload.padEnd(payload.length + (existingSize - Buffer.byteLength(payload, 'utf-8')), ' ');
+            }
+        }
+        catch { /* stat failed — write unpadded */ }
+        fs.writeFileSync(lockPath, payload, { encoding: 'utf-8', flag: 'r+' });
+    }
+    catch {
+        // A failed refresh is not fatal; contenders still respect pid liveness.
+    }
+}
+function startHeldLock(lockPath, token) {
+    const refreshTimer = setInterval(() => refreshLock(lockPath, token), LOCK_REFRESH_INTERVAL_MS);
+    refreshTimer.unref?.();
+    heldLocks.set(lockKey(lockPath), { count: 1, token, refreshTimer });
 }
 export function acquireLock(targetPath, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const lockPath = lockFilePath(targetPath);
-    const heldCount = heldLocks.get(lockPath);
-    if (heldCount) {
-        heldLocks.set(lockPath, heldCount + 1);
+    const held = heldLocks.get(lockKey(lockPath));
+    if (held) {
+        held.count += 1;
+        refreshLock(lockPath, held.token);
         return true;
     }
     const deadline = Date.now() + timeoutMs;
@@ -75,12 +200,12 @@ export function acquireLock(targetPath, timeoutMs = DEFAULT_TIMEOUT_MS) {
         fs.mkdirSync(dir, { recursive: true });
     }
     while (Date.now() < deadline) {
-        if (tryCreateLock(lockPath)) {
-            heldLocks.set(lockPath, 1);
+        const token = tryCreateLock(lockPath);
+        if (token) {
+            startHeldLock(lockPath, token);
             return true;
         }
         if (tryBreakLock(lockPath)) {
-            heldLocks.set(lockPath, 1);
             return true;
         }
         syncSleep(Math.min(LOCK_RETRY_INTERVAL_MS, deadline - Date.now()));
@@ -89,14 +214,16 @@ export function acquireLock(targetPath, timeoutMs = DEFAULT_TIMEOUT_MS) {
 }
 export function releaseLock(targetPath) {
     const lockPath = lockFilePath(targetPath);
-    const heldCount = heldLocks.get(lockPath);
-    if (heldCount && heldCount > 1) {
-        heldLocks.set(lockPath, heldCount - 1);
+    const held = heldLocks.get(lockKey(lockPath));
+    if (held && held.count > 1) {
+        held.count -= 1;
         return;
     }
-    heldLocks.delete(lockPath);
+    heldLocks.delete(lockKey(lockPath));
+    if (held?.refreshTimer)
+        clearInterval(held.refreshTimer);
     try {
-        if (fs.existsSync(lockPath)) {
+        if (lockIsOwnedByCurrentProcess(readLockData(lockPath), held?.token ?? '')) {
             fs.unlinkSync(lockPath);
         }
     }
@@ -130,13 +257,11 @@ export function cleanStaleLocks(dirPath) {
             continue;
         const lockPath = path.join(dirPath, entry);
         const data = readLockData(lockPath);
-        if (!data)
-            continue;
-        const expired = Date.now() - data.timestamp > LOCK_EXPIRY_MS;
-        const ownerDead = !isProcessAlive(data.pid);
-        if (expired || ownerDead) {
+        if (canBreakLock(lockPath, data)) {
+            const tombstone = `${lockPath}.clean.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
             try {
-                fs.unlinkSync(lockPath);
+                fs.renameSync(lockPath, tombstone);
+                fs.unlinkSync(tombstone);
                 removed++;
             }
             catch {

package/dist/core/loops/bootstrap-acquire.js

@@ -18,8 +18,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { acquireClaimScope, listClaims, releaseClaim } from '../claims.js';
+import { buildSurveySignalsBaseline } from './hooks/survey-signals-baseline.js';
 import { BOOTSTRAP_PRESET } from './presets/bootstrap.js';
 import { listLoops, openLoop } from './store.js';
+import { add_artifact } from './verbs.js';
 export class BootstrapCoordinationInProgressError extends Error {
     blockingClaimId;
     constructor(blockingClaimId) {
@@ -165,7 +167,7 @@ export function acquireBootstrapLoop(opts, cwd) {
     // Step 3 — open the loop, release the lock.
     const lockClaimId = acquireResult.claim.id;
     try {
-        const loop = openLoop({
+        let loop = openLoop({
             kind: 'ideation',
             title: opts.title ?? 'Bootstrap PROJECT.md',
             goal: opts.goal,
@@ -181,6 +183,28 @@ export function acquireBootstrapLoop(opts, cwd) {
             stop_condition: BOOTSTRAP_PRESET.stop_condition,
             protocol: BOOTSTRAP_PRESET.protocol,
         }, cwd);
+        // pln#557 step 4 — seed the survey phase with the deterministic-scanner
+        // baseline so survey quality is reproducible across champions instead of
+        // depending on per-agent re-discovery (TranslaVox miss, can_0160d6c4).
+        // Attached as `signals_baseline` (freeform body), NOT `signals_report`,
+        // so the survey advance-gate is not auto-traversed: the champion enriches
+        // the baseline into its own signals_report. Best-effort — a scanner
+        // failure must never block opening the loop.
+        try {
+            const baseline = buildSurveySignalsBaseline(cwd ?? process.cwd());
+            loop = add_artifact({
+                id: loop.id,
+                actor: opts.created_by ?? opts.agent_id ?? opts.actor,
+                artifact: {
+                    phase: 'survey',
+                    type: 'signals_baseline',
+                    body: JSON.stringify(baseline),
+                    produced_by: 'brainclaw-scanner',
+                },
+            }, cwd);
+            warnings.push('survey baseline attached (artifact type signals_baseline, produced by the deterministic scanner) — enrich it into your signals_report instead of re-scanning the repo from scratch.');
+        }
+        catch { /* best-effort */ }
         return { action: 'opened', loop, warnings };
     }
     finally {

package/dist/core/loops/facade-schema.js

@@ -58,6 +58,8 @@ export const BclawLoopTurnSchema = z.object({
     role: z.string().optional(),
     input: z.string().optional(),
     assignment_id: z.string().optional(),
+    /** pln#562 step 4 — claim binding the turn's slot to a dispatched instance. */
+    claim_id: z.string().optional(),
     dispatch: z.boolean().optional(),
     expected_version: z.number().int().nonnegative().optional(),
     ...CallerEnvelopeFields,