niahere 0.4.5 → 0.5.0

package/src/agent/registry.ts

@@ -1,51 +1,76 @@
+import { existsSync } from "fs";
 import type { AgentBackend } from "./types";
+import type { ChainEntry } from "./chain";
 import { ClaudeBackend } from "./backends/claude";
-import { CodexBackend } from "./backends/codex";
+import { CodexBackend, resolveCodexBin } from "./backends/codex";
 import { getConfig } from "../utils/config";
+import { resolveModel, providerDefault, PROVIDER_ORDER, type ProviderName } from "./models";
 
-/**
- * Backend selection — the ONE place backend identity is resolved. Consumers call
- * `getBackend()` and depend only on the `AgentBackend` interface, so no
- * `if (backend === …)` ever leaks into the orchestration loop.
- *
- * Phase 1: always the in-process Claude backend. Phase 2+ adds Codex/Gemini and
- * a role/per-job selector; Phase 3 adds the ordered-fallback failover list.
- */
+/** The ONE place backend identity is resolved. */
 let claudeBackend: ClaudeBackend | null = null;
 let codexBackend: CodexBackend | null = null;
 let override: AgentBackend | null = null;
-let chainOverride: AgentBackend[] | null = null;
+let chainOverride: ChainEntry[] | null = null;
 
-export function getBackend(name?: "claude" | "codex" | "gemini"): AgentBackend {
+export function getBackend(name?: ProviderName): AgentBackend {
   if (override) return override;
-  if (name === "codex") {
-    if (!codexBackend) codexBackend = new CodexBackend();
-    return codexBackend;
-  }
-  if (!claudeBackend) claudeBackend = new ClaudeBackend();
-  return claudeBackend;
+  if (name === "codex") return (codexBackend ??= new CodexBackend());
+  return (claudeBackend ??= new ClaudeBackend());
 }
 
-/** Test seam: force `getBackend()` to return a specific backend; pass null to reset. */
+/** Test seam: force `getBackend()` to return a specific backend; null resets. */
 export function setBackend(backend: AgentBackend | null): void {
   override = backend;
 }
 
-/** Test seam: force `resolveBackends()` to return a specific chain; null resets. */
-export function setBackendChain(backends: AgentBackend[] | null): void {
-  chainOverride = backends;
+/** Test seam: force `resolveChain()` to return a specific chain; null resets. */
+export function setBackendChain(chain: ChainEntry[] | null): void {
+  chainOverride = chain;
+}
+
+/** Gemini is resolvable in config but has no adapter yet. */
+const IMPLEMENTED: ProviderName[] = ["claude", "codex"];
+
+function isAvailable(provider: ProviderName): boolean {
+  if (provider === "claude") return true;
+  if (provider === "codex") return existsSync(resolveCodexBin());
+  return false;
+}
+
+export interface ChainDeps {
+  available: (provider: ProviderName) => boolean;
 }
 
 /**
- * The ordered backend chain for a run: the configured primary first, then any
- * fallbacks (provider-down failover), de-duplicated. Consumers try each in order
- * until one isn't provider-down.
+ * Providers the config never named are appended with their default model, so a
+ * bare config still has somewhere to go — but only if they can run here.
+ * Configured models are always kept, so a misconfiguration surfaces as a real
+ * error rather than vanishing.
  */
-export function resolveBackends(): AgentBackend[] {
+export function buildChain(
+  model: string,
+  fallbackModels: string[],
+  deps: ChainDeps = { available: isAvailable },
+): ChainEntry[] {
+  const configured = [model, ...fallbackModels].map(resolveModel);
+  const named = new Set(configured.map((r) => r.provider));
+  const implicit = PROVIDER_ORDER.filter((p) => !named.has(p) && deps.available(p)).map(providerDefault);
+
+  const seen = new Set<string>();
+  const entries: ChainEntry[] = [];
+  for (const ref of [...configured, ...implicit]) {
+    if (!IMPLEMENTED.includes(ref.provider)) continue;
+    const key = `${ref.provider}:${ref.model ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    entries.push({ backend: getBackend(ref.provider), model: ref.model });
+  }
+  return entries;
+}
+
+export function resolveChain(): ChainEntry[] {
   if (chainOverride) return chainOverride;
-  if (override) return [override];
+  if (override) return [{ backend: override }];
   const cfg = getConfig();
-  const seen = new Set<string>();
-  const names = [cfg.runner, ...cfg.fallback].filter((n) => !seen.has(n) && seen.add(n));
-  return names.map((n) => getBackend(n));
+  return buildChain(cfg.model, cfg.fallback_models);
 }

package/src/agent/types.ts

@@ -32,9 +32,11 @@ export interface AgentUsage {
  * - `text`/`thinking`: streamed reply / status (→ onStream / onActivity).
  * - `tool`: a tool-call activity line.
  * - `result`/`error`: terminal events ending a turn.
- * - `error.retryable` (transient API failure → the backend may retry internally)
- *   and `error.providerDown` (the provider is unavailable → failover trigger) are
- *   INDEPENDENT predicates.
+ * - `error.retryable` (the backend may retry in place) is independent of
+ *   `error.failover`, which scopes how far the chain skips:
+ *   `"model"` advances one entry (possibly the same provider, another model),
+ *   `"provider"` skips that provider's remaining entries, absent stops the
+ *   chain because the task itself failed.
  */
 export type AgentEvent =
   | { type: "session"; backendSessionId: string }
@@ -52,7 +54,10 @@ export type AgentEvent =
        *  Opaque to the orchestrator. */
       metadata?: Record<string, unknown>;
     }
-  | { type: "error"; message: string; retryable: boolean; providerDown: boolean; terminalReason?: string };
+  | { type: "error"; message: string; retryable: boolean; failover?: FailoverScope; terminalReason?: string };
+
+/** How far the chain skips after a failure. See `AgentEvent`. */
+export type FailoverScope = "model" | "provider";
 
 export function isResultEvent(ev: AgentEvent): ev is Extract<AgentEvent, { type: "result" }> {
   return ev.type === "result";

package/src/chat/engine.ts

@@ -10,9 +10,13 @@ import { finalizeSession, cancelPending } from "../core/finalizer";
 import { log } from "../utils/log";
 import { registerActiveHandle, unregisterActiveHandle } from "../core/active-handles";
 import { resolveJobPrompt } from "../core/job-prompt";
-import { resolveBackends, type AgentSession } from "../agent";
+import { truncate } from "../utils/format-activity";
+import { resolveChain, ChainCursor, describeEntry, type AgentSession, type FailoverScope } from "../agent";
+import { scopeOf, parseFailure } from "../agent/failure";
 
 const IDLE_TIMEOUT = 10 * 60 * 1000; // 10 minutes
+const HANDOFF_MESSAGES = 20;
+const HANDOFF_CHARS = 2000;
 const LONG_RUNNING_WARN = 30 * 60 * 1000; // 30 minutes
 const GENERIC_CHAT_ERROR = "💀";
 
@@ -29,8 +33,7 @@ export function formatChatError(rawError: string | null | undefined): string {
 }
 
 export function getChatErrorSignal(rawError: string | null | undefined): SendResult["signal"] | undefined {
-  const error = rawError?.trim();
-  return !error || error.toLowerCase() === "unknown error" ? "provider_down" : undefined;
+  return scopeOf(parseFailure(rawError), "provider") === "provider" ? "provider_down" : undefined;
 }
 
 export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine> {
@@ -96,11 +99,10 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
     systemPrompt += `\n\n## Watch Mode — #${watchChannel}\n\nYou are monitoring this Slack channel. Follow the behavior instructions below.\nRespond with [NO_REPLY] if no action is needed — do not explain why.\n\n${behavior}`;
   }
 
-  // The backend chain: configured primary first, then provider-down fallbacks.
-  // Chat normally runs on the primary; a provider-down turn fails over to the
-  // next backend (answering the current message — see send()).
-  const backends = resolveBackends();
-  let backendIndex = 0;
+  // A turn that cannot be served moves down the chain and answers the current
+  // message there (see send()).
+  const chain = resolveChain();
+  let cursor = new ChainCursor(chain);
 
   let sessionId: string | null = null;
   if (typeof resume === "string") {
@@ -110,13 +112,15 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
     sessionId = await Session.getLatest(room);
   }
 
-  // Verify the primary backend can actually resume this session before
-  // attempting it (Claude probes the on-disk jsonl; others use their own check).
-  if (sessionId && !(await backends[0]!.canResume(sessionId, cwd))) {
+  // Only resume if the head of the chain can actually take this session id.
+  if (sessionId && !(await cursor.current!.backend.canResume(sessionId, cwd))) {
     sessionId = null;
   }
 
   let session: AgentSession | null = null;
+  // Prior turns, replayed into the system prompt when a failover starts a fresh
+  // session on another backend — the new one has no session to resume.
+  let handoff = "";
   let idleTimer: ReturnType<typeof setTimeout> | null = null;
   let longRunningTimer: ReturnType<typeof setTimeout> | null = null;
   let messageCount = 0;
@@ -171,16 +175,28 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
     unregisterActiveHandle(room);
   }
 
-  /** Lazily open (and reuse) the current backend's session for this engine. */
+  /** Transcript of the conversation so far, for a backend that cannot resume it. */
+  async function buildHandoff(currentMessage: string): Promise<string> {
+    const recent = await Message.getRecent(HANDOFF_MESSAGES, room).catch(() => []);
+    const lines = recent
+      .filter((m) => m.content !== currentMessage)
+      .map((m) => `${m.sender === "nia" ? "Nia" : "User"}: ${truncate(m.content, HANDOFF_CHARS)}`);
+    if (lines.length === 0) return "";
+    return `\n\n## Conversation So Far\nYou are continuing this conversation after switching models mid-turn.\n\n${lines.join("\n")}`;
+  }
+
+  /** Lazily open (and reuse) the current chain entry's session for this engine. */
   async function ensureSession(): Promise<AgentSession> {
     if (session) return session;
-    const backend = backends[backendIndex] ?? backends[0]!;
-    const s = await backend.openSession({
+    const entry = cursor.current!;
+    const s = await entry.backend.openSession({
       room,
       channel,
-      systemPrompt,
+      systemPrompt: systemPrompt + handoff,
       cwd,
-      model: contextModel ?? undefined,
+      // A context override names a model for the configured provider, so it
+      // only applies at the head of the chain.
+      model: (cursor.atHead ? (contextModel ?? entry.model) : entry.model) ?? undefined,
       mcpServers,
       resume: sessionId ?? false,
       subagents: getAgentDefinitions(),
@@ -203,6 +219,19 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
     },
 
     async send(userMessage: string, callbacks?: SendCallbacks, attachments?: Attachment[]) {
+      // Re-probe from the top once the failed provider's cooldown lapses, so a
+      // brief outage does not pin the conversation to the fallback for good.
+      if (!cursor.atHead) {
+        const fresh = new ChainCursor(chain);
+        if (fresh.current !== cursor.current) {
+          log.info({ room, to: fresh.current && describeEntry(fresh.current) }, "chat returning to preferred model");
+          cursor = fresh;
+          handoff = await buildHandoff("");
+          await teardown();
+          sessionId = null;
+        }
+      }
+
       // Clear idle timer — engine is not idle while processing a request
       clearIdleTimer();
       startLongRunningTimer();
@@ -227,12 +256,22 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
 
       let result: SendResult = { result: "", costUsd: 0, turns: 0 };
 
-      // Run the turn on the current backend; on a provider-down result, fail over
-      // to the next backend and answer the current message there.
+      // Run the turn on the current chain entry; a turn that cannot be served
+      // moves down the chain and answers the current message there.
       while (true) {
-        const sess = await ensureSession();
+        let sess: AgentSession;
+        try {
+          sess = await ensureSession();
+        } catch (err) {
+          // A backend that cannot start must not take the turn down.
+          const next = cursor.advance("provider");
+          log.warn({ room, err: String(err), to: next && describeEntry(next) }, "chat backend failed to start");
+          if (!next) throw err instanceof Error ? err : new Error(String(err));
+          handoff = await buildHandoff(userMessage);
+          continue;
+        }
         let accumulated = "";
-        let providerDown = false;
+        let failover: FailoverScope | undefined;
 
         try {
           for await (const ev of sess.send(userMessage, attachments)) {
@@ -285,7 +324,7 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
                 break;
               }
               case "error": {
-                providerDown = ev.providerDown;
+                failover = ev.failover;
                 log.error(
                   { room, error: ev.message, terminal_reason: ev.terminalReason },
                   "chat send failed with backend error",
@@ -294,7 +333,7 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
                   result: formatChatError(ev.message),
                   costUsd: 0,
                   turns: 0,
-                  signal: ev.providerDown ? "provider_down" : undefined,
+                  signal: ev.failover === "provider" ? "provider_down" : undefined,
                 };
                 break;
               }
@@ -311,12 +350,13 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
         // Re-read the backend session id post-send so finalize/DB target it.
         if (sess.backendSessionId) sessionId = sess.backendSessionId;
 
-        if (providerDown && backendIndex < backends.length - 1) {
-          backendIndex++;
-          log.warn({ room, to: backends[backendIndex]!.name }, "chat provider down, failing over to next backend");
-          await teardown(); // close the dead session so ensureSession opens the next backend
+        const next = failover && cursor.advance(failover);
+        if (next) {
+          log.warn({ room, to: describeEntry(next), scope: failover }, "chat failing over to next model");
+          await teardown(); // close the dead session so ensureSession opens the next entry
           sessionId = null; // a cross-backend session id is meaningless; start fresh
-          userSaved = false; // re-save the user turn under the new backend's session
+          userSaved = false; // re-save the user turn under the new session
+          handoff = await buildHandoff(userMessage);
           continue;
         }
         break;

package/src/commands/validate.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "fs";
 import yaml from "js-yaml";
 import { getPaths } from "../utils/paths";
 import { ICON_PASS as PASS, ICON_FAIL as FAIL, ICON_WARN as WARN } from "../utils/cli";
+import { buildChain, describeEntry } from "../agent";
 
 interface Result {
   ok: boolean;
@@ -76,24 +77,27 @@ export function validateConfig(): Result {
     messages.push(`${WARN} database_url not set (will use default)`);
   }
 
-  // Backends (primary runner + fallback chain)
-  const BACKENDS = ["claude", "codex", "gemini"];
-  const runner = raw.runner as string | undefined;
-  if (runner && !BACKENDS.includes(runner)) {
-    messages.push(`${FAIL} runner must be one of ${BACKENDS.join(", ")}, got "${runner}"`);
-    ok = false;
-  } else if (runner) {
-    messages.push(`${PASS} runner: ${runner}`);
+  // Model chain. Keys removed in favour of model + fallback_models.
+  for (const dead of ["runner", "fallback", "codex_model"]) {
+    if (raw[dead] !== undefined) {
+      messages.push(`${FAIL} "${dead}" is no longer used — name models in model / fallback_models instead`);
+      ok = false;
+    }
   }
-  if (raw.fallback !== undefined) {
-    const fb = raw.fallback;
-    if (!Array.isArray(fb) || fb.some((b) => !BACKENDS.includes(b as string))) {
-      messages.push(`${FAIL} fallback must be an array of ${BACKENDS.join(", ")}`);
+  if (raw.fallback_models !== undefined) {
+    const fb = raw.fallback_models;
+    if (!Array.isArray(fb) || fb.some((m) => typeof m !== "string")) {
+      messages.push(`${FAIL} fallback_models must be an array of model names`);
       ok = false;
     } else {
-      messages.push(`${PASS} fallback: [${fb.join(", ")}]`);
+      messages.push(`${PASS} fallback_models: [${fb.join(", ")}]`);
     }
   }
+  const chain = buildChain(
+    typeof raw.model === "string" ? raw.model : "default",
+    Array.isArray(raw.fallback_models) ? (raw.fallback_models as string[]).filter((m) => typeof m === "string") : [],
+  );
+  messages.push(`${PASS} model chain: ${chain.map(describeEntry).join(" → ")}`);
 
   // Session finalization
   const sf = raw.session_finalization as Record<string, unknown> | undefined;

package/src/core/alive.ts

@@ -125,7 +125,7 @@ async function notifyUser(message: string): Promise<void> {
 /** Run LLM recovery agent for failures it can fix (e.g. DB down). */
 async function runRecoveryAgent(failures: Check[]): Promise<{ recovered: boolean; report: string }> {
   try {
-    const { runJobWithClaude } = await import("./runner");
+    const { runOneShot } = await import("./runner");
     const { homedir } = await import("os");
 
     const failureSummary = failures.map((f) => `- ${f.name}: ${f.detail}`).join("\n");
@@ -149,7 +149,7 @@ async function runRecoveryAgent(failures: Check[]): Promise<{ recovered: boolean
 
     const jobPrompt = `Health check failures:\n${failureSummary}\n\nDiagnose and fix.`;
 
-    const result = await runJobWithClaude(systemPrompt, jobPrompt, homedir());
+    const result = await runOneShot({ systemPrompt, prompt: jobPrompt, cwd: homedir() });
 
     // Re-check after recovery attempt
     const remaining = await getFailures();

package/src/core/runner.ts

@@ -14,7 +14,7 @@ import { getMcpServers, type McpSourceContext } from "../mcp";
 import { ActiveEngine } from "../db/models";
 import { log } from "../utils/log";
 import { registerActiveHandle, unregisterActiveHandle } from "./active-handles";
-import { getBackend, resolveBackends, type AgentBackend, type AgentSession, type AgentSessionContext } from "../agent";
+import { resolveChain, ChainCursor, describeEntry, type ChainEntry, type AgentSession, type AgentSessionContext, type FailoverScope } from "../agent";
 
 export { buildWorkingMemory } from "./job-prompt";
 
@@ -25,8 +25,8 @@ interface RunnerOutput {
   sessionId: string;
   terminalReason?: string;
   error?: string;
-  /** The backend reported provider-down — caller may fail over to the next backend. */
-  providerDown?: boolean;
+  /** How far the chain should skip after this run. Absent → a real failure, stop. */
+  failover?: FailoverScope;
 }
 
 // ---------------------------------------------------------------------------
@@ -55,7 +55,7 @@ async function consumeBackendRun(
   let agentText = "";
   let terminalReason: string | undefined;
   let error: string | undefined;
-  let providerDown = false;
+  let failover: FailoverScope | undefined;
 
   try {
     for await (const ev of session.send(prompt)) {
@@ -67,7 +67,7 @@ async function consumeBackendRun(
       } else if (ev.type === "error") {
         error = ev.message;
         terminalReason = ev.terminalReason;
-        providerDown = ev.providerDown;
+        failover = ev.failover;
       }
     }
   } catch (err) {
@@ -89,58 +89,74 @@ async function consumeBackendRun(
     return { agentText: "", sessionId: session.backendSessionId ?? "", terminalReason: "aborted", error: abortReason };
   }
 
-  return { agentText, sessionId: session.backendSessionId ?? "", terminalReason, error, providerDown };
+  return { agentText, sessionId: session.backendSessionId ?? "", terminalReason, error, failover };
 }
 
-/**
- * Run a job across the ordered backend chain: try the primary, and on a
- * provider-down result fail over to the next backend (replaying the same prompt;
- * continuity comes from Nia's own context, not a cross-backend session resume).
- */
-export async function runJobAcrossBackends(
-  backends: AgentBackend[],
+/** One attempt. A backend that cannot even start (missing CLI, endpoint down)
+ *  must not take the run with it. */
+async function runEntry(
+  entry: ChainEntry,
   sessionCtx: AgentSessionContext,
-  jobPrompt: string,
+  prompt: string,
   onActivity?: ActivityCallback,
   activeRoom?: string,
 ): Promise<RunnerOutput> {
-  let output: RunnerOutput = { agentText: "", sessionId: "", error: "no backend configured" };
-  for (let i = 0; i < backends.length; i++) {
-    const backend = backends[i]!;
-    const session = await backend.openSession(sessionCtx);
-    output = await consumeBackendRun(session, jobPrompt, onActivity, activeRoom);
-    if (!output.providerDown) return output;
-    const next = backends[i + 1];
-    if (next) log.warn({ from: backend.name, to: next.name }, "provider down, failing over to next backend");
+  try {
+    const session = await entry.backend.openSession({ ...sessionCtx, model: entry.model });
+    return await consumeBackendRun(session, prompt, onActivity, activeRoom);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.warn({ entry: describeEntry(entry), err: message }, "backend failed to start");
+    return { agentText: "", sessionId: "", error: message, failover: "provider" };
   }
-  return output;
 }
 
 /**
- * Run a one-shot job on the in-process Claude backend. Kept as a named export
- * (signature stable) because `alive.ts` and `runTask` call it directly.
+ * Run a job down the chain. The prompt is replayed as-is: continuity comes from
+ * Nia's own context, not a cross-backend session resume.
  */
-export async function runJobWithClaude(
-  systemPrompt: string,
+export async function runJobAcrossChain(
+  chain: ChainEntry[],
+  sessionCtx: AgentSessionContext,
   jobPrompt: string,
-  cwd: string,
   onActivity?: ActivityCallback,
-  model?: string,
-  sourceCtx?: McpSourceContext,
   activeRoom?: string,
 ): Promise<RunnerOutput> {
-  const mcpServers = (getMcpServers(sourceCtx) as Record<string, unknown> | undefined) ?? undefined;
-  const session = await getBackend().openSession({
-    room: activeRoom ?? `_oneshot/${randomUUID()}`,
+  const cursor = new ChainCursor(chain);
+  let output: RunnerOutput = { agentText: "", sessionId: "", error: "no model configured" };
+
+  for (let entry = cursor.current; entry; ) {
+    output = await runEntry(entry, sessionCtx, jobPrompt, onActivity, activeRoom);
+    if (!output.failover) return output;
+
+    const from = describeEntry(entry);
+    entry = cursor.advance(output.failover);
+    if (entry) log.warn({ from, to: describeEntry(entry), scope: output.failover }, "failing over to next model");
+  }
+  return output;
+}
+
+export interface OneShotOptions {
+  systemPrompt: string;
+  prompt: string;
+  cwd: string;
+  onActivity?: ActivityCallback;
+  source?: McpSourceContext;
+  activeRoom?: string;
+}
+
+/** A one-shot run across the chain — no session, no resume. */
+export async function runOneShot(opts: OneShotOptions): Promise<RunnerOutput> {
+  const sessionCtx: AgentSessionContext = {
+    room: opts.activeRoom ?? `_oneshot/${randomUUID()}`,
     channel: "system",
-    systemPrompt,
-    cwd,
-    model,
-    mcpServers,
-    source: sourceCtx,
+    systemPrompt: opts.systemPrompt,
+    cwd: opts.cwd,
+    mcpServers: (getMcpServers(opts.source) as Record<string, unknown> | undefined) ?? undefined,
+    source: opts.source,
     resume: false,
-  });
-  return consumeBackendRun(session, jobPrompt, onActivity, activeRoom);
+  };
+  return runJobAcrossChain(resolveChain(), sessionCtx, opts.prompt, opts.onActivity, opts.activeRoom);
 }
 
 // ---------------------------------------------------------------------------
@@ -165,7 +181,7 @@ export async function runTask(opts: TaskOptions): Promise<RunnerOutput> {
   await ActiveEngine.register(room, "system").catch(() => {});
   try {
     const systemPrompt = opts.systemPrompt || buildSystemPrompt("job");
-    const output = await runJobWithClaude(systemPrompt, opts.prompt, homedir(), undefined, undefined, undefined, room);
+    const output = await runOneShot({ systemPrompt, prompt: opts.prompt, cwd: homedir(), activeRoom: room });
     if (output.error) {
       log.error({ task: opts.name, error: output.error }, "task failed");
     } else {
@@ -243,7 +259,7 @@ export async function runJob(job: JobInput, onActivity?: ActivityCallback): Prom
       source: jobSourceCtx,
       resume: false,
     };
-    output = await runJobAcrossBackends(resolveBackends(), sessionCtx, jobPrompt, onActivity, room);
+    output = await runJobAcrossChain(resolveChain(), sessionCtx, jobPrompt, onActivity, room);
 
     const duration_ms = Math.round(performance.now() - startMs);
     const ok = !output.error;

package/src/core/scheduler.ts

@@ -3,9 +3,25 @@ import { runJob } from "./runner";
 import { getConfig } from "../utils/config";
 import { log } from "../utils/log";
 import { computeInitialNextRun, computeNextRun } from "../utils/schedule";
+import type { JobResult } from "../types";
 
 export { computeInitialNextRun, computeNextRun };
 
+/**
+ * Log a finished job at a level matching its outcome. `runJob` resolves with
+ * `status: "error"` instead of throwing, so the caller's `.catch` only ever sees
+ * an infrastructure fault — a job that ran and failed must be branched on here
+ * or it is indistinguishable from success in the log.
+ */
+export function logJobOutcome(result: JobResult): void {
+  const fields = { job: result.job, status: result.status, duration: result.duration_ms };
+  if (result.status === "error") {
+    log.error({ ...fields, error: result.error, terminal_reason: result.terminal_reason }, "scheduler: job failed");
+    return;
+  }
+  log.info(fields, "scheduler: job completed");
+}
+
 function isWithinActiveHours(): boolean {
   const config = getConfig();
   const { start, end } = config.activeHours;
@@ -57,11 +73,9 @@ async function tick(): Promise<void> {
     runningJobs.add(job.name);
 
     runJob(job)
-      .then((result) => {
-        log.info({ job: job.name, status: result.status, duration: result.duration_ms }, "scheduler: job completed");
-      })
+      .then(logJobOutcome)
       .catch((err) => {
-        log.error({ err, job: job.name }, "scheduler: job failed");
+        log.error({ err, job: job.name }, "scheduler: job crashed");
       })
       .finally(() => {
         runningJobs.delete(job.name);

package/src/mcp/gate.ts

@@ -0,0 +1,46 @@
+import type { NiaTool } from "./tools/types";
+import { log } from "../utils/log";
+
+/**
+ * Per-run budget for tools with real-world consequences.
+ *
+ * The CLI backends run with their own approvals bypassed, and that flag governs
+ * only their built-ins (shell, file writes) — nothing upstream of Nia limits how
+ * often an agent may dial a phone or message the owner. Wrapping the table at
+ * the point each per-run server is built puts one cap in front of every
+ * backend, in-process Claude included.
+ *
+ * These are runaway stops, not permission checks: a looping agent burns its
+ * budget and is told no, while a run doing the job it was asked to do never
+ * reaches them.
+ */
+export const SIDE_EFFECT_LIMITS: Record<string, number> = {
+  place_call: 3,
+  send_message: 25,
+};
+
+/**
+ * Wrap side-effect tools with a budget. Call once per run — the counters live in
+ * the returned closures, so two concurrent runs cannot spend each other's.
+ */
+export function gateSideEffects(tools: NiaTool[]): NiaTool[] {
+  const used = new Map<string, number>();
+
+  return tools.map((t) => {
+    const limit = SIDE_EFFECT_LIMITS[t.name];
+    if (limit === undefined) return t;
+
+    return {
+      ...t,
+      handler: async (args: any, ctx) => {
+        const spent = used.get(t.name) ?? 0;
+        if (spent >= limit) {
+          log.warn({ tool: t.name, limit }, "side-effect tool budget exhausted for this run");
+          return `Refused: ${t.name} has already run ${limit} times in this run, which is its limit. Ask the owner if you genuinely need more.`;
+        }
+        used.set(t.name, spent + 1);
+        return t.handler(args, ctx);
+      },
+    };
+  });
+}

package/src/mcp/server.ts

@@ -1,5 +1,6 @@
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { NIA_TOOLS } from "./tools/table";
+import { gateSideEffects } from "./gate";
 import type { McpSourceContext } from "./index";
 
 /**
@@ -11,7 +12,7 @@ export function createNiaMcpServer(sourceCtx?: McpSourceContext) {
   return createSdkMcpServer({
     name: "nia",
     version: "0.1.0",
-    tools: NIA_TOOLS.map((t) =>
+    tools: gateSideEffects(NIA_TOOLS).map((t) =>
       tool(t.name, t.description, t.schema, async (args: unknown) => ({
         content: [{ type: "text" as const, text: await t.handler(args, sourceCtx) }],
       })),