brainclaw 1.13.0 → 1.15.0

package/dist/commands/harvest.js

@@ -21,13 +21,19 @@ import { memoryExists } from '../core/io.js';
 import { loadAssignment, transitionAssignment } from '../core/assignments.js';
 import { loadClaim, releaseClaimsCascade, logCascadeReleaseResult } from '../core/claims.js';
 import { getCapabilityProfile, dispatchCanCommit } from '../core/agent-capability.js';
-import { commitWorktreeOnBehalf, worktreesBaseDir } from '../core/worktree.js';
+import { commitWorktreeOnBehalf, worktreesBaseDir, resolveGitToplevel } from '../core/worktree.js';
 /**
  * Auto-detect all worktree directories under the brainclaw-managed base dir.
  * Returns subdirectories that exist on disk (may or may not have an inbox).
  */
 function autoDetectWorktreePaths(cwd) {
-    const base = worktreesBaseDir(cwd);
+    // Codex review of PR #49 (MED): createWorktree now writes in-tree worktrees
+    // under the git-TOPLEVEL hash (pln#614), so the scan base must resolve the
+    // toplevel too — otherwise `harvest --all` / candidates from an in-tree
+    // project subdir scan the stale subdir hash and miss every lane result. Only
+    // the scan base is toplevel-resolved; .brainclaw store reads/writes elsewhere
+    // keep the original project cwd.
+    const base = worktreesBaseDir(resolveGitToplevel(cwd));
     if (!fs.existsSync(base))
         return [];
     return fs.readdirSync(base, { withFileTypes: true })

package/dist/commands/mcp.js

@@ -9,6 +9,10 @@ import { generatedSchemas } from './mcp-schemas.generated.js';
 import { getTriggeredItems, renderTriggeredItems } from '../core/lifecycle.js';
 import { resolveCrossProjectLinks, resolveCrossProjectWritableTarget, resolveProjectCwd, writeCrossProjectSignal } from '../core/cross-project.js';
 import { buildContext, renderContextMarkdown, renderContextPromptTemplate, renderContextBriefing } from '../core/context.js';
+import { ageStaleWarnings, ageWorkflowHints, loadServeRegistry } from '../core/hint-aging.js';
+import { loadHygienePolicy } from '../core/hygiene-policy.js';
+import { sweepAssignmentsAtReadPath, selectReadPathSweepCandidates } from '../core/assignment-sweeper.js';
+import { loadAssignment } from '../core/assignments.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, readDiskBrainclawVersion, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
@@ -23,7 +27,7 @@ import { ENTITY_REGISTRY } from '../core/entity-registry.js';
 import { generateClaimId, listClaims, loadClaim, saveClaim, createCoordinatorClaim, adoptClaimSession, attachAssignmentMessageToClaim, linkClaimToAssignment, releaseClaimWithCascade } from '../core/claims.js';
 import { createSequence, updateSequence, deleteSequence } from '../core/sequence.js';
 import { assertCrossProjectBoundary, checkPolicy } from '../core/policy.js';
-import { createWorktree as coreCreateWorktree } from '../core/worktree.js';
+import { createWorktree as coreCreateWorktree, sanitizeBranchComponent } from '../core/worktree.js';
 import { createRuntimeNote } from './runtime-note.js';
 import { createCandidateFromInput } from './reflect.js';
 import { acceptCandidate } from './accept.js';
@@ -52,7 +56,7 @@ import { deleteMemoryItem, updateMemoryItem } from '../core/operations/memory-mu
 import { assessMemoryPressure, buildCompactionTemplate, applyCompaction } from '../core/gc-semantic.js';
 import { WorkRequestSchema, CoordinateRequestSchema } from '../core/facade-schema.js';
 import { codeMapWorkSection, codeMapRefreshNextActions } from '../core/code-map/work-section.js';
-import { getSpawnableAgents, getCapabilityProfile, buildInvokeCommand, validateAgentForDispatch } from '../core/agent-capability.js';
+import { getSpawnableAgents, getCapabilityProfile, buildInvokeCommand, validateAgentForDispatch, resolveModel } from '../core/agent-capability.js';
 import { attemptExecution } from '../core/execution.js';
 import { createAgentRun, transitionAgentRun } from '../core/agentruns.js';
 import { sweepDeadPidRunningAgentRunsAtRead } from '../core/agentrun-reconciler.js';
@@ -516,6 +520,7 @@ const MCP_WRITE_TOOLS = [
                 agents: { type: 'array', items: { type: 'string' }, description: 'Only dispatch to these agents. Default: all available.' },
                 lanes: { type: 'array', items: { type: 'string' }, description: 'Only dispatch items in these lanes. Also used by intent=analysis.' },
                 maxAssignments: { type: 'number', description: 'Max assignments to make (default: all ready). intent=execute only.' },
+                model: { type: 'string', description: 'Model to run on spawned workers, decoupled from agent identity (e.g. "sonnet", "gpt-5-codex"). Injected as `<model_flag> <model>` for agents that declare one (claude-code/codex/copilot); no-op for template-pinned identities. Mirrors the CLI `brainclaw dispatch run --model`. intent=execute only.' },
                 dryRun: { type: 'boolean', description: 'Preview without sending. Accepted by all intents.' },
                 autoExecute: { type: 'boolean', description: 'Attempt to spawn agents after delivery (default: true). intent=execute only.' },
                 // intent=review args (forwarded to bclaw_dispatch_review)
@@ -1047,6 +1052,7 @@ const MCP_WRITE_TOOLS = [
                 project: { type: 'string', description: 'Optional (pln#359 phase 1b): name of a linked project to dispatch into. When set, claim/assignment/message all land in the target project — the target agent picks the brief up async via its own bclaw_work. Auto-spawn is disabled in cross-project mode. Accepts cross_project_links and workspace store-chain children (see `brainclaw link list`).' },
                 allow_dirty: { type: 'boolean', description: 'Override the scope-aware dirty-working-tree guard (trp#371 Tier 2). The guard runs only for worktree-spawning intents (assign/review/reroute) and blocks only when uncommitted files overlap — or cannot be proven disjoint from — the dispatch scope (the worker spawns from HEAD and will not see them). `.brainclaw/` and `.git/` are always excluded. Set true to proceed anyway (the block is downgraded to a warning that lists the overlapping files). Boolean; the string "true"/"false" are also coerced.' },
                 ref: { type: 'string', description: 'Optional git ref (commit/branch/tag) for assign/review/reroute: the dispatched worker builds its worktree from this ref instead of HEAD. When set, uncommitted working-tree changes are intentionally out of scope and the dirty guard allows the dispatch. Ignored by consult/ideate/summarize (no worktree).' },
+                model: { type: 'string', description: 'Model to run on the spawned worker, decoupled from agent identity (e.g. "sonnet", "gpt-5-codex", "gpt-5.4"). Injected as `<model_flag> <model>` into the invoke command for agents that declare one (claude-code/codex/github-copilot); no-op for template-pinned pseudo-identities (e.g. claude-sonnet) or agents without a model_flag. Highest-priority link in the model resolution chain (override > lane > identity > default). Applies to intents that spawn a worker (assign/consult/review/reroute/ideate); ignored by summarize.' },
             },
             required: ['intent', 'task'],
         },
@@ -3538,7 +3544,9 @@ async function _executeMcpToolCallInner(payload) {
             // worktree:false) for an advisory-only lock with no worktree.
             const advisoryClaim = args.advisory === true || args.worktree === false;
             if (!advisoryClaim) {
-                const branchSlug = claimScope.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').slice(0, 48);
+                // Shared slug logic (trp#950): collision-resistant when the scope
+                // exceeds the branch-component cap, and identical to createCoordinatorClaim.
+                const branchSlug = sanitizeBranchComponent(claimScope);
                 const worktreeBranch = args.worktreeBranch?.trim() || `feat/${branchSlug}`;
                 try {
                     worktreePath = coreCreateWorktree(claimCwd, worktreeBranch, {
@@ -3604,7 +3612,7 @@ async function _executeMcpToolCallInner(payload) {
                     const { execSync } = await import('node:child_process');
                     const branch = execSync('git branch --show-current', { cwd: claimCwd, encoding: 'utf-8' }).trim();
                     if (branch === 'master' || branch === 'main') {
-                        const branchSlug = claimScope.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').slice(0, 48);
+                        const branchSlug = sanitizeBranchComponent(claimScope);
                         branchWarn = `\n⚠️ You are on ${branch}. Create a feature branch before editing: git checkout -b feat/${branchSlug}`;
                     }
                 }
@@ -4044,6 +4052,7 @@ async function _executeMcpToolCallInner(payload) {
                     dispatcherAgentId: resolved.identity.agent_id,
                     sessionId: connectionSessionId,
                     autoExecute: args.autoExecute,
+                    model: args.model,
                 }, cwd);
                 if (!result) {
                     return { response: createToolErrorResponse('operation_error', 'No active sequence found. Create a sequence first.') };
@@ -5095,6 +5104,45 @@ async function _executeMcpToolCallInner(payload) {
                     }
                 }
             }
+            let stalePostAging;
+            let staleAggregate;
+            let hintsPostAging;
+            let hintsAggregate;
+            if (contextResult) {
+                try {
+                    const policy = loadHygienePolicy(targetCwd);
+                    if (!policy.disabled) {
+                        // Filter candidates from the projection (no extra reads) — only
+                        // assignments whose surfaced last_heartbeat_at is old enough to
+                        // possibly cross a family TTL. Zero read overhead when the open
+                        // work is fresh (the common case).
+                        const openAssignments = contextResult.open_work?.active_assignments ?? [];
+                        // Codex PR#48 finding 3 (pln#578 guardrail): select candidate ids
+                        // from the already-surfaced projection — created/terminal rows are
+                        // dropped BEFORE any full loadAssignment, so a healthy store costs
+                        // zero extra file reads. Selection logic is unit-tested in
+                        // selectReadPathSweepCandidates.
+                        const candidateIds = selectReadPathSweepCandidates(openAssignments, policy, Date.now());
+                        if (candidateIds.length > 0) {
+                            const full = candidateIds
+                                .map((id) => loadAssignment(id, targetCwd))
+                                .filter((a) => a !== undefined);
+                            sweepAssignmentsAtReadPath(full, targetCwd, {
+                                actor: 'bclaw_work-readpath',
+                                policy,
+                            });
+                        }
+                        const registry = loadServeRegistry(targetCwd);
+                        const aged = ageStaleWarnings(contextResult.stale_warnings ?? [], targetCwd, { policy, registry });
+                        stalePostAging = aged.warnings;
+                        staleAggregate = aged.aggregate;
+                        const agedHints = ageWorkflowHints(contextResult.workflow_hints ?? [], targetCwd, { policy, registry });
+                        hintsPostAging = agedHints.hints;
+                        hintsAggregate = agedHints.aggregate;
+                    }
+                }
+                catch { /* non-fatal — hygiene must never break bclaw_work */ }
+            }
             // Build the full context result, then compact it if requested.
             // Compact mode (default) strips the heavy ContextResult down to a
             // minimal summary that fits within MCP token limits (~25k chars).
@@ -5110,7 +5158,8 @@ async function _executeMcpToolCallInner(payload) {
                     status: item.extra ?? 'unknown',
                     plan_id: item.plan_id,
                 }));
-                const staleTop3 = (contextResult.stale_warnings ?? []).slice(0, 3).map((w) => ({
+                const stalePool = stalePostAging ?? contextResult.stale_warnings ?? [];
+                const staleTop3 = stalePool.slice(0, 3).map((w) => ({
                     id: w.id,
                     entity: w.entity,
                     text: w.text.slice(0, 80),
@@ -5134,6 +5183,7 @@ async function _executeMcpToolCallInner(payload) {
                             : {}),
                     }
                     : undefined;
+                const hintsPool = hintsPostAging ?? contextResult.workflow_hints ?? [];
                 resultPayload = {
                     context_schema: contextResult.context_schema,
                     profile: contextResult.profile,
@@ -5142,7 +5192,9 @@ async function _executeMcpToolCallInner(payload) {
                     context_diff: trimmedDiff ?? null,
                     plan_summary: planItems,
                     stale_warnings: staleTop3,
-                    workflow_hints: (contextResult.workflow_hints ?? []).slice(0, 3),
+                    ...(staleAggregate ? { stale_warnings_aggregate: staleAggregate } : {}),
+                    workflow_hints: hintsPool.slice(0, 3),
+                    ...(hintsAggregate ? { workflow_hints_aggregate: hintsAggregate } : {}),
                     claim_conflicts: contextResult.claim_conflicts ?? [],
                     open_work: contextResult.open_work ?? null,
                     _compact: true,
@@ -5580,6 +5632,15 @@ async function _executeMcpToolCallInner(payload) {
                 side_effects.push({ action: 'create', entity: 'message', id: msgResult.id });
                 const invoke = buildInvokeCommand(input.agent, input.text, {
                     mode: input.commandMode ?? 'worker',
+                    // pln#520/#606 — decouple model from agent identity. req.model is the
+                    // override link; when unset, resolveModel intentionally falls back to
+                    // the profile's default_model (the documented last link in the chain),
+                    // mirroring the dispatcher's resolveModel usage (dispatcher.ts) so
+                    // coordinate and dispatch spawn with the same model. No profile ships
+                    // a default_model today, so omitting model stays a no-op in practice
+                    // (gpt-5.6-luna review). Flows to both the manual commandHint and the
+                    // auto-spawn path (runCoordinateExecution reuses this invoke).
+                    model: resolveModel(input.agent, { override: req.model }),
                 });
                 // Build env prefix for claim routing — centralised in
                 // execution-profile.ts:buildClaimEnvPrefix as of pln#496 step

package/dist/commands/session-start.js

@@ -16,7 +16,9 @@ import { releaseStaleClaimsFromOtherAgents } from '../core/claims.js';
 import { SessionSnapshotSchema } from '../core/schema.js';
 import { auditLocalAgentWorkspaceFiles } from '../core/agent-files.js';
 import { buildAgentInventory, loadAgentInventory, saveAgentInventory, diffInventory } from '../core/agent-inventory.js';
-import { checkMemoryPressure, enforceRuntimeNoteRetention } from '../core/gc-semantic.js';
+import { checkMemoryPressure, enforceRuntimeNoteRetention, parkClosedAutoHandoffs } from '../core/gc-semantic.js';
+import { sweepAssignments } from '../core/assignment-sweeper.js';
+import { loadHygienePolicy } from '../core/hygiene-policy.js';
 import { maybeCreateCheckpoint } from '../core/events/checkpoint.js';
 import { pullSignalsFromLinkedProjects, markSignalProcessed } from '../core/federation-transport.js';
 import { pullSignalsFromCloud, isCloudSyncEnabled } from '../core/federation-cloud.js';
@@ -207,6 +209,19 @@ export async function startSession(options = {}) {
             enforceRuntimeNoteRetention({ cwd: options.cwd });
         }
         catch { /* non-fatal — retention sweep must never block session start */ }
+        // pln#602 — coordination hygiene pass. Converge orphan offered/accepted
+        // assignments (workers that died without a self-report — fable-audit-2026-07
+        // witnesses) and park closed auto-generated handoffs so bclaw_work stops
+        // serving debris. Runs at session-start ONLY (not on the hot read path);
+        // opt-out via config.hygiene.disabled honoured through the policy load.
+        try {
+            const policy = loadHygienePolicy(options.cwd);
+            if (!policy.disabled) {
+                sweepAssignments(options.cwd, { actor: 'session-start', policy });
+                parkClosedAutoHandoffs(options.cwd ?? process.cwd(), Math.floor(policy.handoff_closed_ttl_ms / (24 * 60 * 60 * 1000)));
+            }
+        }
+        catch { /* non-fatal — hygiene sweep must never block session start */ }
         // pln#566 Inc0 — keep a recent journal-derived checkpoint available off the
         // hot path so the (capability-gated, OFF by default) checkpointRead read
         // path has something to serve once enabled. Gated by a growth threshold so

package/dist/core/agent-registry.js

@@ -140,8 +140,17 @@ function ensureParentDir(filepath) {
         fs.mkdirSync(dir, { recursive: true });
     }
 }
-function fingerprintPublicKey(publicKey) {
-    return crypto.createHash('sha256').update(publicKey).digest('hex');
+/**
+ * Canonical Ed25519 public-key fingerprint (pln#101): sha256 over the PEM with
+ * carriage returns stripped and surrounding whitespace trimmed, so a trailing
+ * newline or CRLF (e.g. introduced by copy-paste through the cloud UI) does NOT
+ * change the fingerprint. The cloud computes the same canonical value — see
+ * brainclaw-cloud/src/handlers/agents.ts fingerprintPem — so a local↔remote
+ * match is a reliable proof of the same key regardless of PEM formatting.
+ */
+export function fingerprintPublicKeyPem(publicKeyPem) {
+    const canonical = publicKeyPem.replace(/\r/g, '').trim();
+    return crypto.createHash('sha256').update(canonical).digest('hex');
 }
 function buildIdentityKey(agentId, env = process.env, forceRegenerate = false) {
     migrateLegacyAgentKey(agentId, env);
@@ -168,10 +177,49 @@ function buildIdentityKey(agentId, env = process.env, forceRegenerate = false) {
     return {
         algorithm: 'ed25519',
         public_key: publicKeyPem,
-        fingerprint: fingerprintPublicKey(publicKeyPem),
+        fingerprint: fingerprintPublicKeyPem(publicKeyPem),
         created_at: createdAt,
     };
 }
+/**
+ * Load an agent's Ed25519 signing material for cloud request signing (pln#100).
+ *
+ * Reads the private key from the neutral key store (~/.brainclaw/keys/),
+ * migrating from the legacy CODEX_HOME location if needed, and derives the SPKI
+ * public-key PEM plus its fingerprint — the same sha256(pem) the cloud stores as
+ * agents.key_fingerprint, so a local↔remote fingerprint match is a byte-for-byte
+ * proof of the same key. Returns undefined when no key has been generated yet:
+ * signing NEVER silently mints a key (the public key must be registered with the
+ * cloud first). Use registerAgentIdentity({ generateFingerprint: true }) to mint one.
+ */
+export function loadAgentSigningKey(agentId, env = process.env) {
+    migrateLegacyAgentKey(agentId, env);
+    const filepath = agentKeyPath(agentId);
+    if (!fs.existsSync(filepath))
+        return undefined;
+    const privateKeyPem = fs.readFileSync(filepath, 'utf-8');
+    const privateKey = crypto.createPrivateKey(privateKeyPem);
+    // @types/node 26 dropped the KeyObject overload from createPublicKey's signature
+    // (see buildIdentityKey) — cast to a parameter type the .d.ts still accepts.
+    const publicKeyPem = crypto
+        .createPublicKey(privateKey)
+        .export({ type: 'spki', format: 'pem' })
+        .toString();
+    return { privateKeyPem, publicKeyPem, fingerprint: fingerprintPublicKeyPem(publicKeyPem) };
+}
+/**
+ * Ensure an agent has an Ed25519 signing key, WITHOUT rotating an existing one
+ * (pln#101). Generates the keypair on first call, returns the existing key on
+ * subsequent calls — so it is safe to run after the public key has been
+ * approved in the cloud (rotating would break the fingerprint match). Returns
+ * the SPKI public-key PEM + its sha256(pem) fingerprint.
+ */
+export function ensureAgentSigningKey(agentId, env = process.env) {
+    const key = buildIdentityKey(agentId, env, false);
+    if (!key)
+        throw new Error(`Failed to derive signing key for agent ${agentId}`);
+    return { publicKeyPem: key.public_key, fingerprint: key.fingerprint };
+}
 function withIdentityKey(agent, env = process.env, forceRegenerate = false) {
     return {
         ...agent,

package/dist/core/assignment-sweeper.js

@@ -16,6 +16,7 @@
 import { spawnSync } from 'node:child_process';
 import { listAssignments, transitionAssignment } from './assignments.js';
 import { signalExists, readHeartbeat, latestActivityMs } from './runtime-signals.js';
+import { DEFAULT_HYGIENE_POLICY } from './hygiene-policy.js';
 function lastCommitAgeMs(worktreePath, nowMs) {
     if (!worktreePath)
         return undefined;
@@ -104,28 +105,60 @@ function collectImplicitEvidence(assignment, cwd, nowMs, sinceMs, freshTtlMs) {
  * @param options.actor - Actor name for audit trail (default: 'sweeper')
  */
 export function sweepAssignments(cwd, options) {
+    return sweepAssignmentsFromList(listAssignments(cwd), cwd, options);
+}
+/**
+ * Read-path variant: sweep only the assignments the caller ALREADY loaded
+ * (typically open_work.active_assignments). No `listAssignments` call, so no
+ * additional store scan on the hot bclaw_work path (pln#602 perf guardrail
+ * per the pln#578 read-path optimisation). Use `sweepAssignmentsFromList`
+ * with a bounded slice when a full pass would violate the budget.
+ *
+ * @param assignments - pre-loaded assignments to consider (only non-terminal ones matter)
+ * @param cwd - project root
+ * @param options.nowMs - Override current time for testing
+ * @param options.actor - Actor for the audit trail (default: 'sweeper-readpath')
+ * @param options.policy - Family-level TTL/policy overrides
+ */
+export function sweepAssignmentsFromList(assignments, cwd, options) {
+    const policy = options?.policy;
+    if (policy?.disabled) {
+        return { timed_out: [], expired: [], implicitly_advanced: [] };
+    }
     const now = options?.nowMs ?? Date.now();
     const actor = options?.actor ?? 'sweeper';
     const result = { timed_out: [], expired: [], implicitly_advanced: [] };
-    const all = listAssignments(cwd);
-    for (const assignment of all) {
+    for (const assignment of assignments) {
+        // pln#602 / Codex PR#48 finding 2: when a hygiene `policy` is supplied
+        // (session-start full sweep, bclaw_work read-path), the age comparison,
+        // the implicit-evidence freshness window, AND the status_reason MUST use
+        // the family TTLs (offered 3d / accepted 1d / started 1d by default), NOT
+        // the assignment's embedded heartbeat_ttl_ms/acceptance_ttl_ms (~30/15min).
+        // Otherwise a 20-min offered assignment that `doctor --hygiene` does not
+        // list as a candidate could still be expired here — the exact incoherence
+        // Codex flagged. Without a policy (the dispatcher convergence sweep,
+        // dispatcher.ts), fall back to the embedded TTLs so short-window dispatch
+        // convergence is unchanged.
+        const startedTtl = policy?.assignment_started_ttl_ms ?? assignment.heartbeat_ttl_ms;
+        const acceptedTtl = policy?.assignment_accepted_ttl_ms ?? assignment.acceptance_ttl_ms;
+        const offeredTtl = policy?.assignment_offered_ttl_ms ?? assignment.acceptance_ttl_ms;
         // Check started assignments for heartbeat timeout
         if (assignment.status === 'started') {
             const lastBeat = assignment.last_heartbeat_at ?? assignment.started_at;
             if (!lastBeat)
                 continue;
             const ageMs = now - new Date(lastBeat).getTime();
-            if (ageMs > assignment.heartbeat_ttl_ms) {
+            if (ageMs > startedTtl) {
                 // can_948acfd6: a worker without MCP cannot bump last_heartbeat_at —
                 // its file evidence is the heartbeat. Fresh file activity vetoes the
                 // administrative timeout.
                 const sinceMs = new Date(assignment.started_at ?? assignment.created_at).getTime();
-                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, assignment.heartbeat_ttl_ms);
+                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, startedTtl);
                 if (evidence.fresh)
                     continue;
                 try {
                     transitionAssignment(assignment.id, 'timed_out', {
-                        status_reason: `No heartbeat for ${Math.round(ageMs / 60_000)} minutes (TTL: ${Math.round(assignment.heartbeat_ttl_ms / 60_000)}min); implicit evidence: ${evidence.description}`,
+                        status_reason: `No heartbeat for ${Math.round(ageMs / 60_000)} minutes (TTL: ${Math.round(startedTtl / 60_000)}min); implicit evidence: ${evidence.description}`,
                         actor,
                     }, cwd);
                     result.timed_out.push({ assignment_id: assignment.id, agent: assignment.agent, age_ms: ageMs });
@@ -139,10 +172,12 @@ export function sweepAssignments(cwd, options) {
             if (!acceptedAt)
                 continue;
             const ageMs = now - new Date(acceptedAt).getTime();
-            // Use acceptance_ttl for accepted→timed_out (same window: agent should start quickly after accepting)
-            if (ageMs > assignment.acceptance_ttl_ms) {
+            // Use the accepted-family TTL for accepted→timed_out (agent should start
+            // soon after accepting; family default 1d, or embedded acceptance_ttl_ms
+            // for the policy-less convergence sweep).
+            if (ageMs > acceptedTtl) {
                 const sinceMs = new Date(acceptedAt).getTime();
-                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, assignment.acceptance_ttl_ms);
+                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, acceptedTtl);
                 if (evidence.fresh) {
                     // Working without MCP — record the implicit start so the FSM matches reality.
                     try {
@@ -171,13 +206,13 @@ export function sweepAssignments(cwd, options) {
             if (!offeredAt)
                 continue;
             const ageMs = now - new Date(offeredAt).getTime();
-            if (ageMs > assignment.acceptance_ttl_ms) {
+            if (ageMs > offeredTtl) {
                 // can_948acfd6: ANY worker evidence (ack sentinel touched pre-exec,
                 // heartbeat written, files edited, commit landed) is an implicit
                 // acceptance — the worker just couldn't say so via MCP. Expiring it
                 // is the false-administrative-death observed three times in sprint 1.
                 const sinceMs = new Date(offeredAt).getTime();
-                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, assignment.acceptance_ttl_ms);
+                const evidence = collectImplicitEvidence(assignment, cwd, now, sinceMs, offeredTtl);
                 if (evidence.any) {
                     try {
                         transitionAssignment(assignment.id, 'accepted', {
@@ -191,7 +226,7 @@ export function sweepAssignments(cwd, options) {
                 }
                 try {
                     transitionAssignment(assignment.id, 'expired', {
-                        status_reason: `Not accepted within ${Math.round(ageMs / 60_000)} minutes (TTL: ${Math.round(assignment.acceptance_ttl_ms / 60_000)}min); no implicit evidence`,
+                        status_reason: `Not accepted within ${Math.round(ageMs / 60_000)} minutes (TTL: ${Math.round(offeredTtl / 60_000)}min); no implicit evidence`,
                         actor,
                     }, cwd);
                     result.expired.push({ assignment_id: assignment.id, agent: assignment.agent, age_ms: ageMs });
@@ -202,4 +237,50 @@ export function sweepAssignments(cwd, options) {
     }
     return result;
 }
+/**
+ * Pure candidate selection for the bclaw_work read-path sweep (Codex PR#48
+ * finding 3, pln#578 guardrail). Given ONLY the in-memory projections that
+ * buildContext already surfaced, return the ids worth a full loadAssignment:
+ *   - status must be sweepable (offered/accepted/started) — created/terminal
+ *     rows can never transition and are dropped BEFORE any file read, so a
+ *     healthy store full of `created` assignments costs zero extra I/O;
+ *   - among those, only rows whose surfaced heartbeat is older than the
+ *     smallest family TTL (or that carry no heartbeat) are suspicious;
+ *   - capped at read_path_sweep_budget.
+ * Extracted so the hot-path zero-read guarantee is unit-testable without the
+ * MCP handler.
+ */
+export function selectReadPathSweepCandidates(projections, policy, nowMs) {
+    if (policy.disabled)
+        return [];
+    const minTtl = Math.min(policy.assignment_offered_ttl_ms, policy.assignment_accepted_ttl_ms, policy.assignment_started_ttl_ms);
+    return projections
+        .filter((a) => {
+        if (a.status !== 'offered' && a.status !== 'accepted' && a.status !== 'started')
+            return false;
+        const beat = a.last_heartbeat_at;
+        if (!beat)
+            return true;
+        return nowMs - new Date(beat).getTime() > minTtl;
+    })
+        .slice(0, policy.read_path_sweep_budget)
+        .map((a) => a.id);
+}
+export function sweepAssignmentsAtReadPath(assignments, cwd, options) {
+    const policy = options?.policy ?? DEFAULT_HYGIENE_POLICY;
+    if (policy.disabled) {
+        return { timed_out: [], expired: [], implicitly_advanced: [] };
+    }
+    const budget = policy.read_path_sweep_budget;
+    // Prefer offered/accepted (the empirical debris class); the sweep is a no-op
+    // for terminal statuses so filtering is a perf hygiene, not correctness.
+    const eligible = assignments
+        .filter((a) => a.status === 'offered' || a.status === 'accepted' || a.status === 'started')
+        .slice(0, budget);
+    return sweepAssignmentsFromList(eligible, cwd, {
+        ...options,
+        actor: options?.actor ?? 'sweeper-readpath',
+        policy,
+    });
+}
 //# sourceMappingURL=assignment-sweeper.js.map

package/dist/core/claims.js

@@ -14,6 +14,7 @@ import { loadSessionById } from './identity.js';
 import { loadState, persistState } from './state.js';
 import { createRuntimeEvent } from './events.js';
 import { emitRegistryPostImage, registryFaultPoint } from './events/registry-post-image.js';
+import { maybeEnqueueClaimTransition, isFederationEnqueueActive } from './federation-outbox.js';
 /** Parse duration string like '4h', '30m' to ms. */
 function parseTtl(value) {
     const match = /^(\d+)([mhd])$/i.exec(value.trim());
@@ -69,9 +70,26 @@ function saveClaimUnlocked(claim, cwd, options) {
     // pln#568 (I2): journal the post-image BEFORE the projection write, so a
     // crash can only leave the journal ahead of the projection, never behind.
     const created = !store.exists(parsed.id);
+    // Federation (pln#101): capture the PREVIOUS status BEFORE the write so we can
+    // diff it after (create or active↔terminal transition ⇒ enqueue for cloud
+    // sync). Only pay the prev-load when federation is actually active; this whole
+    // block runs under the store mutation mutex, which serializes rev reservation.
+    const fedActive = isFederationEnqueueActive(cwd, options?.federation?.suppressEnqueue);
+    let fedPrevStatus;
+    if (fedActive) {
+        try {
+            fedPrevStatus = loadClaimFromAnyDir(parsed.id, cwd).status;
+        }
+        catch {
+            fedPrevStatus = undefined;
+        }
+    }
     emitRegistryPostImage('claim', parsed, { created, agent: parsed.agent, agent_id: parsed.agent_id, session_id: parsed.session_id, cwd });
     registryFaultPoint('after_registry_journal');
     store.save(parsed);
+    if (fedActive) {
+        maybeEnqueueClaimTransition(parsed, fedPrevStatus, fedPrevStatus === undefined, cwd, options?.federation?.suppressEnqueue);
+    }
     const writeDir = claimsDir(cwd, 'write');
     for (const dirPath of claimDirs(cwd)) {
         if (dirPath === writeDir)

package/dist/core/facade-schema.js

@@ -109,6 +109,18 @@ export const CoordinateRequestSchema = z.object({
      * rejected as `preset_kind_mismatch`.
      */
     preset: z.string().min(1).optional(),
+    /**
+     * pln#520 step 3 / pln#606 — model to run on the spawned worker, decoupled
+     * from agent identity. Passed through to `resolveModel({ override })` and
+     * injected as `<model_flag> <model>` into the invoke command for agents that
+     * declare a `model_flag` (e.g. `claude-code --model sonnet`, `codex exec
+     * --model …`, `copilot --model …`). No-op for agents whose template already
+     * pins a model (e.g. the `claude-sonnet` pseudo-identity) or that declare no
+     * `model_flag`. Highest-priority link in the model resolution chain. Ignored
+     * by intents that don't spawn a worker (summarize). Mirrors the CLI
+     * `brainclaw dispatch run --model <name>` flag for CLI/MCP parity.
+     */
+    model: z.string().min(1).optional(),
 });
 export const FacadeArtifactSchema = z.object({
     type: z.string(),