@fcon-tech/portolan 0.4.5

package/core/src/harbor/launcher.ts

@@ -0,0 +1,155 @@
+/**
+ * The external expedition launcher (night-watch design.md, decision 2):
+ * the watch never names a harness — it spawns whatever command the operator
+ * passed as `--launcher "<cmd>"`, feeds the expedition brief
+ * (`{ target, proposal }`) as JSON on stdin, and caps the run with
+ * `--launcher-timeout` (default 30m).
+ *
+ * Contract: exit 0 = the expedition completed; non-zero exit, timeout, or
+ * spawn failure = the failure path (the caller records it in the harbor
+ * history and names it in the report). The launcher's stdout is consumed
+ * and discarded (it must never pollute the watch's postable report); its
+ * stderr is forwarded to the watch's stderr so a stuck launcher is visible
+ * in the scheduler's mail without breaking stdout determinism.
+ *
+ * No core module is named here and none is imported by launchers — the
+ * adapter boundary (core/src/server/adapter-boundary.ts) holds both ways.
+ * openspec/changes/night-watch (harbor capability: the launcher is
+ * external and swappable)
+ */
+import { spawn } from "node:child_process";
+import type { Proposal } from "./proposals";
+
+/** What one launch is told: the province and the proposal to execute. */
+export interface LaunchBrief {
+  /** The province root the expedition runs against. */
+  target: string;
+  /** The proposal the night watch auto-accepted, exactly as computed. */
+  proposal: Proposal;
+}
+
+/** The brief one launch receives on stdin: exactly the province and the proposal. */
+export function briefFor(targetRoot: string, proposal: Proposal): LaunchBrief {
+  return { target: targetRoot, proposal };
+}
+
+/** How one launch ended. `reason` is deterministic (status, timeout, spawn error). */
+export interface LaunchResult {
+  ok: boolean;
+  reason?: string;
+}
+
+/** The default per-launch timeout: 30 minutes (design.md, decision 2). */
+export const DEFAULT_LAUNCHER_TIMEOUT_MS = 30 * 60 * 1000;
+
+/**
+ * Split a launcher command string into argv, honoring double and single
+ * quotes so a path with spaces survives: `bash "/path/with spaces/x.sh"`
+ * → `["bash", "/path/with spaces/x.sh"]`.
+ */
+export function splitCommand(command: string): string[] {
+  const argv: string[] = [];
+  for (const match of command.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
+    argv.push(match[1] ?? match[2] ?? match[3] ?? "");
+  }
+  return argv;
+}
+
+/**
+ * Parse a `--launcher-timeout` duration: `<n>ms`, `<n>s`, `<n>m`, `<n>h`,
+ * or a bare number (seconds). Throws on anything else — a silently wrong
+ * timeout is a silently unbounded launcher.
+ */
+export function parseDurationMs(value: string): number {
+  const match = /^(.+?)(ms|s|m|h)?$/.exec(value.trim());
+  const amount = match === null ? NaN : Number(match[1]);
+  if (match === null || !Number.isFinite(amount) || amount <= 0) {
+    throw new Error(`--launcher-timeout must be a positive duration like 45s, 30m or 1h, got ${JSON.stringify(value)}`);
+  }
+  const unit = match[2] ?? "s";
+  const factor = unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : 3_600_000;
+  return Math.round(amount * factor);
+}
+
+/** Render a millisecond duration compactly and deterministically: 250ms, 30m, 1h. */
+export function formatDuration(ms: number): string {
+  if (ms % 3_600_000 === 0) return `${ms / 3_600_000}h`;
+  if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+  if (ms % 1000 === 0) return `${ms / 1000}s`;
+  return `${ms}ms`;
+}
+
+/**
+ * Launch one expedition through the external launcher: spawn the command,
+ * write the brief as JSON on stdin, wait for exit, and kill the launcher
+ * (SIGKILL — a stuck launcher forfeits cleanup) once the timeout burns.
+ * Never throws: every failure is a `{ ok: false, reason }` return.
+ */
+export function launchExpedition(options: {
+  launcher: string;
+  brief: LaunchBrief;
+  timeoutMs: number;
+}): Promise<LaunchResult> {
+  const argv = splitCommand(options.launcher);
+  if (argv.length === 0 || argv[0].length === 0) {
+    return Promise.resolve({ ok: false, reason: "no launcher command given" });
+  }
+
+  return new Promise<LaunchResult>((resolve) => {
+    let child;
+    try {
+      // detached: the launcher leads its own process group, so a timeout can
+      // kill the whole tree — a grandchild holding the stdio pipes would
+      // otherwise outlive the cap and hang the watch.
+      child = spawn(argv[0], argv.slice(1), { stdio: ["pipe", "pipe", "pipe"], detached: true });
+    } catch (err) {
+      resolve({ ok: false, reason: `launcher could not be spawned: ${(err as Error).message}` });
+      return;
+    }
+
+    let settled = false;
+    let timedOut = false;
+    const killTree = (): void => {
+      try {
+        process.kill(-child.pid!, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL"); // the group is gone or unsupported; the child alone then
+      }
+    };
+    const settle = (result: LaunchResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree();
+    }, options.timeoutMs);
+
+    child.on("error", (err) => {
+      settle({ ok: false, reason: `launcher could not be spawned: ${err.message}` });
+    });
+    child.on("close", (code, signal) => {
+      if (code === 0) {
+        settle({ ok: true });
+      } else if (code !== null) {
+        settle({ ok: false, reason: `launcher exited with status ${code}` });
+      } else if (timedOut) {
+        settle({ ok: false, reason: `launcher timed out after ${formatDuration(options.timeoutMs)} and was killed` });
+      } else {
+        settle({ ok: false, reason: `launcher was killed by signal ${signal ?? "unknown"}` });
+      }
+    });
+
+    // The launcher's stdout must be consumed (a full pipe would deadlock the
+    // child) but is never part of the watch report.
+    child.stdout?.on("data", () => {});
+    // Launcher stderr is forwarded so schedulers see it; it never touches stdout.
+    child.stderr?.on("data", (chunk: Buffer) => process.stderr.write(chunk));
+
+    child.stdin.on("error", () => {}); // a launcher that exits before reading stdin is not a spawn bug
+    child.stdin.write(`${JSON.stringify(options.brief)}\n`);
+    child.stdin.end();
+  });
+}

package/core/src/harbor/night-policy.ts

@@ -0,0 +1,64 @@
+/**
+ * The night policy (night-watch design.md, decision 1; the bound is
+ * cumulative since openspec/changes/resurvey-queue, design decision "The
+ * night bound becomes cumulative"): which of the standing queue's proposals
+ * the night watch may auto-execute. The entire policy is one bound —
+ * `harbor.auto_repair_max_vessels` — and one rule with no exceptions:
+ *
+ *   walking the queue in order, a `repair` row launches iff the bound is
+ *   present and positive and its scope's vessels still fit in what remains
+ *   of the bound; each launch spends its scope's vessel count, and
+ *   everything past the bound stays pending.
+ *
+ * The bound is spent cumulatively, not per row: after the per-vessel split
+ * every repair row holds exactly one vessel, so any positive bound would
+ * pass every row and "bounded" would bound nothing. Whether a launch
+ * attempt refunds its share on failure is the watch's question
+ * (watch.ts, accept-then-append-failure) — not answered here: this policy
+ * is pure and knows nothing of outcomes.
+ *
+ * `new-land` and `gap` proposals are NEVER auto-executed, regardless of the
+ * bound — the night watch repairs known coast, it does not explore. Absent,
+ * zero, or negative bound means report-only: everything is pending.
+ *
+ * Pure by construction: proposals and a number in, two lists out, queue
+ * order preserved in both. No filesystem, no clock, no harness.
+ * openspec/changes/night-watch (harbor capability: auto-repair is bounded
+ * and never curious)
+ */
+import type { Proposal } from "./proposals";
+
+/** What the night policy decided: what may launch, what stays with the Governor. */
+export interface NightPolicyResult {
+  /** Repair proposals within the bound, in queue order — the watch may launch these. */
+  launch: Proposal[];
+  /** Everything else, in queue order — left pending for the Governor's decision. */
+  pending: Proposal[];
+}
+
+/**
+ * Apply the night policy to a computed queue. `bound` is the effective
+ * `harbor.auto_repair_max_vessels` (absent = 0): 0 or negative means
+ * report-only.
+ */
+export function nightPolicy(proposals: Proposal[], bound: number): NightPolicyResult {
+  const launch: Proposal[] = [];
+  const pending: Proposal[] = [];
+  // A row's cost is its scope's vessel count: one per served per-vessel
+  // repair row — no grouped shape is served today, and the sum keeps the
+  // policy honest if one ever returns (night-policy.test.ts pins the cost
+  // model). A misfit row does not stop the walk: a later smaller row may
+  // still fit, and the misfit stays pending for the Governor either way.
+  let spent = 0;
+  for (const proposal of proposals) {
+    const cost = proposal.scope.vessels.length;
+    const launches = proposal.kind === "repair" && bound > 0 && spent + cost <= bound;
+    if (launches) {
+      launch.push(proposal);
+      spent += cost;
+    } else {
+      pending.push(proposal);
+    }
+  }
+  return { launch, pending };
+}

package/core/src/harbor/proposals.ts

@@ -0,0 +1,324 @@
+/**
+ * The proposal engine: the deterministic Harbor Master. The queue is
+ * computed from exactly three inputs — never imagined (the trust spine
+ * forbids model-invented proposals):
+ *
+ * 1. repair   — one proposal per vessel marked `pending correction`; the
+ *               row names that vessel alone (staleness refresh runs first,
+ *               exactly like `chart.read`);
+ * 2. gap      — per charted vessel with no recorded behavior and/or no
+ *               charted light (both signals read from the index, never from
+ *               parsed sheets — design.md, decision 1);
+ * 3. new-land — landscape entries absent from the last-survey snapshot,
+ *               compared only while the chart index hash is unchanged.
+ *
+ * Ranking: repair rows order among themselves by the shared rank — direct
+ * cross-vessel charted fan-in, ties by vessel id (../fan-in.ts) — before
+ * the kind rank resolves against new-land and gap: repair > new-land > gap,
+ * then evidence size, then evidence key (design.md, decision 6). Every
+ * proposal carries its kind, evidence keys, anchors, a scope estimate, and
+ * a stable fingerprint; fingerprints whose LAST recorded decision is
+ * declined are filtered — a refusal holds while that vessel's drift is
+ * unchanged and reopens when its stale-entry count changes.
+ *
+ * Anchor honesty on repair: the per-vessel tree signature hashes the file
+ * list, sizes, and mtimes, so individual changed files are not recoverable
+ * without storing per-file state. Repair anchors therefore cite a soundable
+ * regular file under each drifted vessel's charted paths — `sound.anchor`
+ * refutes any non-regular file, so citing the directory itself would refute
+ * true drift at the very first sounding of the brief the Cartographer was
+ * handed (the new-land precedent: landscapeAnchor cites the manifest or
+ * `.git` marker for the same reason).
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Anchor, IndexedEntry, VesselEntry } from "../types";
+import { resolveInsideTarget } from "../perimeter";
+import { readChart } from "../chart-store";
+import { refreshStaleness } from "../staleness";
+import { chargeStaleEntries, compareVesselRank, vesselFanIn } from "../fan-in";
+import { HarborError } from "./errors";
+import { PROPOSAL_KINDS, proposalFingerprint, type ProposalKind } from "./fingerprint";
+import {
+  DECISIONS,
+  appendDecision,
+  lastRecordPerFingerprint,
+  readHistory,
+  type DecisionRecord,
+  type GovernorDecision,
+} from "./history";
+import {
+  chartIndexHash,
+  landscapeAnchor,
+  readSnapshot,
+  scanLandscape,
+  writeSnapshot,
+  type LandscapeEntry,
+} from "./snapshot";
+
+/** The scope estimate every proposal carries: who and what an expedition touches. */
+export interface ProposalScope {
+  /** Charted vessel ids affected; empty for new land (nothing charted there yet). */
+  vessels: string[];
+  /** Estimated chart entries the expedition would touch. */
+  entries: number;
+  /** Estimated soundings (one per entry the verify loop re-sounds). */
+  soundings: number;
+}
+
+/** One expedition proposal, evidence-complete and fingerprinted. */
+export interface Proposal {
+  kind: ProposalKind;
+  fingerprint: string;
+  /** One deterministic sentence: what justifies the proposal. */
+  summary: string;
+  /** The fingerprint's evidence keys (`vessel/api`, `repo:vendor/lib`, ...). */
+  evidence: string[];
+  /** The display path the proposal is about, when it has one (new-land). */
+  subject?: string;
+  /** Anchors justifying the proposal, citable and soundable. */
+  anchors: Anchor[];
+  scope: ProposalScope;
+}
+
+/** What `expeditions.propose` returns: the ranked, refusal-filtered queue. */
+export interface ProposeResult {
+  proposals: Proposal[];
+}
+
+const KIND_RANK: Record<ProposalKind, number> = { repair: 0, "new-land": 1, gap: 2 };
+
+/** A vessel as read from the index: store metadata included. */
+type IndexedVessel = VesselEntry & { stale: boolean };
+
+function sortById<T extends { id: string }>(entries: T[]): T[] {
+  return [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+function uniqueAnchors(anchors: Anchor[]): Anchor[] {
+  const seen = new Set<string>();
+  const out: Anchor[] = [];
+  for (const anchor of anchors) {
+    const key = JSON.stringify(anchor);
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(anchor);
+    }
+  }
+  return out;
+}
+
+/**
+ * A soundable regular file under the given charted path, for repair anchors:
+ * the first file in sorted, hidden/node_modules-skipping walk order, so the
+ * anchor is deterministic. Undefined when the path escapes the province or
+ * holds no regular file — an unsoundable citation is dropped, never faked.
+ */
+function soundableAnchorUnder(targetRoot: string, rel: string): Anchor | undefined {
+  const stack = [rel.replace(/\/+$/, "")];
+  while (stack.length > 0) {
+    const current = stack.shift()!;
+    if (current.length === 0) continue;
+    if (resolveInsideTarget(targetRoot, current) === undefined) continue;
+    let stats;
+    try {
+      stats = statSync(join(targetRoot, current));
+    } catch {
+      continue; // a path that no longer exists contributes nothing
+    }
+    if (stats.isFile()) return { type: "file", path: current };
+    if (!stats.isDirectory()) continue;
+    let names: string[];
+    try {
+      names = readdirSync(join(targetRoot, current), { withFileTypes: true })
+        .filter((de) => de.isFile() || (de.isDirectory() && !de.name.startsWith(".") && de.name !== "node_modules"))
+        .map((de) => de.name)
+        .sort();
+    } catch {
+      continue;
+    }
+    for (const name of names) stack.push(current === "." ? name : `${current}/${name}`);
+  }
+  return undefined;
+}
+
+/**
+ * Repair proposals: one per pending-correction vessel, in vessel-id order
+ * (the queue sort below applies the shared fan-in rank). The evidence key
+ * carries the stale-entry count charged to that vessel (../fan-in.ts, the
+ * report's own attribution rule), so a refusal holds while the drift is
+ * unchanged and reopens when the count changes.
+ */
+function repairProposals(targetRoot: string, entries: IndexedEntry[]): Proposal[] {
+  const charged = chargeStaleEntries(entries);
+  return sortById(
+    entries.filter((e): e is IndexedVessel => e.kind === "vessel" && e.stale === true),
+  ).map((vessel) => {
+    const staleEntries = charged.get(vessel.id) ?? 0;
+    const evidence = [`vessel/${vessel.id}#${staleEntries}`];
+    return {
+      kind: "repair" as const,
+      fingerprint: proposalFingerprint("repair", evidence),
+      summary:
+        `vessel ${vessel.id} marked pending correction ` +
+        `(sources changed under ${vessel.paths.join(", ")})`,
+      evidence,
+      // A vessel whose charted paths hold no soundable regular file is
+      // proposed with its anchor omitted, never faked (the new-land precedent).
+      anchors: uniqueAnchors(
+        vessel.paths
+          .map((path) => soundableAnchorUnder(targetRoot, path))
+          .filter((anchor): anchor is Anchor => anchor !== undefined),
+      ),
+      scope: { vessels: [vessel.id], entries: staleEntries, soundings: staleEntries },
+    };
+  });
+}
+
+/** Gap proposals: one per charted vessel missing its behavior and/or its lights. */
+function gapProposals(entries: IndexedEntry[]): Proposal[] {
+  const lightsPerVessel = new Map<string, number>();
+  for (const entry of entries) {
+    if (entry.kind === "light") {
+      lightsPerVessel.set(entry.vessel, (lightsPerVessel.get(entry.vessel) ?? 0) + 1);
+    }
+  }
+  const proposals: Proposal[] = [];
+  for (const vessel of sortById(entries.filter((e): e is IndexedVessel => e.kind === "vessel"))) {
+    const missing: string[] = [];
+    if (vessel.behavior === undefined || vessel.behavior.trim().length === 0) missing.push("behavior");
+    if ((lightsPerVessel.get(vessel.id) ?? 0) === 0) missing.push("lights");
+    if (missing.length === 0) continue;
+    const phrases = missing.map((pass) =>
+      pass === "behavior" ? "no recorded behavior" : "no charted light",
+    );
+    proposals.push({
+      kind: "gap",
+      fingerprint: proposalFingerprint("gap", missing.map((pass) => `vessel/${vessel.id}#${pass}`)),
+      summary: `vessel ${vessel.id} (${vessel.paths.join(", ")}) has ${phrases.join(" and ")}`,
+      evidence: missing.map((pass) => `vessel/${vessel.id}#${pass}`),
+      anchors: vessel.anchors,
+      scope: { vessels: [vessel.id], entries: missing.length, soundings: missing.length },
+    });
+  }
+  return proposals;
+}
+
+/** New-land proposals: landscape present now but absent from the last-survey snapshot. */
+function newLandProposals(targetRoot: string, absent: LandscapeEntry[]): Proposal[] {
+  return absent.map((entry) => {
+    const evidence = [`${entry.kind}:${entry.path}`];
+    return {
+      kind: "new-land" as const,
+      fingerprint: proposalFingerprint("new-land", evidence),
+      summary:
+        `${entry.kind === "repo" ? "repository" : "manifest"} ${entry.path} is present in the province ` +
+        "but absent from the last-survey snapshot",
+      evidence,
+      subject: entry.path,
+      anchors: [landscapeAnchor(targetRoot, entry)],
+      scope: { vessels: [], entries: 0, soundings: 0 },
+    };
+  });
+}
+
+/**
+ * `expeditions.propose`: compute the ranked queue. Refreshes staleness
+ * first (chart.read semantics), lazily establishes or refreshes the
+ * landscape snapshot, and filters fingerprints whose last decision is
+ * declined. Purely deterministic: no timestamps participate, so two runs
+ * over an unchanged province return the same queue.
+ */
+export function computeProposals(
+  targetRoot: string,
+  options: { includeDeclined?: boolean } = {},
+): ProposeResult {
+  refreshStaleness(targetRoot);
+  const entries = readChart(targetRoot);
+
+  // Landscape vs snapshot. Snapshot first established on a chart with none:
+  // the baseline, and no new-land — there is no earlier survey to differ
+  // from. Index hash changed since the snapshot: a survey stood, refresh to
+  // the current landscape. Hash unchanged: compare, and propose the absent.
+  const stored = readSnapshot(targetRoot);
+  const currentHash = chartIndexHash(targetRoot);
+  let newLand: LandscapeEntry[] = [];
+  if (stored === null) {
+    writeSnapshot(targetRoot, { indexHash: currentHash, landscape: scanLandscape(targetRoot) });
+  } else if (stored.indexHash === currentHash) {
+    const known = new Set(stored.landscape.map((e) => `${e.kind}:${e.path}`));
+    newLand = scanLandscape(targetRoot).filter((e) => !known.has(`${e.kind}:${e.path}`));
+  } else {
+    writeSnapshot(targetRoot, { indexHash: currentHash, landscape: scanLandscape(targetRoot) });
+  }
+
+  const fanIn = vesselFanIn(entries);
+  const proposals: Proposal[] = [
+    ...repairProposals(targetRoot, entries),
+    ...newLandProposals(targetRoot, newLand),
+    ...gapProposals(entries),
+  ];
+  proposals.sort((a, b) => {
+    // Repair rows order among themselves by the shared rank — fan-in
+    // descending, vessel id ascending, the row's single vessel compared —
+    // before the kind rank resolves against new-land and gap.
+    if (a.kind === "repair" && b.kind === "repair") {
+      return compareVesselRank(a.scope.vessels[0], b.scope.vessels[0], fanIn);
+    }
+    return (
+      KIND_RANK[a.kind] - KIND_RANK[b.kind] ||
+      b.evidence.length - a.evidence.length ||
+      (a.evidence[0] < b.evidence[0] ? -1 : a.evidence[0] > b.evidence[0] ? 1 : 0)
+    );
+  });
+
+  if (options.includeDeclined === true) return { proposals };
+  // Refusal filtering keys on `declined` only (the standing rule): an
+  // acceptance — Governor's or night-watch's — never filters, and neither
+  // does a night-watch `launch-failed` outcome, so a failed launch leaves
+  // the proposal queued for retry or the Governor's decision. The LAST
+  // record of any kind is the latest word on the fingerprint.
+  const declined = new Set(
+    [...lastRecordPerFingerprint(readHistory(targetRoot)).values()]
+      .filter(
+        (record): record is DecisionRecord =>
+          "decision" in record && record.decision === "declined",
+      )
+      .map((record) => record.fingerprint),
+  );
+  return { proposals: proposals.filter((p) => !declined.has(p.fingerprint)) };
+}
+
+/**
+ * `expeditions.decide`: record the Governor's decision on a proposal the
+ * queue currently computes (declined proposals stay computable — the
+ * Governor may overturn a refusal while the evidence is unchanged). An
+ * unknown fingerprint is rejected: deciding on a proposal that does not
+ * exist would write an unverifiable row into the history.
+ */
+export function decide(
+  targetRoot: string,
+  fingerprint: string,
+  decision: GovernorDecision,
+): DecisionRecord {
+  if ((DECISIONS as readonly string[]).includes(decision) === false) {
+    throw new HarborError(
+      `unknown decision ${JSON.stringify(decision)}; the vocabulary is ${DECISIONS.join(", ")}`,
+    );
+  }
+  if (fingerprint.length === 0) {
+    throw new HarborError(
+      "a decision needs the proposal's fingerprint, exactly as expeditions.propose returned it",
+    );
+  }
+  const computable = computeProposals(targetRoot, { includeDeclined: true });
+  if (!computable.proposals.some((p) => p.fingerprint === fingerprint)) {
+    throw new HarborError(
+      `unknown proposal fingerprint ${fingerprint}; decide on a proposal the queue currently computes ` +
+        "(call expeditions.propose first)",
+    );
+  }
+  return appendDecision(targetRoot, fingerprint, decision);
+}
+
+export { PROPOSAL_KINDS };

package/core/src/harbor/run.ts

@@ -0,0 +1,72 @@
+/**
+ * The manual single-proposal run (openspec/changes/harbor-run): the
+ * Governor names one fingerprint from the computed queue and launches
+ * exactly that expedition through the external launcher — any kind
+ * (repair, gap, new-land), because the Governor's explicit choice
+ * overrides the night policy bounds while the policy itself stands.
+ *
+ * History semantics mirror the watch (accept-then-append-failure): the
+ * launch is accepted `by: governor` before spawning; a launcher failure
+ * appends `launch-failed` — the latest word — leaving the proposal
+ * effectively not-accepted and queued. A launcher is required (a
+ * report-only run is a contradiction); an unknown fingerprint is a loud
+ * input error that writes nothing.
+ */
+import { computeProposals, type Proposal } from "./proposals";
+import { briefFor, launchExpedition, DEFAULT_LAUNCHER_TIMEOUT_MS } from "./launcher";
+import { appendDecision, appendLaunchFailure, GOVERNOR } from "./history";
+import { HarborError } from "./errors";
+
+export interface RunOptions {
+  /** The fingerprint to launch, exactly as expeditions.propose returned it. */
+  fingerprint: string;
+  /** The external launcher command (argv template); required — no report-only run. */
+  launcher: string;
+  /** Per-launch timeout in milliseconds; default 30m. */
+  launcherTimeoutMs?: number;
+}
+
+/** The run report: the one proposal, and how its launch ended. */
+export interface RunReport {
+  proposal: Proposal;
+  outcome: "completed" | "launch-failed";
+  /** Deterministic failure reason; present iff launch-failed. */
+  reason?: string;
+  /** The launcher command the run used. */
+  launcherCommand: string;
+}
+
+/**
+ * Launch one named proposal. Throws HarborError for input faults (unknown
+ * fingerprint, missing launcher) BEFORE writing any history; a launcher
+ * failure is an outcome (recorded, named in the report), never a throw.
+ */
+export async function runProposal(targetRoot: string, options: RunOptions): Promise<RunReport> {
+  if (typeof options.launcher !== "string" || options.launcher.length === 0) {
+    throw new HarborError("run: --launcher is required — a manual run launches; use propose to list");
+  }
+  const { proposals } = computeProposals(targetRoot);
+  const proposal = proposals.find((p) => p.fingerprint === options.fingerprint);
+  if (proposal === undefined) {
+    throw new HarborError(
+      `run: fingerprint ${options.fingerprint} names no proposal in the current queue — run propose and copy the fingerprint exactly`,
+    );
+  }
+
+  appendDecision(targetRoot, proposal.fingerprint, "accepted", { by: GOVERNOR });
+  const result = await launchExpedition({
+    launcher: options.launcher,
+    brief: briefFor(targetRoot, proposal),
+    timeoutMs: options.launcherTimeoutMs ?? DEFAULT_LAUNCHER_TIMEOUT_MS,
+  });
+  if (result.ok) {
+    return { proposal, outcome: "completed", launcherCommand: options.launcher };
+  }
+  appendLaunchFailure(targetRoot, proposal.fingerprint, result.reason as string, { by: GOVERNOR });
+  return {
+    proposal,
+    outcome: "launch-failed",
+    reason: result.reason,
+    launcherCommand: options.launcher,
+  };
+}