brainclaw 1.7.5 → 1.9.0

package/dist/core/dispatch-status.js

@@ -20,14 +20,44 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { loadAssignment, listAssignments } from './assignments.js';
+import { logger } from './logger.js';
 import { loadAgentRun, listAgentRuns } from './agentruns.js';
 import { loadClaim } from './claims.js';
 import { getLoop, listLoops } from './loops/store.js';
 import { isProcessAlive } from './agentrun-reconciler.js';
-import { latestActivityMs } from './runtime-signals.js';
+import { findRuntimeNoteById } from './runtime.js';
+import { latestActivityMs, decodeOemAwareBuffer } from './runtime-signals.js';
+import { LaneResultSchema } from './schema.js';
 const DEFAULT_TAIL = 20;
 const DEFAULT_STALL_MS = 5 * 60_000;
+const DEFAULT_BASE_REF = 'master';
+/**
+ * pln#554 — worktree git evidence, the signal that beats process/administrative
+ * status: a worker that committed everything to its lane branch has DELIVERED,
+ * whatever its pid/heartbeat/assignment.status say. Shared by dispatch-status
+ * and `brainclaw dispatch watch`. Returns undefined when there is no worktree
+ * or git could not be queried (never conclude "no commits" from a failed read).
+ */
+export function gitEvidence(worktreePath, baseRef) {
+    if (!worktreePath)
+        return undefined;
+    try {
+        const ahead = execFileSync('git', ['-C', worktreePath, 'rev-list', '--count', `${baseRef}..HEAD`], {
+            encoding: 'utf-8', timeout: 15000,
+        }).trim();
+        const status = execFileSync('git', ['-C', worktreePath, 'status', '--short'], {
+            encoding: 'utf-8', timeout: 15000,
+        });
+        const dirty = status.split('\n').filter((l) => l.trim() && !l.startsWith('??')).length;
+        return { commitsAhead: Number.parseInt(ahead, 10) || 0, dirtyTracked: dirty };
+    }
+    catch (err) {
+        logger.debug('dispatch status: git evidence unavailable:', err);
+        return undefined;
+    }
+}
 // ── Internal helpers ──────────────────────────────────────────────────────
 function readLogTail(filePath, lines) {
     try {
@@ -35,7 +65,9 @@ function readLogTail(filePath, lines) {
         if (lines <= 0) {
             return { path: filePath, exists: true, size_bytes: stat.size };
         }
-        const content = fs.readFileSync(filePath, 'utf-8');
+        // can_c39f0961: Windows-native tools write OEM cp850 — decode-aware read
+        // instead of blind utf-8 so the tail is human-readable.
+        const content = decodeOemAwareBuffer(fs.readFileSync(filePath));
         const all = content.split(/\r?\n/);
         // Strip trailing empty line from final \n
         if (all.length > 0 && all[all.length - 1] === '')
@@ -136,6 +168,36 @@ function computeDiagnosis(assignment, agentRun, runtime, options) {
             recommended_next_action: 'Verify the target_id is correct (asgn_/clm_/lop_/run_). Use bclaw_find(entity="assignment") to list available assignments.',
         };
     }
+    // pln#532 — RESULT is the #1 verdict signal. If the worker wrote LANE-RESULT.json
+    // it has FINISHED — regardless of pid / heartbeat / agent_run.status (a sandboxed
+    // worker frequently cannot self-update the run). This sits above every other
+    // signal, including the agent_run terminal/running checks below.
+    if (runtime.lane_result) {
+        const lr = runtime.lane_result;
+        const ok = lr.status === 'completed';
+        const stale = agentRun && agentRun.status !== 'completed'
+            ? ` (agent_run still ${agentRun.status}; the worker could not self-update — harvest reconciles it)`
+            : '';
+        return {
+            health: 'terminal',
+            summary: `worker reported done via LANE-RESULT.json: status=${lr.status} — ${lr.summary.slice(0, 140)}${stale}`,
+            recommended_next_action: ok
+                ? 'Worker finished. `brainclaw harvest <assignment_id>` to ingest the result, then commit/integrate its worktree diff and converge the lane.'
+                : `Worker reported "${lr.status}". Read the LANE-RESULT summary + stderr; address the blocker or reroute.`,
+        };
+    }
+    // pln#554 — git evidence is the #2 signal, ABOVE process sentinels and
+    // administrative status: commits ahead of base with a clean tracked tree
+    // means the worker delivered everything to the branch, even if its pid is
+    // dead, its heartbeat stale, or the run was relabeled interrupted by a TTL
+    // sweep (can_948acfd6). The verdict is "harvest it" — never "kill and reroute".
+    if ((runtime.commits_ahead ?? 0) > 0 && runtime.dirty_tracked === 0) {
+        return {
+            health: 'terminal',
+            summary: `worker delivered: ${runtime.commits_ahead} commit(s) ahead of base with a clean tracked tree — everything is on the lane branch${agentRun && !TERMINAL_RUN_STATUSES.has(agentRun.status) ? ` (agent_run still ${agentRun.status}; exit formalities missing — harvest reconciles it)` : ''}`,
+            recommended_next_action: 'Worker delivered; harvest it: `brainclaw harvest <assignment_id>` to ingest and merge the lane branch. Do NOT kill or reroute.',
+        };
+    }
     if (!agentRun) {
         return {
             health: 'not_dispatched',
@@ -215,7 +277,15 @@ export function getDispatchStatus(options) {
     const resolved = resolveTarget(options.target_id, cwd);
     const assignmentId = resolved.assignment_id;
     const assignment = assignmentId ? loadAssignment(assignmentId, cwd) : undefined;
-    const claim = assignment?.claim_id ? loadClaim(assignment.claim_id, cwd) : undefined;
+    // loadClaim THROWS on a missing id — a GC'd/never-created claim must not
+    // crash the whole diagnostic (sprint 1.5).
+    let claim;
+    if (assignment?.claim_id) {
+        try {
+            claim = loadClaim(assignment.claim_id, cwd);
+        }
+        catch { /* claim gone — diagnose without it */ }
+    }
     // Prefer the pre-resolved agent_run (when target_id was a run_…); otherwise
     // look up by assignment_id and pick the most recent attempt.
     let agentRun = resolved.agent_run;
@@ -241,13 +311,29 @@ export function getDispatchStatus(options) {
     // pln#527 — filesystem-activity age: max mtime across the captured logs + the
     // run's worktree files (skipping junctions). The truer liveness signal when
     // the heartbeat / last_event_at is stale during a long single operation.
-    const worktreeForFs = agentRun?.worktree_path ?? claim?.worktree_path;
+    // can_948acfd6: also fall back to assignment.worktree_path — without it a
+    // LANE-RESULT.json sitting in the assignment's worktree was invisible when
+    // neither the run nor the claim carried the path, and the verdict degraded
+    // to 'read stderr for failure detail' despite a completed lane result.
+    const worktreeForFs = agentRun?.worktree_path ?? claim?.worktree_path ?? assignment?.worktree_path;
     let lastFsActivityMs;
     if (assignmentId) {
         const lastFs = latestActivityMs(projectRoot, assignmentId, worktreeForFs);
         if (lastFs !== undefined)
             lastFsActivityMs = nowMs - lastFs;
     }
+    // pln#532 — the #1 verdict signal: a LANE-RESULT.json at the worktree root means
+    // the worker FINISHED (even if it couldn't self-update the run). Read + validate it.
+    let laneResult;
+    if (worktreeForFs) {
+        try {
+            const parsed = LaneResultSchema.parse(JSON.parse(fs.readFileSync(path.join(worktreeForFs, 'LANE-RESULT.json'), 'utf-8')));
+            laneResult = { status: parsed.status, summary: parsed.summary };
+        }
+        catch { /* no / invalid LANE-RESULT.json */ }
+    }
+    // pln#554 — worktree git evidence (commits ahead of base + dirty tracked files).
+    const evidence = gitEvidence(worktreeForFs, options.base_ref ?? DEFAULT_BASE_REF);
     const runtime = {
         pid: agentRun?.pid,
         pid_alive: isProcessAlive(agentRun?.pid),
@@ -260,8 +346,26 @@ export function getDispatchStatus(options) {
             stderr: stderrPath ? readLogTail(stderrPath, tailLines) : undefined,
         },
         last_fs_activity_ms: lastFsActivityMs,
+        lane_result: laneResult,
+        commits_ahead: evidence?.commitsAhead,
+        dirty_tracked: evidence?.dirtyTracked,
     };
-    const diagnosis = computeDiagnosis(assignment, agentRun, runtime, { stallMs, nowMs });
+    let diagnosis = computeDiagnosis(assignment, agentRun, runtime, { stallMs, nowMs });
+    // can_b8d53d18 — a `run_` target that resolves to nothing may be a LEGACY
+    // runtime_note id (pre-rtn_ prefix collision). Say so precisely instead of
+    // the generic "verify the target_id" message.
+    if (resolved.resolved_from === 'unresolved' && options.target_id.startsWith('run_')) {
+        try {
+            if (findRuntimeNoteById(options.target_id, {}, cwd)) {
+                diagnosis = {
+                    health: 'unknown',
+                    summary: `${options.target_id} is a runtime_note (legacy run_ id prefix), not an agent_run — nothing to dispatch-diagnose`,
+                    recommended_next_action: 'Read it with bclaw_get(entity="runtime_note"). Run `brainclaw repair` to migrate legacy run_ note ids to rtn_.',
+                };
+            }
+        }
+        catch { /* diagnosis stays generic */ }
+    }
     return {
         target_id: options.target_id,
         resolved_from: resolved.resolved_from,

package/dist/core/dispatcher.js

@@ -43,8 +43,8 @@ import { memoryDir } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import fs from 'node:fs';
 import path from 'node:path';
-import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile, dispatchHasMcp, resolveConcurrencyLimit, resolveResourceKey, resolveModel, serializeConcurrencyLimit } from './agent-capability.js';
-import { getRuntimeSignalPath } from './runtime-signals.js';
+import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile, dispatchHasMcp, dispatchCanCommit, isSandboxedSpawn, resolveConcurrencyLimit, resolveResourceKey, resolveModel, serializeConcurrencyLimit } from './agent-capability.js';
+import { getRuntimeSignalPath, getWorktreeHeartbeatPath } from './runtime-signals.js';
 import { attemptExecution } from './execution.js';
 import { createAssignment, transitionAssignment, generateAssignmentId, patchAssignmentMessageId } from './assignments.js';
 import { createAgentRun, transitionAgentRun } from './agentruns.js';
@@ -211,12 +211,28 @@ export function analyzeSequence(cwd) {
  * heartbeat. This is the worker-side half of the liveness contract whose
  * engine-side floor is the wrapper + reconciler (steps 4 + 1).
  */
-export function buildLivenessSection(cwd, assignmentId) {
-    const hbPath = getRuntimeSignalPath(cwd, assignmentId, 'heartbeat');
+export function buildLivenessSection(cwd, assignmentId, worktreePath, opts) {
+    // sprint 1.5 (dogfooding): the project-root signal path is NOT writable from
+    // inside worker sandboxes (Claude Code restricts writes to its working dirs;
+    // codex workspace-write roots exclude the project root) — the brief was
+    // demanding a heartbeat the worker could not write. When the worker has a
+    // worktree, point step 0 at a worktree-local heartbeat instead; every reader
+    // (reconciler, sweeper, dispatch_status fs-activity) checks both locations.
+    //
+    // pln#554 step 4 — sandbox-aware: codex workspace-write refuses even absolute
+    // paths in some configurations (cnd_asgn_7336aa79_heartbeat_sandbox /
+    // can_asgn_b0169fd8_heartbeat). When the execution adapter KNOWS the worker is
+    // sandboxed, point the write command at a worktree-RELATIVE path (the sandbox
+    // cwd is the worktree root) — same file, sandbox-proof spelling.
+    const sandboxRelative = opts?.sandboxed === true && !!worktreePath;
+    const hbPath = worktreePath
+        ? getWorktreeHeartbeatPath(worktreePath, assignmentId)
+        : getRuntimeSignalPath(cwd, assignmentId, 'heartbeat');
+    const targetPath = sandboxRelative ? `.brainclaw-heartbeat-${assignmentId}` : hbPath;
     const isWin = process.platform === 'win32';
     const writeCmd = isWin
-        ? `echo work_loop_reached ${assignmentId} > "${hbPath}"`
-        : `printf 'work_loop_reached ${assignmentId} %s' "$(date +%s)" > "${hbPath}"`;
+        ? `echo work_loop_reached ${assignmentId} > "${targetPath}"`
+        : `printf 'work_loop_reached ${assignmentId} %s' "$(date +%s)" > "${targetPath}"`;
     return [
         '## Liveness — DO THIS FIRST (step 0)',
         'Before ANY other action, prove you reached your work loop by writing a heartbeat,',
@@ -228,7 +244,28 @@ export function buildLivenessSection(cwd, assignmentId) {
         '```sh',
         writeCmd,
         '```',
-        `Heartbeat file (absolute, writable): ${hbPath}`,
+        sandboxRelative
+            ? `Heartbeat file (worktree-RELATIVE — run it from the worktree root, your sandbox cwd; sandboxes refuse the absolute coordination path): ${targetPath}`
+            : `Heartbeat file (absolute, writable from your sandbox): ${hbPath}`,
+        ...(worktreePath ? ['If that write is denied, use any file edit in your worktree as your liveness signal and continue — do NOT stall on the heartbeat.'] : []),
+        '',
+    ].join('\n');
+}
+/**
+ * pln#554 step 4 — working defaults baked into every generated brief, distilled
+ * from the 2026-06-10 session: (a) incremental commits so a worker death costs
+ * one step max (the orphaned recoveries that night lost zero work ONLY because
+ * the diff was still on disk); (b) a split validation bar so parallel workers
+ * don't pile full test suites onto a memory-pressured machine.
+ */
+export function buildWorkingDefaultsSection(opts) {
+    const commitRule = opts.canCommit
+        ? '- **Incremental commits**: commit after EACH completed step (conventional message). Never hold more than one step uncommitted — a worker death then costs at most one step, and the coordinator can harvest everything already on the branch.'
+        : '- **Incremental delivery**: your sandbox cannot `git commit` — finish steps in order and keep every file saved as you complete each step; the coordinator commits the worktree on your behalf at harvest. Never leave a step half-edited.';
+    return [
+        '## Working defaults',
+        commitRule,
+        '- **Validation bar**: run `tsc --noEmit` (or the project typecheck) + the targeted unit tests for the files you touched ONLY. Do NOT run the full default test suite — the coordinator runs the full gate after harvest (prevents test-suite pileups when several workers run in parallel).',
         '',
     ].join('\n');
 }
@@ -364,12 +401,18 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     if (plan.estimated_effort)
         parts.push(`Estimated effort: ${plan.estimated_effort} minutes`);
     parts.push('');
+    // Capability profile drives the sandbox-aware liveness path + the working
+    // defaults' commit rule (pln#554 step 4) and the transport addendum below.
+    const briefProfile = options?.agent ? getCapabilityProfile(options.agent) : undefined;
+    const briefSandboxed = briefProfile ? isSandboxedSpawn(briefProfile) : false;
     // pln#520 step 5 — liveness heartbeat instruction, first actionable block so
     // the worker writes work_loop_reached before anything else. Only when an
     // assignment id is known (the heartbeat is keyed by it).
     if (options?.assignmentId) {
-        parts.push(buildLivenessSection(cwd, options.assignmentId));
+        parts.push(buildLivenessSection(cwd, options.assignmentId, options.worktreePath, { sandboxed: briefSandboxed }));
     }
+    // pln#554 step 4 — working defaults (incremental commits + validation bar).
+    parts.push(buildWorkingDefaultsSection({ canCommit: briefProfile ? dispatchCanCommit(briefProfile) : true }));
     // Steps if any
     if (plan.steps?.length) {
         parts.push('## Steps');
@@ -435,7 +478,6 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     // so the reconciler-independent path is preserved; this addendum disambiguates
     // the transport rather than stripping the section — the full compact reversal
     // is a separate human-owned call on the May-vs-June MCP-availability conflict.)
-    const briefProfile = options?.agent ? getCapabilityProfile(options.agent) : undefined;
     if (briefProfile && !dispatchHasMcp(briefProfile)) {
         parts.push('## ⚠ Transport: sandboxed run (no MCP, no commit)');
         parts.push('Your runtime is sandboxed — the brainclaw MCP server is NOT reachable and `git commit` is unavailable (.git is outside the sandbox root). Any `bclaw_*` MCP instruction above does NOT apply to you. Report your outcome via the FILE protocol only — it is authoritative for this run:');
@@ -468,6 +510,15 @@ export function generateDispatchBrief(options) {
     if (options.worktreePath)
         parts.push(`Worktree: ${options.worktreePath}`);
     parts.push('');
+    const taskBriefProfile = options.agent ? getCapabilityProfile(options.agent) : undefined;
+    const taskSandboxed = taskBriefProfile ? isSandboxedSpawn(taskBriefProfile) : false;
+    // sprint 1.5 — task-based briefs get the same step-0 liveness contract as
+    // plan-based briefs (worktree-local heartbeat, writable from any sandbox).
+    if (options.assignmentId && options.worktreePath) {
+        parts.push(buildLivenessSection(options.worktreePath, options.assignmentId, options.worktreePath, { sandboxed: taskSandboxed }));
+    }
+    // pln#554 step 4 — working defaults (incremental commits + validation bar).
+    parts.push(buildWorkingDefaultsSection({ canCommit: taskBriefProfile ? dispatchCanCommit(taskBriefProfile) : true }));
     if (briefMode === 'full') {
         parts.push(buildProtocolSection({
             claimId: options.claimId,
@@ -476,7 +527,6 @@ export function generateDispatchBrief(options) {
         }));
     }
     // pln#528 — transport-aware addendum for sandboxed agents (see generateBrief).
-    const taskBriefProfile = options.agent ? getCapabilityProfile(options.agent) : undefined;
     if (taskBriefProfile && !dispatchHasMcp(taskBriefProfile)) {
         parts.push('## ⚠ Transport: sandboxed run (no MCP, no commit)');
         parts.push('Your runtime is sandboxed — the brainclaw MCP server is NOT reachable and `git commit` is unavailable (.git is outside the sandbox root). Any `bclaw_*` MCP instruction above does NOT apply to you. Report your outcome via the FILE protocol only — it is authoritative for this run:');
@@ -679,7 +729,7 @@ export async function dispatch(options, cwd) {
             const invokeCmd = buildInvokeCommand(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) });
             if (invokeCmd) {
                 const cmdPrefix = buildEnvPrefix(claimId);
-                result.commands.push({ agent: targetAgent, lane: readyItem.lane, command: `${cmdPrefix}${invokeCmd.bashCommand}`, shell: process.platform === 'win32' ? 'cmd' : (invokeCmd.shell ? 'bash' : 'sh') });
+                result.commands.push({ agent: targetAgent, lane: readyItem.lane, plan_id: readyItem.plan.id, command: `${cmdPrefix}${invokeCmd.bashCommand}`, shell: process.platform === 'win32' ? 'cmd' : (invokeCmd.shell ? 'bash' : 'sh') });
             }
             const deliveryEntry = { agent: targetAgent, plan_id: readyItem.plan.id, message_id: '(dry-run)', lane: readyItem.lane, channel: 'inbox', claim_id: claimId };
             result.delivery_plan.push(deliveryEntry);
@@ -738,6 +788,7 @@ export async function dispatch(options, cwd) {
             result.commands.push({
                 agent: targetAgent,
                 lane: readyItem.lane,
+                plan_id: readyItem.plan.id,
                 command: `${cmdPrefix}${invokeCmd.bashCommand}`,
                 shell: process.platform === 'win32' ? 'cmd' : (invokeCmd.shell ? 'bash' : 'sh'),
             });
@@ -850,6 +901,7 @@ export async function dispatch(options, cwd) {
                 dispatcherAgentId: options.dispatcherAgentId,
                 cwd,
                 handshakeTimeoutMs: options.handshakeTimeoutMs,
+                requireWorktree: true, // pln#531: never spawn a worker in the integration repo
             });
             entry.execution_status = execResult.execution_status;
             if (execResult.pid)
@@ -880,6 +932,7 @@ export async function dispatch(options, cwd) {
                             status_reason: 'CLI spawn launched by dispatcher',
                             tags: ['dispatch-run', ...(entry.lane ? [`lane:${entry.lane}`] : [])],
                         }, cwd);
+                        entry.run_id = run.id;
                         transitionAgentRun(run.id, 'failed', {
                             actor: options.dispatcherAgent,
                             actor_id: options.dispatcherAgentId,
@@ -927,6 +980,7 @@ export async function dispatch(options, cwd) {
                         status_reason: execResult.error,
                         tags: ['dispatch-run', ...(entry.lane ? [`lane:${entry.lane}`] : [])],
                     }, cwd);
+                    entry.run_id = run.id;
                     if (execResult.execution_status === 'delivered_and_started') {
                         transitionAgentRun(run.id, 'launching', {
                             actor: options.dispatcherAgent,

package/dist/core/entity-operations.js

@@ -12,14 +12,15 @@
  * until later slices wire them in.
  */
 import path from 'node:path';
-import { loadState, persistState } from './state.js';
+import { loadState, mutateState } from './state.js';
 import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from './candidates.js';
 import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
-import { listClaims } from './claims.js';
+import { listClaims, loadClaim, saveClaim } from './claims.js';
 import { listActionRequired } from './actions.js';
 import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, transitionAssignment } from './assignments.js';
 import { listAgentRuns } from './agentruns.js';
 import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
+import { isObserverMode } from './observer-mode.js';
 import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
 import { createSequence, deleteSequence, listSequences, updateSequence, } from './sequence.js';
 import { createConstraint, createDecision, createTrap, } from './operations/memory-write.js';
@@ -102,6 +103,12 @@ export class InvalidTransitionError extends Error {
  */
 function loadAgentRunsWithReconciliation(cwd) {
     const runs = listAgentRuns(cwd);
+    // Observer mode (BRAINCLAW_OBSERVER=1) suppresses the lazy reconciliation
+    // pass. A dashboard reading agent_run records must never transition them —
+    // that loop drove the 2026-06-10 lock storm (every poll could mutate every
+    // non-terminal run, holding the mutation lock under each transition).
+    if (isObserverMode())
+        return runs;
     for (const run of runs) {
         if (run.status === 'running') {
             try {
@@ -441,6 +448,20 @@ export function updateEntity(name, id, patch, cwd) {
             saveAssignment(patched, cwd);
             return { entity: name, id };
         }
+        case 'claim': {
+            // sprint 1.5 — description + worktree_path (manual-worktree registration).
+            // Status changes still go through bclaw_transition / release flows.
+            let claim;
+            try {
+                claim = loadClaim(id, cwd);
+            }
+            catch {
+                throw new EntityNotFoundError(name, id);
+            }
+            const patched = { ...claim, ...patch };
+            saveClaim(patched, cwd);
+            return { entity: name, id };
+        }
         case 'candidate': {
             // Note: `candidate.type` is intentionally create-only (not in
             // candidate.updatable at entity-registry.ts) — no validation needed.
@@ -561,8 +582,9 @@ export function transitionEntity(name, id, to, cwd, _reason) {
     if (!spec.statusField) {
         throw new Error(`${name} has no lifecycle (statusField is undefined)`);
     }
+    const statusField = spec.statusField;
     const current = getEntity(name, id, cwd);
-    const from = current[spec.statusField];
+    const from = current[statusField];
     if (!from) {
         throw new Error(`${name} '${id}' has no '${spec.statusField}' field set`);
     }
@@ -579,15 +601,15 @@ export function transitionEntity(name, id, to, cwd, _reason) {
         case 'decision':
         case 'constraint':
         case 'trap': {
-            const state = loadState(cwd);
-            const bucket = name === 'decision' ? state.recent_decisions
-                : name === 'constraint' ? state.active_constraints
-                    : state.known_traps;
-            const item = bucket.find((x) => x.id === id);
-            if (!item)
-                throw new EntityNotFoundError(name, id);
-            item[spec.statusField] = to;
-            persistState(state, cwd);
+            mutateState((state) => {
+                const bucket = name === 'decision' ? state.recent_decisions
+                    : name === 'constraint' ? state.active_constraints
+                        : state.known_traps;
+                const item = bucket.find((x) => x.id === id);
+                if (!item)
+                    throw new EntityNotFoundError(name, id);
+                item[statusField] = to;
+            }, cwd);
             return { entity: name, id, from, to, side_effects: sideEffects };
         }
         case 'candidate': {
@@ -618,20 +640,19 @@ export function transitionEntity(name, id, to, cwd, _reason) {
 // ─── Helpers ──────────────────────────────────────────────────────────
 /**
  * Stamp provenance on a state-resident record (plan, decision, constraint, trap)
- * immediately after create. Writes one extra persistState call; acceptable for
- * v1 since create is infrequent compared to reads.
+ * immediately after create.
  */
 function stampProvenanceOnStateItem(name, id, provenance, cwd) {
-    const state = loadState(cwd);
-    const bucket = name === 'plan' ? state.plan_items
-        : name === 'decision' ? state.recent_decisions
-            : name === 'constraint' ? state.active_constraints
-                : state.known_traps;
-    const item = bucket.find((x) => x.id === id);
-    if (!item)
-        return;
-    item.provenance = provenance;
-    persistState(state, cwd);
+    mutateState((state) => {
+        const bucket = name === 'plan' ? state.plan_items
+            : name === 'decision' ? state.recent_decisions
+                : name === 'constraint' ? state.active_constraints
+                    : state.known_traps;
+        const item = bucket.find((x) => x.id === id);
+        if (!item)
+            return;
+        item.provenance = provenance;
+    }, cwd);
 }
 function requireString(data, field) {
     const value = data[field];

package/dist/core/entity-registry.js

@@ -44,7 +44,7 @@ const step = {
     name: 'step',
     shortLabelPrefix: 'stp',
     schema: PlanStepSchema,
-    updatable: ['text', 'assignee'],
+    updatable: ['text', 'assignee', 'estimated_effort', 'actual_effort'],
     statusField: 'status',
     transitions: {
         todo: ['in_progress', 'blocked', 'done'],
@@ -63,7 +63,9 @@ const claim = {
     name: 'claim',
     shortLabelPrefix: 'clm',
     schema: ClaimSchema,
-    updatable: ['description'],
+    // worktree_path: sprint 1.5 — coordinators register manual worktrees (or fix
+    // stale paths) so harvest/dispatch_status can resolve LANE-RESULT locations.
+    updatable: ['description', 'worktree_path'],
     statusField: 'status',
     transitions: {
         active: ['released', 'stale'],
@@ -107,7 +109,16 @@ const decision = {
     name: 'decision',
     shortLabelPrefix: 'dec',
     schema: DecisionSchema,
-    updatable: ['text', 'tags', 'outcome', 'scope', 'related_paths'],
+    updatable: [
+        'text', 'tags', 'outcome', 'scope', 'related_paths', 'verified_at', 'verify_cmd',
+        // pln#544 lifecycle (touched via memory-lifecycle.ts recordMemoryEvent;
+        // exposing them here keeps bclaw_update straight-through for tests and
+        // operator backfills).
+        'last_confirmed_at', 'last_infirmed_at',
+        'confirmation_count', 'infirmation_count',
+        'saved_me_count', 'misled_me_count',
+        'confirmations',
+    ],
     statusField: 'outcome',
     transitions: {
         pending: ['approved', 'rejected', 'deferred'],
@@ -121,7 +132,14 @@ const constraint = {
     name: 'constraint',
     shortLabelPrefix: 'cst',
     schema: ConstraintSchema,
-    updatable: ['text', 'tags', 'category', 'scope', 'related_paths', 'expires_at'],
+    updatable: [
+        'text', 'tags', 'category', 'scope', 'related_paths', 'expires_at',
+        // pln#544 lifecycle — see decision.updatable.
+        'last_confirmed_at', 'last_infirmed_at',
+        'confirmation_count', 'infirmation_count',
+        'saved_me_count', 'misled_me_count',
+        'confirmations',
+    ],
     statusField: 'status',
     transitions: {
         active: ['resolved', 'expired'],
@@ -137,7 +155,15 @@ const trap = {
     name: 'trap',
     shortLabelPrefix: 'trp',
     schema: TrapSchema,
-    updatable: ['text', 'tags', 'severity', 'scope', 'related_paths', 'expires_at', 'platform_scope'],
+    updatable: [
+        'text', 'tags', 'severity', 'scope', 'related_paths', 'expires_at', 'platform_scope',
+        'verified_at', 'verify_cmd',
+        // pln#544 lifecycle — see decision.updatable.
+        'last_confirmed_at', 'last_infirmed_at',
+        'confirmation_count', 'infirmation_count',
+        'saved_me_count', 'misled_me_count',
+        'confirmations',
+    ],
     statusField: 'status',
     transitions: {
         active: ['resolved', 'expired'],