@opsee/cli 0.11.12 → 0.11.18

package/src/foreman/usage-store.ts

@@ -0,0 +1,213 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mergeObservation, type AccountUsage, type ActivityTurn, type UsageWindow } from "./usage.js";
+
+/**
+ * Where per-Account usage is kept (the multi-account headroom design, §2).
+ *
+ * Deliberately **not** a field on `Account`. The accounts file is a registry: written rarely, by
+ * humans, through `FileAccountStore.save`, whose own comment says what it does not buy — the write
+ * is atomic but the read-modify-write is not, so "the later save wins whole". Usage is telemetry,
+ * written constantly by a poller and by every Run that sees a `rate_limit_event`, and putting it
+ * there would lose an operator's `account set --cap` to a poll.
+ *
+ * There is no `save(all)` on this interface on purpose: a writer states what it observed about one
+ * Account and the store folds it in (`mergeObservation`), so no writer can write a snapshot of the
+ * whole world and flatten another's Account.
+ */
+export interface UsageStore {
+  /** Every Account the store knows about. Unreadable records are skipped, never thrown. */
+  load(): AccountUsage[];
+  loadOne(account: string): AccountUsage | undefined;
+  /** Folds one observation in and returns the merged record. `activity` carries the turns this
+   * Foreman ran
+   * (usage-activity.ts); a write may carry windows, turns, or both. */
+  observe(account: string, windows: Record<string, UsageWindow>, now: number, activity?: { turns: ActivityTurn[] }): AccountUsage;
+  /** Notes that a poll failed, touching no window (a failing poll means the Foreman knows less, not
+   * that the Account is spent). `backoffUntil` is set when the endpoint rate-limited us; nothing
+   * asks again before it. */
+  noteFailure(account: string, at: Date, reason: string, backoffUntil?: Date): AccountUsage;
+}
+
+/** The store's own directory, overridable for tests and for a daemon run out of tree. Sibling of
+ * the accounts file and of the credentials file the mcp auth module keeps, never inside either. */
+export function usageDirPath(): string {
+  return process.env.OPSEE_FOREMAN_USAGE_DIR || join(homedir(), ".opsee", "foreman-usage");
+}
+
+interface UsageFile {
+  version: 1;
+  usage: AccountUsage;
+}
+
+/**
+ * The Account names this store will touch: exactly `NAME_PATTERN` from account.ts, re-stated as a
+ * file-name guard rather than imported, because what matters here is not "is this a valid Account"
+ * but "is this safe to join onto a path". A registered Account always passes; a name from a
+ * hand-edited file or a future caller that does not is refused rather than escaping the directory.
+ */
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function safeName(account: string): string {
+  if (!SAFE_NAME.test(account) || account.includes("..")) {
+    throw new Error(`Account name "${account}" cannot be used as a usage file name`);
+  }
+  return account;
+}
+
+export class MemoryUsageStore implements UsageStore {
+  private records = new Map<string, AccountUsage>();
+
+  load(): AccountUsage[] {
+    return [...this.records.values()].map(clone);
+  }
+
+  loadOne(account: string): AccountUsage | undefined {
+    const record = this.records.get(account);
+    return record ? clone(record) : undefined;
+  }
+
+  observe(account: string, windows: Record<string, UsageWindow>, now: number, activity?: { turns: ActivityTurn[] }): AccountUsage {
+    const merged = mergeObservation(this.records.get(account) ?? empty(account), windows, now, activity);
+    this.records.set(account, merged);
+    return clone(merged);
+  }
+
+  noteFailure(account: string, at: Date, reason: string, backoffUntil?: Date): AccountUsage {
+    const record = {
+      ...(this.records.get(account) ?? empty(account)),
+      pollFailedAt: at.toISOString(),
+      pollFailure: reason,
+      ...(backoffUntil ? { pollBackoffUntil: backoffUntil.toISOString() } : {}),
+    };
+    this.records.set(account, record);
+    return clone(record);
+  }
+}
+
+/**
+ * One JSON file per Account under one directory, written through a temp file that is renamed over
+ * the target — the same idiom, envelope and modes as `FileAccountStore`.
+ *
+ * One file per Account rather than one file for all of them because this store has two writers: the
+ * poller in the daemon, and whichever Run saw an in-band observation. Separate files mean they can
+ * never lose each other's Accounts; `mergeObservation` is what settles the case where they write
+ * the same Account's window.
+ *
+ * A record it cannot read is no record. Usage is telemetry, and telemetry must not be able to stop
+ * a Run: the Foreman's fallback is the reactive behaviour it had before any of this existed.
+ */
+export class FileUsageStore implements UsageStore {
+  constructor(private readonly dir: string) {}
+
+  load(): AccountUsage[] {
+    if (!existsSync(this.dir)) return [];
+    let entries: string[];
+    try {
+      entries = readdirSync(this.dir);
+    } catch {
+      return [];
+    }
+    const records: AccountUsage[] = [];
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      const record = this.read(join(this.dir, entry));
+      if (record) records.push(record);
+    }
+    return records;
+  }
+
+  loadOne(account: string): AccountUsage | undefined {
+    return this.read(this.pathFor(account));
+  }
+
+  observe(account: string, windows: Record<string, UsageWindow>, now: number, activity?: { turns: ActivityTurn[] }): AccountUsage {
+    // Read-modify-write against this Account's own file. Two writers on one Account can still
+    // interleave here; the merge rule is what makes the outcome of that deterministic rather than
+    // whichever process happened to finish last, and a lost in-band observation costs one tick.
+    const merged = mergeObservation(this.loadOne(account) ?? empty(account), windows, now, activity);
+    this.write(account, merged);
+    return merged;
+  }
+
+  noteFailure(account: string, at: Date, reason: string, backoffUntil?: Date): AccountUsage {
+    const record = {
+      ...(this.loadOne(account) ?? empty(account)),
+      pollFailedAt: at.toISOString(),
+      pollFailure: reason,
+      ...(backoffUntil ? { pollBackoffUntil: backoffUntil.toISOString() } : {}),
+    };
+    this.write(account, record);
+    return record;
+  }
+
+  private pathFor(account: string): string {
+    return join(this.dir, `${safeName(account)}.json`);
+  }
+
+  private read(path: string): AccountUsage | undefined {
+    let text: string;
+    try {
+      // A directory named `*.json`, a dangling symlink, a file another user owns: all of them are
+      // "no usage", the same as a file whose JSON does not parse.
+      if (!statSync(path).isFile()) return undefined;
+      text = readFileSync(path, "utf-8");
+    } catch {
+      return undefined;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return undefined;
+    }
+    const file = parsed as Partial<UsageFile> | null;
+    if (!file || file.version !== 1) return undefined;
+    const usage = file.usage as Partial<AccountUsage> | undefined;
+    if (!usage || typeof usage.account !== "string" || typeof usage.windows !== "object" || usage.windows === null) {
+      return undefined;
+    }
+    return usage as AccountUsage;
+  }
+
+  private write(account: string, usage: AccountUsage): void {
+    const path = this.pathFor(account);
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    const file: UsageFile = { version: 1, usage };
+    const temp = `${path}.${process.pid}.tmp`;
+    try {
+      writeFileSync(temp, JSON.stringify(file, null, 2) + "\n", { mode: 0o600, encoding: "utf-8" });
+      renameSync(temp, path);
+    } catch (error) {
+      try {
+        rmSync(temp, { force: true });
+      } catch {
+        /* the write's error is the one worth reporting */
+      }
+      throw error;
+    }
+  }
+}
+
+function empty(account: string): AccountUsage {
+  return { account, windows: {} };
+}
+
+function clone(usage: AccountUsage): AccountUsage {
+  return { ...usage, windows: { ...usage.windows }, ...(usage.activity ? { activity: { turns: [...usage.activity.turns] } } : {}) };
+}
+
+/**
+ * Everything the store knows, keyed by Account name.
+ *
+ * Every reader wants this shape and none wants the list: the Run ranks Lanes by it, `account usage`
+ * and `account list` print by it, and the launcher chooses by it. All three had built the same Map
+ * by hand. An absent store is an empty Map rather than an error, which is what keeps usage an
+ * optimisation and never a dependency.
+ */
+export function usageByAccount(store: UsageStore | undefined): Map<string, AccountUsage> {
+  const known = new Map<string, AccountUsage>();
+  for (const record of store?.load() ?? []) known.set(record.account, record);
+  return known;
+}

package/src/foreman/usage.ts

@@ -0,0 +1,257 @@
+import { mergeActivity } from "./usage-activity.js";
+/**
+ * What the Foreman knows about how much of an Account's quota is gone (the multi-account headroom
+ * design, docs/superpowers/specs/2026-09-12-multi-account-headroom-design.md).
+ *
+ * Pure: no file system, no clock of its own, no vendor. Everything here is a function of a stored
+ * record and a `now`, so the ranking and holding decisions built on it (core/scheduler.ts,
+ * core/run.ts) are testable without a network or a credential.
+ *
+ * Nothing in this module reads a credential. The one module that does is usage-poller.ts, and it
+ * hands its result here as plain numbers (ADR-0013 and its amendment).
+ */
+
+/** Where an observation came from, and — via `SOURCE_RANK` — how much it is trusted. */
+export type UsageSourceKind = "polled" | "in_band";
+
+
+/**
+ * How far an observation outranks another of the same window.
+ *
+ * `in_band` is highest because it is not an observation at all but a report: the vendor said it to a
+ * Worker that was running at that moment. `polled` is a measurement of an Account nobody is using.
+ *
+ * There is deliberately no third, estimated source. The design sketched one, from the Foreman's own
+ * turn counts, and usage-activity.ts says why it is not built: turns and dollars cannot be turned
+ * into a share of a window without the plan's limit, which nothing here knows.
+ */
+const SOURCE_RANK: Record<UsageSourceKind, number> = { in_band: 2, polled: 1 };
+
+/** One rate-limit window as the vendor names it. */
+export interface UsageWindow {
+  /** How much of the window is spent, 0–100. A vendor number above 100 is kept as given and
+   * clamped where it is used (`headroom`), so the stored record stays what was actually reported. */
+  usedPct: number;
+  /** When this window resets, ISO 8601. A window whose reset has passed is not a window. */
+  resetsAt: string;
+  /** When the observation was made, ISO 8601, so a reader can say "6m ago". */
+  observedAt: string;
+  source: UsageSourceKind;
+}
+
+/** One turn the Foreman ran on an Account (usage-activity.ts). */
+export interface ActivityTurn {
+  at: string;
+  /** What the vendor said the turn cost, when it said. A turn with no cost is still a turn. */
+  costUsd?: number;
+}
+
+/** Everything known about one Account's quota. Keyed by name, one file each (usage-store.ts). */
+export interface AccountUsage {
+  account: string;
+  /**
+   * Keyed by the vendor's own `rateLimitType` — "five_hour", "seven_day", a per-model weekly — so a
+   * window the vendor invents needs no change here. Claude Code emits that string on
+   * `rate_limit_event`, and the poller reports whatever the endpoint names.
+   */
+  windows: Record<string, UsageWindow>;
+  /** The last poll that failed, and its words. Carried so `account usage` can show why a number is
+   * stale, and deliberately never a reason to hold an Account back: a failing poll means the
+   * Foreman knows less, not that the Account is spent. */
+  pollFailedAt?: string;
+  pollFailure?: string;
+  /** Set when the usage endpoint rate-limited us: nothing asks again before this moment, not the
+   * poller and not a human running `account usage --refresh` (usage-poller.ts). */
+  pollBackoffUntil?: string;
+  /** What this Foreman has itself spent on the Account (usage-activity.ts). Advisory: it is never a
+   * window, never a percentage, and nothing ranks or holds an Account by it. */
+  activity?: { turns: ActivityTurn[] };
+}
+
+/**
+ * How much of an Account is left to spend, or that nothing is known.
+ *
+ * `unknown` is not zero. An API-key Account reports no windows at all and is not rate limited by
+ * anything the Foreman can see; a subscription Account nobody has run yet is in the same position.
+ * Both must stay dispatchable — they rank below a measured Account (core/scheduler.ts) and are
+ * never held back.
+ */
+export type Headroom =
+  | { kind: "known"; remainingPct: number; tightest: string; resetsAt: string; observedAt: string }
+  | { kind: "unknown" };
+
+/**
+ * The furthest ahead a window's reset is believed.
+ *
+ * The longest window any vendor here reports is seven days, so anything past eight is not a window
+ * — it is a corrupt record, a hand-edited file, or a unit mistaken for another. Trusting one would
+ * hold an Account back until that date: `thresholdHold` has no natural ceiling of its own, where
+ * the vendor's own pauses are capped at `MAX_PAUSE_MS` (account.ts) for exactly this reason.
+ */
+export const MAX_WINDOW_MS = 8 * 24 * 60 * 60_000;
+
+/**
+ * True while this window still describes something: it holds real numbers, and its reset is ahead
+ * of `now` but not absurdly so.
+ *
+ * Everything that is not believable reads as expired, which loses one observation rather than
+ * acting on it. A `usedPct` that is not a number, an unparseable `resetsAt`, a reset years out — a
+ * hand-edited file, a truncated write, a future vendor field — all of them mean the Foreman knows
+ * less about this Account, never that the Account should stop being used.
+ */
+function isLive(window: UsageWindow, now: number): boolean {
+  if (typeof window?.usedPct !== "number" || !Number.isFinite(window.usedPct)) return false;
+  const resetsAt = Date.parse(window?.resetsAt);
+  return Number.isFinite(resetsAt) && resetsAt > now && resetsAt - now <= MAX_WINDOW_MS;
+}
+
+/**
+ * The Account's headroom: what is left of its **tightest** live window.
+ *
+ * The minimum, not an average, because a limit is a limit — an Account at 20% of its five-hour and
+ * 98% of its seven-day has 2% to spend, and dispatching it as though it had 41% would walk it into
+ * the weekly wall. Windows that have already reset are ignored rather than trusted.
+ */
+export function headroom(usage: AccountUsage | undefined, now: number): Headroom {
+  if (!usage) return { kind: "unknown" };
+  let tightest: { name: string; window: UsageWindow } | undefined;
+  for (const [name, window] of Object.entries(usage.windows)) {
+    if (!isLive(window, now)) continue;
+    if (!tightest || window.usedPct > tightest.window.usedPct) tightest = { name, window };
+  }
+  if (!tightest) return { kind: "unknown" };
+  return {
+    kind: "known",
+    // Clamped both ways: a vendor percentage past 100 would otherwise become negative headroom,
+    // which sorts below an exhausted Account and reads as nonsense in `account usage`.
+    remainingPct: Math.max(0, Math.min(100, 100 - tightest.window.usedPct)),
+    tightest: tightest.name,
+    resetsAt: tightest.window.resetsAt,
+    observedAt: tightest.window.observedAt,
+  };
+}
+
+/**
+ * Folds one observation into a stored record, window by window, and returns a new record.
+ *
+ * This is where "in-band always wins" lives, once, rather than at each call site. Two processes
+ * write an Account's usage — the poller in the daemon and whichever Run saw a `rate_limit_event` —
+ * and per-Account files (usage-store.ts) keep them from clobbering each other's Accounts, but not
+ * each other's windows. This rule is what makes that collision deterministic instead of
+ * last-write-wins:
+ *
+ * - a window the record does not have is taken;
+ * - a window whose stored reset has passed is replaced by anything, since the stored observation
+ *   describes a window that no longer exists and the incoming one describes the new one;
+ * - otherwise the incoming window must come from a source that ranks at least as high, and within
+ *   one source it must be newer.
+ */
+export function mergeObservation(
+  stored: AccountUsage,
+  observed: Record<string, UsageWindow>,
+  now: number,
+  activity?: { turns: ActivityTurn[] },
+): AccountUsage {
+  const windows: Record<string, UsageWindow> = { ...stored.windows };
+  for (const [name, incoming] of Object.entries(observed)) {
+    const current = windows[name];
+    if (current === undefined || !isLive(current, now) || wins(incoming, current)) {
+      windows[name] = incoming;
+    }
+  }
+  // An observation arriving at all is the answer the failed poll was after, so the failure stops
+  // being worth reporting; `account usage` shows a live number instead of a stale one and a reason.
+  // A write that carries only activity turns is not an observation, so it leaves the failure standing.
+  //
+  // `pollBackoffUntil` goes with them. It used to ride through in the rest, so an Account that was
+  // rate limited once kept the window even after a poll succeeded — and with an unbounded
+  // `Retry-After` that was a state nothing could leave (`MAX_BACKOFF_MS`, usage-poller.ts).
+  const carriesWindows = Object.keys(observed).length > 0;
+  const { pollFailedAt, pollFailure, pollBackoffUntil, ...rest } = stored;
+  const base = carriesWindows ? rest : stored;
+  if (!activity) return { ...base, windows };
+  // Both sides' turns, so a Run recording one and the poller writing a window at the same moment
+  // cannot lose each other's work (usage-activity.ts `mergeActivity`).
+  return { ...base, windows, activity: { turns: mergeActivity(stored.activity?.turns, activity.turns, now) } };
+}
+
+/** Whether `incoming` replaces `current` for the same live window: a higher-ranked source, or the
+ * same source with something newer to say. */
+function wins(incoming: UsageWindow, current: UsageWindow): boolean {
+  const byRank = SOURCE_RANK[incoming.source] - SOURCE_RANK[current.source];
+  if (byRank !== 0) return byRank > 0;
+  return Date.parse(incoming.observedAt) >= Date.parse(current.observedAt);
+}
+
+/** A hold the Foreman has decided on: which window breached, by how much, and when it resets. */
+export interface ThresholdHold {
+  window: string;
+  usedPct: number;
+  until: Date;
+  /** When the breaching observation was made. Carried here so a caller that reports the hold does
+   * not have to reach back into the record's windows to find out how old the number is. */
+  observedAt: string;
+  /** The breach in the words a human reads on `account list`: "93% of seven_day". */
+  reason: string;
+}
+
+/**
+ * Whether this Account should be held back before the vendor refuses it, and until when.
+ *
+ * **Derived, never stored.** A hold is a function of what is known about usage and of the policy in
+ * force at the moment it is asked, so raising `--threshold` lifts one with nothing to clear, a
+ * window resetting lifts one by itself, and there is no way to leave a stale hold on an Account
+ * that is fine. That is the whole reason this is not written into the Paused state beside a vendor
+ * refusal, which *is* stored because it is a fact about something that already happened.
+ *
+ * The tightest breaching window wins, and the hold lasts until **that** window's reset — not the
+ * soonest reset of any window, which would put the Account back in rotation still spent.
+ *
+ * Nothing known is never a hold (`headroom` answers `unknown`, an API-key Account reports nothing),
+ * and neither is a failed poll: knowing less about an Account is not evidence against it.
+ */
+export function thresholdHold(usage: AccountUsage | undefined, thresholdPct: number, now: number): ThresholdHold | undefined {
+  if (!usage) return undefined;
+  let worst: { name: string; window: UsageWindow } | undefined;
+  for (const [name, window] of Object.entries(usage.windows)) {
+    if (!isLive(window, now)) continue;
+    if (window.usedPct < thresholdPct) continue;
+    if (!worst || window.usedPct > worst.window.usedPct) worst = { name, window };
+  }
+  if (!worst) return undefined;
+  const usedPct = worst.window.usedPct;
+  return { window: worst.name, usedPct, until: new Date(worst.window.resetsAt), observedAt: worst.window.observedAt, reason: `${usedPct}% of ${worst.name}` };
+}
+
+/**
+ * How far off a moment is, for a reader: "now", "in 14m", "in 2h14m", "in 5d".
+ *
+ * Beside `describeAge` and for the same reason: a reset printed as an ISO timestamp makes a reader
+ * do arithmetic against a clock in another timezone to answer "can I use this Account yet".
+ */
+export function describeUntil(at: string, now: number): string {
+  const ms = Date.parse(at) - now;
+  if (!Number.isFinite(ms)) return "at an unknown time";
+  if (ms <= 0) return "now";
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `in ${Math.max(1, minutes)}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `in ${hours}h${minutes % 60 === 0 ? "" : `${minutes % 60}m`}`;
+  return `in ${Math.floor(hours / 24)}d`;
+}
+
+/** How long ago an observation was made, for a reader: "just now", "6m ago", "3h ago". Rounded
+ * down, so a number is never reported as fresher than it is. */
+export function describeAge(observedAt: string, now: number): string {
+  const ms = now - Date.parse(observedAt);
+  // A timestamp that is not a date is not a fresh one: reporting it as "just now" would print an
+  // unknown freshness as the freshest there is, which is the one reading that misleads. A stamp in
+  // the *future* is the same mistake wearing a sign: `ms < 60_000` is true of every negative
+  // number, so a skewed clock read as the freshest possible number.
+  if (!Number.isFinite(ms) || ms < 0) return "at an unknown time";
+  if (ms < 60_000) return "just now";
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  return hours < 48 ? `${hours}h ago` : `${Math.floor(hours / 24)}d ago`;
+}

package/src/foreman/vendor.ts

@@ -21,3 +21,26 @@ export const VENDOR_CONFIG_DIR_ENV: Readonly<Record<Vendor, string>> = {
 export function isVendor(value: string): value is Vendor {
   return (VENDORS as readonly string[]).includes(value);
 }
+
+/**
+ * The binary each vendor's CLI is invoked as. The Worker Adapters already know theirs; this is for
+ * the one place outside them that has to launch a vendor — `account add --login`, which runs the
+ * vendor's own interactive login in a fresh config directory.
+ */
+export const VENDOR_BINARY: Readonly<Record<Vendor, string>> = {
+  claude: "claude",
+  codex: "codex",
+};
+
+/**
+ * The file a vendor keeps its credential in, **where it keeps one in a file at all**.
+ *
+ * Not a universal truth, and assuming it was is what shipped a broken `account add --login`: on
+ * macOS, Claude Code writes no such file and keeps the credential in a Keychain item it derives
+ * from the config directory instead. `credential-store.ts` decides which store applies, and is the
+ * only module that should use this.
+ */
+export const VENDOR_CREDENTIAL_FILE: Readonly<Record<Vendor, string>> = {
+  claude: ".credentials.json",
+  codex: "auth.json",
+};

package/src/foreman/worker-adapter.ts

@@ -10,6 +10,7 @@
  */
 import type { Account } from "./account.js";
 import type { CompletionReport } from "./completion-report.js";
+import type { UsageWindow } from "./usage.js";
 
 /** One unattended turn of a Worker. The Foreman pins the working directory to the Workspace and
  * says which Account the Worker runs under; the adapter turns that into a vendor launch. */
@@ -105,6 +106,17 @@ export type AdapterEvent =
   /** The vendor reported a rate limit. `resetAt` is ISO 8601 when the vendor said when it lifts;
    * the scheduler marks the Account Paused until then (or a default when unknown). */
   | { type: "rate_limited"; resetAt?: string; message: string }
+  /**
+   * What the vendor said about how much of this Account's quota is gone (the multi-account headroom
+   * design, §4). Advisory and non-terminal: it says nothing about whether the turn succeeded, and a
+   * turn may report it several times or never.
+   *
+   * Emitted from whatever the vendor volunteers in band — Claude Code puts a full set of windows
+   * with their utilizations on every `rate_limit_event`, including the 90% warning that precedes
+   * any refusal. It is the highest-trust usage source there is (`usage.ts` `SOURCE_RANK`): the
+   * vendor said it, about this identity, at that moment.
+   */
+  | { type: "usage"; windows: Record<string, UsageWindow> }
   /** No output for `stallTimeoutMs`. Always followed by `failed` with reason `stalled`. */
   | { type: "stalled"; silentMs: number }
   /** Terminal: the Worker ended with a valid final message under its contract. `report` is the

package/src/init/prompt.ts

@@ -3,26 +3,25 @@ import type { ProjectChoice } from "./project.js";
 import type { RunRecipe } from "../foreman/run-recipe.js";
 import type { RecipeDefaults } from "./run-recipe-config.js";
 
-/** Asks for the Run Recipe with the inferred values as defaults (Enter keeps them). Without a
- * terminal the defaults stand as they are, and null comes back when no start command could be
- * inferred, since a recipe without one cannot start anything. */
-export async function askRecipe(defaults: RecipeDefaults): Promise<RunRecipe | null> {
-  if (!process.stdin.isTTY) {
-    return defaults.start ? { ...defaults, start: defaults.start } : null;
-  }
+/**
+ * Asks for the one Run Recipe value nothing else can infer: the typecheck Gate.
+ *
+ * It no longer asks how to start the app. That question has no answer at setup time in a
+ * repository with more than one program -- "the app" means whichever one a Task's Verification
+ * happens to exercise, which is not known until there is a Task. The analyzer's dev command is
+ * still written when it exists, and the Verifier works the rest out when a browser round is
+ * actually wanted.
+ *
+ * Without a terminal the inferred values stand as they are.
+ */
+export async function askRecipe(defaults: RecipeDefaults): Promise<RunRecipe> {
+  if (!process.stdin.isTTY) return { ...defaults };
   const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const ask = async (label: string, fallback: string | undefined): Promise<string> => {
-    const answer = (await rl.question(`${label}${fallback ? ` [${fallback}]` : ""}: `)).trim();
-    return answer || fallback || "";
-  };
   try {
-    rl.write("Run Recipe (how the Foreman starts the app for verification; {port} is the Worker's port):\n");
-    const start = await ask("Start command", defaults.start);
-    if (!start) return null;
-    const readinessUrl = await ask("Readiness URL", defaults.readinessUrl);
-    const portEnv = await ask("Port variable", defaults.portEnv);
-    const typecheck = await ask("Typecheck command (blank for none)", defaults.gates.typecheck);
-    return { start, readinessUrl, portEnv, gates: { ...defaults.gates, typecheck: typecheck || undefined } };
+    const fallback = defaults.gates.typecheck;
+    const answer = (await rl.question(`Typecheck command for the Foreman's Gates (blank for none)${fallback ? ` [${fallback}]` : ""}: `)).trim();
+    const typecheck = answer || fallback;
+    return { ...defaults, gates: { ...defaults.gates, typecheck: typecheck || undefined } };
   } finally {
     rl.close();
   }

package/src/init/run-recipe-config.ts

@@ -33,18 +33,16 @@ export function commandsOf(files: OpseeConfigFiles): Record<string, string> {
  * Gate has no analyzer equivalent and is only ever a flag or a prompt answer. */
 export function inferRecipe(files: OpseeConfigFiles, flags: RecipeFlags): RecipeDefaults {
   const commands = commandsOf(files);
+  const start = flags.start ?? commands.dev ?? commands.start;
   return {
-    start: flags.start ?? commands.dev ?? commands.start,
-    readinessUrl: flags.readinessUrl ?? DEFAULT_READINESS_URL,
+    // The pair travels together or not at all: a readiness URL with nothing to start is a line
+    // that answers a question nobody asked, and `recipeFromConfig` rejects the other half-pair.
+    ...(start === undefined ? {} : { start, readinessUrl: flags.readinessUrl ?? DEFAULT_READINESS_URL }),
     portEnv: flags.portEnv ?? DEFAULT_PORT_ENV,
     gates: { test: commands.test, lint: commands.lint, typecheck: flags.typecheck },
   };
 }
 
-/** Why `init` skipped the recipe when nothing said how to start the app. */
-export const NO_START_COMMAND =
-  "no start command: pass --start <cmd>, answer the prompt on a terminal, or set commands.dev in .opsee/config";
-
 /** The recipe a config file already carries, so a block present in one of the two files is copied
  * into the other rather than asked for again; null when neither has a block that can serve as a
  * recipe. The YAML is the analyzer's primary file and wins when both have one. */
@@ -68,12 +66,13 @@ function gateEntries(gates: RunRecipeGates): Array<[string, string]> {
 }
 
 function yamlRecipeBlock(recipe: RunRecipe, indent: string): string {
-  const lines = [
-    `${RECIPE_KEY}:`,
-    `${indent}start: ${yamlScalar(recipe.start)}`,
-    `${indent}readiness_url: ${yamlScalar(recipe.readinessUrl)}`,
-    `${indent}port_env: ${yamlScalar(recipe.portEnv)}`,
-  ];
+  // start and readiness_url only when something already knew them: the analyzer's dev command, or
+  // an --start flag. A block with neither is a complete recipe for a repository whose Verdict comes
+  // from its Gates.
+  const lines = [`${RECIPE_KEY}:`];
+  if (recipe.start) lines.push(`${indent}start: ${yamlScalar(recipe.start)}`);
+  if (recipe.readinessUrl) lines.push(`${indent}readiness_url: ${yamlScalar(recipe.readinessUrl)}`);
+  lines.push(`${indent}port_env: ${yamlScalar(recipe.portEnv)}`);
   const gates = gateEntries(recipe.gates);
   if (gates.length > 0) {
     lines.push(`${indent}gates:`);