@opsee/cli 0.11.13 → 0.11.18

package/README.md

@@ -225,14 +225,30 @@ or an API-key Account, a vendor plus the name of the environment variable that w
 
 ```sh
 node bin/opsee.js foreman account add --vendor claude --config-dir ~/.claude-work --name work
+node bin/opsee.js foreman account add --vendor claude --config-dir ~/.claude-spare --login --name spare
 node bin/opsee.js foreman account add --vendor codex --key-env OPENAI_API_KEY --cap 3
 node bin/opsee.js foreman account list
+node bin/opsee.js foreman account usage                    # what is left, and how old the number is
 node bin/opsee.js foreman account set work --cap 4          # more Slots, only ever by asking
 node bin/opsee.js foreman account set work --max-turns 40 --stall-timeout 600000
+node bin/opsee.js foreman account set work --threshold 75   # hold it back earlier than the default 90%
+node bin/opsee.js foreman account sync-skeleton             # share settings/skills between Accounts
 node bin/opsee.js foreman account remove work
 node bin/opsee.js foreman account resume work              # lifts a quarantine (and any pause)
 ```
 
+`--login` is for the second Account and after: it makes the config directory, runs **the vendor's
+own** login inside it with that vendor's config-directory variable set, and registers only if a
+credential was left behind. It refuses an unknown vendor, a name already taken or a cap out of
+range *before* spawning anything, so a typo never costs an interactive sign-in.
+
+The Foreman reads nothing the login writes. It asks only **whether** a credential exists, and where
+that lives is the vendor's business, not a given: on macOS Claude Code writes no file at all and
+keeps the credential in a Keychain item it derives from the config directory, so a file check there
+answers "no" however well the login went (`credential-store.ts`). The answer is three-valued, and
+the third is the point — a machine that cannot tell returns *unknown*, the Account is registered
+anyway, and the command says it could not confirm. Only a positive *absent* refuses.
+
 Several Accounts per vendor are fine, and worth having: each has its own name, cap and rate-limit
 window, and a Run on one **Fails over to its siblings of the same vendor** while it is Paused (see
 [Paused Accounts and Failover](#paused-accounts-and-failover)). Records live in
@@ -368,6 +384,106 @@ out of the real Run Record: the order off the Account with one implementer Slot,
 order is the order the scheduler chose in, and the concurrency off the Account with two, where a
 barrier the turns wait at proves they really overlapped.
 
+### Headroom: how much of an Account is left
+
+An Account's **Headroom** is what remains of its tightest live rate-limit window, so an Account at
+20% of its five-hour and 98% of its seven-day has 2% — the minimum, never an average, because a
+limit is a limit.
+
+Most of it arrives free. Claude Code puts every window it tracks, with a utilization and a reset, on
+each `rate_limit_event` — including the `allowed_warning` that fires at 90% of a window, before
+anything is refused. Those numbers are recorded against the Lane's own Account as the turn runs. An
+Account nobody is running reports nothing, so the daemon polls those from the vendor's own usage
+endpoint; that poll is the one place in this package that reads a credential, and
+[ADR-0013](../docs/adr/0013-credential-boundary-and-account-types.md) was amended to permit exactly
+it and nothing more — read wherever the vendor keeps it, which is a Keychain item on macOS and a
+file elsewhere. `usage-poller-boundary.test.ts` holds both backends to it: only this config
+directory's own credential is ever asked for, only Anthropic is ever contacted, and no
+credential-derived value reaches anything written or printed.
+
+```sh
+node bin/opsee.js foreman account usage              # a line per Account: what is left, and why
+node bin/opsee.js foreman account usage --windows    # every window behind that number
+node bin/opsee.js foreman account usage --refresh    # measure now, rather than printing what is known
+```
+
+The default is one line per Account, because the question is *which Account has room* and the answer
+is one number: the headroom of its tightest live window. An Account nothing is known about says
+`never observed` rather than showing as fresh, and an API-key Account says in words that it reports
+no usage — it is never treated as spent. When **nothing** has been measured the command says where
+usage comes from instead of printing a table of dashes.
+
+**The endpoint has a request cap**, and the intervals are built around it: roughly 28-30 requests an hour
+per identity, over a trailing window rather than a refilling bucket, so a burst saturates the
+identity for a full hour and waiting does not return the headroom early. An idle Account is asked at
+most every 5 minutes, an exhausted one every 10, never more often than a 3-minute floor, and each
+Account's schedule is nudged off the others' so a fleet does not ask in lockstep. A 429 is waited out
+over the window that produced it rather than retried in minutes. `--refresh` honours the same floors:
+a number under 3 minutes old is served as it stands, so running it in a loop cannot spend the hour's
+requests.
+
+Records live in `~/.opsee/foreman-usage/` (or `OPSEE_FOREMAN_USAGE_DIR`), one file per Account,
+owner-only. **Usage is an optimisation and never a dependency**: stale, missing, unparseable or a
+failed poll all fall back to the behaviour below, which is to find out by being refused. A failed
+poll is not a credential failure and can never contribute to a quarantine.
+
+### Holds: stopping before the vendor says no
+
+An Account at or past its threshold — 90% by default, where the vendor's own warning fires, and
+`account set <name> --threshold <pct>` per Account — is **held**: no new Worker starts on it until
+that window resets. `account list` says `held` rather than `paused`, because the two ask different
+things of a reader. A pause is Anthropic refusing; a hold is the Foreman declining first.
+
+A hold is derived from usage and policy every tick and never stored, so raising `--threshold` lifts
+one with nothing to clear, and a window resetting lifts one by itself.
+
+### Dispatch strategies: which Account gets the next Task
+
+```sh
+node bin/opsee.js foreman run 42 --strategy best
+node bin/opsee.js foreman up --strategy consume-first --hysteresis 5 --cooldown 60000
+```
+
+- `order` — registration order. **The default**, and exactly what the Foreman did before any of
+  this existed, so upgrading cannot silently move anyone's Tasks to a different Account.
+
+  Under `order`, a Run on a fleet still has to be told where to start (`--account <name>`): nothing
+  has said which Account to prefer, so `chooseAccount` refuses rather than guessing. Under `best` or
+  `consume-first` it starts on the Account the strategy would pick, because that is the same
+  question already answered. A Run queued for the daemon leaves the choice unresolved unless a name
+  was given: a `RunRequestRow` carries no strategy, so the daemon's policy is the one that applies.
+- `best` — most Headroom first. What an overnight Run across several Accounts wants.
+- `consume-first` — soonest-resetting Account first, draining one before the next is touched.
+
+The Lanes are ranked **once per tick**, not once per Ready Task, and each Task then orders its own
+eligible Lanes by that ranking — otherwise a Task pinned to one Account would write a one-Lane order
+into the ranking state and drag every later Task onto it. `--hysteresis` (10 points) and
+`--cooldown` (5 minutes) stop two Accounts a point apart from swapping on every dispatch.
+
+### `opsee claude`: the same Accounts, interactively
+
+```sh
+node bin/opsee.js claude                      # the Account with the most Headroom
+node bin/opsee.js claude --print-choice        # resolve and print, launch nothing
+node bin/opsee.js claude --account spare -- --model opus
+```
+
+Runs the real `claude` with `CLAUDE_CONFIG_DIR` pointed at the chosen Account and every argument
+passed through untouched. **No credential moves**: a config directory you have logged into is
+already a whole identity, and the vendor's own variable is the supported way to select one.
+
+Its own flags are read only from the front and stop at the first token it does not recognise, or at
+a bare `--`, so an argument meant for `claude` can never be eaten. It skips an Account that is
+quarantined, Paused, held, or one a Foreman already has Workers on — a session there would double
+what that identity is running. Told `--account` explicitly it obeys and warns instead of refusing;
+the person at the keyboard is not overruled about their own subscription.
+
+`account sync-skeleton` symlinks the account-independent entries (`settings.json`, `CLAUDE.md`,
+`skills`, `commands`, `agents`, `.mcp.json`) from one directory — `~/.claude` by default — into each
+Account's, so only history differs between them. It moves no bytes, never replaces a file you wrote,
+and refuses anything credential-shaped as well as `.claude.json` by name, since that one carries the
+account identity and sharing it would quietly make two Accounts one.
+
 ### Paused Accounts and Failover
 
 When a Worker Adapter reports a rate limit, the Account it ran under becomes **Paused**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsee/cli",
-  "version": "0.11.13",
+  "version": "0.11.18",
   "description": "Opsee CLI — the opsee binary: login, whoami, and the home of the Foreman",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "@bufbuild/protobuf": "^2.14.0",
     "@connectrpc/connect": "^2.1.2",
     "@connectrpc/connect-node": "^2.1.2",
-    "@opsee/mcp-server": "0.11.13",
+    "@opsee/mcp-server": "0.11.18",
     "tsx": "^4.23.12"
   },
   "devDependencies": {

package/src/args.ts

@@ -1,4 +1,7 @@
-import type { ForemanRunArgs } from "./commands/foreman.js";
+import type { AccountUsageArgs } from "./commands/account-usage.js";
+import type { ClaudeLaunchArgs } from "./commands/claude-launcher.js";
+import type { ForemanRunArgs, ForemanUpArgs, RankingArgs } from "./commands/foreman.js";
+import type { DispatchStrategy } from "./foreman/core/scheduler.js";
 import type { ForemanPlanArgs } from "./commands/foreman-plan.js";
 import type { ForemanServiceArgs } from "./commands/foreman-service.js";
 import type { ForemanLogsArgs, ForemanReviewArgs, ForemanStatusArgs } from "./commands/foreman-views.js";
@@ -7,6 +10,8 @@ import type { RecipeFlags } from "./init/run-recipe-config.js";
 
 /** Raw options of `opsee foreman account add`; the account module validates them. */
 export interface AccountAddArgs {
+  /** Run the vendor's own login in the new config directory before registering (spec §7). */
+  login?: boolean;
   vendor?: string;
   name?: string;
   configDir?: string;
@@ -21,6 +26,8 @@ export interface AccountSetArgs {
   cap?: string;
   maxTurns?: string;
   stallTimeoutMs?: string;
+  /** How much of a rate-limit window may be spent before the Account is held back. */
+  thresholdPct?: string;
 }
 
 /** Raw options of `opsee initiative list`. Validated where the command runs, like the account
@@ -83,6 +90,11 @@ export type Command =
   | { kind: "init"; projectKey?: string; recipe: RecipeFlags }
   | { kind: "foreman-account-add"; args: AccountAddArgs }
   | { kind: "foreman-account-list" }
+  /** What is known about each Account's rate-limit windows (the multi-account headroom design). */
+  | { kind: "foreman-account-usage"; args: AccountUsageArgs }
+  /** Symlinks the account-independent config entries from one canonical directory into every
+   * claude subscription Account's (the multi-account headroom design, §5). */
+  | { kind: "foreman-account-sync-skeleton"; args: { from?: string } }
   /** Changes an Account's Slot cap and per-turn limits (story 27): raising a cap is always this. */
   | { kind: "foreman-account-set"; args: AccountSetArgs }
   | { kind: "foreman-account-remove"; name: string }
@@ -97,7 +109,7 @@ export type Command =
   | { kind: "initiative-memory"; args: InitiativeMemoryArgs }
   | { kind: "initiative-note"; args: InitiativeNoteArgs }
   /** The daemon that idles until given work (story 13); a placeholder until the Process Table lands. */
-  | { kind: "foreman-up" }
+  | { kind: "foreman-up"; args: ForemanUpArgs }
   /** A Run scoped to one Initiative, in the foreground until no Ready Task remains (story 14). */
   | { kind: "foreman-run"; args: ForemanRunArgs }
   /** An attended planning session on an Initiative, in a Workspace of its own (story 10). */
@@ -123,11 +135,14 @@ export type Command =
   | { kind: "foreman-debug-serve"; port: number }
   /** Hidden: runs one unattended Worker turn through the Worker Adapter and prints its report. */
   | { kind: "foreman-debug-turn"; args: DebugTurnArgs }
+  /** `opsee claude [args…]`: the vendor's own binary on the Account with the most headroom (the
+   * multi-account headroom design, §5). */
+  | { kind: "claude-launch"; args: ClaudeLaunchArgs }
   | { kind: "help" }
   | { kind: "usage-error"; message: string }
   | { kind: "unknown"; input: string };
 
-const ACCOUNT_ADD_OPTIONS: Record<string, keyof AccountAddArgs> = {
+const ACCOUNT_ADD_OPTIONS: Record<string, keyof Omit<AccountAddArgs, "login">> = {
   "--vendor": "vendor",
   "--name": "name",
   "--config-dir": "configDir",
@@ -139,6 +154,11 @@ function parseAccountAdd(argv: string[]): Command {
   const args: AccountAddArgs = {};
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
+    // The one flag here that takes no value; everything else is `--flag <value>`.
+    if (token === "--login") {
+      args.login = true;
+      continue;
+    }
     const eq = token.indexOf("=");
     const flag = eq === -1 ? token : token.slice(0, eq);
     const field = ACCOUNT_ADD_OPTIONS[flag];
@@ -159,9 +179,11 @@ const ACCOUNT_SET_OPTIONS: Record<string, keyof Omit<AccountSetArgs, "name">> =
   "--cap": "cap",
   "--max-turns": "maxTurns",
   "--stall-timeout": "stallTimeoutMs",
+  "--threshold": "thresholdPct",
 };
 
-const ACCOUNT_SET_USAGE = "foreman account set needs an Account name and at least one of --cap, --max-turns, --stall-timeout: foreman account set <name> --cap <n>";
+const ACCOUNT_SET_USAGE =
+  "foreman account set needs an Account name and at least one of --cap, --max-turns, --stall-timeout, --threshold: foreman account set <name> --cap <n>";
 
 function parseAccountSet(argv: string[]): Command {
   const [name, ...rest] = argv;
@@ -219,7 +241,7 @@ function parseDebugTurn(argv: string[]): Command {
   return { kind: "foreman-debug-turn", args: { account, cwd, prompt, resume: values["--resume"], maxTurns, stallTimeoutMs, raw } };
 }
 
-const FOREMAN_SUBCOMMANDS = "up | run <initiativeId> | plan <initiativeId> | status | logs <task> | review [initiativeId] | attach <taskId> | release <taskId> | cancel <taskId> | pause <initiativeId> | resume <initiativeId> | service install | service uninstall | service status | account add | account list | account set | account remove | account resume";
+const FOREMAN_SUBCOMMANDS = "up | run <initiativeId> | plan <initiativeId> | status | logs <task> | review [initiativeId] | attach <taskId> | release <taskId> | cancel <taskId> | pause <initiativeId> | resume <initiativeId> | service install | service uninstall | service status | account add | account list | account usage | account set | account remove | account resume | account sync-skeleton";
 
 /** The task-scoped controls (attach, release, cancel) take a Task id; pause and resume an
  * Initiative id. All take exactly one positive integer. */
@@ -231,9 +253,38 @@ function parseForemanControl(kind: "foreman-attach" | "foreman-release" | "forem
   return kind === "foreman-pause" || kind === "foreman-resume" ? { kind, initiativeId: id } : { kind, taskId: id };
 }
 
-const FOREMAN_RUN_VALUE_OPTIONS = ["--account", "--task", "--max-turns", "--stall-timeout"] as const;
+/** The dispatch-policy flags (`RankingArgs`), taken by both `foreman run` and `foreman up`. */
+const RANKING_VALUE_OPTIONS = ["--strategy", "--hysteresis", "--cooldown"] as const;
+const STRATEGIES: readonly DispatchStrategy[] = ["order", "best", "consume-first"];
+
+/** Reads the three policy flags out of the values already collected, or says which one is wrong.
+ * The strategy is checked against the list here rather than deeper down, because a typo in it
+ * would otherwise be a silent fall back to registration order. */
+function rankingArgs(values: Partial<Record<string, string>>): RankingArgs | { error: string } {
+  const strategy = values["--strategy"];
+  if (strategy !== undefined && !(STRATEGIES as readonly string[]).includes(strategy)) {
+    return { error: `--strategy must be one of: ${STRATEGIES.join(", ")}` };
+  }
+  const hysteresisPct = values["--hysteresis"] === undefined ? undefined : Number(values["--hysteresis"]);
+  const cooldownMs = values["--cooldown"] === undefined ? undefined : Number(values["--cooldown"]);
+  // Zero is meaningful for both — no margin, no cooldown — so these are not `positiveInteger`.
+  for (const [flag, value] of [["--hysteresis", hysteresisPct], ["--cooldown", cooldownMs]] as const) {
+    if (value !== undefined && (!Number.isInteger(value) || value < 0)) return { error: `${flag} must be a whole number of ${flag === "--hysteresis" ? "percentage points" : "milliseconds"}` };
+  }
+  if (hysteresisPct !== undefined && hysteresisPct > 100) return { error: "--hysteresis is a margin in percentage points, so it is at most 100" };
+  // Only what was actually asked for: an absent flag is absent from the result rather than a key
+  // holding undefined, so `foreman up` with no flags parses to an empty policy.
+  return {
+    ...(strategy === undefined ? {} : { strategy: strategy as DispatchStrategy }),
+    ...(hysteresisPct === undefined ? {} : { hysteresisPct }),
+    ...(cooldownMs === undefined ? {} : { cooldownMs }),
+  };
+}
+
+const FOREMAN_RUN_VALUE_OPTIONS = ["--account", "--task", "--max-turns", "--stall-timeout", ...RANKING_VALUE_OPTIONS] as const;
 type ForemanRunValueOption = (typeof FOREMAN_RUN_VALUE_OPTIONS)[number];
-const FOREMAN_RUN_USAGE = "foreman run needs an Initiative id: foreman run <initiativeId> [--account <name>] [--once] [--task <id>] [--max-turns <n>] [--stall-timeout <ms>]";
+const FOREMAN_RUN_USAGE =
+  "foreman run needs an Initiative id: foreman run <initiativeId> [--account <name>] [--once] [--task <id>] [--max-turns <n>] [--stall-timeout <ms>] [--strategy <order|best|consume-first>] [--hysteresis <pct>] [--cooldown <ms>]";
 
 function positiveInteger(text: string | undefined): number | undefined | null {
   if (text === undefined) return undefined;
@@ -270,7 +321,9 @@ function parseForemanRun(argv: string[]): Command {
   if (taskId === null || maxTurns === null || stallTimeoutMs === null) {
     return { kind: "usage-error", message: "--task, --max-turns and --stall-timeout must be positive integers" };
   }
-  return { kind: "foreman-run", args: { initiativeId, account: values["--account"], once, taskId, maxTurns, stallTimeoutMs } };
+  const ranking = rankingArgs(values);
+  if ("error" in ranking) return { kind: "usage-error", message: ranking.error };
+  return { kind: "foreman-run", args: { initiativeId, account: values["--account"], once, taskId, maxTurns, stallTimeoutMs, ...ranking } };
 }
 
 const FOREMAN_PLAN_VALUE_OPTIONS = ["--account", "--skill", "--memory"] as const;
@@ -383,11 +436,27 @@ function parseForemanReview(argv: string[]): Command {
   return { kind: "foreman-review", args: { initiativeId: id } };
 }
 
+const FOREMAN_UP_USAGE = "foreman up takes only the dispatch policy: foreman up [--strategy <order|best|consume-first>] [--hysteresis <pct>] [--cooldown <ms>]";
+
+function parseForemanUp(argv: string[]): Command {
+  const values: Partial<Record<string, string>> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    const eq = token.indexOf("=");
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    if (!(RANKING_VALUE_OPTIONS as readonly string[]).includes(flag)) return { kind: "usage-error", message: FOREMAN_UP_USAGE };
+    const value = eq === -1 ? argv[++i] : token.slice(eq + 1);
+    if (value === undefined || (eq === -1 && value.startsWith("--"))) return { kind: "usage-error", message: `${flag} needs a value` };
+    values[flag] = value;
+  }
+  const ranking = rankingArgs(values);
+  if ("error" in ranking) return { kind: "usage-error", message: ranking.error };
+  return { kind: "foreman-up", args: ranking };
+}
+
 function parseForeman(argv: string[]): Command {
   const [group, action, ...rest] = argv;
-  if (group === "up") {
-    return action === undefined ? { kind: "foreman-up" } : { kind: "usage-error", message: "foreman up takes no arguments" };
-  }
+  if (group === "up") return parseForemanUp([action, ...rest].filter((t): t is string => t !== undefined));
   if (group === "run") return parseForemanRun(argv.slice(1));
   if (group === "plan") return parseForemanPlan(argv.slice(1));
   if (group === "service") return parseForemanService(action, rest);
@@ -418,6 +487,27 @@ function parseForeman(argv: string[]): Command {
       return parseAccountAdd(rest);
     case "list":
       return { kind: "foreman-account-list" };
+    case "usage": {
+      const args: AccountUsageArgs = {};
+      for (const token of rest) {
+        if (token === "--refresh") args.refresh = true;
+        else if (token === "--windows") args.windows = true;
+        else return { kind: "usage-error", message: "foreman account usage takes only --refresh and --windows" };
+      }
+      return { kind: "foreman-account-usage", args };
+    }
+    case "sync-skeleton": {
+      if (rest.length === 0) return { kind: "foreman-account-sync-skeleton", args: {} };
+      const [flag, value] = rest;
+      if (flag === "--from" && value !== undefined && !value.startsWith("--") && rest.length === 2) {
+        return { kind: "foreman-account-sync-skeleton", args: { from: value } };
+      }
+      if (flag.startsWith("--from=") && rest.length === 1) {
+        const from = flag.slice("--from=".length);
+        return from === "" ? { kind: "usage-error", message: "--from needs a directory" } : { kind: "foreman-account-sync-skeleton", args: { from } };
+      }
+      return { kind: "usage-error", message: "foreman account sync-skeleton takes only --from <dir>" };
+    }
     case "set":
       return parseAccountSet(rest);
     case "remove":
@@ -425,7 +515,7 @@ function parseForeman(argv: string[]): Command {
     case "resume":
       return rest[0] ? { kind: "foreman-account-resume", name: rest[0] } : { kind: "usage-error", message: "foreman account resume needs an Account name" };
     default:
-      return { kind: "usage-error", message: "foreman account needs one of: add, list, set, remove, resume" };
+      return { kind: "usage-error", message: "foreman account needs one of: add, list, usage, set, remove, resume, sync-skeleton" };
   }
 }
 
@@ -534,6 +624,42 @@ function parseInitiative(argv: string[]): Command {
   }
 }
 
+/**
+ * `opsee claude [our flags] [the vendor's arguments…]`.
+ *
+ * The launcher's own flags are read only from the front, and reading stops at the first token that
+ * is not one of them — or at a bare `--`. Everything from there on is the vendor's, verbatim.
+ *
+ * It has to work this way round: `claude` has its own flags and may one day have these names too,
+ * and a launcher that grabbed `--account` from the middle of a command line would silently eat an
+ * argument meant for the vendor. Stopping at the first unrecognised token means the ambiguity can
+ * only ever be resolved in the vendor's favour, and `--` says so explicitly.
+ */
+function parseClaudeLaunch(argv: string[]): Command {
+  const args: ClaudeLaunchArgs = { printChoice: false, passthrough: [] };
+  let i = 0;
+  for (; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--") {
+      i++;
+      break;
+    }
+    if (token === "--print-choice") {
+      args.printChoice = true;
+      continue;
+    }
+    if (token === "--account" || token.startsWith("--account=")) {
+      const value = token === "--account" ? argv[++i] : token.slice("--account=".length);
+      if (value === undefined || value === "" || value.startsWith("--")) return { kind: "usage-error", message: "--account needs an Account name" };
+      args.account = value;
+      continue;
+    }
+    break;
+  }
+  args.passthrough = argv.slice(i);
+  return { kind: "claude-launch", args };
+}
+
 export function parseCommand(argv: string[]): Command {
   const [first, ...rest] = argv;
   switch (first) {
@@ -547,6 +673,8 @@ export function parseCommand(argv: string[]): Command {
       return parseForeman(rest);
     case "initiative":
       return parseInitiative(rest);
+    case "claude":
+      return parseClaudeLaunch(rest);
     case undefined:
     case "help":
     case "--help":
@@ -602,10 +730,20 @@ export function usage(): string {
     "                                Run Recipe values for a non-interactive run; {port} in a",
     "                                command or URL is replaced with the Worker's port",
     "",
+    "  opsee claude [--account <name>] [--print-choice] [-- ] [claude arguments…]",
+    "                                Run the real claude on the registered Account with the most",
+    "                                headroom, by pointing CLAUDE_CONFIG_DIR at it. Arguments after",
+    "                                the launcher's own are handed to claude untouched",
+    "",
     "Foreman:",
-    "  opsee foreman up              Start the Foreman daemon: it Reconciles each tick and serves Runs queued by foreman run",
+    "  opsee foreman up [--strategy <order|best|consume-first>] [--hysteresis <pct>] [--cooldown <ms>]",
+    "                                Start the Foreman daemon: it Reconciles each tick and serves Runs",
+    "                                queued by foreman run. --strategy orders the Accounts a Ready Task",
+    "                                may run on: registration order, most headroom left, or one Account",
+    "                                drained before the next is touched",
     "  opsee foreman run <initiativeId> [--account <name>] [--once] [--task <id>]",
-    "      [--max-turns <n>] [--stall-timeout <ms>]",
+    "      [--max-turns <n>] [--stall-timeout <ms>] [--strategy <order|best|consume-first>]",
+    "      [--hysteresis <pct>] [--cooldown <ms>]",
     "                                Run the Initiative's Ready Tasks one by one from this checkout:",
     "                                a Workspace and branch per Task, one unattended Worker turn each,",
     "                                Completion Reports into Initiative memory, moves on the board",
@@ -646,10 +784,24 @@ export function usage(): string {
     "                                Workers finish either way, both are on the Run Record",
     "",
     "Foreman Accounts (stored by path or variable name only; the credential is never read):",
-    "  opsee foreman account add --vendor <claude|codex> --config-dir <dir> [--name <n>] [--cap <n>]",
+    "  opsee foreman account add --vendor <claude|codex> --config-dir <dir> [--name <n>] [--cap <n>] [--login]",
+    "                                --login makes the directory and runs the vendor's own login in",
+    "                                it first, so a second Account needs no set-up by hand",
     "  opsee foreman account add --vendor <claude|codex> --key-env <VAR> [--name <n>] [--cap <n>]",
     "  opsee foreman account list",
+    "  opsee foreman account sync-skeleton [--from <dir>]",
+    "                                Symlink the shared config entries (settings.json, CLAUDE.md,",
+    "                                skills, commands, agents) from one directory — ~/.claude by",
+    "                                default — into every claude subscription Account's, so only",
+    "                                history differs between them. A credential is never linked",
+    "  opsee foreman account usage [--refresh] [--windows]",
+    "                                What is left on each Account: the headroom of the window that",
+    "                                decides dispatch, when it resets, and whether it is held back.",
+    "                                --windows shows every window; --refresh measures now rather than",
+    "                                printing only what a Run or the daemon has already recorded",
     "  opsee foreman account set <name> [--cap <n>] [--max-turns <n>] [--stall-timeout <ms>]",
+    "      [--threshold <pct>]       How much of a rate-limit window may be spent before the Account",
+    "                                is held back (90 by default, where the vendor warns)",
     "                                The Account's Slots and per-turn limits. The cap is how many",
     "                                Workers may run on it at once, one Slot of it reserved for",
     "                                Verifiers; it defaults to 2 and is only ever raised here",

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,