brainclaw 1.18.0 → 1.19.1

package/dist/commands/claim.js

@@ -1,7 +1,7 @@
 import { buildOperationalIdentity } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { mutate } from '../core/mutation-pipeline.js';
-import { saveClaim, generateClaimId, listClaims } from '../core/claims.js';
+import { saveClaim, generateClaimId, listClaims, claimBaselineFields } from '../core/claims.js';
 import { rebuildProjectMd } from '../core/markdown.js';
 import { loadState, saveState } from '../core/state.js';
 import { nowISO } from '../core/ids.js';
@@ -64,6 +64,10 @@ export function runClaim(description, options) {
         status: 'active',
         expires_at: options.ttl ? parseTtl(options.ttl) : undefined,
         model: resolveCurrentModel(options.cwd),
+        // pln#636 C0-b / trp#1292 — resolved here, OUTSIDE the mutate() below, so the
+        // git subprocess never widens the critical section that serializes writes on
+        // the claims store.
+        ...claimBaselineFields(options.cwd),
     };
     try {
         mutate({ cwd: options.cwd }, () => {

package/dist/commands/harvest.js

@@ -28,6 +28,8 @@ import { dispatchReviewLoopTurn, turnOwnedReviewEnabled } from '../core/review-l
 import { reconcileTurn } from '../core/loops/reconcile-turn.js';
 import { findReservationByAssignmentId } from '../core/loops/attempt-reservation.js';
 import { readCompletionSignals } from '../core/runtime-signals.js';
+import { reconcileClaimConformity } from '../core/claim-conformity.js';
+import { toWarningDetail } from '../core/warnings.js';
 /**
  * pln#630 PR3a — finalize a TURN-OWNED review lane via the exactly-once `reconcileTurn`
  * instead of the legacy `closeReviewLoopFromLaneResult`. Returns `undefined` for a legacy
@@ -329,7 +331,7 @@ function laneHarvestedMarkerPath(cwd, assignmentId) {
 export function harvestLaneResults(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const agent = options.agent ?? 'coordinator';
-    const result = { harvested: [], skipped: [], errors: [] };
+    const result = { harvested: [], skipped: [], errors: [], warnings: [] };
     const worktreePaths = resolveLaneScanPaths(options, cwd);
     for (const worktreePath of worktreePaths) {
         const file = getLaneResultPath(worktreePath);
@@ -346,6 +348,7 @@ export function harvestLaneResults(options = {}) {
         // Assignment filter (when harvesting a specific lane).
         if (options.assignmentId && lane.assignment_id !== options.assignmentId)
             continue;
+        let ideationLoop = undefined;
         // pln#628 Focus 4B (Codex review of #87 BLOCKING 1) — a review lane must
         // close/advance its loop on the plain report-only harvest path too, not only
         // on `--integrate`. closeReviewLoopFromLaneResult is convergent + idempotent
@@ -371,7 +374,23 @@ export function harvestLaneResults(options = {}) {
                 }
                 // pln#521 P2-bis — the ideation analog: a critic lane records its critique +
                 // advances the ideation loop. Returns undefined for non-ideate scopes (no-op here).
-                closeIdeationLoopFromLaneResult(laneAssignment, lane, agent, cwd);
+                ideationLoop = closeIdeationLoopFromLaneResult(laneAssignment, lane, agent, cwd);
+                // pln#636 C2 (review F3) — the universal net's most important trigger.
+                // A file-fallback worker declares its own footprint in `files_changed`,
+                // which is BOTH cheaper and more reliable than a git diff here: by
+                // harvest time the lane's worktree may already have been reaped, so
+                // trusting the worker's declaration is the only thing that still works.
+                if (laneAssignment.claim_id && lane.files_changed?.length) {
+                    const laneClaim = loadClaim(laneAssignment.claim_id, cwd);
+                    if (laneClaim) {
+                        const conformity = reconcileClaimConformity(laneClaim, cwd, {
+                            touchedPaths: lane.files_changed,
+                        });
+                        if (conformity.warning) {
+                            result.warnings.push(toWarningDetail(conformity.warning));
+                        }
+                    }
+                }
             }
         }
         catch { /* never block harvest on loop-close */ }
@@ -392,6 +411,9 @@ export function harvestLaneResults(options = {}) {
                         assignment_id: lane.assignment_id,
                         status: lane.status,
                         artifacts: lane.artifacts ?? [],
+                        body: lane.body ?? null,
+                        artifact_type: lane.artifact_type ?? null,
+                        ideation_loop: ideationLoop ?? null,
                         files_changed: lane.files_changed ?? [],
                         source_worktree: worktreePath,
                     },
@@ -563,6 +585,7 @@ export function integrateLaneResults(options = {}) {
                 const ideationClose = closeIdeationLoopFromLaneResult(assignment, lane, actor, cwd);
                 if (ideationClose) {
                     reasons.push(`ideate-loop ${ideationClose.loop_id}: ${ideationClose.action} — ${ideationClose.reason}`);
+                    entry.ideation_loop = ideationClose;
                 }
                 // pln#630 PR3a — a TURN-OWNED review lane finalizes via the exactly-once
                 // reconcileTurn, which REPLACES the legacy closer + teardown gate for this lane
@@ -704,6 +727,9 @@ export function integrateLaneResults(options = {}) {
                         files_changed: entry.files_changed,
                         assignment_completed: entry.assignment_completed,
                         claim_released: entry.claim_released,
+                        body: lane.body ?? null,
+                        artifact_type: lane.artifact_type ?? null,
+                        ideation_loop: entry.ideation_loop ?? null,
                     },
                 }, cwd);
             }

package/dist/commands/install-hooks.js

@@ -36,48 +36,205 @@ export function runInstallHooks(options = {}) {
     if (!fs.existsSync(claudeHookPath) || options.force) {
         fs.writeFileSync(claudeHookPath, generateClaudePreToolScript(), { encoding: 'utf-8', mode: 0o755 });
         console.log(`✔ Claude Code preToolUse hook generated at ${claudeHookPath}`);
-        console.log('  To activate, add to .claude/settings.json hooks: { "PreToolUse": ".git/hooks/claude-pre-tool.sh" }');
     }
+    // pln#636 C1 second half (review F2) — GENERATION IS NOT ACTIVATION. This step
+    // used to only print instructions, which is why the hook was dead even for
+    // operators who ran the command: a repaired script nobody wires up is still
+    // dead. The Codex writer has owned `.codex/hooks.json` since v1.17.0; this
+    // brings the Claude surface to the same standard.
+    const activation = activateClaudePreToolHook(gitRoot, claudeHookPath);
+    switch (activation.status) {
+        case 'activated':
+            console.log(`✔ PreToolUse hook activated in ${activation.settingsPath}`);
+            console.log('  Advisory-only (never blocks): it adds context, it cannot deny a write.');
+            break;
+        case 'already_active':
+            console.log(`✔ PreToolUse hook already active in ${activation.settingsPath}`);
+            break;
+        case 'failed':
+            console.log(`⚠ Could not activate the PreToolUse hook automatically: ${activation.reason}`);
+            console.log('  Add this to .claude/settings.json by hand:');
+            console.log('    { "hooks": { "PreToolUse": [ { "matcher": "Edit|Write|MultiEdit|NotebookEdit",');
+            console.log(`        "hooks": [ { "type": "command", "command": "${toPosixPath(claudeHookPath)}" } ] } ] } }`);
+            break;
+    }
+}
+/** Hook scripts are invoked through a shell, so the command is always POSIX-style. */
+function toPosixPath(p) {
+    return p.split('\\').join('/');
 }
+/**
+ * The tools whose `tool_input` exposes a concrete file path.
+ *
+ * `Bash` is deliberately absent: a shell command's file footprint is not
+ * statically knowable, so it is `unverifiable`, never a guess. The pre-repair
+ * matcher included it, which was one source of the noise that made the hook
+ * worth ignoring.
+ */
+const CLAUDE_PRE_TOOL_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+/**
+ * Merge the PreToolUse entry into `.claude/settings.json`, additively.
+ *
+ * NON-DESTRUCTIVE BY CONSTRUCTION, which matters more here than anywhere else in
+ * this file: that file holds the operator's own permission allow-list, and
+ * clobbering it would be a far worse outcome than an unactivated advisory. So
+ * every unknown key is preserved, a pre-existing PreToolUse array is appended
+ * to rather than replaced, and anything unparseable is left strictly untouched
+ * with a manual instruction printed instead (trp_5f342186: a hook mechanism may
+ * never be the thing that destroys work).
+ *
+ * Idempotent: re-running finds the existing command and reports `already_active`.
+ */
+export function activateClaudePreToolHook(gitRoot, hookPath) {
+    const settingsPath = path.join(gitRoot, '.claude', 'settings.json');
+    const command = toPosixPath(hookPath);
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return { status: 'failed', reason: 'settings.json is not a JSON object', settingsPath };
+            }
+            settings = parsed;
+        }
+        catch (err) {
+            // Refusing to touch a file we cannot parse is the whole point: rewriting it
+            // would silently drop the operator's permission list.
+            return {
+                status: 'failed',
+                reason: `settings.json is not valid JSON (${err instanceof Error ? err.message : String(err)})`,
+                settingsPath,
+            };
+        }
+    }
+    const hooksSection = (typeof settings.hooks === 'object' && settings.hooks !== null && !Array.isArray(settings.hooks))
+        ? settings.hooks
+        : {};
+    const preToolUse = Array.isArray(hooksSection.PreToolUse)
+        ? hooksSection.PreToolUse
+        : [];
+    const alreadyActive = preToolUse.some((entry) => entry?.hooks?.some((h) => typeof h?.command === 'string' && toPosixPath(h.command) === command));
+    if (alreadyActive)
+        return { status: 'already_active', settingsPath };
+    const next = {
+        ...settings,
+        hooks: {
+            ...hooksSection,
+            PreToolUse: [
+                ...preToolUse,
+                { matcher: CLAUDE_PRE_TOOL_MATCHER, hooks: [{ type: 'command', command }] },
+            ],
+        },
+    };
+    try {
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        fs.writeFileSync(settingsPath, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+    }
+    catch (err) {
+        return {
+            status: 'failed',
+            reason: err instanceof Error ? err.message : String(err),
+            settingsPath,
+        };
+    }
+    return { status: 'activated', settingsPath };
+}
+/**
+ * Claude Code PreToolUse advisory hook (pln#636 C1, mechanism per cst_38effd52).
+ *
+ * THE MECHANISM MATTERS, AND THE PREVIOUS VERSION HAD IT WRONG THREE WAYS:
+ *
+ * 1. It read the tool name from `CLAUDE_TOOL_NAME` in the environment. Claude
+ *    Code delivers a JSON payload on **stdin**; that env var does not exist, so
+ *    the hook exited before doing anything — dead on arrival.
+ * 2. It wrote its advisory to **stderr with exit 0**. Per the documented host
+ *    contract, stderr at exit 0 is NOT surfaced to the model (only exit 2 feeds
+ *    stderr to Claude, and exit 2 BLOCKS the tool — unacceptable for an
+ *    advisory). So even a hook fixed for (1) would have spoken into the void.
+ *    The only non-blocking channel to the model is
+ *    `hookSpecificOutput.additionalContext` on **stdout** with exit 0.
+ * 3. It shelled out to the CLI (`execSync brainclaw claim list`) on every write,
+ *    and deduped through one project-global marker, so one agent's warning
+ *    silenced every other agent.
+ *
+ * Advisory-only is non-negotiable (trp_5f342186 — a hook cascade destroyed
+ * work): `permissionDecision` is always `allow`, the exit code is always 0.
+ *
+ * SCOPE LIMIT, STATED HONESTLY: this version answers "do you hold ANY active
+ * claim of your own?", not "are you writing outside your claim's scope". Real
+ * scope awareness needs the scope grammar (pln#636 C0-a) — 42.4% of real claim
+ * scopes are not path-matchable (cst_22ebb103), so a path comparison written
+ * today would false-accuse on nearly half of them.
+ *
+ * Guarded by tests/unit/guidance-engine-consistency.test.ts.
+ */
 function generateClaudePreToolScript() {
     return `#!/bin/sh
-# brainclaw Claude Code preToolUse hook
+# brainclaw Claude Code PreToolUse hook (advisory-only)
 # Generated by: brainclaw install-hooks
+# Contract: reads a JSON payload on stdin, replies with JSON on stdout, and
+# ALWAYS exits 0. stderr is deliberately unused: Claude Code does not surface it
+# to the model at exit 0 (cst_38effd52).
 exec node -e "
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
 
-const toolName = process.env.CLAUDE_TOOL_NAME || process.argv[2] || process.env.TOOL_NAME || '';
-const isWrite = /edit|write|replace|bash|str_replace/i.test(toolName);
+let raw = '';
+try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { process.exit(0); }
 
-if (!isWrite || !toolName) process.exit(0);
+let payload;
+try { payload = JSON.parse(raw); } catch (e) { process.exit(0); }
 
+// Only STRUCTURED writes expose a concrete file path. A shell command's file
+// footprint is not statically knowable, so it stays unverifiable — never guessed.
+const toolName = (payload && payload.tool_name) || '';
+if (['Edit', 'Write', 'NotebookEdit', 'MultiEdit'].indexOf(toolName) === -1) process.exit(0);
+
+// Read the store directly; spawning the CLI per edit was the third defect.
+var active = [];
 try {
-  const BCLAW_CMD = fs.existsSync(path.join(process.cwd(), 'node_modules', '.bin', 'brainclaw')) 
-    ? 'npx brainclaw' : 'brainclaw';
-  const out = execSync(BCLAW_CMD + ' claim list --json', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
-  const claims = JSON.parse(out);
-  if (claims && claims.length > 0) process.exit(0);
-} catch (e) {
-  // ignore if brainclaw not found or fails
-  process.exit(0);
-}
+  var claimsDir = path.join(process.cwd(), '.brainclaw', 'coordination', 'claims');
+  var walk = function (dir) {
+    var entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (var i = 0; i < entries.length; i++) {
+      var full = path.join(dir, entries[i].name);
+      if (entries[i].isDirectory()) { walk(full); continue; }
+      if (entries[i].name.slice(-5) !== '.json') continue;
+      try {
+        var claim = JSON.parse(fs.readFileSync(full, 'utf8'));
+        if (claim && claim.status === 'active') active.push(claim);
+      } catch (e) { /* skip an unreadable claim */ }
+    }
+  };
+  walk(claimsDir);
+} catch (e) { process.exit(0); }
 
-const sessionMark = path.join(process.cwd(), '.brainclaw', 'tmp', 'claude_warned');
-if (!fs.existsSync(path.dirname(sessionMark))) fs.mkdirSync(path.dirname(sessionMark), { recursive: true });
+// Identity-aware: only THIS agent's claims count. Another agent holding a claim
+// says nothing about whether you hold one.
+var me = (process.env.BRAINCLAW_AGENT_ID || process.env.BRAINCLAW_AGENT_NAME || process.env.BRAINCLAW_AGENT || '').trim();
+var mine = me ? active.filter(function (c) { return c.agent_id === me || c.agent === me; }) : active;
+if (mine.length > 0) process.exit(0);
 
-if (fs.existsSync(sessionMark)) {
-  const mtime = fs.statSync(sessionMark).mtimeMs;
-  if (Date.now() - mtime < 2 * 60 * 60 * 1000) {
-    process.exit(0); // already warned this session
-  }
-}
-fs.writeFileSync(sessionMark, Date.now().toString());
+// Dedup PER AGENT, not once per project.
+try {
+  var runtimeDir = path.join(process.cwd(), '.brainclaw', 'coordination', 'runtime');
+  var slug = (me || 'unknown').replace(/[^A-Za-z0-9_.-]/g, '_');
+  var mark = path.join(runtimeDir, 'claim-advisory-' + slug + '.mark');
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  if (fs.existsSync(mark) && Date.now() - fs.statSync(mark).mtimeMs < 2 * 60 * 60 * 1000) process.exit(0);
+  fs.writeFileSync(mark, String(Date.now()));
+} catch (e) { /* dedup is best-effort: speaking twice beats crashing */ }
 
-process.stderr.write('\\n[Brainclaw] ⚠️  WARNING: You are about to use an Edit/Write tool (' + toolName + ') but you have NO active claim.\\n');
-process.stderr.write('[Brainclaw] Consider running \\\`brainclaw claim create <scope>\\\` to lock your work and avoid conflicts.\\n\\n');
-" 2>&1 || exit 0
+// The ONLY non-blocking channel to the model. permissionDecision stays 'allow'.
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'allow',
+    additionalContext: '[brainclaw] Editing without an active claim of your own. Claim the scope so parallel agents do not collide. Advisory only: this write is proceeding.',
+  },
+}));
+process.exit(0);
+"
 `;
 }
 function generatePostMergeScript() {

package/dist/commands/mcp-write-claims.js

@@ -18,7 +18,10 @@ import { getTriggeredItems, renderTriggeredItems } from '../core/lifecycle.js';
 import { buildContext } from '../core/context.js';
 import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
-import { generateClaimId, loadClaim, saveClaim, adoptClaimSession, releaseClaimWithCascade } from '../core/claims.js';
+import { generateClaimId, loadClaim, saveClaim, adoptClaimSession, releaseClaimWithCascade, claimBaselineFields } from '../core/claims.js';
+import { releaseClaimNextActions } from '../core/next-actions.js';
+import { reconcileClaimConformity } from '../core/claim-conformity.js';
+import { pushStructuredWarning } from '../core/warnings.js';
 import { checkPolicy } from '../core/policy.js';
 import { createWorktree as coreCreateWorktree, sanitizeBranchComponent } from '../core/worktree.js';
 import { startSession } from './session-start.js';
@@ -125,6 +128,11 @@ export async function handleBclawClaim(payload, ctx) {
         worktree_path: worktreePath,
         expires_at: claimExpiresAt,
         handoff_mode: handoffMode,
+        // pln#636 C0-b / trp#1292 — this handler builds its claim literal instead of
+        // going through acquireClaimScope, which is why the baseline was missing on
+        // every MCP-created claim and the conformity reconcile never had anything to
+        // compare against.
+        ...claimBaselineFields(claimCwd),
     }, claimCwd);
     appendAuditEntry({ actor: resolvedIdentity.agent_name, actor_id: resolvedIdentity.agent_id, action: 'claim', item_id: claimId, item_type: 'claim', scope: claimScope, session_id: identity.session_id, host_id: identity.host_id }, claimCwd);
     // Post-claim policy check: surface constraints/traps as warnings
@@ -251,6 +259,14 @@ export async function handleBclawReleaseClaim(payload, ctx) {
         session_id: connectionSessionId,
         override: coordinatorOverrideRequested,
     };
+    // pln#636 C2 — read the claim BEFORE the cascade: release is what closes it,
+    // and the conformity comparison needs its baseline + declared footprint.
+    // Best-effort by construction; a missing claim just means no advisory.
+    let claimBeforeRelease;
+    try {
+        claimBeforeRelease = loadClaim(claimId, cwd);
+    }
+    catch { /* conformity is advisory — never block a release on it */ }
     let cascadeResult;
     try {
         cascadeResult = releaseClaimWithCascade(claimId, {
@@ -268,12 +284,38 @@ export async function handleBclawReleaseClaim(payload, ctx) {
         planTransitioned ? ` — plan ${cascadePlanId} → ${cascadeNewStatus}` : '',
         planWarning ? ` ⚠ ${planWarning}` : '',
     ].join('');
+    // pln#634 — release is the single most protocol-loaded moment of the daily
+    // loop (it is where the plan cascade either fires or refuses), and it shipped
+    // pure data. Derived from what the cascade actually decided.
+    const releaseActions = releaseClaimNextActions({
+        claimId,
+        planId: cascadePlanId,
+        planTransitioned,
+        planWarning,
+        requestedPlanStatus: typeof args.planStatus === 'string' ? args.planStatus : undefined,
+    });
+    // pln#636 C2 — release is the natural reconcile point: the work is finished, so
+    // the footprint is final. Emits ONLY on a concrete, path-resolvable violation;
+    // every doubt (no baseline, prose scope, reaped worktree) stays silent.
+    const conformityWarnings = [];
+    const conformityDetails = [];
+    if (claimBeforeRelease) {
+        try {
+            const conformity = reconcileClaimConformity(claimBeforeRelease, cwd);
+            if (conformity.warning) {
+                pushStructuredWarning(conformityWarnings, conformityDetails, conformity.warning);
+            }
+        }
+        catch { /* advisory only */ }
+    }
     return {
         response: toolResponse({
             content: [{ type: 'text', text: summaryText }],
             claim_id: claimId,
             ...(planTransitioned ? { plan_id: cascadePlanId, plan_status: cascadeNewStatus } : {}),
             ...(planWarning ? { plan_warning: planWarning, plan_id: cascadePlanId } : {}),
+            ...(conformityWarnings.length ? { warnings: conformityWarnings, warning_details: conformityDetails } : {}),
+            ...(releaseActions.length ? { next_actions: releaseActions } : {}),
         }),
     };
 }
@@ -540,6 +582,23 @@ export async function handleBclawAssignmentUpdate(payload, ctx) {
             actor: callerAgent,
             actor_id: resolved.identity.agent_id,
         }, cwd);
+        // pln#636 C2 — reconcile the linked claim's scope BEFORE the cascade below
+        // releases it (after release there is no claim left to read). This is the
+        // lifecycle boundary a worker crosses when it reports its own completion.
+        const asgnConformityWarnings = [];
+        const asgnConformityDetails = [];
+        if (status === 'completed' && assignment.claim_id) {
+            try {
+                const linkedClaim = loadClaim(assignment.claim_id, cwd);
+                if (linkedClaim) {
+                    const conformity = reconcileClaimConformity(linkedClaim, cwd);
+                    if (conformity.warning) {
+                        pushStructuredWarning(asgnConformityWarnings, asgnConformityDetails, conformity.warning);
+                    }
+                }
+            }
+            catch { /* advisory only — never block a completion report */ }
+        }
         // trp#928 — cascade-release the assignment's linked claim on completion.
         // Before this landing an obedient worker had to make TWO calls to close
         // the loop (bclaw_assignment_update status=completed AND
@@ -628,6 +687,9 @@ export async function handleBclawAssignmentUpdate(payload, ctx) {
                     ...(result.assignment.completed_at && { completed_at: result.assignment.completed_at }),
                     last_heartbeat_at: result.assignment.last_heartbeat_at,
                     ...(createdActionId ? { action_id: createdActionId } : {}),
+                    ...(asgnConformityWarnings.length
+                        ? { warnings: asgnConformityWarnings, warning_details: asgnConformityDetails }
+                        : {}),
                 },
             },
         };

package/dist/commands/mcp-write-coordination.js

@@ -21,6 +21,8 @@ import { nowISO } from '../core/ids.js';
 import { validateMcpField } from '../core/input-validation.js';
 import { generateCandidateIdWithLabel, saveCandidate } from '../core/candidates.js';
 import { validateLoopProjectResolution } from '../core/loops/project-resolution.js';
+import { coordinateNextActions, dispatchNextActions } from '../core/next-actions.js';
+import { agentValidationFailedWarning, planAlreadyAssignedWarning, pushStructuredWarning, scopeAlreadyClaimedWarning, } from '../core/warnings.js';
 import { ackMessage, getThread, hasActiveAssignment, sendMessage } from '../core/messaging.js';
 import { dispatch, dispatchReview, generateDispatchBrief } from '../core/dispatcher.js';
 import { CoordinateRequestSchema } from '../core/facade-schema.js';
@@ -173,12 +175,25 @@ export async function handleBclawDispatch(args, ctx) {
             item_type: 'dispatch',
             scope: `${dispatchResult.messages_sent.length} assignments`,
         }, cwd);
+        // pln#634 — the text body already tells a human what to do next; the
+        // structured payload told an agent nothing. Derived from the real cycle
+        // outcome: verification targets for what spawned, analysis for what is
+        // blocked, and a re-run hint for a dry run. Manual launch commands are
+        // deliberately NOT mirrored here — they are not MCP-callable.
+        const dispatchActions = dispatchNextActions({
+            spawnedTargets: spawned
+                .map((m) => m.assignment_id ?? m.run_id ?? m.claim_id)
+                .filter((id) => typeof id === 'string' && id.length > 0),
+            blockedCount: analysis.blocked.length,
+            dryRun: !!args.dryRun,
+        });
         return {
             response: toolResponse({
                 content: [{ type: 'text', text: lines.join('\n') }],
                 ...dispatchResult,
                 sequence_id: analysis.sequence.id,
                 dry_run: !!args.dryRun,
+                ...(dispatchActions.length ? { next_actions: dispatchActions } : {}),
             }),
         };
     }
@@ -308,6 +323,11 @@ export async function handleBclawCoordinate(args, ctx) {
     // for the intents that actually spawn a worktree worker). See the
     // assessDirtyDispatchGuard call after the cross-project block.
     const warnings = [];
+    // pln#635 — structured sibling of `warnings`. Deliberately a SUBSET: the
+    // codes that carry a recovery path write here, prose advisories stay
+    // string-only for now (`warnings` remains the complete channel — see
+    // core/warnings.ts for the reference-threading reason).
+    const warningDetails = [];
     const artifacts = [];
     const side_effects = [];
     // can_5e62334e — codex sandboxed dispatches cannot commit in worktrees
@@ -694,8 +714,7 @@ export async function handleBclawCoordinate(args, ctx) {
             // retry loops can react (e.g. fall back to a different agent).
             const check = validateAgentForDispatch(agentName, { requireSpawnable: true });
             if (!check.valid) {
-                warnings.push(JSON.stringify({
-                    warning: 'agent_validation_failed',
+                pushStructuredWarning(warnings, warningDetails, agentValidationFailedWarning({
                     agent: agentName,
                     code: check.code,
                     reason: check.reason,
@@ -707,21 +726,19 @@ export async function handleBclawCoordinate(args, ctx) {
             const assignScope = req.scope ?? req.task;
             // Guard: warn if there is already a non-archived assign message for this agent+scope
             if (hasActiveAssignment(agentName, assignScope, dispatchCwd)) {
-                warnings.push(JSON.stringify({
-                    warning: 'plan_already_assigned',
-                    plan_id: assignScope,
-                    existing_agent: agentName,
+                pushStructuredWarning(warnings, warningDetails, planAlreadyAssignedWarning({
+                    planId: assignScope,
+                    existingAgent: agentName,
                 }));
             }
             // Guard: warn if there is already an active claim on the same scope
             const conflictingClaims = listClaims(dispatchCwd).filter((c) => c.status === 'active' && c.scope === assignScope);
             if (conflictingClaims.length > 0) {
                 const existing = conflictingClaims[0];
-                warnings.push(JSON.stringify({
-                    warning: 'scope_already_claimed',
+                pushStructuredWarning(warnings, warningDetails, scopeAlreadyClaimedWarning({
                     scope: assignScope,
-                    existing_agent: existing.agent,
-                    existing_claim_id: existing.id,
+                    existingAgent: existing.agent,
+                    existingClaimId: existing.id,
                 }));
             }
             const claimResult = createCoordinatorClaim({
@@ -1255,8 +1272,7 @@ export async function handleBclawCoordinate(args, ctx) {
             // trp#51: validate target agent before creating a new claim.
             const check = validateAgentForDispatch(newAgentName, { requireSpawnable: true });
             if (!check.valid) {
-                warnings.push(JSON.stringify({
-                    warning: 'agent_validation_failed',
+                pushStructuredWarning(warnings, warningDetails, agentValidationFailedWarning({
                     agent: newAgentName,
                     code: check.code,
                     reason: check.reason,
@@ -1643,8 +1659,7 @@ export async function handleBclawCoordinate(args, ctx) {
                         // behind that only fails later at spawn time.
                         const critCheck = validateAgentForDispatch(slot.agent, { requireSpawnable: true });
                         if (!critCheck.valid) {
-                            warnings.push(JSON.stringify({
-                                warning: 'agent_validation_failed',
+                            pushStructuredWarning(warnings, warningDetails, agentValidationFailedWarning({
                                 agent: slot.agent,
                                 code: critCheck.code,
                                 reason: critCheck.reason,
@@ -1871,8 +1886,17 @@ export async function handleBclawCoordinate(args, ctx) {
     // attach a self-documenting `verify_with` hint pointing at the assignment
     // record. Callers should not take delivered_and_started at face value —
     // it only attests the brief-ack sentinel was touched, not that the worker
-    // is doing useful work. The hint tells them exactly which canonical-
-    // grammar call to make next to verify spawn liveness.
+    // is doing useful work.
+    //
+    // pln#634 — the hint used to tell callers to expect "OS pid alive", which
+    // directly contradicts the protocol every instruction file ships
+    // (instruction-templates.ts: trust dispatch_status, NEVER the tracked pid).
+    // On Windows an ack-wrapped spawn runs under cmd.exe, so agent_run.pid is
+    // the wrapper — it exits by design and reads dead while the worker is alive
+    // and committing (trp_7fc3e3c4). An obedient agent following the old text
+    // killed healthy workers. The field shape is unchanged (retro-compat), the
+    // expectation no longer lies, and the authoritative call now also ships in
+    // `next_actions` below as bclaw_dispatch_status.
     let verifyWith;
     if (resultExecStatus === 'delivered_and_started') {
         const firstAssignment = artifacts.find((a) => a.type === 'assignment');
@@ -1881,11 +1905,25 @@ export async function handleBclawCoordinate(args, ctx) {
                 action: 'bclaw_find',
                 entity: 'agent_run',
                 filter: { assignment_id: firstAssignment.id },
-                expected_when_alive: 'agent_run with status="running" AND OS pid alive AND last_event_at within the last few minutes',
+                expected_when_alive: 'agent_run with status="running" AND last_event_at within the last few minutes. '
+                    + 'Do NOT judge liveness from agent_run.pid — on an ack-wrapped spawn that pid is the '
+                    + `wrapper, not the worker. Prefer bclaw_dispatch_status(target_id: "${firstAssignment.id}") `
+                    + 'for a sentinel-based verdict.',
                 see_also: 'docs/concepts/dispatch-lifecycle.md',
             };
         }
     }
+    // pln#634 — outcome-derived affordances on the coordinate facade. Derived
+    // from what actually happened (did anything spawn? was a loop opened?), not
+    // from the intent alone; empty means the key is omitted rather than shipping
+    // an empty array for an agent to parse.
+    const coordinateActions = coordinateNextActions({
+        intent: req.intent,
+        assignmentIds: artifacts.filter((a) => a.type === 'assignment').map((a) => a.id),
+        loopId: artifacts.find((a) => a.type === 'loop')?.id,
+        candidateId: artifacts.find((a) => a.type === 'candidate')?.id,
+        executionStatus: resultExecStatus,
+    });
     const facadeResponse = {
         status: facadeStatus,
         intent: req.intent,
@@ -1897,6 +1935,8 @@ export async function handleBclawCoordinate(args, ctx) {
         ...(resultExecStatus ? { execution_status: resultExecStatus } : {}),
         ...(resultExecReason ? { execution_reason: resultExecReason } : {}),
         ...(verifyWith ? { verify_with: verifyWith } : {}),
+        ...(coordinateActions.length ? { next_actions: coordinateActions } : {}),
+        ...(warningDetails.length ? { warning_details: warningDetails } : {}),
     };
     const summaryParts = [`✔ bclaw_coordinate [${req.intent}] targets=${resolvedAgents.length}`];
     if (resultExecStatus)

package/dist/commands/mcp-write-entities.js

@@ -23,6 +23,7 @@ import { createPlan, deletePlan as deletePlanOp } from '../core/operations/plan.
 import { loadCandidate } from '../core/candidates.js';
 import { resolveCrossProjectWritableTarget, resolveProjectCwd, writeCrossProjectSignal } from '../core/cross-project.js';
 import { hasMinimumTrustLevel } from '../core/agent-registry.js';
+import { createEntityNextActions, transitionNextActions } from '../core/next-actions.js';
 import { acceptCandidate } from './accept.js';
 import { rejectCandidate } from './reject.js';
 import { applyHandoffUpdates } from './update-handoff.js';
@@ -432,6 +433,10 @@ export function handleBclawCreate(payload, ctx) {
         const createContent = autoRepair
             ? [{ type: 'text', text: createText }, { type: 'text', text: renderAutoRepairWarning(autoRepair, actor ?? 'unknown') }]
             : [{ type: 'text', text: createText }];
+        // pln#634 — a freshly created plan whose steps are never added is the most
+        // common half-finished shape in the store; a sequence with no readiness
+        // check is the second. Only those two emit a follow-up.
+        const createActions = createEntityNextActions({ entity, id: result.id });
         return {
             response: appendSecurityWarnings(toolResponse({
                 content: createContent,
@@ -441,6 +446,7 @@ export function handleBclawCreate(payload, ctx) {
                     active_source: autoSwitched ? 'auto_switch' : targetScope.active_source,
                     ...(autoSwitched ? { auto_switched: true } : {}),
                     ...(autoRepair ? { auto_repair: autoRepair } : {}),
+                    ...(createActions.length ? { next_actions: createActions } : {}),
                 },
             }), createScan.warnings),
         };
@@ -600,6 +606,10 @@ export function handleBclawTransition(payload, ctx) {
         const transitionContent = auto_repair
             ? [{ type: 'text', text: transitionText }, { type: 'text', text: renderAutoRepairWarning(auto_repair, agent_name) }]
             : [{ type: 'text', text: transitionText }];
+        // pln#634 — only the two transitions that imply an unambiguous next call
+        // emit anything (plan → in_progress / blocked); everything else is terminal
+        // for the caller and returns nothing rather than inventing busywork.
+        const transitionActions = transitionNextActions({ entity, id, to });
         return {
             response: toolResponse({
                 content: transitionContent,
@@ -609,6 +619,7 @@ export function handleBclawTransition(payload, ctx) {
                     active_source: autoSwitched ? 'auto_switch' : targetScope.active_source,
                     ...(autoSwitched ? { auto_switched: true } : {}),
                     ...(auto_repair ? { auto_repair } : {}),
+                    ...(transitionActions.length ? { next_actions: transitionActions } : {}),
                 },
             }),
         };