@amenophis1er/foreman 0.1.0

package/src/gateway.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Gateway supervisor tests.
+ *
+ * These drive a real child process against a stub upstream rather than mocking
+ * the spawn: the things that break here — a port that never binds, a gateway
+ * that dies, a credential that does or does not reach the upstream — are all
+ * properties of an actual process, and a mock would assert the design back at
+ * itself.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import {
+  ensureGateway, gatewayStatus, gatewayUsage, reapNow, releaseGateways, stopGateways,
+} from './gateway.js';
+import { providerEnv, resolveProvider } from './provider.js';
+
+const ROOT = '/tmp/foreman-gateway-test';
+
+/** A minimal OpenAI-compatible endpoint that records what it was sent. */
+function stubUpstream(): Promise<{
+  url: string; seen: Array<{ auth?: string; body: any }>; close: () => Promise<void>;
+}> {
+  const seen: Array<{ auth?: string; body: any }> = [];
+  const server = http.createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c: Buffer) => chunks.push(c));
+    req.on('end', () => {
+      let body: any = null;
+      try { body = JSON.parse(Buffer.concat(chunks).toString()); } catch { /* not json */ }
+      seen.push({ auth: req.headers.authorization as string | undefined, body });
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({
+        id: 'chatcmpl-1', object: 'chat.completion', model: body?.model ?? 'stub',
+        choices: [{ index: 0, message: { role: 'assistant', content: 'pong' }, finish_reason: 'stop' }],
+        usage: { prompt_tokens: 3, completion_tokens: 1, total_tokens: 4 },
+      }));
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address();
+      const port = typeof addr === 'object' && addr ? addr.port : 0;
+      resolve({
+        url: `http://127.0.0.1:${port}`,
+        seen,
+        close: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+test('a gateway starts, translates, and carries the agent credential through', async (t) => {
+  const upstream = await stubUpstream();
+  t.after(async () => { stopGateways(); await upstream.close(); });
+
+  const provider = await resolveProvider(
+    { kind: 'openai-compatible', id: 'stub', baseUrl: upstream.url, apiKeyEnv: 'TEST_GW_KEY' },
+    ROOT,
+  );
+  process.env.TEST_GW_KEY = 'sk-stub-key';
+  const withKey = { ...(await resolveProvider(
+    { kind: 'openai-compatible', id: 'stub', baseUrl: upstream.url, apiKeyEnv: 'TEST_GW_KEY' }, ROOT)) };
+  assert.equal(withKey.problem, undefined);
+  assert.equal(provider.wire, 'gateway-openai');
+
+  const gatewayUrl = await ensureGateway(withKey);
+  assert.match(gatewayUrl, /^http:\/\/127\.0\.0\.1:\d+$/);
+  assert.notEqual(new URL(gatewayUrl).port, '11434', 'must not squat Ollama’s port');
+
+  // Speak to it the way the SDK does: Anthropic Messages in, x-api-key header.
+  const res = await fetch(`${gatewayUrl}/v1/messages`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': 'sk-stub-key' },
+    body: JSON.stringify({
+      model: 'gpt-5', max_tokens: 16,
+      messages: [{ role: 'user', content: 'ping' }],
+    }),
+  });
+  assert.equal(res.status, 200);
+  const body = await res.json() as any;
+
+  // Out the far side it must look like an Anthropic response.
+  assert.equal(body.type, 'message');
+  assert.equal(body.role, 'assistant');
+  assert.equal(body.content[0].text, 'pong');
+
+  // And the upstream must have been spoken to in OpenAI's dialect, holding the
+  // credential the agent sent — not one the supervisor knows.
+  assert.equal(upstream.seen.length, 1);
+  assert.equal(upstream.seen[0].auth, 'Bearer sk-stub-key');
+  assert.equal(upstream.seen[0].body.messages[0].content, 'ping');
+});
+
+test('the same upstream is served by one process, a different one by another', async (t) => {
+  const a = await stubUpstream();
+  const b = await stubUpstream();
+  t.after(async () => { stopGateways(); await a.close(); await b.close(); });
+
+  const mk = (url: string, id: string) =>
+    resolveProvider({ kind: 'openai-compatible', id, baseUrl: url }, ROOT);
+
+  const first = await ensureGateway(await mk(a.url, 'a'));
+  const same = await ensureGateway(await mk(a.url, 'a2'));
+  const other = await ensureGateway(await mk(b.url, 'b'));
+
+  assert.equal(first, same, 'one upstream, one process');
+  assert.notEqual(first, other, 'two upstreams cannot share a process');
+  assert.equal(gatewayStatus().length, 2);
+  assert.ok(gatewayStatus().every((g) => !('apiKey' in g)), 'status must never carry a secret');
+});
+
+test('an agent env built for a gateway points at that gateway', async (t) => {
+  const upstream = await stubUpstream();
+  t.after(async () => { stopGateways(); await upstream.close(); });
+
+  const p = await resolveProvider(
+    { kind: 'openai-compatible', id: 'e2e', baseUrl: upstream.url, model: 'llama3' }, ROOT);
+  const url = await ensureGateway(p);
+  const { env } = providerEnv(p, url);
+  assert.equal(env?.ANTHROPIC_BASE_URL, url);
+  assert.ok(env?.ANTHROPIC_API_KEY, 'the invariant still holds through the supervisor');
+  assert.equal(env?.ANTHROPIC_DEFAULT_SONNET_MODEL, 'llama3');
+});
+
+test('a gateway a run still holds is never reaped, however quiet', async (t) => {
+  const upstream = await stubUpstream();
+  t.after(async () => { stopGateways(); await upstream.close(); });
+
+  const p = await resolveProvider(
+    { kind: 'openai-compatible', id: 'held', baseUrl: upstream.url }, ROOT);
+
+  // Idle time moves when an agent env is BUILT, which happens once at
+  // dispatch — not when requests flow. Reaping on that alone pulled the proxy
+  // out from under a thirty-minute mission ten minutes in, and every call
+  // after it failed with a refused connection.
+  const url = await ensureGateway(p, 'run-1');
+  assert.equal(gatewayStatus().length, 1);
+
+  reapNow(Date.now() + 60 * 60_000);
+  assert.equal(gatewayStatus().length, 1, 'held by run-1, so it must survive');
+
+  const stillThere = await fetch(`${url}/v1/messages`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': 'k' },
+    body: JSON.stringify({ model: 'm', max_tokens: 4, messages: [{ role: 'user', content: 'hi' }] }),
+  });
+  assert.equal(stillThere.status, 200, 'a held gateway still answers');
+
+  releaseGateways('run-1');
+  reapNow(Date.now() + 60 * 60_000);
+  assert.equal(gatewayStatus().length, 0, 'released and idle, so it goes');
+});
+
+test('two runs holding one gateway: the first to finish does not kill it', async (t) => {
+  const upstream = await stubUpstream();
+  t.after(async () => { stopGateways(); await upstream.close(); });
+
+  const p = await resolveProvider(
+    { kind: 'openai-compatible', id: 'shared', baseUrl: upstream.url }, ROOT);
+  await ensureGateway(p, 'run-a');
+  await ensureGateway(p, 'run-b');
+
+  releaseGateways('run-a');
+  reapNow(Date.now() + 60 * 60_000);
+  assert.equal(gatewayStatus().length, 1, 'run-b still needs it');
+
+  releaseGateways('run-b');
+  reapNow(Date.now() + 60 * 60_000);
+  assert.equal(gatewayStatus().length, 0);
+});
+
+test('a run key on the path is stripped, attributed, and never sent upstream', async (t) => {
+  // The mechanism the whole ledger rests on: Foreman points an agent at
+  // `.../run/<key>`, the SDK preserves that prefix (measured — it sends
+  // `POST /run/<key>/v1/messages`), and the gateway must both count against
+  // the key AND hand the upstream the path it expects.
+  const upstream = await stubUpstream();
+  t.after(async () => { stopGateways(); await upstream.close(); });
+
+  const p = await resolveProvider(
+    { kind: 'openai-compatible', id: 'ledger', baseUrl: upstream.url }, ROOT);
+  const url = await ensureGateway(p, 'run-x');
+
+  const ask = (path: string) => fetch(`${url}${path}/v1/messages`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': 'k' },
+    body: JSON.stringify({ model: 'm', max_tokens: 8, messages: [{ role: 'user', content: 'hi' }] }),
+  });
+
+  const res = await ask('/run/mission-1.0');
+  assert.equal(res.status, 200, 'a keyed request is served exactly like an unkeyed one');
+  const body = await res.json() as { content: Array<{ text: string }> };
+  assert.equal(body.content[0].text, 'pong', 'the agent must not be able to tell it was counted');
+
+  // The upstream sees its own API, not Foreman's routing.
+  assert.equal(upstream.seen.length, 1);
+
+  const totals = await gatewayUsage('mission-1.0');
+  assert.ok(totals, 'the key should have been attributed');
+  assert.equal(totals!.inputTokens, 3, 'the stub reports 3 prompt tokens');
+  assert.equal(totals!.outputTokens, 1);
+  assert.equal(totals!.calls, 1);
+
+  // A different attempt of the same run is a different bucket.
+  assert.equal(await gatewayUsage('mission-1.1'), null);
+});
+
+test('an unkeyed request is still served, just not counted', async (t) => {
+  // A gateway that refused traffic it could not label would turn bookkeeping
+  // into an outage.
+  const upstream = await stubUpstream();
+  t.after(async () => { stopGateways(); await upstream.close(); });
+
+  const p = await resolveProvider(
+    { kind: 'openai-compatible', id: 'unkeyed', baseUrl: upstream.url }, ROOT);
+  const url = await ensureGateway(p, 'run-y');
+
+  const res = await fetch(`${url}/v1/messages`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': 'k' },
+    body: JSON.stringify({ model: 'm', max_tokens: 8, messages: [{ role: 'user', content: 'hi' }] }),
+  });
+  assert.equal(res.status, 200);
+  assert.equal((await res.json() as any).content[0].text, 'pong');
+});

package/src/gateway.ts

@@ -0,0 +1,309 @@
+/**
+ * Gateway supervisor — one translating proxy per active provider.
+ *
+ * `src/gateway/llm-gateway.cjs` is a verbatim copy from a sibling project. It
+ * takes its upstream and mode from process env and serves one of them, which
+ * is right for a container holding a single agent and wrong for Foreman, where
+ * one server may run missions for several projects on different providers at
+ * once.
+ *
+ * The answer is a process per provider rather than a router inside the file.
+ * That keeps the copy verbatim — its test suite applies unchanged and
+ * re-syncing upstream stays a `cp` — and it buys process isolation and a
+ * lifecycle that ends when a provider goes idle. See
+ * docs/provider-model-tracker.md, Decisions.
+ *
+ * Nothing here ever sees a credential. The gateway authenticates per request
+ * from the header the agent sends, so a running gateway is a route, not a
+ * secret: the key travels agent → gateway → upstream and is never in this
+ * process's argv, env, or logs.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import net from 'node:net';
+import { fileURLToPath } from 'node:url';
+import type { ResolvedProvider } from './provider.js';
+
+// ledger.cjs, not llm-gateway.cjs: the wrapper binds the socket, counts tokens
+// per run, and hands every request to the ported handler unchanged. See its
+// header for why the counting lives outside the file it wraps.
+const GATEWAY_CLI = fileURLToPath(new URL('./gateway/ledger.cjs', import.meta.url));
+
+/** Give up on a gateway that has not bound its port by then. */
+const START_TIMEOUT_MS = 10_000;
+
+/**
+ * A gateway held by nobody for this long is shut down. Restarting one costs
+ * ~200ms, so reaping is cheap — but only once nothing can still need it.
+ */
+const IDLE_MS = 10 * 60_000;
+
+/** Restarts within this window count toward the crash-loop cutoff. */
+const CRASH_WINDOW_MS = 60_000;
+const MAX_RESTARTS_PER_WINDOW = 3;
+
+interface Gateway {
+  key: string;
+  port: number;
+  mode: 'openai' | 'codex';
+  upstream: string;
+  child: ChildProcess;
+  /** Bumped whenever an agent env is built against this gateway. */
+  lastUsed: number;
+  /**
+   * Runs currently depending on this gateway.
+   *
+   * Idle time alone is not safe to reap on: `lastUsed` moves when an agent
+   * environment is *built*, which happens once at dispatch, not when requests
+   * flow. A mission that ran for thirty minutes therefore looked idle after
+   * ten, and the proxy was pulled out from under a live run — every subsequent
+   * call failed with a refused connection, for the director and its workers
+   * alike. A gateway with holders is never reaped, however quiet it looks.
+   */
+  holders: Set<string>;
+  restarts: number[];
+  /** Set when the gateway has crash-looped; reported instead of restarted. */
+  broken?: string;
+}
+
+const running = new Map<string, Gateway>();
+let reaper: NodeJS.Timeout | null = null;
+
+/**
+ * Identity of a gateway. Mode and upstream are all that distinguish one from
+ * another — two providers pointing at the same endpoint in the same mode can
+ * share, since the credential rides on each request rather than the process.
+ */
+function keyFor(p: ResolvedProvider): string {
+  // Account id is part of the identity for Codex: it is the gateway's fallback
+  // when a token carries no account claim, and two logins sharing a process
+  // would then borrow the first one's.
+  return `${p.wire}|${p.upstreamUrl ?? ''}|${p.accountId ?? ''}`;
+}
+
+/** An unused loopback port, chosen by the OS rather than guessed. */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      const port = typeof addr === 'object' && addr ? addr.port : 0;
+      srv.close(() => (port ? resolve(port) : reject(new Error('no free port'))));
+    });
+  });
+}
+
+/** Resolves once something is listening on the port, or rejects on timeout. */
+async function waitForListen(port: number, child: ChildProcess): Promise<void> {
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  for (;;) {
+    if (child.exitCode !== null || child.signalCode) {
+      throw new Error(`gateway exited during startup (code ${child.exitCode ?? child.signalCode})`);
+    }
+    const up = await new Promise<boolean>((resolve) => {
+      const sock = net.connect({ port, host: '127.0.0.1' });
+      const done = (ok: boolean) => { sock.destroy(); resolve(ok); };
+      sock.once('connect', () => done(true));
+      sock.once('error', () => done(false));
+      sock.setTimeout(500, () => done(false));
+    });
+    if (up) return;
+    if (Date.now() > deadline) throw new Error(`gateway did not listen on ${port} within ${START_TIMEOUT_MS}ms`);
+    await new Promise((r) => setTimeout(r, 50));
+  }
+}
+
+/**
+ * Ensures a gateway is running for this provider and returns its base URL.
+ *
+ * Called on the dispatch path, so it throws rather than returning a broken
+ * URL: a run that cannot reach its gateway must fail with a reason, not send
+ * requests into a closed port.
+ */
+export async function ensureGateway(p: ResolvedProvider, holder?: string): Promise<string> {
+  if (p.wire === 'anthropic-native') throw new Error('native providers need no gateway');
+  const key = keyFor(p);
+
+  const existing = running.get(key);
+  if (existing) {
+    if (existing.broken) throw new Error(existing.broken);
+    if (existing.child.exitCode === null) {
+      existing.lastUsed = Date.now();
+      if (holder) existing.holders.add(holder);
+      return `http://127.0.0.1:${existing.port}`;
+    }
+    running.delete(key);
+  }
+
+  const mode = p.wire === 'gateway-codex' ? 'codex' as const : 'openai' as const;
+  const upstream = p.upstreamUrl ?? '';
+  const accountId = p.accountId ?? '';
+  const port = await freePort();
+
+  // Only routing goes in the env. LLM_GATEWAY_DEFAULT_MODEL is deliberately
+  // absent: the model-alias remap already happens in the agent's own env, and
+  // baking a model into a shared process would make it wrong for the next
+  // provider that reuses this gateway.
+  const child = spawn(process.execPath, [GATEWAY_CLI], {
+    env: {
+      ...process.env,
+      LLM_GATEWAY_MODE: mode,
+      LLM_GATEWAY_TARGET_URL: upstream,
+      LLM_GATEWAY_PORT: String(port),
+      // The ported file defaults this to the name of the project it came from.
+      // Foreman says who it actually is: the originator header is a claim
+      // about which client is calling, and sending someone else's name — or
+      // the CLI's, to look like Codex itself — would be a lie told to a
+      // vendor. See provider-model.md §5.
+      CODEX_ORIGINATOR: process.env.CODEX_ORIGINATOR || 'foreman',
+      // Only consulted when the token carries no account claim of its own.
+      ...(accountId ? { CODEX_ACCOUNT_ID: accountId } : {}),
+      // Opt-in request dumping for diagnosing a stall that only the real
+      // payload reproduces. Forwarded only when the operator set it: the
+      // files contain prompts and repository contents.
+      ...(process.env.FOREMAN_GATEWAY_DUMP_DIR
+        ? { FOREMAN_GATEWAY_DUMP_DIR: process.env.FOREMAN_GATEWAY_DUMP_DIR } : {}),
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  child.unref();
+
+  const gw: Gateway = {
+    key, port, mode, upstream, child, lastUsed: Date.now(), restarts: [],
+    holders: new Set(holder ? [holder] : []),
+  };
+  running.set(key, gw);
+
+  // The gateway logs one line per translated model substitution and its own
+  // startup banner. Prefix them so they are attributable in Foreman's output.
+  const log = (buf: Buffer) => {
+    for (const line of buf.toString().split('\n')) {
+      if (line.trim()) console.error(`[gateway ${mode}:${port}] ${line}`);
+    }
+  };
+  child.stdout?.on('data', log);
+  child.stderr?.on('data', log);
+
+  child.on('exit', (code, signal) => {
+    const g = running.get(key);
+    if (!g || g.child !== child) return; // already replaced
+    const now = Date.now();
+    g.restarts = [...g.restarts.filter((t) => now - t < CRASH_WINDOW_MS), now];
+    if (g.restarts.length > MAX_RESTARTS_PER_WINDOW) {
+      // A gateway that dies repeatedly is misconfigured, not unlucky. Report it
+      // instead of restarting forever behind a mission that keeps failing.
+      g.broken = `gateway for ${upstream || mode} keeps exiting (last: code ${code ?? signal})`;
+      console.error(`[gateway] ${g.broken}`);
+      return;
+    }
+    running.delete(key);
+  });
+
+  try {
+    await waitForListen(port, child);
+  } catch (err) {
+    child.kill();
+    running.delete(key);
+    throw new Error(`could not start the gateway: ${String(err instanceof Error ? err.message : err)}`);
+  }
+
+  startReaper();
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * Retires gateways nothing holds and nothing has used recently.
+ *
+ * Exported so a test can run it at an arbitrary clock instead of waiting a
+ * real ten minutes — the property worth testing is *which* gateways it spares,
+ * and that is invisible on the interval's own schedule.
+ */
+export function reapNow(now = Date.now()): void {
+  for (const [key, g] of running) {
+    if (g.holders.size > 0) continue;
+    if (now - g.lastUsed < IDLE_MS) continue;
+    g.child.kill();
+    running.delete(key);
+  }
+}
+
+/** Stops gateways nothing has used recently. Cheap to restart on demand. */
+function startReaper(): void {
+  if (reaper) return;
+  reaper = setInterval(() => {
+    reapNow();
+    if (running.size === 0 && reaper) {
+      clearInterval(reaper);
+      reaper = null;
+    }
+  }, 60_000);
+  reaper.unref();
+}
+
+/**
+ * Releases every gateway a run was holding. Called when the run ends, however
+ * it ends — the reaper can then retire anything nothing else needs.
+ */
+export function releaseGateways(holder: string): void {
+  for (const g of running.values()) {
+    if (g.holders.delete(holder)) g.lastUsed = Date.now();
+  }
+}
+
+/** Stops every gateway. Called on server shutdown so none are orphaned. */
+export function stopGateways(): void {
+  for (const [key, g] of running) {
+    g.child.kill();
+    running.delete(key);
+  }
+  if (reaper) {
+    clearInterval(reaper);
+    reaper = null;
+  }
+}
+
+/**
+ * Token totals every running gateway has counted for one run key.
+ *
+ * Summed across gateways because a run may hold two — a director on one
+ * provider, workers on another — and the caller wants the run's total, not a
+ * per-process breakdown. A gateway that has seen nothing for this key simply
+ * contributes nothing, so an unreachable or restarted one degrades to a lower
+ * number rather than an error: this is a live read of work in progress, and
+ * the SDK's own figure at the end of the turn remains the authority.
+ */
+export async function gatewayUsage(key: string): Promise<{
+  inputTokens: number; outputTokens: number; cacheReadTokens: number;
+  cacheWriteTokens: number; calls: number; costUsd?: number;
+} | null> {
+  let out: {
+    inputTokens: number; outputTokens: number; cacheReadTokens: number;
+    cacheWriteTokens: number; calls: number; costUsd?: number;
+  } | null = null;
+  for (const g of running.values()) {
+    if (g.broken) continue;
+    const body = await fetch(`http://127.0.0.1:${g.port}/_foreman/usage`, {
+      signal: AbortSignal.timeout(1500),
+    }).then((r) => (r.ok ? r.json() : null)).catch(() => null) as Record<string, {
+      inputTokens: number; outputTokens: number; cacheReadTokens: number;
+      cacheWriteTokens: number; calls: number; costUsd?: number;
+    }> | null;
+    const t = body?.[key];
+    if (!t) continue;
+    out ??= { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, calls: 0 };
+    out.inputTokens += t.inputTokens;
+    out.outputTokens += t.outputTokens;
+    out.cacheReadTokens += t.cacheReadTokens;
+    out.cacheWriteTokens += t.cacheWriteTokens;
+    out.calls += t.calls;
+    if (typeof t.costUsd === 'number') out.costUsd = (out.costUsd ?? 0) + t.costUsd;
+  }
+  return out;
+}
+
+/** Running gateways, for preflight and diagnostics. Never includes secrets. */
+export function gatewayStatus(): Array<{ mode: string; upstream: string; port: number; broken?: string }> {
+  return [...running.values()].map((g) => ({
+    mode: g.mode, upstream: g.upstream, port: g.port, broken: g.broken,
+  }));
+}

package/src/instance.ts

@@ -0,0 +1,124 @@
+/**
+ * Claude Code installs — discovery and description.
+ *
+ * A machine can host several side by side: distinct CLAUDE_CONFIG_DIRs (each
+ * with its own credentials, settings and plugins) and potentially distinct
+ * executables. This module finds them and describes them.
+ *
+ * It deliberately does NOT decide what an agent authenticates as. That is one
+ * question with one answer, and it lives in provider.ts — a Claude Code
+ * install is only one of several things a provider can be, and having two
+ * modules able to build an agent's environment is how a credential ends up
+ * somewhere it should not.
+ */
+import os from 'node:os';
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+export interface ClaudeInstance {
+  /** CLAUDE_CONFIG_DIR for the agent — selects credentials, settings, plugins. */
+  configDir?: string;
+  /** Claude Code executable; the SDK's bundled one is used when absent. */
+  executable?: string;
+}
+
+/** Expands a leading `~` so config can be written the way people type it. */
+function expandHome(p: string): string {
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function clean(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? expandHome(trimmed) : undefined;
+}
+
+/** Server-wide default, from the environment. */
+export function defaultInstance(): ClaudeInstance {
+  return {
+    configDir: clean(process.env.FOREMAN_CLAUDE_CONFIG_DIR),
+    executable: clean(process.env.FOREMAN_CLAUDE_EXECUTABLE),
+  };
+}
+
+/**
+ * One-line description for the preflight screen and run history.
+ *
+ * Resolves through effectiveConfigDir rather than assuming ~/.claude, because a
+ * CLAUDE_CONFIG_DIR inherited from the launching shell silently selects a
+ * different account — and printing the wrong directory here is worse than
+ * printing nothing, since this line is what someone checks before spending.
+ */
+export function describeInstance(instance: ClaudeInstance): string {
+  const dir = effectiveConfigDir(instance);
+  const inherited = !instance.configDir ? ' (inherited)' : '';
+  return [
+    `${dir}${inherited}`,
+    instance.executable ? path.basename(instance.executable) : 'bundled executable',
+  ].join(' · ');
+}
+
+/** One Claude Code install offered in the project settings picker. */
+export interface DiscoveredInstance {
+  /** Absolute config dir (CLAUDE_CONFIG_DIR). */
+  configDir: string;
+  /** How it was found, for the muted hint in the picker. */
+  origin: 'server default' | 'this process' | 'found on disk';
+  /** Whether that dir holds a stored subscription login. */
+  hasStoredLogin: boolean;
+}
+
+/**
+ * Config dirs worth offering: the server default, whatever this process was
+ * started with, and any `~/.claude*` directory that actually looks like a
+ * Claude Code install. Free-text entry stays available for anything missed.
+ */
+export async function discoverInstances(
+  probe: (dir: string) => Promise<boolean>,
+): Promise<DiscoveredInstance[]> {
+  const home = os.homedir();
+  const origins = new Map<string, DiscoveredInstance['origin']>();
+
+  const note = (dir: string | undefined, origin: DiscoveredInstance['origin']) => {
+    const resolved = clean(dir);
+    if (resolved && !origins.has(resolved)) origins.set(resolved, origin);
+  };
+
+  note(process.env.FOREMAN_CLAUDE_CONFIG_DIR, 'server default');
+  note(process.env.CLAUDE_CONFIG_DIR, 'this process');
+  note(path.join(home, '.claude'), 'found on disk');
+
+  const entries = await readdir(home, { withFileTypes: true }).catch(() => []);
+  for (const e of entries) {
+    if (!e.isDirectory() || !e.name.startsWith('.claude')) continue;
+    note(path.join(home, e.name), 'found on disk');
+  }
+
+  const found = await Promise.all(
+    [...origins].map(async ([configDir, origin]) => {
+      const hasStoredLogin = await probe(configDir);
+      // A dir only counts as an install if it holds a login or real settings.
+      const looksReal =
+        hasStoredLogin || (await stat(path.join(configDir, 'settings.json')).then(() => true, () => false));
+      return looksReal || origin !== 'found on disk'
+        ? { configDir, origin, hasStoredLogin }
+        : null;
+    }),
+  );
+
+  return found.filter((i): i is DiscoveredInstance => i !== null)
+    .sort((a, b) => a.configDir.localeCompare(b.configDir));
+}
+
+/**
+ * The config dir that will actually apply to an agent — the pin if there is
+ * one, otherwise whatever the server process itself resolves to.
+ */
+export function effectiveConfigDir(instance: ClaudeInstance): string {
+  return (
+    instance.configDir ??
+    clean(process.env.CLAUDE_CONFIG_DIR) ??
+    path.join(os.homedir(), '.claude')
+  );
+}