brainclaw 1.7.0 → 1.7.2

package/dist/core/agentrun-reconciler.js

@@ -38,6 +38,7 @@ import { loadClaim } 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';
 // ── Constants ──────────────────────────────────────────────────────────────
 /**
  * Minimum age before a run is eligible for reconciliation. Below this, the
@@ -52,6 +53,11 @@ export const DEFAULT_HEALTH_CHECK_GRACE_MS = 60_000;
 export const DEFAULT_STALE_AFTER_MS = 30 * 60_000;
 export const DEFAULT_DEAD_PID_READ_SWEEP_AGE_MS = 5 * 60_000;
 export const DEFAULT_DEAD_PID_READ_SWEEP_LIMIT = 50;
+/**
+ * pln#520 step 1 — a heartbeat older than this (with no completion signal) means
+ * the worker reached its loop then went silent: `stalled`. Default 10 min.
+ */
+export const DEFAULT_HEARTBEAT_STALE_MS = 10 * 60_000;
 const TERMINAL_STATUSES = new Set([
     'completed', 'failed', 'cancelled', 'timed_out', 'interrupted',
 ]);
@@ -152,15 +158,51 @@ export function collectEvidence(run, cwd, options) {
     }
     catch { /* defensive */ }
     const process_alive = isProcessAlive(run.pid);
-    return { age_ms, has_post_start_commit, claim_released, assignment_completed, process_alive };
+    // pln#520 step 1 — sentinel evidence. Signals live under the project
+    // coordination dir (the dispatcher's ackRoot), which is `cwd` for the
+    // reconciler. Keyed by assignment_id.
+    const signalRoot = cwd ?? process.cwd();
+    let completed_signal = false;
+    let failed_signal = false;
+    let heartbeat_exists = false;
+    let heartbeat_age_ms;
+    try {
+        completed_signal = signalExists(signalRoot, run.assignment_id, 'completed');
+        failed_signal = signalExists(signalRoot, run.assignment_id, 'failed');
+        const hb = readHeartbeat(signalRoot, run.assignment_id);
+        heartbeat_exists = hb.exists;
+        if (hb.exists && hb.mtimeMs !== undefined)
+            heartbeat_age_ms = now - hb.mtimeMs;
+    }
+    catch { /* defensive */ }
+    return {
+        age_ms, has_post_start_commit, claim_released, assignment_completed, process_alive,
+        completed_signal, failed_signal, heartbeat_exists, heartbeat_age_ms,
+    };
 }
 function anyCompletionEvidence(evidence) {
-    return evidence.has_post_start_commit
+    return evidence.completed_signal
+        || evidence.has_post_start_commit
         || evidence.claim_released
         || evidence.assignment_completed;
 }
+/**
+ * pln#520 step 1 — a short tail of the captured stderr (or stdout) for
+ * failed_silent / stalled diagnostics, so the verdict carries the worker's
+ * last words instead of just a status code.
+ */
+function logTailSuffix(run, cwd) {
+    const root = cwd ?? process.cwd();
+    const tail = (readLogTail(root, run.assignment_id, 'stderr', 500).trim()
+        || readLogTail(root, run.assignment_id, 'stdout', 500).trim());
+    if (!tail)
+        return '';
+    return ` | log tail: ${tail.replace(/\s+/g, ' ').slice(0, 300)}`;
+}
 function describeEvidence(evidence) {
     const reasons = [];
+    if (evidence.completed_signal)
+        reasons.push('wrapper wrote completed sentinel');
     if (evidence.has_post_start_commit)
         reasons.push('post-start commit on worktree branch');
     if (evidence.claim_released)
@@ -231,6 +273,7 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
         const evidence = {
             age_ms: 0, has_post_start_commit: false, claim_released: false,
             assignment_completed: false, process_alive: undefined,
+            completed_signal: false, failed_signal: false, heartbeat_exists: false,
         };
         return {
             run_id: runId, action: 'no_op', reason: 'run not found', evidence,
@@ -280,18 +323,12 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
             };
         }
     }
-    // Failure inference: stale + dead process + no evidence.
-    if (evidence.age_ms >= stale && evidence.process_alive === false) {
+    // pln#520 step 1 — sentinel-based failure (fast + trustworthy, pid-independent).
+    const heartbeatStale = options.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+    const failHere = (reason) => {
         try {
-            transitionAgentRun(runId, 'failed', {
-                actor,
-                status_reason: 'silent_termination_no_evidence',
-            }, cwd);
-            return {
-                run_id: runId, action: 'inferred_failed',
-                reason: 'silent_termination_no_evidence',
-                evidence, previous_status, current_status: 'failed',
-            };
+            transitionAgentRun(runId, 'failed', { actor, status_reason: reason }, cwd);
+            return { run_id: runId, action: 'inferred_failed', reason, evidence, previous_status, current_status: 'failed' };
         }
         catch (err) {
             return {
@@ -300,6 +337,26 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
                 evidence, previous_status, current_status: run.status,
             };
         }
+    };
+    // `failed` sentinel — the wrapper saw a non-zero agent exit.
+    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.
+    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)}`);
+    }
+    // Fresh heartbeat → alive; trust it over the untrustworthy wrapper pid.
+    if (evidence.heartbeat_exists) {
+        return {
+            run_id: runId, action: 'no_op',
+            reason: `heartbeat fresh (${Math.round((evidence.heartbeat_age_ms ?? 0) / 1000)}s) — worker alive, pid untrusted`,
+            evidence, previous_status, current_status: run.status,
+        };
+    }
+    // Failure inference: stale + dead process + no evidence.
+    if (evidence.age_ms >= stale && evidence.process_alive === false) {
+        return failHere('silent_termination_no_evidence');
     }
     // Health-check window: past grace, not yet stale, no evidence either way.
     // Emit a non-mutating event so callers see the uncertainty without
@@ -339,6 +396,7 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
         const evidence = {
             age_ms: 0, has_post_start_commit: false, claim_released: false,
             assignment_completed: false, process_alive: undefined,
+            completed_signal: false, failed_signal: false, heartbeat_exists: false,
         };
         return {
             run_id: runId, action: 'no_op', reason: 'run not found', evidence,
@@ -352,19 +410,25 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
             evidence, previous_status: run.status, current_status: run.status,
         };
     }
-    if (evidence.process_alive !== false) {
-        return {
-            run_id: run.id, action: 'no_op',
-            reason: evidence.process_alive === true ? 'process alive' : 'pid liveness unknown',
-            evidence, previous_status: run.status, current_status: run.status,
-        };
-    }
-    // pid reads dead — but the tracked pid is NOT trustworthy (see doc above),
-    // so a bare dead pid NEVER cancels. Evidence of real work wins; otherwise
-    // surface the uncertainty non-destructively and leave the run `running` for
-    // reconcileAgentRun's stale-threshold path to fail it only after a fair,
-    // evidence-based delay.
     const actor = options.actor ?? 'reconciler';
+    const stale = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    const heartbeatStale = options.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+    const failRun = (reason) => {
+        try {
+            transitionAgentRun(run.id, 'failed', { actor, status_reason: reason }, cwd);
+            return { run_id: run.id, action: 'inferred_failed', reason, evidence, previous_status: run.status, current_status: 'failed' };
+        }
+        catch (err) {
+            return {
+                run_id: run.id, action: 'no_op',
+                reason: `failure transition rejected: ${err instanceof Error ? err.message : String(err)}`,
+                evidence, previous_status: run.status, current_status: run.status,
+            };
+        }
+    };
+    // ── pln#520 step 1: SENTINELS are authoritative, independent of the
+    // untrustworthy wrapper pid. Check them first. ──────────────────────────
+    // 1. Completion evidence (mechanical `completed` sentinel or work evidence).
     if (anyCompletionEvidence(evidence)) {
         try {
             transitionAgentRun(run.id, 'completed', {
@@ -385,33 +449,43 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
             };
         }
     }
-    // Stale + provably dead + still no evidence -> genuine silent failure. This
-    // MUST converge HERE: the canonical read path (entity-operations.ts) and the
-    // MCP pre-read sweep route `running` runs through this function, never
-    // through reconcileAgentRun, so deferring would leave a crashed run `running`
-    // forever (trp#292). The 30-min stale window — vs the immediate cancel before
-    // pln#520 — gives a worker behind an untrusted pid ample time to leave
-    // evidence first. Reported as `failed` (it died), not `cancelled`.
-    const stale = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    // 2. `failed` sentinel — the wrapper saw a non-zero agent exit. This is the
+    // FAST, TRUSTWORTHY failed_silent detector (vs the pid heuristic that caused
+    // can_f792cacd false negatives). Carries the captured log tail.
+    if (evidence.failed_signal) {
+        return failRun(`failed_silent: wrapper reported non-zero exit${logTailSuffix(run, cwd)}`);
+    }
+    // 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)}`);
+    }
+    // 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
+    // live, heartbeating worker just because its wrapper pid reads dead.
+    if (evidence.heartbeat_exists) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: `heartbeat fresh (${Math.round((evidence.heartbeat_age_ms ?? 0) / 1000)}s) — worker alive, pid untrusted`,
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+    // ── No sentinel, no heartbeat: fall back to the pid-conservative path. The
+    // wrapper writes completed/failed on any normal exit, so reaching here means
+    // the worker has not exited and never heartbeat. Do NOT fast-fail on a dead
+    // pid (it's the wrapper's, not the worker's). ──────────────────────────────
+    if (evidence.process_alive !== false) {
+        return {
+            run_id: run.id, action: 'no_op',
+            reason: evidence.process_alive === true ? 'process alive' : 'pid liveness unknown',
+            evidence, previous_status: run.status, current_status: run.status,
+        };
+    }
+    // pid dead + no sentinel + no heartbeat: only converge after the long stale
+    // window (trp#292 — must converge HERE since the read path never routes
+    // through reconcileAgentRun), giving an untrusted-pid worker ample time.
     if (evidence.age_ms >= stale) {
-        try {
-            transitionAgentRun(run.id, 'failed', {
-                actor,
-                status_reason: 'silent_termination_no_evidence',
-            }, cwd);
-            return {
-                run_id: run.id, action: 'inferred_failed',
-                reason: 'silent_termination_no_evidence',
-                evidence, previous_status: run.status, current_status: 'failed',
-            };
-        }
-        catch (err) {
-            return {
-                run_id: run.id, action: 'no_op',
-                reason: `failure transition rejected: ${err instanceof Error ? err.message : String(err)}`,
-                evidence, previous_status: run.status, current_status: run.status,
-            };
-        }
+        return failRun('silent_termination_no_evidence');
     }
     emitUnverifiedEvent(run, evidence, actor, cwd);
     return {
@@ -457,7 +531,7 @@ export function reconcileAllOpenRuns(cwd, filter = {}, options = {}) {
             catch {
                 results.push({
                     run_id: run.id, action: 'no_op', reason: 'reconcile threw — skipped',
-                    evidence: { age_ms: 0, has_post_start_commit: false, claim_released: false, assignment_completed: false, process_alive: undefined },
+                    evidence: { age_ms: 0, has_post_start_commit: false, claim_released: false, assignment_completed: false, process_alive: undefined, completed_signal: false, failed_signal: false, heartbeat_exists: false },
                     previous_status: run.status, current_status: run.status,
                 });
             }

package/dist/core/coordination.js

@@ -11,7 +11,7 @@ import { inferProjectFromTarget, loadInstructions, resolveInstructions } from '.
 import { buildReputationSummary, findAgentReputationSummary } from './reputation.js';
 import { listRuntimeNotes } from './runtime.js';
 import { loadState, persistState } from './state.js';
-import { getCapabilityProfile } from './agent-capability.js';
+import { resolveConcurrencyLimit, serializeConcurrencyLimit } from './agent-capability.js';
 import { loadAllSessions } from './identity.js';
 import { countActionable } from './messaging.js';
 import { listCandidates } from './candidates.js';
@@ -176,8 +176,7 @@ function buildOtherAgentsSummary(claims, notes, currentAgent, cwd) {
     for (const identity of listAgentIdentities(cwd)) {
         if (identity.agent_name === currentAgent)
             continue;
-        const profile = getCapabilityProfile(identity.agent_name);
-        const maxTasks = profile?.max_concurrent_tasks ?? 1;
+        const limit = serializeConcurrencyLimit(resolveConcurrencyLimit(identity.agent_name));
         agentMap.set(identity.agent_name, {
             name: identity.agent_name,
             trust_level: identity.trust_level ?? 'contributor',
@@ -185,23 +184,25 @@ function buildOtherAgentsSummary(claims, notes, currentAgent, cwd) {
             scopes: [],
             has_open_session: false,
             instance_count: sessionCounts.get(identity.agent_name) ?? 0,
-            max_tasks: maxTasks,
-            slots_remaining: maxTasks, // will be reduced when claims are counted
+            max_tasks: limit,
+            slots_remaining: limit, // will be reduced when claims are counted (null stays unlimited)
         });
     }
     // Enrich with active claims
     for (const claim of claims) {
         if (claim.agent === currentAgent)
             continue;
-        const profile = getCapabilityProfile(claim.agent);
-        const maxTasks = profile?.max_concurrent_tasks ?? 1;
+        const limit = serializeConcurrencyLimit(resolveConcurrencyLimit(claim.agent));
         const existing = agentMap.get(claim.agent) ?? {
             name: claim.agent, trust_level: 'contributor', claim_count: 0, scopes: [],
             has_open_session: false, instance_count: sessionCounts.get(claim.agent) ?? 0,
-            max_tasks: maxTasks, slots_remaining: maxTasks,
+            max_tasks: limit, slots_remaining: limit,
         };
         existing.claim_count++;
-        existing.slots_remaining = Math.max(0, existing.max_tasks - existing.claim_count);
+        // null max_tasks = unlimited → slots stay unlimited.
+        existing.slots_remaining = existing.max_tasks === null
+            ? null
+            : Math.max(0, existing.max_tasks - existing.claim_count);
         existing.scopes.push(claim.scope);
         if (!existing.last_active || claim.created_at > existing.last_active) {
             existing.last_active = claim.created_at;

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');
@@ -305,6 +344,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 +466,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 +487,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 +566,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 +628,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 +638,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 +684,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 +775,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