@monoes/monomindcli 2.9.22 → 2.9.24

package/dist/src/orgrt/session.js

@@ -1,8 +1,8 @@
 // packages/@monomind/cli/src/orgrt/session.ts
 import { z } from 'zod';
-import { Mailbox } from './mailbox.js';
-import { scanInput } from './fence.js';
 import { ClaudeAgentRunner, defaultClaudeRunner } from './agent-runner.js';
+import { scanInput } from './fence.js';
+import { Mailbox } from './mailbox.js';
 import { StateDetector } from './state-detector.js';
 /** How long an SDK stream may stay open with zero messages before we say so.
  *  Comfortably longer than a slow first turn, shorter than the idle watchdog's
@@ -10,7 +10,7 @@ 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 { resolveProviderEnv } from './provider.js';
+import { resolveProviderEnv, resolveRoleProvider } from './provider.js';
 /** Per-vendor/per-runtime default models. Used when a role doesn't pin
  *  adapter_config.model explicitly. Explicit model always wins. */
 const VENDOR_DEFAULTS = {
@@ -40,16 +40,23 @@ export function resolveModel(role, runtime, vendor) {
     if (vendor && VENDOR_DEFAULTS[vendor])
         return VENDOR_DEFAULTS[vendor];
     switch (runtime) {
-        case 'claude': return 'claude-sonnet-4-5';
+        case 'claude':
+            return 'claude-sonnet-4-5';
         // Kimi Code CLI namespaces model ids as <provider>/<model> (its own
         // default_model is "kimi-code/kimi-for-coding-highspeed") — a bare "k3"
         // 404s with "Model \"k3\" is not configured in config.toml".
-        case 'kimicode': return 'kimi-code/k3';
-        case 'opencode': return 'glm-5.2'; // opencode is typically paired with a vendor; this is the bare-runtime fallback
-        case 'codex': return 'gpt-5.6-terra';
-        case 'antigravity': return 'gemini-3.6-flash-high';
-        case 'vercel': return 'gpt-5.5';
-        default: return 'claude-sonnet-4-5';
+        case 'kimicode':
+            return 'kimi-code/k3';
+        case 'opencode':
+            return 'glm-5.2'; // opencode is typically paired with a vendor; this is the bare-runtime fallback
+        case 'codex':
+            return 'gpt-5.6-terra';
+        case 'antigravity':
+            return 'gemini-3.6-flash-high';
+        case 'vercel':
+            return 'gpt-5.5';
+        default:
+            return 'claude-sonnet-4-5';
     }
 }
 /** The SDK's `canUseTool` gate, composed from two independent layers: PolicyEngine's
@@ -60,25 +67,64 @@ export function resolveModel(role, runtime, vendor) {
  *  composition is unit-testable without spinning up a real SDK session: previously
  *  `beforeTool` was wired into SessionOpts but never actually called from here, so
  *  none of those sensitive actions ever paused for a human. */
-export function gatedCanUseTool(policy, beforeTool, roleId, fence) {
+export function gatedCanUseTool(policy, beforeTool, roleId, fence, 
+/** Optional hook invoked whenever this gate denies a tool call — wired to
+ *  daemon.recordDecision() so denials show up in `org decisions` traces. */
+onDeny, 
+/** ORG-9: reports whether this role has a pending (unresolved) decision gate.
+ *  org_gate is documented as creating a "hard-blocking" checkpoint, but until
+ *  this was wired in nothing actually stopped tool use while a gate sat
+ *  pending — only approvals did that. When set and true, ALL tool calls are
+ *  denied (not just the sensitive subset approvals gate) until the gate is
+ *  resolved, matching the "hard-blocking" description. */
+hasPendingGate) {
     return async (toolName, input) => {
+        if (hasPendingGate?.()) {
+            const decision = {
+                behavior: 'deny',
+                message: `Tool "${toolName}" is blocked — awaiting gate resolution. A decision gate is pending; wait for a human to approve or reject it via 'monomind org gate-approve/gate-reject'.`,
+            };
+            onDeny?.(toolName, input, decision);
+            return decision;
+        }
         if (fence) {
-            const text = typeof input.command === 'string' ? input.command
-                : typeof input.content === 'string' ? input.content
-                    : typeof input.url === 'string' ? input.url
+            const text = typeof input.command === 'string'
+                ? input.command
+                : typeof input.content === 'string'
+                    ? input.content
+                    : typeof input.url === 'string'
+                        ? input.url
                         : JSON.stringify(input);
             const fenceDecision = await scanInput(fence.instance, text, fence.abortThreshold);
-            if (fenceDecision.behavior === 'deny')
+            if (fenceDecision.behavior === 'deny') {
+                onDeny?.(toolName, input, fenceDecision);
                 return fenceDecision;
+            }
         }
         const decision = await policy.decide(toolName, input);
-        if (decision.behavior === 'deny' || !beforeTool)
+        if (decision.behavior === 'deny') {
+            onDeny?.(toolName, input, decision);
+            return decision;
+        }
+        if (!beforeTool)
             return decision;
         const approved = await beforeTool(roleId, toolName);
-        if (approved === false)
-            return { behavior: 'deny', message: `Tool "${toolName}" was denied by guardrail approval` };
-        if (approved === null)
-            return { behavior: 'deny', message: `Tool "${toolName}" is pending human approval — it will be available once approved or denied via 'monomind org approve/deny'.` };
+        if (approved === false) {
+            const denied = {
+                behavior: 'deny',
+                message: `Tool "${toolName}" was denied by guardrail approval`,
+            };
+            onDeny?.(toolName, input, denied);
+            return denied;
+        }
+        if (approved === null) {
+            const pending = {
+                behavior: 'deny',
+                message: `Tool "${toolName}" is pending human approval — it will be available once approved or denied via 'monomind org approve/deny'.`,
+            };
+            onDeny?.(toolName, input, pending);
+            return pending;
+        }
         return decision;
     };
 }
@@ -89,14 +135,16 @@ export function buildRolePrompt(role, def, roster, glossary) {
         `You are agent "${role.id}" (${role.title || role.type}) in the org "${def.name}".`,
         `Org goal: ${def.goal}`,
         isCoordinator ? `You are the coordinator of this org.` : `You report to "${role.reports_to}".`,
-        role.responsibilities?.length ? `Your responsibilities:\n- ${role.responsibilities.join('\n- ')}` : '',
+        role.responsibilities?.length
+            ? `Your responsibilities:\n- ${role.responsibilities.join('\n- ')}`
+            : '',
         `## Communication protocol`,
         `The ONLY way to communicate with other agents is the org_send tool.`,
         `Roster: ${roster.join(', ')}. Address another org's agent as "<org-name>:<role-id>".`,
         `If you need a human decision, call ask_human with your question, then end your turn - you'll receive the human's answer as a new message when it arrives. Do not call ask_human for anything you can resolve yourself.`,
         `For irreversible or high-risk actions (deployments, deletions, external communications), call org_gate to create a decision gate — a hard-blocking approval checkpoint. End your turn and wait for the human's approval or rejection before proceeding.`,
         `You can structure work as a task DAG: use org_task to create tasks with dependencies, org_task_done to mark them complete, and org_tasks to see the full DAG. Tasks with satisfied dependencies are automatically dispatched to their assignee.`,
-        `The work graph is dynamic: call org_task_split when scope expands, org_task_merge when parallel branches converge early, or org_task_cancel when evidence makes a planned task moot. Use org_plan_graph to propose a full work graph in one call when you know the plan upfront.`,
+        `The work graph is dynamic: call org_task_split when scope expands, org_task_merge when parallel branches converge early, or org_task_cancel when evidence makes a planned task moot. Use org_plan_graph to propose a full work graph in one call when you know the plan upfront. If a task genuinely can't proceed until a specific real-world time — a scheduled long-running process, a deadline someone gave you, anything with a known future unblock time — call org_task_block instead of leaving it idle: it stops the idle watchdog from nudging you about it and automatically resumes the task when the time arrives, instead of you repeatedly re-confirming "still waiting" every idle cycle.`,
         `Before starting substantial work, call org_recall to check what previous runs already learned or delivered - do not redo finished work.`,
         `The user's documents (notes, handbooks, specs) are searchable with knowledge_search - ground your work in them instead of guessing; results labeled [global] come from the user's personal cross-project brain.`,
         `When you receive a message, act on it, then org_send your result to the requester.`,
@@ -106,7 +154,9 @@ export function buildRolePrompt(role, def, roster, glossary) {
         isCoordinator && glossary?.length
             ? `Known entities (reuse these EXACT names in org_learn instead of near-duplicates): ${glossary.slice(0, 40).join(', ')}`
             : '',
-    ].filter(Boolean).join('\n\n');
+    ]
+        .filter(Boolean)
+        .join('\n\n');
 }
 /**
  * Runs a role for the life of the org, transparently restarting the
@@ -213,17 +263,31 @@ export async function runAgentSession(opts) {
                 consecutiveSpin++;
             if (consecutiveSpin < MAX_CONTINUATIONS) {
                 mailbox.push(`${Mailbox.CONTINUE_PREFIX} You reached the per-session turn limit while still working. Continue your in-progress task from where you left off; if nothing remains, end your turn.`);
-                opts.bus.emit({ type: 'status', from: opts.role.id, reason: 'turn-limit-resume', msg: 'session restarting (turn limit reached, mailbox still open)' });
+                opts.bus.emit({
+                    type: 'status',
+                    from: opts.role.id,
+                    reason: 'turn-limit-resume',
+                    msg: 'session restarting (turn limit reached, mailbox still open)',
+                });
             }
             else {
                 // Spinning on continuations alone — park for the watchdog instead of
                 // looping forever. Reset so the watchdog's nudge buys a fresh budget.
                 consecutiveSpin = 0;
-                opts.bus.emit({ type: 'status', from: opts.role.id, reason: 'turn-limit-park', msg: 'turn limit hit repeatedly with no new input — parking for idle watchdog' });
+                opts.bus.emit({
+                    type: 'status',
+                    from: opts.role.id,
+                    reason: 'turn-limit-park',
+                    msg: 'turn limit hit repeatedly with no new input — parking for idle watchdog',
+                });
             }
         }
         else {
-            opts.bus.emit({ type: 'status', from: opts.role.id, msg: 'session restarting (turn limit reached, mailbox still open)' });
+            opts.bus.emit({
+                type: 'status',
+                from: opts.role.id,
+                msg: 'session restarting (turn limit reached, mailbox still open)',
+            });
         }
     }
 }
@@ -235,12 +299,19 @@ async function runOneSession(opts, resume, costTotals) {
     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
-    const getLastMessageId = () => opts.lastMessageId ? opts.lastMessageId() : undefined;
+    const getLastMessageId = () => (opts.lastMessageId ? opts.lastMessageId() : undefined);
     // Resolve runner. Precedence: explicit runner > queryFn-wrapped > default.
     // queryFn stays supported so daemon.ts / test-loop.ts need no changes.
-    const runner = opts.runner
-        ?? (opts.queryFn ? new ClaudeAgentRunner(opts.queryFn) : defaultClaudeRunner);
+    const runner = opts.runner ?? (opts.queryFn ? new ClaudeAgentRunner(opts.queryFn) : defaultClaudeRunner);
     const tools = buildOrgTools(opts);
+    // Named-provider resolution (`adapter_config.provider`): explicit role
+    // provider wins, else the named entry from `monomind providers configure`.
+    // 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);
+    const model = role.adapter_config?.model ??
+        prov.defaultModel ??
+        resolveModel(role, role.runtime, role.provider?.vendor ?? prov.cfg?.vendor);
     bus.emit({ type: 'status', from: role.id, msg: 'session starting' });
     let sessionId = resume;
     let hitTurnLimit = false;
@@ -249,11 +320,17 @@ async function runOneSession(opts, resume, costTotals) {
         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),
-            model: resolveModel(role, role.runtime, role.provider?.vendor),
+            systemPrompt: buildRolePrompt(role, (opts.def ?? { name: org, goal: '' }), opts.def?.roles.map((r) => r.id) ?? [role.id], opts.glossary),
+            model,
             cwd,
             env: {
-                ...resolveProviderEnv(role.provider),
+                ...resolveProviderEnv(prov.cfg),
+                // 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.
+                ...(prov.cfg?.authToken
+                    ? { ANTHROPIC_MODEL: model, ANTHROPIC_SMALL_FAST_MODEL: model }
+                    : {}),
                 // Suppress all hook advisory output and expensive graph operations for
                 // SDK-spawned org agent sessions. These agents don't need routing,
                 // intelligence injection, or monograph suggestions — they have their
@@ -272,16 +349,20 @@ async function runOneSession(opts, resume, costTotals) {
             },
             maxTurns: opts.maxTurns ?? 30,
             resume,
-            canUseTool: gatedCanUseTool(policy, opts.beforeTool, role.id, opts.fence),
+            canUseTool: gatedCanUseTool(policy, opts.beforeTool, role.id, opts.fence, opts.onDecision
+                ? (toolName, _input, decision) => opts.onDecision?.(role.id, toolName, decision.message ?? 'denied')
+                : undefined, opts.hasPendingGate),
             // test seam forwarded through extras: lets the scripted fake SDK
             // (test-loop.ts) drive org_send and tool calls through the real
             // deliver/policy paths; the real SDK ignores it.
-            extras: opts.runner ? undefined : {
-                _orgTest: {
-                    deliver: (to, subject, body) => opts.deliver(role.id, to, subject, body),
-                    callTool: (name, input) => policy.decide(name, input),
+            extras: opts.runner
+                ? undefined
+                : {
+                    _orgTest: {
+                        deliver: (to, subject, body) => opts.deliver(role.id, to, subject, body),
+                        callTool: (name, input) => policy.decide(name, input),
+                    },
                 },
-            },
             // VercelAgentRunner-only fields — ignored by other runners.
             vendor: role.provider?.vendor,
             providerConfig: role.provider,
@@ -314,7 +395,7 @@ async function runOneSession(opts, resume, costTotals) {
         let silentTimer;
         const firstPull = await Promise.race([
             iterator.next(),
-            new Promise(resolve => {
+            new Promise((resolve) => {
                 silentTimer = setTimeout(() => resolve(SILENT), SILENT_SESSION_MS);
                 silentTimer.unref?.();
             }),
@@ -322,16 +403,23 @@ async function runOneSession(opts, resume, costTotals) {
         clearTimeout(silentTimer);
         if (firstPull === SILENT) {
             bus.emit({
-                type: 'audit', from: role.id, reason: 'session-silent',
+                type: 'audit',
+                from: role.id,
+                reason: 'session-silent',
                 msg: `SDK stream open ${Math.round((Date.now() - openedAt) / 1000)}s with zero messages - aborting this attempt and retrying. Set MONOMIND_DEBUG=1 to log raw message types.`,
             });
             try {
                 await Promise.race([
                     iterator.return?.(undefined) ?? Promise.resolve(),
-                    new Promise(r => { const t = setTimeout(() => r(), 2_000); t.unref?.(); }),
+                    new Promise((r) => {
+                        const t = setTimeout(() => r(), 2_000);
+                        t.unref?.();
+                    }),
                 ]);
             }
-            catch { /* best-effort */ }
+            catch {
+                /* best-effort */
+            }
             throw new Error(`org "${org}" role "${role.id}": SDK stream silent for ${Math.round(SILENT_SESSION_MS / 1000)}s with zero messages`);
         }
         const first = firstPull;
@@ -357,10 +445,16 @@ async function runOneSession(opts, resume, costTotals) {
                 opts.onSessionId?.(sessionId);
             }
             const prevState = detector.current();
-            const textForDetect = m.type === 'assistant' ? (m.text || '') : undefined;
+            const textForDetect = m.type === 'assistant' ? m.text || '' : undefined;
             const newState = detector.onMessage(m.type, m.subtype, textForDetect);
             if (newState !== prevState) {
-                bus.emit({ type: 'status', from: role.id, reason: 'state-change', msg: `${prevState} → ${newState}`, data: { from: prevState, to: newState } });
+                bus.emit({
+                    type: 'status',
+                    from: role.id,
+                    reason: 'state-change',
+                    msg: `${prevState} → ${newState}`,
+                    data: { from: prevState, to: newState },
+                });
             }
             if (m.type === 'assistant') {
                 const text = m.text || '';
@@ -369,7 +463,12 @@ async function runOneSession(opts, resume, costTotals) {
                     bus.emit({ type: 'chat', from: role.id, msg: text, parentId: getLastMessageId() });
                     if (opts.onContextLimit && !contextLimitFired && CONTEXT_LIMIT_RE.test(text)) {
                         contextLimitFired = true;
-                        bus.emit({ type: 'audit', from: role.id, reason: 'boss-context-limit', msg: 'coordinator context window exhausted — requesting whole-org restart with fresh sessions' });
+                        bus.emit({
+                            type: 'audit',
+                            from: role.id,
+                            reason: 'boss-context-limit',
+                            msg: 'coordinator context window exhausted — requesting whole-org restart with fresh sessions',
+                        });
                         opts.onContextLimit();
                     }
                 }
@@ -379,21 +478,36 @@ async function runOneSession(opts, resume, costTotals) {
                 policy.addUsage(tokens);
                 // Convert the SDK's cumulative-per-session total_cost_usd into a
                 // per-result delta before emitting - downstream sums usage events.
-                // A value below the stored total means the billing session restarted
-                // (fresh session id), in which case the full value is the delta.
+                // costTotals is keyed by session_id, so a genuinely new/restarted
+                // session (fresh sid, no prior entry) correctly gets its full
+                // cumulative value as the delta. A same-sid value that ticks down
+                // (rounding, a provider-side cost correction) is NOT a restart —
+                // treating it as one would re-add the full cumulative cost and,
+                // now that this feeds real USD budget enforcement (ORG-7), could
+                // incorrectly close a well-behaved session's mailbox. Floor at 0
+                // instead of re-adding the cumulative value in that case.
                 let costDelta = m.cost_usd;
                 if (costTotals && typeof m.cost_usd === 'number' && Number.isFinite(m.cost_usd)) {
                     const sid = m.session_id ?? sessionId ?? '';
                     const prev = costTotals.get(sid);
-                    costDelta = prev === undefined || m.cost_usd < prev ? m.cost_usd : m.cost_usd - prev;
+                    costDelta = prev === undefined ? m.cost_usd : Math.max(0, m.cost_usd - prev);
                     costTotals.set(sid, m.cost_usd);
                 }
-                bus.emit({ type: 'usage', from: role.id, data: { tokens, cost_usd: costDelta, subtype: m.subtype } });
+                // ORG-7: accumulate real USD cost so policy.overBudgetUsd (role.budget_usd) is enforceable.
+                if (typeof costDelta === 'number' && Number.isFinite(costDelta))
+                    policy.addUsageUsd(costDelta);
+                bus.emit({
+                    type: 'usage',
+                    from: role.id,
+                    data: { tokens, cost_usd: costDelta, subtype: m.subtype },
+                });
                 if (m.subtype && m.subtype !== 'success') {
                     if (m.subtype === 'error_max_turns')
                         hitTurnLimit = true;
                     bus.emit({
-                        type: 'audit', from: role.id, reason: 'session-result-error',
+                        type: 'audit',
+                        from: role.id,
+                        reason: 'session-result-error',
                         msg: `turn ended with subtype "${m.subtype}"${m.is_error ? ' (is_error)' : ''} - the role produced no usable output`,
                     });
                     if (opts.circuitBreaker && m.subtype !== 'error_max_turns') {
@@ -402,7 +516,9 @@ async function runOneSession(opts, resume, costTotals) {
                         if (cb.state.failures >= cb.threshold) {
                             cb.state.tripped = true;
                             bus.emit({
-                                type: 'audit', from: role.id, reason: 'circuit-breaker-tripped',
+                                type: 'audit',
+                                from: role.id,
+                                reason: 'circuit-breaker-tripped',
                                 msg: `circuit breaker tripped after ${cb.state.failures} consecutive failures — closing role`,
                                 data: { failures: cb.state.failures, threshold: cb.threshold },
                             });
@@ -414,8 +530,26 @@ async function runOneSession(opts, resume, costTotals) {
                     opts.circuitBreaker.state.failures = 0;
                 }
                 if (policy.overBudget) {
-                    bus.emit({ type: 'status', from: role.id, msg: 'token budget exhausted - closing session' });
-                    mailbox.close();
+                    bus.emit({
+                        type: 'status',
+                        from: role.id,
+                        reason: 'budget-exhausted',
+                        msg: 'token budget exhausted - closing session',
+                    });
+                    // #205: tag WHY the mailbox closed. A budget-exhausted boss is
+                    // recoverable (raise the budget, resume) — the idle watchdog reads
+                    // this to stop reporting it as generic "unreachable" (crash-like).
+                    mailbox.close('token-budget');
+                }
+                // ORG-7: parallel USD-budget enforcement, same pattern as the token check above.
+                if (policy.overBudgetUsd) {
+                    bus.emit({
+                        type: 'status',
+                        from: role.id,
+                        reason: 'budget-exhausted',
+                        msg: 'USD budget exhausted - closing session',
+                    });
+                    mailbox.close('usd-budget');
                 }
             }
         }
@@ -441,17 +575,17 @@ export function buildOrgTools(opts) {
     if (opts.searchKnowledge) {
         tools.push({
             name: 'knowledge_search',
-            description: 'Semantic search over the user\'s Second Brain: this project\'s indexed documents plus their personal cross-project global brain. Use to ground work in the user\'s actual notes, handbooks, and documents.',
+            description: "Semantic search over the user's Second Brain: this project's indexed documents plus their personal cross-project global brain. Use to ground work in the user's actual notes, handbooks, and documents.",
             schema: { query: z.string() },
-            handler: async (args) => text(await opts.searchKnowledge(role.id, args.query)),
+            handler: async (args) => text(await opts.searchKnowledge?.(role.id, args.query)),
         });
     }
     if (opts.recall) {
         tools.push({
             name: 'org_recall',
-            description: 'Search this org\'s accumulated memory from previous runs (outcomes, decisions, learnings). Use before starting work that may already have been done.',
+            description: "Search this org's accumulated memory from previous runs (outcomes, decisions, learnings). Use before starting work that may already have been done.",
             schema: { query: z.string() },
-            handler: async (args) => text(await opts.recall(role.id, args.query)),
+            handler: async (args) => text(await opts.recall?.(role.id, args.query)),
         });
     }
     if (opts.remember) {
@@ -459,19 +593,32 @@ export function buildOrgTools(opts) {
             name: 'org_remember',
             description: 'Save a memory for future runs. scope "org" (default) shares it with the whole org; scope "agent" keeps it private to your role. Use for decisions, findings, and state worth recalling later - org_recall searches both.',
             schema: { content: z.string(), scope: z.enum(['org', 'agent']).optional() },
-            handler: async (args) => text(await opts.remember(role.id, args.content, args.scope ?? 'org')),
+            handler: async (args) => text(await opts.remember?.(role.id, args.content, args.scope ?? 'org')),
         });
     }
     if (opts.learn) {
         tools.push({
             name: 'org_learn',
-            description: 'Persist durable knowledge from this run into the org\'s knowledge graph: entities ({name, type?, description?}), relationships ({source, target, relation, description?}) and reusable rules ({rule, context?}). Entities merge by name across runs - reuse the exact names listed in your briefing. Call once, before org_complete.',
+            description: "Persist durable knowledge from this run into the org's knowledge graph: entities ({name, type?, description?}), relationships ({source, target, relation, description?}) and reusable rules ({rule, context?}). Entities merge by name across runs - reuse the exact names listed in your briefing. Call once, before org_complete.",
             schema: {
-                nodes: z.array(z.object({ name: z.string(), type: z.string().optional(), description: z.string().optional() })).optional(),
-                edges: z.array(z.object({ source: z.string(), target: z.string(), relation: z.string(), description: z.string().optional() })).optional(),
+                nodes: z
+                    .array(z.object({
+                    name: z.string(),
+                    type: z.string().optional(),
+                    description: z.string().optional(),
+                }))
+                    .optional(),
+                edges: z
+                    .array(z.object({
+                    source: z.string(),
+                    target: z.string(),
+                    relation: z.string(),
+                    description: z.string().optional(),
+                }))
+                    .optional(),
                 rules: z.array(z.object({ rule: z.string(), context: z.string().optional() })).optional(),
             },
-            handler: async (args) => text(await opts.learn(role.id, args)),
+            handler: async (args) => text(await opts.learn?.(role.id, args)),
         });
     }
     // Gate purely on onComplete: the daemon passes it only to the role its
@@ -480,10 +627,10 @@ export function buildOrgTools(opts) {
     if (opts.onComplete) {
         tools.push({
             name: 'org_complete',
-            description: '⚠️ Ends the run — every agent session shuts down after this. Call exactly once, and only against the org\'s actual, full stated goal (see your briefing), never against just the current batch of dispatched tasks. "achieved" means the WHOLE goal is done, not "everyone assigned so far finished their piece" — a multi-phase or open-ended goal is very rarely achieved in a single run. If the current task batch is clearly done but the goal has more scope left: do NOT call this — use org_task/createTask to dispatch the next phase\'s work instead, so the org keeps making progress instead of stopping short. Use outcome "partial" only when you are ending the run with real scope still remaining (e.g. a genuine external stopping point, not merely "out of tasks right now"); "achieved" only when the full goal is met; "failed" only when it clearly cannot be. Before calling, check org_tasks — siblings with in-progress work only get a short drain window to finish before being cut off, so do not call this while others are still mid-build or mid-edit unless the run genuinely cannot continue. The outcome and summary are persisted to the org run history and briefed to the next run.',
+            description: '⚠️ Ends the run — every agent session shuts down after this. Call exactly once, and only against the org\'s actual, full stated goal (see your briefing), never against just the current batch of dispatched tasks. "achieved" means the WHOLE goal is done, not "everyone assigned so far finished their piece" — a multi-phase or open-ended goal is very rarely achieved in a single run. If the current task batch is clearly done but the goal has more scope left: do NOT call this — use org_task/createTask to dispatch the next phase\'s work instead, so the org keeps making progress instead of stopping short. Use outcome "partial" only when you are ending the run with real scope still remaining (e.g. a genuine external stopping point, not merely "out of tasks right now" — if the only thing blocking further work is a scheduled process or deadline you know the time of, call org_task_block instead of ending the run, so a future run can pick back up automatically); "achieved" only when the full goal is met; "failed" only when it clearly cannot be. Before calling, check org_tasks — siblings with in-progress work only get a short drain window to finish before being cut off, so do not call this while others are still mid-build or mid-edit unless the run genuinely cannot continue. The outcome and summary are persisted to the org run history and briefed to the next run.',
             schema: { outcome: z.enum(['achieved', 'partial', 'failed']), summary: z.string() },
             handler: async (args) => {
-                opts.onComplete(role.id, args.outcome, args.summary);
+                opts.onComplete?.(role.id, args.outcome, args.summary);
                 return text(`outcome "${args.outcome}" recorded`);
             },
         });
@@ -493,7 +640,7 @@ export function buildOrgTools(opts) {
             name: 'org_gate',
             description: 'Create a decision gate — a hard-blocking human-approval checkpoint. Use before irreversible actions (deployments, deletions, external comms). The gate pauses your work until a human approves or rejects it. End your turn after calling this; you will receive the resolution as a new message.',
             schema: { name: z.string(), description: z.string() },
-            handler: async (args) => text(await opts.onGate(role.id, args.name, args.description)),
+            handler: async (args) => text(await opts.onGate?.(role.id, args.name, args.description)),
         });
     }
     if (opts.createTask) {
@@ -501,27 +648,30 @@ export function buildOrgTools(opts) {
             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(opts.createTask(role.id, args.title, args.assignee, args.deps ?? [])),
+            handler: async (args) => text(opts.createTask?.(role.id, args.title, args.assignee, args.deps ?? [])),
         });
         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(opts.completeTask(role.id, args.taskId, args.result)),
+            handler: async (args) => text(opts.completeTask?.(role.id, args.taskId, args.result)),
         });
         tools.push({
             name: 'org_tasks',
             description: 'List all tasks in the DAG with their current status and dependencies.',
             schema: {},
-            handler: async () => text(opts.listTasks()),
+            handler: async () => text(opts.listTasks?.()),
         });
     }
     if (opts.splitTask) {
         tools.push({
             name: 'org_task_split',
             description: 'Split a task into parallel children when scope expands. The parent becomes "split"; children inherit its deps; downstream tasks are rewired to depend on all children.',
-            schema: { parentId: z.string(), children: z.array(z.object({ title: z.string(), assignee: z.string() })).min(1) },
-            handler: async (args) => text(opts.splitTask(role.id, args.parentId, args.children ?? [])),
+            schema: {
+                parentId: z.string(),
+                children: z.array(z.object({ title: z.string(), assignee: z.string() })).min(1),
+            },
+            handler: async (args) => text(opts.splitTask?.(role.id, args.parentId, args.children ?? [])),
         });
     }
     if (opts.mergeTask) {
@@ -529,7 +679,7 @@ export function buildOrgTools(opts) {
             name: 'org_task_merge',
             description: 'Merge one task into another when parallel branches converge early. The source becomes "merged"; downstream deps are rewired to the target.',
             schema: { sourceId: z.string(), targetId: z.string() },
-            handler: async (args) => text(opts.mergeTask(role.id, args.sourceId, args.targetId)),
+            handler: async (args) => text(opts.mergeTask?.(role.id, args.sourceId, args.targetId)),
         });
     }
     if (opts.cancelTask) {
@@ -537,15 +687,33 @@ export function buildOrgTools(opts) {
             name: 'org_task_cancel',
             description: 'Cancel a task as moot. The task becomes "cancelled" and unblocks downstream work.',
             schema: { taskId: z.string(), reason: z.string().optional() },
-            handler: async (args) => text(opts.cancelTask(role.id, args.taskId, args.reason)),
+            handler: async (args) => text(opts.cancelTask?.(role.id, args.taskId, args.reason)),
+        });
+    }
+    if (opts.blockTask) {
+        tools.push({
+            name: 'org_task_block',
+            description: 'Mark a task you are actively working (status "running") as blocked on a real-world time, not on other tasks — e.g. a scheduled soak test, a CI run that takes hours, a human-set deadline. Use this INSTEAD of leaving the task "running" with nothing actually happening, and instead of calling org_complete just because there is genuinely nothing to do right now: the idle watchdog will stop nudging you about this task until the time you give arrives, then automatically re-dispatch it to you. Give untilIso as an ISO 8601 date/time (e.g. "2026-08-19T09:00:00Z").',
+            schema: { taskId: z.string(), untilIso: z.string(), reason: z.string().optional() },
+            handler: async (args) => text(opts.blockTask?.(role.id, args.taskId, args.untilIso, args.reason)),
         });
     }
     if (opts.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".',
-            schema: { tasks: z.array(z.object({ name: z.string(), title: z.string(), assignee: z.string(), after: z.array(z.string()).default([]) })).min(1) },
-            handler: async (args) => text(opts.planGraph(role.id, args.tasks ?? [])),
+            schema: {
+                tasks: z
+                    .array(z.object({
+                    name: z.string(),
+                    title: z.string(),
+                    assignee: z.string(),
+                    after: z.array(z.string()).default([]),
+                }))
+                    .min(1),
+            },
+            handler: async (args) => text(opts.planGraph?.(role.id, args.tasks ??
+                [])),
         });
     }
     tools.push({