@monoes/monomindcli 2.13.0 → 2.14.1

package/dist/src/orgrt/session.js

@@ -12,10 +12,15 @@ import { StateDetector } from './state-detector.js';
  *  "boss appears hung". */
 const SILENT_SESSION_MS = 4 * 60_000;
 const CONTEXT_LIMIT_RE = /context.window.limit|context.length.exceeded|maximum.context/i;
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveRoleCostTier } from './cost-tier.js';
+import { expandRolePromptVars, promptVarsFor } from './prompt-vars.js';
 import { resolveProviderEnv, resolveRoleProvider } from './provider.js';
 import { resolveRoleGitEnforcement } from './role-sandbox.js';
 import { loadBuiltinRoleSkill } from './role-skills.js';
+import { mailRouteKey, ROLE_SESSION_KEY, resolveSessionScope, SessionLedger, } from './session-ledger.js';
 import { DEFAULT_CLAUDE_MODEL, VERCEL_PROVIDERS } from './vercel-providers.js';
 /**
  * Resolves the extra system-prompt block for a role: built-in archetype
@@ -189,6 +194,14 @@ endpointBriefing) {
         .filter(Boolean)
         .join('\n\n');
 }
+/** The system prompt one session of this role is built with. */
+function rolePromptFor(opts) {
+    return buildRolePrompt(expandRolePromptVars(opts.role, promptVarsFor(opts.orgRoot ?? opts.cwd)), (opts.def ?? { name: opts.org, goal: '' }), opts.def?.roles.map((r) => r.id) ?? [opts.role.id], opts.glossary, 
+    // D7: the loadout's text follows the role's own guidance. With no
+    // loadout this is exactly resolveRoleExtraGuidance(role), as before.
+    [resolveRoleExtraGuidance(opts.role), opts.loadout?.guidance].filter(Boolean).join('\n\n') ||
+        undefined, opts.onComplete ? endpointBriefingLines(opts.def) : undefined);
+}
 /**
  * Runs a role for the life of the org, transparently restarting the
  * underlying SDK session whenever it ends on its own (`maxTurns` reached)
@@ -248,23 +261,151 @@ async function runAgentSessionLoop(opts) {
     // SDK session id here (it must outlive individual runOneSession calls,
     // since resume continues the same billing session) and emit only deltas.
     const sessionCostTotals = new Map();
+    // ADR-O001 D1: modelUsage is cumulative per session exactly like
+    // total_cost_usd, so it needs the same prev-value map to become a delta.
+    const sessionTokenTotals = new Map();
+    // ADR-O001 D3. 'role' scope (the default) keeps the pre-D3 loop exactly: one
+    // model session for the role's life, resumed across maxTurns restarts via
+    // resumeSessionId. 'task' scope keys model sessions by the task a message
+    // belongs to: the process exits at a task boundary (or on idle) and the next
+    // one resumes that task's session from the ledger. Either way every session
+    // run is recorded with its session id before and after.
+    const scope = resolveSessionScope(opts.role, opts.def);
+    const idleExitMs = opts.def?.run_config
+        ?.session_idle_exit_ms;
+    const ledger = opts.sessionLedger ?? new SessionLedger();
+    const runtimeKey = opts.role.runtime ?? opts.def?.runtime ?? 'claude';
+    let taskKey = ROLE_SESSION_KEY;
+    // Why the next fresh session for a key is fresh, when the loop itself threw
+    // the record away (stale resume, turn-limit error) — recorded, not guessed.
+    const droppedBecause = new Map();
+    const staleTried = new Set();
+    // The options THIS session is built from — the role's own, except that a
+    // task-scoped session carries its task's loadout (D7).
+    let sessionOpts = opts;
+    let promptHash = '*';
+    // Task scope: which task last wrote to each correspondent, so their
+    // untagged reply goes back to that task's session (see mailRouteKey).
+    const correspondents = new Map();
     // Always run at least once: a mailbox can be closed with queued items still
     // pending (stream() drains the queue before honoring `closed`), which is a
     // normal, valid starting state - checking isClosed before the first run
     // would skip that drain entirely.
     while (true) {
+        // Opt-in only: keep the process DOWN until there is mail, instead of
+        // starting a query() that parks on an empty mailbox. waitForMessage()
+        // still returns true for a closed mailbox with queued items.
+        if (scope !== 'role' || idleExitMs !== undefined) {
+            if (!(await mailbox.waitForMessage()))
+                return;
+        }
+        let startReason;
+        if (scope === 'cold') {
+            // D6: nothing carries over — not a checkpointed session, not the last
+            // message's. Paying the cache miss here is the point.
+            resumeSessionId = undefined;
+            startReason = 'fresh-cold';
+        }
+        else if (scope === 'task') {
+            // An untagged message (mail, an answer, a continuation) belongs to the
+            // session the role is already in.
+            taskKey = mailRouteKey(mailbox.peek() ?? '', correspondents) ?? taskKey;
+            const key = taskKey;
+            sessionOpts = {
+                ...opts,
+                // D7: this task's session is built with this task's loadout.
+                ...(key !== ROLE_SESSION_KEY && opts.loadoutFor ? { loadout: opts.loadoutFor(key) } : {}),
+                // Mail sent from a task's session names the task in its subject, so
+                // the reader knows what it is about and a reply can find its way back.
+                deliver: (from, to, subject, body) => {
+                    if (key === ROLE_SESSION_KEY)
+                        return opts.deliver(from, to, subject, body);
+                    correspondents.set(to, key);
+                    const tagged = subject.includes('[task:') ? subject : `[task:${key}] ${subject}`;
+                    return opts.deliver(from, to, tagged, body);
+                },
+            };
+            promptHash = createHash('sha256')
+                .update(rolePromptFor(sessionOpts))
+                .digest('hex')
+                .slice(0, 16);
+            const pick = ledger.resumeFor({
+                role: opts.role.id,
+                runtime: runtimeKey,
+                taskKey,
+                cwd: opts.cwd,
+                promptHash,
+            });
+            resumeSessionId = pick.sessionId;
+            startReason =
+                pick.reason === 'fresh-no-record'
+                    ? (droppedBecause.get(taskKey) ?? pick.reason)
+                    : pick.reason;
+        }
+        else {
+            startReason = resumeSessionId ? 'resumed' : 'fresh-no-record';
+        }
+        const sessionKey = taskKey;
+        const streamOpts = scope === 'cold'
+            ? { stopBefore: () => true, idleExitMs }
+            : scope === 'task'
+                ? {
+                    stopBefore: (next) => {
+                        const k = mailRouteKey(next, correspondents);
+                        return k !== undefined && k !== sessionKey;
+                    },
+                    idleExitMs,
+                }
+                : idleExitMs !== undefined
+                    ? { idleExitMs }
+                    : undefined;
+        const sessionIdBefore = resumeSessionId;
+        const startedAt = Date.now();
+        const recordRun = (after, error) => {
+            const run = ledger.recordRun({
+                role: opts.role.id,
+                runtime: runtimeKey,
+                taskKey: sessionKey,
+                sessionIdBefore,
+                sessionIdAfter: after,
+                reason: startReason,
+                startedAt,
+                endedAt: Date.now(),
+                ...(error ? { error } : {}),
+            });
+            opts.bus.emit({
+                type: 'audit',
+                from: opts.role.id,
+                reason: 'session-run',
+                msg: `session ${run.resumed ? 'resumed' : 'started fresh'} (${startReason}) for ${sessionKey}`,
+                data: run,
+            });
+        };
         const realBefore = mailbox.consumedRealCount;
         let sessionId;
         let hitTurnLimit = false;
         const attempt = { replied: false };
         try {
-            const res = await runOneSession(opts, resumeSessionId, sessionCostTotals, attempt);
+            const res = await runOneSession(sessionOpts, resumeSessionId, sessionCostTotals, attempt, sessionTokenTotals, streamOpts);
             sessionId = res.sessionId;
             hitTurnLimit = res.hitTurnLimit;
             resumeSessionId = sessionId;
+            recordRun(sessionId);
+            if (scope === 'task' && sessionId) {
+                droppedBecause.delete(sessionKey);
+                ledger.set({
+                    role: opts.role.id,
+                    runtime: runtimeKey,
+                    taskKey: sessionKey,
+                    cwd: opts.cwd,
+                    promptHash,
+                    sessionId,
+                });
+            }
         }
         catch (err) {
             const errMsg = err instanceof Error ? err.message : String(err);
+            recordRun(undefined, errMsg);
             // #304 (review round 3): an org's own stop aborts whatever this attempt
             // was doing — max-turns and stale-resume below are diagnoses for a
             // genuinely failed attempt, not for one the org itself just cut off.
@@ -285,8 +426,36 @@ async function runAgentSessionLoop(opts) {
                 sessionId = undefined;
                 resumeSessionId = undefined;
                 hitTurnLimit = true;
+                if (scope === 'task') {
+                    ledger.drop({ role: opts.role.id, runtime: runtimeKey, taskKey: sessionKey });
+                    droppedBecause.set(sessionKey, 'fresh-after-turn-limit');
+                }
+            }
+            else if (!stopping &&
+                scope === 'task' &&
+                sessionIdBefore !== undefined &&
+                !staleTried.has(sessionKey) &&
+                !attempt.replied) {
+                // D3's per-key form of #149 below: a recorded session that fails
+                // before replying is treated as expired — forget it and retry that
+                // task fresh once. Anything it had already pulled goes back first.
+                staleTried.add(sessionKey);
+                ledger.drop({ role: opts.role.id, runtime: runtimeKey, taskKey: sessionKey });
+                droppedBecause.set(sessionKey, 'fresh-after-stale-resume');
+                mailbox.reclaimInFlight();
+                sessionId = undefined;
+                resumeSessionId = undefined;
+                hitTurnLimit = false;
+                opts.bus.emit({
+                    type: 'status',
+                    from: opts.role.id,
+                    reason: 'resume-session-stale',
+                    msg: `agent "${opts.role.id}" could not resume its session for ${sessionKey} — retrying with a fresh session`,
+                    data: { error: errMsg },
+                });
             }
             else if (!stopping &&
+                scope === 'role' &&
                 resumeSessionId &&
                 resumeSessionId === initialResumeSessionId &&
                 !triedFreshAfterResumeFailure &&
@@ -357,6 +526,17 @@ async function runAgentSessionLoop(opts) {
                 });
             }
         }
+        else if (mailbox.lastStreamEnd) {
+            // D3: the process ended on purpose — a task boundary or idle — and the
+            // model session is kept for the next wake.
+            opts.bus.emit({
+                type: 'status',
+                from: opts.role.id,
+                reason: 'session-cycled',
+                msg: `process cycled (${mailbox.lastStreamEnd}); model session kept for ${sessionKey}`,
+                data: { taskKey: sessionKey, end: mailbox.lastStreamEnd, sessionId },
+            });
+        }
         else {
             opts.bus.emit({
                 type: 'status',
@@ -366,11 +546,68 @@ async function runAgentSessionLoop(opts) {
         }
     }
 }
+/** ADR-O001 D1 — token-metering helpers.
+ *
+ *  `cache_read_input_tokens` and `cache_creation_input_tokens` are siblings
+ *  of `input_tokens` in the Anthropic API, not subsets of it, and both are
+ *  billable. Everything below therefore sums all four. */
+function totalTokens(u) {
+    return u.input + u.output + u.cacheRead + u.cacheCreation;
+}
+function addTo(target, add) {
+    target.input += add.input;
+    target.output += add.output;
+    target.cacheRead += add.cacheRead;
+    target.cacheCreation += add.cacheCreation;
+}
+/** One model turn's own usage, off an 'assistant' (or per-turn 'result')
+ *  message. */
+function turnBreakdown(m) {
+    return {
+        input: m.input_tokens ?? 0,
+        output: m.output_tokens ?? 0,
+        cacheRead: m.cache_read_input_tokens ?? 0,
+        cacheCreation: m.cache_creation_input_tokens ?? 0,
+    };
+}
+/** What a 'result' message says this mailbox message consumed.
+ *
+ *  When the runner reports `cumulative_tokens` (the Claude SDK's whole-pipeline
+ *  `modelUsage`, which unlike `usage` includes Task subagents and sidechains),
+ *  that value is CUMULATIVE per session — the same lifecycle as
+ *  `total_cost_usd` — so it is converted to a delta against the previous value
+ *  for the same session_id. A fresh/restarted session has no prior entry and
+ *  correctly yields its full value; a value that ticks down (a provider-side
+ *  correction) floors at 0 rather than re-adding the whole cumulative total.
+ *  Without `cumulative_tokens` the per-turn fields are used as before. */
+function resultBreakdown(m, tokenTotals, sid) {
+    const cum = m.cumulative_tokens;
+    if (!cum)
+        return turnBreakdown(m);
+    const now = {
+        input: cum.input,
+        output: cum.output,
+        cacheRead: cum.cache_read,
+        cacheCreation: cum.cache_creation,
+    };
+    if (!tokenTotals)
+        return now;
+    const prev = tokenTotals.get(sid);
+    tokenTotals.set(sid, now);
+    if (!prev)
+        return now;
+    return {
+        input: Math.max(0, now.input - prev.input),
+        output: Math.max(0, now.output - prev.output),
+        cacheRead: Math.max(0, now.cacheRead - prev.cacheRead),
+        cacheCreation: Math.max(0, now.cacheCreation - prev.cacheCreation),
+    };
+}
 /** One bounded SDK session for a role; resolves with the SDK's session_id (for
  *  resuming on restart) and whether it ended by hitting the turn limit (so the
  *  caller can push a continuation) when the stream ends (mailbox closed or
  *  maxTurns reached). */
-async function runOneSession(opts, resume, costTotals, progress) {
+async function runOneSession(opts, resume, costTotals, progress, tokenTotals, streamOpts) {
     const { org, role, bus, policy, mailbox, cwd } = opts;
     // Read lastMessageId live from opts instead of capturing at session start
     // This ensures chat responses link to the most recent message delivered
@@ -389,7 +626,24 @@ async function runOneSession(opts, resume, costTotals, progress) {
     // The named provider's default model fills in adapter_config.model when the
     // role didn't pin one.
     const prov = resolveRoleProvider(role, opts.orgRoot ?? opts.cwd);
+    // ADR-O001 D8: the role's cost tier, when the org declares one. Resolved
+    // here — the single choke point where a role's model is decided — so the
+    // documented precedence holds in exactly one place:
+    //   explicit adapter_config.model > tier > named-provider default > runtime
+    // The tier's EFFORT is applied even when the model came from an explicit
+    // pin: which model to run and how hard to think are separate axes, and
+    // silently dropping the effort because a model was pinned would be the
+    // "silent downgrade" this decision exists to prevent.
+    // Throws (fails the session) rather than guessing when the tier has no
+    // entry for this role's provider — daemon.ts validates the whole roster
+    // up front so that is normally caught before any token is spent.
+    const tier = resolveRoleCostTier({
+        role,
+        def: opts.def,
+        vendor: role.provider?.vendor ?? prov.cfg?.vendor,
+    });
     const model = role.adapter_config?.model ??
+        tier?.model ??
         prov.defaultModel ??
         resolveModel(role, role.runtime, role.provider?.vendor ?? prov.cfg?.vendor);
     bus.emit({ type: 'status', from: role.id, msg: 'session starting' });
@@ -401,7 +655,7 @@ async function runOneSession(opts, resume, costTotals, progress) {
     // time a 'result' message ends one mailbox message and the next one starts.
     // Exists purely so the 'result' branch never re-adds what this branch
     // already added (see there for why it can't just always add).
-    let messageTurnTokens = 0;
+    let messageTurnTokens = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
     // Abort hook for the runner (AgentRunArgs.signal): the silent-stream
     // abort below used to call iterator.return() only, which queues behind a
     // subprocess runner blocked in `for await (child.stdout)` — the child was
@@ -438,12 +692,18 @@ async function runOneSession(opts, resume, costTotals, progress) {
         });
         const stream = runner.run({
             tools,
-            prompt: mailbox.stream(),
-            systemPrompt: buildRolePrompt(role, (opts.def ?? { name: org, goal: '' }), opts.def?.roles.map((r) => r.id) ?? [role.id], opts.glossary, resolveRoleExtraGuidance(role), opts.onComplete ? endpointBriefingLines(opts.def) : undefined),
+            // No options = the pre-D3 stream, exactly.
+            prompt: streamOpts ? mailbox.stream('', streamOpts) : mailbox.stream(),
+            systemPrompt: rolePromptFor(opts),
             model,
             cwd,
+            effort: tier?.effort,
             env: {
                 ...resolveProviderEnv(prov.cfg),
+                // D8: how a NON-Claude provider expresses the tier's effort level.
+                // Empty for Claude (handled natively by ClaudeAgentRunner) and for a
+                // provider that declares no mechanism — which simply ignores effort.
+                ...(tier?.env ?? {}),
                 // Custom-endpoint providers (named-provider path): pin the engine's
                 // model env so background/haiku tasks also route to the endpoint's
                 // model instead of erroring on an Anthropic-only default.
@@ -475,6 +735,13 @@ async function runOneSession(opts, resume, costTotals, progress) {
             maxTurns: opts.maxTurns ?? 30,
             resume,
             claudeRestrictions: gitEnforcement.claudeRestrictions,
+            // ADR-O001 D2: tool results are 76% of a role's context mass and nothing
+            // bounded them. Under the ORG STATE dir (never the workspace cwd, which
+            // may be the repo), and under orgRoot — which file-roots.ts already
+            // makes readable to the role's file tools and role-sandbox.ts already
+            // makes readable to Bash — so the path in the digest actually resolves
+            // when the role decides it needs the full text.
+            toolSpillDir: join(opts.orgDir ?? opts.cwd, 'tool-results', role.id.replace(/[^a-zA-Z0-9_.-]/g, '_')),
             canUseTool: gatedCanUseTool(policy, opts.beforeTool, role.id, opts.fence, opts.onDecision
                 ? (toolName, _input, decision, kind) => opts.onDecision?.(role.id, toolName, decision.message ?? 'denied', kind)
                 : undefined, opts.hasPendingGate),
@@ -624,10 +891,18 @@ async function runOneSession(opts, resume, costTotals, progress) {
                 // .d.ts, which puts `usage`/token counts on BetaMessage but cost only
                 // on SDKResultSuccess.total_cost_usd/modelUsage. overBudgetUsd is
                 // still checked below, once per message, same as before this fix.)
-                const turnTokens = (m.input_tokens ?? 0) + (m.output_tokens ?? 0);
+                //
+                // ADR-O001 D1: the sum must include BOTH cache fields. They are
+                // siblings of input_tokens in the Anthropic API, not subsets of it —
+                // `input_tokens` is the uncached remainder — and both are billable
+                // (~0.1x and ~1.25x input). Omitting them meant the better the cache
+                // worked the less the meter saw: on one measured run, 2,765M tokens
+                // billed against 8.1M recorded, with input_tokens at 0.0M.
+                const turn = turnBreakdown(m);
+                const turnTokens = totalTokens(turn);
                 if (turnTokens > 0) {
-                    messageTurnTokens += turnTokens;
-                    policy.addUsage(turnTokens);
+                    addTo(messageTurnTokens, turn);
+                    policy.addTokenUsage(turn);
                     if (policy.overBudget) {
                         bus.emit({
                             type: 'status',
@@ -664,20 +939,48 @@ async function runOneSession(opts, resume, costTotals, progress) {
                 });
             }
             else if (m.type === 'result') {
-                const tokens = (m.input_tokens ?? 0) + (m.output_tokens ?? 0);
+                // ADR-O001 D1: prefer the SDK's `modelUsage` over `usage`. The SDK
+                // documents `usage` as "MAIN AGENT LOOP ONLY — excludes Task
+                // subagent, sidechain, and auxiliary model calls ... Prefer
+                // modelUsage for token/cost accounting"; the measured run made 46
+                // subagent calls this counter never saw. modelUsage is CUMULATIVE per
+                // session (same lifecycle as total_cost_usd, per its own type doc),
+                // so it is converted to a delta here rather than added, exactly as
+                // cost is below. A runner that reports no modelUsage falls back to
+                // the per-turn `usage` fields, which keep their old semantics.
+                const resultTokens = resultBreakdown(m, tokenTotals, m.session_id ?? sessionId ?? '');
                 // Per the SDK's own type docs, a 'result' message's usage is that
                 // message's own (effectively last-turn) usage in streaming-input mode,
                 // NOT a cumulative total across every turn of the mailbox message —
                 // and that last turn was already counted above via its own 'assistant'
                 // message, specifically so overBudget could trip mid-message. Adding
-                // `tokens` again here unconditionally would double-count it. Only make
+                // the result's own usage again unconditionally would double-count it.
+                // (A modelUsage-derived delta is per-session-cumulative, so the same
+                // subtraction is exactly right there too: it removes what the
+                // assistant turns of THIS message already contributed and leaves the
+                // subagent/auxiliary volume the main loop never reported.) Only make
                 // up the shortfall (never negative) so a turn whose usage somehow
                 // never reached the 'assistant' branch (e.g. a runner/test double that
                 // doesn't emit per-turn usage) still gets counted at least once.
-                const shortfall = Math.max(0, tokens - messageTurnTokens);
-                if (shortfall > 0)
-                    policy.addUsage(shortfall);
-                messageTurnTokens = 0;
+                const shortfall = {
+                    input: Math.max(0, resultTokens.input - messageTurnTokens.input),
+                    output: Math.max(0, resultTokens.output - messageTurnTokens.output),
+                    cacheRead: Math.max(0, resultTokens.cacheRead - messageTurnTokens.cacheRead),
+                    cacheCreation: Math.max(0, resultTokens.cacheCreation - messageTurnTokens.cacheCreation),
+                };
+                if (totalTokens(shortfall) > 0)
+                    policy.addTokenUsage(shortfall);
+                // What this whole mailbox message actually added to the meter: the
+                // per-turn accounting above plus whatever the result topped up. This
+                // is what the 'usage' event reports, so a consumer summing events
+                // lands on the same number as policy.usage.
+                const messageTokens = {
+                    input: messageTurnTokens.input + shortfall.input,
+                    output: messageTurnTokens.output + shortfall.output,
+                    cacheRead: messageTurnTokens.cacheRead + shortfall.cacheRead,
+                    cacheCreation: messageTurnTokens.cacheCreation + shortfall.cacheCreation,
+                };
+                messageTurnTokens = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
                 // Convert the SDK's cumulative-per-session total_cost_usd into a
                 // per-result delta before emitting - downstream sums usage events.
                 // costTotals is keyed by session_id, so a genuinely new/restarted
@@ -701,7 +1004,19 @@ async function runOneSession(opts, resume, costTotals, progress) {
                 bus.emit({
                     type: 'usage',
                     from: role.id,
-                    data: { tokens, cost_usd: costDelta, subtype: m.subtype },
+                    // ADR-O001 D1: the four quantities travel separately so every
+                    // downstream consumer (forwarder → dashboard state.json, reporting,
+                    // `org costs`) can record real values instead of the 0s they used
+                    // to persist. `tokens` stays the single billable total.
+                    data: {
+                        tokens: totalTokens(messageTokens),
+                        cost_usd: costDelta,
+                        subtype: m.subtype,
+                        tokens_in: messageTokens.input,
+                        tokens_out: messageTokens.output,
+                        cache_read: messageTokens.cacheRead,
+                        cache_creation: messageTokens.cacheCreation,
+                    },
                 });
                 if (m.subtype && m.subtype !== 'success') {
                     if (m.subtype === 'error_max_turns')
@@ -787,6 +1102,13 @@ async function runOneSession(opts, resume, costTotals, progress) {
         providerSet?.close();
     }
 }
+/** ADR-O001 D7: org_task's description suffix for an org with a catalog. */
+function loadoutHelp(catalog) {
+    const list = catalog
+        .map((l) => (l.description ? `${l.name} (${l.description})` : l.name))
+        .join(', ');
+    return ` Optionally select a "loadout" — the named, stable specialisation the assignee's session is built with: ${list}. Select by kind of work; put everything specific to this task (which diff, criteria, what failed last time) in the title or a message, not in the choice of loadout. The selection is recorded on the task and reused on every retry.`;
+}
 /** Build the org tool surface as platform-agnostic OrgToolDef[]. The handlers
  *  close over sessionOpts callbacks (deliver, recall, remember, …) — same
  *  wiring as the previous inline createSdkMcpServer block, just decoupled from
@@ -912,22 +1234,64 @@ export function buildOrgTools(opts) {
             handler: async (args) => text(await onGate(role.id, args.name, args.description)),
         });
     }
+    // ADR-O001 D7: the `loadout` argument exists only for an org with a
+    // catalog, so every other org's tool list stays byte-identical.
+    const catalog = opts.loadoutCatalog?.length ? opts.loadoutCatalog : undefined;
+    const loadoutArg = catalog
+        ? { loadout: z.enum(catalog.map((l) => l.name)).optional() }
+        : {};
     const createTask = opts.createTask;
     if (createTask) {
         tools.push({
             name: 'org_task',
-            description: 'Create a task in the DAG with optional dependencies. Dependencies must be existing task IDs. Tasks become ready when all deps are done, then get dispatched to the assignee.',
-            schema: { title: z.string(), assignee: z.string(), deps: z.array(z.string()).default([]) },
-            handler: async (args) => text(createTask(role.id, args.title, args.assignee, args.deps ?? [])),
+            description: 'Create a task in the DAG with optional dependencies. Dependencies must be existing task IDs. Tasks become ready when all deps are done, then get dispatched to the assignee.' +
+                (catalog ? loadoutHelp(catalog) : ''),
+            schema: {
+                title: z.string(),
+                assignee: z.string(),
+                deps: z.array(z.string()).default([]),
+                ...loadoutArg,
+            },
+            handler: async (args) => text(createTask(role.id, args.title, args.assignee, args.deps ?? [], args.loadout)),
         });
     }
     const completeTask = opts.completeTask;
     if (completeTask) {
         tools.push({
             name: 'org_task_done',
-            description: 'Mark a task as completed and optionally provide a result summary. Any downstream tasks whose deps are now all done will become ready and be dispatched.',
-            schema: { taskId: z.string(), result: z.string().optional() },
-            handler: async (args) => text(completeTask(role.id, args.taskId, args.result)),
+            description: opts.requireTaskEvidence
+                ? 'Mark a task as completed. This org requires EVIDENCE (run_config.completion_evidence): pass `evidence` with the current commit sha and one entry per acceptance criterion — the command you actually ran, its real exit code, and its output. Evidence pinned to an older commit is stale and will be refused, and a refused completion puts the task back in your queue with the reason — but only up to run_config.max_evidence_attempts times (default 3), after which the task is recorded as failed and escalated to the boss instead of returned to you. Any downstream tasks whose deps are now all done become ready and are dispatched.'
+                : 'Mark a task as completed and optionally provide a result summary. Any downstream tasks whose deps are now all done will become ready and be dispatched.',
+            schema: {
+                taskId: z.string(),
+                result: z.string().optional(),
+                evidence: z
+                    .object({
+                    headSha: z.string(),
+                    checks: z
+                        .array(z.object({
+                        command: z.string(),
+                        exitCode: z.number().int(),
+                        output: z.string().optional(),
+                    }))
+                        .default([]),
+                })
+                    .optional(),
+            },
+            handler: async (args) => text(completeTask(role.id, args.taskId, args.result, args.evidence)),
+        });
+    }
+    const requestReview = opts.requestReview;
+    if (requestReview) {
+        tools.push({
+            name: 'org_review',
+            description: "Ask an artifact-only reviewer for a verdict on a task. You pass ids only: the runtime builds the review from the task's text, its assignee's latest org_task_done evidence (commands, exit codes, output) and its own git diff of base...headSha — nothing you write is added, so there is no summary to give. The reviewer starts cold every time and replies to you with org_send. Refused if the task has no evidence yet.",
+            schema: {
+                taskId: z.string(),
+                reviewer: z.string(),
+                base: z.string().optional().describe("git ref to diff against (default 'main')"),
+            },
+            handler: async (args) => text(requestReview(role.id, args.taskId, args.reviewer, args.base)),
         });
     }
     const listTasks = opts.listTasks;
@@ -982,7 +1346,8 @@ export function buildOrgTools(opts) {
     if (planGraph) {
         tools.push({
             name: 'org_plan_graph',
-            description: 'Propose a full work graph in one call. Each task spec uses a local "name" and references other specs by name in "after".',
+            description: 'Propose a full work graph in one call. Each task spec uses a local "name" and references other specs by name in "after".' +
+                (catalog ? ' Each spec may select a "loadout" exactly as org_task does.' : ''),
             schema: {
                 tasks: z
                     .array(z.object({
@@ -990,11 +1355,11 @@ export function buildOrgTools(opts) {
                     title: z.string(),
                     assignee: z.string(),
                     after: z.array(z.string()).default([]),
+                    ...loadoutArg,
                 }))
                     .min(1),
             },
-            handler: async (args) => text(planGraph(role.id, args.tasks ??
-                [])),
+            handler: async (args) => text(planGraph(role.id, args.tasks ?? [])),
         });
     }
     tools.push({
@@ -1015,12 +1380,17 @@ export function buildOrgTools(opts) {
     });
     tools.push({
         name: 'ask_human',
-        description: 'Ask a human a free-form question and pause for their answer. Use only when you genuinely need human judgment.',
-        schema: { question: z.string() },
+        description: 'Ask a human a free-form question. Use only when you genuinely need human judgment. ' +
+            'Set blocking: true ONLY if you cannot continue until it is answered — a blocking question pauses the ' +
+            "org's idle watchdog (for up to an hour; after that the run resumes its normal idle checks either way). " +
+            'If you can keep working while you wait — an FYI, a preference, anything you would describe as "not blocking on this" — ' +
+            'pass blocking: false and carry on; the question is still recorded and answered, it just does not freeze the run. ' +
+            'Defaults to blocking.',
+        schema: { question: z.string(), blocking: z.boolean().optional() },
         handler: async (args) => {
             if (!opts.askHuman)
                 return text('ask_human is not available in this session');
-            const receipt = await opts.askHuman(role.id, args.question);
+            const receipt = await opts.askHuman(role.id, args.question, args.blocking);
             return text(receipt);
         },
     });