@opsee/cli 0.11.9

package/src/foreman/tracker-adapter.ts

@@ -0,0 +1,298 @@
+/**
+ * Tracker Adapter seam (see ../../CONTEXT.md).
+ *
+ * The piece that lets the Foreman read and write one kind of Tracker: list the Ready Issues of a
+ * Run, read one with its comments, post a Completion Report, keep its Status Label current, file a
+ * Defect, and append to the Run Record. The v1 implementation is Opsee over Connect-RPC
+ * (opsee-tracker-adapter.ts); the Foreman core only ever sees this interface.
+ *
+ * Readiness is the Tracker's to decide (ADR-0008): `listReadyTasks` returns what the server derives
+ * from the Initiative's slices and the dispatch label, never a client-side blocker walk.
+ */
+import type { Run, RunEvent, RunEventInput } from "@opsee/mcp-server/gen/api/v1/initiative_pb.js";
+
+/** The project label that makes a Task dispatchable; matched by name because every project defines
+ * its own labels (backend model.DispatchLabelName). Defined in the MCP package so that
+ * `opsee_file_defect` labels a Defect Task exactly as the Foreman does. */
+export { DISPATCH_LABEL } from "@opsee/mcp-server/src/utils/defect.js";
+
+/** A board column's lifecycle state. The canonical vocabulary is the first five; a project may
+ * carry others, and a column with no state at all counts as open. `in_review` is where a Task
+ * waits for a human after its Hand-off (ADR-0003); boards rarely name that state, so
+ * `pickColumn` resolves it by column name or the status editor's `active`. */
+export type Lifecycle = "backlog" | "todo" | "in_progress" | "in_review" | "done" | "archived" | (string & {});
+
+export interface TrackerColumn {
+  id: number;
+  name: string;
+  lifecycle?: string;
+}
+
+/** The column for a lifecycle state, from a board's active columns in display order: the one
+ * carrying that state, or for `in_review` (a state no board editor writes) the column whose name
+ * says review, else the board's only `active` column. Undefined when the board has none, so the
+ * adapter can name what it does have. */
+export function pickColumn<C extends TrackerColumn>(columns: C[], lifecycle: Lifecycle): C | undefined {
+  const exact = columns.find((c) => c.lifecycle === lifecycle);
+  if (exact || lifecycle !== "in_review") return exact;
+  // A review column must be an open one: a Done-state column named "Reviewed" would close the Task
+  // and release its successors before a human merged anything.
+  const open = columns.filter((c) => c.lifecycle !== "done" && c.lifecycle !== "archived");
+  const named = open.find((c) => /review/i.test(c.name));
+  if (named) return named;
+  const active = open.filter((c) => c.lifecycle === "active");
+  return active.length === 1 ? active[0] : undefined;
+}
+
+export interface TrackerTask {
+  id: number;
+  /** Human identifier, e.g. OPS-267. */
+  identifier: string;
+  title: string;
+  /** Markdown, whatever the Tracker stores: the work contract (core/work-contract.ts) reads its
+   * headings and the Worker's prompt carries it verbatim, so an adapter converts on the way in. */
+  description: string;
+  projectId: number;
+  initiativeId?: number;
+  parentTaskId?: number;
+  column?: TrackerColumn;
+  labels: string[];
+  type?: string;
+  priority?: string;
+  /** The priority as a number that rises with urgency (Opsee's `TaskPriority.level`; the seeded
+   * scale is Low 1, Medium 2, High 3, Critical 4). The scheduler's first sort key
+   * (core/scheduler.ts); unset when the Tracker reports no priority, which sorts below every
+   * named one. */
+  priorityLevel?: number;
+  /** When the Task was created: the scheduler's second sort key, oldest first. */
+  createdAt?: Date;
+  /** The Task's page in the web app, when the Tracker can build one; the Hand-off links to it. */
+  url?: string;
+}
+
+export interface TrackerComment {
+  id: number;
+  body: string;
+  authorUserId: number;
+  createdAt?: Date;
+}
+
+export type DependencyType = "blocks" | "blocked_by" | "duplicates" | "relates_to";
+
+export interface TrackerDependency {
+  id: number;
+  fromTaskId: number;
+  toTaskId: number;
+  type: DependencyType;
+}
+
+/** The Tasks that must be Done before `taskId`: `blocks` edges into it and `blocked_by` edges out of
+ * it, from a both-direction dependency list. */
+export function blockerIdsOf(taskId: number, dependencies: TrackerDependency[]): number[] {
+  const ids = dependencies
+    .filter((d) => (d.type === "blocks" && d.toTaskId === taskId) || (d.type === "blocked_by" && d.fromTaskId === taskId))
+    .map((d) => (d.type === "blocks" ? d.fromTaskId : d.toTaskId));
+  return [...new Set(ids)];
+}
+
+export interface TaskWithContext {
+  task: TrackerTask;
+  comments: TrackerComment[];
+  /** Both directions: edges where the task is `from` and edges where it is `to`. */
+  dependencies: TrackerDependency[];
+  parent?: TrackerTask;
+}
+
+export interface ReadyTasks {
+  tasks: TrackerTask[];
+  /** The label the server intersected with; `dispatchLabelExists` false means the project has no
+   * such label and nothing can ever be ready. */
+  dispatchLabel: string;
+  dispatchLabelExists: boolean;
+}
+
+export interface NewTask {
+  initiativeId: number;
+  title: string;
+  description: string;
+  labels?: string[];
+  /** Tasks this one relates to (a Defect names the Task it was found on). */
+  relatesTo?: number[];
+  /** Tasks that must be Done before this one is ready. */
+  blockedBy?: number[];
+  parentTaskId?: number;
+  /** Task type and priority by name; the project's first of each when omitted. */
+  type?: string;
+  priority?: string;
+}
+
+export interface ProjectRepository {
+  id: number;
+  fullName: string;
+  url: string;
+}
+
+export interface PullRequestLink {
+  projectRepositoryId: number;
+  number: number;
+  url: string;
+  title: string;
+  headBranch: string;
+  headSha: string;
+}
+
+export type MemoryKind = "decision" | "outcome" | "learning" | "blocker" | "context";
+
+export interface MemoryEntry {
+  kind: MemoryKind;
+  body: string;
+  /** The Task this entry is about; a Completion Report sets it. */
+  sourceTaskId?: number;
+  /** The Hand-off (draft PR) when there is one. */
+  sourceUrl?: string;
+}
+
+/** One memory entry as read back: what Context Assembly consumes. */
+/** Why the Tracker refused, for the refusals a caller acts on rather than only reports. A code and
+ * not the message text: the prose is English and free to change, so a caller that branches on it
+ * (the Defect filer retrying without its task type) reads the code instead. */
+export type TrackerErrorCode = "unknown_task_type" | "unknown_priority";
+
+/** A refusal the Tracker itself made (an unknown Initiative, a board without the column, a
+ * missing user), as opposed to a transport failure; thrown by every adapter alike. */
+export class TrackerError extends Error {
+  /** Set on the refusals a caller branches on; undefined on the rest. */
+  readonly code?: TrackerErrorCode;
+  constructor(message: string, code?: TrackerErrorCode) {
+    super(message);
+    this.name = "TrackerError";
+    this.code = code;
+  }
+}
+
+/** Whether a rejection is the Tracker saying the project defines no task type of that name, as
+ * opposed to anything else. The typed guard every adapter's refusal answers to, so no caller has to
+ * match on the wording of a message. */
+export function isUnknownTaskTypeError(error: unknown): boolean {
+  return error instanceof TrackerError && error.code === "unknown_task_type";
+}
+
+export interface MemoryRecord {
+  id: number;
+  kind: MemoryKind;
+  body: string;
+  sourceTaskId?: number;
+  sourceUrl?: string;
+  /** Agent-authored entries are re-injected as data, never as instructions (story 46). */
+  isAgent: boolean;
+  /** Written by the Tracker itself (a Task moved to Done, an edge changed): bookkeeping, not a
+   * Completion Report, so Context Assembly leaves it out. */
+  isSystem: boolean;
+  createdAt?: Date;
+}
+
+export interface MemoryQuery {
+  kinds?: MemoryKind[];
+  /** Only entries whose source is this Task. */
+  sourceTaskId?: number;
+}
+
+export interface RunRecordQuery {
+  /** Only events with an id greater than this: incremental reads. */
+  afterId?: number;
+  taskId?: number;
+  kinds?: string[];
+}
+
+export interface RunRecord {
+  /** Absent until the first event is appended. */
+  run?: Run;
+  events: RunEvent[];
+}
+
+/** One edge of an Initiative's task graph, as the server reports it. */
+export interface TrackerEdge {
+  fromTaskId: number;
+  toTaskId: number;
+  type: DependencyType;
+}
+
+/** One layer of the server's parallel execution batches: the Tasks that can run at once. */
+export interface TrackerSlice {
+  layer: number;
+  taskIds: number[];
+}
+
+/** A pull request rolled up across an Initiative's Tasks: a Hand-off, or one a person opened. */
+export interface TrackerPullRequest {
+  taskId: number;
+  number: number;
+  title: string;
+  url: string;
+  /** `open`, `merged`, `closed`... as the code host reports it. */
+  state: string;
+  /** `owner/repo`, when the link carries its repository. */
+  repository?: string;
+}
+
+/** What a planning session starts from (story 10): the Initiative with its core idea, its whole
+ * task tree with statuses and edges, the memory log newest first (the Completion Reports among
+ * it), and the pull requests linked to its Tasks. Mirrors the MCP's `opsee_get_initiative_context`
+ * (backend GetInitiativeContext), read through the Tracker Adapter so `foreman plan` sees the same
+ * Initiative a planning skill would. */
+export interface InitiativeContext {
+  initiative: {
+    id: number;
+    title: string;
+    summary?: string;
+    status: string;
+    /** Markdown, converted on the way in like a Task description. */
+    coreIdea: string;
+    projectId: number;
+  };
+  /** Every Task of the Initiative, with its column, whatever its state. */
+  tasks: TrackerTask[];
+  edges: TrackerEdge[];
+  slices: TrackerSlice[];
+  /** The whole memory log, newest first, system entries included (a reader filters). */
+  memory: MemoryRecord[];
+  pullRequests: TrackerPullRequest[];
+}
+
+export interface TrackerAdapter {
+  listReadyTasks(initiativeId: number): Promise<ReadyTasks>;
+  getTask(taskId: number): Promise<TaskWithContext>;
+  addComment(taskId: number, body: string): Promise<TrackerComment>;
+  /** The Initiative's own discussion thread, the counterpart of `addComment` (story 62). Where the
+   * Run's end summary goes: the per-Task comments say what happened to each Task, and this is the
+   * one place that says what happened to the night. */
+  addInitiativeComment(initiativeId: number, body: string): Promise<TrackerComment>;
+  /** Moves the Task to the board column carrying this lifecycle state; rejects when the board has
+   * none, naming the states it does have. */
+  moveTask(taskId: number, lifecycle: Lifecycle): Promise<TrackerColumn>;
+  /** Idempotent: attaching a label the Task already carries is a no-op. */
+  attachLabel(taskId: number, label: string): Promise<void>;
+  /** Idempotent: detaching a label the Task does not carry is a no-op. */
+  detachLabel(taskId: number, label: string): Promise<void>;
+  /** Makes sure the project has an active label of this name (a Status Label the Foreman keeps
+   * on the Tasks it touches); idempotent. */
+  ensureLabel(projectId: number, label: string): Promise<void>;
+  /** Creates the Task inside the Initiative with its labels and edges. Either the whole Task exists
+   * as asked, or the call rejects and nothing is left behind (an implementation that needs several
+   * writes undoes the create when a later write fails). */
+  createTask(input: NewTask): Promise<TrackerTask>;
+  /** The repositories connected to a project; `linkPullRequest` needs one of their ids. */
+  projectRepositories(projectId: number): Promise<ProjectRepository[]>;
+  linkPullRequest(taskId: number, pr: PullRequestLink): Promise<void>;
+  addMemory(initiativeId: number, entry: MemoryEntry): Promise<{ id: number }>;
+  /** The Initiative's memory log, newest first, filtered by kind and source Task. What Context
+   * Assembly reads: a blocker's Completion Report is its `outcome` entries with that Task as source. */
+  listMemory(initiativeId: number, query?: MemoryQuery): Promise<MemoryRecord[]>;
+  /** Appends in order, atomically: every event lands or none does. */
+  appendRunEvents(initiativeId: number, events: RunEventInput[]): Promise<RunEvent[]>;
+  /** The whole matching Run Record in id order, however long; `afterId` reads incrementally. */
+  readRunRecord(initiativeId: number, query?: RunRecordQuery): Promise<RunRecord>;
+  /** The Initiative as a planning session reads it (story 10): core idea, task tree, memory, pull
+   * requests. Rejects when there is no such Initiative. */
+  getInitiativeContext(initiativeId: number): Promise<InitiativeContext>;
+}

package/src/foreman/triage-draft.ts

@@ -0,0 +1,40 @@
+/**
+ * What a Triage turn (see ../../CONTEXT.md, spec story 23) produces: a drafted Verification section
+ * for a Task that has none.
+ *
+ * A Triage turn is an ordinary unattended turn, so the vendor constrains its final message to the
+ * Completion Report schema like any other; both adapters hard-wire that schema, and a second one
+ * would change the Worker Adapter's terminal event, which the seam does not allow. The draft
+ * therefore travels in the report's `summary` (the prompt in core/triage.ts asks for exactly that,
+ * outcome `done`, nothing else filled in), and this module is the projection from report to draft.
+ */
+import type { CompletionReport } from "./completion-report.js";
+
+export interface TriageDraft {
+  /** The Verification section body, markdown, without its heading. */
+  verification: string;
+}
+
+export type ParsedTriageDraft = { ok: true; draft: TriageDraft } | { ok: false; reason: string };
+
+/** A heading line naming Verification, at any level, with or without a colon. */
+const VERIFICATION_HEADING = /^ {0,3}#{1,6}\s+verification\s*:?\s*#*\s*$/i;
+
+function firstSentence(text: string): string {
+  const trimmed = text.trim().replace(/\s+/g, " ");
+  const end = trimmed.search(/[.!?](\s|$)/);
+  return end === -1 ? trimmed : trimmed.slice(0, end + 1);
+}
+
+/** The draft in a Triage turn's report: its summary, less a heading the Worker added anyway. A
+ * report that is not `done`, or says nothing, is no draft, with the Worker's own reason. */
+export function triageDraftFrom(report: CompletionReport): ParsedTriageDraft {
+  if (report.outcome !== "done") {
+    return { ok: false, reason: `the Worker reported ${report.outcome}: ${firstSentence(report.blockers[0] ?? report.summary)}` };
+  }
+  const lines = report.summary.trim().split("\n");
+  if (lines.length > 0 && VERIFICATION_HEADING.test(lines[0])) lines.shift();
+  const verification = lines.join("\n").trim();
+  if (!verification) return { ok: false, reason: "the Worker reported done with an empty summary" };
+  return { ok: true, draft: { verification } };
+}

package/src/foreman/vendor.ts

@@ -0,0 +1,23 @@
+/** The coding-agent products whose CLIs can be Workers in v1 (ADR-0001). */
+export const VENDORS = ["claude", "codex"] as const;
+export type Vendor = (typeof VENDORS)[number];
+
+/**
+ * The environment variable each vendor's CLI honours as its config directory. The Worker Adapter
+ * sets it to a subscription Account's `configDir` so a Worker runs under that login and no other
+ * (ADR-0013); the Foreman itself never reads what is inside the directory.
+ *
+ * - Claude Code: `CLAUDE_CONFIG_DIR`, default `~/.claude`.
+ * - Codex: `CODEX_HOME`, default `~/.codex`. It "sets the root for Codex state, including config,
+ *   auth, logs, sessions, skills", and "if you set it, the directory must already exist"
+ *   (https://learn.chatgpt.com/docs/config-file/environment-variables, where
+ *   developers.openai.com/codex redirects).
+ */
+export const VENDOR_CONFIG_DIR_ENV: Readonly<Record<Vendor, string>> = {
+  claude: "CLAUDE_CONFIG_DIR",
+  codex: "CODEX_HOME",
+};
+
+export function isVendor(value: string): value is Vendor {
+  return (VENDORS as readonly string[]).includes(value);
+}

package/src/foreman/verdict.ts

@@ -0,0 +1,120 @@
+/**
+ * The Verdict (see ../../CONTEXT.md: Verdict, Defect; spec story 39): the Verifier's structured
+ * result, passed or a list of Defects, each with the steps that led to it, what was expected, what
+ * was observed and a screenshot. It is the output contract of the Verifier's turn
+ * (worker-adapter.ts `OutputContract`), enforced the way the Completion Report is: one JSON schema
+ * handed to the vendor, one validator that judges what came back, and a turn that ends with
+ * anything else is `invalid_report`, which the Verifier records as a failed round, never a pass.
+ *
+ * Every key is required and no field is nullable, so the Codex strict projection is the schema
+ * itself and nothing needs folding; a passed Verdict has an empty `defects` list.
+ */
+import type { OutputContract } from "./worker-adapter.js";
+
+export interface Defect {
+  /** One line naming the failure; the Defect's title when it is filed as a Task (OPS-273). */
+  title: string;
+  /** What the Verifier did, step by step, to reach it. */
+  steps: string;
+  expected: string;
+  observed: string;
+  /** Path of the screenshot the Verifier took, relative to its screenshot directory (or absolute);
+   * empty when it could not take one, which the comment then says. */
+  screenshot: string;
+}
+
+export interface Verdict {
+  passed: boolean;
+  /** Empty when passed; at least one when not. */
+  defects: Defect[];
+  /** One paragraph: what was exercised and what was seen, for the human reading the pull request. */
+  summary: string;
+  /** Set only by the Foreman, on a Verdict it synthesized for a round that failed before the
+   * Verifier observed anything (`failureVerdict`, core/verifier.ts): its one stand-in Defect says
+   * the Foreman could not verify, which is not something a Worker can be asked to fix, so the
+   * Defect filer never files it. Structural on purpose (OPS-273 review): `parseVerdict` builds a
+   * Verdict field by field from the agent's JSON and never sets this, so a Verifier can neither
+   * make a real Defect look synthesized nor a synthesized one look real, whatever it titles them. */
+  roundFailed?: true;
+}
+
+export const VERDICT_JSON_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["passed", "defects", "summary"],
+  properties: {
+    passed: { type: "boolean" },
+    defects: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["title", "steps", "expected", "observed", "screenshot"],
+        properties: {
+          title: { type: "string" },
+          steps: { type: "string" },
+          expected: { type: "string" },
+          observed: { type: "string" },
+          screenshot: { type: "string" },
+        },
+      },
+    },
+    summary: { type: "string" },
+  },
+} as const;
+
+export type ParsedVerdict = { ok: true; verdict: Verdict } | { ok: false; errors: string[] };
+
+const DEFECT_FIELDS = ["title", "steps", "expected", "observed", "screenshot"] as const;
+
+/** Validates a candidate Verdict. A string is parsed as JSON first, as the Completion Report is.
+ * Every defect is reported, since the list goes into the failure a human reads; a Verdict whose
+ * `passed` and `defects` disagree is malformed, the rule the backend enforces on the event too. */
+export function parseVerdict(candidate: unknown): ParsedVerdict {
+  let value = candidate;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return { ok: false, errors: ["verdict is not JSON"] };
+    }
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return { ok: false, errors: ["verdict must be an object"] };
+  const record = value as Record<string, unknown>;
+  const errors: string[] = [];
+  if (typeof record.passed !== "boolean") errors.push("passed must be a boolean");
+  if (typeof record.summary !== "string") errors.push("summary must be a string");
+  const defects: Defect[] = [];
+  if (!Array.isArray(record.defects)) {
+    errors.push("defects must be an array");
+  } else {
+    record.defects.forEach((raw, i) => {
+      if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        errors.push(`defects[${i}] must be an object`);
+        return;
+      }
+      const d = raw as Record<string, unknown>;
+      const defect: Partial<Defect> = {};
+      for (const field of DEFECT_FIELDS) {
+        if (typeof d[field] !== "string") errors.push(`defects[${i}].${field} must be a string`);
+        else defect[field] = d[field] as string;
+      }
+      if (typeof d.title === "string" && d.title.trim() === "") errors.push(`defects[${i}].title must not be empty`);
+      defects.push(defect as Defect);
+    });
+  }
+  if (record.passed === true && defects.length > 0) errors.push("a passed verdict lists no defects");
+  if (record.passed === false && Array.isArray(record.defects) && defects.length === 0) errors.push("a failed verdict lists at least one defect");
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, verdict: { passed: record.passed as boolean, defects, summary: record.summary as string } };
+}
+
+/** The Verdict as an output contract: what the Verifier's turn runs under. */
+export const VERDICT_CONTRACT: OutputContract<Verdict> = {
+  name: "Verdict",
+  jsonSchema: VERDICT_JSON_SCHEMA as unknown as Record<string, unknown>,
+  parse(candidate) {
+    const parsed = parseVerdict(candidate);
+    return parsed.ok ? { ok: true, value: parsed.verdict } : parsed;
+  },
+};

package/src/foreman/worker-adapter.ts

@@ -0,0 +1,177 @@
+/**
+ * Worker Adapter seam (see ../../CONTEXT.md).
+ *
+ * The vendor-specific piece that knows how to launch, observe, resume, and stop a Worker for one
+ * coding-agent product. The Foreman only speaks to Worker Adapters, never to a vendor directly, so
+ * nothing here names a vendor: the Account carries that, and the adapter implementation is chosen
+ * per Account vendor. Tests substitute `FakeWorkerAdapter`, which replays scripted event streams;
+ * the real adapters are contract-tested against recorded stream fixtures with the process seam
+ * replaced by a replayer (spec, "Testing Decisions").
+ */
+import type { Account } from "./account.js";
+import type { CompletionReport } from "./completion-report.js";
+
+/** One unattended turn of a Worker. The Foreman pins the working directory to the Workspace and
+ * says which Account the Worker runs under; the adapter turns that into a vendor launch. */
+export interface TurnRequest {
+  account: Account;
+  /** Absolute path the Worker runs in. Always a Workspace once the Foreman core lands. */
+  cwd: string;
+  prompt: string;
+  /** Cap on agentic turns within this Worker turn, where the vendor supports one (story 33). */
+  maxTurns?: number;
+  /** Silence longer than this ends the turn as `stalled` (story 33). Unset means no stall timer. */
+  stallTimeoutMs?: number;
+  /** Extra environment for the Worker process, applied after the adapter's own variables. Never a
+   * credential: the Account decides identity and the adapter sets that itself. */
+  env?: Readonly<Record<string, string>>;
+  /** What the turn must end with. The Completion Report (`COMPLETION_REPORT_CONTRACT`) when unset,
+   * which is every implementing turn; the Verifier's turn (core/verifier.ts) hands in the Verdict
+   * contract instead. The adapter gives the vendor the contract's JSON schema and validates what
+   * comes back with its parser, so a turn that ends with anything else is `invalid_report`
+   * whichever contract it ran under. */
+  contract?: OutputContract;
+  /** MCP servers the turn may use on top of the vendor's own configuration: the Verifier's
+   * Playwright MCP. Each adapter renders them the way its vendor takes them and allows their tools;
+   * a turn without any runs with the vendor's defaults. */
+  mcpServers?: Readonly<Record<string, McpServerSpec>>;
+  /** What the Worker may touch. `worker` (the default) is an implementing turn: it edits its
+   * Workspace and runs commands there. `readonly-browser` is the Verifier's turn
+   * (core/verifier.ts): the vendor's built-in tools are removed or its sandbox made read-only,
+   * nothing may be written or run, the MCP servers named here are the only tools, and the
+   * process environment loses the Foreman's own credentials as well as the vendors' identities
+   * (worker-process.ts `VERIFIER_STRIPPED_ENV`). A property of the request, not of the contract,
+   * so the adapters need not know which contract is which. */
+  sandbox?: TurnSandbox;
+}
+
+export type TurnSandbox = "worker" | "readonly-browser";
+
+/** One stdio MCP server, as both vendors describe it: a command, its arguments, extra environment. */
+export interface McpServerSpec {
+  command: string;
+  args: string[];
+  env?: Readonly<Record<string, string>>;
+}
+
+/** What a turn must hand back as its final, structured message: a JSON schema for the vendor's
+ * structured-output flag and the validator that judges what came back. One object per contract
+ * (the Completion Report, the Verdict), so the schema and its parser cannot drift apart. */
+export interface OutputContract<T = unknown> {
+  /** What the failure event calls it: "Completion Report", "Verdict". */
+  name: string;
+  jsonSchema: Record<string, unknown>;
+  parse(candidate: unknown): { ok: true; value: T } | { ok: false; errors: string[] };
+}
+
+/** Why a turn ended without a Completion Report. */
+export type TurnFailureReason =
+  /** The process could not be started at all: binary missing, key variable unset, bad cwd. */
+  | "launch_failed"
+  /** The Worker finished but its final message was not valid under the turn's contract (a
+   * Completion Report, or the Verifier's Verdict). */
+  | "invalid_report"
+  /** The vendor stopped the Worker at its turn cap before it reported. */
+  | "max_turns"
+  /** The vendor refused or cut the turn on a rate limit; a `rate_limited` event preceded this. */
+  | "rate_limited"
+  /**
+   * The Account's credential is dead rather than busy: a login the vendor no longer accepts, a
+   * revoked or expired token, an API-key variable that is not set (story 33, OPS-288). Distinct
+   * from `rate_limited`, which is the same identity being told "not yet", and from `launch_failed`,
+   * which is a machine that could not start the binary at all — a dead credential is the one
+   * failure that no amount of retrying on this Account can fix, so it is what quarantines it.
+   *
+   * The adapters are deliberately stingy with it. A false positive takes a working Account out of
+   * rotation until a human re-adds it, which on an overnight run costs the whole Lane, so it is
+   * raised only for a locally-decided fact (`CredentialError`) or a narrow match against the
+   * vendor's own documented auth text, and never where a rate limit would also match.
+   */
+  | "credential_failed"
+  /** No output for `stallTimeoutMs`; the adapter stopped the Worker. A `stalled` event preceded this. */
+  | "stalled"
+  /** `stop()` was called before the Worker reported. */
+  | "stopped"
+  /** The vendor reported an error of its own, or the process exited without a result. */
+  | "vendor_error";
+
+export type AdapterEvent =
+  /** The Worker is running. `sessionId` is what `resume` needs for the next turn. */
+  | { type: "started"; sessionId: string }
+  /** Assistant text as it arrives. Progress for the Dashboard; never parsed for meaning. */
+  | { type: "output"; text: string }
+  /** The Worker invoked a tool; progress for the Dashboard. */
+  | { type: "tool"; name: string }
+  /** The vendor reported a rate limit. `resetAt` is ISO 8601 when the vendor said when it lifts;
+   * the scheduler marks the Account Paused until then (or a default when unknown). */
+  | { type: "rate_limited"; resetAt?: string; message: string }
+  /** No output for `stallTimeoutMs`. Always followed by `failed` with reason `stalled`. */
+  | { type: "stalled"; silentMs: number }
+  /** Terminal: the Worker ended with a valid final message under its contract. `report` is the
+   * Completion Report of an implementing turn; a turn run under another contract (the Verifier's
+   * Verdict) carries the validated object in `structured` and a stand-in report that says so
+   * (`contractReport`), so every reader of the stream sees the same shape. */
+  | { type: "completed"; sessionId: string; report: CompletionReport; structured?: unknown; costUsd?: number; numTurns?: number }
+  /** Terminal: the turn ended without a valid final message. `details` carries the validation
+   * errors for `invalid_report` and the vendor's text otherwise. */
+  | { type: "failed"; reason: TurnFailureReason; message: string; sessionId?: string; details?: string[] };
+
+/** One launched turn. Iterate `events` to completion; exactly one terminal event is yielded and the
+ * iterator then ends. `stop()` may be called at any time and is idempotent. */
+export interface TurnHandle {
+  events: AsyncIterable<AdapterEvent>;
+  stop(): Promise<void>;
+  /** The Worker's OS pid once it is running, for the Process Table (ADR-0009); unset for an
+   * adapter that has no process (the fake) or before the launch. */
+  readonly pid?: number;
+}
+
+/** What `foreman attach` runs in the human's terminal: the vendor's own interactive resume of a
+ * session, in the Workspace, under the Account's identity. The adapter builds it, the command
+ * spawns it with the terminal inherited; the Foreman never drives the attended turn itself. */
+export interface InteractiveCommand {
+  command: string;
+  args: string[];
+  cwd: string;
+  /** The Worker's environment, built from the Account alone the way an unattended turn's is. */
+  env: Record<string, string>;
+}
+
+/** What `foreman plan` opens: a fresh interactive session of the vendor, in a Workspace, under the
+ * Account, whose first message is `prompt`. No session id: nothing is resumed. The command keeps
+ * `prompt` under the OS argument limit itself (a long context goes to a file the prompt points at). */
+export interface InteractiveSessionRequest extends Pick<TurnRequest, "account" | "cwd"> {
+  prompt: string;
+}
+
+export interface WorkerAdapter {
+  /** Starts a new Worker session for one unattended turn. */
+  launch(request: TurnRequest): TurnHandle;
+  /** Runs a further turn in an existing session, so the Worker sees its earlier context. */
+  resume(sessionId: string, request: TurnRequest): TurnHandle;
+  /** The attended turn (story 53): how to resume `sessionId` interactively in `cwd` under the
+   * Account. Turn mode is a property of the turn, not the Worker: this is the same session the
+   * unattended turns use, so what the human says and does there is what the next unattended turn
+   * sees. */
+  interactiveCommand(sessionId: string, request: Pick<TurnRequest, "account" | "cwd">): InteractiveCommand;
+  /** An attended session from scratch (story 10, `foreman plan`): the vendor's interactive form
+   * opened on `prompt` as its first message, in `cwd`, under the Account's environment. The
+   * Foreman never drives it and it is never resumed unattended. */
+  interactiveSession(request: InteractiveSessionRequest): InteractiveCommand;
+}
+
+/** Drains a handle and returns its terminal event, collecting the rest, for callers that want the
+ * outcome rather than the live stream (the contract suite and most Foreman tests; the debug command
+ * streams so a human sees progress). */
+export async function collectTurn(handle: TurnHandle): Promise<{
+  events: AdapterEvent[];
+  terminal: Extract<AdapterEvent, { type: "completed" | "failed" }>;
+}> {
+  const events: AdapterEvent[] = [];
+  for await (const event of handle.events) events.push(event);
+  const terminal = events[events.length - 1];
+  if (!terminal || (terminal.type !== "completed" && terminal.type !== "failed")) {
+    throw new Error("Worker Adapter contract violated: the event stream ended without a terminal event");
+  }
+  return { events, terminal };
+}