@opsee/cli 0.11.9

package/src/foreman/fake-tracker-adapter.ts

@@ -0,0 +1,355 @@
+import { create } from "@bufbuild/protobuf";
+import { RunEventSchema, RunSchema, type RunEvent, type RunEventInput } from "@opsee/mcp-server/gen/api/v1/initiative_pb.js";
+import {
+  blockerIdsOf,
+  DISPATCH_LABEL,
+  pickColumn,
+  TrackerError,
+  type InitiativeContext,
+  type Lifecycle,
+  type MemoryEntry,
+  type MemoryQuery,
+  type MemoryRecord,
+  type NewTask,
+  type ProjectRepository,
+  type PullRequestLink,
+  type ReadyTasks,
+  type RunRecord,
+  type RunRecordQuery,
+  type TaskWithContext,
+  type TrackerAdapter,
+  type TrackerColumn,
+  type TrackerComment,
+  type TrackerDependency,
+  type TrackerSlice,
+  type TrackerTask,
+} from "./tracker-adapter.js";
+
+/**
+ * An in-memory Tracker for the Foreman core's tests: one project with one connected repository,
+ * one board with the five canonical columns plus an In Review column shaped like the live board's
+ * (lifecycle `active`, the status editor's default), Tasks with labels and edges, a memory log and
+ * a Run Record. Readiness follows the server's rule closely enough for the loop's decisions (open
+ * Task, dispatch label, every blocker Done, where In Review is still open); the real rule is
+ * exercised against the real backend in the integration tier.
+ */
+export const FAKE_COLUMNS: TrackerColumn[] = [
+  { id: 1, name: "Backlog", lifecycle: "backlog" },
+  { id: 2, name: "To Do", lifecycle: "todo" },
+  { id: 3, name: "In Progress", lifecycle: "in_progress" },
+  { id: 6, name: "In Review", lifecycle: "active" },
+  { id: 4, name: "Done", lifecycle: "done" },
+  { id: 5, name: "Archived", lifecycle: "archived" },
+];
+
+export const FAKE_REPOSITORY: ProjectRepository = { id: 1, fullName: "opsee/monorepo", url: "https://gitlab.example/opsee/monorepo" };
+
+/** The description a fake Task gets when the test gives none: a complete work contract, so a test
+ * about the loop is not also a test about the contract check (work-contract.ts). */
+export const FAKE_CONTRACT = "## Goal\n\nDo the thing.\n\n## Acceptance Criteria\n\n- [ ] The thing is done\n\n## Verification\n\nRun the tests.";
+
+/** An Initiative the fake knows by id; a Task's `initiativeId` may name one not registered here,
+ * in which case `getInitiativeContext` rejects the way the server does for an unknown id. */
+export interface FakeInitiativeInput {
+  id: number;
+  title: string;
+  summary?: string;
+  status?: string;
+  /** Markdown; the fake stores it as the adapter would hand it out, already converted. */
+  coreIdea?: string;
+}
+
+export interface FakeTaskInput {
+  id: number;
+  identifier?: string;
+  title: string;
+  /** Defaults to `FAKE_CONTRACT`; pass "" for a Task with no description at all. */
+  description?: string;
+  initiativeId?: number;
+  parentTaskId?: number;
+  labels?: string[];
+  lifecycle?: Lifecycle;
+  blockedBy?: number[];
+  /** Tasks this one relates to; `createTask` wires a `relates_to` edge per entry, as the adapter's
+   * RELATES_TO dependency does. */
+  relatesTo?: number[];
+  /** The project's task type by name (the fake defines no types of its own, so any name is taken
+   * as given); what the Defect filer sets to `Bug`. */
+  type?: string;
+  /** The scheduler's sort keys (core/scheduler.ts). `priorityLevel` rises with urgency the way
+   * Opsee's `TaskPriority.level` does; `createdAt` is when the Task was made. Both unset by
+   * default, which leaves the order the ids' — what a test that is not about ordering wants. */
+  priorityLevel?: number;
+  createdAt?: Date;
+}
+
+export class FakeTrackerAdapter implements TrackerAdapter {
+  readonly projectId: number;
+  readonly tasks = new Map<number, TrackerTask>();
+  readonly dependencies: TrackerDependency[] = [];
+  readonly comments = new Map<number, TrackerComment[]>();
+  /** By Initiative id, kept apart from the Task comments above: the two are different threads and a
+   * test that asserts one must not be able to see the other. */
+  readonly initiativeComments = new Map<number, TrackerComment[]>();
+  readonly memory: (MemoryRecord & { initiativeId: number })[] = [];
+  readonly events: RunEvent[] = [];
+  readonly labels = new Set<string>([DISPATCH_LABEL]);
+  readonly repositories: ProjectRepository[];
+  readonly pullRequests = new Map<number, PullRequestLink[]>();
+  readonly initiatives = new Map<number, Required<FakeInitiativeInput>>();
+  /** The project's task types by name, first being its default. Undefined means the fake takes any
+   * name, which is what a test not about task types wants. */
+  readonly taskTypes?: string[];
+  /** Every write, in order, so a test can assert the sequence the loop performed. */
+  readonly log: string[] = [];
+  private nextId = 1000;
+
+  constructor(options: { projectId?: number; tasks?: FakeTaskInput[]; repositories?: ProjectRepository[]; initiatives?: FakeInitiativeInput[]; taskTypes?: string[] } = {}) {
+    this.projectId = options.projectId ?? 3;
+    this.taskTypes = options.taskTypes;
+    this.repositories = options.repositories ?? [FAKE_REPOSITORY];
+    for (const i of options.initiatives ?? []) this.addInitiative(i);
+    for (const t of options.tasks ?? []) this.addTask(t);
+  }
+
+  addInitiative(input: FakeInitiativeInput): void {
+    this.initiatives.set(input.id, { summary: "", status: "active", coreIdea: "", ...input });
+  }
+
+  addTask(input: FakeTaskInput): TrackerTask {
+    const column = FAKE_COLUMNS.find((c) => c.lifecycle === (input.lifecycle ?? "todo"))!;
+    const task: TrackerTask = {
+      id: input.id,
+      identifier: input.identifier ?? `OPS-${input.id}`,
+      title: input.title,
+      description: input.description ?? FAKE_CONTRACT,
+      projectId: this.projectId,
+      initiativeId: input.initiativeId,
+      parentTaskId: input.parentTaskId,
+      column,
+      labels: [...(input.labels ?? [])],
+      type: input.type,
+      priorityLevel: input.priorityLevel,
+      createdAt: input.createdAt,
+    };
+    this.tasks.set(task.id, task);
+    for (const blocker of input.blockedBy ?? []) {
+      this.dependencies.push({ id: this.nextId++, fromTaskId: blocker, toTaskId: task.id, type: "blocks" });
+    }
+    for (const other of input.relatesTo ?? []) {
+      this.dependencies.push({ id: this.nextId++, fromTaskId: task.id, toTaskId: other, type: "relates_to" });
+    }
+    return task;
+  }
+
+  private task(id: number): TrackerTask {
+    const task = this.tasks.get(id);
+    if (!task) throw new Error(`Task ${id} not found`);
+    return task;
+  }
+
+  private blockersOf(taskId: number): number[] {
+    return blockerIdsOf(taskId, this.dependencies);
+  }
+
+  async listReadyTasks(initiativeId: number): Promise<ReadyTasks> {
+    const isDone = (t: TrackerTask) => t.column?.lifecycle === "done" || t.column?.lifecycle === "archived";
+    const tasks = [...this.tasks.values()].filter(
+      (t) =>
+        t.initiativeId === initiativeId &&
+        !isDone(t) &&
+        t.labels.includes(DISPATCH_LABEL) &&
+        // An edge to a Task the Tracker no longer has does not gate readiness, as on the server.
+        this.blockersOf(t.id).every((b) => !this.tasks.has(b) || isDone(this.tasks.get(b)!)),
+    );
+    return { tasks: tasks.map((t) => ({ ...t, labels: [...t.labels] })), dispatchLabel: DISPATCH_LABEL, dispatchLabelExists: true };
+  }
+
+  async getTask(taskId: number): Promise<TaskWithContext> {
+    const task = this.task(taskId);
+    return {
+      task: { ...task, labels: [...task.labels] },
+      comments: [...(this.comments.get(taskId) ?? [])],
+      dependencies: this.dependencies.filter((d) => d.fromTaskId === taskId || d.toTaskId === taskId),
+      parent: task.parentTaskId ? { ...this.task(task.parentTaskId) } : undefined,
+    };
+  }
+
+  async addComment(taskId: number, body: string): Promise<TrackerComment> {
+    this.task(taskId);
+    const comment: TrackerComment = { id: this.nextId++, body, authorUserId: 1, createdAt: new Date() };
+    this.comments.set(taskId, [...(this.comments.get(taskId) ?? []), comment]);
+    this.log.push(`comment ${taskId}: ${body}`);
+    return comment;
+  }
+
+  async addInitiativeComment(initiativeId: number, body: string): Promise<TrackerComment> {
+    const comment: TrackerComment = { id: this.nextId++, body, authorUserId: 1, createdAt: new Date() };
+    this.initiativeComments.set(initiativeId, [...(this.initiativeComments.get(initiativeId) ?? []), comment]);
+    // The id alone: unlike a Task comment, the body here is a multi-line report, and a test that
+    // asserts the interaction log wants to see *that* a summary was posted. What it says is
+    // asserted through `initiativeComments`.
+    this.log.push(`initiative comment ${initiativeId}`);
+    return comment;
+  }
+
+  async moveTask(taskId: number, lifecycle: Lifecycle): Promise<TrackerColumn> {
+    const column = pickColumn(FAKE_COLUMNS, lifecycle);
+    if (!column) throw new Error(`Board has no column with lifecycle "${lifecycle}"`);
+    this.task(taskId).column = column;
+    this.log.push(`move ${taskId} -> ${lifecycle}`);
+    return column;
+  }
+
+  async attachLabel(taskId: number, label: string): Promise<void> {
+    if (!this.labels.has(label)) throw new Error(`Project ${this.projectId} has no active label "${label}"`);
+    const task = this.task(taskId);
+    if (task.labels.includes(label)) return;
+    task.labels.push(label);
+    this.log.push(`label ${taskId} +${label}`);
+  }
+
+  async detachLabel(taskId: number, label: string): Promise<void> {
+    const task = this.task(taskId);
+    if (!task.labels.includes(label)) return;
+    task.labels = task.labels.filter((l) => l !== label);
+    this.log.push(`label ${taskId} -${label}`);
+  }
+
+  async ensureLabel(_projectId: number, label: string): Promise<void> {
+    if (this.labels.has(label)) return;
+    this.labels.add(label);
+    this.log.push(`create label ${label}`);
+  }
+
+  async createTask(input: NewTask): Promise<TrackerTask> {
+    // The real adapter resolves a label and a task type by name and refuses a name the project
+    // does not define (`labelByName`, `pickNamed`); a caller that forgot `ensureLabel`, or asked
+    // for a type this project has not got, must fail here too.
+    for (const label of input.labels ?? []) {
+      if (!this.labels.has(label)) throw new TrackerError(`Project ${this.projectId} has no active label "${label}"`);
+    }
+    if (input.type !== undefined && this.taskTypes && !this.taskTypes.includes(input.type)) {
+      throw new TrackerError(`No task type named "${input.type}" (have: ${this.taskTypes.join(", ")})`, "unknown_task_type");
+    }
+    const created = this.addTask({
+      id: this.nextId++,
+      title: input.title,
+      description: input.description,
+      initiativeId: input.initiativeId,
+      parentTaskId: input.parentTaskId,
+      labels: input.labels,
+      blockedBy: input.blockedBy,
+      relatesTo: input.relatesTo,
+      type: input.type ?? this.taskTypes?.[0],
+    });
+    this.log.push(`create task ${created.identifier}: ${created.title}`);
+    return created;
+  }
+
+  async projectRepositories(): Promise<ProjectRepository[]> {
+    return [...this.repositories];
+  }
+
+  async linkPullRequest(taskId: number, pr: PullRequestLink): Promise<void> {
+    this.task(taskId);
+    if (!this.repositories.some((r) => r.id === pr.projectRepositoryId)) throw new Error(`Project ${this.projectId} has no repository ${pr.projectRepositoryId}`);
+    // The backend upserts on (task, repository, number): a re-link replaces the row.
+    const links = (this.pullRequests.get(taskId) ?? []).filter((l) => !(l.projectRepositoryId === pr.projectRepositoryId && l.number === pr.number));
+    this.pullRequests.set(taskId, [...links, { ...pr }]);
+    this.log.push(`link pr ${taskId}: ${pr.url}`);
+  }
+
+  async addMemory(initiativeId: number, entry: MemoryEntry): Promise<{ id: number }> {
+    const record = { id: this.nextId++, initiativeId, ...entry, isAgent: true, isSystem: false, createdAt: new Date() };
+    this.memory.push(record);
+    this.log.push(`memory ${initiativeId} ${entry.kind}${entry.sourceTaskId ? ` (task ${entry.sourceTaskId})` : ""}`);
+    return { id: record.id };
+  }
+
+  async listMemory(initiativeId: number, query: MemoryQuery = {}): Promise<MemoryRecord[]> {
+    return this.memory
+      .filter(
+        (m) =>
+          m.initiativeId === initiativeId &&
+          (!query.kinds || query.kinds.includes(m.kind)) &&
+          (query.sourceTaskId === undefined || m.sourceTaskId === query.sourceTaskId),
+      )
+      .sort((a, b) => b.id - a.id)
+      .map(({ initiativeId: _drop, ...rest }) => rest);
+  }
+
+  async appendRunEvents(initiativeId: number, inputs: RunEventInput[]): Promise<RunEvent[]> {
+    const appended = inputs.map((input) =>
+      create(RunEventSchema, {
+        id: this.nextId++,
+        runId: initiativeId,
+        initiativeId,
+        kind: input.payload?.payload.case ?? "",
+        taskId: input.taskId,
+        payload: input.payload,
+        isAgent: true,
+      }),
+    );
+    this.events.push(...appended);
+    for (const e of appended) this.log.push(`event ${e.kind}${e.taskId ? ` (task ${e.taskId})` : ""}`);
+    return appended;
+  }
+
+  /** The Initiative's Tasks, edges among them, and slices layered the way the server does: every
+   * Task, Done ones included, at one past its deepest blocker's layer (the server lays out the
+   * whole graph; readiness, not the slice, is what excludes a Done Task). */
+  async getInitiativeContext(initiativeId: number): Promise<InitiativeContext> {
+    const ini = this.initiatives.get(initiativeId);
+    if (!ini) throw new TrackerError(`Initiative ${initiativeId} not found`);
+    const tasks = [...this.tasks.values()].filter((t) => t.initiativeId === initiativeId).map((t) => ({ ...t, labels: [...t.labels] }));
+    const ids = new Set(tasks.map((t) => t.id));
+    const edges = this.dependencies.filter((d) => ids.has(d.fromTaskId) && ids.has(d.toTaskId)).map(({ fromTaskId, toTaskId, type }) => ({ fromTaskId, toTaskId, type }));
+    const layerOf = new Map<number, number>();
+    const layer = (id: number, seen: Set<number>): number => {
+      const known = layerOf.get(id);
+      if (known !== undefined) return known;
+      if (seen.has(id)) return 0;
+      seen.add(id);
+      const blockers = blockerIdsOf(id, this.dependencies).filter((b) => ids.has(b));
+      const value = blockers.length === 0 ? 0 : 1 + Math.max(...blockers.map((b) => layer(b, seen)));
+      layerOf.set(id, value);
+      return value;
+    };
+    for (const t of tasks) layer(t.id, new Set());
+    const slices: TrackerSlice[] = [];
+    for (const t of tasks) {
+      const l = layerOf.get(t.id) ?? 0;
+      let slice = slices.find((s) => s.layer === l);
+      if (!slice) slices.push((slice = { layer: l, taskIds: [] }));
+      slice.taskIds.push(t.id);
+    }
+    slices.sort((a, b) => a.layer - b.layer);
+    const pullRequests = [...this.pullRequests.entries()].flatMap(([taskId, links]) =>
+      ids.has(taskId) ? links.map((l) => ({ taskId, number: l.number, title: l.title, url: l.url, state: "open", repository: this.repositories.find((r) => r.id === l.projectRepositoryId)?.fullName })) : [],
+    );
+    return {
+      initiative: { id: ini.id, title: ini.title, summary: ini.summary || undefined, status: ini.status, coreIdea: ini.coreIdea, projectId: this.projectId },
+      tasks,
+      edges,
+      slices,
+      memory: await this.listMemory(initiativeId),
+      pullRequests,
+    };
+  }
+
+  async readRunRecord(initiativeId: number, query: RunRecordQuery = {}): Promise<RunRecord> {
+    const events = this.events.filter(
+      (e) =>
+        e.initiativeId === initiativeId &&
+        (query.afterId === undefined || e.id > query.afterId) &&
+        (query.taskId === undefined || e.taskId === query.taskId) &&
+        (!query.kinds || query.kinds.includes(e.kind)),
+    );
+    // A Run is created lazily by the first appended event and its status mirrors the Initiative's
+    // (initiative.proto), so the fake reports one exactly when the Record has something in it.
+    const all = this.events.filter((e) => e.initiativeId === initiativeId);
+    const run = all.length === 0 ? undefined : create(RunSchema, { id: initiativeId, initiativeId, status: this.initiatives.get(initiativeId)?.status ?? "active", eventCount: BigInt(all.length) });
+    return { run, events };
+  }
+}

package/src/foreman/fake-worker-adapter.ts

@@ -0,0 +1,221 @@
+import { completedEvent, type CompletionReport } from "./completion-report.js";
+import type { AdapterEvent, InteractiveCommand, InteractiveSessionRequest, TurnHandle, TurnRequest, WorkerAdapter } from "./worker-adapter.js";
+
+/**
+ * A Worker Adapter that replays scripts instead of running a vendor CLI. Every later Foreman test
+ * (scheduling, Gates, Verifiers) drives the core through this so the LLM is out of the loop
+ * (spec, "Testing Decisions"). A script is the event list one turn yields, in order, ending in a
+ * terminal event; a script may also be a function, for turns that must wait or react to `stop()`.
+ */
+export type FakeTurnScript = AdapterEvent[] | ((control: FakeTurnControl) => AsyncIterable<AdapterEvent>);
+
+export interface FakeTurnControl {
+  /** Resolves when `stop()` is called on the handle, for scripts that hang until stopped. */
+  stopped: Promise<void>;
+  /** The request this turn was launched or resumed with. */
+  request: TurnRequest;
+}
+
+/** Scripts a turn that starts and reports the given outcome. Defaults are a minimal valid report. */
+export function scriptedTurn(sessionId: string, report: Partial<CompletionReport> = {}, before: AdapterEvent[] = []): AdapterEvent[] {
+  const full: CompletionReport = {
+    outcome: "done",
+    summary: "Scripted turn finished.",
+    decisions: [],
+    tried: [],
+    blockers: [],
+    proposedLearnings: [],
+    ...report,
+  };
+  return [{ type: "started", sessionId }, ...before, { type: "completed", sessionId, report: full }];
+}
+
+/** Scripts a turn that starts and ends with `structured` as its final message: what a turn under a
+ * contract other than the Completion Report (the Verifier's Verdict) hands back. The fake holds it
+ * to the request's contract the way the vendor adapters do (`replay`), so a script handing in a
+ * malformed object ends the turn as `invalid_report`. */
+export function structuredTurn(sessionId: string, structured: unknown, before: AdapterEvent[] = []): AdapterEvent[] {
+  const [started, completed] = scriptedTurn(sessionId);
+  return [started, ...before, { ...(completed as Extract<AdapterEvent, { type: "completed" }>), structured }];
+}
+
+/** Scripts a turn the vendor refused on a rate limit. */
+export function rateLimitedTurn(sessionId: string, resetAt?: string): AdapterEvent[] {
+  const message = "Scripted rate limit";
+  return [
+    { type: "started", sessionId },
+    { type: "rate_limited", resetAt, message },
+    { type: "failed", reason: "rate_limited", message, sessionId },
+  ];
+}
+
+/** Scripts a turn the vendor refused because the Account's credential is dead (OPS-288). No event
+ * precedes the failure, unlike a rate limit's: there is nothing for the Run to learn mid-turn, and
+ * the decision to quarantine is made from the terminal event alone. */
+export function credentialFailedTurn(sessionId: string, message = "Scripted dead credential"): AdapterEvent[] {
+  return [
+    { type: "started", sessionId },
+    { type: "failed", reason: "credential_failed", message, sessionId },
+  ];
+}
+
+/** Scripts a turn that produces output and then goes silent until stopped or the stall timer fires.
+ * The fake does not run a real timer: with `stallTimeoutMs` set it reports the stall at once. */
+export function stallingTurn(sessionId: string): FakeTurnScript {
+  return async function* (control) {
+    yield { type: "started", sessionId };
+    yield { type: "output", text: "working..." };
+    const stallMs = control.request.stallTimeoutMs;
+    if (stallMs !== undefined) {
+      yield { type: "stalled", silentMs: stallMs };
+      yield { type: "failed", reason: "stalled", message: `No output for ${stallMs}ms`, sessionId };
+      return;
+    }
+    await control.stopped;
+    yield { type: "failed", reason: "stopped", message: "Stopped before the Worker reported", sessionId };
+  };
+}
+
+/** A turn a test finishes when it chooses, so concurrency is deterministic rather than raced: the
+ * scheduler's tests hold several turns open at once, look at how many are running, and then let
+ * them report one at a time. `started` resolves as the turn begins (the Foreman has taken a Slot
+ * for it), and the turn ends only once `finish` is called. */
+export interface GatedTurn {
+  script: FakeTurnScript;
+  /** Resolves the moment the Foreman launched this turn: it has taken a Slot for it. */
+  started: Promise<void>;
+  /** True between the launch and the report: what a test counts to see how many turns are running. */
+  readonly running: boolean;
+  /** Lets the turn report, ending it. */
+  finish: (report?: Partial<CompletionReport>) => void;
+}
+
+/** A turn a test ends when it chooses, so concurrency is deterministic rather than raced: the
+ * scheduler's tests hold several turns open at once, count how many are running, and then let them
+ * report one at a time. */
+export function gatedTurn(sessionId: string): GatedTurn {
+  let began!: () => void;
+  const started = new Promise<void>((resolve) => {
+    began = resolve;
+  });
+  let release!: (report: Partial<CompletionReport>) => void;
+  const gate = new Promise<Partial<CompletionReport>>((resolve) => {
+    release = resolve;
+  });
+  const turn = {
+    running: false,
+    started,
+    finish: (report: Partial<CompletionReport> = {}) => release(report),
+    script: async function* (): AsyncIterable<AdapterEvent> {
+      yield { type: "started", sessionId };
+      turn.running = true;
+      began();
+      const report = await gate;
+      turn.running = false;
+      yield* scriptedTurn(sessionId, report).slice(1);
+    },
+  };
+  return turn;
+}
+
+export class FakeWorkerAdapter implements WorkerAdapter {
+  /** Every request seen, in order, so a test can assert what the Foreman asked for. */
+  readonly launches: TurnRequest[] = [];
+  readonly resumes: { sessionId: string; request: TurnRequest }[] = [];
+  /** Every interactive command asked for (`foreman attach`), in order. */
+  readonly interactives: { sessionId: string; request: Pick<TurnRequest, "account" | "cwd"> }[] = [];
+  /** Every interactive session asked for (`foreman plan`), in order. */
+  readonly sessions: InteractiveSessionRequest[] = [];
+  private readonly scripts: FakeTurnScript[];
+  /** Chooses a script from the request rather than from the queue: what a test needs once turns
+   * overlap, since the queue's order is then the very thing under test. Consulted first; a request
+   * it has no script for falls back to the queue. */
+  scriptFor?: (request: TurnRequest) => FakeTurnScript | undefined;
+
+  constructor(scripts: FakeTurnScript[] = []) {
+    this.scripts = [...scripts];
+  }
+
+  /** Queues the script the next `launch` or `resume` will replay. */
+  enqueue(script: FakeTurnScript): this {
+    this.scripts.push(script);
+    return this;
+  }
+
+  launch(request: TurnRequest): TurnHandle {
+    this.launches.push(request);
+    return this.replay(request);
+  }
+
+  resume(sessionId: string, request: TurnRequest): TurnHandle {
+    this.resumes.push({ sessionId, request });
+    return this.replay(request);
+  }
+
+  /** A command a test can recognise and never run: `fake-worker --resume <id>` in the Workspace. */
+  interactiveCommand(sessionId: string, request: Pick<TurnRequest, "account" | "cwd">): InteractiveCommand {
+    this.interactives.push({ sessionId, request });
+    return { command: "fake-worker", args: ["--resume", sessionId], cwd: request.cwd, env: { FAKE_ACCOUNT: request.account.name } };
+  }
+
+  /** `fake-worker --prompt <prompt>` in the Workspace: recognisable, never run. */
+  interactiveSession(request: InteractiveSessionRequest): InteractiveCommand {
+    this.sessions.push(request);
+    return { command: "fake-worker", args: ["--prompt", request.prompt], cwd: request.cwd, env: { FAKE_ACCOUNT: request.account.name } };
+  }
+
+  private replay(request: TurnRequest): TurnHandle {
+    const script = this.scriptFor?.(request) ?? this.scripts.shift();
+    let stop!: () => void;
+    const stopped = new Promise<void>((resolve) => {
+      stop = resolve;
+    });
+    const control: FakeTurnControl = { request, stopped };
+    let stopRequested = false;
+
+    const source: AsyncIterable<AdapterEvent> =
+      script === undefined
+        ? (async function* () {
+            yield { type: "failed", reason: "launch_failed", message: "FakeWorkerAdapter has no script queued for this turn" } as AdapterEvent;
+          })()
+        : typeof script === "function"
+          ? script(control)
+          : (async function* () {
+              yield* script;
+            })();
+
+    // Stopping cuts the replay off at the next event and substitutes the `stopped` failure, the way a
+    // killed process would end the real stream; a script that already reached its terminal event is
+    // left alone. A request under a contract (the Verifier's) has its final message judged by that
+    // contract, as the vendor adapters judge theirs: a script's `structured` (or its report, when it
+    // scripted none) is parsed, and a malformed one ends the turn as `invalid_report`.
+    const contract = request.contract;
+    const events: AsyncIterable<AdapterEvent> = (async function* () {
+      for await (const event of source) {
+        if (stopRequested && event.type !== "completed" && event.type !== "failed") {
+          yield { type: "failed", reason: "stopped", message: "Stopped before the Worker reported" };
+          return;
+        }
+        if (event.type === "completed" && contract) {
+          const parsed = contract.parse(event.structured ?? event.report);
+          if (!parsed.ok) {
+            yield { type: "failed", reason: "invalid_report", message: `The Worker's final message is not a ${contract.name}`, sessionId: event.sessionId, details: parsed.errors };
+            return;
+          }
+          yield { ...event, ...completedEvent(contract, parsed.value, event.sessionId) };
+          return;
+        }
+        yield event;
+        if (event.type === "completed" || event.type === "failed") return;
+      }
+    })();
+
+    return {
+      events,
+      async stop() {
+        stopRequested = true;
+        stop();
+      },
+    };
+  }
+}

package/src/foreman/host.ts

@@ -0,0 +1,75 @@
+/**
+ * What kind of machine the daemon is on (story 17). A laptop sleeps: the lid closes, the display
+ * timer fires, and every Worker in flight is suspended mid-turn; Reconcile resumes them on wake,
+ * but the Run stalls for as long as the lid is down. `foreman up` warns when it finds an internal
+ * battery, which is the one signal that separates a laptop from a desktop or a server, and says
+ * how to keep the machine awake. Detection is a probe with injected commands and file system so a
+ * test can be a laptop or a server at will.
+ */
+
+import { join } from "node:path";
+
+export interface HostProbeDeps {
+  platform: NodeJS.Platform;
+  /** Runs a command and resolves with its stdout; rejects when it is missing or fails. */
+  exec: (file: string, args: string[]) => Promise<string>;
+  /** Lists a directory, or throws when it does not exist. */
+  readdir: (dir: string) => string[];
+  /** Reads a small file as text, or throws when it does not exist. */
+  readFile: (path: string) => string;
+}
+
+/** Where Linux exposes power supplies. Each entry has a `type`; an internal battery is one of type
+ * `Battery` whose `scope` is not `Device` (a mouse's or a headset's is), whatever its name: BAT0
+ * on most, macsmc-battery, axp20x-battery, sbs-* and bq27xxx-* elsewhere. */
+export const LINUX_POWER_SUPPLY_DIR = "/sys/class/power_supply";
+
+/** True when the machine has an internal battery, false for a desktop, a server, or an unknown
+ * platform. A probe that fails (no `pmset`, no sysfs) reads as not a laptop: the warning is a
+ * courtesy, and a false one on every server would teach people to ignore it. */
+export async function hostIsLaptop(deps: HostProbeDeps): Promise<boolean> {
+  try {
+    if (deps.platform === "darwin") {
+      const batt = await deps.exec("pmset", ["-g", "batt"]);
+      if (batt.includes("InternalBattery")) return true;
+      const ioreg = await deps.exec("ioreg", ["-r", "-c", "AppleSmartBattery"]);
+      return ioreg.includes("AppleSmartBattery");
+    }
+    if (deps.platform === "linux") {
+      return deps.readdir(LINUX_POWER_SUPPLY_DIR).some((name) => linuxSupplyIsInternalBattery(deps, join(LINUX_POWER_SUPPLY_DIR, name)));
+    }
+  } catch {
+    // Fall through: an unanswerable probe is not a laptop.
+  }
+  return false;
+}
+
+/** One power supply: a battery by its `type`, internal by a `scope` that is not `Device` (absent
+ * counts as internal; the kernel writes it only for peripherals). An entry that cannot be read is
+ * not a battery. */
+function linuxSupplyIsInternalBattery(deps: HostProbeDeps, dir: string): boolean {
+  try {
+    if (deps.readFile(join(dir, "type")).trim() !== "Battery") return false;
+  } catch {
+    return false;
+  }
+  try {
+    return deps.readFile(join(dir, "scope")).trim() !== "Device";
+  } catch {
+    return true;
+  }
+}
+
+/** The warning `foreman up` prints on a laptop: the risk, and the ways out. */
+export function sleepWarning(platform: NodeJS.Platform): string[] {
+  const keepAwake =
+    platform === "darwin"
+      ? "run it under caffeinate (caffeinate -i opsee foreman up), or turn off sleep in System Settings > Battery while it works"
+      : platform === "linux"
+        ? "run it under systemd-inhibit (systemd-inhibit --what=sleep opsee foreman up), or turn off suspend in your power settings while it works"
+        : "turn off sleep while it works";
+  return [
+    "Warning: this machine has a battery, so it is a laptop that may sleep. Sleep suspends every Worker mid-turn; Reconcile resumes them on wake, but the Run stalls until then.",
+    `To keep it going: ${keepAwake}, or move the Run to an always-on host (opsee foreman service install there).`,
+  ];
+}

package/src/foreman/local-dir.ts

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Where the Foreman keeps what is meaningful only on this machine (ADR-0009): the Process Table,
+ * the daemon's pid file and the Worker transcripts. All under `~/.opsee/`, beside the credentials
+ * file the MCP server keeps and the Accounts file (account-store.ts), each with its own override
+ * so a test can point one at a temporary directory without touching the others.
+ */
+export function foremanLocalDir(): string {
+  return process.env.OPSEE_FOREMAN_LOCAL_DIR || join(homedir(), ".opsee");
+}
+
+/** The SQLite Process Table (core/process-table.ts). */
+export function processTablePath(): string {
+  return process.env.OPSEE_FOREMAN_PROCESS_TABLE_PATH || join(foremanLocalDir(), "foreman-process-table.sqlite");
+}
+
+/** Where each turn's raw adapter event stream is written (core/transcripts.ts): the transcript
+ * never leaves the machine (story 49). */
+export function transcriptsDir(): string {
+  return process.env.OPSEE_FOREMAN_TRANSCRIPTS_PATH || join(foremanLocalDir(), "transcripts");
+}
+
+/** The daemon's pid file (commands/foreman.ts): how `foreman run` tells whether a daemon is up. */
+export function daemonPidPath(): string {
+  return process.env.OPSEE_FOREMAN_PID_PATH || join(foremanLocalDir(), "foreman.pid");
+}