@amenophis1er/foreman 0.1.0

package/src/store.ts

@@ -0,0 +1,346 @@
+/**
+ * RunStore — durable, append-only persistence for Foreman runs.
+ *
+ * Layout (default root: ~/.foreman):
+ *
+ *   <root>/runs/<runId>/meta.json     — RunMeta, rewritten atomically on change
+ *   <root>/runs/<runId>/events.jsonl  — one ForemanEvent per line, append-only
+ *   <root>/chats/<projectId>/…        — same two files for a project's
+ *                                       planning conversation
+ *
+ * Design notes for reviewers:
+ *  - The event log is the source of truth for the UI; meta.json is a derived
+ *    summary kept small so listing runs never reads event logs.
+ *  - meta.json writes go through tmp-file + rename so a crash mid-write can
+ *    never corrupt an existing file.
+ *  - Event appends are serialized per store instance through a promise chain,
+ *    preserving emit order even when callers don't await.
+ *  - {@link sweepOrphans} reconciles runs left in status "running" by a
+ *    previous process: it appends a synthetic `run_finished` event and marks
+ *    the run interrupted, so replaying a log always terminates cleanly.
+ */
+import { appendFile, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import type {
+  ChatMeta, ForemanEvent, Project, ProviderRef, RunMeta, RunSummary, SettingsFile,
+} from './types.js';
+
+const RUN_ID_RE = /^[0-9]{13}-[0-9a-f]{8}$/;
+
+/** Sortable, collision-safe run id: `<ms since epoch>-<random hex>`. */
+export function newRunId(now = Date.now()): string {
+  return `${String(now).padStart(13, '0')}-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+export class RunStore {
+  /** Absolute data root; exposed so startup checks can report and test it. */
+  readonly root: string;
+  private readonly runsDir: string;
+  private readonly chatsDir: string;
+  /** Serializes appends per run so event order matches emit order. */
+  private appendChains = new Map<string, Promise<void>>();
+  /** Serializes projects.json rewrites. */
+  private projectsChain: Promise<unknown> = Promise.resolve();
+
+  constructor(root: string = path.join(os.homedir(), '.foreman')) {
+    this.root = root;
+    this.runsDir = path.join(root, 'runs');
+    this.chatsDir = path.join(root, 'chats');
+  }
+
+  // -- projects -------------------------------------------------------------
+
+  private get projectsFile(): string {
+    return path.join(this.root, 'projects.json');
+  }
+
+  async listProjects(): Promise<Project[]> {
+    const raw = await readFile(this.projectsFile, 'utf8').catch(() => null);
+    if (!raw) return [];
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      return Array.isArray(parsed) ? (parsed as Project[]) : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /** Atomically rewrites projects.json through `mutate`; returns its result. */
+  private mutateProjects<T>(mutate: (projects: Project[]) => { projects: Project[]; result: T }): Promise<T> {
+    const task = this.projectsChain.then(async () => {
+      const { projects, result } = mutate(await this.listProjects());
+      await mkdir(this.root, { recursive: true });
+      const tmp = path.join(this.root, `.projects.${crypto.randomBytes(4).toString('hex')}.tmp`);
+      await writeFile(tmp, JSON.stringify(projects, null, 2));
+      await rename(tmp, this.projectsFile);
+      return result;
+    });
+    this.projectsChain = task.catch(() => {});
+    return task;
+  }
+
+  /** Links a folder as a project. Re-linking an already-linked folder returns
+   *  the existing project instead of duplicating it. */
+  /**
+   * Applies a partial change to one project. `provider: null` clears the pin
+   * (back to the server default) — distinct from `undefined`, which means
+   * "leave it alone", so the settings form can express both.
+   */
+  updateProject(
+    id: string,
+    patch: { name?: string; defaultBudgetUsd?: number; provider?: ProviderRef | null },
+  ): Promise<Project | null> {
+    return this.mutateProjects((projects) => {
+      const i = projects.findIndex((p) => p.id === id);
+      if (i === -1) return { projects, result: null };
+
+      const next: Project = { ...projects[i] };
+      if (patch.name?.trim()) next.name = patch.name.trim();
+      if (typeof patch.defaultBudgetUsd === 'number' && patch.defaultBudgetUsd > 0) {
+        next.defaultBudgetUsd = patch.defaultBudgetUsd;
+      }
+      if (patch.provider === null) {
+        delete next.provider;
+        // Drop the pre-provider pin too, or clearing would silently fall back
+        // to it through providerOf().
+        delete next.claudeInstance;
+      } else if (patch.provider) {
+        next.provider = patch.provider;
+        delete next.claudeInstance;
+      }
+
+      const updated = [...projects];
+      updated[i] = next;
+      return { projects: updated, result: next };
+    });
+  }
+
+  addProject(folder: string, name?: string, provider?: ProviderRef): Promise<Project> {
+    return this.mutateProjects((projects) => {
+      const existing = projects.find((p) => p.folder === folder);
+      if (existing) return { projects, result: existing };
+      const project: Project = {
+        id: `p-${crypto.randomBytes(6).toString('hex')}`,
+        name: name?.trim() || path.basename(folder),
+        folder,
+        createdAt: Date.now(),
+        defaultBudgetUsd: 5,
+        ...(provider ? { provider } : {}),
+      };
+      return { projects: [...projects, project], result: project };
+    });
+  }
+
+  /** Unlinks a project (run history is kept). Returns whether it existed. */
+  removeProject(projectId: string): Promise<boolean> {
+    return this.mutateProjects((projects) => {
+      const rest = projects.filter((p) => p.id !== projectId);
+      return { projects: rest, result: rest.length !== projects.length };
+    });
+  }
+
+  async getProject(projectId: string): Promise<Project | null> {
+    return (await this.listProjects()).find((p) => p.id === projectId) ?? null;
+  }
+
+  // -- settings -------------------------------------------------------------
+
+  private get settingsFile(): string {
+    return path.join(this.root, 'settings.json');
+  }
+
+  /** Reads persisted settings: a global object plus per-project overlays. */
+  async readSettings(): Promise<SettingsFile> {
+    const raw = await readFile(this.settingsFile, 'utf8').catch(() => null);
+    if (!raw) return { global: {}, projects: {} };
+    try {
+      const parsed = JSON.parse(raw) as Partial<SettingsFile>;
+      return { global: parsed.global ?? {}, projects: parsed.projects ?? {} };
+    } catch {
+      return { global: {}, projects: {} };
+    }
+  }
+
+  /** Atomically replaces settings.json (serialized like projects.json). */
+  writeSettings(settings: SettingsFile): Promise<void> {
+    const task = this.projectsChain.then(async () => {
+      await mkdir(this.root, { recursive: true });
+      const tmp = path.join(this.root, `.settings.${crypto.randomBytes(4).toString('hex')}.tmp`);
+      await writeFile(tmp, JSON.stringify(settings, null, 2));
+      await rename(tmp, this.settingsFile);
+    });
+    this.projectsChain = task.catch(() => {});
+    return task;
+  }
+
+  // -- runs -----------------------------------------------------------------
+
+  private runDir(runId: string): string {
+    if (!RUN_ID_RE.test(runId)) throw new Error(`invalid run id: ${runId}`);
+    return path.join(this.runsDir, runId);
+  }
+
+  /** Creates the run directory and writes initial metadata. */
+  async createRun(meta: RunMeta): Promise<void> {
+    await mkdir(this.runDir(meta.id), { recursive: true });
+    await this.writeMeta(meta);
+  }
+
+  /** Atomically replaces meta.json (tmp + rename). */
+  async writeMeta(meta: RunMeta): Promise<void> {
+    const dir = this.runDir(meta.id);
+    const tmp = path.join(dir, `.meta.${crypto.randomBytes(4).toString('hex')}.tmp`);
+    await writeFile(tmp, JSON.stringify(meta, null, 2));
+    await rename(tmp, path.join(dir, 'meta.json'));
+  }
+
+  /**
+   * Appends one event to the run's log. Returns a promise that resolves when
+   * the line is on disk; callers may fire-and-forget — order is preserved.
+   */
+  append(runId: string, event: ForemanEvent): Promise<void> {
+    const file = path.join(this.runDir(runId), 'events.jsonl');
+    const prev = this.appendChains.get(runId) ?? Promise.resolve();
+    const next = prev.then(() => appendFile(file, JSON.stringify(event) + '\n'));
+    // Keep the chain alive even if one append fails; the failure still
+    // surfaces to the caller awaiting `next`.
+    this.appendChains.set(runId, next.catch(() => {}));
+    return next;
+  }
+
+  async readMeta(runId: string): Promise<RunMeta | null> {
+    const raw = await readFile(path.join(this.runDir(runId), 'meta.json'), 'utf8')
+      .catch(() => null);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as RunMeta;
+    } catch {
+      return null; // unreadable meta is treated as missing, never fatal
+    }
+  }
+
+  /** Reads the full event log; skips lines that fail to parse (torn writes). */
+  async readEvents(runId: string): Promise<ForemanEvent[]> {
+    const raw = await readFile(path.join(this.runDir(runId), 'events.jsonl'), 'utf8')
+      .catch(() => '');
+    const events: ForemanEvent[] = [];
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        events.push(JSON.parse(line) as ForemanEvent);
+      } catch {
+        // A torn final line after a crash is expected; drop it.
+      }
+    }
+    return events;
+  }
+
+  /** Lists all runs, newest first. Reads only meta.json files. */
+  async listRuns(): Promise<RunSummary[]> {
+    const ids = await readdir(this.runsDir).catch(() => [] as string[]);
+    const metas = await Promise.all(
+      ids.filter((id) => RUN_ID_RE.test(id)).map((id) => this.readMeta(id)),
+    );
+    return metas
+      .filter((m): m is RunMeta => m !== null)
+      .sort((a, b) => b.id.localeCompare(a.id));
+  }
+
+  // -- chats ----------------------------------------------------------------
+
+  /**
+   * A project's planning conversation lives in the same two-file shape as a
+   * run: durable meta plus an append-only event log the UI replays. Project
+   * ids are generated by this store (`p-<hex>`), but they arrive here from
+   * request paths, so the same containment check a run id gets applies.
+   */
+  private chatDir(projectId: string): string {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(projectId)) throw new Error(`invalid project id: ${projectId}`);
+    return path.join(this.chatsDir, projectId);
+  }
+
+  async readChatMeta(projectId: string): Promise<ChatMeta | null> {
+    const raw = await readFile(path.join(this.chatDir(projectId), 'meta.json'), 'utf8')
+      .catch(() => null);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as ChatMeta;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Atomically replaces a chat's meta.json, creating the directory if needed. */
+  async writeChatMeta(meta: ChatMeta): Promise<void> {
+    const dir = this.chatDir(meta.projectId);
+    await mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.meta.${crypto.randomBytes(4).toString('hex')}.tmp`);
+    await writeFile(tmp, JSON.stringify(meta, null, 2));
+    await rename(tmp, path.join(dir, 'meta.json'));
+  }
+
+  /** Appends one event to a project's chat log, serialized like a run's. */
+  appendChat(projectId: string, event: ForemanEvent): Promise<void> {
+    const key = `chat:${projectId}`;
+    const file = path.join(this.chatDir(projectId), 'events.jsonl');
+    const prev = this.appendChains.get(key) ?? Promise.resolve();
+    const next = prev
+      .then(() => mkdir(this.chatDir(projectId), { recursive: true }))
+      .then(() => appendFile(file, JSON.stringify(event) + '\n'));
+    this.appendChains.set(key, next.catch(() => {}));
+    return next;
+  }
+
+  /** Every project id that has a planning conversation on disk. */
+  async listChatIds(): Promise<string[]> {
+    const names = await readdir(this.chatsDir).catch(() => [] as string[]);
+    return names.filter((n) => !n.startsWith('.'));
+  }
+
+  /** Reads a chat's full event log; skips lines that fail to parse. */
+  async readChatEvents(projectId: string): Promise<ForemanEvent[]> {
+    const raw = await readFile(path.join(this.chatDir(projectId), 'events.jsonl'), 'utf8')
+      .catch(() => '');
+    const events: ForemanEvent[] = [];
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        events.push(JSON.parse(line) as ForemanEvent);
+      } catch {
+        // A torn final line after a crash is expected; drop it.
+      }
+    }
+    return events;
+  }
+
+  /**
+   * Forgets a conversation: the log and the session id both go, so the next
+   * message starts a genuinely new session rather than resuming a cleared one.
+   */
+  async clearChat(projectId: string): Promise<void> {
+    await rm(this.chatDir(projectId), { recursive: true, force: true });
+  }
+
+  /**
+   * Marks runs left in status "running" by a dead process as interrupted,
+   * appending a synthetic `run_finished` so replayed logs terminate cleanly.
+   * Returns the ids of swept runs.
+   */
+  async sweepOrphans(): Promise<string[]> {
+    const swept: string[] = [];
+    for (const meta of await this.listRuns()) {
+      if (meta.status !== 'running') continue;
+      const ended: RunMeta = { ...meta, status: 'interrupted', endedAt: Date.now() };
+      await this.append(meta.id, {
+        ts: Date.now(),
+        event: 'run_finished',
+        data: { status: 'interrupted', costUsd: meta.costUsd, reason: 'server restarted' },
+      });
+      await this.writeMeta(ended);
+      swept.push(meta.id);
+    }
+    return swept;
+  }
+}

package/src/tailscale.test.ts

@@ -0,0 +1,32 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { isTailscaleIp, parseTailscaleStatus, tailnetFromInterfaces, tailnetUrl } from './tailscale.js';
+
+test('isTailscaleIp: only 100.64.0.0/10', () => {
+  assert.equal(isTailscaleIp('100.94.221.98'), true);
+  assert.equal(isTailscaleIp('100.64.0.1'), true);
+  assert.equal(isTailscaleIp('100.127.255.255'), true);
+  assert.equal(isTailscaleIp('100.128.0.1'), false);
+  assert.equal(isTailscaleIp('100.63.0.1'), false);
+  assert.equal(isTailscaleIp('192.168.1.10'), false);
+});
+
+test('parseTailscaleStatus: running with an address and a name; stopped is null', () => {
+  const t = parseTailscaleStatus({ BackendState: 'Running', Self: { DNSName: 'laptop.tail1234.ts.net.', TailscaleIPs: ['100.94.221.98', 'fd7a::1'] } });
+  assert.deepEqual(t, { ip: '100.94.221.98', dnsName: 'laptop.tail1234.ts.net' });
+  assert.equal(parseTailscaleStatus({ BackendState: 'Stopped', Self: { TailscaleIPs: ['100.94.221.98'] } }), null);
+  assert.equal(parseTailscaleStatus({ BackendState: 'Running', Self: { TailscaleIPs: [] } }), null);
+  assert.equal(parseTailscaleStatus(null), null);
+  assert.equal(tailnetUrl(t!, 4177), 'http://laptop.tail1234.ts.net:4177');
+  assert.equal(tailnetUrl({ ip: '100.1.2.3' }, 4177), 'http://100.1.2.3:4177');
+});
+
+test('tailnetFromInterfaces: finds the CGNAT address, ignores loopback and LAN', () => {
+  const t = tailnetFromInterfaces({
+    lo0: [{ address: '127.0.0.1', family: 'IPv4', internal: true } as never],
+    en0: [{ address: '192.168.1.5', family: 'IPv4', internal: false } as never],
+    utun4: [{ address: '100.94.221.98', family: 'IPv4', internal: false } as never],
+  });
+  assert.deepEqual(t, { ip: '100.94.221.98' });
+  assert.equal(tailnetFromInterfaces({ en0: [{ address: '192.168.1.5', family: 'IPv4', internal: false } as never] }), null);
+});

package/src/tailscale.ts

@@ -0,0 +1,79 @@
+/**
+ * Is this machine on a tailnet, and what is it called there?
+ *
+ * Foreman has no login. Listening on every interface would put the dashboard
+ * on whatever Wi-Fi the laptop joins; listening on loopback alone leaves the
+ * phone out. Tailscale is the middle: a private network of the user's own
+ * devices, with a stable name. When it is present Foreman listens on it too,
+ * and the links it sends to the phone use that name — the phone can open
+ * them from anywhere the tailnet reaches.
+ *
+ * Detection is read-only and best-effort: the CLI's `status --json` when a
+ * CLI exists (PATH, or the Mac app's bundle), else an interface holding an
+ * address in Tailscale's 100.64.0.0/10 range. Never an install, never a
+ * login — those are the user's, in Tailscale's own UI.
+ */
+import { execFile } from 'node:child_process';
+import os from 'node:os';
+
+export interface Tailnet {
+  /** The IPv4 address on the tailnet, e.g. `100.94.221.98`. */
+  ip: string;
+  /** MagicDNS name without the trailing dot, e.g. `laptop.tail1234.ts.net`. */
+  dnsName?: string;
+}
+
+/** True for addresses in 100.64.0.0/10, the CGNAT range Tailscale hands out. */
+export function isTailscaleIp(ip: string): boolean {
+  const m = /^100\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/.exec(ip);
+  if (!m) return false;
+  const second = Number(m[1]);
+  return second >= 64 && second <= 127;
+}
+
+/** The parts of `tailscale status --json` Foreman reads; null when not running or unusable. */
+export function parseTailscaleStatus(json: unknown): Tailnet | null {
+  const d = json as { BackendState?: string; Self?: { DNSName?: string; TailscaleIPs?: string[] } } | null;
+  if (!d || d.BackendState !== 'Running') return null;
+  const ip = (d.Self?.TailscaleIPs ?? []).find(isTailscaleIp);
+  if (!ip) return null;
+  const dns = (d.Self?.DNSName ?? '').replace(/\.$/, '');
+  return { ip, ...(dns ? { dnsName: dns } : {}) };
+}
+
+/** An interface carrying a tailnet address, when the CLI is not around to ask. */
+export function tailnetFromInterfaces(ifaces: NodeJS.Dict<os.NetworkInterfaceInfo[]> = os.networkInterfaces()): Tailnet | null {
+  for (const list of Object.values(ifaces)) {
+    for (const i of list ?? []) {
+      if (i.family === 'IPv4' && !i.internal && isTailscaleIp(i.address)) return { ip: i.address };
+    }
+  }
+  return null;
+}
+
+const CLI_CANDIDATES = [
+  'tailscale',
+  '/Applications/Tailscale.app/Contents/MacOS/Tailscale',
+  'C:\\Program Files\\Tailscale\\tailscale.exe',
+];
+
+function run(cmd: string, args: string[], timeoutMs: number): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => resolve(err ? null : String(stdout)));
+  });
+}
+
+/** The tailnet this machine is on, or null. Read-only; a few seconds at most. */
+export async function detectTailscale(): Promise<Tailnet | null> {
+  for (const cmd of CLI_CANDIDATES) {
+    const out = await run(cmd, ['status', '--json'], 3_000);
+    if (!out) continue;
+    try { const t = parseTailscaleStatus(JSON.parse(out)); if (t) return t; } catch { /* not JSON — try the next */ }
+  }
+  return tailnetFromInterfaces();
+}
+
+/** `http://laptop.tail1234.ts.net:4177` — the name when there is one, the address otherwise. */
+export function tailnetUrl(t: Tailnet, port: number): string {
+  return `http://${t.dnsName ?? t.ip}:${port}`;
+}

package/src/title.ts

@@ -0,0 +1,138 @@
+/**
+ * Mission titles.
+ *
+ * A brief is a paragraph of instructions; a run list needs a name. Clipping
+ * the brief mid-word ("Design a high-end fitness studio bran…") reads as an
+ * accident, so once per run Foreman asks the cheapest model for a short label
+ * and persists it in run metadata.
+ *
+ * Three properties matter more than the title itself:
+ *  - It is never load-bearing. The call is fire-and-forget and every failure
+ *    path returns null, leaving the UI to fall back to the brief.
+ *  - It bills the same provider as the mission it names, so a project pinned to
+ *    its own login does not quietly charge someone else a fraction of a cent.
+ *  - It costs what it costs, visibly: the caller folds the reported spend into
+ *    the run's cost rather than hiding it.
+ */
+import os from 'node:os';
+import { query, type SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { AgentEnv } from './provider.js';
+
+/** Cheapest model in the roster — the whole point of the exercise. */
+const TITLE_MODEL = 'haiku';
+
+/** Titles longer than this are a summary, not a name. */
+const MAX_TITLE_CHARS = 60;
+
+/** A stuck subprocess must not leak; the title is optional, so give up early. */
+// Generous on purpose. Nothing waits on the title, and a slow first call on
+// a cloud gateway (test-4's kimi took 114 s to answer its first turn) is not
+// a reason to leave a run named by its brief for good.
+const TIMEOUT_MS = 150_000;
+
+const SYSTEM_PROMPT =
+  'You name software missions. You reply with the title and nothing else: no ' +
+  'preamble, no quotes, no trailing period, no markdown.';
+
+export interface RunTitle {
+  title: string;
+  /** What the naming call itself cost, for the run's ledger. */
+  costUsd: number;
+}
+
+/** Collapses model output into a single short line, or null if unusable. */
+function cleanTitle(raw: string): string | null {
+  const line = raw.trim().split('\n').find((l) => l.trim()) ?? '';
+  const cleaned = line
+    .replace(/^["'`*\s]+|["'`*\s.]+$/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!cleaned || cleaned.length < 3) return null;
+  return cleaned.length > MAX_TITLE_CHARS
+    ? cleaned.slice(0, MAX_TITLE_CHARS - 1).trimEnd() + '…'
+    : cleaned;
+}
+
+/**
+ * Asks the cheap model to name a mission. Resolves to null on any failure —
+ * no auth, no network, a timeout, or a model that answered with prose.
+ *
+ * Runs with no tools, no setting sources, and a temp cwd: this call must not
+ * read the project, and giving it nothing to read is cheaper than trusting it
+ * not to.
+ */
+export async function generateRunTitle(
+  mission: string,
+  agentEnv: AgentEnv,
+): Promise<RunTitle | null> {
+  const brief = mission.trim().slice(0, 2000);
+  if (!brief) return null;
+
+  const prompt =
+    'Name this mission in 3-7 words — a title someone can pick out of a list, ' +
+    'naming the concrete thing being built or changed. Reply with the title only.\n\n' +
+    `MISSION:\n${brief}`;
+
+  let q: ReturnType<typeof query> | undefined;
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    void (q as AsyncGenerator<SDKMessage> | undefined)?.return?.(undefined as never)
+      .catch(() => {});
+  }, TIMEOUT_MS);
+
+  try {
+    q = query({
+      prompt,
+      options: {
+        model: TITLE_MODEL,
+        maxTurns: 1,
+        // Everything below strips context this call has no use for. It is not
+        // tidiness: the same request with the default harness context loaded
+        // (Claude Code's tools plus the account's claude.ai connectors) costs
+        // around 100x more than the ~$0.0003 it costs stripped, because the
+        // tool definitions dwarf the paragraph being named.
+        tools: [],
+        allowedTools: [],
+        mcpServers: {},
+        strictMcpConfig: true,
+        settings: { disableClaudeAiConnectors: true },
+        // A title is a lookup, not a problem: reasoning tokens here cost more
+        // than the answer is worth.
+        thinking: { type: 'disabled' },
+        // A plain string prompt opts out of the claude_code preset; with no
+        // setting sources, the user's CLAUDE.md and plugins stay out too.
+        systemPrompt: SYSTEM_PROMPT,
+        settingSources: [],
+        cwd: os.tmpdir(),
+        ...agentEnv,
+      },
+    });
+
+    let text = '';
+    let costUsd = 0;
+    for await (const msg of q as AsyncIterable<SDKMessage>) {
+      const m = msg as Record<string, unknown>;
+      if (m.type === 'assistant') {
+        const content = (m.message as { content?: Array<Record<string, unknown>> })?.content ?? [];
+        for (const b of content) if (b.type === 'text') text += String(b.text ?? '');
+      } else if (m.type === 'result') {
+        if (typeof m.total_cost_usd === 'number') costUsd = m.total_cost_usd;
+        if (m.is_error) { console.warn(`[title] model returned an error: ${String(m.result ?? m.subtype ?? '').slice(0, 200)}`); return null; }
+      }
+    }
+
+    const title = cleanTitle(text);
+    if (!title) console.warn(`[title] ${timedOut ? `no answer within ${TIMEOUT_MS / 1000}s` : text.trim() ? `unusable reply: ${JSON.stringify(text.slice(0, 120))}` : 'empty reply'}`);
+    return title ? { title, costUsd } : null;
+  } catch (e) {
+    // A name is never worth failing a mission over — but a silent failure
+    // left a run un-named twice with nothing to go on. Say why, once.
+    console.warn(`[title] failed: ${(e as Error)?.message ?? e}`);
+    return null;
+  } finally {
+    clearTimeout(timer);
+    await (q as AsyncGenerator<SDKMessage> | undefined)?.return?.(undefined as never)
+      .catch(() => {});
+  }
+}