@opsee/cli 0.11.12 → 0.11.18

package/src/cli.ts

@@ -1,21 +1,23 @@
 import { execFile } from "node:child_process";
 import { accessSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename } from "node:path";
+import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Code, ConnectError } from "@connectrpc/connect";
 import { authManager } from "@opsee/mcp-server/src/auth/manager.js";
 import { startLoginFlow } from "@opsee/mcp-server/src/auth/login.js";
 import { createClients, type ApiClients } from "@opsee/mcp-server/src/client/api.js";
 import { parseCommand, usage } from "./args.js";
-import { runAccountAdd, runAccountList, runAccountRemove, runAccountResume, runAccountSet, type AccountDeps } from "./commands/account.js";
+import { runAccountAdd, runAccountList, runAccountRemove, runAccountResume, runAccountSet, runAccountSyncSkeleton, type AccountDeps } from "./commands/account.js";
+import { runAccountUsage } from "./commands/account-usage.js";
+import { runClaudeLaunch, type ClaudeLaunchDeps } from "./commands/claude-launcher.js";
 import { runInitiativeCreate, runInitiativeList, runInitiativeMemory, runInitiativeNote, runInitiativeShow, type InitiativeDeps } from "./commands/initiative.js";
 import type { CommandDeps } from "./commands/deps.js";
 import { runForemanDebugReady, runForemanDebugServe, runForemanDebugTurn } from "./commands/foreman-debug.js";
 import { currentRepoRoot, runForemanRun, type ForemanLocal } from "./commands/foreman.js";
 import { runForemanPlan } from "./commands/foreman-plan.js";
 import { runForemanService } from "./commands/foreman-service.js";
-import { runForemanAttach, runForemanCancel, runForemanPause, runForemanRelease, runForemanResume, type ForemanControlDeps } from "./commands/foreman-control.js";
+import { runForemanAttach, runForemanCancel, runForemanPause, runForemanRelease, runForemanResume, type ForemanControlDeps, runInteractiveCommand } from "./commands/foreman-control.js";
 import { runForemanUp } from "./commands/foreman-up.js";
 import { runForemanLogs, runForemanReview, runForemanStatus } from "./commands/foreman-views.js";
 import { ClaudeWorkerAdapter } from "./foreman/claude-worker-adapter.js";
@@ -25,12 +27,16 @@ import { runLogin } from "./commands/login.js";
 import { runWhoami, NOT_LOGGED_IN } from "./commands/whoami.js";
 import { runInit } from "./commands/init.js";
 import { accountsFilePath, FileAccountStore } from "./foreman/account-store.js";
-import { ProcessTable } from "./foreman/core/process-table.js";
+import { FileUsageStore, usageDirPath } from "./foreman/usage-store.js";
+import { ProcessTable, otherForemanWorkersOn } from "./foreman/core/process-table.js";
 import { ForemanError } from "./foreman/core/run.js";
 import { TranscriptStore } from "./foreman/core/transcripts.js";
 import { hostIsLaptop } from "./foreman/host.js";
 import { daemonPidPath, foremanLocalDir, processTablePath, transcriptsDir } from "./foreman/local-dir.js";
-import type { ConfigDirFs } from "./foreman/account.js";
+import { realConfigDirFs, type ConfigDirFs } from "./foreman/account.js";
+import { VENDOR_BINARY } from "./foreman/vendor.js";
+import { credentialPresence, realCredentialDeps } from "./foreman/credential-store.js";
+import { AnthropicUsageSource } from "./foreman/usage-poller.js";
 import { OpseeTrackerAdapter } from "./foreman/opsee-tracker-adapter.js";
 import type { Vendor } from "./foreman/vendor.js";
 import type { WorkerAdapter } from "./foreman/worker-adapter.js";
@@ -75,7 +81,7 @@ function foremanLocal(): ForemanLocal {
 }
 
 /** The real file system, narrowed to the two calls Account registration may make. */
-const configDirFs: ConfigDirFs = { statSync, accessSync };
+const configDirFs: ConfigDirFs = realConfigDirFs;
 
 /** The CLI entry a service unit runs: bin/opsee.js beside src/, absolute (story 16). */
 const CLI_BIN = fileURLToPath(new URL("../bin/opsee.js", import.meta.url));
@@ -157,15 +163,56 @@ function initiativeDeps(io: CliIo): InitiativeDeps {
   return { clients: clients(), out: io.log };
 }
 
+/** What `opsee claude` needs: the Accounts, what is known about their limits, and a way to run the
+ * vendor's binary with this terminal handed to it. No client and no login — like the Account
+ * commands, it is local. */
+function claudeLaunchDeps(io: CliIo): ClaudeLaunchDeps {
+  return {
+    store: new FileAccountStore(accountsFilePath()),
+    usage: new FileUsageStore(usageDirPath()),
+    out: io.log,
+    env: process.env,
+    exec: (command, args, env) => runInteractiveCommand({ command, args, cwd: process.cwd(), env }),
+    // The machine-local Process Table, so a session is not started on an Account a Foreman is
+    // already running Workers on (ADR-0013's per-identity concurrency).
+    busyAccounts: () => {
+      const table = foremanLocal().table;
+      const at = Date.now();
+      const busy = new Set<string>();
+      for (const row of table.liveWorkers()) {
+        if (otherForemanWorkersOn(table, row.account, at).length > 0) busy.add(row.account);
+      }
+      return busy;
+    },
+  };
+}
+
 function accountDeps(io: CliIo): AccountDeps {
   return {
     store: new FileAccountStore(accountsFilePath()),
+    usage: new FileUsageStore(usageDirPath()),
+    // `account usage --refresh` measures through the same source the daemon polls with.
+    usageSource: new AnthropicUsageSource(),
     fs: configDirFs,
     env: process.env,
     out: io.log,
+    // `--login`: the vendor's *own* binary, interactive, with only the config-directory variable
+    // added. What it writes there is never read (ADR-0013) — only asked about, below.
+    login: (vendor, _configDir, env) =>
+      runInteractiveCommand({ command: VENDOR_BINARY[vendor], args: [], cwd: process.cwd(), env: { ...processEnvStrings(), ...env } }),
+    // Presence, never contents, and platform-aware: on macOS the credential is a Keychain item
+    // derived from the config directory rather than a file in it (credential-store.ts).
+    loggedIn: (vendor, configDir) => credentialPresence(vendor, configDir, realCredentialDeps),
   };
 }
 
+/** `process.env` with the unset keys dropped, which is what a spawn's `env` must be. */
+function processEnvStrings(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) if (value !== undefined) env[key] = value;
+  return env;
+}
+
 /** Runs one invocation of `opsee` and returns the exit code. One credential for the MCP server
  * and the CLI: both read and write through mcp's auth module, and both talk to the backend through
  * mcp's generated Connect-RPC clients (ADR-0010). */
@@ -212,6 +259,12 @@ export async function main(argv: string[], io: CliIo = console): Promise<number>
         return await runAccountAdd(accountDeps(io), command.args);
       case "foreman-account-list":
         return await runAccountList(accountDeps(io));
+      case "foreman-account-usage":
+        return await runAccountUsage(accountDeps(io), command.args);
+      case "foreman-account-sync-skeleton":
+        return await runAccountSyncSkeleton(accountDeps(io), command.args);
+      case "claude-launch":
+        return await runClaudeLaunch(claudeLaunchDeps(io), command.args);
       case "foreman-account-set":
         return await runAccountSet(accountDeps(io), command.args);
       case "foreman-account-remove":
@@ -231,6 +284,8 @@ export async function main(argv: string[], io: CliIo = console): Promise<number>
       case "foreman-up":
         return await runForemanUp({
           store: new FileAccountStore(accountsFilePath()),
+          usage: new FileUsageStore(usageDirPath()),
+          ranking: command.args,
           tracker: new OpseeTrackerAdapter(clients()),
           adapterFor: (account) => workerAdapterFor(account),
           repoRoot: currentRepoRoot,
@@ -248,6 +303,7 @@ export async function main(argv: string[], io: CliIo = console): Promise<number>
         return await runForemanRun(
           {
             store: new FileAccountStore(accountsFilePath()),
+            usage: new FileUsageStore(usageDirPath()),
             tracker: new OpseeTrackerAdapter(clients()),
             adapterFor: (account) => workerAdapterFor(account),
             repoRoot: currentRepoRoot,

package/src/commands/account-usage.ts

@@ -0,0 +1,106 @@
+import type { Account } from "../foreman/account.js";
+import { printableOneLine } from "../foreman/core/text.js";
+import { summaryRows, windowRows } from "../foreman/usage-format.js";
+import { pollUsage, SERVE_TTL_MS, staleFor } from "../foreman/usage-poller.js";
+import { usageByAccount } from "../foreman/usage-store.js";
+import type { AccountDeps } from "./account.js";
+
+/** What `opsee foreman account usage` was asked for. */
+export interface AccountUsageArgs {
+  /** Measure now, rather than printing only what is already known. */
+  refresh?: boolean;
+  /** Every window, rather than the one that decides dispatch. */
+  windows?: boolean;
+}
+
+/**
+ * `opsee foreman account usage`: what is known about every Account's rate-limit windows.
+ *
+ * A line per Account by default, because the question a human is asking is *which Account has room*
+ * and the answer is one number — the headroom of its tightest window. `--windows` shows the rest.
+ *
+ * It used to print a row per window always, and, when it knew nothing, a table of dashes with no
+ * hint that usage only arrives from a Worker turn or the daemon. On a freshly set-up machine that
+ * looked like a broken command rather than an unmeasured one.
+ */
+export async function runAccountUsage(deps: AccountDeps, args: AccountUsageArgs): Promise<number> {
+  const accounts = deps.store.load();
+  if (accounts.length === 0) {
+    deps.out("No Accounts registered. Run `opsee foreman account add` to register one.");
+    return 0;
+  }
+  const now = (deps.now ?? Date.now)();
+  if (args.refresh) await refresh(deps, accounts, now);
+
+  const known = usageByAccount(deps.usage);
+  // What the Foreman could ever have a number for: the vendor the poller speaks to, and a
+  // subscription rather than a key. A Codex Account counted here would be told to start the daemon,
+  // which will never measure it.
+  const measurable = accounts.filter((a) => a.vendor === "claude" && a.type === "subscription");
+  // "Nothing has been measured" is only true when nothing has been *tried* either: an Account whose
+  // every poll was refused has no windows, and saying "neither has happened here" would bury the
+  // refusal in the one state where it most needs reading.
+  const untried = measurable.every((a) => {
+    const record = known.get(a.name);
+    return Object.keys(record?.windows ?? {}).length === 0 && !record?.pollFailedAt;
+  });
+  if (measurable.length > 0 && untried) {
+    for (const line of nothingKnown(args)) deps.out(line);
+    return 0;
+  }
+  for (const line of args.windows ? windowRows(accounts, known, now) : summaryRows(accounts, known, now)) deps.out(line);
+  return 0;
+}
+
+/**
+ * Measures the Accounts whose numbers are too old to print, and says what happened.
+ *
+ * `staleFor` rather than "all of them": the endpoint has a request cap (usage-poller.ts), so a command a
+ * human can run in a loop must not be able to spend the hour's worth of requests. A number younger
+ * than `SERVE_TTL_MS` is served as it stands, and an Account inside a rate-limit window is not asked
+ * however explicitly it was requested.
+ */
+async function refresh(deps: AccountDeps, accounts: Account[], now: number): Promise<void> {
+  if (!deps.usage || !deps.usageSource) {
+    deps.out("This build has no way to measure usage directly; it can only show what a Run or the daemon has already recorded.");
+    return;
+  }
+  const measurable = accounts.filter((a) => a.vendor === "claude" && a.type === "subscription");
+  if (measurable.length === 0) {
+    // Not the same as "everything is fresh": there was nothing this could ever have asked about.
+    deps.out("No Account here reports usage: the poller speaks to claude subscriptions, and these are not.");
+    return;
+  }
+  const due = staleFor(measurable, usageByAccount(deps.usage), now);
+  if (due.length === 0) {
+    deps.out(`Everything measurable was measured less than ${Math.round(SERVE_TTL_MS / 60_000)} minutes ago; showing that rather than asking again.`);
+    return;
+  }
+  const { polled, failed } = await pollUsage({ store: deps.usage, source: deps.usageSource, accounts: due, now: () => now });
+  const reasons = new Set<string>();
+  for (const account of due) {
+    const failure = deps.usage.loadOne(account.name)?.pollFailure;
+    if (failure) reasons.add(printableOneLine(failure));
+  }
+  // Said either way: a refresh that measured in silence is indistinguishable from one that did
+  // nothing, and the no-op path was the only one that spoke.
+  deps.out(
+    failed === 0
+      ? `Measured ${polled} of ${polled}.`
+      : `Measured ${polled} of ${polled + failed}${reasons.size > 0 ? `; the rest could not be asked (${[...reasons].join("; ")})` : ""}.`,
+  );
+}
+
+/** What to say when no Account has ever been measured: where usage comes from, and how to get some. */
+function nothingKnown(args: AccountUsageArgs): string[] {
+  return [
+    "No usage has been measured yet.",
+    "",
+    "Usage reaches the Foreman two ways, and neither has happened here:",
+    "  a Worker reports its Account's windows as it runs   — start a Run (opsee foreman run <initiativeId>)",
+    "  the daemon measures the Accounts that are idle      — opsee foreman up",
+    "",
+    ...(args.refresh ? [] : ["Or measure now:  opsee foreman account usage --refresh"]),
+  ];
+}
+

package/src/commands/account.ts

@@ -1,3 +1,6 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 import type { AccountAddArgs, AccountSetArgs } from "../args.js";
 import {
   AccountError,
@@ -9,10 +12,18 @@ import {
   noteResumed,
   removeAccount,
   resumeAccount,
+  expandHome,
   setAccountLimits,
+  validateAccountSpec,
   type ConfigDirFs,
+  type SubscriptionAccount,
 } from "../foreman/account.js";
 import type { AccountStore } from "../foreman/account-store.js";
+import { usageByAccount, type UsageStore } from "../foreman/usage-store.js";
+import type { CredentialPresence } from "../foreman/credential-store.js";
+import type { UsageSource } from "../foreman/usage-poller.js";
+import { VENDOR_CONFIG_DIR_ENV, type Vendor } from "../foreman/vendor.js";
+import { formatSkeletonResults, syncSkeleton } from "../foreman/config-skeleton.js";
 import { printableOneLine } from "../foreman/core/text.js";
 
 /** Account commands are local: no backend, no login. The fs seam is the whole of their file-system
@@ -22,6 +33,37 @@ export interface AccountDeps {
   fs: ConfigDirFs;
   env: Readonly<Record<string, string | undefined>>;
   out: (line: string) => void;
+  /** What is known about each Account's rate-limit windows (the multi-account headroom design).
+   * Optional throughout: usage is an optimisation, and every command here works without it. */
+  usage?: UsageStore;
+  /** How `account usage --refresh` measures. Absent, the command can only print what a Run or the
+   * daemon already recorded, and says so. */
+  usageSource?: UsageSource;
+  now?: () => number;
+  /**
+   * Runs the vendor's own interactive login in `configDir`, with the terminal handed to it, and
+   * resolves with its exit code (`--login`, spec §7).
+   *
+   * A seam, and deliberately the only new one: what it does is spawn the vendor's binary with the
+   * config-directory variable set. Nothing here reads what that login writes — the boundary this
+   * command has always respected (ADR-0013) is unchanged, and `--login` succeeds or fails on the
+   * vendor's exit code alone rather than on the Foreman inspecting a credentials file.
+   */
+  login?: (vendor: Vendor, configDir: string, env: Record<string, string>) => Promise<number>;
+  /**
+   * Whether a login left a credential for `configDir`: `present`, `absent`, or `unknown`
+   * (`credential-store.ts`).
+   *
+   * Presence only — no credential is read. Quitting the vendor's REPL without signing in exits 0,
+   * so an exit code alone would register an Account against an empty directory, which the Foreman
+   * then dispatches onto and quarantines on its second failure.
+   *
+   * **`unknown` must never refuse.** The first version of this asked whether a file existed, which
+   * on macOS is always "no" because the credential lives in the Keychain — so it refused three
+   * Accounts that had been logged into perfectly well. A check that cannot answer has to stand
+   * aside and say so.
+   */
+  loggedIn?: (vendor: Vendor, configDir: string) => Promise<CredentialPresence> | CredentialPresence;
 }
 
 /** Returns the process exit code. Validation failures throw AccountError for the CLI to report. */
@@ -29,6 +71,19 @@ export async function runAccountAdd(deps: AccountDeps, args: AccountAddArgs): Pr
   if (args.vendor === undefined) {
     throw new AccountError("--vendor is required");
   }
+  if (args.login) {
+    // Everything the registration would refuse, asked before the directory is made and before an
+    // interactive sign-in is spent: an unknown vendor, a name already taken, a cap out of range.
+    const { vendor } = validateAccountSpec(deps.store, {
+      vendor: args.vendor,
+      name: args.name,
+      configDir: args.configDir,
+      keyRef: args.keyEnv,
+      cap: positiveInteger("--cap", args.cap),
+    });
+    const refused = await runVendorLogin(deps, args, vendor);
+    if (refused !== undefined) return refused;
+  }
   const account = registerAccount(deps.store, deps.fs, {
     vendor: args.vendor,
     name: args.name,
@@ -43,13 +98,62 @@ export async function runAccountAdd(deps: AccountDeps, args: AccountAddArgs): Pr
   return 0;
 }
 
+/**
+ * Makes the config directory and runs the vendor's login in it, before anything is registered.
+ *
+ * Returns an exit code when the Account must **not** be registered, and undefined to carry on.
+ * Registering a directory nobody managed to log into would give the Foreman an Account it will
+ * dispatch onto and quarantine on the second failure — worse than no Account at all.
+ */
+async function runVendorLogin(deps: AccountDeps, args: AccountAddArgs, vendor: Vendor): Promise<number | undefined> {
+  if (args.configDir === undefined) {
+    throw new AccountError("--login needs --config-dir: it makes that directory and logs the vendor into it. An API-key Account has nothing to log into.");
+  }
+  if (!deps.login) {
+    throw new AccountError("--login is not available here");
+  }
+  // The same expansion registration uses. A second one drifted on bare `~`, which would have
+  // logged in under `<cwd>/~` and then stored `$HOME` — the item written under one string and looked
+  // up under another, which on macOS is a Keychain miss with no visible cause.
+  const configDir = resolve(expandHome(args.configDir));
+  // Owner-only, like every other directory holding an identity (the accounts file, the usage store).
+  // Codex additionally requires its config directory to exist before it will start.
+  mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  deps.out(`Running ${vendor}'s own login in ${configDir}. Sign in as the Account you want registered, then leave the session.`);
+  const code = await deps.login(vendor, configDir, { [VENDOR_CONFIG_DIR_ENV[vendor]]: configDir });
+  if (code !== 0) {
+    deps.out(`The login did not complete (${vendor} exited ${code}); nothing was registered. The directory ${configDir} is left in place, so running this again resumes where it stopped.`);
+    return code;
+  }
+  // An exit code of 0 only says the vendor's CLI closed cleanly, which is also what quitting its
+  // prompt without signing in does. Registering on that alone hands the Foreman an Account it will
+  // dispatch onto and quarantine on the second failure — the thing this whole path exists to avoid.
+  //
+  // Only a positive `absent` refuses. `unknown` registers and says why it could not check: being
+  // unable to see a credential is not evidence that there is none, and the cost of getting that
+  // backwards is refusing a good Account, which is worse than registering one that needs a login.
+  const presence = (await deps.loggedIn?.(vendor, configDir)) ?? "unknown";
+  if (presence === "absent") {
+    deps.out(`${vendor} closed with no sign-in recorded for ${configDir}; nothing was registered. Run this again and complete the login, or register the directory yourself once you have.`);
+    return 1;
+  }
+  if (presence === "unknown") {
+    deps.out(
+      `Registered without confirming the sign-in: this machine did not answer whether ${vendor} stored a credential for ${configDir}. ` +
+        `If the login did not complete, the Account is quarantined on its second turn; log the vendor in and run "opsee foreman account resume <name>".`,
+    );
+  }
+  return undefined;
+}
+
 export async function runAccountList(deps: AccountDeps): Promise<number> {
   const accounts = deps.store.load();
   if (accounts.length === 0) {
     deps.out("No Accounts registered. Run `opsee foreman account add` to register one.");
     return 0;
   }
-  for (const line of formatAccountTable(accounts)) deps.out(line);
+  const now = (deps.now ?? Date.now)();
+  for (const line of formatAccountTable(accounts, now, usageByAccount(deps.usage))) deps.out(line);
   return 0;
 }
 
@@ -61,6 +165,7 @@ export async function runAccountSet(deps: AccountDeps, args: AccountSetArgs): Pr
     cap: positiveInteger("--cap", args.cap),
     maxTurns: positiveInteger("--max-turns", args.maxTurns),
     stallTimeoutMs: positiveInteger("--stall-timeout", args.stallTimeoutMs),
+    thresholdPct: positiveInteger("--threshold", args.thresholdPct),
   });
   deps.out(`Account "${account.name}": ${describeLimits(account)}`);
   return 0;
@@ -119,3 +224,31 @@ export async function runAccountRemove(deps: AccountDeps, name: string): Promise
   deps.out(`Removed Account "${removed.name}"`);
   return 0;
 }
+
+/**
+ * `opsee foreman account sync-skeleton [--from <dir>]` (the multi-account headroom design, §5).
+ *
+ * Symlinks the account-independent config entries from one canonical directory into every claude
+ * subscription Account's, so registering a second Account does not mean maintaining a second set of
+ * settings and skills. Claude Accounts only: the entries are Claude Code's own file names, and
+ * another vendor's config directory holds different files under different names.
+ *
+ * Never a credential (`config-skeleton.ts` refuses credential-shaped names whatever it is asked),
+ * and never a file a person wrote: a real file already in place is reported and left alone.
+ */
+export async function runAccountSyncSkeleton(deps: AccountDeps, args: { from?: string }): Promise<number> {
+  const canonical = args.from ?? join(homedir(), ".claude");
+  const targets = deps.store.load().filter((a): a is SubscriptionAccount => a.vendor === "claude" && a.type === "subscription");
+  if (targets.length === 0) {
+    deps.out("No claude subscription Account is registered, so there is nothing to link into. Register one with: opsee foreman account add --vendor claude --config-dir <dir>");
+    return 0;
+  }
+  deps.out(`Linking the shared config entries from ${canonical} into ${targets.length === 1 ? "1 Account" : `${targets.length} Accounts`}:`);
+  const results = syncSkeleton({ canonical, targets: targets.map((a) => a.configDir) });
+  for (const line of formatSkeletonResults(results)) deps.out(line);
+  const refused = results.filter((r) => r.outcome === "refused").length;
+  if (refused > 0) {
+    deps.out(`${refused === 1 ? "1 entry was" : `${refused} entries were`} left alone; nothing was overwritten. Move or delete the file named above to share the canonical one.`);
+  }
+  return 0;
+}

package/src/commands/claude-launcher.ts

@@ -0,0 +1,183 @@
+import { isPaused, isQuarantined, thresholdFor, type Account, type SubscriptionAccount } from "../foreman/account.js";
+import type { AccountStore } from "../foreman/account-store.js";
+import { DEFAULT_RANKING_POLICY, rankLanes } from "../foreman/core/scheduler.js";
+import { printableOneLine } from "../foreman/core/text.js";
+import { describeAge, headroom, thresholdHold, type AccountUsage } from "../foreman/usage.js";
+import { usageByAccount, type UsageStore } from "../foreman/usage-store.js";
+import { VENDOR_CONFIG_DIR_ENV } from "../foreman/vendor.js";
+
+/**
+ * `opsee claude [args…]` — the launcher (the multi-account headroom design, §5).
+ *
+ * Picks the registered Claude Account with the most headroom and runs the vendor's own binary under
+ * it, by naming that Account's config directory in `CLAUDE_CONFIG_DIR` and nothing else. Every
+ * argument the caller gave is handed on untouched.
+ *
+ * **No credential is read, copied or moved.** A config directory the user has logged into is
+ * already a complete, isolated Claude Code identity, and the vendor's own variable is the supported
+ * way to select one — so the interactive half of multi-account needs no credential store and
+ * nothing here crosses the boundary ADR-0013 draws. What it costs is that history and per-account
+ * state live per directory; `config-skeleton.ts` narrows that to history alone.
+ */
+export interface ClaudeLaunchArgs {
+  /** Use this Account whatever usage says. A human who names one is not overruled. */
+  account?: string;
+  /** Resolve and print the choice, launch nothing. For scripts and for looking before leaping. */
+  printChoice: boolean;
+  /** The vendor's own arguments, verbatim. */
+  passthrough: string[];
+}
+
+export interface ClaudeLaunchDeps {
+  store: AccountStore;
+  /** Absent, or holding nothing, means the choice is made blind — and says so. */
+  usage?: UsageStore;
+  now?: () => number;
+  out: (line: string) => void;
+  env: Readonly<Record<string, string | undefined>>;
+  /** Runs the vendor's binary with the terminal inherited and resolves with its exit code. The one
+   * seam this command has, so the whole of the choosing is testable without a `claude` on PATH. */
+  exec: (command: string, args: string[], env: Record<string, string>) => Promise<number>;
+  /**
+   * Which Accounts a Foreman already has live Workers on (the Process Table).
+   *
+   * Asked because a session started here runs under the same vendor identity as those Workers, and
+   * two things on one identity is twice the concurrency its owner chose — the concentration the
+   * per-Account caps exist to limit (ADR-0013). The Run refuses to double up at its `contended`
+   * filter; a launcher that ignored the question would walk straight past that guard.
+   *
+   * Optional: absent, the launcher behaves as though nothing is running, which is what a machine
+   * with no Process Table yet actually means.
+   */
+  busyAccounts?: () => ReadonlySet<string>;
+}
+
+/** The vendor's binary. Not configurable: `opsee claude` launching something other than `claude`
+ * would be a way to have the Foreman's Account selection point at an arbitrary program. */
+const CLAUDE_BINARY = "claude";
+
+/** Exit code when no Account can be chosen. Not 1, which the vendor itself uses for an ordinary
+ * failed turn, so a script can tell "the launcher refused" from "claude ran and said no". */
+export const NO_ACCOUNT_EXIT = 3;
+
+export async function runClaudeLaunch(deps: ClaudeLaunchDeps, args: ClaudeLaunchArgs): Promise<number> {
+  const now = (deps.now ?? Date.now)();
+  const known = usageByAccount(deps.usage);
+  const busy = deps.busyAccounts?.() ?? new Set<string>();
+
+  // Subscriptions only. An API-key Account has no config directory to point at, and handing the key
+  // to an interactive session is a different thing from choosing between logins — the caller can do
+  // that themselves by setting the variable.
+  const candidates = deps.store.load().filter((a): a is SubscriptionAccount => a.vendor === "claude" && a.type === "subscription");
+
+  if (args.account !== undefined) {
+    const named = candidates.find((a) => a.name === args.account);
+    if (!named) {
+      deps.out(
+        `No subscription Account named "${args.account}" for claude. Registered: ${candidates.map((a) => a.name).join(", ") || "none"}. ` +
+          `Register one with: opsee foreman account add --vendor claude --config-dir <dir>`,
+      );
+      return NO_ACCOUNT_EXIT;
+    }
+    // Told explicitly, it obeys. Refusing here would be the launcher overruling the person at the
+    // keyboard about their own subscription; what it owes them is what it knows, not a veto.
+    deps.out(`${describeChoice(named, known, now)}${warning(named, known, now, busy)}`);
+    return args.printChoice ? 0 : await launch(deps, named, args.passthrough);
+  }
+
+  if (candidates.length === 0) {
+    deps.out(
+      deps.store.load().some((a) => a.vendor === "claude")
+        ? "Every registered claude Account is an API key, and there is no config directory to launch against. Register a subscription Account: opsee foreman account add --vendor claude --config-dir <dir>"
+        : "No claude Account is registered. Register one with: opsee foreman account add --vendor claude --config-dir <dir>",
+    );
+    return NO_ACCOUNT_EXIT;
+  }
+
+  // The same three questions the Run asks of a Lane, in the same order, so `opsee claude` and an
+  // overnight Run never disagree about whether an Account is usable.
+  const usable = candidates.filter(
+    (a) => !isQuarantined(a) && !isPaused(a, now) && !busy.has(a.name) && !thresholdHold(known.get(a.name), thresholdFor(a), now),
+  );
+  if (usable.length === 0) {
+    deps.out(refusal(candidates, known, now, busy));
+    return NO_ACCOUNT_EXIT;
+  }
+
+  // `best` regardless of the Run's configured strategy: a person waiting at a prompt wants the
+  // Account with the most room, not one being deliberately drained first. Fresh ranking state, so
+  // there is no hysteresis to carry — there is no previous leader in a one-shot command.
+  const { lanes } = rankLanes(
+    usable.map((account) => ({ account })),
+    known,
+    { ...DEFAULT_RANKING_POLICY, strategy: "best" },
+    {},
+    now,
+  );
+  const chosen = lanes[0].account;
+  deps.out(describeChoice(chosen, known, now));
+  return args.printChoice ? 0 : await launch(deps, chosen, args.passthrough);
+}
+
+async function launch(deps: ClaudeLaunchDeps, account: SubscriptionAccount, passthrough: string[]): Promise<number> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(deps.env)) if (value !== undefined) env[key] = value;
+  // The one thing added, and last, so a `CLAUDE_CONFIG_DIR` already in the caller's environment
+  // cannot quietly win over the Account they were just told they are running as.
+  env[VENDOR_CONFIG_DIR_ENV.claude] = account.configDir;
+  return await deps.exec(CLAUDE_BINARY, passthrough, env);
+}
+
+/** The line printed before the vendor takes the terminal: which Account, and how much is known
+ * about it. "never observed" rather than a blank, so a blind choice is never read as a measured
+ * one. */
+function describeChoice(account: Account, known: ReadonlyMap<string, AccountUsage>, now: number): string {
+  const record = known.get(account.name);
+  const left = headroom(record, now);
+  if (left.kind === "unknown") {
+    return `opsee: claude on Account "${account.name}" (never observed — nothing is known about its limits yet)`;
+  }
+  return `opsee: claude on Account "${account.name}" (${left.remainingPct}% left of ${left.tightest}, seen ${describeAge(left.observedAt, now)})`;
+}
+
+/** What else the caller should know about an Account they named themselves. */
+function warning(account: Account, known: ReadonlyMap<string, AccountUsage>, now: number, busy: ReadonlySet<string>): string {
+  if (isQuarantined(account)) return `\nopsee: warning — this Account is quarantined (${printableOneLine(account.quarantined!.reason)}); the vendor may refuse the session`;
+  const until = isPaused(account, now) ? account.paused!.until : undefined;
+  if (until) return `\nopsee: warning — this Account is Paused until ${until}; the vendor may refuse the session`;
+  if (busy.has(account.name)) {
+    return `\nopsee: warning — a Foreman already has Workers on this Account, so this session adds to the concurrency that identity is running`;
+  }
+  const hold = thresholdHold(known.get(account.name), thresholdFor(account), now);
+  return hold ? `\nopsee: warning — this Account is at ${hold.reason}, past its ${thresholdFor(account)}% threshold; the Foreman would not start a Worker on it` : "";
+}
+
+/** Why nothing could be launched, and the soonest moment that changes. A refusal that does not say
+ * when to come back is a refusal the reader has to go and investigate. */
+function refusal(candidates: Account[], known: ReadonlyMap<string, AccountUsage>, now: number, busy: ReadonlySet<string>): string {
+  let soonest: Date | undefined;
+  const lines: string[] = [];
+  for (const account of candidates) {
+    if (isQuarantined(account)) {
+      lines.push(`  ${account.name}: quarantined (${printableOneLine(account.quarantined!.reason)}) — log the vendor back in, then: opsee foreman account resume ${account.name}`);
+      continue;
+    }
+    if (busy.has(account.name)) {
+      lines.push(`  ${account.name}: a Foreman has live Workers on it — a session here would double what that identity is running`);
+      continue;
+    }
+    const paused = isPaused(account, now) ? new Date(account.paused!.until) : undefined;
+    const hold = thresholdHold(known.get(account.name), thresholdFor(account), now);
+    const until = paused ?? hold?.until;
+    if (until && (!soonest || until < soonest)) soonest = until;
+    if (paused) lines.push(`  ${account.name}: Paused until ${paused.toISOString()} — the vendor refused it`);
+    else if (hold) lines.push(`  ${account.name}: held at ${hold.reason} until ${hold.until.toISOString()} — its own threshold, not a refusal`);
+  }
+  return [
+    "opsee: no claude Account is usable right now.",
+    ...lines,
+    soonest
+      ? `The soonest window resets at ${soonest.toISOString()}. Register another Account, raise a threshold (opsee foreman account set <name> --threshold <pct>), or pass --account <name> to use one anyway.`
+      : "Register another Account, or pass --account <name> to use one anyway.",
+  ].join("\n");
+}

package/src/commands/foreman-debug.ts

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import type { DebugTurnArgs } from "../args.js";
 import { AccountError, type Account } from "../foreman/account.js";
 import type { AccountStore } from "../foreman/account-store.js";
-import { loadRunRecipe, startApp, waitForReady, type RunRecipe, type StartOptions, type AppHandle, type WaitOptions, type Readiness } from "../foreman/run-recipe.js";
+import { loadRunRecipe, startable, startApp, waitForReady, type RunRecipe, type StartableRecipe, type StartOptions, type AppHandle, type WaitOptions, type Readiness } from "../foreman/run-recipe.js";
 import type { TrackerAdapter } from "../foreman/tracker-adapter.js";
 import type { TurnRequest, WorkerAdapter } from "../foreman/worker-adapter.js";
 
@@ -75,7 +75,7 @@ export interface ForemanDebugServeDeps {
   timeoutMs?: number;
   /** Test seams; the real recipe functions by default. */
   load?: (root: string) => RunRecipe;
-  start?: (recipe: RunRecipe, options: StartOptions) => AppHandle;
+  start?: (recipe: StartableRecipe, options: StartOptions) => AppHandle;
   wait?: (url: string, options: WaitOptions) => Promise<Readiness>;
 }
 
@@ -84,9 +84,16 @@ export interface ForemanDebugServeDeps {
  * the app up until Ctrl-C. Exit 1 when the recipe is missing or the app never becomes ready. */
 export async function runForemanDebugServe(deps: ForemanDebugServeDeps, port: number): Promise<number> {
   const recipe = (deps.load ?? loadRunRecipe)(deps.root);
+  // This command exists to serve the app, so a recipe that cannot is the whole failure, said here
+  // rather than as a spawn error from a command that is the empty string.
+  const servable = startable(recipe);
+  if (!servable) {
+    deps.out(`.opsee/config: the foreman block has no start command, so there is no app to serve. Add foreman.start, or let the Verifier work it out.`);
+    return 1;
+  }
   const timeoutMs = deps.timeoutMs ?? 120_000;
-  const app = (deps.start ?? startApp)(recipe, { port, cwd: deps.root, onOutput: (line) => deps.out(`  | ${line}`) });
-  deps.out(`starting: ${app.command}  (${recipe.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
+  const app = (deps.start ?? startApp)(servable, { port, cwd: deps.root, onOutput: (line) => deps.out(`  | ${line}`) });
+  deps.out(`starting: ${app.command}  (${servable.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
   deps.out(`waiting for ${app.readinessUrl} (up to ${timeoutMs}ms)`);
   try {
     const ready = await (deps.wait ?? waitForReady)(app.readinessUrl, { timeoutMs, signal: app.exitSignal });