brainclaw 1.7.3 → 1.7.4

package/README.md

@@ -345,6 +345,22 @@ npm run test:coverage      # with coverage report
 
 For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
+### v1.7.4
+
+- **Dispatch observability + worker DX hardening** (from a real cross-project
+  field session) — `bclaw_dispatch_status` and the reconciler now derive liveness
+  from filesystem activity (log + worktree mtime), so a worker actively editing
+  files is no longer falsely flagged `stalled`, and known codex boot-failure
+  stderr signatures get a targeted diagnosis; briefs are transport-aware (a
+  sandboxed agent without MCP/commit gets the file protocol, not instructions it
+  can't follow), backed by a derived capability matrix
+  (`dispatchHasMcp`/`dispatchCanCommit`); `bclaw_claim` gains an advisory
+  (no-worktree) mode; `bclaw_find` payloads are size-bounded with pagination
+  metadata; an opt-in per-worktree `tsc --noEmit` pre-commit gate; gated ready
+  lanes carry a code-propagation advisory; the reconciler auto-releases the claim
+  of a run it infers failed; and `plan.related_paths` is now updatable.
+  (pln#479, pln#491, pln#527, pln#528, pln#529, trp#291, trp#431, trp#433, trp#434)
+
 ### v1.7.3
 
 - **Multi-agent dispatch hardening for JS/TS monorepos** — dispatched worktrees

package/dist/commands/mcp.js

@@ -16,7 +16,7 @@ import { collectLoadValidationWarnings, findLoadValidationWarning, loadState, pe
 import { generateIdWithLabel } from '../core/ids.js';
 import { memoryExists } from '../core/io.js';
 import { generateCandidateIdWithLabel, loadCandidate, saveCandidate } from '../core/candidates.js';
-import { createEntity, getEntity, listEntities, removeEntity, transitionEntity, updateEntity, } from '../core/entity-operations.js';
+import { createEntity, getEntity, listEntities, boundListResult, removeEntity, transitionEntity, updateEntity, } from '../core/entity-operations.js';
 import { ENTITY_REGISTRY } from '../core/entity-registry.js';
 import { generateClaimId, listClaims, loadClaim, saveClaim, createCoordinatorClaim, adoptClaimSession, attachAssignmentMessageToClaim, linkClaimToAssignment, releaseClaimWithCascade } from '../core/claims.js';
 import { createSequence, updateSequence, deleteSequence } from '../core/sequence.js';
@@ -575,7 +575,7 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_claim',
-        description: 'Claim a work scope (advisory lock). Automatically creates an isolated git worktree for this claim. Requires contributor trust level or above.',
+        description: 'Claim a work scope (advisory lock). By default creates an isolated git worktree for the claim (multi-agent safety). Pass advisory:true (or worktree:false) for an advisory-only lock with NO worktree — use this when the work already lives uncommitted in the main tree and a fresh worktree would be counterproductive (trp#431). Requires contributor trust level or above.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -588,6 +588,8 @@ const MCP_WRITE_TOOLS = [
                 project: { type: 'string', description: 'Project name or path. Use this when working on a project different from the MCP server workspace (e.g. CLI agents in a different directory).' },
                 store: { type: 'string', description: 'Target store level: local (default), repo, workspace.' },
                 worktreeBranch: { type: 'string', description: 'Branch name for the worktree. Defaults to feat/<scope-slug>.' },
+                worktree: { type: 'boolean', description: 'Whether to create an isolated git worktree (default true). Pass false for an advisory-only lock with no worktree (trp#431) — for in-place work in the main tree.' },
+                advisory: { type: 'boolean', description: 'Alias for worktree:false — advisory-only lock with no worktree (trp#431).' },
                 handoffMode: { type: 'string', enum: ['self-commit', 'integrator'], description: 'Handoff mode: "self-commit" (worker commits+merges) or "integrator" (another agent reviews+merges). Default: self-commit.' },
             },
             required: ['scope', 'description'],
@@ -1033,7 +1035,7 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_assignment_update',
-        description: 'Report assignment lifecycle status. Part of the Agent SDK runtime protocol. Workers call this to report: accepted (acknowledging receipt), started (work begun), progress (heartbeat), completed (done with artifacts), failed (error), or blocked (external blocker). The assignment_id is provided in the dispatch brief.',
+        description: 'Report assignment lifecycle status. Part of the Agent SDK runtime protocol. Workers call this to report: accepted (acknowledging receipt), started (work begun), progress (heartbeat), completed (done with artifacts), failed (error), or blocked (external blocker). The assignment_id is provided in the dispatch brief. OWNERSHIP (trp#291): only the agent the assignment is OWNED BY (the dispatched worker) may update it — a different agent (e.g. the coordinator) gets `Agent <x> cannot update assignment owned by <y>`. If you are the coordinator and need to converge a worker run, do NOT call this; verify via bclaw_dispatch_status instead (the reconciler infers completion from sentinels/commits).',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -1111,7 +1113,7 @@ const MCP_WRITE_TOOLS = [
     // Promoted to `standard` tier at the v1.0 cut.
     {
         name: 'bclaw_find',
-        description: 'Canonical list query over a brainclaw entity. Default read filter excludes records with provenance.kind="legacy" and auto_reflect records below 0.6 confidence — override via filter.includeLegacy / filter.minAutoReflectConfidence. Tag filters accept `tag: string` for one tag or `tags: string[]` for any-match. For entity="agent_run", filters also accept assignment_id, claim_id, and message_id. Pass `project` to query a linked project instead of the current one.',
+        description: 'Canonical list query over a brainclaw entity. Default read filter excludes records with provenance.kind="legacy" and auto_reflect records below 0.6 confidence — override via filter.includeLegacy / filter.minAutoReflectConfidence. Tag filters accept `tag: string` for one tag or `tags: string[]` for any-match. For entity="agent_run", filters also accept assignment_id, claim_id, and message_id. Pass `project` to query a linked project instead of the current one. PAGINATION & SIZE (pln#491): returns at most filter.limit items (default 50), and the page is additionally shrunk if it would exceed the MCP size budget. The response carries `total` (full match count), `returned`, and — when more remain — `has_more: true`, `next_offset`, and a `hint`; pass `filter.offset=<next_offset>` (or a narrower filter) to page rather than expecting everything at once. ORDERING: results follow on-disk/load order, NOT recency — do not assume the first item is the newest (trp#291); filter explicitly (e.g. status, plan_id) to target what you need.',
         annotations: { tier: 'standard', category: 'memory', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -2906,9 +2908,13 @@ async function _executeMcpToolCallInner(payload) {
             const claimId = generateClaimId();
             let worktreePath;
             let worktreeWarn = '';
-            // Always create worktree in MCP context for multi-agent isolation.
-            // The createWorktree param is no longer exposed in the schema.
-            {
+            // trp#431: advisory mode skips worktree creation. Default is to create an
+            // isolated worktree (multi-agent safety), but when the work already lives
+            // (uncommitted) in the main tree a fresh worktree is counterproductive and
+            // the agent ends up skipping the claim. Pass advisory:true (or
+            // worktree:false) for an advisory-only lock with no worktree.
+            const advisoryClaim = args.advisory === true || args.worktree === false;
+            if (!advisoryClaim) {
                 const branchSlug = claimScope.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').slice(0, 48);
                 const worktreeBranch = args.worktreeBranch?.trim() || `feat/${branchSlug}`;
                 try {
@@ -5788,6 +5794,12 @@ async function _executeMcpToolCallInner(payload) {
                     };
                 }
                 const result = listEntities(entity, targetCwd, filter);
+                // pln#491 — bound the payload (count is already capped by applyPaging;
+                // this caps SIZE) so a verbose result set never overflows the MCP token
+                // cap and silently pushes the agent to the CLI (trp#449). Advertises
+                // has_more / next_offset / hint for explicit pagination.
+                const offset = Math.max(0, Number(filter.offset) || 0);
+                const bounded = boundListResult(result, offset);
                 const warnings = collectLoadValidationWarnings(entity, targetCwd);
                 // structuredContent is the canonical MCP return channel that clients
                 // (VS Code extension, Codex, etc.) read for machine-parseable data.
@@ -5795,10 +5807,11 @@ async function _executeMcpToolCallInner(payload) {
                 // response body, which got dropped by the MCP protocol wrapper so
                 // `result.items` arrived as undefined on the client — the root cause
                 // of the VS Code Backlog section rendering empty.
+                const moreNote = bounded.has_more ? ` (returned ${bounded.returned}; ${result.total - bounded.returned} more — offset ${bounded.next_offset})` : '';
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)` }],
-                        structuredContent: { ...result, warnings },
+                        content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)${moreNote}` }],
+                        structuredContent: { ...bounded, warnings },
                     }),
                 };
             }

package/dist/core/agent-capability.js

@@ -664,6 +664,34 @@ export function resolveBriefMode(agentName) {
         return 'compact';
     return 'full';
 }
+// ── Dispatch-time capability matrix (pln#528) ──────────────────────────────
+/**
+ * pln#528 — capability matrix DERIVED from the spawn template, so it stays in
+ * sync with how each agent is actually invoked (no per-profile duplication).
+ *
+ * The motivating reality (debrief LeaseUp): codex is spawned with
+ * `--sandbox workspace-write`, which (a) does NOT wire the brainclaw MCP server
+ * and (b) puts `.git` outside the sandbox root — so a sandboxed worker can
+ * neither call `bclaw_*` nor `git commit`, regardless of the profile's nominal
+ * `runtime.mcp_direct` flag. These helpers expose that so the brief / handoff /
+ * harvest logic can adapt to the transport instead of issuing instructions the
+ * worker cannot follow.
+ */
+export function isSandboxedSpawn(profile) {
+    return /--sandbox\b/.test(profile.invoke_template ?? '');
+}
+/** Whether the agent, AS SPAWNED by the dispatcher, can reach brainclaw MCP. */
+export function dispatchHasMcp(profile) {
+    return profile.runtime.mcp_direct && !isSandboxedSpawn(profile);
+}
+/**
+ * Whether the spawned worker can `git commit`. A sandbox whose root excludes
+ * `.git` cannot — the coordinator must integrate the worker's output instead of
+ * relying on a self-commit handoff.
+ */
+export function dispatchCanCommit(profile) {
+    return !isSandboxedSpawn(profile);
+}
 // ── getDefaultInvokeTemplate ───────────────────────────────────────────────
 /**
  * Get the default invoke template for an agent.

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/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)
@@ -261,6 +266,11 @@ 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}\`.`);
@@ -416,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)
@@ -423,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');
@@ -447,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/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

package/dist/core/worktree.js

@@ -370,6 +370,14 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     // Symlinking .brainclaw/ causes hooks and session_start to trigger on the
     // shared store, creating session conflicts and potentially blocking agents
     // (especially Claude CLI which auto-detects .brainclaw/ presence).
+    // pln#479: opt-in per-worktree typecheck gate. Off by default — on large
+    // monorepos `tsc` is slow and a per-commit gate would be punishing — enable
+    // with BRAINCLAW_WORKTREE_TYPECHECK_GATE=1. Isolated to this worktree, so the
+    // main repo's commits are never affected.
+    let typecheckGate;
+    if (process.env.BRAINCLAW_WORKTREE_TYPECHECK_GATE === '1') {
+        typecheckGate = installWorktreeTypecheckGate(mainWorktreePath, targetPath);
+    }
     const mainGitignorePath = path.join(mainWorktreePath, '.gitignore');
     const targetGitignorePath = path.join(targetPath, '.gitignore');
     if (fs.existsSync(mainGitignorePath)) {
@@ -389,10 +397,83 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
         // that could not be created) so the worker / supervisor can see why a build
         // might fail, instead of an invisible degradation.
         ...(symlinkWarnings.length > 0 ? { symlink_warnings: symlinkWarnings } : {}),
+        // pln#479: record whether the per-worktree typecheck gate is active.
+        ...(typecheckGate?.installed ? { typecheck_gate: true } : {}),
     };
     fs.writeFileSync(path.join(targetPath, '.brainclaw-worktree.json'), JSON.stringify(meta, null, 2));
     return targetPath;
 }
+/** Directory (relative to a worktree root) holding the per-worktree git hooks. */
+export const WORKTREE_HOOKS_DIRNAME = '.brainclaw-hooks';
+/**
+ * The pre-commit gate body (pln#479). Runs via `node -e` — same SIGPIPE-avoiding
+ * pattern as install-hooks.ts. Git runs hooks with cwd = worktree root, so the
+ * relative paths resolve there. `node` and the tsc entry point are invoked with
+ * forward-slash relative paths to stay cross-platform (no quoting/backslash
+ * pitfalls). If typescript is absent the gate degrades to a warning rather than
+ * blocking — a tooling gap must not trap a worker.
+ */
+export function buildTypecheckPreCommitScript() {
+    return `#!/bin/sh
+# brainclaw worktree typecheck gate (pln#479) — do not edit manually.
+# Blocks the commit when 'tsc --noEmit' fails. Bypass: git commit --no-verify.
+exec node -e "
+const fs = require('fs');
+const { execSync } = require('child_process');
+if (!fs.existsSync('tsconfig.json')) process.exit(0);
+if (!fs.existsSync('node_modules/typescript/bin/tsc')) {
+  process.stderr.write('\\\\n[brainclaw] typecheck gate: typescript not found in worktree node_modules — skipping (commit allowed).\\\\n');
+  process.exit(0);
+}
+try {
+  execSync('node node_modules/typescript/bin/tsc --noEmit', { stdio: 'inherit' });
+} catch (e) {
+  process.stderr.write('\\\\n[brainclaw] commit blocked: tsc --noEmit reported type errors (above). Fix them, or bypass with: git commit --no-verify\\\\n\\\\n');
+  process.exit(1);
+}
+" 2>&1 || exit $?
+`;
+}
+/**
+ * pln#479 — install an ISOLATED pre-commit gate in a dispatched worktree that
+ * blocks a commit when `tsc --noEmit` fails, so a worker cannot land code that
+ * breaks the type-check (observed: workers committing strict-mode-broken TS that
+ * only blew up at merge/build time, pln#466).
+ *
+ * Isolation is the crux: git hooks are shared across all worktrees of a repo by
+ * default, so we must NOT write into the common hooks dir — that would impose
+ * tsc on the human's main-repo commits too. Instead we point THIS worktree's
+ * `core.hooksPath` at a worktree-local dir via the `--worktree` config scope
+ * (enabling `extensions.worktreeConfig`), which leaves the main repo's hook
+ * setup completely untouched and is torn down with the worktree.
+ *
+ * No-ops when the worktree has no `tsconfig.json`. Depends on pln#523 having
+ * linked `node_modules` so `tsc` resolves.
+ */
+export function installWorktreeTypecheckGate(mainWorktreePath, worktreePath) {
+    if (!fs.existsSync(path.join(worktreePath, 'tsconfig.json'))) {
+        return { installed: false, reason: 'no tsconfig.json — not a TypeScript worktree' };
+    }
+    try {
+        const hooksDir = path.join(worktreePath, WORKTREE_HOOKS_DIRNAME);
+        fs.mkdirSync(hooksDir, { recursive: true });
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), buildTypecheckPreCommitScript(), {
+            encoding: 'utf-8',
+            mode: 0o755,
+        });
+        // Enable per-worktree config on the repo (idempotent, additive) so the
+        // hooksPath override stays scoped to THIS worktree only.
+        runGit(['config', 'extensions.worktreeConfig', 'true'], mainWorktreePath);
+        const set = runGit(['config', '--worktree', 'core.hooksPath', gitPath(hooksDir)], worktreePath);
+        if (!set.ok) {
+            return { installed: false, reason: `git config --worktree core.hooksPath failed: ${set.stderr.trim()}` };
+        }
+        return { installed: true };
+    }
+    catch (err) {
+        return { installed: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
 /**
  * Lists all git worktrees for the given repo and enriches them with
  * brainclaw metadata if available.

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.7.3 on 2026-06-05T21:43:11.193Z
+// Source: brainclaw v1.7.4 on 2026-06-08T21:59:54.110Z
 export const FACTS = {
-  "version": "1.7.3",
-  "generated_at": "2026-06-05T21:43:11.193Z",
+  "version": "1.7.4",
+  "generated_at": "2026-06-08T21:59:54.110Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.3",
-  "generated_at": "2026-06-05T21:43:11.193Z",
+  "version": "1.7.4",
+  "generated_at": "2026-06-08T21:59:54.110Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.7.3",
+  "version": "1.7.4",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {