@stigmer/cli 3.0.8

package/src/local/daemon/supervisor.test.ts

@@ -0,0 +1,260 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Logger } from "../../logger.js";
+import type { HealthState } from "../state/health-state.js";
+import { readPidFile } from "../state/pidfile.js";
+import { MAX_RESTARTS, ProcessSupervisor } from "./supervisor.js";
+import type { ChildHandle, Clock, ComponentSpec, ExitInfo, ProcessHost, ReadinessGate, SpawnRequest } from "./types.js";
+
+const silent: Logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+// A controllable fake child: the test triggers its exit/readiness and inspects
+// the signals it received.
+interface FakeChild {
+  request: SpawnRequest;
+  handle: ChildHandle;
+  signals: NodeJS.Signals[];
+  termExits: boolean;
+  triggerExit(info?: ExitInfo): void;
+  triggerReady(): void;
+}
+
+class FakeHost implements ProcessHost {
+  readonly children: FakeChild[] = [];
+  readonly killOrder: string[] = [];
+  private nextPid = 1000;
+
+  spawn(request: SpawnRequest): ChildHandle {
+    let exited = false;
+    let exitCb: ((info: ExitInfo) => void) | null = null;
+    let readyCb: (() => void) | null = null;
+    const signals: NodeJS.Signals[] = [];
+    const pid = this.nextPid++;
+    const order = this.killOrder;
+
+    const child: FakeChild = {
+      request,
+      signals,
+      termExits: true,
+      triggerExit: (info = { code: 1, signal: null }) => {
+        if (!exited) {
+          exited = true;
+          exitCb?.(info);
+        }
+      },
+      triggerReady: () => readyCb?.(),
+      handle: {
+        pid,
+        hasExited: () => exited,
+        onExit: (cb) => {
+          exitCb = cb;
+        },
+        onReady: (cb) => {
+          readyCb = cb;
+        },
+        kill: (signal) => {
+          signals.push(signal);
+          order.push(request.command);
+          if (signal === "SIGKILL" || (signal === "SIGTERM" && child.termExits)) {
+            if (!exited) {
+              exited = true;
+              exitCb?.({ code: null, signal });
+            }
+          }
+        },
+      },
+    };
+    this.children.push(child);
+    return child.handle;
+  }
+
+  /** The most-recently-spawned child for a component command. */
+  latest(command: string): FakeChild {
+    const matches = this.children.filter((c) => c.request.command === command);
+    return matches[matches.length - 1];
+  }
+
+  countOf(command: string): number {
+    return this.children.filter((c) => c.request.command === command).length;
+  }
+}
+
+class FakeClock implements Clock {
+  t = 1_000_000;
+  now(): number {
+    return this.t;
+  }
+  sleep(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+const okGate: ReadinessGate = { description: "ok", wait: async () => {} };
+const failGate: ReadinessGate = {
+  description: "fail",
+  wait: async () => {
+    throw new Error("did not become ready");
+  },
+};
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "stigmer-sup-"));
+});
+
+function spec(name: string, opts: { critical?: boolean; marker?: string; gate?: ReadinessGate } = {}): ComponentSpec {
+  return {
+    name,
+    pidFile: join(dir, `${name}.pid`),
+    critical: opts.critical ?? false,
+    resolve: () => ({ command: name, args: [], env: {}, logFile: join(dir, `${name}.log`), readinessMarker: opts.marker }),
+    gate: opts.gate,
+  };
+}
+
+function emptyHealth(): HealthState {
+  return { daemon_pid: 1, started_at: "", components: {} };
+}
+
+function makeSupervisor(
+  specs: ComponentSpec[],
+  extras: { probe?: (port: number) => Promise<boolean> } = {},
+): { sup: ProcessSupervisor; host: FakeHost; clock: FakeClock; hs: HealthState } {
+  const host = new FakeHost();
+  const clock = new FakeClock();
+  const hs = emptyHealth();
+  const sup = new ProcessSupervisor(specs, { host, clock, healthState: hs, persist: () => {}, log: silent, probe: extras.probe });
+  return { sup, host, clock, hs };
+}
+
+describe("startAll", () => {
+  it("starts components in order, writes PID files, and gates the server", async () => {
+    const { sup, host, hs } = makeSupervisor([spec("stigmer-server", { critical: true, gate: okGate }), spec("runner", { marker: "ready" })]);
+    const result = await sup.startAll();
+
+    expect(result.ok).toBe(true);
+    expect(hs.components["stigmer-server"].state).toBe("running");
+    expect(hs.components.runner.state).toBe("running");
+    expect(readPidFile(join(dir, "stigmer-server.pid"))).toBe(host.latest("stigmer-server").handle.pid);
+    expect(readPidFile(join(dir, "runner.pid"))).toBe(host.latest("runner").handle.pid);
+  });
+
+  it("aborts when a critical component fails its gate", async () => {
+    const { sup, hs } = makeSupervisor([spec("stigmer-server", { critical: true, gate: failGate }), spec("runner")]);
+    const result = await sup.startAll();
+
+    expect(result.ok).toBe(false);
+    expect(result.failedCritical).toBe("stigmer-server");
+    expect(hs.components["stigmer-server"].state).toBe("failed");
+    // The runner is registered up front but never started after the abort.
+    expect(hs.components.runner.state).toBe("stopped");
+  });
+});
+
+describe("readiness marker", () => {
+  it("flips ready false -> true when the child announces it", async () => {
+    const { sup, host, hs } = makeSupervisor([spec("runner", { marker: "ready" })]);
+    await sup.startAll();
+    expect(hs.components.runner.ready).toBe(false);
+    host.latest("runner").triggerReady();
+    expect(hs.components.runner.ready).toBe(true);
+  });
+});
+
+describe("settleCheck", () => {
+  it("marks a component that crashed during startup as failed", async () => {
+    const { sup, host, hs } = makeSupervisor([spec("runner")]);
+    await sup.startAll();
+    host.latest("runner").triggerExit();
+    sup.settleCheck();
+    expect(hs.components.runner.state).toBe("failed");
+    expect(hs.components.runner.last_error).toMatch(/crashed during startup/);
+  });
+});
+
+describe("restart policy", () => {
+  it("restarts a crashed component that ran longer than the rapid-crash window", async () => {
+    const { sup, host, clock, hs } = makeSupervisor([spec("runner")]);
+    await sup.startAll();
+    clock.t += 10_000; // 10s uptime
+    host.latest("runner").triggerExit();
+    await sup.tick();
+
+    expect(hs.components.runner.restart_count).toBe(1);
+    expect(hs.components.runner.state).toBe("running");
+    expect(host.countOf("runner")).toBe(2);
+  });
+
+  it("marks a rapid-crashing component failed without retry", async () => {
+    const { sup, host, clock, hs } = makeSupervisor([spec("runner")]);
+    await sup.startAll();
+    clock.t += 1_000; // 1s uptime — inside the rapid-crash window
+    host.latest("runner").triggerExit();
+    await sup.tick();
+
+    expect(hs.components.runner.state).toBe("failed");
+    expect(host.countOf("runner")).toBe(1); // not respawned
+  });
+
+  it("stops retrying after the max-restart ceiling", async () => {
+    const { sup, host, clock, hs } = makeSupervisor([spec("runner")]);
+    await sup.startAll();
+    hs.components.runner.restart_count = MAX_RESTARTS;
+    clock.t += 10_000;
+    host.latest("runner").triggerExit();
+    await sup.tick();
+
+    expect(hs.components.runner.state).toBe("failed");
+    expect(hs.components.runner.last_error).toMatch(/max restarts/);
+    expect(host.countOf("runner")).toBe(1);
+  });
+});
+
+describe("server health probe", () => {
+  it("escalates to kill+restart after the unhealthy threshold, then recovers", async () => {
+    let healthy = false;
+    const { sup, host, clock, hs } = makeSupervisor([spec("stigmer-server", { critical: true, gate: okGate })], {
+      probe: async () => healthy,
+    });
+    await sup.startAll();
+    clock.t += 10_000;
+
+    await sup.tick(); // 1 unhealthy
+    await sup.tick(); // 2 unhealthy
+    expect(hs.components["stigmer-server"].state).toBe("unhealthy");
+    await sup.tick(); // 3 -> kill + restart
+
+    expect(hs.components["stigmer-server"].restart_count).toBe(1);
+    expect(host.countOf("stigmer-server")).toBe(2);
+
+    healthy = true;
+    await sup.tick();
+    expect(hs.components["stigmer-server"].state).toBe("running");
+  });
+});
+
+describe("shutdown", () => {
+  it("stops components in reverse order, removing PID files", async () => {
+    const { sup, host, hs } = makeSupervisor([spec("stigmer-server", { critical: true, gate: okGate }), spec("runner")]);
+    await sup.startAll();
+    await sup.shutdown();
+
+    expect(host.killOrder).toEqual(["runner", "stigmer-server"]);
+    expect(hs.components.runner.state).toBe("stopped");
+    expect(hs.components["stigmer-server"].state).toBe("stopped");
+    expect(readPidFile(join(dir, "runner.pid"))).toBeNull();
+    expect(readPidFile(join(dir, "stigmer-server.pid"))).toBeNull();
+  });
+
+  it("escalates to SIGKILL when a child ignores SIGTERM", async () => {
+    const { sup, host } = makeSupervisor([spec("runner")]);
+    await sup.startAll();
+    host.latest("runner").termExits = false; // ignores SIGTERM
+    await sup.shutdown();
+
+    expect(host.latest("runner").signals).toContain("SIGTERM");
+    expect(host.latest("runner").signals).toContain("SIGKILL");
+  });
+});

package/src/local/daemon/supervisor.ts

@@ -0,0 +1,249 @@
+// The child-process supervision policy: start order, readiness gating, crash
+// restart with rapid-crash and max-restart guards, server health probing, and
+// reverse-order shutdown.
+//
+// Every side effect (spawning, time, the health probe) is injected, so this
+// whole policy is unit-testable without real processes or real waiting — the
+// property the Go daemon never had. process.ts wires this to the real host,
+// clock, Temporal, signals, and the 10s tick.
+
+import { SERVER_PORT } from "../constants.js";
+import { type Logger, log as defaultLog } from "../../logger.js";
+import { tcpConnects } from "../net/tcp.js";
+import type { ComponentState, HealthState } from "../state/health-state.js";
+import { removePidFile, writePidFile } from "../state/pidfile.js";
+import type { ChildHandle, Clock, ComponentSpec, ProcessHost } from "./types.js";
+
+export const MAX_RESTARTS = 5;
+export const RAPID_CRASH_WINDOW_MS = 5_000;
+export const MAX_UNHEALTHY_CHECKS = 3;
+export const GRACEFUL_STOP_TIMEOUT_MS = 5_000;
+export const SETTLE_DELAY_MS = 2_000;
+export const HEALTH_CHECK_INTERVAL_MS = 10_000;
+
+export interface SupervisorDeps {
+  host: ProcessHost;
+  clock: Clock;
+  /** Shared snapshot; the supervisor owns the components map. */
+  healthState: HealthState;
+  /** Persist the snapshot (atomic health-state write). */
+  persist: () => void;
+  log?: Logger;
+  /** TCP probe for the server health check; injectable for tests. */
+  probe?: (port: number) => Promise<boolean>;
+  serverPort?: number;
+}
+
+/** Result of the initial start sequence. */
+export interface StartResult {
+  ok: boolean;
+  /** Name of the critical component that failed, if any. */
+  failedCritical?: string;
+}
+
+interface Managed {
+  spec: ComponentSpec;
+  state: ComponentState;
+  handle: ChildHandle | null;
+  unhealthyCount: number;
+  exitWaiter: Promise<void> | null;
+}
+
+export class ProcessSupervisor {
+  private readonly managed: Managed[];
+  private readonly host: ProcessHost;
+  private readonly clock: Clock;
+  private readonly healthState: HealthState;
+  private readonly persist: () => void;
+  private readonly log: Logger;
+  private readonly probe: (port: number) => Promise<boolean>;
+  private readonly serverPort: number;
+
+  constructor(specs: ComponentSpec[], deps: SupervisorDeps) {
+    this.host = deps.host;
+    this.clock = deps.clock;
+    this.healthState = deps.healthState;
+    this.persist = deps.persist;
+    this.log = deps.log ?? defaultLog;
+    this.probe = deps.probe ?? ((port) => tcpConnects(port, "127.0.0.1", 500));
+    this.serverPort = deps.serverPort ?? SERVER_PORT;
+
+    this.managed = specs.map((spec) => {
+      const state: ComponentState = { pid: 0, state: "stopped", started_at: "", restart_count: 0 };
+      this.healthState.components[spec.name] = state;
+      return { spec, state, handle: null, unhealthyCount: 0, exitWaiter: null };
+    });
+  }
+
+  /**
+   * Start all components in order. A critical component that fails to start or
+   * gate aborts startup (returns failedCritical); a non-critical failure is
+   * recorded and skipped.
+   */
+  async startAll(): Promise<StartResult> {
+    for (const m of this.managed) {
+      this.log.info("starting component", { component: m.spec.name });
+      try {
+        this.spawn(m);
+      } catch (err) {
+        m.state.state = "failed";
+        m.state.last_error = String(err);
+        this.log.error("failed to start component", { component: m.spec.name, error: String(err) });
+        if (m.spec.critical) {
+          this.persist();
+          return { ok: false, failedCritical: m.spec.name };
+        }
+        continue;
+      }
+
+      if (m.spec.gate !== undefined && m.handle !== null) {
+        try {
+          await m.spec.gate.wait(m.handle);
+          this.log.info("component ready", { component: m.spec.name, gate: m.spec.gate.description });
+        } catch (err) {
+          m.state.state = "failed";
+          m.state.last_error = `not ready: ${String(err)}`;
+          this.persist();
+          if (m.spec.critical) return { ok: false, failedCritical: m.spec.name };
+        }
+      }
+    }
+    this.persist();
+    return { ok: true };
+  }
+
+  /** After a brief settle, mark any component that already crashed as failed. */
+  settleCheck(): void {
+    for (const m of this.managed) {
+      if (m.handle !== null && m.handle.hasExited()) {
+        m.state.state = "failed";
+        m.state.last_error = "crashed during startup";
+        this.log.error("component crashed during startup", { component: m.spec.name, pid: m.state.pid });
+      }
+    }
+    this.persist();
+  }
+
+  /** One health-monitor iteration: restart crashed children, probe the server. */
+  async tick(): Promise<void> {
+    for (const m of this.managed) {
+      if (m.handle === null || m.state.state === "failed") continue;
+
+      if (m.handle.hasExited()) {
+        this.log.warn("component exited, attempting restart", { component: m.spec.name, pid: m.state.pid });
+        await this.tryRestart(m);
+        continue;
+      }
+
+      if (m.spec.name === "stigmer-server") {
+        await this.probeServer(m);
+      }
+    }
+    this.persist();
+  }
+
+  /** Gracefully stop all components in reverse start order. */
+  async shutdown(): Promise<void> {
+    for (let i = this.managed.length - 1; i >= 0; i -= 1) {
+      const m = this.managed[i];
+      if (m.handle === null || m.handle.hasExited()) continue;
+      this.log.info("stopping component", { component: m.spec.name, pid: m.state.pid });
+      await this.killAndWait(m);
+      removePidFile(m.spec.pidFile);
+      m.state.state = "stopped";
+    }
+    this.persist();
+  }
+
+  private async probeServer(m: Managed): Promise<void> {
+    if (await this.probe(this.serverPort)) {
+      if (m.unhealthyCount > 0 || m.state.state === "unhealthy") {
+        m.unhealthyCount = 0;
+        m.state.state = "running";
+        m.state.last_error = undefined;
+        this.log.info("component recovered — gRPC port responding again", { component: m.spec.name });
+      }
+      return;
+    }
+    m.unhealthyCount += 1;
+    this.log.warn("gRPC port not responding", { component: m.spec.name, consecutive_failures: m.unhealthyCount });
+    if (m.unhealthyCount >= MAX_UNHEALTHY_CHECKS) {
+      this.log.error("unhealthy threshold exceeded, restarting", { component: m.spec.name });
+      await this.killAndWait(m);
+      await this.tryRestart(m);
+    } else {
+      m.state.state = "unhealthy";
+      m.state.last_error = "gRPC port not responding";
+    }
+  }
+
+  private async tryRestart(m: Managed): Promise<void> {
+    const startedAtMs = m.state.started_at !== "" ? Date.parse(m.state.started_at) : 0;
+    if (startedAtMs > 0 && this.clock.now() - startedAtMs < RAPID_CRASH_WINDOW_MS) {
+      m.state.state = "failed";
+      m.state.last_error = "crashed immediately after start (likely a configuration or dependency error)";
+      this.log.error("component crashed too quickly, marking failed", { component: m.spec.name });
+      return;
+    }
+    if (m.state.restart_count >= MAX_RESTARTS) {
+      m.state.state = "failed";
+      m.state.last_error = `exceeded max restarts (${MAX_RESTARTS})`;
+      this.log.error("component exceeded max restarts, marking failed", { component: m.spec.name });
+      return;
+    }
+    removePidFile(m.spec.pidFile);
+    m.state.restart_count += 1;
+    try {
+      this.spawn(m);
+      this.log.info("component restarted", { component: m.spec.name, restart_count: m.state.restart_count });
+    } catch (err) {
+      m.state.state = "failed";
+      m.state.last_error = String(err);
+      this.log.error("failed to restart component", { component: m.spec.name, error: String(err) });
+    }
+  }
+
+  // Spawn (or respawn) one component, wiring exit/readiness and writing its PID.
+  private spawn(m: Managed): void {
+    const request = m.spec.resolve();
+    const handle = this.host.spawn(request);
+    m.handle = handle;
+    m.unhealthyCount = 0;
+
+    m.exitWaiter = new Promise<void>((resolve) => {
+      handle.onExit(() => resolve());
+    });
+    handle.onReady(() => {
+      m.state.ready = true;
+      this.log.info("component announced readiness", { component: m.spec.name });
+    });
+
+    m.state.pid = handle.pid;
+    m.state.state = "running";
+    m.state.started_at = new Date(this.clock.now()).toISOString();
+    m.state.last_error = undefined;
+    if (request.readinessMarker !== undefined) m.state.ready = false;
+
+    writePidFile(m.spec.pidFile, handle.pid);
+  }
+
+  // SIGTERM, wait for graceful exit, then SIGKILL as a last resort.
+  private async killAndWait(m: Managed): Promise<void> {
+    if (m.handle === null || m.handle.hasExited()) return;
+    m.handle.kill("SIGTERM");
+    const timedOut = await this.raceTimeout(m.exitWaiter, GRACEFUL_STOP_TIMEOUT_MS);
+    if (timedOut && !m.handle.hasExited()) {
+      this.log.warn("graceful stop timed out, sending SIGKILL", { component: m.spec.name });
+      m.handle.kill("SIGKILL");
+      if (m.exitWaiter !== null) await m.exitWaiter;
+    }
+  }
+
+  // Resolve false if the waiter wins, true if the timeout wins.
+  private async raceTimeout(waiter: Promise<void> | null, ms: number): Promise<boolean> {
+    if (waiter === null) return false;
+    const timeout = Symbol("timeout");
+    const result = await Promise.race([waiter.then(() => undefined), this.clock.sleep(ms).then(() => timeout)]);
+    return result === timeout;
+  }
+}

package/src/local/daemon/types.ts

@@ -0,0 +1,76 @@
+// Shared types for the daemon supervisor and its injectable seams.
+//
+// The supervisor's restart/health policy is the part that must be exhaustively
+// testable, so every side effect it performs — spawning a process, reading the
+// clock — goes through an interface that tests can fake. The Go daemon's policy
+// is only reachable through a full integration run; this design makes it a pure
+// unit.
+
+/** How a child terminated. */
+export interface ExitInfo {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+}
+
+/** A request to launch one child process. */
+export interface SpawnRequest {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env: NodeJS.ProcessEnv;
+  /** Log file the child's stdout+stderr are appended to. */
+  logFile: string;
+  /** If set, the host watches stdout for this line and fires onReady once. */
+  readinessMarker?: string;
+}
+
+/** A live handle to a spawned child. */
+export interface ChildHandle {
+  readonly pid: number;
+  /** True once the child has terminated (and been observed). */
+  hasExited(): boolean;
+  /** Register the exit callback (invoked once). */
+  onExit(cb: (info: ExitInfo) => void): void;
+  /** Register the readiness callback (invoked once if a marker was set). */
+  onReady(cb: () => void): void;
+  /** Signal the child's process group. */
+  kill(signal: NodeJS.Signals): void;
+}
+
+/** Spawns child processes. The real implementation pipes + tees logs; tests
+ * substitute a fake that drives exit/readiness synthetically. */
+export interface ProcessHost {
+  spawn(request: SpawnRequest): ChildHandle;
+}
+
+/** Time source, injectable so policy tests run without real delays. */
+export interface Clock {
+  /** Current epoch milliseconds. */
+  now(): number;
+  /** Resolve after `ms` milliseconds. */
+  sleep(ms: number): Promise<void>;
+}
+
+/**
+ * Declarative description of one managed component. `resolve` is called lazily
+ * at (re)start time so binary resolution and env construction happen fresh on
+ * every attempt — matching the Go daemon's per-start `startFn`.
+ */
+export interface ComponentSpec {
+  name: string;
+  pidFile: string;
+  /** Critical components abort daemon startup if they fail to start/gate. */
+  critical: boolean;
+  /** Produce the spawn request for a (re)start. */
+  resolve(): SpawnRequest;
+  /** Optional post-spawn readiness gate (e.g. the server's gRPC port). */
+  gate?: ReadinessGate;
+}
+
+/** A post-spawn readiness check with its own deadline. */
+export interface ReadinessGate {
+  /** Resolves when ready; rejects if the deadline passes or the child exits. */
+  wait(handle: ChildHandle): Promise<void>;
+  /** Human description for logs/errors. */
+  description: string;
+}

package/src/local/llm-config.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import type { Config } from "../config/config.js";
+import {
+  detectProviderFromEnv,
+  readLlm,
+  resolveApiKey,
+  resolveModel,
+  resolveProvider,
+  setLlm,
+  withProviderDefaults,
+} from "./llm-config.js";
+
+function config(local?: unknown): Config {
+  return { backend: { type: "local", local } };
+}
+
+describe("detectProviderFromEnv", () => {
+  it("prefers Anthropic, then OpenAI, else empty", () => {
+    expect(detectProviderFromEnv({ ANTHROPIC_API_KEY: "a", OPENAI_API_KEY: "b" })).toBe("anthropic");
+    expect(detectProviderFromEnv({ OPENAI_API_KEY: "b" })).toBe("openai");
+    expect(detectProviderFromEnv({})).toBe("");
+  });
+});
+
+describe("resolveProvider", () => {
+  it("honors env override > config > autodetect", () => {
+    const cfg = config({ llm: { provider: "ollama" } });
+    expect(resolveProvider(cfg, { STIGMER_LLM_PROVIDER: "openai" })).toBe("openai");
+    expect(resolveProvider(cfg, {})).toBe("ollama");
+    expect(resolveProvider(config(), { ANTHROPIC_API_KEY: "x" })).toBe("anthropic");
+    expect(resolveProvider(config(), {})).toBe("");
+  });
+});
+
+describe("resolveModel", () => {
+  it("falls back to the provider default", () => {
+    expect(resolveModel(config({ llm: { provider: "anthropic" } }), {})).toBe("claude-sonnet-4.5");
+    expect(resolveModel(config({ llm: { provider: "openai" } }), {})).toBe("gpt-4");
+    expect(resolveModel(config({ llm: { provider: "ollama" } }), {})).toBe("qwen2.5-coder:7b");
+    expect(resolveModel(config({ llm: { provider: "anthropic", model: "claude-x" } }), {})).toBe("claude-x");
+    expect(resolveModel(config({ llm: { provider: "anthropic" } }), { STIGMER_LLM_MODEL: "envm" })).toBe("envm");
+  });
+});
+
+describe("resolveApiKey", () => {
+  it("uses the provider-specific env var, then config", () => {
+    const cfg = config({ llm: { provider: "anthropic", api_key: "cfgkey" } });
+    expect(resolveApiKey(cfg, { ANTHROPIC_API_KEY: "envkey" })).toBe("envkey");
+    expect(resolveApiKey(cfg, {})).toBe("cfgkey");
+  });
+});
+
+describe("withProviderDefaults", () => {
+  it("fills model and base URL per provider, keeping api_key only when set", () => {
+    expect(withProviderDefaults({ provider: "anthropic" })).toEqual({ provider: "anthropic", model: "claude-sonnet-4.5" });
+    expect(withProviderDefaults({ provider: "ollama" })).toEqual({
+      provider: "ollama",
+      model: "qwen2.5-coder:7b",
+      base_url: "http://localhost:11434",
+    });
+    expect(withProviderDefaults({ provider: "openai", api_key: "k" })).toEqual({
+      provider: "openai",
+      model: "gpt-4",
+      api_key: "k",
+    });
+  });
+});
+
+describe("setLlm", () => {
+  it("preserves sibling local keys and can clear the section", () => {
+    const cfg = config({ temporal: { managed: true }, llm: { provider: "openai" } });
+    const updated = setLlm(cfg, { provider: "anthropic", model: "m" });
+    expect(readLlm(updated)).toEqual({ provider: "anthropic", model: "m" });
+    expect((updated.backend.local as { temporal: unknown }).temporal).toEqual({ managed: true });
+
+    const cleared = setLlm(cfg, undefined);
+    expect(readLlm(cleared)).toBeUndefined();
+    expect((cleared.backend.local as { temporal: unknown }).temporal).toEqual({ managed: true });
+  });
+});