@opsee/cli 0.11.9

package/src/commands/foreman-control.ts

@@ -0,0 +1,242 @@
+/**
+ * The human's controls on a Run (stories 53-56): `opsee foreman attach <task>`, `release <task>`,
+ * `pause <initiative>`, `resume <initiative>` and `cancel <task>`. CLI only, by design: the daemon
+ * holds the subscriptions, and nothing on a web page controls it (spec, "Out of Scope").
+ *
+ * The daemon (or a foreground `foreman run`) owns the Workers; these commands run in another
+ * process and speak to it through the Process Table, the machine-local control channel
+ * (ADR-0009): a mark on the Worker's row, or a pause row for the Initiative. The command that
+ * marks a row is also the one that stops the process, by the pid the row records, so the human
+ * sees the Worker gone before the command returns, and it forgets that pid once the process is
+ * gone; the process that owns the turn reads the mark when the stream ends and settles accordingly
+ * (core/run.ts), and Reconcile does the same for a row nobody owns (core/reconcile.ts). The mark
+ * and the owner's settlement can still cross: a turn that ends on its own while the command runs.
+ * So the mark is refused when the row is already gone, and when nothing was stopped the command
+ * confirms the row is still there and the Task still wears `foreman:running` before going on.
+ * Every control lands on the Run Record as a `control` event, through the outbox so an unreachable
+ * backend queues it; a backend that refuses the event is reported, but never undoes what was done
+ * on the machine, since the human asked for exactly that.
+ *
+ * Attach is the one control with a second half: once the unattended turn is stopped, this process
+ * runs the vendor's own interactive resume of the same session in the Workspace (the Worker
+ * Adapter's `interactiveCommand`), with the terminal inherited, and waits for the human to leave
+ * it. The command is built before anything is marked or stopped (an Account whose key is unset
+ * fails there), and a session that cannot be opened (no vendor binary) hands the Worker straight
+ * back, so Reconcile resumes it. The row stays `attached` until `release`, so Reconcile never
+ * resumes it underneath them.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { AccountError, type Account } from "../foreman/account.js";
+import type { AccountStore } from "../foreman/account-store.js";
+import { OutboxTracker } from "../foreman/core/outbox-tracker.js";
+import type { WorkerRow } from "../foreman/core/process-table.js";
+import { controlEvent, ForemanError, STATUS_LABELS, type ControlAction } from "../foreman/core/run.js";
+import { stopProcessByPid } from "../foreman/process-group.js";
+import type { TrackerAdapter } from "../foreman/tracker-adapter.js";
+import type { InteractiveCommand, WorkerAdapter } from "../foreman/worker-adapter.js";
+import { errorMessage, KILL_GRACE_MS } from "../foreman/worker-process.js";
+import type { ForemanLocal } from "./foreman.js";
+
+export interface ForemanControlDeps {
+  tracker: TrackerAdapter;
+  store: AccountStore;
+  local: ForemanLocal;
+  adapterFor: (account: Account) => WorkerAdapter;
+  out: (line: string) => void;
+  /** Stops the Worker a row names, from this process; true when something was running, false when
+   * nothing alive was the Worker (a dead pid, or one the OS reused), and it throws when the stop
+   * could not be carried out (`StopRefusedError`). The process-group kill by the row's pid by
+   * default; the tests stop the fake's handle instead. */
+  stopWorker?: (row: WorkerRow) => Promise<boolean>;
+  /** Runs the attended turn with the terminal inherited and resolves to its exit code; rejects when
+   * the vendor's command could not start. */
+  runInteractive?: (command: InteractiveCommand) => Promise<number>;
+  now?: () => number;
+}
+
+/** Stops the Worker, and the app a Verifier round has running for the Task (`appPid`), which the
+ * Worker's process group does not contain: the app was spawned by the Foreman, not by the Worker. */
+const defaultStopWorker = async (row: WorkerRow): Promise<boolean> => {
+  const worker = row.pid === undefined ? false : await stopProcessByPid(row.pid, KILL_GRACE_MS, { startedAt: row.startedAt });
+  const app = row.appPid === undefined ? false : await stopProcessByPid(row.appPid, KILL_GRACE_MS, { startedAt: row.startedAt });
+  return worker || app;
+};
+
+/** Runs an attended session in this terminal, stdio inherited, and resolves to its exit code;
+ * rejects when the vendor's command could not start. Shared with `foreman plan`, which asks for
+ * the child through `onSpawn` so a signal to this process can be forwarded to the session. */
+export const runInteractiveCommand = (command: InteractiveCommand, options: { onSpawn?: (child: ChildProcess) => void } = {}): Promise<number> =>
+  new Promise((resolve, reject) => {
+    const child = spawn(command.command, command.args, { cwd: command.cwd, env: command.env, stdio: "inherit" });
+    options.onSpawn?.(child);
+    child.once("error", (error) => reject(new ForemanError(`Could not start ${command.command}: ${errorMessage(error)}`)));
+    child.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+  });
+
+/** The Worker row for a Task, or a refusal that says how to find one. */
+function rowOf(deps: ForemanControlDeps, taskId: number, verb: string): WorkerRow {
+  const row = deps.local.table.worker(taskId);
+  if (!row) {
+    throw new ForemanError(`No Worker on Task ${taskId} to ${verb}: the Process Table ${deps.local.table.path} has no row for it. Only a Task the Foreman has dispatched and not yet settled can be ${verb === "cancel" ? "cancelled" : `${verb}ed`}.`);
+  }
+  return row;
+}
+
+/** Appends the control event, through the outbox; a refusal is reported and does not undo the
+ * machine-side change the human asked for. */
+async function record(deps: ForemanControlDeps, initiativeId: number, action: ControlAction, message: string, taskId?: number): Promise<void> {
+  const tracker = new OutboxTracker(deps.tracker, deps.local.table, deps.out);
+  try {
+    await tracker.appendRunEvents(initiativeId, [controlEvent(action, message, taskId)]);
+  } catch (error) {
+    deps.out(`control: ${action} done on this machine, but the Run Record did not take the control event: ${errorMessage(error)}`);
+  }
+}
+
+/** Puts the mark on the row, or refuses when the row is gone: the turn ended on its own between
+ * the read and the mark, and its owner has recorded the attempt. */
+function mark(deps: ForemanControlDeps, row: WorkerRow, control: "attached" | "cancelled", verb: string): void {
+  if (!deps.local.table.setControl(row.taskId, control, (deps.now ?? Date.now)())) {
+    throw new ForemanError(`Task ${row.identifier}'s turn ended as the ${verb} ran: its attempt ${row.attempt} was recorded by the process that owned it, so there is nothing to ${verb}.`);
+  }
+}
+
+/** Stops the Worker and forgets its pid, which named nothing of the Worker's any more once the stop
+ * resolved (dead, or reused by the OS). A refused stop takes the mark back off and is rethrown:
+ * nothing changed on the machine. */
+async function stopAndForget(deps: ForemanControlDeps, row: WorkerRow): Promise<boolean> {
+  let stopped: boolean;
+  try {
+    stopped = await (deps.stopWorker ?? defaultStopWorker)(row);
+  } catch (error) {
+    deps.local.table.setControl(row.taskId, row.control, (deps.now ?? Date.now)());
+    throw error;
+  }
+  if (row.pid !== undefined) deps.local.table.clearPid(row.taskId);
+  if (row.appPid !== undefined) deps.local.table.setAppPid(row.taskId, undefined);
+  return stopped;
+}
+
+/** Nothing was stopped, so the mark may have landed on a turn that was ending on its own: the row
+ * must still be there and the Task must still wear `foreman:running`, else the attempt has been
+ * recorded and the mark is taken back off. */
+async function confirmStillOpen(deps: ForemanControlDeps, row: WorkerRow, verb: string): Promise<void> {
+  const ended = `Task ${row.identifier}'s turn ended as the ${verb} ran: its attempt ${row.attempt} was recorded by the process that owned it, so there is nothing to ${verb}.`;
+  if (!deps.local.table.worker(row.taskId)) throw new ForemanError(ended);
+  const { task } = await deps.tracker.getTask(row.taskId);
+  if (!task.labels.includes(STATUS_LABELS.running)) {
+    deps.local.table.setControl(row.taskId, row.control, (deps.now ?? Date.now)());
+    throw new ForemanError(ended);
+  }
+}
+
+/** `opsee foreman attach <taskId>` (story 53). */
+export async function runForemanAttach(deps: ForemanControlDeps, taskId: number): Promise<number> {
+  const { out } = deps;
+  const now = deps.now ?? Date.now;
+  const row = rowOf(deps, taskId, "attach");
+  const account = deps.store.load().find((a) => a.name === row.account);
+  if (!account) throw new AccountError(`Task ${row.identifier} runs under Account "${row.account}", which is no longer registered; register it again to attach.`);
+  if (row.control === "cancelled") throw new ForemanError(`Task ${row.identifier} was cancelled (opsee foreman cancel ${taskId}); its attempt is being closed, so there is nothing to attach to.`);
+  if (!row.sessionId) {
+    throw new ForemanError(`Task ${row.identifier} has no session id yet: the Worker has not said which session it is, so nothing can be resumed. Wait for its first line, or cancel it.`);
+  }
+  // The command first: an Account whose key is not set in this environment fails here, before any
+  // mark is made or anything is stopped.
+  const command = deps.adapterFor(account).interactiveCommand(row.sessionId, { account, cwd: row.workspace });
+
+  const alreadyAttached = row.control === "attached";
+  if (alreadyAttached) {
+    out(`attach: ${row.identifier} is already attached; opening the session again`);
+  } else {
+    mark(deps, row, "attached", "attach");
+    const stopped = await stopAndForget(deps, row);
+    if (!stopped) await confirmStillOpen(deps, row, "attach");
+    out(`attach: ${row.identifier} attempt ${row.attempt}: ${stopped ? `unattended turn stopped (pid ${row.pid})` : "no unattended turn was running"}; the attempt stays open`);
+    await record(deps, row.initiativeId, "attach", `attached to attempt ${row.attempt} in ${row.workspace}${stopped ? "; the unattended turn was stopped" : ""}`, taskId);
+  }
+
+  out(`attach: resuming session ${row.sessionId} as an attended turn: ${[command.command, ...command.args].join(" ")} in ${command.cwd} (Account "${account.name}")`);
+  let code: number;
+  try {
+    code = await (deps.runInteractive ?? runInteractiveCommand)(command);
+  } catch (error) {
+    if (alreadyAttached) throw error;
+    // The session never opened, so no attended turn happened: hand the Worker straight back and
+    // let the next tick resume it unattended, rather than leave it attached to nobody. The row
+    // goes to `released`, not blank: the owner of the stopped turn may not have read the mark yet,
+    // and either mark tells it to leave the attempt open, where a blank row would settle it as
+    // failed.
+    deps.local.table.setControl(taskId, "released", now());
+    const message = errorMessage(error);
+    out(`attach: could not open the session (${message}); ${row.identifier} is handed back, and the next Foreman tick resumes session ${row.sessionId} unattended in ${row.workspace}`);
+    await record(deps, row.initiativeId, "release", `attach could not open the session (${message}); handed back to the Foreman, which resumes attempt ${row.attempt} unattended`, taskId);
+    throw error;
+  }
+  out(`attach: attended turn on ${row.identifier} over (exit ${code}); the Worker stays attached to you: opsee foreman release ${taskId} hands it back, opsee foreman cancel ${taskId} stops it for good`);
+  return 0;
+}
+
+/** `opsee foreman release <taskId>` (story 54). */
+export async function runForemanRelease(deps: ForemanControlDeps, taskId: number): Promise<number> {
+  const now = deps.now ?? Date.now;
+  const row = rowOf(deps, taskId, "release");
+  if (row.control !== "attached") {
+    throw new ForemanError(`Task ${row.identifier} is not attached${row.control ? ` (it is ${row.control})` : ""}; only an attached Worker can be released.`);
+  }
+  deps.local.table.setControl(taskId, "released", now());
+  deps.out(`release: ${row.identifier} attempt ${row.attempt} handed back; the next Foreman tick resumes session ${row.sessionId ?? "(none)"} unattended in ${row.workspace}`);
+  await record(deps, row.initiativeId, "release", `released attempt ${row.attempt} after the attended turn; the next tick resumes it unattended`, taskId);
+  return 0;
+}
+
+/** `opsee foreman cancel <taskId>` (story 56). */
+export async function runForemanCancel(deps: ForemanControlDeps, taskId: number): Promise<number> {
+  const { out } = deps;
+  const row = rowOf(deps, taskId, "cancel");
+  if (row.control === "cancelled") {
+    out(`cancel: ${row.identifier} is already cancelled; its attempt is closed by the process that owns the turn, or by the next Foreman tick`);
+    return 0;
+  }
+  mark(deps, row, "cancelled", "cancel");
+  const closer = `the attempt is recorded as cancelled (outcome stopped) and the Task blocked by the process that owns the turn, or by the next Foreman tick (foreman up, or foreman run ${row.initiativeId})`;
+  if (row.control === "attached") {
+    // The unattended turn is long stopped and the session is the human's own interactive one, in
+    // their terminal, not a pid this command knows; it is theirs to leave.
+    out(`cancel: ${row.identifier} attempt ${row.attempt} is attached to you, so nothing was signalled: leave the interactive session yourself; ${closer}`);
+    await record(deps, row.initiativeId, "cancel", `cancelled attempt ${row.attempt} while attached; the attended session is the human's to leave`, taskId);
+    return 0;
+  }
+  const stopped = await stopAndForget(deps, row);
+  if (!stopped) await confirmStillOpen(deps, row, "cancel");
+  out(`cancel: ${row.identifier} attempt ${row.attempt}: ${stopped ? `Worker stopped (pid ${row.pid})` : "no Worker process was running"}; ${closer}`);
+  await record(deps, row.initiativeId, "cancel", `cancelled attempt ${row.attempt}${stopped ? "; the Worker was stopped" : "; no Worker process was running"}`, taskId);
+  return 0;
+}
+
+/** `opsee foreman pause <initiativeId>` (story 55). */
+export async function runForemanPause(deps: ForemanControlDeps, initiativeId: number): Promise<number> {
+  const now = deps.now ?? Date.now;
+  if (deps.local.table.isPaused(initiativeId)) {
+    deps.out(`pause: Initiative ${initiativeId} is already paused`);
+    return 0;
+  }
+  deps.local.table.pause(initiativeId, now());
+  // In flight: the Workers nobody has steered. An attached one is the human's, a released one waits
+  // for a tick, a cancelled one is being closed; none of them is work the pause lets finish.
+  const inFlight = deps.local.table.liveWorkers({ initiativeId }).filter((w) => w.control === undefined).length;
+  deps.out(`pause: Initiative ${initiativeId} paused; no new dispatch until foreman resume ${initiativeId}${inFlight ? `, ${inFlight} in-flight ${inFlight === 1 ? "Worker finishes" : "Workers finish"}` : ""}`);
+  await record(deps, initiativeId, "pause", `paused new dispatch${inFlight ? `; ${inFlight} in flight` : ""}`);
+  return 0;
+}
+
+/** `opsee foreman resume <initiativeId>` (story 55). */
+export async function runForemanResume(deps: ForemanControlDeps, initiativeId: number): Promise<number> {
+  if (!deps.local.table.resume(initiativeId)) {
+    deps.out(`resume: Initiative ${initiativeId} is not paused`);
+    return 0;
+  }
+  deps.out(`resume: Initiative ${initiativeId} resumed; dispatch continues on the next Foreman tick`);
+  await record(deps, initiativeId, "resume", "resumed new dispatch");
+  return 0;
+}

package/src/commands/foreman-debug.ts

@@ -0,0 +1,131 @@
+import { resolve } from "node:path";
+import type { DebugTurnArgs } from "../args.js";
+import { AccountError, type Account } from "../foreman/account.js";
+import type { AccountStore } from "../foreman/account-store.js";
+import { loadRunRecipe, startApp, waitForReady, type RunRecipe, type StartOptions, type AppHandle, type WaitOptions, type Readiness } from "../foreman/run-recipe.js";
+import type { TrackerAdapter } from "../foreman/tracker-adapter.js";
+import type { TurnRequest, WorkerAdapter } from "../foreman/worker-adapter.js";
+
+export interface ForemanDebugTurnDeps {
+  store: AccountStore;
+  /** The Worker Adapter for an Account's vendor (Claude Code or Codex). */
+  adapterFor: (account: Account, options: { raw: boolean }) => WorkerAdapter;
+  isDirectory: (path: string) => boolean;
+  out: (line: string) => void;
+}
+
+/** `opsee foreman debug turn`: one unattended turn (or a resumed one) under a registered Account,
+ * pinned to `--cwd`, with every adapter event printed and the Completion Report last. Exit code 0
+ * when the Worker reported, 1 otherwise. Nothing about the turn is written anywhere: this is the
+ * manual check of the Worker Adapter, not a Run. */
+export async function runForemanDebugTurn(deps: ForemanDebugTurnDeps, args: DebugTurnArgs): Promise<number> {
+  const account = deps.store.load().find((a) => a.name === args.account);
+  if (!account) throw new AccountError(`No Account named "${args.account}"`);
+  const cwd = resolve(args.cwd);
+  if (!deps.isDirectory(cwd)) throw new AccountError(`--cwd is not a directory: ${cwd}`);
+
+  const request: TurnRequest = { account, cwd, prompt: args.prompt, maxTurns: args.maxTurns, stallTimeoutMs: args.stallTimeoutMs };
+  const adapter = deps.adapterFor(account, { raw: args.raw });
+  const handle = args.resume ? adapter.resume(args.resume, request) : adapter.launch(request);
+  deps.out(`${args.resume ? "Resuming" : "Launching"} ${account.vendor} Worker on Account "${account.name}" in ${cwd}`);
+
+  for await (const event of handle.events) {
+    switch (event.type) {
+      case "started":
+        deps.out(`session ${event.sessionId}`);
+        break;
+      case "output":
+        for (const line of event.text.split("\n")) deps.out(`  | ${line}`);
+        break;
+      case "tool":
+        deps.out(`  tool ${event.name}`);
+        break;
+      case "rate_limited":
+        deps.out(`  rate limited: ${event.message}${event.resetAt ? ` (resets ${event.resetAt})` : ""}`);
+        break;
+      case "stalled":
+        deps.out(`  stalled: no output for ${event.silentMs}ms`);
+        break;
+      case "completed": {
+        const cost = event.costUsd === undefined ? "" : `, $${event.costUsd.toFixed(4)}`;
+        const turns = event.numTurns === undefined ? "" : `, ${event.numTurns} turns`;
+        deps.out(`Completion Report (${event.report.outcome}${turns}${cost}):`);
+        for (const line of JSON.stringify(event.report, null, 2).split("\n")) deps.out(line);
+        deps.out(`Resume with --resume ${event.sessionId}`);
+        return 0;
+      }
+      case "failed":
+        deps.out(`Turn failed (${event.reason}): ${event.message}`);
+        for (const detail of event.details ?? []) deps.out(`  ${detail}`);
+        if (event.sessionId) deps.out(`Resume with --resume ${event.sessionId}`);
+        return 1;
+    }
+  }
+  deps.out("Turn ended without a terminal event");
+  return 1;
+}
+
+export interface ForemanDebugServeDeps {
+  /** The repo whose Run Recipe is used: the cwd. */
+  root: string;
+  out: (line: string) => void;
+  /** Resolves when the user asks to stop (SIGINT in the real command). */
+  untilStop: Promise<void>;
+  /** How long to wait on the readiness URL; default 120s, a Vite or Go dev server cold start. */
+  timeoutMs?: number;
+  /** Test seams; the real recipe functions by default. */
+  load?: (root: string) => RunRecipe;
+  start?: (recipe: RunRecipe, options: StartOptions) => AppHandle;
+  wait?: (url: string, options: WaitOptions) => Promise<Readiness>;
+}
+
+/** `opsee foreman debug serve <port>`: what the Foreman does before a Verifier, by hand. Starts
+ * the app from the cwd's Run Recipe on `port`, reports when the readiness URL answers, and keeps
+ * the app up until Ctrl-C. Exit 1 when the recipe is missing or the app never becomes ready. */
+export async function runForemanDebugServe(deps: ForemanDebugServeDeps, port: number): Promise<number> {
+  const recipe = (deps.load ?? loadRunRecipe)(deps.root);
+  const timeoutMs = deps.timeoutMs ?? 120_000;
+  const app = (deps.start ?? startApp)(recipe, { port, cwd: deps.root, onOutput: (line) => deps.out(`  | ${line}`) });
+  deps.out(`starting: ${app.command}  (${recipe.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
+  deps.out(`waiting for ${app.readinessUrl} (up to ${timeoutMs}ms)`);
+  try {
+    const ready = await (deps.wait ?? waitForReady)(app.readinessUrl, { timeoutMs, signal: app.exitSignal });
+    deps.out(`ready: ${app.readinessUrl} answered after ${ready.elapsedMs}ms (${ready.attempts} attempts). Ctrl-C to stop.`);
+  } catch (error) {
+    deps.out(`not ready: ${error instanceof Error ? error.message : String(error)}`);
+    await app.stop();
+    return 1;
+  }
+  const outcome = await Promise.race([deps.untilStop.then(() => "stop" as const), app.exited.then((code) => ({ code }))]);
+  if (outcome === "stop") {
+    deps.out("stopping the app");
+    await app.stop();
+    return 0;
+  }
+  deps.out(`app exited with code ${outcome.code}`);
+  return outcome.code === 0 ? 0 : 1;
+}
+
+export interface ForemanDebugDeps {
+  tracker: Pick<TrackerAdapter, "listReadyTasks">;
+  out: (line: string) => void;
+}
+
+/** `opsee foreman debug ready <initiativeId>`: prints the Initiative's Ready Tasks exactly as the
+ * Foreman would dispatch them (server-derived first open slice, dispatch label applied). Read-only.
+ * Returns the process exit code. */
+export async function runForemanDebugReady(deps: ForemanDebugDeps, initiativeId: number): Promise<number> {
+  const ready = await deps.tracker.listReadyTasks(initiativeId);
+  if (!ready.dispatchLabelExists) {
+    deps.out(
+      `Initiative ${initiativeId}: the project has no "${ready.dispatchLabel}" label, so no Task can be ready.`,
+    );
+    return 1;
+  }
+  deps.out(`Initiative ${initiativeId}: ${ready.tasks.length} ready (label "${ready.dispatchLabel}")`);
+  for (const task of ready.tasks) {
+    const column = task.column ? ` [${task.column.name}]` : "";
+    deps.out(`  ${task.identifier}  ${task.title}${column}  (id ${task.id})`);
+  }
+  return 0;
+}

package/src/commands/foreman-plan.ts

@@ -0,0 +1,213 @@
+/**
+ * `opsee foreman plan <initiativeId>` (story 10): an attended planning session that starts already
+ * informed. The command picks the Account the way `foreman run` does, makes a Workspace on a
+ * planning branch of its own (`foreman/plan-<initiative>-<timestamp>`, from the default branch's
+ * remote head, through the guarded git like every other Workspace), checks the planning skill is
+ * in that worktree, assembles the Initiative's context (core/plan-context.ts: core idea, task
+ * tree, memory with the Completion Reports, pull requests) and opens the vendor's interactive
+ * session there, under the Account's environment, with that context and the instruction naming
+ * the skill as the first message. Then it waits for the human to leave and says where the
+ * worktree is.
+ *
+ * Attended only: nothing here launches or resumes a Worker turn, and the session is never resumed
+ * unattended. The Tasks the session files go through the MCP tools the skills already use; the
+ * prompt gives the Initiative id so they land there, with the four work-contract headings.
+ *
+ * Outside the guard (ADR-0003): the session's git is the human's own, with their credentials, in
+ * a worktree the guarded runner made but does not police; the prompt tells the session to commit
+ * to the planning branch and leave pushing, merging and pull requests to the human.
+ *
+ * The skills are the repository's own (`opsee init` writes them into `.claude/skills` and
+ * `.agents/skills`, OPS-261/OPS-264). This command never writes them: a worktree the human will
+ * commit from is theirs, and a skill written silently would show up as their change. A checkout
+ * without the skill is refused with the line that fixes it.
+ */
+import type { ChildProcess } from "node:child_process";
+import type { EventEmitter } from "node:events";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Account } from "../foreman/account.js";
+import type { AccountStore } from "../foreman/account-store.js";
+import { assemblePlanContext, DEFAULT_MEMORY_LIMIT, DEFAULT_PLANNING_SKILL, planBranch, WORK_CONTRACT_HEADINGS, type PlanningSkill } from "../foreman/core/plan-context.js";
+import { ForemanError, type RunDeps } from "../foreman/core/run.js";
+import { guardedGit, runGit, WorkspaceManager, type GitRunner } from "../foreman/core/workspace.js";
+import type { TrackerAdapter } from "../foreman/tracker-adapter.js";
+import type { Vendor } from "../foreman/vendor.js";
+import type { InteractiveCommand, WorkerAdapter } from "../foreman/worker-adapter.js";
+import { oneLine } from "../foreman/core/text.js";
+import { errorMessage } from "../foreman/worker-process.js";
+import { chooseAccount } from "./foreman.js";
+import { runInteractiveCommand } from "./foreman-control.js";
+
+/** Options of `opsee foreman plan`. */
+export interface ForemanPlanArgs {
+  initiativeId: number;
+  account?: string;
+  skill: PlanningSkill;
+  /** `--memory <n>`: the newest this many memory entries in the context; `DEFAULT_MEMORY_LIMIT` unless set. */
+  memory?: number;
+}
+
+export interface ForemanPlanDeps {
+  tracker: TrackerAdapter;
+  store: AccountStore;
+  adapterFor: (account: Account) => WorkerAdapter;
+  /** The repository the session plans in: the checkout the command runs in. */
+  repoRoot: () => Promise<string | undefined>;
+  out: (line: string) => void;
+  /** Test seams; the real Workspace manager over the guarded git, and a real spawn, by default. */
+  workspacesFor?: (repoRoot: string, log: (line: string) => void, git: GitRunner) => RunDeps["workspaces"];
+  runInteractive?: (command: InteractiveCommand) => Promise<number>;
+  /** Whether `dir` holds the skill for the vendor (`skillPath`); the file system by default. */
+  hasSkill?: (dir: string, vendor: Vendor, skill: PlanningSkill) => boolean;
+  now?: () => Date;
+  /** Above this many bytes the prompt goes to a file the first message points at. */
+  promptArgLimit?: number;
+  /** Where that file is made; the OS temp dir by default. */
+  tmpDir?: string;
+  /** Where the signal handlers that remove that file go; this process by default. */
+  signals?: EventEmitter;
+}
+
+/** Where each vendor looks for the repository's skills (`opsee init` writes both, init/paths.ts). */
+export const SKILL_DIR_BY_VENDOR: Readonly<Record<Vendor, string>> = {
+  claude: ".claude/skills",
+  codex: ".agents/skills",
+};
+
+/** `<dir>/.claude/skills/to-issues/SKILL.md`: the file that makes a skill available to a vendor. */
+export function skillPath(dir: string, vendor: Vendor, skill: PlanningSkill): string {
+  return join(dir, SKILL_DIR_BY_VENDOR[vendor], skill, "SKILL.md");
+}
+
+/**
+ * The most bytes the prompt is passed as one argument. Linux caps a single argument at 128 KiB
+ * (MAX_ARG_STRLEN), macOS the whole argument list at 1 MiB (ARG_MAX), and the vendor's own
+ * options sit beside it; a context past this goes to a file, and the first message points at it.
+ */
+export const PROMPT_ARG_LIMIT = 100_000;
+
+/**
+ * The first message when the context is in a file: short, the only thing on the command line, and
+ * enough on its own to satisfy the session's brief (the skill, the Initiative, the headings), since
+ * a file tool that stops at a line count would otherwise leave the model without them. The file
+ * has its Instructions first for the same reason; the pointer says how long it is and to read to
+ * the end.
+ */
+export function pointerPrompt(file: string, bytes: number, lines: number, skill: PlanningSkill, initiativeId: number): string {
+  const headings = WORK_CONTRACT_HEADINGS.map((h) => `## ${h}`).join(", ");
+  return [
+    `The planning context and your instructions for this session are in the file ${file}: ${bytes} bytes, ${lines} lines, the Instructions section first, then the Initiative's context. Read the whole file before doing anything else, to line ${lines}, in more than one read if your file tool returns only part of it (some stop at 2000 lines unless given an offset); then follow the Instructions.`,
+    `In short: run the /${skill} skill against Initiative ${initiativeId}; every Task filed from this session lands in Initiative ${initiativeId} through the Opsee MCP tools, with the work contract in its description as the four markdown headings ${headings}; propose before you publish.`,
+  ].join(" ");
+}
+
+/** The signals on which the context file is removed while the session runs. */
+export const CLEANUP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
+
+/**
+ * Removes `dir` when this process gets a signal while the session runs, since `finally` runs on
+ * none of them. SIGINT is the terminal's Ctrl-C, which the session gets from the terminal too:
+ * the directory goes and this process keeps waiting for the session to end. SIGTERM and SIGHUP
+ * (a `kill`, the terminal closing) remove it, go on to the session, and are then re-raised so
+ * this process dies of them as it would have. Returns the disposer that unregisters the handlers.
+ */
+export function cleanupOnSignal(
+  dir: string,
+  child: () => Pick<ChildProcess, "kill"> | undefined,
+  options: { target?: EventEmitter; raise?: (signal: NodeJS.Signals) => void } = {},
+): () => void {
+  const target = options.target ?? process;
+  const raise = options.raise ?? ((signal: NodeJS.Signals) => process.kill(process.pid, signal));
+  const listeners: [NodeJS.Signals, () => void][] = [];
+  const dispose = () => {
+    for (const [signal, listener] of listeners) target.removeListener(signal, listener);
+  };
+  for (const signal of CLEANUP_SIGNALS) {
+    const listener = () => {
+      rmSync(dir, { recursive: true, force: true });
+      if (signal === "SIGINT") return;
+      dispose();
+      child()?.kill(signal);
+      raise(signal);
+    };
+    listeners.push([signal, listener]);
+    target.on(signal, listener);
+  }
+  return dispose;
+}
+
+/** `opsee foreman plan <initiativeId>` (story 10). Exit 0 once the human leaves the session. */
+export async function runForemanPlan(deps: ForemanPlanDeps, args: ForemanPlanArgs): Promise<number> {
+  const { out } = deps;
+  const skill = args.skill ?? DEFAULT_PLANNING_SKILL;
+  const hasSkill = deps.hasSkill ?? ((dir, vendor, name) => existsSync(skillPath(dir, vendor, name)));
+  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 plan from the checkout the Initiative is about.");
+
+  // The checkout first, before any git or Tracker call: the Workspace is made from what is merged,
+  // so a skill missing here is missing there too, and the fix is the same.
+  if (!hasSkill(repoRoot, account.vendor, skill)) {
+    throw new ForemanError(
+      `The ${skill} skill is not in this repository at ${skillPath(repoRoot, account.vendor, skill)}, so a ${account.vendor} session could not run /${skill}. Run opsee init here, commit the skills it writes and merge them to the default branch (the Workspace is made from origin's), then run foreman plan again.`,
+    );
+  }
+
+  const context = await deps.tracker.getInitiativeContext(args.initiativeId);
+  const memoryLimit = args.memory ?? DEFAULT_MEMORY_LIMIT;
+  // The title is agent-writable and this is the terminal: one line of it.
+  out(`plan: Initiative ${context.initiative.id} "${oneLine(context.initiative.title)}" on Account "${account.name}" (${account.vendor}), skill /${skill}, memory ${memoryLimit}`);
+
+  const git = guardedGit(runGit, repoRoot);
+  const workspaces = (deps.workspacesFor ?? ((root, log, guarded) => new WorkspaceManager(root, { log, git: guarded })))(repoRoot, out, git);
+  const branch = planBranch(args.initiativeId, (deps.now ?? (() => new Date()))());
+  const workspace = await workspaces.create(branch);
+  // Both paths quoted: the line is meant to be pasted, and a workspaces root with a space in it is not rare.
+  const removal = `git -C "${repoRoot}" worktree remove "${workspace.path}" && git -C "${repoRoot}" branch -D ${workspace.branch}`;
+  out(`plan: Workspace ${workspace.path} on branch ${workspace.branch}${workspace.base ? ` from ${workspace.base}` : ""}`);
+  if (!hasSkill(workspace.path, account.vendor, skill)) {
+    throw new ForemanError(
+      `The ${skill} skill is in this checkout but not on the default branch's remote head, which the Workspace ${workspace.path} was made from (${skillPath(workspace.path, account.vendor, skill)} is missing). Merge the skills opsee init wrote, then run foreman plan again; to remove this Workspace: ${removal}`,
+    );
+  }
+
+  const assembled = assemblePlanContext({ context, skill, workspace, memoryLimit });
+  for (const line of assembled.summary) out(`context: ${line}`);
+
+  // The prompt as one argument when the OS allows it, else in a file of its own (never in the
+  // Workspace, whose contents are the human's) that the first message points at, laid out with
+  // the Instructions first.
+  let prompt = assembled.prompt;
+  let promptDir: string | undefined;
+  const promptBytes = Buffer.byteLength(prompt, "utf8");
+  if (promptBytes > (deps.promptArgLimit ?? PROMPT_ARG_LIMIT)) {
+    promptDir = mkdtempSync(join(deps.tmpDir ?? tmpdir(), "opsee-foreman-plan-"));
+    const file = join(promptDir, "planning-context.md");
+    const contents = assembled.fileContents;
+    const bytes = Buffer.byteLength(contents, "utf8");
+    const lines = contents.split("\n").length;
+    writeFileSync(file, contents, { mode: 0o600 });
+    out(`plan: the context is ${promptBytes} bytes, more than fits on the command line; written with the Instructions first to ${file} (${bytes} bytes, ${lines} lines), which the first message points at`);
+    prompt = pointerPrompt(file, bytes, lines, skill, args.initiativeId);
+  }
+
+  let code: number;
+  let child: ChildProcess | undefined;
+  const dispose = promptDir ? cleanupOnSignal(promptDir, () => child, { target: deps.signals }) : () => {};
+  try {
+    // Built before anything is said about opening: an Account whose key is not set fails here.
+    const command = deps.adapterFor(account).interactiveSession({ account, cwd: workspace.path, prompt });
+    out(`plan: opening ${command.command} in ${command.cwd} with the context as its first message (Account "${account.name}")`);
+    code = await (deps.runInteractive ?? ((c) => runInteractiveCommand(c, { onSpawn: (p) => (child = p) })))(command);
+  } catch (error) {
+    out(`plan: could not open the session (${errorMessage(error)}); the Workspace stays at ${workspace.path} on branch ${workspace.branch}. To remove it: ${removal}`);
+    throw error;
+  } finally {
+    dispose();
+    if (promptDir) rmSync(promptDir, { recursive: true, force: true });
+  }
+  out(`plan: session over (exit ${code}). The Workspace stays at ${workspace.path} on branch ${workspace.branch}; commit anything you want to keep from it, and remove it with: ${removal}`);
+  return 0;
+}