faberun 0.3.0

package/src/run/usage.mjs

@@ -0,0 +1,337 @@
+/**
+ * The usage and cost ledger: `usage.jsonl`, one record per invocation, and the
+ * arithmetic that rolls it up onto a node.
+ *
+ * Reporting only. No control path reads this -- a spent allowance is handled by
+ * runtime re-tiering, never by a token or dollar cap -- and that is why a usage
+ * the provider did not report stays null instead of becoming a plausible zero.
+ */
+import { appendJsonl, writeJsonAtomic } from "./store.mjs";
+import { basename, join } from "node:path";
+import { errorMessage, stableJson } from "../util.mjs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { liveUsage } from "../harnesses/exec-jsonl/index.mjs";
+
+import { priceUsage, readBoundedTail } from "../engine/process.mjs";
+import { writeNode } from "../engine/state.mjs";
+import { normalizeProviderResult } from "../harnesses/index.mjs";
+
+// `priceUsage` is defined beside `invocationResult`, the second source point,
+// and re-exported here so the ledger's public surface is unchanged. This module
+// already imports `engine/process.mjs`, so the definition lives there to keep
+// the two source points out of a runtime import cycle.
+export { priceUsage };
+
+/** @typedef {import("../engine/process.mjs").Invocation} Invocation */
+/** @typedef {import("../engine/process.mjs").Job} Job */
+/** @typedef {ReturnType<typeof import("../run/lock.mjs").acquire>} LockHandle */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("../harnesses/index.mjs").ProviderEnvelope} ProviderEnvelope */
+/** @typedef {ProviderEnvelope & {costProvenance?: "priced"}} PricedEnvelope */
+/** @typedef {{kind: "adopted"|"rejudge"|"restart"|"reconciled"|"exhausted"|"stalled", phase?: "worker"|"judge", result?: unknown, usage?: Usage, costUsd?: number|null, costProvenance?: "priced", exhaustedUntil?: string|null, error?: {code: string, message: string}|null, invocationId?: string, reason?: string}} RecoveryOutcome */
+/** @typedef {import("../contract/index.mjs").Usage} Usage */
+
+/**
+ * Extract the invocation's provider envelope from the bounded transcript tail
+ * and persist its usage into the matching invocation record. By default the
+ * usage is also accumulated into `state.usage` (the caller then transitions or
+ * continues); with `accumulate: false` only the invocation record is updated,
+ * for jobs whose node already reached a terminal state that already counted
+ * this spend.
+ *
+ * @param {Job} job
+ * @param {{accumulate?: boolean}} [options]
+ * @returns {PricedEnvelope}
+ */
+export function recordInvocationUsage(job, options = {}) {
+  const { state } = job;
+  /** @type {PricedEnvelope} */
+  let envelope;
+  let boundedStdout = "";
+  try {
+    boundedStdout = readBoundedTail(job.paths.stdout);
+    const boundedStderr = readBoundedTail(job.paths.stderr, 512 * 1024);
+    envelope = normalizeProviderResult(job.runtime, boundedStdout, job.exitCode, job.signal, {
+      preferStructured: job.phase === "judge",
+      stderr: boundedStderr,
+    });
+  } catch (error) {
+    envelope = {
+      status: "failed",
+      result: null,
+      continuationId: null,
+      usage: { inputTokens: null, outputTokens: null, cacheReadInputTokens: null },
+      costUsd: null,
+      error: { code: "invalid_output", message: errorMessage(error) },
+    };
+  }
+  // Failure envelopes carry zeroed usage (a killed provider emits no terminal
+  // event), yet its transcript holds real per-turn counters. Backfill the
+  // normalized usage components from the live meter so kills, timeouts, and
+  // scope failures still report what they spent, cache reads separated.
+  if (envelope.usage.inputTokens === null && boundedStdout) {
+    const observed = liveUsage(job.runtime.harness, boundedStdout);
+    if (observed.inputTokens !== null) {
+      envelope = { ...envelope, usage: { ...envelope.usage, inputTokens: observed.inputTokens, cacheReadInputTokens: observed.cacheReadInputTokens } };
+    }
+  }
+  // Price only after the backfill has run: the counters this function persists
+  // and returns are the ones the price is derived from, and the envelope becomes
+  // the single priced object every later copy spreads from.
+  const priced = priceUsage(job.runtime, envelope.usage, envelope.costUsd);
+  envelope = { ...envelope, costUsd: priced.costUsd, costProvenance: priced.costProvenance };
+  state.invocations = (state.invocations ?? []).map((invocation) => invocation.id === job.invocation.id
+    ? { ...invocation, usage: envelope.usage, costUsd: envelope.costUsd, costProvenance: envelope.costProvenance }
+    : invocation);
+  if (options.accumulate !== false) state.usage = addUsage(state.usage, envelope.usage);
+  return envelope;
+}
+const USAGE_LOG_NAME = "usage.jsonl";
+/** @param {Usage|undefined} usage @returns {boolean} */
+function hasMeasuredUsage(usage) {
+  return Boolean(usage && [usage.inputTokens, usage.outputTokens, usage.cacheReadInputTokens]
+    .some((value) => typeof value === "number" && Number.isFinite(value)));
+}
+/** @param {NodeSnapshot} state @returns {Usage} */
+export function invocationUsage(state) {
+  const seen = new Set();
+  return (state.invocations ?? []).reduce((total, invocation) => {
+    if (invocation.id && seen.has(invocation.id)) return total;
+    if (invocation.id) seen.add(invocation.id);
+    return addUsage(total, invocation.usage);
+  }, /** @type {Usage} */ ({ inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 }));
+}
+/** @param {NodeSnapshot} state @returns {number|undefined} */
+export function invocationCost(state) {
+  const costs = /** @type {number[]} */ ((state.invocations ?? [])
+    .map((invocation) => invocation.costUsd)
+    .filter((cost) => typeof cost === "number" && Number.isFinite(cost)));
+  return costs.length ? costs.reduce((total, cost) => total + cost, 0) : undefined;
+}
+/**
+ * Invocation ids already present in the run's usage.jsonl. The append path
+ * uses this to stay idempotent across resume and replay.
+ *
+ * @param {string} runDir
+ * @returns {Set<string>}
+ */
+export function usageRecordIds(runDir) {
+  const ids = new Set();
+  const path = join(runDir, USAGE_LOG_NAME);
+  if (!existsSync(path)) return ids;
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const record = JSON.parse(line);
+      const value = record && typeof record === "object" && !Array.isArray(record)
+        ? /** @type {Record<string, unknown>} */ (record)
+        : null;
+      if (value && typeof value.invocationId === "string") ids.add(value.invocationId);
+    } catch {
+      // A truncated tail line is repaired by appendJsonl on the next write.
+    }
+  }
+  return ids;
+}
+/**
+ * Append one usage.jsonl record for a worker or judge invocation. Usage is a
+ * reporting record only: no control path reads this file to gate work.
+ *
+ * @param {string} runDir
+ * @param {Invocation|undefined|null} invocation
+ */
+export function appendUsageRecord(runDir, invocation) {
+  if (!invocation?.id || usageRecordIds(runDir).has(invocation.id)) return;
+  const usage = /** @type {Usage} */ (invocation.usage ?? { inputTokens: null, outputTokens: null, cacheReadInputTokens: null });
+  appendJsonl(join(runDir, USAGE_LOG_NAME), {
+    invocationId: invocation.id,
+    runId: invocation.runId ?? basename(runDir),
+    nodeId: invocation.nodeId ?? null,
+    attempt: invocation.attempt ?? null,
+    role: invocation.role ?? null,
+    runtimeId: invocation.runtimeId ?? null,
+    model: invocation.model ?? null,
+    inputTokens: typeof usage.inputTokens === "number" ? usage.inputTokens : null,
+    cacheReadInputTokens: typeof usage.cacheReadInputTokens === "number" ? usage.cacheReadInputTokens : null,
+    outputTokens: typeof usage.outputTokens === "number" ? usage.outputTokens : null,
+    costUsd: typeof invocation.costUsd === "number" ? invocation.costUsd : null,
+    // A persisted `priced` marker wins; otherwise the pre-Phase-4 rule applies
+    // unchanged: a reported number is `provider`, absence is `unknown`.
+    costProvenance: invocation.costProvenance ?? (typeof invocation.costUsd === "number" ? "provider" : "unknown"),
+    startedAt: invocation.startedAt ?? null,
+    finishedAt: invocation.closedAt ?? null,
+  });
+}
+/**
+ * Recovery can discover usage after the run synchronized its records. Attach
+ * it to the authoritative invocation first, then write the updated usage
+ * record. The invocation id makes repeated resumes idempotent.
+ *
+ * @param {string} runDir
+ * @param {NodeSnapshot} state
+ * @param {RecoveryOutcome|null|undefined} recovery
+ * @param {LockHandle} lock
+ * @returns {Promise<void>}
+ */
+export async function persistRecoveryUsage(runDir, state, recovery, lock) {
+  if (!recovery?.invocationId) return;
+  const current = state.invocations?.find((invocation) => invocation.id === recovery.invocationId);
+  if (!current) return;
+  const usage = hasMeasuredUsage(current.usage) ? current.usage : recovery.usage;
+  // Cost and provenance are selected together from whichever source wins the
+  // numeric-cost predicate: an independent fallback could attach a stray
+  // recovery provenance to an already-settled cost that was never priced.
+  const priced = typeof current.costUsd === "number"
+    ? { costUsd: current.costUsd, costProvenance: current.costProvenance }
+    : { costUsd: recovery.costUsd ?? null, costProvenance: recovery.costProvenance };
+  const changed = stableJson(current.usage) !== stableJson(usage)
+    || current.costUsd !== priced.costUsd
+    || (current.costProvenance ?? null) !== (priced.costProvenance ?? null);
+  if (changed) {
+    state.invocations = (state.invocations ?? []).map((invocation) => invocation.id === current.id
+      ? { ...invocation, usage, costUsd: priced.costUsd, costProvenance: priced.costProvenance }
+      : invocation);
+    state.usage = invocationUsage(state);
+    writeNode(runDir, state, lock);
+  }
+  const updated = state.invocations?.find((invocation) => invocation.id === current.id);
+  if (updated) appendUsageRecord(runDir, updated);
+}
+/**
+ * @param {Usage|undefined} left
+ * @param {Usage|undefined} right
+ * @returns {Usage}
+ */
+function addUsage(left, right) {
+  return {
+    inputTokens: (left?.inputTokens ?? 0) + (right?.inputTokens ?? 0),
+    outputTokens: (left?.outputTokens ?? 0) + (right?.outputTokens ?? 0),
+    cacheReadInputTokens: (left?.cacheReadInputTokens ?? 0) + (right?.cacheReadInputTokens ?? 0),
+  };
+}
+/** @returns {{inputTokens: number|null, outputTokens: number|null, cacheReadInputTokens: number|null}} */
+export function emptyUsage() {
+  return { inputTokens: null, outputTokens: null, cacheReadInputTokens: null };
+}
+
+/**
+ * The named artifact the fresh-session hypothesis is recorded to. The
+ * measurement is the acceptance, not a threshold met: a cohort with no gate
+ * revision is recorded as absent rather than compared against an empty set.
+ */
+export const CACHE_READ_PER_REVISION_ARTIFACT = "cacheReadPerRevision.json";
+
+/** @typedef {{runCount: number, runsWithGateRevision: number, gateRevisions: number, retryWorkerInvocations: number, cacheReadTokens: number, cacheReadPerRevision: number|null}} CacheReadCohort */
+/** @typedef {{before: CacheReadCohort, after: CacheReadCohort}} CacheReadCohorts */
+
+/**
+ * `cacheReadPerRevision` over one cohort of run directories:
+ *
+ *   cacheReadPerRevision =
+ *     cache-read tokens attributable to gate revisions
+ *     / number of gate revisions
+ *
+ * A gate revision is one `state.revisions` increment — a judge or mechanical
+ * rejection that re-dispatched the worker. The persisted ledger does not link
+ * an invocation to the rejection that caused it, so the attribution is the
+ * declared approximation: the cache-read tokens recorded on worker invocations
+ * after the first attempt of their node, which are the retries that include
+ * those gate revisions. A cohort with no gate revision reports
+ * `cacheReadPerRevision: null`, never a divide-by-zero.
+ *
+ * @param {string[]} runDirs
+ * @returns {CacheReadCohort}
+ */
+export function measureCacheReadPerRevision(runDirs) {
+  let gateRevisions = 0;
+  let retryWorkerInvocations = 0;
+  let cacheReadTokens = 0;
+  let runsWithGateRevision = 0;
+  for (const runDir of runDirs) {
+    let runRevisions = 0;
+    for (const name of listNodeSnapshotFiles(runDir)) {
+      let state;
+      try {
+        state = JSON.parse(readFileSync(join(runDir, "nodes", name), "utf8"));
+      } catch {
+        // A torn or unreadable snapshot contributes nothing; a measurement
+        // never fails because one run was mid-write.
+        continue;
+      }
+      if (typeof state.revisions === "number" && Number.isFinite(state.revisions)) runRevisions += state.revisions;
+      for (const invocation of Array.isArray(state.invocations) ? state.invocations : []) {
+        if (invocation?.role !== "worker") continue;
+        if (!(typeof invocation.attempt === "number" && invocation.attempt > 1)) continue;
+        retryWorkerInvocations += 1;
+        const cacheRead = invocation.usage?.cacheReadInputTokens;
+        if (typeof cacheRead === "number" && Number.isFinite(cacheRead)) cacheReadTokens += cacheRead;
+      }
+    }
+    if (runRevisions > 0) {
+      gateRevisions += runRevisions;
+      runsWithGateRevision += 1;
+    }
+  }
+  return {
+    runCount: runDirs.length,
+    runsWithGateRevision,
+    gateRevisions,
+    retryWorkerInvocations,
+    cacheReadTokens,
+    cacheReadPerRevision: gateRevisions > 0 ? cacheReadTokens / gateRevisions : null,
+  };
+}
+
+/**
+ * The two declared cohorts and the recorded comparison. `before` is the runs
+ * preceding the change commit and `after` those following it; when the after
+ * cohort records no gate revision the artifact says so explicitly rather than
+ * presenting an empty comparison. `changeCommit` is recorded so the cohort
+ * boundary is auditable.
+ *
+ * @param {CacheReadCohort} before
+ * @param {CacheReadCohort} after
+ * @param {{changeCommit?: string|null, generatedAt?: string, runDirs?: {before: string[], after: string[]}}} [context]
+ * @returns {Record<string, unknown>}
+ */
+export function cacheReadPerRevisionArtifact(before, after, context = {}) {
+  const measured = after.gateRevisions > 0;
+  return {
+    schemaVersion: 1,
+    metric: "cacheReadPerRevision",
+    definition: "cache-read tokens attributable to gate revisions divided by the number of gate revisions",
+    attribution: "gateRevisions is the sum of persisted node revisions; cacheReadTokens is the cache-read tokens on worker invocations after the first attempt, the retries that include those gate revisions",
+    changeCommit: context.changeCommit ?? null,
+    generatedAt: context.generatedAt ?? new Date().toISOString(),
+    status: measured ? "measured" : "no_post_change_revision",
+    note: measured
+      ? "the after cohort records at least one gate revision; before and after are compared below"
+      : "no post-change gate revision exists: the after cohort records zero gate revisions, so no comparison is fabricated",
+    before,
+    after,
+    ...(context.runDirs ? { runDirs: context.runDirs } : {}),
+  };
+}
+
+/**
+ * Write the measurement to its named artifact path.
+ *
+ * @param {string} artifactPath
+ * @param {CacheReadCohort} before
+ * @param {CacheReadCohort} after
+ * @param {{changeCommit?: string|null, generatedAt?: string, runDirs?: {before: string[], after: string[]}}} [context]
+ * @returns {string} the artifact path
+ */
+export function writeCacheReadPerRevisionArtifact(artifactPath, before, after, context = {}) {
+  writeJsonAtomic(artifactPath, cacheReadPerRevisionArtifact(before, after, context));
+  return artifactPath;
+}
+
+/** @param {string} runDir @returns {string[]} */
+function listNodeSnapshotFiles(runDir) {
+  try {
+    return readdirSync(join(runDir, "nodes")).filter((name) => name.endsWith(".json"));
+  } catch {
+    return [];
+  }
+}

package/src/seat/harnesses.mjs

@@ -0,0 +1,83 @@
+/**
+ * The operator harness registry: how to launch an interactive harness, how to
+ * recognize it from the environment, and whether it can render ambient state.
+ *
+ * The seat is where a human talks to a harness; it is not a second worker
+ * engine. These five entries are the whole operator surface and each one
+ * declares exactly three facts. The worker registry in `harnesses/` answers a
+ * different question with a much larger interface, and keeping the two apart is
+ * why this is one declarative file instead of a folder per harness.
+ *
+ * `canRenderAmbient` is true only for claude, the single harness with a
+ * statusLine surface (TECH-SPEC 2026-09-12 §3.2). An `envMarker` is the
+ * variable the harness leaves in the shell it starts, so the registry can name
+ * the harness a seat is already inside without probing a process table.
+ *
+ * @typedef {Readonly<{argv: readonly string[], envMarker: string, canRenderAmbient: boolean}>} OperatorHarness
+ */
+
+/** @type {Readonly<Record<string, OperatorHarness>>} */
+export const OPERATOR_HARNESSES = Object.freeze({
+  claude: Object.freeze({ argv: Object.freeze(["claude"]), envMarker: "CLAUDECODE", canRenderAmbient: true }),
+  codex: Object.freeze({ argv: Object.freeze(["codex"]), envMarker: "CODEX_SANDBOX", canRenderAmbient: false }),
+  zcode: Object.freeze({ argv: Object.freeze(["zcode"]), envMarker: "ZCODE_MODEL", canRenderAmbient: false }),
+  dsh: Object.freeze({ argv: Object.freeze(["dsh"]), envMarker: "DSH_PERMISSION_MODE", canRenderAmbient: false }),
+  agy: Object.freeze({ argv: Object.freeze(["agy"]), envMarker: "AGY_MODEL", canRenderAmbient: false }),
+});
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function canRenderAmbient(name) {
+  const harness = /** @type {OperatorHarness|undefined} */ (OPERATOR_HARNESSES[name]);
+  return harness?.canRenderAmbient === true;
+}
+
+/**
+ * The argv a seat launches for one harness, with an optional instruction
+ * appended as a single positional argument. `seat switch` passes the operator
+ * brief here so a fresh harness starts by reading what the previous one knew,
+ * and the registry stays the one place that knows each harness's base command.
+ *
+ * @param {string} name
+ * @param {string|null} [instruction]
+ * @returns {string[]|null}
+ */
+export function launchArgv(name, instruction = null) {
+  const harness = /** @type {OperatorHarness|undefined} */ (OPERATOR_HARNESSES[name]);
+  if (!harness) return null;
+  return instruction ? [...harness.argv, instruction] : [...harness.argv];
+}
+
+/**
+ * The operator harness this process is running inside, or null. Detection is
+ * marker-based on purpose: the markers above are the only environment facts a
+ * harness guarantees, and reading them costs nothing.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function detectOperatorHarness(env = process.env) {
+  for (const [name, harness] of Object.entries(OPERATOR_HARNESSES)) {
+    if (env[harness.envMarker] !== undefined) return name;
+  }
+  return null;
+}
+
+/**
+ * The operator harness a pane's current command names, or null while the pane
+ * is still a shell or has moved on to something the registry does not know.
+ * The registry's launch argv is the contract: whatever `argv[0]` is, that is
+ * the command a live seat of that harness shows.
+ *
+ * @param {string|null|undefined} command
+ * @returns {string|null}
+ */
+export function detectOperatorHarnessByCommand(command) {
+  const name = String(command ?? "").split(/[\\/]/u).at(-1) ?? "";
+  for (const [harness, entry] of Object.entries(OPERATOR_HARNESSES)) {
+    if (entry.argv[0] === name) return harness;
+  }
+  return null;
+}

package/src/seat/index.mjs

@@ -0,0 +1,239 @@
+/**
+ * The seat facade the CLI calls: `startSeat`, `attachSeat`, `seatStatus`,
+ * `stopSeat`, `switchSeat`.
+ *
+ * It composes the tmux session layer with the operator harness registry and
+ * executes no tmux itself; every tmux fact comes back from `tmux.mjs` as an
+ * explicit result. The seat is where a human talks to a harness, never the
+ * engine that drives a run. `switchSeat` does write one durable file -- the
+ * operator brief under the campaign directory -- but nothing here reads or
+ * writes a run's lock, status or node snapshots, so swapping the pane cannot
+ * touch the controller that drives the run.
+ */
+import { join, resolve } from "node:path";
+import { OPERATOR_HARNESSES, canRenderAmbient, detectOperatorHarness, detectOperatorHarnessByCommand, launchArgv } from "./harnesses.mjs";
+import { SEAT_SESSION, createSeatWindow, listSeatWindows, respawnSeatWindow, stopSeatSession, stopSeatWindow, tmuxAvailability } from "./tmux.mjs";
+import { BRIEF_FILE } from "../campaign/layout.mjs";
+import { briefFromState, materializeBrief } from "../campaign/brief.mjs";
+import { readProjectionState } from "../campaign/projection.mjs";
+import { resolveCampaign } from "../campaign/index.mjs";
+import { errorMessage } from "../util.mjs";
+
+/** `seat status --json` payload version. */
+const SEAT_STATUS_SCHEMA_VERSION = 1;
+
+/** @typedef {import("./tmux.mjs").SeatWindow} SeatWindow */
+/** @typedef {{campaign: string, harness: string|null, canRenderAmbient: boolean, command: string|null, index: number|null}} SeatStatusEntry */
+/** @typedef {{ok: boolean, available: boolean, reason: string|null, session: string, campaign: string, harness: string|null, window: string|null, command: string|null, attachCommand: string|null, stderr: string, message: string|null}} SeatStartResult */
+/** @typedef {{ok: boolean, available: boolean, reason: string|null, session: string, campaign: string|null, harness: string|null, window: string|null, command: string|null, brief: string|null, attachCommand: string|null, stderr: string, message: string|null}} SeatSwitchResult */
+
+/**
+ * @param {{campaign: string, harness?: string, cwd?: string}} options
+ * @returns {SeatStartResult}
+ */
+export function startSeat(options) {
+  const campaign = options.campaign;
+  if (!campaign) return startFailure("campaign_required", "", null, "a campaign id is required");
+  const harness = options.harness ?? detectOperatorHarness();
+  if (!harness || !Object.prototype.hasOwnProperty.call(OPERATOR_HARNESSES, harness)) {
+    const known = Object.keys(OPERATOR_HARNESSES).join(", ");
+    return startFailure("unknown_harness", campaign, harness ?? null, `unknown harness ${harness ?? "(none detected)"}; choose one of ${known}`);
+  }
+  const created = createSeatWindow({
+    session: SEAT_SESSION,
+    window: campaign,
+    argv: /** @type {string[]} */ (launchArgv(harness)),
+    harness,
+    cwd: resolve(options.cwd ?? "."),
+  });
+  if (!created.ok) {
+    const message = created.available
+      ? `tmux could not create the seat window: ${created.reason ?? "tmux_command_failed"}`
+      : "tmux is not available; cannot start the seat";
+    return { ...startFailure(created.reason ?? "tmux_command_failed", campaign, harness, message), available: created.available, stderr: created.stderr };
+  }
+  return {
+    ok: true,
+    available: true,
+    reason: null,
+    session: SEAT_SESSION,
+    campaign,
+    harness,
+    window: campaign,
+    command: created.command,
+    attachCommand: attachCommandLine(SEAT_SESSION, campaign, null),
+    stderr: "",
+    message: null,
+  };
+}
+
+/**
+ * @param {{campaign?: string, ssh?: string}} [options]
+ * @returns {{ok: boolean, available: boolean, reason: string|null, command: string|null, target: string, message: string|null}}
+ */
+export function attachSeat(options = {}) {
+  const target = options.campaign ? `${SEAT_SESSION}:${options.campaign}` : SEAT_SESSION;
+  // An SSH attach runs tmux on the far side, so the local binary is irrelevant.
+  if (options.ssh) {
+    return { ok: true, available: true, reason: null, command: attachCommandLine(SEAT_SESSION, options.campaign ?? null, options.ssh), target, message: null };
+  }
+  const availability = tmuxAvailability();
+  if (!availability.available) {
+    return { ok: false, available: false, reason: "tmux_unavailable", command: null, target, message: "tmux is not available; cannot reattach to the seat" };
+  }
+  return { ok: true, available: true, reason: null, command: attachCommandLine(SEAT_SESSION, options.campaign ?? null, null), target, message: null };
+}
+
+/**
+ * @returns {{schemaVersion: number, session: string, tmux: boolean, seats: SeatStatusEntry[], reason: string|null}}
+ */
+export function seatStatus() {
+  const listed = listSeatWindows(SEAT_SESSION);
+  if (!listed.available) {
+    return { schemaVersion: SEAT_STATUS_SCHEMA_VERSION, session: SEAT_SESSION, tmux: false, seats: [], reason: "tmux_unavailable" };
+  }
+  return { schemaVersion: SEAT_STATUS_SCHEMA_VERSION, session: SEAT_SESSION, tmux: true, seats: listed.windows.map(seatEntry), reason: listed.reason };
+}
+
+/**
+ * @param {{campaign?: string}} [options]
+ * @returns {{ok: boolean, available: boolean, reason: string|null, stopped: "window"|"session", stderr: string}}
+ */
+export function stopSeat(options = {}) {
+  const result = options.campaign ? stopSeatWindow(SEAT_SESSION, options.campaign) : stopSeatSession(SEAT_SESSION);
+  return { ok: result.ok, available: result.available, reason: result.reason, stopped: options.campaign ? "window" : "session", stderr: result.stderr };
+}
+
+/**
+ * Swap the harness in a campaign's seat window without touching the run. It
+ * materializes the operator brief from the campaign's durable facts, respawns
+ * the window on the new harness with that brief as its opening instruction,
+ * and returns. The controller lock, the run status and every node snapshot are
+ * never opened for writing: the brief lives under the campaign directory, and
+ * the only process this kills is the pane's.
+ *
+ * @param {{campaign?: string, harness?: string, cwd?: string}} options
+ * @returns {SeatSwitchResult}
+ */
+export function switchSeat(options) {
+  const cwd = resolve(options.cwd ?? ".");
+  const runsDir = join(cwd, ".runs");
+  let resolved;
+  try {
+    resolved = resolveCampaign(runsDir, options.campaign);
+  } catch (error) {
+    return switchFailure("campaign_not_found", options.campaign ?? null, options.harness ?? null, errorMessage(error));
+  }
+  const campaign = resolved.campaign.id;
+  const harness = options.harness;
+  if (!harness || !Object.prototype.hasOwnProperty.call(OPERATOR_HARNESSES, harness)) {
+    const known = Object.keys(OPERATOR_HARNESSES).join(", ");
+    return switchFailure("unknown_harness", campaign, harness ?? null, `unknown harness ${harness ?? "(none)"}; choose one of ${known}`);
+  }
+  const briefPath = join(resolved.path, BRIEF_FILE);
+  try {
+    const { state } = readProjectionState(resolved.path, resolved.campaign);
+    materializeBrief(resolved.path, briefFromState(resolved.campaign, state, []));
+  } catch (error) {
+    return switchFailure("brief_failed", campaign, harness, `could not write the operator brief: ${errorMessage(error)}`);
+  }
+  const argv = /** @type {string[]} */ (launchArgv(harness, `Read ${briefPath} before continuing this campaign.`));
+  const respawned = respawnSeatWindow({ session: SEAT_SESSION, window: campaign, argv, harness, cwd });
+  if (!respawned.ok) {
+    const message = respawned.available
+      ? `tmux could not respawn the seat window: ${respawned.reason ?? "tmux_command_failed"}`
+      : "tmux is not available; cannot switch the seat";
+    return { ...switchFailure(respawned.reason ?? "tmux_command_failed", campaign, harness, message), available: respawned.available, stderr: respawned.stderr };
+  }
+  return {
+    ok: true,
+    available: true,
+    reason: null,
+    session: SEAT_SESSION,
+    campaign,
+    harness,
+    window: campaign,
+    command: respawned.command,
+    brief: briefPath,
+    attachCommand: attachCommandLine(SEAT_SESSION, campaign, null),
+    stderr: "",
+    message: null,
+  };
+}
+
+/**
+ * The line to paste. `attach` must not run `tmux attach` itself: attaching
+ * from a child process nests sessions. The SSH form quotes the whole remote
+ * command so it survives the local shell.
+ *
+ * @param {string} session
+ * @param {string|null} campaign
+ * @param {string|null} ssh
+ * @returns {string}
+ */
+function attachCommandLine(session, campaign, ssh) {
+  const attach = `tmux attach -t ${campaign ? `${session}:${campaign}` : session}`;
+  return ssh ? `ssh -t ${ssh} ${JSON.stringify(attach)}` : attach;
+}
+
+/**
+ * @param {SeatWindow} window
+ * @returns {SeatStatusEntry}
+ */
+function seatEntry(window) {
+  const harness = window.harness ?? detectOperatorHarnessByCommand(window.command);
+  return {
+    campaign: window.window,
+    harness,
+    canRenderAmbient: harness ? canRenderAmbient(harness) : false,
+    command: window.command,
+    index: window.index,
+  };
+}
+
+/**
+ * @param {string} reason
+ * @param {string} campaign
+ * @param {string|null} harness
+ * @param {string} message
+ * @returns {SeatStartResult}
+ */
+function startFailure(reason, campaign, harness, message) {
+  return {
+    ok: false,
+    available: reason !== "tmux_unavailable",
+    reason,
+    session: SEAT_SESSION,
+    campaign,
+    harness,
+    window: null,
+    command: null,
+    attachCommand: null,
+    stderr: "",
+    message,
+  };
+}
+
+/**
+ * @param {string} reason
+ * @param {string|null} campaign
+ * @param {string|null} harness
+ * @param {string} message
+ * @returns {SeatSwitchResult}
+ */
+function switchFailure(reason, campaign, harness, message) {
+  return {
+    ok: false,
+    available: reason !== "tmux_unavailable",
+    reason,
+    session: SEAT_SESSION,
+    campaign,
+    harness,
+    window: null,
+    command: null,
+    brief: null,
+    attachCommand: null,
+    stderr: "",
+    message,
+  };
+}