npm - @opsee/cli - Versions diffs - 0.11.9 - Mend

@opsee/cli 0.11.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (85) hide show

package/README.md +1962 -0
package/bin/opsee.js +28 -0
package/package.json +40 -0
package/skills/README.md +3 -0
package/skills/to-issues/SKILL.md +92 -0
package/skills/to-issues/agents/openai.yaml +5 -0
package/skills/to-spec/SKILL.md +79 -0
package/skills/to-spec/agents/openai.yaml +5 -0
package/skills/wayfinder/SKILL.md +138 -0
package/skills/wayfinder/agents/openai.yaml +5 -0
package/src/args.ts +676 -0
package/src/cli.ts +341 -0
package/src/commands/account.ts +121 -0
package/src/commands/deps.ts +11 -0
package/src/commands/foreman-control.ts +242 -0
package/src/commands/foreman-debug.ts +131 -0
package/src/commands/foreman-plan.ts +213 -0
package/src/commands/foreman-service.ts +186 -0
package/src/commands/foreman-up.ts +165 -0
package/src/commands/foreman-views.ts +398 -0
package/src/commands/foreman.ts +465 -0
package/src/commands/init.ts +176 -0
package/src/commands/initiative.ts +192 -0
package/src/commands/login.ts +24 -0
package/src/commands/whoami.ts +15 -0
package/src/foreman/account-store.ts +96 -0
package/src/foreman/account.ts +474 -0
package/src/foreman/claude-worker-adapter.ts +412 -0
package/src/foreman/codex-worker-adapter.ts +472 -0
package/src/foreman/completion-report.ts +153 -0
package/src/foreman/core/context.ts +169 -0
package/src/foreman/core/defects.ts +280 -0
package/src/foreman/core/exec.ts +20 -0
package/src/foreman/core/gates.ts +493 -0
package/src/foreman/core/handoff.ts +163 -0
package/src/foreman/core/install.ts +109 -0
package/src/foreman/core/learnings.ts +368 -0
package/src/foreman/core/outbox-tracker.ts +192 -0
package/src/foreman/core/pin.ts +226 -0
package/src/foreman/core/plan-context.ts +238 -0
package/src/foreman/core/process-table.ts +535 -0
package/src/foreman/core/reconcile.ts +227 -0
package/src/foreman/core/report.ts +60 -0
package/src/foreman/core/run.ts +2836 -0
package/src/foreman/core/scheduler.ts +244 -0
package/src/foreman/core/summary.ts +166 -0
package/src/foreman/core/text.ts +97 -0
package/src/foreman/core/transcripts.ts +38 -0
package/src/foreman/core/triage.ts +138 -0
package/src/foreman/core/verifier.ts +800 -0
package/src/foreman/core/views.ts +940 -0
package/src/foreman/core/work-contract.ts +152 -0
package/src/foreman/core/workspace.ts +335 -0
package/src/foreman/fake-handoff.ts +33 -0
package/src/foreman/fake-learnings.ts +26 -0
package/src/foreman/fake-remote-api.ts +70 -0
package/src/foreman/fake-tracker-adapter.ts +355 -0
package/src/foreman/fake-worker-adapter.ts +221 -0
package/src/foreman/host.ts +75 -0
package/src/foreman/local-dir.ts +28 -0
package/src/foreman/opsee-tracker-adapter.ts +612 -0
package/src/foreman/process-group.ts +160 -0
package/src/foreman/remote-api.ts +283 -0
package/src/foreman/run-recipe.ts +274 -0
package/src/foreman/service-unit.ts +257 -0
package/src/foreman/tracker-adapter.ts +298 -0
package/src/foreman/triage-draft.ts +40 -0
package/src/foreman/vendor.ts +23 -0
package/src/foreman/verdict.ts +120 -0
package/src/foreman/worker-adapter.ts +177 -0
package/src/foreman/worker-process.ts +488 -0
package/src/identity.ts +49 -0
package/src/index.ts +3 -0
package/src/init/managed.ts +84 -0
package/src/init/mcp-config.ts +77 -0
package/src/init/paths.ts +16 -0
package/src/init/pointer-block.ts +45 -0
package/src/init/project.ts +22 -0
package/src/init/prompt.ts +45 -0
package/src/init/run-recipe-config.ts +133 -0
package/src/init/skills.ts +38 -0
package/src/init/text.ts +22 -0
package/src/init/tracker-doc.ts +106 -0
package/src/opsee-config.ts +116 -0
package/templates/issue-tracker.md +162 -0

package/src/args.ts ADDED Viewed

@@ -0,0 +1,676 @@
+import type { ForemanRunArgs } from "./commands/foreman.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";
+import { DEFAULT_PLANNING_SKILL, isPlanningSkill, PLANNING_SKILLS } from "./foreman/core/plan-context.js";
+import type { RecipeFlags } from "./init/run-recipe-config.js";
+/** Raw options of `opsee foreman account add`; the account module validates them. */
+export interface AccountAddArgs {
+  vendor?: string;
+  name?: string;
+  configDir?: string;
+  keyEnv?: string;
+  cap?: string;
+}
+/** Raw options of `opsee foreman account set <name>`: the scheduling limits of an Account that
+ * already exists, never its identity. Validated in the account module like the add form's. */
+export interface AccountSetArgs {
+  name: string;
+  cap?: string;
+  maxTurns?: string;
+  stallTimeoutMs?: string;
+}
+/** Raw options of `opsee initiative list`. Validated where the command runs, like the account
+ * forms: the parser's job is to say what was typed, not whether it is usable. */
+export interface InitiativeListArgs {
+  project?: string;
+  search?: string;
+}
+/** Raw options of `opsee initiative show <id>`. */
+export interface InitiativeShowArgs {
+  initiativeId: number;
+  /** The whole work session — task tree, memory log, pull requests — rather than the details
+   * alone; the same split `opsee_get_initiative` and `opsee_get_initiative_context` draw. */
+  context: boolean;
+  memory?: string;
+}
+/** Raw options of `opsee initiative create`. */
+export interface InitiativeCreateArgs {
+  title?: string;
+  project?: string;
+  summary?: string;
+  status?: string;
+  /** A file holding the core idea, or `-` for stdin: a markdown body does not fit in argv. */
+  coreIdeaFile?: string;
+}
+/** Raw options of `opsee initiative memory <id>`. */
+export interface InitiativeMemoryArgs {
+  initiativeId: number;
+  kind?: string;
+  limit?: string;
+}
+/** Raw options of `opsee initiative note <id> <body>`. */
+export interface InitiativeNoteArgs {
+  initiativeId: number;
+  body: string;
+  kind?: string;
+}
+/** Options of the hidden `opsee foreman debug turn`. */
+export interface DebugTurnArgs {
+  account: string;
+  cwd: string;
+  prompt: string;
+  resume?: string;
+  maxTurns?: number;
+  stallTimeoutMs?: number;
+  /** Also print every raw stream line the vendor emitted, for re-recording fixtures. */
+  raw: boolean;
+}
+export type Command =
+  | { kind: "login" }
+  | { kind: "whoami" }
+  | { kind: "init"; projectKey?: string; recipe: RecipeFlags }
+  | { kind: "foreman-account-add"; args: AccountAddArgs }
+  | { kind: "foreman-account-list" }
+  /** 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 }
+  /** Lifts a quarantine and a pause by hand (OPS-288), so a re-authenticated Account comes back
+   * without the remove-and-add that would lose its cap and per-turn limits. */
+  | { kind: "foreman-account-resume"; name: string }
+  /** The Initiative surface (phase 1): thin commands over the same RPCs the MCP tools call, so the
+   * two surfaces cannot drift about what an Initiative looks like. */
+  | { kind: "initiative-list"; args: InitiativeListArgs }
+  | { kind: "initiative-show"; args: InitiativeShowArgs }
+  | { kind: "initiative-create"; args: InitiativeCreateArgs }
+  | { 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" }
+  /** 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). */
+  | { kind: "foreman-plan"; args: ForemanPlanArgs }
+  /** The daemon under launchd or systemd (story 16): write, remove or report its unit. */
+  | { kind: "foreman-service"; args: ForemanServiceArgs }
+  /** Attach (story 53): stop a Worker's unattended turn and resume its session in this terminal. */
+  | { kind: "foreman-attach"; taskId: number }
+  /** Release (story 54): hand an attached Worker back so its next turn runs unattended. */
+  | { kind: "foreman-release"; taskId: number }
+  /** Pause / resume (story 55): stop and restart new dispatch for the Initiative's Run. */
+  | { kind: "foreman-pause"; initiativeId: number }
+  | { kind: "foreman-resume"; initiativeId: number }
+  /** Cancel (story 56): stop a Worker and record the attempt as cancelled. */
+  | { kind: "foreman-cancel"; taskId: number }
+  /** The three read-only views (OPS-280); none of them touches a Worker or the Run Record. */
+  | { kind: "foreman-status"; args: ForemanStatusArgs }
+  | { kind: "foreman-logs"; args: ForemanLogsArgs }
+  | { kind: "foreman-review"; args: ForemanReviewArgs }
+  /** Hidden and read-only: lists an Initiative's Ready Tasks as the Tracker Adapter sees them. */
+  | { kind: "foreman-debug-ready"; initiativeId: number }
+  /** Hidden: starts the app from the cwd's Run Recipe on `port` and reports when it is ready. */
+  | { 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 }
+  | { kind: "help" }
+  | { kind: "usage-error"; message: string }
+  | { kind: "unknown"; input: string };
+const ACCOUNT_ADD_OPTIONS: Record<string, keyof AccountAddArgs> = {
+  "--vendor": "vendor",
+  "--name": "name",
+  "--config-dir": "configDir",
+  "--key-env": "keyEnv",
+  "--cap": "cap",
+};
+function parseAccountAdd(argv: string[]): Command {
+  const args: AccountAddArgs = {};
+  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);
+    const field = ACCOUNT_ADD_OPTIONS[flag];
+    if (!field) {
+      // The flag only, never `token`: a value after `=` might be a pasted key.
+      return { kind: "usage-error", message: `Unknown option ${flag} for foreman account add` };
+    }
+    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` };
+    }
+    args[field] = value;
+  }
+  return { kind: "foreman-account-add", args };
+}
+const ACCOUNT_SET_OPTIONS: Record<string, keyof Omit<AccountSetArgs, "name">> = {
+  "--cap": "cap",
+  "--max-turns": "maxTurns",
+  "--stall-timeout": "stallTimeoutMs",
+};
+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>";
+function parseAccountSet(argv: string[]): Command {
+  const [name, ...rest] = argv;
+  if (!name || name.startsWith("--")) return { kind: "usage-error", message: ACCOUNT_SET_USAGE };
+  const args: AccountSetArgs = { name };
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    const eq = token.indexOf("=");
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    const field = ACCOUNT_SET_OPTIONS[flag];
+    if (!field) return { kind: "usage-error", message: `Unknown option ${flag} for foreman account set` };
+    const value = eq === -1 ? rest[++i] : token.slice(eq + 1);
+    if (value === undefined || (eq === -1 && value.startsWith("--"))) {
+      return { kind: "usage-error", message: `${flag} needs a value` };
+    }
+    args[field] = value;
+  }
+  if (rest.length === 0) return { kind: "usage-error", message: ACCOUNT_SET_USAGE };
+  return { kind: "foreman-account-set", args };
+}
+const DEBUG_TURN_VALUE_OPTIONS = ["--account", "--cwd", "--prompt", "--resume", "--max-turns", "--stall-timeout"] as const;
+function parseDebugTurn(argv: string[]): Command {
+  const values: Partial<Record<(typeof DEBUG_TURN_VALUE_OPTIONS)[number], string>> = {};
+  let raw = false;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--raw") {
+      raw = true;
+      continue;
+    }
+    const eq = token.indexOf("=");
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    if (!(DEBUG_TURN_VALUE_OPTIONS as readonly string[]).includes(flag)) {
+      return { kind: "usage-error", message: `Unknown option ${flag} for foreman debug turn` };
+    }
+    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 as (typeof DEBUG_TURN_VALUE_OPTIONS)[number]] = value;
+  }
+  const account = values["--account"];
+  const cwd = values["--cwd"];
+  const prompt = values["--prompt"];
+  if (!account || !cwd || !prompt) {
+    return { kind: "usage-error", message: "foreman debug turn needs --account <name> --cwd <dir> --prompt <text> [--resume <session-id>] [--max-turns <n>] [--stall-timeout <ms>] [--raw]" };
+  }
+  const maxTurns = positiveInteger(values["--max-turns"]);
+  const stallTimeoutMs = positiveInteger(values["--stall-timeout"]);
+  if (maxTurns === null || stallTimeoutMs === null) {
+    return { kind: "usage-error", message: "--max-turns and --stall-timeout must be positive integers" };
+  }
+  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";
+/** The task-scoped controls (attach, release, cancel) take a Task id; pause and resume an
+ * Initiative id. All take exactly one positive integer. */
+function parseForemanControl(kind: "foreman-attach" | "foreman-release" | "foreman-cancel" | "foreman-pause" | "foreman-resume", argv: string[]): Command {
+  const name = kind.slice("foreman-".length);
+  const what = kind === "foreman-pause" || kind === "foreman-resume" ? "an Initiative id" : "a Task id";
+  const id = positiveInteger(argv[0]);
+  if (!id || argv.length !== 1) return { kind: "usage-error", message: `foreman ${name} needs ${what}: foreman ${name} <${what === "a Task id" ? "taskId" : "initiativeId"}>` };
+  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;
+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>]";
+function positiveInteger(text: string | undefined): number | undefined | null {
+  if (text === undefined) return undefined;
+  const n = Number(text);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+function parseForemanRun(argv: string[]): Command {
+  const [first, ...rest] = argv;
+  const initiativeId = positiveInteger(first);
+  if (!initiativeId) return { kind: "usage-error", message: FOREMAN_RUN_USAGE };
+  const values: Partial<Record<ForemanRunValueOption, string>> = {};
+  let once = false;
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    if (token === "--once") {
+      once = true;
+      continue;
+    }
+    const eq = token.indexOf("=");
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    if (!(FOREMAN_RUN_VALUE_OPTIONS as readonly string[]).includes(flag)) {
+      return { kind: "usage-error", message: `Unknown option ${flag} for foreman run` };
+    }
+    const value = eq === -1 ? rest[++i] : token.slice(eq + 1);
+    if (value === undefined || (eq === -1 && value.startsWith("--"))) {
+      return { kind: "usage-error", message: `${flag} needs a value` };
+    }
+    values[flag as ForemanRunValueOption] = value;
+  }
+  const taskId = positiveInteger(values["--task"]);
+  const maxTurns = positiveInteger(values["--max-turns"]);
+  const stallTimeoutMs = positiveInteger(values["--stall-timeout"]);
+  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 FOREMAN_PLAN_VALUE_OPTIONS = ["--account", "--skill", "--memory"] as const;
+type ForemanPlanValueOption = (typeof FOREMAN_PLAN_VALUE_OPTIONS)[number];
+const FOREMAN_PLAN_USAGE = `foreman plan needs an Initiative id: foreman plan <initiativeId> [--account <name>] [--skill <${PLANNING_SKILLS.join("|")}>] [--memory <n>]`;
+function parseForemanPlan(argv: string[]): Command {
+  const [first, ...rest] = argv;
+  const initiativeId = positiveInteger(first);
+  if (!initiativeId) return { kind: "usage-error", message: FOREMAN_PLAN_USAGE };
+  const values: Partial<Record<ForemanPlanValueOption, string>> = {};
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    const eq = token.indexOf("=");
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    if (!(FOREMAN_PLAN_VALUE_OPTIONS as readonly string[]).includes(flag)) {
+      return { kind: "usage-error", message: `Unknown option ${flag} for foreman plan` };
+    }
+    const value = eq === -1 ? rest[++i] : token.slice(eq + 1);
+    if (value === undefined || (eq === -1 && value.startsWith("--"))) {
+      return { kind: "usage-error", message: `${flag} needs a value` };
+    }
+    values[flag as ForemanPlanValueOption] = value;
+  }
+  const skill = values["--skill"] ?? DEFAULT_PLANNING_SKILL;
+  if (!isPlanningSkill(skill)) {
+    return { kind: "usage-error", message: `--skill must be one of ${PLANNING_SKILLS.join(", ")} (the planning skills opsee init writes), not "${skill}"` };
+  }
+  const memory = positiveInteger(values["--memory"]);
+  if (memory === null) return { kind: "usage-error", message: "--memory must be a positive integer (the newest that many memory entries go into the context)" };
+  return { kind: "foreman-plan", args: { initiativeId, account: values["--account"], skill, memory } };
+}
+const FOREMAN_SERVICE_USAGE = "foreman service needs one of: install [--start], uninstall [--stop], status";
+function parseForemanService(action: string | undefined, rest: string[]): Command {
+  if (action !== "install" && action !== "uninstall" && action !== "status") return { kind: "usage-error", message: FOREMAN_SERVICE_USAGE };
+  const allowed = action === "install" ? "--start" : action === "uninstall" ? "--stop" : undefined;
+  let start = false;
+  let stop = false;
+  for (const token of rest) {
+    if (token !== allowed) return { kind: "usage-error", message: `Unknown option ${token} for foreman service ${action}` };
+    if (token === "--start") start = true;
+    if (token === "--stop") stop = true;
+  }
+  return { kind: "foreman-service", args: { action, start, stop } };
+}
+const FOREMAN_STATUS_USAGE = "foreman status takes no arguments but --watch [--every <seconds>]: foreman status [--watch] [--every <seconds>]";
+/** `foreman status [--watch] [--every <seconds>]`. `--every` without `--watch` is a usage error
+ * rather than a silent no-op: the human asked for a repeating view and would get one reading. */
+function parseForemanStatus(argv: string[]): Command {
+  let watch = false;
+  let watchMs: number | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--watch") {
+      watch = true;
+      continue;
+    }
+    if (token === "--every") {
+      const seconds = Number(argv[++i]);
+      if (!Number.isFinite(seconds) || seconds <= 0) return { kind: "usage-error", message: "foreman status --every needs a positive number of seconds" };
+      watchMs = Math.round(seconds * 1000);
+      continue;
+    }
+    return { kind: "usage-error", message: `Unknown option ${token} for foreman status` };
+  }
+  if (watchMs !== undefined && !watch) return { kind: "usage-error", message: FOREMAN_STATUS_USAGE };
+  return { kind: "foreman-status", args: { watch, watchMs } };
+}
+const FOREMAN_LOGS_USAGE = "foreman logs needs a Task: foreman logs <OPS-123 | taskId> [--lines <n>] [--no-follow]";
+/** `foreman logs <task> [--lines <n>] [--no-follow]`. The Task is an identifier or a numeric id;
+ * which of the two it is, is the command's to work out, not this parser's. */
+function parseForemanLogs(argv: string[]): Command {
+  let task: string | undefined;
+  let lines: number | undefined;
+  let noFollow = false;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--no-follow") {
+      noFollow = true;
+      continue;
+    }
+    if (token === "--lines") {
+      const n = Number(argv[++i]);
+      if (!Number.isInteger(n) || n <= 0) return { kind: "usage-error", message: "foreman logs --lines needs a positive whole number" };
+      lines = n;
+      continue;
+    }
+    if (token.startsWith("--")) return { kind: "usage-error", message: `Unknown option ${token} for foreman logs` };
+    if (task !== undefined) return { kind: "usage-error", message: FOREMAN_LOGS_USAGE };
+    task = token;
+  }
+  if (!task) return { kind: "usage-error", message: FOREMAN_LOGS_USAGE };
+  return { kind: "foreman-logs", args: { task, lines, noFollow } };
+}
+/** `foreman review [<initiativeId>]`; the id is optional because the Process Table usually names
+ * exactly one Initiative and the command falls back to it. */
+function parseForemanReview(argv: string[]): Command {
+  if (argv.length === 0) return { kind: "foreman-review", args: {} };
+  const id = Number(argv[0]);
+  if (argv.length !== 1 || !Number.isInteger(id) || id <= 0) {
+    return { kind: "usage-error", message: "foreman review takes at most one Initiative id: foreman review [initiativeId]" };
+  }
+  return { kind: "foreman-review", args: { initiativeId: id } };
+}
+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 === "run") return parseForemanRun(argv.slice(1));
+  if (group === "plan") return parseForemanPlan(argv.slice(1));
+  if (group === "service") return parseForemanService(action, rest);
+  if (group === "status") return parseForemanStatus(argv.slice(1));
+  if (group === "logs") return parseForemanLogs(argv.slice(1));
+  if (group === "review") return parseForemanReview(argv.slice(1));
+  if (group === "attach" || group === "release" || group === "cancel" || group === "pause" || group === "resume") {
+    return parseForemanControl(`foreman-${group}`, argv.slice(1));
+  }
+  if (group === "debug") {
+    if (action === "turn") return parseDebugTurn(rest);
+    // The other hidden forms take one positive integer: an Initiative id, or a port.
+    const number = Number(rest[0]);
+    if (action === "ready" && Number.isInteger(number) && number > 0) {
+      return { kind: "foreman-debug-ready", initiativeId: number };
+    }
+    if (action === "serve" && Number.isInteger(number) && number > 0 && number < 65536) {
+      return { kind: "foreman-debug-serve", port: number };
+    }
+    // Hidden command: a malformed form is reported as unknown, not documented in usage.
+    return { kind: "unknown", input: ["foreman", ...argv].join(" ") };
+  }
+  if (group !== "account") {
+    return { kind: "usage-error", message: `foreman needs a subcommand: ${FOREMAN_SUBCOMMANDS}` };
+  }
+  switch (action) {
+    case "add":
+      return parseAccountAdd(rest);
+    case "list":
+      return { kind: "foreman-account-list" };
+    case "set":
+      return parseAccountSet(rest);
+    case "remove":
+      return rest[0] ? { kind: "foreman-account-remove", name: rest[0] } : { kind: "usage-error", message: "foreman account remove needs an Account name" };
+    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" };
+  }
+}
+const INITIATIVE_SUBCOMMANDS = "list | show <id> | create | memory <id> | note <id> <body>";
+/** Flag tables per subcommand: the flag as typed, and the field it fills. Kept as data so a typo
+ * is refused by name rather than silently ignored, exactly as the account forms do it. */
+const INITIATIVE_LIST_OPTIONS: Record<string, keyof InitiativeListArgs> = { "--project": "project", "--search": "search" };
+const INITIATIVE_CREATE_OPTIONS: Record<string, keyof InitiativeCreateArgs> = {
+  "--title": "title",
+  "--project": "project",
+  "--summary": "summary",
+  "--status": "status",
+  "--core-idea-file": "coreIdeaFile",
+};
+const INITIATIVE_MEMORY_OPTIONS: Record<string, "kind" | "limit"> = { "--kind": "kind", "--limit": "limit" };
+/**
+ * `--flag value` and `--flag=value` into a record, refusing an unknown flag by name and a flag with
+ * nothing after it. Returns the message rather than throwing, so every caller reports it the same
+ * way. `bare` names the valueless flags, which are set to "" and read as present.
+ */
+function parseFlags<K extends string>(argv: string[], table: Record<string, K>, where: string, bare: readonly string[] = []): Partial<Record<K, string>> | string {
+  const out: Partial<Record<K, 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 (bare.includes(flag)) {
+      if (eq !== -1) return `${flag} takes no value`;
+      out[table[flag]] = "";
+      continue;
+    }
+    const field = table[flag];
+    if (!field) return `Unknown option ${flag} for ${where}`;
+    const value = eq === -1 ? argv[++i] : token.slice(eq + 1);
+    // A flag followed by another flag is a value the user forgot, not a value of "--x".
+    if (value === undefined || (eq === -1 && value.startsWith("--"))) return `${flag} needs a value`;
+    out[field] = value;
+  }
+  return out;
+}
+/** The `<id>` every Initiative subcommand but `list` and `create` takes first. */
+function initiativeId(token: string | undefined, where: string): number | string {
+  if (token === undefined || !/^\d+$/.test(token)) return `${where} needs an Initiative id: opsee initiative ${where.replace("initiative ", "")} <initiativeId>`;
+  const id = Number(token);
+  return id >= 1 ? id : `${where} needs an Initiative id of 1 or more`;
+}
+function parseInitiative(argv: string[]): Command {
+  const [action, ...rest] = argv;
+  switch (action) {
+    case "list": {
+      const flags = parseFlags(rest, INITIATIVE_LIST_OPTIONS, "initiative list");
+      return typeof flags === "string" ? { kind: "usage-error", message: flags } : { kind: "initiative-list", args: flags };
+    }
+    case "show": {
+      const [id, ...flags] = rest;
+      const parsedId = initiativeId(id, "initiative show");
+      if (typeof parsedId === "string") return { kind: "usage-error", message: parsedId };
+      const parsed = parseFlags(flags, { "--context": "context", "--memory": "memory" } as const, "initiative show", ["--context"]);
+      if (typeof parsed === "string") return { kind: "usage-error", message: parsed };
+      return { kind: "initiative-show", args: { initiativeId: parsedId, context: parsed.context !== undefined, memory: parsed.memory } };
+    }
+    case "create": {
+      const flags = parseFlags(rest, INITIATIVE_CREATE_OPTIONS, "initiative create");
+      if (typeof flags === "string") return { kind: "usage-error", message: flags };
+      if (!flags.title) return { kind: "usage-error", message: "initiative create needs a title: opsee initiative create --title <title> [--project <key>] [--summary <text>] [--core-idea-file <path|->]" };
+      return { kind: "initiative-create", args: flags };
+    }
+    case "memory": {
+      const [id, ...flags] = rest;
+      const parsedId = initiativeId(id, "initiative memory");
+      if (typeof parsedId === "string") return { kind: "usage-error", message: parsedId };
+      const parsed = parseFlags(flags, INITIATIVE_MEMORY_OPTIONS, "initiative memory");
+      if (typeof parsed === "string") return { kind: "usage-error", message: parsed };
+      return { kind: "initiative-memory", args: { initiativeId: parsedId, ...parsed } };
+    }
+    case "note": {
+      const [id, ...restOfNote] = rest;
+      const parsedId = initiativeId(id, "initiative note");
+      if (typeof parsedId === "string") return { kind: "usage-error", message: parsedId };
+      // The body is the one positional after the id; flags may sit on either side of it, so it is
+      // whatever is left once the flags are taken out rather than "the next token".
+      const flagTokens: string[] = [];
+      const positionals: string[] = [];
+      for (let i = 0; i < restOfNote.length; i++) {
+        const token = restOfNote[i];
+        if (!token.startsWith("--")) {
+          positionals.push(token);
+          continue;
+        }
+        flagTokens.push(token);
+        if (token.indexOf("=") === -1 && restOfNote[i + 1] !== undefined && !restOfNote[i + 1].startsWith("--")) flagTokens.push(restOfNote[++i]);
+      }
+      const parsed = parseFlags(flagTokens, { "--kind": "kind" } as const, "initiative note");
+      if (typeof parsed === "string") return { kind: "usage-error", message: parsed };
+      if (positionals.length === 0) return { kind: "usage-error", message: 'initiative note needs the note text: opsee initiative note <initiativeId> "what happened" [--kind <kind>]' };
+      if (positionals.length > 1) return { kind: "usage-error", message: `initiative note takes one note; quote it if it has spaces (got ${positionals.length} arguments after the id)` };
+      return { kind: "initiative-note", args: { initiativeId: parsedId, body: positionals[0], kind: parsed.kind } };
+    }
+    default:
+      return { kind: "usage-error", message: `initiative needs a subcommand: ${INITIATIVE_SUBCOMMANDS}` };
+  }
+}
+export function parseCommand(argv: string[]): Command {
+  const [first, ...rest] = argv;
+  switch (first) {
+    case "login":
+      return { kind: "login" };
+    case "whoami":
+      return { kind: "whoami" };
+    case "init":
+      return parseInit(rest);
+    case "foreman":
+      return parseForeman(rest);
+    case "initiative":
+      return parseInitiative(rest);
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      return { kind: "help" };
+    default:
+      return { kind: "unknown", input: first };
+  }
+}
+const INIT_RECIPE_OPTIONS: Record<string, keyof RecipeFlags> = {
+  "--start": "start",
+  "--readiness-url": "readinessUrl",
+  "--port-env": "portEnv",
+  "--typecheck": "typecheck",
+};
+function parseInit(rest: string[]): Command {
+  let projectKey: string | undefined;
+  const recipe: RecipeFlags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    const eq = arg.indexOf("=");
+    const flag = eq === -1 ? arg : arg.slice(0, eq);
+    const recipeField = INIT_RECIPE_OPTIONS[flag];
+    if (arg === "--project" || arg === "-p") {
+      projectKey = rest[++i] ?? "";
+    } else if (arg.startsWith("--project=")) {
+      projectKey = arg.slice("--project=".length);
+    } else if (recipeField) {
+      const value = eq === -1 ? rest[++i] : arg.slice(eq + 1);
+      if (value === undefined || value === "") return { kind: "usage-error", message: `${flag} needs a value` };
+      recipe[recipeField] = value;
+    } else {
+      return { kind: "unknown", input: `init ${arg}` };
+    }
+  }
+  if (projectKey === "") return { kind: "unknown", input: "init --project (missing key)" };
+  return { kind: "init", projectKey, recipe };
+}
+export function usage(): string {
+  return [
+    "Usage: opsee <command>",
+    "",
+    "Commands:",
+    "  opsee login                   Sign in through the browser; shared with the Opsee MCP server",
+    "  opsee whoami                  Show the signed-in user and company",
+    "  opsee init [--project <key>]  Set up the current repo for Opsee-driven planning: planning",
+    "                                skills, the tracker doc, MCP registration, AGENTS.md pointer,",
+    "                                and the Foreman's Run Recipe in .opsee/config",
+    "      [--start <cmd>] [--readiness-url <url>] [--port-env <VAR>] [--typecheck <cmd>]",
+    "                                Run Recipe values for a non-interactive run; {port} in a",
+    "                                command or URL is replaced with the Worker's port",
+    "",
+    "Foreman:",
+    "  opsee foreman up              Start the Foreman daemon: it Reconciles each tick and serves Runs queued by foreman run",
+    "  opsee foreman run <initiativeId> [--account <name>] [--once] [--task <id>]",
+    "      [--max-turns <n>] [--stall-timeout <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",
+    "  opsee foreman plan <initiativeId> [--account <name>] [--skill <to-issues|wayfinder|to-spec>]",
+    "      [--memory <n>]",
+    "                                Open an attended planning session on the Initiative: a Workspace on",
+    "                                a planning branch, the vendor's interactive session there with the",
+    "                                Initiative's context (core idea, task tree, the newest n memory",
+    "                                entries with the Completion Reports, pull requests) as its first",
+    "                                message, and the skill to run",
+    "  opsee foreman service install [--start]",
+    "                                Write the launchd LaunchAgent (macOS) or systemd user unit (Linux)",
+    "                                that runs foreman up in this checkout at login/boot and restarts it",
+    "                                after a crash; prints the commands that load it, or runs them with --start",
+    "  opsee foreman service uninstall [--stop]",
+    "                                Remove that unit (stop and unload it first with --stop)",
+    "  opsee foreman service status  Whether the unit is installed and a daemon is up",
+    "  opsee foreman status [--watch] [--every <seconds>]",
+    "                                What is running on this machine, read fresh from the Process Table:",
+    "                                each Account's Slots (cap, used, reserved Verifier Slot, free), the",
+    "                                live Workers, and every Paused Account and paused Initiative",
+    "  opsee foreman logs <OPS-123 | taskId> [--lines <n>] [--no-follow]",
+    "                                One Worker's transcript: streamed live while its turn is running,",
+    "                                the stored tail once it is over (the header says which)",
+    "  opsee foreman review [<initiativeId>]",
+    "                                The morning summary of a Run from the Run Record: Hand-offs to look",
+    "                                at, Defects filed, Breakers hit, Proposed Learnings to accept, with",
+    "                                every Task named by its title",
+    "  opsee foreman attach <taskId>  Stop the Worker's unattended turn and resume its session here,",
+    "                                in its Workspace, as an attended turn (exit the vendor's session",
+    "                                and run release to hand it back)",
+    "  opsee foreman release <taskId> Hand an attached Worker back: the next tick resumes it unattended",
+    "  opsee foreman cancel <taskId>  Stop the Worker and record the attempt as cancelled; the Task is",
+    "                                left blocked with a comment",
+    "  opsee foreman pause <initiativeId>",
+    "  opsee foreman resume <initiativeId>",
+    "                                Stop and restart new dispatch for the Initiative's Run; running",
+    "                                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> --key-env <VAR> [--name <n>] [--cap <n>]",
+    "  opsee foreman account list",
+    "  opsee foreman account set <name> [--cap <n>] [--max-turns <n>] [--stall-timeout <ms>]",
+    "                                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",
+    "  opsee foreman account remove <name>",
+    "",
+    "Initiatives (the same RPCs the Opsee MCP tools call, printed the same way):",
+    "  opsee initiative list [--project <key>] [--search <text>]",
+    "                                The project's Initiatives, newest first; --search ranks a",
+    "                                keyword against title and summary",
+    "  opsee initiative show <initiativeId> [--context] [--memory <n>]",
+    "                                Title, status, summary and core idea. --context prints the whole",
+    "                                work session instead: task tree, memory log and pull requests",
+    "  opsee initiative create --title <title> [--project <key>] [--summary <text>]",
+    "      [--status <draft|active|paused|done|archived>] [--core-idea-file <path|->]",
+    "                                A new Initiative. The core idea is markdown read from a file, or",
+    "                                from stdin when the path is -",
+    "  opsee initiative memory <initiativeId> [--kind <kind>] [--limit <n>]",
+    "                                The append-only memory log, newest first",
+    "  opsee initiative note <initiativeId> \"what happened\" [--kind <kind>]",
+    "                                Append one entry to that log; --kind is decision, outcome,",
+    "                                learning, blocker or context (the default)",
+    "",
+    "Environment: OPSEE_API_URL, OPSEE_APP_URL, OPSEE_MCP_URL, OPSEE_CREDENTIALS_PATH, OPSEE_API_TOKEN,",
+    "             OPSEE_FOREMAN_ACCOUNTS_PATH, OPSEE_FOREMAN_WORKSPACES_PATH, OPSEE_FOREMAN_LOCAL_DIR",
+    "             (or OPSEE_FOREMAN_PROCESS_TABLE_PATH, OPSEE_FOREMAN_TRANSCRIPTS_PATH, OPSEE_FOREMAN_PID_PATH)",
+  ].join("\n");
+}