@opsee/cli 0.11.12 → 0.11.18

package/README.md

@@ -102,15 +102,33 @@ environment, so an app that reads the variable needs no placeholder at all. Vite
 kind: it ignores `PORT` and takes `--port`, and `--strictPort` makes it fail rather than drift to
 the next free port, which is the silent-corruption hazard AGENTS.md describes for two dev servers.
 
-`opsee init` writes the block once. `start` defaults to `commands.dev` (then `commands.start`),
-`gates.test` and `gates.lint` to `commands.test` and `commands.lint`, the readiness URL to
-`http://localhost:{port}/` and the variable to `PORT`; `typecheck` has no analyzer equivalent and
-is asked for or left out. On a terminal the four are prompted with those defaults; otherwise the
-defaults and the flags `--start`, `--readiness-url`, `--port-env`, `--typecheck` stand, and a repo
-where nothing says how to start the app gets a `skipped` line instead of a recipe. An existing
-`foreman` block, the user's or the analyzer's, is never rewritten: a re-run reports `unchanged`
-whatever the flags say, and a block that cannot serve as a recipe (no `start`, no
-`readiness_url`) is reported and kept. The YAML is spliced textually, the block appended in the
+`opsee init` writes the block once. `gates.test` and `gates.lint` default to `commands.test` and
+`commands.lint`; `start` is written only when `commands.dev` (then `commands.start`) or `--start`
+already says how to serve the app, and the readiness URL and the port variable travel with it.
+`typecheck` has no analyzer equivalent, so it is the one value a terminal is asked for.
+
+**It never asks how to start the app.** That question has no answer at setup time in a repository
+with several programs: "the app" means whichever one a Task's Verification happens to exercise, and
+no Task exists yet. A block with Gates and no `start` is a complete recipe — the Gates are the whole
+Verdict for most repositories — and the Verifier says so when a Task does ask for a browser round.
+The flags `--start`, `--readiness-url` and `--port-env` still write one for anyone who wants it
+pinned.
+
+When a Task's Verification asks for a browser round and the recipe has no `start`, the Foreman runs
+a **Start turn** before giving up: one short unattended turn in the Task's Workspace
+(`core/start-discovery.ts`), given that Task's Verification section, which answers with the command
+that serves the program the Verification exercises. That is the whole reason `opsee init` can stop
+asking — in a repository with several programs the answer depends on the Task, and a Task exists by
+then. The answer must take the leased port (`{port}` or the port variable) or it is refused: a
+command that serves on its own default is the failure that looks like success, because the readiness
+URL answers from a server the Foreman never started. It is agent-authored, so it runs under the
+Gates' filtered environment like every other command from the repository, and it lands verbatim on
+the Run Record as the app's command.
+
+`start` without `readiness_url` is still refused: that is half a recipe, which would serve the app
+and never learn it came up. An existing `foreman` block, the user's or the analyzer's, is never
+rewritten: a re-run reports `unchanged` whatever the flags say, and a block whose `verify` is not a
+known word is reported and kept. The YAML is spliced textually, the block appended in the
 file's own indentation with no blank line before it, because a parsed-and-reserialised document
 would lose the analyzer's header comments; the JSON copy is re-serialised in its own indentation
 with `foreman` after the analyzer's members. The two are only ever both written when both exist
@@ -207,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
@@ -350,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.12",
+  "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.12",
+    "@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",