brainclaw 1.7.1 → 1.7.3

package/dist/core/dispatcher.js

@@ -43,7 +43,8 @@ import { memoryDir } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import fs from 'node:fs';
 import path from 'node:path';
-import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile } from './agent-capability.js';
+import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile, 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';
 import { createAgentRun, transitionAgentRun } from './agentruns.js';
@@ -163,13 +164,20 @@ export function analyzeSequence(cwd) {
         .map(a => a.agent_name);
     const agent_capacity = allAgentNames.map(agent => {
         const active_claims = agentClaimCounts.get(agent) ?? 0;
-        const profile = getCapabilityProfile(agent);
-        const max_tasks = profile?.max_concurrent_tasks ?? 1;
-        return { agent, active_claims, max_tasks, slots_remaining: Math.max(0, max_tasks - active_claims) };
+        // pln#520 step 3: limit is resolved (default unlimited for parallelizable
+        // CLI agents), not the per-name structural constant.
+        const limit = resolveConcurrencyLimit(agent);
+        const slots = Number.isFinite(limit) ? Math.max(0, limit - active_claims) : Infinity;
+        return {
+            agent,
+            active_claims,
+            max_tasks: serializeConcurrencyLimit(limit),
+            slots_remaining: serializeConcurrencyLimit(slots),
+        };
     });
-    // Available agents: those with remaining capacity (slots_remaining > 0)
+    // Available agents: unlimited (null) or with remaining capacity (> 0).
     const available_agents = agent_capacity
-        .filter(a => a.slots_remaining > 0)
+        .filter(a => a.slots_remaining === null || a.slots_remaining > 0)
         .map(a => a.agent);
     return { sequence, ready, active, blocked, done, available_agents, agent_capacity };
 }
@@ -188,6 +196,37 @@ export function analyzeSequence(cwd) {
  * Protocol section IS useful to them — `resolveBriefMode` was updated to
  * return 'full' for that combination.
  */
+/**
+ * pln#520 step 5 — the liveness section of a generated brief. An imperative
+ * "do this first" instruction telling the worker to write its `work_loop_reached`
+ * heartbeat to an ABSOLUTE, writable signals path BEFORE any other action, then
+ * refresh it periodically. Zero-MCP (a plain shell redirect) so even sandboxed
+ * agents without the brainclaw MCP can comply. Completion is recorded
+ * mechanically by the spawn wrapper (step 4), so the agent only owns the
+ * heartbeat. This is the worker-side half of the liveness contract whose
+ * engine-side floor is the wrapper + reconciler (steps 4 + 1).
+ */
+export function buildLivenessSection(cwd, assignmentId) {
+    const hbPath = getRuntimeSignalPath(cwd, assignmentId, 'heartbeat');
+    const isWin = process.platform === 'win32';
+    const writeCmd = isWin
+        ? `echo work_loop_reached ${assignmentId} > "${hbPath}"`
+        : `printf 'work_loop_reached ${assignmentId} %s' "$(date +%s)" > "${hbPath}"`;
+    return [
+        '## Liveness — DO THIS FIRST (step 0)',
+        'Before ANY other action, prove you reached your work loop by writing a heartbeat,',
+        'then refresh it every few minutes while you work. brainclaw uses this to tell',
+        '"alive and working" from "spawned but dead" — a missing/stale heartbeat marks the',
+        'run stalled. Completion is recorded automatically by the spawn wrapper; you do NOT',
+        'need to write a completed/failed signal.',
+        '',
+        '```sh',
+        writeCmd,
+        '```',
+        `Heartbeat file (absolute, writable): ${hbPath}`,
+        '',
+    ].join('\n');
+}
 export function buildProtocolSection(options) {
     const parts = [];
     parts.push('## Protocol');
@@ -199,6 +238,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)
@@ -215,6 +261,9 @@ 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#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');
@@ -305,6 +354,12 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     if (plan.estimated_effort)
         parts.push(`Estimated effort: ${plan.estimated_effort} minutes`);
     parts.push('');
+    // pln#520 step 5 — liveness heartbeat instruction, first actionable block so
+    // the worker writes work_loop_reached before anything else. Only when an
+    // assignment id is known (the heartbeat is keyed by it).
+    if (options?.assignmentId) {
+        parts.push(buildLivenessSection(cwd, options.assignmentId));
+    }
     // Steps if any
     if (plan.steps?.length) {
         parts.push('## Steps');
@@ -421,14 +476,18 @@ export function scoreAgents(agentPool, plan, activeClaims, cycleAssignments) {
         const canExecute = profile?.role_capabilities.includes('execute') ?? false;
         const canSpawn = profile?.runtime.canBeSpawnedCli ?? false;
         const capability = canExecute ? (canSpawn ? 1.0 : 0.5) : 0.1;
-        // Factor 3: Availability — graduated by utilization (claims / max_concurrent_tasks)
-        // Include in-cycle assignments so load-balance works within a single dispatch call
+        // Factor 3 & 4: Availability + load balance.
+        // pln#520 step 3: these are based on the agent's RAW load (active claims +
+        // in-cycle assignments), decoupled from any concurrency cap. Dividing by the
+        // cap (as before) made every agent look identically idle once concurrency
+        // went unlimited, collapsing load-balancing — work piled onto the single
+        // top-scored agent. A cap-independent load fraction keeps spreading work to
+        // the least-busy agent whether or not a cap is set. The hard cap is enforced
+        // separately by the capacity guard in the dispatch loop.
         const agentClaims = (claimCounts.get(agent) ?? 0) + (cycleAssignments?.get(agent) ?? 0);
-        const maxTasks = profile?.max_concurrent_tasks ?? 1;
-        const utilization = Math.min(1.0, agentClaims / maxTasks);
-        const availability = 1.0 - (utilization * 0.5); // range [0.5, 1.0]
-        // Factor 4: Load balance — normalized by agent's capacity, not raw claim count
-        const load_balance = 1.0 - utilization;
+        const loadFraction = agentClaims / (agentClaims + 1); // 0 when idle, →1 as load grows
+        const availability = 1.0 - loadFraction * 0.5; // range (0.5, 1.0]
+        const load_balance = 1.0 - loadFraction; // range (0, 1]
         const score = preference * W_PREFERENCE +
             capability * W_CAPABILITY +
             availability * W_AVAILABILITY +
@@ -438,6 +497,20 @@ export function scoreAgents(agentPool, plan, activeClaims, cycleAssignments) {
 }
 // Re-export checkActiveInstance for consumers who import from dispatcher
 export { checkActiveInstance } from './execution.js';
+/**
+ * pln#520 step 3 — sum in-cycle assignments across every agent identity that
+ * shares the same host-binary resource (e.g. claude-code + claude-sonnet both
+ * map to `claude`). Pairs with `resolveResourceKey` so a concurrency cap pools
+ * by binary, not by agent name.
+ */
+function countCycleByResource(cycleAssignments, resourceKey) {
+    let total = 0;
+    for (const [agent, count] of cycleAssignments) {
+        if (resolveResourceKey(agent) === resourceKey)
+            total += count;
+    }
+    return total;
+}
 export function selectWorktreeBaseForReadyLane(item, analysis) {
     const hardAfter = item.hard_after ?? [];
     if (hardAfter.length === 0)
@@ -503,13 +576,17 @@ export async function dispatch(options, cwd) {
                     continue; // truly active — skip
                 // Claim released but message not archived: stale assignment, allow re-dispatch
             }
-            // Claim-based capacity guard: check claims (existing + this cycle) against max_concurrent_tasks.
-            // This is the authoritative capacity check — covers both options.agents and analysis.available_agents paths.
-            const existingClaims = allActiveClaims.filter(c => c.agent === candidate.agent).length;
-            const inCycleCount = cycleAssignments.get(candidate.agent) ?? 0;
-            const maxTasks = getCapabilityProfile(candidate.agent)?.max_concurrent_tasks ?? 1;
-            if (existingClaims + inCycleCount >= maxTasks) {
-                result.warnings.push(`${candidate.agent}: at capacity (${existingClaims + inCycleCount}/${maxTasks} claims)`);
+            // Claim-based capacity guard (pln#520 step 3): count usage per host-binary
+            // resource (claude-code + claude-sonnet share `claude`), compare against the
+            // resolved limit (default unlimited — no arbitrary per-identity throttle).
+            // This is the authoritative capacity check — covers both options.agents and
+            // analysis.available_agents paths.
+            const resourceKey = resolveResourceKey(candidate.agent);
+            const existingClaims = allActiveClaims.filter(c => resolveResourceKey(c.agent) === resourceKey).length;
+            const inCycleCount = countCycleByResource(cycleAssignments, resourceKey);
+            const limit = resolveConcurrencyLimit(candidate.agent, { override: options.maxConcurrency });
+            if (existingClaims + inCycleCount >= limit) {
+                result.warnings.push(`${candidate.agent}: at capacity (${existingClaims + inCycleCount}/${limit} ${resourceKey} slots)`);
                 continue; // try next agent
             }
             targetAgent = candidate.agent;
@@ -561,7 +638,7 @@ export async function dispatch(options, cwd) {
         if (options.dryRun) {
             const briefMode = resolveBriefMode(targetAgent);
             const brief = generateBrief(readyItem.plan, readyItem.item, cwd, briefMode, { claimId, worktreePath });
-            const invokeCmd = buildInvokeCommand(targetAgent, brief);
+            const invokeCmd = buildInvokeCommand(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) });
             if (invokeCmd) {
                 const cmdPrefix = buildEnvPrefix(claimId);
                 result.commands.push({ agent: targetAgent, lane: readyItem.lane, command: `${cmdPrefix}${invokeCmd.bashCommand}`, shell: process.platform === 'win32' ? 'cmd' : (invokeCmd.shell ? 'bash' : 'sh') });
@@ -571,9 +648,10 @@ export async function dispatch(options, cwd) {
             result.messages_sent.push(deliveryEntry);
             assigned++;
             cycleAssignments.set(targetAgent, (cycleAssignments.get(targetAgent) ?? 0) + 1);
-            const dryExisting = allActiveClaims.filter(c => c.agent === targetAgent).length;
-            const dryCycle = cycleAssignments.get(targetAgent) ?? 0;
-            const dryMax = getCapabilityProfile(targetAgent)?.max_concurrent_tasks ?? 1;
+            const dryResourceKey = resolveResourceKey(targetAgent);
+            const dryExisting = allActiveClaims.filter(c => resolveResourceKey(c.agent) === dryResourceKey).length;
+            const dryCycle = countCycleByResource(cycleAssignments, dryResourceKey);
+            const dryMax = resolveConcurrencyLimit(targetAgent, { override: options.maxConcurrency });
             if (dryExisting + dryCycle >= dryMax) {
                 const idx = agentPool.indexOf(targetAgent);
                 if (idx >= 0)
@@ -616,7 +694,7 @@ export async function dispatch(options, cwd) {
             agent: targetAgent,
         });
         // Step 3: Build invoke command
-        const invokeCmd = buildInvokeCommand(targetAgent, brief);
+        const invokeCmd = buildInvokeCommand(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) });
         if (invokeCmd) {
             const cmdPrefix = buildEnvPrefix(claimId);
             result.commands.push({
@@ -707,10 +785,12 @@ export async function dispatch(options, cwd) {
         assigned++;
         // Track assignments this cycle for multi-slot capacity
         cycleAssignments.set(targetAgent, (cycleAssignments.get(targetAgent) ?? 0) + 1);
-        // Remove agent from pool only when at capacity (existing claims + this cycle's assignments)
-        const existingClaims = allActiveClaims.filter(c => c.agent === targetAgent).length;
-        const cycleCount = cycleAssignments.get(targetAgent) ?? 0;
-        const maxTasks = getCapabilityProfile(targetAgent)?.max_concurrent_tasks ?? 1;
+        // Remove agent from pool only when at capacity, counted per host-binary
+        // resource against the resolved limit (pln#520 step 3).
+        const liveResourceKey = resolveResourceKey(targetAgent);
+        const existingClaims = allActiveClaims.filter(c => resolveResourceKey(c.agent) === liveResourceKey).length;
+        const cycleCount = countCycleByResource(cycleAssignments, liveResourceKey);
+        const maxTasks = resolveConcurrencyLimit(targetAgent, { override: options.maxConcurrency });
         if (existingClaims + cycleCount >= maxTasks) {
             const idx = agentPool.indexOf(targetAgent);
             if (idx >= 0)

package/dist/core/entity-operations.js

@@ -21,12 +21,13 @@ import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, tran
 import { listAgentRuns } from './agentruns.js';
 import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
 import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
+import { createSequence, deleteSequence, listSequences, updateSequence, } from './sequence.js';
 import { createConstraint, createDecision, createTrap, } from './operations/memory-write.js';
 import { deleteMemoryItem, findMemoryItemInChain, updateMemoryItem, } from './operations/memory-mutation.js';
 import { createPlan, deletePlan, updatePlan, } from './operations/plan.js';
 import { ENTITY_REGISTRY, isValidTransition, } from './entity-registry.js';
 import { generateId } from './ids.js';
-import { CandidateTypeSchema, ConstraintCategorySchema, DecisionOutcomeSchema, MemoryVisibilitySchema, PlanTypeEnumSchema, PrioritySchema, RuntimeNoteTypeSchema, SeveritySchema, } from './schema.js';
+import { CandidateTypeSchema, ConstraintCategorySchema, DecisionOutcomeSchema, MemoryVisibilitySchema, PlanTypeEnumSchema, PrioritySchema, RuntimeNoteTypeSchema, SequenceStatusSchema, SeveritySchema, } from './schema.js';
 /**
  * Default provenance stamp applied on create when the caller does not
  * supply one. `user` kind with whatever author is in the payload; the
@@ -134,6 +135,7 @@ function loadAll(name, cwd) {
         case 'handoff': return loadState(cwd).open_handoffs;
         case 'candidate': return listCandidates(undefined, cwd);
         case 'runtime_note': return listRuntimeNotes(undefined, cwd);
+        case 'sequence': return listSequences(cwd);
         case 'claim': return listClaims(cwd);
         case 'action': return listActionRequired(cwd);
         case 'assignment': return listAssignments(cwd);
@@ -310,6 +312,19 @@ export function createEntity(name, data, cwd) {
             saveCandidate(candidate, cwd);
             return { entity: name, id };
         }
+        case 'sequence': {
+            const res = createSequence({
+                name: requireString(data, 'name'),
+                description: data.description,
+                status: requireEnum(data, 'status', SequenceStatusSchema.options, { optional: true }),
+                items: optionalSequenceItems(data),
+                owner: data.owner,
+                author: requireString(data, 'author'),
+                authorId: data.agent_id,
+                tags: data.tags,
+            }, cwd);
+            return { entity: name, id: res.id, short_label: res.shortLabel };
+        }
         case 'cross_project_link': {
             const link = addCrossProjectLink({
                 path: requireString(data, 'path'),
@@ -398,6 +413,20 @@ export function updateEntity(name, id, patch, cwd) {
             saveCandidate(patched, cwd);
             return { entity: name, id };
         }
+        case 'sequence': {
+            // `status` is intentionally NOT in sequence.updatable — lifecycle moves
+            // go through bclaw_transition. The invalidFields guard above already
+            // rejects it, so only name/description/tags/items/owner reach here.
+            const result = updateSequence({
+                id,
+                name: patch.name,
+                description: patch.description,
+                items: optionalSequenceItems(patch),
+                owner: patch.owner,
+                tags: patch.tags,
+            }, cwd);
+            return { entity: name, id: result.id };
+        }
         case 'cross_project_link': {
             // In-place patch: find by id (= name/path), remove, re-add with merged
             // fields. Same path semantics as resolveCrossProjectTarget so callers can
@@ -450,6 +479,16 @@ export function removeEntity(name, id, cwd, purge = false) {
             archiveCandidate(candidate, 'rejected', cwd);
             return { entity: name, id, archived: true, purged: false };
         }
+        case 'sequence': {
+            // purge → hard-delete the file; default → soft-archive (status='archived',
+            // the sequence terminal state) so the lane history stays auditable.
+            if (purge) {
+                const deleted = deleteSequence(id, cwd);
+                return { entity: name, id: deleted.id, archived: false, purged: true };
+            }
+            const archived = updateSequence({ id, status: 'archived' }, cwd);
+            return { entity: name, id: archived.id, archived: true, purged: false };
+        }
         case 'cross_project_link': {
             const removed = removeCrossProjectLink(id, cwd);
             return { entity: name, id: removed.name ?? removed.path, archived: false, purged: true };
@@ -530,6 +569,12 @@ export function transitionEntity(name, id, to, cwd, _reason) {
             }, cwd);
             return { entity: name, id, from, to, side_effects: sideEffects };
         }
+        case 'sequence': {
+            // isValidTransition above already enforced the registry matrix
+            // (draft→active|archived, active→archived); updateSequence persists it.
+            updateSequence({ id, status: to }, cwd);
+            return { entity: name, id, from, to, side_effects: sideEffects };
+        }
         default:
             throw new EntityOperationUnsupportedError(name, 'transition', `Lifecycle transitions for ${name} not yet wired.`);
     }
@@ -559,6 +604,14 @@ function requireString(data, field) {
     }
     return value;
 }
+function optionalSequenceItems(data) {
+    if (!('items' in data) || data.items === undefined || data.items === null)
+        return undefined;
+    if (!Array.isArray(data.items)) {
+        throw new Error(`Invalid value for 'items': expected an array of sequence item objects`);
+    }
+    return data.items;
+}
 /**
  * Validates that data[field] is one of `validValues`, throwing a clear
  * error message when the value is invalid. Fixes the silent-data-loss bug

package/dist/core/execution-adapters.js

@@ -4,12 +4,21 @@ import path from 'node:path';
 import { buildClaimEnvPrefix } from './execution-profile.js';
 import { getCapabilityProfile } from './agent-capability.js';
 import { nowISO } from './ids.js';
+import { ensureRuntimeDirs, getRuntimeLogPath, getRuntimeSignalPath, } from './runtime-signals.js';
+export function buildAckWrapCommand(bashCommand, paths, isWin32) {
+    const touch = isWin32
+        ? (p) => `type nul > "${p}"`
+        : (p) => `touch "${p}"`;
+    const redirected = `${bashCommand} > "${paths.stdoutLog}" 2> "${paths.stderrLog}"`;
+    return (`${touch(paths.ackPath)} && ` +
+        `( ${redirected} && ${touch(paths.completedPath)} || ${touch(paths.failedPath)} )`);
+}
 /**
  * Check if a binary is resolvable on the system PATH.
  * On Windows, `spawn({shell:true})` always succeeds (launches cmd.exe),
  * masking ENOENT for missing binaries. This pre-check catches that.
  */
-function resolveBinaryOnPath(binary) {
+export function resolveBinaryOnPath(binary) {
     // Absolute or relative path — check directly
     if (binary.includes('/') || binary.includes('\\')) {
         return fs.existsSync(binary) ? binary : undefined;
@@ -90,48 +99,32 @@ export class CliExecutionAdapter {
         const spawnExecutable = resolvedExecutable ?? invoke.executable;
         const useShell = isWin32 && /\.(cmd|bat)$/i.test(spawnExecutable);
         const needsStdin = invoke.promptDelivery === 'stdin_pipe' && invoke.promptText;
-        // pln#504: open per-assignment log files for stdout/stderr capture so silent
-        // worker deaths (trp#292) become diagnosable. Previously stdio used 'ignore'
-        // for stdout+stderr — anything the worker said vanished. Best-effort: on
-        // failure to open log files we fall back to the legacy 'ignore' behaviour
-        // rather than abort the spawn.
+        // pln#520 step 4: when we ack-wrap, the SHELL redirects stdout/stderr to the
+        // per-assignment log files (fds passed via stdio are NOT inherited through
+        // the cmd.exe → .cmd → node shim — the empty-logs bug of can_f792cacd), and
+        // the wrapper emits completed/failed sentinels mechanically. So the spawned
+        // process just ignores stdout/stderr here. stdin stays a pipe when the
+        // prompt is delivered that way (the grouped agent command inherits it).
         const useAckWrap = !!(options.assignmentId && (options.ackRoot ?? options.worktreePath));
-        let logFds;
-        if (useAckWrap) {
-            try {
-                const logRoot = options.ackRoot ?? options.worktreePath;
-                const logDir = path.join(logRoot, '.brainclaw', 'coordination', 'runtime', 'log');
-                fs.mkdirSync(logDir, { recursive: true });
-                logFds = {
-                    stdout: fs.openSync(path.join(logDir, `${options.assignmentId}.stdout.log`), 'a'),
-                    stderr: fs.openSync(path.join(logDir, `${options.assignmentId}.stderr.log`), 'a'),
-                };
-            }
-            catch {
-                // Log capture is best-effort — never block the spawn on logging issues.
-                logFds = undefined;
-            }
-        }
         const stdinTarget = needsStdin ? 'pipe' : 'ignore';
-        const stdoutTarget = logFds ? logFds.stdout : 'ignore';
-        const stderrTarget = logFds ? logFds.stderr : 'ignore';
-        const stdio = [stdinTarget, stdoutTarget, stderrTarget];
-        // pln#476: wrap the spawn command with a brief-ack step so the worker
-        // shell touches a sentinel file BEFORE the agent binary runs.
-        // waitForAssignmentHandshake checks that file as evidence the spawn
-        // executed — needed for codex (which lacks the brainclaw MCP context
-        // to call bclaw_assignment_update). When ackRoot/assignmentId are
-        // omitted, we keep the original direct-binary spawn.
+        const stdio = [stdinTarget, 'ignore', 'ignore'];
+        // pln#476 + pln#520 step 4: wrap the spawn so the worker shell touches the
+        // pre-exec `ack` sentinel, redirects logs at the shell level, and emits a
+        // completed/failed sentinel from the agent's exit code. waitForAssignmentHandshake
+        // checks the ack file; the reconciler trusts the completed/failed/heartbeat
+        // sentinels rather than the (untrustworthy) wrapper pid. When ackRoot/
+        // assignmentId are omitted, we keep the original direct-binary spawn.
         let child;
         if (useAckWrap) {
-            const ackRoot = options.ackRoot ?? options.worktreePath;
-            const ackDir = path.join(ackRoot, '.brainclaw', 'coordination', 'runtime', 'ack');
-            const ackPath = path.join(ackDir, `${options.assignmentId}.ack`);
-            fs.mkdirSync(ackDir, { recursive: true });
-            const ackStep = isWin32
-                ? `type nul > "${ackPath}"`
-                : `touch "${ackPath}"`;
-            const wrappedCmd = `${ackStep} && ${invoke.bashCommand}`;
+            const signalRoot = options.ackRoot ?? options.worktreePath;
+            ensureRuntimeDirs(signalRoot);
+            const wrappedCmd = buildAckWrapCommand(invoke.bashCommand, {
+                ackPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'ack'),
+                completedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'completed'),
+                failedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'failed'),
+                stdoutLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stdout'),
+                stderrLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stderr'),
+            }, isWin32);
             child = spawn(wrappedCmd, [], {
                 detached: !isWin32,
                 shell: true,
@@ -163,18 +156,6 @@ export class CliExecutionAdapter {
             child.stdin.end();
         }
         child.unref();
-        // Close the parent's copies of the log file descriptors. The child has its
-        // own dup'd copies and will keep writing to them after we return.
-        if (logFds) {
-            try {
-                fs.closeSync(logFds.stdout);
-            }
-            catch { /* best-effort */ }
-            try {
-                fs.closeSync(logFds.stderr);
-            }
-            catch { /* best-effort */ }
-        }
         const pid = child.pid;
         if (!pid) {
             throw new Error(`Failed to spawn agent ${options.agent}: no PID returned`);

package/dist/core/execution.js

@@ -8,8 +8,8 @@
  * @module
  */
 import fs from 'node:fs';
-import path from 'node:path';
-import { getCapabilityProfile } from './agent-capability.js';
+import { resolveConcurrencyLimit, resolveResourceKey } from './agent-capability.js';
+import { getRuntimeSignalPath } from './runtime-signals.js';
 import { appendAuditEntry } from './audit.js';
 import { loadAllSessions } from './identity.js';
 import { loadConfig } from './config.js';
@@ -30,7 +30,7 @@ function sleep(ms) {
  * spawn anyway).
  */
 export function getAssignmentAckPath(cwd, assignmentId) {
-    return path.join(cwd, '.brainclaw', 'coordination', 'runtime', 'ack', `${assignmentId}.ack`);
+    return getRuntimeSignalPath(cwd, assignmentId, 'ack');
 }
 function isAssignmentAcked(assignmentId, cwd) {
     // Fast path: the brief-ack sentinel was written by the worker shell.
@@ -73,9 +73,13 @@ export function checkActiveInstance(agentName, cwd) {
     catch { /* use default */ }
     const SESSION_STALE_MS = parseDurationMs(ttlStr);
     const now = Date.now();
+    // pln#520 step 3: pool active sessions by host-binary resource so all
+    // identities of one binary (e.g. claude-code + claude-sonnet → `claude`)
+    // count together against a shared cap.
+    const targetResource = resolveResourceKey(agentName);
     const activeSessions = [];
     for (const session of sessions) {
-        if (session.agent !== agentName)
+        if (resolveResourceKey(session.agent) !== targetResource)
             continue;
         const lastSeen = new Date(session.last_seen_at).getTime();
         if (isNaN(lastSeen))
@@ -84,18 +88,20 @@ export function checkActiveInstance(agentName, cwd) {
             activeSessions.push(session.session_id);
         }
     }
-    const profile = getCapabilityProfile(agentName);
-    const maxAllowed = profile?.max_concurrent_tasks ?? 1;
+    // Limit resolved from the chain (default unlimited for parallelizable CLI
+    // agents; structural floor for non-spawnable IDE agents). Infinity → no cap.
+    const maxAllowed = resolveConcurrencyLimit(agentName);
     const activeCount = activeSessions.length;
     const canSpawnMore = activeCount < maxAllowed;
+    const capLabel = Number.isFinite(maxAllowed) ? String(maxAllowed) : '∞';
     return {
         active: !canSpawnMore, // backward compat: active=true means "cannot spawn more"
         canSpawnMore,
         activeCount,
         maxAllowed,
         reason: canSpawnMore
-            ? `Agent ${agentName} has capacity (${activeCount}/${maxAllowed} slots used)`
-            : `Agent ${agentName} at capacity (${activeCount}/${maxAllowed} slots used)`,
+            ? `Agent ${agentName} has capacity (${activeCount}/${capLabel} slots used)`
+            : `Agent ${agentName} at capacity (${activeCount}/${capLabel} slots used)`,
         activeSessions,
     };
 }

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() {
@@ -382,21 +382,22 @@ function renderAvailableTools() {
         '- `bclaw_remove(entity, id, purge?)` — soft-delete (or purge)',
         '- `bclaw_transition(entity, id, to)` — change status (e.g. plan todo→in_progress→done)',
         '',
-        'Entities supported by the grammar: plan, decision, constraint, trap, handoff, runtime_note, candidate, claim, action, assignment, agent_run.',
+        'Entities supported by the grammar: plan, decision, constraint, trap, handoff, runtime_note, candidate, sequence, claim, action, assignment, agent_run.',
         '',
         '**Cross-project access (pln#359):** every canonical-grammar call, `bclaw_context`, and `bclaw_coordinate` accept an optional `project: <name>` argument that routes the operation to a linked project (cross_project_links from `brainclaw link list` OR a workspace store-chain child). Identity is sourced from the caller; writes + audit land in the target. Unknown project names throw — no silent fallback. The CLI exposes the same as `--project <name>` (mutually exclusive with `--cwd`). Example: `bclaw_get(entity="trap", id="trp#36", project="brainclaw-site")`. Cross-project `bclaw_coordinate` is inbox-only — auto-spawn is force-disabled because the spawn cwd / worktree are tied to the target repo; the target agent picks the brief up async via its own `bclaw_work`.',
         '',
         '**Session + claims:** `bclaw_session_start`, `bclaw_session_end`, `bclaw_claim`, `bclaw_release_claim`',
         '**Plan steps:** `bclaw_add_step`, `bclaw_complete_step`, `bclaw_update_step`, `bclaw_delete_step`',
+        '**Sequences:** `bclaw_list_sequences`, `bclaw_create_sequence`, `bclaw_update_sequence`, `bclaw_delete_sequence` — create/activate ordered lanes for parallel dispatch. Item shape: `{ planId, stepId?, rank, hard_after?, soft_after?, lane?, scope_hint?, rationale? }`.',
         '**Inbox + handoffs:** `bclaw_read_inbox`, `bclaw_ack_message`, `bclaw_send_message`, `bclaw_correct_handoff`',
         '**Notes + search:** `bclaw_write_note`, `bclaw_quick_capture`, `bclaw_search`',
         '**Escalation (orchestrator path):**',
         '- Review / consult / assign another agent → `bclaw_coordinate(intent=review|consult|assign)` (use `open_loop=true` on review to also dispatch the reviewer turn)',
-        '- Parallel execute across a sequence\'s lanes → `bclaw_dispatch(intent=execute)`',
+        '- Parallel execute across a sequence\'s lanes → create/update an active sequence, then `bclaw_dispatch(intent=analysis)` and `bclaw_dispatch(intent=execute)`',
         '- Drive your turn in an already-opened loop → `bclaw_loop(intent=turn|complete_turn|advance|close)`',
         '**Setup + navigation:** `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`',
         '',
-        'Legacy per-entity tools (`bclaw_list_plans`, `bclaw_accept`, `bclaw_get_context`, `bclaw_dispatch_review`, …) were removed from the catalog at v1.0 — direct calls still succeed as a migration escape hatch but emit a redirect warning. See `docs/integrations/mcp.md` + `docs/concepts/mcp-governance.md` for the full catalog and stability contract; raw MCP clients can request advanced tools with `tools/list` params `{ catalog: "all" }`.',
+        'Legacy per-entity tools (`bclaw_list_plans`, `bclaw_accept`, `bclaw_get_context`, `bclaw_dispatch_review`, …) were removed from the catalog at v1.0 — direct calls still succeed as a migration escape hatch but emit a redirect warning. See `docs/integrations/mcp.md` + `docs/concepts/mcp-governance.md` for the full catalog and stability contract.',
     ].join('\n');
 }
 // ─── Live section renderers ─────────────────────────────────────────────────