brainclaw 1.7.2 → 1.7.4

package/dist/core/agent-inventory.js

@@ -5,6 +5,14 @@ import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
 import { MEMORY_DIR } from './io.js';
 import { detectHostExecutionProfile, } from './execution-profile.js';
+import { getCapabilityProfile } from './agent-capability.js';
+/**
+ * trp#427 — cold-start CLI `--version` probes need headroom; a 3s timeout
+ * false-negatived claude-code on first launch. The spawnable check (binary on
+ * PATH) is the robust signal, so this only affects version-string capture
+ * latency, not the installed/spawnable decision.
+ */
+const VERSION_PROBE_TIMEOUT_MS = 8000;
 function tryCommand(command, args, timeout = 5000) {
     try {
         const r = spawnSync(command, args, { encoding: 'utf-8', timeout, windowsHide: true });
@@ -14,12 +22,40 @@ function tryCommand(command, args, timeout = 5000) {
         return { ok: false, stdout: '' };
     }
 }
+/**
+ * trp#427 — fast PATH resolution for a binary (no process launch, unlike a
+ * `--version` probe). Uses `where` (Windows) / `which` (POSIX).
+ */
+function isBinaryOnPath(binary) {
+    if (!binary)
+        return false;
+    try {
+        const cmd = process.platform === 'win32' ? 'where' : 'which';
+        const r = spawnSync(cmd, [binary], { encoding: 'utf-8', timeout: 3000, windowsHide: true });
+        return r.status === 0 && (r.stdout ?? '').trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * trp#427 — an agent is SPAWNABLE when its capability profile is CLI-spawnable,
+ * declares an invoke binary, and that binary resolves on PATH. Decoupled from
+ * the `--version` health probe so a slow cold-start CLI is never misreported as
+ * "not installed" / undispatchable.
+ */
+export function detectSpawnable(agentName) {
+    const profile = getCapabilityProfile(agentName);
+    if (!profile || !profile.runtime?.canBeSpawnedCli || !profile.invoke_binary)
+        return false;
+    return isBinaryOnPath(profile.invoke_binary);
+}
 const AGENT_DEFINITIONS = [
     {
         name: 'claude-code',
         detect: (_home, env) => {
             // Check if claude CLI is available
-            const cli = tryCommand('claude', ['--version'], 3000);
+            const cli = tryCommand('claude', ['--version'], VERSION_PROBE_TIMEOUT_MS);
             if (cli.ok) {
                 const ver = cli.stdout.trim().match(/(\d+\.\d+\.\d+)/)?.[1];
                 return { installed: true, method: 'claude CLI', version: ver };
@@ -81,7 +117,7 @@ const AGENT_DEFINITIONS = [
             if (fs.existsSync(codexDir)) {
                 return { installed: true, method: '~/.codex directory' };
             }
-            const cli = tryCommand('codex', ['--version'], 3000);
+            const cli = tryCommand('codex', ['--version'], VERSION_PROBE_TIMEOUT_MS);
             if (cli.ok) {
                 const ver = cli.stdout.trim().match(/(\d+\.\d+\.\d+)/)?.[1];
                 return { installed: true, method: 'codex CLI', version: ver };
@@ -252,7 +288,7 @@ const AGENT_DEFINITIONS = [
             if (fs.existsSync(path.join(home, '.gemini', 'antigravity'))) {
                 return { installed: true, method: '~/.gemini/antigravity directory' };
             }
-            const cli = tryCommand('gemini', ['--version'], 3000);
+            const cli = tryCommand('gemini', ['--version'], VERSION_PROBE_TIMEOUT_MS);
             if (cli.ok) {
                 return { installed: true, method: 'gemini CLI', version: cli.stdout.trim() };
             }
@@ -309,7 +345,7 @@ const AGENT_DEFINITIONS = [
             if (fs.existsSync(path.join(home, '.hermes'))) {
                 return { installed: true, method: '~/.hermes directory' };
             }
-            const cli = tryCommand('hermes', ['--version'], 3000);
+            const cli = tryCommand('hermes', ['--version'], VERSION_PROBE_TIMEOUT_MS);
             if (cli.ok) {
                 return { installed: true, method: 'hermes CLI', version: cli.stdout.trim() };
             }
@@ -332,14 +368,23 @@ const AGENT_DEFINITIONS = [
 /**
  * Detect ALL installed agents on this machine (not just the running one).
  */
-export function buildAgentInventory(homeDir = os.homedir(), env = process.env) {
+export function buildAgentInventory(homeDir = os.homedir(), env = process.env, opts = {}) {
+    const spawnableResolver = opts.spawnableResolver ?? detectSpawnable;
     const agents = AGENT_DEFINITIONS.map(def => {
         const detection = def.detect(homeDir, env);
+        const spawnable = spawnableResolver(def.name);
+        // trp#427: an agent brainclaw can spawn (invoke binary on PATH) IS installed,
+        // even when the cold-start `--version` probe timed out. This decouples the
+        // dispatch decision (getInstalledAgentNames) from probe latency.
+        const installed = detection.installed || spawnable;
         return {
             name: def.name,
-            installed: detection.installed,
-            detection_method: detection.method,
+            installed,
+            detection_method: detection.installed
+                ? detection.method
+                : (spawnable ? 'spawnable: invoke binary on PATH' : detection.method),
             version: detection.version,
+            spawnable,
             models: def.models,
             native_tools: def.native_tools,
             mcp_support: def.mcp_support,
@@ -415,6 +460,8 @@ export function renderAgentInventorySummary(inventory) {
             features.push('Rules');
         if (agent.hooks_support)
             features.push('Hooks');
+        if (agent.spawnable)
+            features.push('Spawnable');
         lines.push(`  Features: ${features.join(', ') || 'none'}`);
         if (agent.instruction_file) {
             lines.push(`  Instructions: ${agent.instruction_file}`);

package/dist/core/agentrun-reconciler.js

@@ -34,11 +34,11 @@
  */
 import { spawnSync } from 'node:child_process';
 import { loadAgentRun, transitionAgentRun, listAgentRuns } from './agentruns.js';
-import { loadClaim } from './claims.js';
+import { loadClaim, releaseClaim } from './claims.js';
 import { loadAssignment } from './assignments.js';
 import { createRuntimeEvent } from './events.js';
 import { nowISO } from './ids.js';
-import { readHeartbeat, readLogTail, signalExists } from './runtime-signals.js';
+import { readHeartbeat, readLogTail, signalExists, latestActivityMs } from './runtime-signals.js';
 // ── Constants ──────────────────────────────────────────────────────────────
 /**
  * Minimum age before a run is eligible for reconciliation. Below this, the
@@ -175,11 +175,59 @@ export function collectEvidence(run, cwd, options) {
             heartbeat_age_ms = now - hb.mtimeMs;
     }
     catch { /* defensive */ }
+    // pln#527 — filesystem-activity liveness (logs + worktree). Independent of the
+    // heartbeat: a worker can be actively editing files / streaming to stderr while
+    // its heartbeat is frozen (written once at step 0).
+    let fs_activity_age_ms;
+    try {
+        const lastFs = latestActivityMs(signalRoot, run.assignment_id, run.worktree_path);
+        if (lastFs !== undefined)
+            fs_activity_age_ms = now - lastFs;
+    }
+    catch { /* defensive */ }
     return {
         age_ms, has_post_start_commit, claim_released, assignment_completed, process_alive,
-        completed_signal, failed_signal, heartbeat_exists, heartbeat_age_ms,
+        completed_signal, failed_signal, heartbeat_exists, heartbeat_age_ms, fs_activity_age_ms,
     };
 }
+/**
+ * pln#527 — true when the run shows filesystem activity within `windowMs`
+ * (logs growing / worktree files touched). Used to VETO a `stalled` verdict: a
+ * stale heartbeat with fresh fs activity means "working", not "hung".
+ */
+function fsActiveWithin(evidence, windowMs) {
+    return evidence.fs_activity_age_ms !== undefined && evidence.fs_activity_age_ms < windowMs;
+}
+/**
+ * trp#433 — when a run is reconciled to `failed` (silent_death / stalled), release
+ * its linked claim so dead runs stop leaving active claims (and their worktrees)
+ * accumulating for manual cleanup. Best-effort + idempotent: only an active claim
+ * is released, and any error is swallowed (GC must never break reconciliation).
+ * Inference only fires after the stale window with no life evidence, so this is
+ * conservative. (Loop auto-close on failure is a follow-up.)
+ */
+function cascadeReleaseOnFailure(run, actor, cwd) {
+    if (!run.claim_id)
+        return;
+    try {
+        const claim = loadClaim(run.claim_id, cwd);
+        if (claim && claim.status === 'active') {
+            releaseClaim(run.claim_id, cwd);
+            createRuntimeEvent({
+                agent: actor,
+                session_id: run.session_id,
+                event_type: 'run_failed',
+                text: `Auto-released claim ${run.claim_id} after run ${run.id} was reconciled to failed (trp#433 GC cascade)`,
+                tags: ['reconciler', 'gc', 'claim-release'],
+                assignment_id: run.assignment_id,
+                run_id: run.id,
+                claim_id: run.claim_id,
+                status_reason: 'gc_cascade_release_on_failure',
+            }, cwd);
+        }
+    }
+    catch { /* best-effort — never let GC break reconciliation */ }
+}
 function anyCompletionEvidence(evidence) {
     return evidence.completed_signal
         || evidence.has_post_start_commit
@@ -328,6 +376,7 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
     const failHere = (reason) => {
         try {
             transitionAgentRun(runId, 'failed', { actor, status_reason: reason }, cwd);
+            cascadeReleaseOnFailure(run, actor, cwd);
             return { run_id: runId, action: 'inferred_failed', reason, evidence, previous_status, current_status: 'failed' };
         }
         catch (err) {
@@ -342,9 +391,18 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
     if (evidence.failed_signal) {
         return failHere(`failed_silent: wrapper reported non-zero exit${logTailSuffix(run, cwd)}`);
     }
-    // Heartbeat present but stale → reached the loop then went silent.
+    // Heartbeat present but stale → reached the loop then went silent — UNLESS the
+    // filesystem shows recent activity (pln#527): a frozen heartbeat with fresh
+    // log/worktree writes means the worker is mid-operation, not hung.
     if (evidence.heartbeat_exists && evidence.heartbeat_age_ms !== undefined && evidence.heartbeat_age_ms >= heartbeatStale) {
-        return failHere(`stalled: heartbeat last seen ${Math.round(evidence.heartbeat_age_ms / 1000)}s ago${logTailSuffix(run, cwd)}`);
+        if (fsActiveWithin(evidence, heartbeatStale)) {
+            return {
+                run_id: runId, action: 'no_op',
+                reason: `heartbeat stale (${Math.round(evidence.heartbeat_age_ms / 1000)}s) but fs active ${Math.round((evidence.fs_activity_age_ms ?? 0) / 1000)}s ago — working, not stalled`,
+                evidence, previous_status, current_status: run.status,
+            };
+        }
+        return failHere(`stalled: heartbeat last seen ${Math.round(evidence.heartbeat_age_ms / 1000)}s ago, no fs activity${logTailSuffix(run, cwd)}`);
     }
     // Fresh heartbeat → alive; trust it over the untrustworthy wrapper pid.
     if (evidence.heartbeat_exists) {
@@ -416,6 +474,7 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
     const failRun = (reason) => {
         try {
             transitionAgentRun(run.id, 'failed', { actor, status_reason: reason }, cwd);
+            cascadeReleaseOnFailure(run, actor, cwd);
             return { run_id: run.id, action: 'inferred_failed', reason, evidence, previous_status: run.status, current_status: 'failed' };
         }
         catch (err) {
@@ -458,7 +517,14 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
     // 3. Heartbeat present but STALE → the worker reached its loop then went
     // silent (e.g. hung). pid-independent: a hung worker keeps the wrapper alive.
     if (evidence.heartbeat_exists && evidence.heartbeat_age_ms !== undefined && evidence.heartbeat_age_ms >= heartbeatStale) {
-        return failRun(`stalled: heartbeat last seen ${Math.round(evidence.heartbeat_age_ms / 1000)}s ago${logTailSuffix(run, cwd)}`);
+        if (fsActiveWithin(evidence, heartbeatStale)) {
+            return {
+                run_id: run.id, action: 'no_op',
+                reason: `heartbeat stale (${Math.round(evidence.heartbeat_age_ms / 1000)}s) but fs active ${Math.round((evidence.fs_activity_age_ms ?? 0) / 1000)}s ago — working, not stalled`,
+                evidence, previous_status: run.status, current_status: run.status,
+            };
+        }
+        return failRun(`stalled: heartbeat last seen ${Math.round(evidence.heartbeat_age_ms / 1000)}s ago, no fs activity${logTailSuffix(run, cwd)}`);
     }
     // 4. Fresh heartbeat → the worker is alive and working; trust it OVER the
     // (untrustworthy) wrapper pid. This is the can_f792cacd fix: never fail a

package/dist/core/dirty-scope.js

@@ -44,13 +44,19 @@ function defaultRunGit(cwd, args) {
         return { ok: false, stdout: '' };
     }
 }
-/** True for coordination/store paths that are dirty as a side effect of dispatching. */
+/**
+ * Top-level directories that are dirty as a side effect of coordination /
+ * agent tooling, never part of a dispatch's code scope:
+ *   - `.brainclaw`, `.git` — coordination store + VCS metadata.
+ *   - `.claude`, `.cursor`, `.codex` — per-agent local config (trp#371). A
+ *     worker leaving these dirty (Claude Code settings, etc.) must not block an
+ *     otherwise-safe dispatch of an unrelated code scope.
+ */
+const SYSTEM_DIRTY_DIRS = ['.brainclaw', '.git', '.claude', '.cursor', '.codex'];
+/** True for coordination/store/agent-config paths that are dirty as a side effect of tooling. */
 export function isSystemDirtyPath(p) {
     const norm = p.replace(/\\/g, '/');
-    return norm === '.brainclaw'
-        || norm.startsWith('.brainclaw/')
-        || norm === '.git'
-        || norm.startsWith('.git/');
+    return SYSTEM_DIRTY_DIRS.some((dir) => norm === dir || norm.startsWith(dir + '/'));
 }
 /**
  * Parse `git status --porcelain=v1 -z` output into a flat list of paths.

package/dist/core/dispatch-status.js

@@ -25,6 +25,7 @@ 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';
 const DEFAULT_TAIL = 20;
 const DEFAULT_STALL_MS = 5 * 60_000;
 // ── Internal helpers ──────────────────────────────────────────────────────
@@ -96,6 +97,37 @@ function resolveTarget(targetId, cwd) {
 const TERMINAL_RUN_STATUSES = new Set([
     'completed', 'failed', 'cancelled', 'timed_out', 'interrupted',
 ]);
+/**
+ * pln#527 (#5) — recognize known fatal boot signatures in a worker's stderr tail
+ * so dispatch_status returns a targeted diagnosis + remediation instead of a
+ * generic silent_death. These are agent/CLI/config faults (NOT brainclaw bugs)
+ * that a coordinator can fix and re-dispatch. Patterns sourced from field traps
+ * (trp#292 codex service_tier / model mismatch).
+ */
+export function recognizeStderrSignature(tail) {
+    if (!tail || tail.length === 0)
+        return undefined;
+    const text = tail.join('\n');
+    if (/service_tier/i.test(text) && /flex|unsupported/i.test(text)) {
+        return {
+            summary: 'codex rejected an unsupported `service_tier` (e.g. flex) — a config/model mismatch at boot, not a brainclaw fault',
+            recommended_next_action: 'Fix ~/.codex/config.toml `service_tier` (remove it or set a supported value) or upgrade codex, then re-dispatch. See trap trp#292.',
+        };
+    }
+    if (/unknown variant/i.test(text)) {
+        return {
+            summary: 'codex CLI rejected an unknown config variant — the installed codex does not support a value in ~/.codex/config.toml (e.g. model/approval)',
+            recommended_next_action: 'Reconcile ~/.codex/config.toml with the installed codex (`codex --version`) or upgrade codex, then re-dispatch.',
+        };
+    }
+    if (/\b400\b/.test(text) && /(unsupported|requires a newer|model)/i.test(text)) {
+        return {
+            summary: 'the model API returned 400 (unsupported model / needs a newer CLI) — the worker died at boot, before doing work',
+            recommended_next_action: 'Check the configured model vs the installed CLI version; upgrade the agent CLI or pick a supported model, then re-dispatch.',
+        };
+    }
+    return undefined;
+}
 function computeDiagnosis(assignment, agentRun, runtime, options) {
     if (!assignment && !agentRun) {
         return {
@@ -127,17 +159,37 @@ function computeDiagnosis(assignment, agentRun, runtime, options) {
     const lastEventMs = new Date(agentRun.last_event_at ?? agentRun.started_at ?? agentRun.created_at).getTime();
     const stallAge = options.nowMs - lastEventMs;
     if (runtime.pid_alive === false) {
+        // pln#527 (#5) — surface a TARGETED diagnosis when the captured stderr matches
+        // a known fatal boot signature (codex model/service_tier mismatch, API 400)
+        // instead of a generic "silent_death".
+        const sig = recognizeStderrSignature(runtime.log_files.stderr?.tail);
         return {
             health: 'silent_death',
-            summary: `agent_run.status="${agentRun.status}" but pid ${runtime.pid} is dead — worker exited without self-reporting; lazy reconciler will mark it failed after the stale window (default 30min)`,
-            recommended_next_action: 'Read .stderr.log for the exit reason; then trigger reconciliation by calling bclaw_find(entity="agent_run") again, or cancel + reroute.',
+            summary: sig
+                ? `agent_run.status="${agentRun.status}", pid ${runtime.pid} dead — ${sig.summary}`
+                : `agent_run.status="${agentRun.status}" but pid ${runtime.pid} is dead — worker exited without self-reporting; lazy reconciler will mark it failed after the stale window (default 30min)`,
+            recommended_next_action: sig?.recommended_next_action
+                ?? 'Read .stderr.log for the exit reason; then trigger reconciliation by calling bclaw_find(entity="agent_run") again, or cancel + reroute.',
+        };
+    }
+    // pln#527 — a stale last_event_at is NOT "stalled" when the filesystem is still
+    // active (logs streaming / worktree files edited). Workers emit no heartbeat
+    // during a long single operation (codex→stderr, claude -p buffering stdout),
+    // so fs activity is the truer liveness signal and vetoes the false-stalled.
+    const fsAge = runtime.last_fs_activity_ms;
+    const fsActive = fsAge !== undefined && fsAge < options.stallMs;
+    if (runtime.pid_alive === true && stallAge > options.stallMs && fsActive) {
+        return {
+            health: 'healthy',
+            summary: `agent_run alive (pid=${runtime.pid}); last_event_at stale (${Math.round(stallAge / 1000)}s) but filesystem active ${Math.round((fsAge ?? 0) / 1000)}s ago — working through a long op without a heartbeat`,
+            recommended_next_action: 'No action — the worker is actively writing to logs/worktree. Re-check periodically until terminal.',
         };
     }
     if (runtime.pid_alive === true && stallAge > options.stallMs) {
         return {
             health: 'stalled',
-            summary: `agent_run alive (pid=${runtime.pid}) but no activity for ${Math.round(stallAge / 1000)}s; last_event_at=${agentRun.last_event_at ?? '(never)'}`,
-            recommended_next_action: 'Tail the stdout/stderr log to see whether the worker is doing useful work; if truly hung, kill the pid and reroute.',
+            summary: `agent_run alive (pid=${runtime.pid}) but no activity for ${Math.round(stallAge / 1000)}s AND no filesystem writes${fsAge !== undefined ? ` (last fs ${Math.round(fsAge / 1000)}s ago)` : ' (no logs/worktree mtime)'}; last_event_at=${agentRun.last_event_at ?? '(never)'}`,
+            recommended_next_action: 'Worker appears genuinely hung (no log/file writes). Tail stderr to confirm, then kill the pid and reroute.',
         };
     }
     if (runtime.pid_alive === true) {
@@ -186,6 +238,16 @@ export function getDispatchStatus(options) {
     const ackPath = assignmentId ? path.join(runtimeRoot, 'ack', `${assignmentId}.ack`) : undefined;
     const stdoutPath = assignmentId ? path.join(runtimeRoot, 'log', `${assignmentId}.stdout.log`) : undefined;
     const stderrPath = assignmentId ? path.join(runtimeRoot, 'log', `${assignmentId}.stderr.log`) : undefined;
+    // 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;
+    let lastFsActivityMs;
+    if (assignmentId) {
+        const lastFs = latestActivityMs(projectRoot, assignmentId, worktreeForFs);
+        if (lastFs !== undefined)
+            lastFsActivityMs = nowMs - lastFs;
+    }
     const runtime = {
         pid: agentRun?.pid,
         pid_alive: isProcessAlive(agentRun?.pid),
@@ -197,6 +259,7 @@ export function getDispatchStatus(options) {
             stdout: stdoutPath ? readLogTail(stdoutPath, tailLines) : undefined,
             stderr: stderrPath ? readLogTail(stderrPath, tailLines) : undefined,
         },
+        last_fs_activity_ms: lastFsActivityMs,
     };
     const diagnosis = computeDiagnosis(assignment, agentRun, runtime, { stallMs, nowMs });
     return {

package/dist/core/dispatcher.js

@@ -43,7 +43,7 @@ import { memoryDir } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import fs from 'node:fs';
 import path from 'node:path';
-import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile, resolveConcurrencyLimit, resolveResourceKey, resolveModel, serializeConcurrencyLimit } from './agent-capability.js';
+import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile, dispatchHasMcp, resolveConcurrencyLimit, resolveResourceKey, resolveModel, serializeConcurrencyLimit } from './agent-capability.js';
 import { getRuntimeSignalPath } from './runtime-signals.js';
 import { attemptExecution } from './execution.js';
 import { createAssignment, transitionAssignment, generateAssignmentId, patchAssignmentMessageId } from './assignments.js';
@@ -156,6 +156,11 @@ export function analyzeSequence(cwd) {
             plan,
             lane: item.lane,
             reason: `All hard dependencies met${softNote}`,
+            // pln#529 — readiness ≠ code-availability for gated lanes.
+            ...(item.hard_after.length > 0 ? {
+                code_propagation_note: `Unblocked by hard_after [${item.hard_after.join(', ')}]. Ensure that work is committed AND on the dispatch base (HEAD), ` +
+                    `or dispatch this lane with ref=<predecessor branch> — otherwise the worker spawns from HEAD without it.`,
+            } : {}),
         });
     }
     // Build capacity summary per agent (multi-instance aware)
@@ -238,6 +243,13 @@ export function buildProtocolSection(options) {
     }
     if (options?.worktreePath) {
         parts.push(`Worktree: ${options.worktreePath}`);
+        // pln#523: tell the worker how dependencies are provisioned so it does not
+        // stall trying to install them. node_modules (and per-package node_modules in
+        // monorepos) are junction-linked from the main repo — run builds/typecheck
+        // directly. If they are missing, do NOT `npm install` in the worktree: check
+        // `.brainclaw-worktree.json` → `symlink_warnings` (a link may have failed,
+        // e.g. cross-volume) and validate the build centrally with the coordinator.
+        parts.push('Dependencies: node_modules is linked from the main repo (incl. monorepo per-package). Build/typecheck directly; if deps are missing, do NOT npm install here — see .brainclaw-worktree.json symlink_warnings and validate centrally.');
     }
     parts.push('');
     // Assignment lifecycle protocol (Agent SDK)
@@ -254,6 +266,14 @@ export function buildProtocolSection(options) {
         parts.push(`${options.worktreePath ? '7' : '6'}. Release the claim: bclaw_release_claim(${claimRef}, planStatus: "done") — required for hard_after gating to unblock downstream tasks`);
         parts.push(`${options.worktreePath ? '8' : '7'}. If blocked: bclaw_assignment_update(status: "blocked", blocker: "...")`);
         parts.push(`${options.worktreePath ? '9' : '8'}. If failed: bclaw_assignment_update(status: "failed", error_message: "...")`);
+        // pln#479: compile-check contract for code workers — a per-worktree
+        // pre-commit gate may HARD-block a commit that fails tsc (opt-in).
+        if (options.worktreePath) {
+            parts.push('**Compile check**: before every commit, `tsc --noEmit` (or the project build) must pass — a per-worktree pre-commit gate may enforce this and reject the commit otherwise. Do not bypass with --no-verify unless you intend to hand off a known-broken state.');
+        }
+        // pln#526: standard fallback channel — works even when MCP is unreachable
+        // (sandboxed agents). The coordinator ingests it with `brainclaw harvest`.
+        parts.push(`Final fallback (if bclaw_assignment_update / MCP is unavailable, e.g. a sandboxed agent): write LANE-RESULT.json at the worktree root — {"assignment_id":"${options.assignmentId}","status":"completed|blocked|failed","summary":"<what you did>","files_changed":["..."],"artifacts":["..."]}. The coordinator harvests it via \`brainclaw harvest ${options.assignmentId}\`.`);
     }
     else if (options?.claimId) {
         parts.push('1. Call bclaw_session_start to register your session');
@@ -406,6 +426,25 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     if (mode === 'full') {
         parts.push(buildProtocolSection(options));
     }
+    // pln#528 — transport-aware addendum (debrief LeaseUp P1#2). When the agent is
+    // spawned sandboxed (no MCP + no git commit — e.g. codex --sandbox
+    // workspace-write), the MCP lifecycle lines in the Protocol section do NOT
+    // apply. Say so explicitly and make the FILE protocol authoritative, so the
+    // worker never receives instructions it cannot follow nor has to guess the
+    // fallback. (Note: resolveBriefMode still returns 'full' for codex per pln#496
+    // 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:');
+        const asgn = options?.assignmentId ?? '<assignment_id>';
+        parts.push(`- When done, write LANE-RESULT.json at the worktree root: {"assignment_id":"${asgn}","status":"completed|blocked|failed","summary":"<what you did>","files_changed":["..."]}.`);
+        parts.push('- Capture decisions/traps as candidate JSON under .brainclaw/coordination/inbox/ (the coordinator harvests them).');
+        parts.push('- Do NOT call bclaw_* tools — they are unavailable here. The coordinator harvests your result and integrates/commits it.');
+        parts.push('');
+    }
     // Codex-specific constraints: focus and speed guidance for sandboxed runs.
     // Gated on agent identity (not brief mode) so future non-codex compact consumers
     // don't inherit sandbox-specific wording. (Codex review cnd#561)
@@ -413,7 +452,6 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
         parts.push('## Constraints');
         parts.push('- Focus on specified files only — do not explore the broader codebase');
         parts.push('- Produce output quickly; if blocked, capture as trap candidate and move on');
-        parts.push('- Sandbox blocks MCP writes: use filesystem writes for candidates, coordinator harvests');
         parts.push('');
     }
     return parts.join('\n');
@@ -437,12 +475,22 @@ export function generateDispatchBrief(options) {
             assignmentId: options.assignmentId,
         }));
     }
+    // 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:');
+        const asgn = options.assignmentId ?? '<assignment_id>';
+        parts.push(`- When done, write LANE-RESULT.json at the worktree root: {"assignment_id":"${asgn}","status":"completed|blocked|failed","summary":"<what you did>","files_changed":["..."]}.`);
+        parts.push('- Capture decisions/traps as candidate JSON under .brainclaw/coordination/inbox/ (the coordinator harvests them).');
+        parts.push('- Do NOT call bclaw_* tools — they are unavailable here. The coordinator harvests your result and integrates/commits it.');
+        parts.push('');
+    }
     // Codex-specific constraints: focus and speed guidance for sandboxed runs
     if (options.agent === 'codex') {
         parts.push('## Constraints');
         parts.push('- Focus on specified files only — do not explore the broader codebase');
         parts.push('- Produce output quickly; if blocked, capture as trap candidate and move on');
-        parts.push('- Sandbox blocks MCP writes: use filesystem writes for candidates, coordinator harvests');
         parts.push('');
     }
     return parts.join('\n');

package/dist/core/entity-operations.js

@@ -126,6 +126,42 @@ export function listEntities(name, cwd, filter = {}) {
     const paged = applyPaging(filtered, filter);
     return { entity: name, total: filtered.length, items: paged };
 }
+/** Default serialized-items budget (chars) — keeps a bclaw_find payload well under the ~25k-token MCP cap (trp#449). */
+export const DEFAULT_FIND_CHAR_BUDGET = 40000;
+/**
+ * pln#491 — bound a list payload so a verbose result set never overflows the MCP
+ * token cap (which makes agents silently fall back to the CLI, trp#449).
+ * `listEntities` already caps COUNT (default 50 via applyPaging); this additionally
+ * caps SIZE: if the serialized items exceed `charBudget`, the page is shrunk until
+ * it fits (always keeping at least one item). Either way the result advertises
+ * has_more / next_offset / a hint so the caller paginates explicitly instead of
+ * guessing or falling back to the terminal.
+ */
+export function boundListResult(result, offset, charBudget = DEFAULT_FIND_CHAR_BUDGET) {
+    let items = result.items;
+    let omittedForSize = 0;
+    while (items.length > 1 && JSON.stringify(items).length > charBudget) {
+        const drop = Math.max(1, Math.ceil(items.length * 0.25));
+        items = items.slice(0, items.length - drop);
+        omittedForSize = result.items.length - items.length;
+    }
+    const returned = items.length;
+    const hasMore = offset + returned < result.total;
+    const bounded = {
+        ...result,
+        items,
+        returned,
+        has_more: hasMore,
+        ...(omittedForSize > 0 ? { omitted_for_size: omittedForSize } : {}),
+    };
+    if (hasMore) {
+        bounded.next_offset = offset + returned;
+        bounded.hint = omittedForSize > 0
+            ? `Payload size-bounded: returned ${returned} of ${result.total} ${result.entity} item(s). Fetch more with filter.offset=${bounded.next_offset}, or narrow the filter (status/tag/author).`
+            : `Returned ${returned} of ${result.total} ${result.entity} item(s). Page with filter.offset=${bounded.next_offset}, or narrow the filter.`;
+    }
+    return bounded;
+}
 function loadAll(name, cwd) {
     switch (name) {
         case 'plan': return loadState(cwd).plan_items;

package/dist/core/entity-registry.js

@@ -23,7 +23,7 @@ const plan = {
     name: 'plan',
     shortLabelPrefix: 'pln',
     schema: PlanItemSchema,
-    updatable: ['text', 'priority', 'tags', 'assignee', 'estimated_effort', 'actual_effort', 'depends_on'],
+    updatable: ['text', 'priority', 'tags', 'assignee', 'estimated_effort', 'actual_effort', 'depends_on', 'related_paths'],
     statusField: 'status',
     transitions: {
         todo: ['in_progress', 'blocked', 'done', 'dropped'],

package/dist/core/instruction-templates.js

@@ -237,7 +237,7 @@ function renderSessionProtocol() {
         '',
         '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. Always (1) `bclaw_find(entity="agent_run", filter={assignment_id})` to read the spawn record; (2) check OS pid liveness yourself (`Get-Process -Id <pid>` on Windows, `kill -0 <pid>` on POSIX); (3) if the worker is silent, read its captured streams at `.brainclaw/coordination/runtime/log/<assignment_id>.{stdout,stderr}.log`. Full FSM tables + diagnostic decision tree in `docs/concepts/dispatch-lifecycle.md`.',
+        '_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`.',
     ].join('\n');
 }
 function renderUserWorkflow() {

package/dist/core/runtime-signals.js

@@ -99,4 +99,76 @@ export function readLogTail(root, assignmentId, stream, maxBytes = 2000) {
         return '';
     }
 }
+/**
+ * pln#527 — directories never worth walking for filesystem-activity (junction
+ * targets / VCS / coordination store). Skipping them keeps the worktree mtime
+ * scan cheap AND avoids following node_modules/dist junctions into the main repo.
+ */
+const FS_ACTIVITY_SKIP_DIRS = new Set(['.git', '.brainclaw', 'node_modules', 'dist', '.venv', 'venv', 'vendor']);
+/**
+ * pln#527 — most-recent file mtime (ms) under a worktree, via a bounded walk that
+ * NEVER follows symlinks/junctions (lstat) and skips dependency/VCS dirs. This is
+ * the liveness signal for workers that edit files but emit no heartbeat/stdout
+ * (e.g. `claude -p` buffers stdout; a long single edit pass refreshes no
+ * sentinel). Returns undefined when the path is absent/unreadable.
+ */
+export function latestWorktreeFileMtimeMs(worktreePath, maxDepth = 4) {
+    let latest;
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue; // never follow junctions (node_modules/dist)
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (FS_ACTIVITY_SKIP_DIRS.has(entry.name))
+                    continue;
+                walk(full, depth + 1);
+            }
+            else if (entry.isFile()) {
+                try {
+                    const m = fs.statSync(full).mtimeMs;
+                    if (latest === undefined || m > latest)
+                        latest = m;
+                }
+                catch { /* ignore */ }
+            }
+        }
+    };
+    walk(worktreePath, 0);
+    return latest;
+}
+/**
+ * pln#527 — the most recent filesystem activity (ms since epoch) attributable to
+ * a dispatched run: the max mtime across its captured stdout/stderr logs AND any
+ * file in its worktree. Lets the reconciler / dispatch_status distinguish
+ * "no heartbeat BUT fs active" (working — e.g. codex streaming to stderr, or
+ * claude -p editing files) from "no heartbeat AND fs inert" (genuinely stalled),
+ * fixing the false-`stalled` verdict (debrief LeaseUp P1#1). Returns undefined
+ * when nothing is observable.
+ */
+export function latestActivityMs(root, assignmentId, worktreePath) {
+    let latest;
+    const bump = (ms) => {
+        if (ms !== undefined && (latest === undefined || ms > latest))
+            latest = ms;
+    };
+    for (const stream of ['stdout', 'stderr']) {
+        try {
+            bump(fs.statSync(getRuntimeLogPath(root, assignmentId, stream)).mtimeMs);
+        }
+        catch { /* no log */ }
+    }
+    if (worktreePath)
+        bump(latestWorktreeFileMtimeMs(worktreePath));
+    return latest;
+}
 //# sourceMappingURL=runtime-signals.js.map