@opsee/cli 0.11.9

package/src/commands/foreman.ts

@@ -0,0 +1,465 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { uptime } from "node:os";
+import { AccountError, type Account } from "../foreman/account.js";
+import type { AccountStore } from "../foreman/account-store.js";
+import { defectFilerWith } from "../foreman/core/defects.js";
+import { baseGateCommands, gatesWith, noGatesWarning } from "../foreman/core/gates.js";
+import { handOffWith } from "../foreman/core/handoff.js";
+import { DEFAULT_LEARNINGS_FILE, learningsFileOf, learningsRefusedWith, learningsWith } from "../foreman/core/learnings.js";
+import { OutboxTracker } from "../foreman/core/outbox-tracker.js";
+import { otherForemanWorkersOn, pidIsAlive, type ProcessTable } from "../foreman/core/process-table.js";
+import { ForemanError, isHandedOff, runForeman, type BlockedTask, type Dispatch, type RunAccount, type RunDeps, type RunOutcome, type RunOptions } from "../foreman/core/run.js";
+import { count, printableOneLine } from "../foreman/core/text.js";
+import { summarize } from "../foreman/core/summary.js";
+import type { TranscriptStore } from "../foreman/core/transcripts.js";
+import { verifierWith } from "../foreman/core/verifier.js";
+import { guardedGit, repoRootOf, runGit, WorkspaceManager, type GitRunner } from "../foreman/core/workspace.js";
+import { remoteApiFor, runCli, type RemoteApi } from "../foreman/remote-api.js";
+import type { TrackerAdapter } from "../foreman/tracker-adapter.js";
+import type { WorkerAdapter } from "../foreman/worker-adapter.js";
+
+/** Silence a Worker may keep before the turn is `stalled`: long enough for a real test run, short
+ * enough that a wedged Worker does not hold the Run all night (story 33 tunes this per Account). */
+export const DEFAULT_STALL_TIMEOUT_MS = 15 * 60_000;
+
+/** What is meaningful only on this machine (ADR-0009) and both commands share: the Process Table,
+ * the transcript store and the daemon's pid file. Optional on `foreman run` so the loop can be
+ * exercised without a file; the real command always has it. */
+export interface ForemanLocal {
+  table: ProcessTable;
+  transcripts: TranscriptStore;
+  pidFile: string;
+  /** How a live daemon is told from a stale pid file; the real probe by default, a test's otherwise. */
+  probe?: DaemonProbe;
+}
+
+/** What `liveDaemonPid` asks the machine, injectable so a test can be any boot and any process. */
+export interface DaemonProbe {
+  /** The current time, ms since the epoch. */
+  now?: () => number;
+  /** How long this boot has been up, in ms (os.uptime). */
+  uptimeMs?: () => number;
+  /** Whether a signal could reach the pid (process-table.ts pidIsAlive). */
+  isAlive?: (pid: number) => boolean;
+  /** The command line of the process with that pid, or undefined when it cannot be read (no ps, no
+   * /proc, the process gone in between); undefined means "cannot tell", not "not ours". */
+  commandOf?: (pid: number) => string | undefined;
+}
+
+/** The real probe: `/proc/<pid>/cmdline` where there is one, `ps -o command=` elsewhere. */
+export const realDaemonProbe: Required<DaemonProbe> = {
+  now: () => Date.now(),
+  uptimeMs: () => uptime() * 1000,
+  isAlive: pidIsAlive,
+  commandOf: (pid) => {
+    try {
+      if (process.platform === "linux") return readFileSync(`/proc/${pid}/cmdline`, "utf8").replace(/\0/g, " ");
+      return execFileSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      return undefined;
+    }
+  },
+};
+
+/** What both commands need to build a Run's deps for one Account. */
+export interface SharedDeps {
+  tracker: TrackerAdapter;
+  adapterFor: (account: Account) => WorkerAdapter;
+  out: (line: string) => void;
+  /** The registered Accounts. Where a rate limit's Paused state is written and read back
+   * (story 30), and where the sibling Accounts a Run may Fail over to come from (story 31). Both
+   * commands have one; it is optional here so a test can build a Run's deps without a store, which
+   * then Pauses nothing and Fails over nowhere. */
+  store?: AccountStore;
+  /** Test seams; the real Workspace manager, code host, Hand-off and loop by default. Every git
+   * call the commands make goes through `git`, the guarded runner (ADR-0003). */
+  workspacesFor?: (repoRoot: string, log: (line: string) => void, git: GitRunner) => RunDeps["workspaces"];
+  remoteFor?: (originUrl: string, repoRoot: string) => RemoteApi;
+  handOff?: RunDeps["handOff"];
+  /** The Gates after a Hand-off; the base's Run Recipe commands (`gatesWith`) by default. */
+  gates?: RunDeps["gates"];
+  gateRetries?: number;
+  /** The Verifier after the Gates; the base's Run Recipe app and a Playwright MCP Worker on the
+   * same Account (`verifierWith`) by default. */
+  verifier?: RunDeps["verifier"];
+  /** The Defect filer after a failed Verdict; the real one (`defectFilerWith`) by default. */
+  defects?: RunDeps["defects"];
+  learnings?: RunDeps["learnings"];
+  run?: (deps: RunDeps, options: RunOptions) => Promise<RunOutcome>;
+  install?: RunDeps["install"];
+  isAlive?: RunDeps["isAlive"];
+}
+
+/** Options of `opsee foreman run`. */
+export interface ForemanRunArgs {
+  initiativeId: number;
+  account?: string;
+  once: boolean;
+  taskId?: number;
+  maxTurns?: number;
+  stallTimeoutMs?: number;
+}
+
+export interface ForemanRunDeps extends SharedDeps {
+  store: AccountStore;
+  /** The repository the Run works on: the checkout the command runs in. */
+  repoRoot: () => Promise<string | undefined>;
+  local?: ForemanLocal;
+}
+
+/** The pid in the daemon's pid file when that daemon is alive; undefined for no file, one that
+ * does not hold a number, or a stale one. Stale is: written before this boot (its mtime predates
+ * the uptime; a reboot restarts pids low, so last boot's number is often some other process's
+ * today, and pidIsAlive counts EPERM as alive), naming a pid nothing answers at, or naming a pid
+ * whose command line can be read and is not a Foreman. A command line that cannot be read is not
+ * held against the pid: better to refuse a start than to run two daemons. */
+export function liveDaemonPid(pidFile: string, probe: DaemonProbe = {}): number | undefined {
+  const { now, uptimeMs, isAlive, commandOf } = { ...realDaemonProbe, ...probe };
+  if (!existsSync(pidFile)) return undefined;
+  const pid = Number.parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+  if (!Number.isInteger(pid) || pid <= 0) return undefined;
+  if (statSync(pidFile).mtimeMs < now() - uptimeMs()) return undefined;
+  if (!isAlive(pid)) return undefined;
+  const command = commandOf(pid);
+  return command === undefined || /foreman/.test(command) ? pid : undefined;
+}
+
+/**
+ * Refuses a foreground Run on an Account another Foreman is already running Workers under
+ * (story 27, ADR-0013).
+ *
+ * The cap is the Account's, but `new Slots(cap)` is the Run's: two `foreman run` in two terminals
+ * on one Account would each fill their own Slots and put 2 x cap Workers on one vendor identity —
+ * exactly what `registerAccount`'s twin check refuses to let two *Accounts* do to one login, and
+ * what the README's "what one person at one keyboard looks like" claims. The Process Table is the
+ * only state the two processes share, so it is what is asked: one `liveWorkers({ account })` query.
+ *
+ * Rows whose Worker is gone are not held against the new Run — they are what Reconcile exists to
+ * settle, and refusing on them would leave every crashed Run needing a manual cleanup before
+ * anything could start again. That leaves one hole, deliberately: a live Foreman whose Worker
+ * Adapter reports no pid has rows this cannot tell from a dead one's, and two Runs could still
+ * overlap there. Closing it wants a heartbeat or a lock in the table itself, which is its own
+ * change (the same fact `Scheduling.owns` is in-process only for).
+ */
+export function refuseSecondRunOnAccount(table: Pick<ProcessTable, "liveWorkers">, account: Account, isAlive: (pid: number | undefined) => boolean = pidIsAlive): void {
+  const live = table.liveWorkers({ account: account.name }).filter((row) => row.pid !== undefined && isAlive(row.pid));
+  if (live.length === 0) return;
+  const which = live.map((row) => `${row.identifier} (pid ${row.pid})`).join(", ");
+  throw new ForemanError(
+    `Account "${account.name}" already has ${count(live.length, "Worker")} running under another Foreman: ${which}. ` +
+      `The cap is what one vendor identity may run at once (ADR-0013), and a second Run here would have its own Slots and double it. ` +
+      `Wait for that Foreman, or queue this Run for a daemon (opsee foreman up), or run it on another Account (--account <name>).`,
+  );
+}
+
+/**
+ * Refuses a Run whose own Account is quarantined (OPS-288).
+ *
+ * The Run loop would notice anyway — `quarantinedNow` drops the Lane and the tick ends the Run — but
+ * only after opening the Process Table, Reconciling and asking the Tracker for Ready Tasks, and the
+ * line it prints then is about Lanes rather than about the Account the operator named. Refused here
+ * instead, in the words of the thing they can fix.
+ *
+ * Deliberately not in `chooseAccount`, which `foreman plan` and the daemon also call: an attended
+ * planning session on a quarantined Account is the vendor prompting a human who is sitting there to
+ * log in, which is the remedy rather than the problem.
+ */
+export function refuseQuarantinedRun(account: Account): void {
+  if (!account.quarantined) return;
+  throw new ForemanError(
+    `Account "${account.name}" is quarantined: its credential was judged dead at ${account.quarantined.at} (${printableOneLine(account.quarantined.reason)}). ` +
+      `A quarantined Account contributes no Slots and is not a Failover target, so this Run would have nowhere to dispatch. ` +
+      `Log the vendor back in and run "opsee foreman account resume ${account.name}", or run it on another Account (--account <name>).`,
+  );
+}
+
+/** Picks the Account a Run uses: the named one, or the only one registered. */
+export function chooseAccount(accounts: Account[], name: string | undefined): Account {
+  if (accounts.length === 0) {
+    throw new AccountError("No Account registered; register one with: opsee foreman account add --vendor claude --config-dir <dir>");
+  }
+  if (name !== undefined) {
+    const found = accounts.find((a) => a.name === name);
+    if (!found) throw new AccountError(`No Account named "${name}" (have: ${accounts.map((a) => a.name).join(", ")})`);
+    return found;
+  }
+  if (accounts.length > 1) {
+    throw new AccountError(`Several Accounts are registered; pass --account <name> (have: ${accounts.map((a) => a.name).join(", ")})`);
+  }
+  return accounts[0];
+}
+
+/** The repository's learnings file, or the default with the reason the configured one is refused
+ * (`learningsFileOf`). Both commands say so once at start; `runDepsFor` reads it again per Run. */
+export function checkLearningsFile(repoRoot: string): { file: string; refused?: string } {
+  try {
+    return { file: learningsFileOf(repoRoot) };
+  } catch (error) {
+    return { file: DEFAULT_LEARNINGS_FILE, refused: `${error instanceof Error ? error.message : String(error)}; Proposed Learnings are not submitted until it is fixed, and Workers read ${DEFAULT_LEARNINGS_FILE}` };
+  }
+}
+
+/** One Run's deps for one Account: the Tracker behind the outbox, the Worker Adapter for the
+ * Account's vendor, the Workspace manager and Hand-off for the checkout (every git call through
+ * the guarded runner, ADR-0003; the code host chosen from origin up front, so a repository the
+ * Foreman could never hand off from is refused before any Worker turn), and the machine-local
+ * record. */
+export async function runDepsFor(
+  shared: SharedDeps,
+  account: Account,
+  repoRoot: string,
+  local: ForemanLocal | undefined,
+  options: { maxTurns?: number; stallTimeoutMs?: number; failover?: boolean },
+): Promise<RunDeps> {
+  const outbox = local ? new OutboxTracker(shared.tracker, local.table, shared.out) : undefined;
+  const git = guardedGit(runGit, repoRoot);
+  const workspaces = (shared.workspacesFor ?? ((root, log, guarded) => new WorkspaceManager(root, { log, git: guarded })))(repoRoot, shared.out, git);
+  // The code host serves the Hand-off, the Gates' comment on it and the learnings pull request;
+  // it is read from origin once, and only when a step that needs it is not handed in by a test.
+  let remote: RemoteApi | undefined;
+  const remoteOnce = async () => (remote ??= await remoteFor(shared, git, repoRoot));
+  const handOff = shared.handOff ?? handOffWith({ git, remote: await remoteOnce(), repoRoot, log: shared.out });
+  // A bad `foreman.learnings_file` must not stop the Run, nor Reconcile of the Workers alive under
+  // a daemon that builds these deps every tick: Workers read the default file, and the learnings
+  // step reports the refusal instead of submitting.
+  const learningsConfig = checkLearningsFile(repoRoot);
+  const learningsFile = learningsConfig.file;
+  const learnings = shared.learnings ?? (learningsConfig.refused ? learningsRefusedWith(learningsConfig.refused) : learningsWith({ git, remote: await remoteOnce(), repoRoot, workspaces, file: learningsFile, log: shared.out }));
+  const worker = shared.adapterFor(account);
+  // The Run's own flags win, then the Account's own limits (story 33: a subscription that bills by
+  // turn, or one whose Workers are known to go quiet, carries its numbers rather than the Run
+  // repeating them), then the CLI's default.
+  const maxTurns = options.maxTurns ?? account.maxTurns;
+  const stallTimeoutMs = options.stallTimeoutMs ?? account.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+  const tracker = outbox ?? shared.tracker;
+  // A base that names no Gate command is a whole-Run condition: every Hand-off this Run makes will
+  // reach In review with nothing on this machine having run the repository's tests, lint or
+  // typecheck. Said once at the start, loudly, rather than only per Task in the morning. Not on the
+  // daemon's idle Reconcile tick (`failover: false`), which dispatches nothing and would repeat it
+  // every tick, and not when a test hands in its own Gates.
+  if (options.failover !== false && !shared.gates) {
+    const base = await baseGateCommands(git, repoRoot);
+    const warning = noGatesWarning(base.commands, base.source);
+    if (warning) shared.out(warning);
+  }
+  /** One Account's own steps: the adapter for its vendor, and the Gates and Verifier built on it.
+   * Both take an Account because both spend the vendor's identity — the Verifier runs a second
+   * unattended turn on it, the Gates run their shell without its key. */
+  const runAccountFor = (a: Account): RunAccount => {
+    const adapter = shared.adapterFor(a);
+    // The same precedence as the Run's own Account: the Run's flags, then this Account's own
+    // limits, then the CLI's default. Carried on the RunAccount so the implementer turn on this
+    // Lane runs under them too — `schedulingFor` (core/run.ts) reads them — rather than under the
+    // primary Account's, which would make `foreman account set --max-turns` on a Failover Account
+    // a setting the Verifier honoured and the Worker ignored.
+    const laneMaxTurns = options.maxTurns ?? a.maxTurns;
+    const laneStallTimeoutMs = options.stallTimeoutMs ?? a.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+    return {
+      account: a,
+      worker: adapter,
+      maxTurns: laneMaxTurns,
+      stallTimeoutMs: laneStallTimeoutMs,
+      gates: shared.gates ?? gatesWith({ git, repoRoot, account: a, log: shared.out }),
+      verifier: shared.verifier ?? verifierWith({ git, repoRoot, worker: adapter, account: a, transcripts: local?.transcripts, maxTurns: laneMaxTurns, stallTimeoutMs: laneStallTimeoutMs, log: shared.out }),
+    };
+  };
+  // Failover is a Run's business: the daemon's idle Reconcile builds these deps to settle one
+  // Account's rows and dispatches nothing, so it asks for none (`failover: false`) rather than
+  // reading the store and logging about siblings every tick.
+  const failover = options.failover === false ? [] : failoverAccountsFor(shared, account, local, shared.isAlive ?? pidIsAlive).map(runAccountFor);
+  // The Accounts of another vendor, as Lanes only a pinned Task may use (story 24). Built exactly
+  // like a Failover Lane — the same adapter, Gates and Verifier for that Account — and asked for
+  // under the same condition: the daemon's idle Reconcile dispatches nothing, so it wants none.
+  const pinnable = options.failover === false ? [] : pinnableAccountsFor(shared, account, local, shared.isAlive ?? pidIsAlive).map(runAccountFor);
+  return {
+    tracker,
+    worker,
+    account,
+    failover,
+    pinnable,
+    accounts: shared.store,
+    workspaces,
+    install: shared.install,
+    handOff,
+    // The base's recipe through the guarded git, never the Workspace's (gates.ts); the Account so
+    // the Gate shell does not see its key.
+    gates: shared.gates ?? gatesWith({ git, repoRoot, account, log: shared.out }),
+    gateRetries: shared.gateRetries,
+    // The same recipe and Account for the Verifier (verifier.ts): a second unattended turn through
+    // the same Worker Adapter, in a scratch directory with Playwright MCP.
+    verifier: shared.verifier ?? verifierWith({ git, repoRoot, worker, account, transcripts: local?.transcripts, maxTurns, stallTimeoutMs, log: shared.out }),
+    // Every Defect of a failed Verdict becomes a sibling Task of the Initiative (defects.ts);
+    // through the same Tracker as the rest of the Run, so an offline Run Record does not stop it.
+    defects: shared.defects ?? defectFilerWith({ tracker, log: shared.out }),
+    remote,
+    learnings,
+    learningsFile,
+    log: shared.out,
+    maxTurns,
+    stallTimeoutMs,
+    tickDelayMs: 1000,
+    processTable: local?.table,
+    transcripts: local?.transcripts,
+    drainOutbox: outbox ? (id) => outbox.drain(id) : undefined,
+    isAlive: shared.isAlive,
+  };
+}
+
+/**
+ * The sibling Accounts a Run on `account` may Fail over to (story 31): every other registered
+ * Account of the same vendor, minus the ones another Foreman is already running Workers under *at
+ * the moment the Run is built*.
+ *
+ * That last filter is the vendor-terms boundary again (ADR-0013). The cap is what one identity may
+ * run at once and the Slots that enforce it are a Run's, so an Account another Foreman already has
+ * Workers on is one this Run must not open Slots of its own on — the same reason a second
+ * foreground Run on the *primary* Account is refused outright (`refuseSecondRunOnAccount`). Here it
+ * is a filter rather than a refusal: the Run has its own Account to work on, and losing a Failover
+ * target is a narrower fleet, not a reason to refuse the work.
+ *
+ * This pass alone does **not** keep the boundary, and does not claim to: a Lane that is idle now
+ * may be a second Foreman's before this Run ever fails over onto it (that Foreman's own
+ * `refuseSecondRunOnAccount` sees nothing here either, since this Run has not touched the Account).
+ * What keeps it is the Run loop asking the Process Table again each tick and dropping a Lane that
+ * is not clean (`contendedNow`, core/run.ts). This is the cheap first cut: an Account that is
+ * plainly busy never becomes a Lane at all, and the one line about it is written once at start
+ * rather than on every tick.
+ */
+export function failoverAccountsFor(shared: SharedDeps, account: Account, local: ForemanLocal | undefined, isAlive: (pid: number | undefined) => boolean, now: () => number = Date.now): Account[] {
+  const siblings = (shared.store?.load() ?? []).filter((a) => a.name !== account.name && a.vendor === account.vendor);
+  return uncontended(shared, notQuarantined(shared, siblings, "Failover"), local, isAlive, now, "Failover");
+}
+
+/**
+ * The Accounts a *pinned* Task may be routed to that Failover would never reach (story 24): every
+ * registered Account of another vendor, minus the ones another Foreman is already running Workers
+ * under. They become pin-only Lanes inside the Run (`RunDeps.pinnable`, core/run.ts).
+ *
+ * Vendor is the whole difference from `failoverAccountsFor`, and it is the difference that makes
+ * them two functions rather than one: Failover moves work the Foreman chose to move, and moving a
+ * Task between vendors is not the same work moved (the session, the prompt contract and the adapter
+ * are the vendor's), so it stays within one. A pin is the developer choosing, having said which
+ * vendor they meant — which is the entire point of story 24 — so it crosses.
+ *
+ * The contention filter is the same one and for the same reason (ADR-0013): an Account another
+ * Foreman has Workers on is one this Run must not open Slots of its own on, whatever the reason it
+ * wanted to. A pinned Task whose only Lane is dropped here waits, and is told so.
+ */
+export function pinnableAccountsFor(shared: SharedDeps, account: Account, local: ForemanLocal | undefined, isAlive: (pid: number | undefined) => boolean, now: () => number = Date.now): Account[] {
+  const others = (shared.store?.load() ?? []).filter((a) => a.name !== account.name && a.vendor !== account.vendor);
+  return uncontended(shared, notQuarantined(shared, others, "a pinned Task"), local, isAlive, now, "a pinned Task");
+}
+
+/**
+ * Drops the quarantined Accounts, saying so once each (OPS-288).
+ *
+ * The cheap first cut, exactly as the contention filter beside it is: a Lane the Run never builds
+ * costs nothing to skip every tick. It is not what keeps a quarantined Account out — `quarantinedNow`
+ * inside the Run re-reads the store each tick, and has to, because the quarantine that matters most
+ * is the one a turn of this very Run just wrote. What this buys is the line at start, which is where
+ * an operator looks to see why the fleet is narrower than the Accounts they registered.
+ */
+function notQuarantined(shared: SharedDeps, accounts: Account[], use: string): Account[] {
+  return accounts.filter((a) => {
+    if (!a.quarantined) return true;
+    shared.out(
+      `run: Account "${a.name}" is quarantined (${printableOneLine(a.quarantined.reason)}), so it is not used for ${use}. ` +
+        `Log the vendor back in, then: opsee foreman account resume ${a.name}`,
+    );
+    return false;
+  });
+}
+
+/** Drops the Accounts another Foreman has live Workers on, saying so once per Account. */
+function uncontended(shared: SharedDeps, accounts: Account[], local: ForemanLocal | undefined, isAlive: (pid: number | undefined) => boolean, now: () => number, use: string): Account[] {
+  if (!local) return accounts;
+  const at = now();
+  return accounts.filter((a) => {
+    const live = otherForemanWorkersOn(local.table, a.name, at, { isAlive });
+    if (live.length === 0) return true;
+    shared.out(`run: Account "${a.name}" has ${count(live.length, "Worker")} running under another Foreman, so it is not used for ${use}; its own Foreman keeps its cap`);
+    return false;
+  });
+}
+
+/** The code host behind the checkout's origin, for the Hand-off. */
+async function remoteFor(deps: SharedDeps, git: GitRunner, repoRoot: string): Promise<RemoteApi> {
+  let originUrl: string;
+  try {
+    originUrl = await git(["remote", "get-url", "origin"], repoRoot);
+  } catch {
+    throw new ForemanError("This repository has no origin remote. The Foreman hands work off as a draft pull request on origin, so it needs one (ADR-0003).");
+  }
+  try {
+    return (deps.remoteFor ?? ((url, root) => remoteApiFor(url, runCli, root)))(originUrl, repoRoot);
+  } catch (error) {
+    throw new ForemanError(`Cannot hand off from this repository: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/** The Run's tally, and the comment it leaves on the Initiative, both live in core beside the
+ * Run itself (`core/summary.ts`): the counting has one owner, and a terminal line that disagreed
+ * with the Initiative comment about how many Tasks need a human would be worse than either alone.
+ * Re-exported here because this is where every caller and test already looks for it. */
+export { summarize };
+
+/** What a Reconcile pass produced, in the shape of a Run's outcome. */
+export function reconciled(results: Array<Dispatch | BlockedTask>): RunOutcome {
+  const outcome: RunOutcome = { dispatches: [], blocked: [], failures: [] };
+  for (const r of results) {
+    if ("missing" in r) outcome.blocked.push(r);
+    else outcome.dispatches.push(r);
+  }
+  return outcome;
+}
+
+/** `opsee foreman run <initiativeId>` (story 14): a Run scoped to that Initiative. With a daemon
+ * up (its pid file names a live process) the request is queued for it and this returns at once;
+ * otherwise the Run happens in the foreground, until no Ready Task remains. Exit 0 when every
+ * dispatched Task was handed off (reported `done` with its draft pull request open) and no Ready
+ * Task was blocked on its work contract, 1 otherwise (blocked, failed, stalled, nothing to
+ * push...), so a script can tell the two apart. The code host is chosen from origin before the
+ * first dispatch: a repository the Foreman could never hand off from is refused up front. */
+export async function runForemanRun(deps: ForemanRunDeps, args: ForemanRunArgs): Promise<number> {
+  const account = chooseAccount(deps.store.load(), args.account);
+  const repoRoot = await deps.repoRoot();
+  if (!repoRoot) throw new ForemanError("Not inside a git repository; run foreman run from the checkout the Initiative's Tasks are about.");
+
+  const daemon = deps.local ? liveDaemonPid(deps.local.pidFile, deps.local.probe) : undefined;
+  if (daemon !== undefined && deps.local) {
+    const request = deps.local.table.requestRun({
+      initiativeId: args.initiativeId,
+      account: account.name,
+      once: args.once,
+      taskId: args.taskId,
+      repoRoot,
+      maxTurns: args.maxTurns,
+      stallTimeoutMs: args.stallTimeoutMs,
+    });
+    deps.out(`Run #${request.id} queued for the Foreman daemon (pid ${daemon}) on Account "${account.name}"; it starts on the daemon's next tick and its output goes to the daemon's terminal.`);
+    return 0;
+  }
+
+  // In the foreground this process is the one running the Workers, so it is the one that must not
+  // double the Account's cap on top of another Foreman's.
+  if (deps.local) refuseSecondRunOnAccount(deps.local.table, account, deps.isAlive ?? pidIsAlive);
+  refuseQuarantinedRun(account);
+
+  deps.out(`repository: ${repoRoot}`);
+  const learningsConfig = checkLearningsFile(repoRoot);
+  if (learningsConfig.refused) deps.out(`learnings: ${learningsConfig.refused}`);
+  // In the foreground there is no daemon to hand a paused Run back to, so it waits for the resume.
+  const outcome = await (deps.run ?? runForeman)(await runDepsFor(deps, account, repoRoot, deps.local, { maxTurns: args.maxTurns, stallTimeoutMs: args.stallTimeoutMs }), {
+    initiativeId: args.initiativeId,
+    once: args.once,
+    taskId: args.taskId,
+    waitWhilePaused: true,
+  });
+  const { line, needingAttention, blocked } = summarize(outcome);
+  deps.out(`Run over: ${line}`);
+  return needingAttention === 0 && blocked === 0 ? 0 : 1;
+}
+
+/** The repository the current directory is in, for the real command. */
+export const currentRepoRoot = () => repoRootOf(process.cwd());

package/src/commands/init.ts

@@ -0,0 +1,176 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Client } from "@connectrpc/connect";
+import type { ProjectService } from "@opsee/mcp-server/gen/api/v1/project_pb.js";
+import type { LabelService } from "@opsee/mcp-server/gen/api/v1/label_pb.js";
+import type { BoardService } from "@opsee/mcp-server/gen/api/v1/board_pb.js";
+import type { BoardColumnService } from "@opsee/mcp-server/gen/api/v1/board_column_pb.js";
+import type { TaskTypeService } from "@opsee/mcp-server/gen/api/v1/task_type_pb.js";
+import type { TaskPriorityService } from "@opsee/mcp-server/gen/api/v1/task_priority_pb.js";
+import { planWrite, type WriteAction, type WritePlan } from "../init/managed.js";
+import { mergeClaudeMcpJson, mergeCodexConfigToml } from "../init/mcp-config.js";
+import { pickInstructionFile, pointerBlock, upsertPointerBlock } from "../init/pointer-block.js";
+import { CLAUDE_MCP_PATH, CODEX_CONFIG_PATH, SKILL_TARGETS, TRACKER_DOC_PATH } from "../init/paths.js";
+import { pickProject, type ProjectChoice } from "../init/project.js";
+import { listSkillFiles, skillNames } from "../init/skills.js";
+import { findReadyLabel, READY_LABEL, renderTrackerDoc, type Named, type TrackerDocData } from "../init/tracker-doc.js";
+import { existingRecipe, inferRecipe, mergeRecipeJson, mergeRecipeYaml, NO_START_COMMAND, type RecipeDefaults, type RecipeFlags } from "../init/run-recipe-config.js";
+import { OPSEE_CONFIG_JSON, OPSEE_CONFIG_YAML, readOpseeConfigFiles } from "../opsee-config.js";
+import type { RunRecipe } from "../foreman/run-recipe.js";
+import { NOT_LOGGED_IN } from "./whoami.js";
+import type { CommandDeps } from "./deps.js";
+
+/** The slices of the generated clients `init` reads; tests supply fakes. All reads: setting a
+ * repo up never writes to the tracker. */
+export interface InitApi {
+  projects: Pick<Client<typeof ProjectService>, "getProjects">;
+  labels: Pick<Client<typeof LabelService>, "getLabels">;
+  boards: Pick<Client<typeof BoardService>, "getBoards">;
+  boardColumns: Pick<Client<typeof BoardColumnService>, "getBoardColumns">;
+  taskTypes: Pick<Client<typeof TaskTypeService>, "getTaskTypes">;
+  taskPriorities: Pick<Client<typeof TaskPriorityService>, "getTaskPriorities">;
+}
+
+export interface InitDeps extends Pick<CommandDeps, "isAuthenticated" | "out"> {
+  api: InitApi;
+  /** The repo to set up; `init` writes only under it. */
+  root: string;
+  /** `--project <key>`; when absent and the account has several projects, `choose` is asked. */
+  projectKey?: string;
+  /** Interactive picker; resolves null when there is no terminal to ask on. */
+  choose: (projects: ProjectChoice[]) => Promise<string | null>;
+  mcpUrl: string;
+  skillsDir: string;
+  trackerTemplate: string;
+  /** Run Recipe values given on the command line; the rest is inferred or asked for. */
+  recipeFlags: RecipeFlags;
+  /** Asks for the Run Recipe with inferred defaults; null when there is no start command to
+   * write. Only called when `.opsee/config` has no `foreman` block yet. */
+  askRecipe: (defaults: RecipeDefaults) => Promise<RunRecipe | null>;
+}
+
+export const CODEX_TRUST_HINT =
+  "Codex reads .codex/config.toml only in a trusted project: open the repo in Codex once and accept its trust prompt.";
+
+/** Sets a repo up for Opsee-driven planning: skills, tracker doc, MCP registration, and the
+ * instructions pointer. Re-runs update what Opsee wrote and leave anything else alone. Returns
+ * the exit code. */
+export async function runInit(deps: InitDeps): Promise<number> {
+  if (!deps.isAuthenticated()) {
+    deps.out(NOT_LOGGED_IN);
+    return 1;
+  }
+  const res = await deps.api.projects.getProjects({});
+  const project = await pickProject(
+    res.projects.filter((p) => p.isActive).map((p) => ({ id: p.id, key: p.shortName, name: p.name })),
+    deps.projectKey,
+    deps.choose,
+  );
+  if (typeof project === "string") {
+    deps.out(project);
+    return 1;
+  }
+  const data = await collect(deps.api, project);
+  const doc = renderTrackerDoc(deps.trackerTemplate, data);
+  const skills = listSkillFiles(deps.skillsDir);
+
+  const report = new Reporter(deps.root, deps.out);
+  for (const target of SKILL_TARGETS) {
+    for (const file of skills) {
+      const rel = join(target, file.rel);
+      report.apply(rel, planWrite(read(deps.root, rel), file.content, file.style));
+    }
+  }
+  report.apply(TRACKER_DOC_PATH, planWrite(read(deps.root, TRACKER_DOC_PATH), doc, "markdown"));
+  report.apply(CLAUDE_MCP_PATH, mergeClaudeMcpJson(read(deps.root, CLAUDE_MCP_PATH), deps.mcpUrl));
+  report.apply(CODEX_CONFIG_PATH, mergeCodexConfigToml(read(deps.root, CODEX_CONFIG_PATH), deps.mcpUrl));
+  const instructions = pickInstructionFile((name) => existsSync(join(deps.root, name)));
+  report.apply(instructions, upsertPointerBlock(read(deps.root, instructions), pointerBlock(TRACKER_DOC_PATH)));
+
+  // The Run Recipe (spec story 5): written once into the analyzer's config, in both of its forms
+  // when both exist, and never rewritten while a foreman block is there. A block present in only
+  // one of the two files is copied into the other, so they stay in step without a prompt.
+  const config = readOpseeConfigFiles(deps.root);
+  const answers = existingRecipe(config) ?? (await deps.askRecipe(inferRecipe(config, deps.recipeFlags)));
+  if (answers === null) {
+    deps.out(`skipped   ${OPSEE_CONFIG_YAML} — ${NO_START_COMMAND}`);
+  } else {
+    report.apply(OPSEE_CONFIG_YAML, mergeRecipeYaml(config.yaml, answers));
+    if (config.json !== null || config.yaml === null) report.apply(OPSEE_CONFIG_JSON, mergeRecipeJson(config.json, answers));
+  }
+
+  deps.out("");
+  deps.out(`Project ${project.name} (${project.key}, id ${project.id}); skills ${skillNames(skills).map((s) => `/${s}`).join(", ")}.`);
+  if (!findReadyLabel(data.labels)) {
+    deps.out(`Project ${project.key} has no ${READY_LABEL} label, the dispatch signal the skills rely on. Create it in Opsee and re-run opsee init to fill in its id.`);
+  }
+  deps.out(CODEX_TRUST_HINT);
+  deps.out(report.summary());
+  return 0;
+}
+
+/** Everything the tracker doc names by id. */
+async function collect(api: InitApi, project: ProjectChoice): Promise<TrackerDocData> {
+  const projectId = project.id;
+  const named = (items: Array<{ id: number; name: string }>): Named[] => items.map((i) => ({ id: i.id, name: i.name }));
+  const boards = (await api.boards.getBoards({ projectId })).boards
+    .filter((b) => b.isActive)
+    .sort((a, b) => a.displayOrder - b.displayOrder);
+  const board = boards.find((b) => /main/i.test(b.name)) ?? boards[0];
+  if (!board) throw new Error(`Project ${project.key} has no board`);
+  const columns = (await api.boardColumns.getBoardColumns({ boardId: board.id })).boardColumns
+    .filter((c) => c.isActive)
+    .sort((a, b) => a.displayOrder - b.displayOrder);
+  const types = (await api.taskTypes.getTaskTypes({ projectId })).taskTypes
+    .filter((t) => t.isActive)
+    .sort((a, b) => a.displayOrder - b.displayOrder);
+  const priorities = (await api.taskPriorities.getTaskPriorities({ projectId })).taskPriorities
+    .filter((p) => p.isActive)
+    .sort((a, b) => a.level - b.level);
+  const labels = (await api.labels.getLabels({ projectId })).labels.filter((l) => l.isActive);
+  return {
+    project: { id: projectId, name: project.name, key: project.key },
+    labels: named(labels),
+    board: { id: board.id, name: board.name },
+    columns: named(columns),
+    types: named(types),
+    priorities: named(priorities),
+  };
+}
+
+function read(root: string, rel: string): string | null {
+  const path = join(root, rel);
+  return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
+const EXPLAIN: Partial<Record<WriteAction, string>> = {
+  "kept-edited": "edited since opsee init wrote it; delete it to let opsee init write its own",
+  "kept-unmanaged": "not written by opsee init; delete it to let opsee init write its own",
+};
+
+class Reporter {
+  private counts = new Map<WriteAction, number>();
+
+  constructor(
+    private root: string,
+    private out: (line: string) => void,
+  ) {}
+
+  apply(rel: string, plan: WritePlan) {
+    if (plan.content !== undefined && (plan.action === "create" || plan.action === "update")) {
+      const path = join(this.root, rel);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, plan.content);
+    }
+    this.counts.set(plan.action, (this.counts.get(plan.action) ?? 0) + 1);
+    const why = plan.action === "kept-invalid" ? `${plan.reason}` : EXPLAIN[plan.action];
+    const verb = plan.action.startsWith("kept") ? "kept" : plan.action;
+    this.out(`${verb.padEnd(9)} ${rel}${why ? ` — ${why}` : ""}`);
+  }
+
+  summary(): string {
+    const n = (a: WriteAction) => this.counts.get(a) ?? 0;
+    const kept = n("kept-edited") + n("kept-unmanaged") + n("kept-invalid");
+    return `${n("create")} created, ${n("update")} updated, ${n("unchanged")} unchanged, ${kept} kept.`;
+  }
+}