@fcon-tech/portolan 0.4.5

package/core/src/fan-in.ts

@@ -0,0 +1,84 @@
+/**
+ * The two per-vessel facts the harbor queue and trust.report both quote, in
+ * one leaf so one definition serves both.
+ *
+ * The rank (openspec/changes/resurvey-queue/specs/harbor/spec.md, "The
+ * repair queue is fan-in ranked"): direct cross-vessel charted fan-in, ties
+ * broken by vessel id. The harbor queue orders its repair rows by it and
+ * trust.report orders its pending-vessel list by the same rank — one rank,
+ * one order (the lists themselves differ by settled design).
+ *
+ * The charge (same delta, "charged by the same attribution the staleness
+ * report uses"): per-vessel stale-entry counts, so the queue's evidence and
+ * scope name the same number the report's staleness section does.
+ *
+ * The rank is deliberately a second definition beside chart.neighborhood's,
+ * not a unification of it: the neighborhood counts every charted incoming
+ * fairway per entry, while this rank counts per vessel and excludes a
+ * vessel's fairways to itself — internal traffic says nothing about how much
+ * of the rest of the chart hangs from the vessel. The divergence is pinned
+ * by the spec; the leaf keeps exactly those two importers.
+ *
+ * Arithmetic over charted bytes only: no timestamps and no judgment
+ * participate, so two computations over an unchanged chart return the same
+ * counts and, sorted by the compare below, the same order.
+ */
+import type { ChartEntry, IndexedEntry } from "./types";
+
+/**
+ * Per-vessel direct cross-vessel charted fan-in: the count of charted
+ * fairways whose target vessel is that vessel and whose source vessel is a
+ * different one. Fairway endpoints are vessel ids — a fairway from an id
+ * with no charted vessel entry still counts, the chart is the truth, not
+ * the vessel list. A vessel with no incoming cross-vessel fairway is absent
+ * from the map and ranks zero wherever it is read.
+ */
+export function vesselFanIn(entries: ReadonlyArray<ChartEntry>): Map<string, number> {
+  const fanIn = new Map<string, number>();
+  for (const entry of entries) {
+    if (entry.kind !== "fairway") continue;
+    if (entry.from === entry.to) continue; // intra-vessel: no cross-vessel fan-in
+    fanIn.set(entry.to, (fanIn.get(entry.to) ?? 0) + 1);
+  }
+  return fanIn;
+}
+
+/**
+ * The rank order over vessel ids, as the compare the two importers sort
+ * with: fan-in descending, ties broken by vessel id ascending — the queue's
+ * voice. A count missing from the map ranks zero, so a detached vessel is
+ * ordered by the tie-break alone instead of dropping out.
+ */
+export function compareVesselRank(a: string, b: string, fanIn: Map<string, number>): number {
+  const fa = fanIn.get(a) ?? 0;
+  const fb = fanIn.get(b) ?? 0;
+  if (fa !== fb) return fb - fa;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Charge every stale entry to the pending-correction vessel(s) it hangs
+ * from, read from the index's own stale flags: a vessel entry charges its
+ * vessel, a stale fairway charges BOTH the vessels it runs between, and
+ * every other entry charges its vessel. The refresh recomputes those flags
+ * — a drifted vessel stays pending, a reverted one clears — so attribution
+ * must come from the chart as it stands now, never from a refresh delta.
+ * A pending fairway drags on both its endpoints: once drift is reverted
+ * there is no telling which endpoint moved, and over-attribution is the
+ * honest direction, so an endpoint that is itself fresh is charged too.
+ */
+export function chargeStaleEntries(entries: ReadonlyArray<IndexedEntry>): Map<string, number> {
+  const charged = new Map<string, number>();
+  for (const entry of entries) {
+    if (!entry.stale) continue;
+    const bump = (vesselId: string): void => {
+      charged.set(vesselId, (charged.get(vesselId) ?? 0) + 1);
+    };
+    if (entry.kind === "vessel") bump(entry.id);
+    else if (entry.kind === "fairway") {
+      bump(entry.from);
+      bump(entry.to);
+    } else bump(entry.vessel);
+  }
+  return charged;
+}

package/core/src/harbor/chat-format.ts

@@ -0,0 +1,154 @@
+/**
+ * The chat rendering of the proposal queue and of the night-watch report —
+ * the one format the headless CLI posts and the skill's session-start
+ * message mirrors (design.md risk: the wording lives here, with a golden
+ * test; the skill references it, not copies). Deterministic by
+ * construction: the queue in, the same text out, no timestamps. An empty
+ * queue renders to the empty string — silence on a still province. The
+ * watch report always renders: an invoked watch says what it did, even
+ * when what it did was nothing.
+ * openspec/changes/harbor-master + openspec/changes/night-watch (harbor
+ * capability: the watch report is chat-formatted and deterministic)
+ */
+import { formatAnchor } from "../types";
+import type { Proposal, ProposeResult } from "./proposals";
+import type { WatchAction, WatchReport } from "./watch";
+import type { RunReport } from "./run";
+
+function scopeLine(proposal: Proposal): string {
+  if (proposal.kind === "new-land") {
+    // Proposals carry their display path; the evidence-key parse stays only
+    // for records stored before `subject` existed (history is append-only).
+    const key = proposal.evidence[0] ?? "";
+    const path = proposal.subject ?? key.slice(key.indexOf(":") + 1);
+    return `full survey of ${path}; no charted vessels there yet`;
+  }
+  return (
+    `vessels ${proposal.scope.vessels.join(", ")} · ` +
+    `${proposal.scope.entries} entries · ${proposal.scope.soundings} soundings`
+  );
+}
+
+/** Render the queue as one postable chat message; "" when the queue is empty. */
+export function renderQueueChat(result: ProposeResult): string {
+  const { proposals } = result;
+  if (proposals.length === 0) return "";
+  const lines: string[] = [];
+  lines.push(
+    `Portolan harbor — ${proposals.length} expedition ${proposals.length === 1 ? "proposal" : "proposals"} for this province.`,
+    "",
+  );
+  for (const [index, proposal] of proposals.entries()) {
+    lines.push(`${index + 1}. ${proposal.kind} — ${proposal.summary}`);
+    lines.push(`   evidence: ${proposal.anchors.map(formatAnchor).join("; ")}`);
+    lines.push(`   scope: ${scopeLine(proposal)}`);
+  }
+  lines.push(
+    "",
+    "Accept or decline by number — one phrase is enough; the decision is recorded with expeditions.decide.",
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+/** One proposal as the report's pending entries render it: summary, evidence, scope. */
+function proposalLines(proposal: Proposal): string[] {
+  return [
+    `${proposal.kind} — ${proposal.summary}`,
+    `   evidence: ${proposal.anchors.map(formatAnchor).join("; ")}`,
+    `   scope: ${scopeLine(proposal)}`,
+  ];
+}
+
+/** The policy line: the bound, and whether anything could launch at all. */
+function watchPolicyLine(report: WatchReport): string {
+  const vessels = report.bound === 1 ? "vessel" : "vessels";
+  if (report.bound <= 0) {
+    return `policy: auto-repair bound 0 ${vessels} — report-only (harbor.auto_repair_max_vessels unset or zero)`;
+  }
+  if (report.reportOnly) {
+    return `policy: auto-repair bound ${report.bound} ${vessels} — report-only (no --launcher configured)`;
+  }
+  const command = (report.launcherCommand ?? "").trim().split(/\s+/)[0];
+  return `policy: auto-repair bound ${report.bound} ${vessels}; launcher ${command}`;
+}
+
+function ranLine(action: WatchAction): string {
+  return action.outcome === "completed"
+    ? "   outcome: completed"
+    : `   outcome: launch-failed (${action.reason})`;
+}
+
+/**
+ * Render the manual run report as one postable chat message: the proposal
+ * (kind, summary, evidence, scope), the launcher, and the outcome. Always
+ * renders; deterministic — no timestamps, no ambient state. A failure says
+ * it stays queued, like the watch report does.
+ * openspec/changes/harbor-run (harbor capability: the run report is
+ * chat-formatted and deterministic)
+ */
+export function renderRunChat(report: RunReport): string {
+  const lines: string[] = [];
+  lines.push(
+    "Portolan harbor run — one expedition by the Governor's hand.",
+    "",
+    ...proposalLines(report.proposal),
+    `launcher: ${(report.launcherCommand ?? "").trim().split(/\s+/)[0]}`,
+  );
+  if (report.outcome === "completed") {
+    lines.push("outcome: completed");
+  } else {
+    lines.push(
+      `outcome: launch-failed (${report.reason})`,
+      "note: recorded in history; the proposal stays queued for the Governor",
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** The night-watch report in chat form: what ran (with outcomes), what was
+ * left pending (with evidence summaries), and any launcher failures. Always
+ * renders — even a watch that did nothing says so. Deterministic: no
+ * timestamps, no ambient state.
+ */
+export function renderWatchChat(report: WatchReport): string {
+  const completed = report.ran.filter((a) => a.outcome === "completed");
+  const failed = report.ran.filter((a) => a.outcome === "launch-failed");
+
+  const lines: string[] = [];
+  lines.push(
+    `Portolan night watch — ${completed.length} launched, ${report.pending.length} pending, ${failed.length} failed.`,
+    "",
+    watchPolicyLine(report),
+  );
+
+  lines.push("ran:");
+  if (completed.length === 0) {
+    lines.push(
+      failed.length > 0
+        ? "none — every attempted launch failed (see launch failures)"
+        : "none"
+    );
+  }
+  for (const [index, action] of completed.entries()) {
+    lines.push(`${index + 1}. ${action.proposal.kind} — ${action.proposal.summary}`);
+    lines.push(ranLine(action));
+  }
+
+  lines.push("pending:");
+  if (report.pending.length === 0) lines.push("none");
+  for (const [index, proposal] of report.pending.entries()) {
+    for (const [lineNo, line] of proposalLines(proposal).entries()) {
+      lines.push(lineNo === 0 ? `${index + 1}. ${line}` : line);
+    }
+  }
+
+  lines.push("launch failures:");
+  if (failed.length === 0) lines.push("none");
+  for (const [index, action] of failed.entries()) {
+    lines.push(`${index + 1}. ${action.proposal.kind} — ${action.proposal.summary}`);
+    lines.push(`   failure: ${action.reason}`);
+    lines.push("   note: recorded in history; the proposal stays queued for the Governor");
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/core/src/harbor/cli.ts

@@ -0,0 +1,178 @@
+#!/usr/bin/env bun
+/**
+ * The headless Harbor Master CLI — the scheduler's entry (Portolan ships no
+ * daemon; the harbor schedule setting only documents an external cadence).
+ *
+ *   bun core/src/harbor/cli.ts propose [--target <province root>] [--format chat|json]
+ *   bun core/src/harbor/cli.ts watch [--target <province root>] [--format chat|json]
+ *                                      [--launcher "<command>"] [--launcher-timeout <duration>]
+ *   bun core/src/harbor/cli.ts run --fingerprint <fp> --launcher "<command>"
+ *                                   [--target <province root>] [--format chat|json]
+ *                                   [--launcher-timeout <duration>]
+ *
+ * `propose` computes the deterministic queue and prints it: `--format chat`
+ * is the postable chat rendering (nothing at all on an empty queue),
+ * `--format json` (the default) is the machine queue.
+ *
+ * `watch` (openspec/changes/night-watch) applies the night policy to the
+ * queue, launches what qualifies through the external launcher, records the
+ * auto-accepts (`by night-watch`) and any launch failures in the harbor
+ * history, and prints one chat-formatted watch report (`--format chat` is
+ * the default; `--format json` is the machine report). A launch failure is
+ * receipted, not fatal: the exit stays 0 so the scheduler always gets the
+ * report; the failure is named in it and appended to the history.
+ *
+ * Both commands are deterministic — two runs over an unchanged province
+ * emit identical output. Settings warnings print to stderr so stdout stays
+ * postable; any failure (no chart, corrupt settings, bad arguments) exits 1
+ * with the error on stderr.
+ * openspec/changes/harbor-master + openspec/changes/night-watch (harbor
+ * capability: scheduling is an explicit setting, off by default / the
+ * night watch acts only on invocation)
+ */
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import { renderQueueChat, renderWatchChat, renderRunChat } from "./chat-format";
+import { computeProposals } from "./proposals";
+import { readSettings } from "./settings";
+import { runWatch } from "./watch";
+import { runProposal } from "./run";
+import { DEFAULT_LAUNCHER_TIMEOUT_MS, formatDuration, parseDurationMs } from "./launcher";
+
+function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+}
+
+const USAGE = "usage: bun core/src/harbor/cli.ts <propose|watch|run> [flags] — try --help";
+
+const HELP = `Portolan harbor CLI — the scheduler's entry (no daemon).
+
+usage:
+  bun core/src/harbor/cli.ts propose [--target <province root>] [--format chat|json]
+  bun core/src/harbor/cli.ts watch [--target <province root>] [--format chat|json] \\
+                                    [--launcher "<command>"] [--launcher-timeout <duration>]
+  bun core/src/harbor/cli.ts run --fingerprint <fp> --launcher "<command>" \\
+                                 [--target <province root>] [--format chat|json] \\
+                                 [--launcher-timeout <duration>]
+
+commands:
+  propose  compute the deterministic expedition queue and print it
+  watch    apply the night policy (harbor.auto_repair_max_vessels), launch
+           what qualifies through the external launcher, record the history,
+           and print the chat-formatted watch report
+  run      launch ONE named proposal by the Governor's explicit choice —
+           any kind (repair, gap, new-land); records the acceptance
+           (by: governor) and any launch failure in the history
+
+flags:
+  --target <province root>    the province to operate on (default: working directory)
+  --format <chat|json>        output format; propose defaults to json, watch and run to chat
+  --fingerprint <fp>          run only: the proposal's fingerprint, exactly as propose returned
+  --launcher "<command>"      watch/run: the external launcher to spawn; the
+                              proposal brief arrives as JSON on stdin; absent means
+                              report-only for the watch (nothing is launched) and is a
+                              usage error for run
+  --launcher-timeout <duration>
+                              watch/run: how long one launch may run
+                              (default: ${formatDuration(DEFAULT_LAUNCHER_TIMEOUT_MS)}); e.g. 45s, 30m, 1h
+  --help                      print this help`;
+
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      target: { type: "string", default: process.cwd() },
+      format: { type: "string" },
+      fingerprint: { type: "string" },
+      launcher: { type: "string" },
+      "launcher-timeout": { type: "string" },
+      help: { type: "boolean", default: false },
+    },
+  });
+} catch (err) {
+  fail((err as Error).message);
+}
+const { values, positionals } = parsed;
+
+if (values.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const COMMANDS = ["propose", "watch", "run"] as const;
+if (positionals.length !== 1 || !(COMMANDS as readonly string[]).includes(positionals[0]!)) {
+  fail(USAGE);
+}
+const command = positionals[0] as (typeof COMMANDS)[number];
+
+// The launcher flags belong to the launching commands alone; accepting them
+// silently elsewhere would be a false promise.
+if (command === "propose" && (values.launcher !== undefined || values["launcher-timeout"] !== undefined)) {
+  fail("--launcher and --launcher-timeout belong to the watch and run commands");
+}
+
+// A manual run launches — the fingerprint is its whole identity (a missing
+// launcher is run.ts's own loud input error, the one message for the rule).
+if (command === "run") {
+  if (values.fingerprint === undefined) fail("run: --fingerprint is required — copy it from propose");
+}
+
+const format = values.format ?? (command === "propose" ? "json" : "chat");
+if (format !== "chat" && format !== "json") {
+  fail(`--format must be "chat" or "json", got ${JSON.stringify(format)}`);
+}
+
+const targetRoot = resolve(values.target as string);
+
+// The settings file is read for its warnings and the watch's auto-repair
+// bound; nothing is interpreted from harbor.schedule — the scheduler owns
+// timing. (runWatch reads the settings again for the bound itself.)
+const { warnings } = readSettings(targetRoot);
+for (const warning of warnings) console.error(warning);
+
+function parseTimeout(): number {
+  if (values["launcher-timeout"] === undefined) return DEFAULT_LAUNCHER_TIMEOUT_MS;
+  try {
+    return parseDurationMs(values["launcher-timeout"]);
+  } catch (err) {
+    return fail((err as Error).message);
+  }
+}
+
+if (command === "propose") {
+  try {
+    const result = computeProposals(targetRoot);
+    process.stdout.write(
+      format === "chat" ? renderQueueChat(result) : `${JSON.stringify(result, null, 2)}\n`,
+    );
+  } catch (err) {
+    fail(String((err as Error).message));
+  }
+} else if (command === "watch") {
+  try {
+    const report = await runWatch(targetRoot, {
+      launcher: values.launcher,
+      launcherTimeoutMs: parseTimeout(),
+    });
+    process.stdout.write(
+      format === "chat" ? renderWatchChat(report) : `${JSON.stringify(report, null, 2)}\n`,
+    );
+  } catch (err) {
+    fail(String((err as Error).message));
+  }
+} else {
+  try {
+    const report = await runProposal(targetRoot, {
+      fingerprint: values.fingerprint as string,
+      launcher: values.launcher as string,
+      launcherTimeoutMs: parseTimeout(),
+    });
+    process.stdout.write(
+      format === "chat" ? renderRunChat(report) : `${JSON.stringify(report, null, 2)}\n`,
+    );
+  } catch (err) {
+    fail(String((err as Error).message));
+  }
+}

package/core/src/harbor/errors.ts

@@ -0,0 +1,22 @@
+/**
+ * The Harbor Master's error type. One shape for every harbor rejection —
+ * corrupt snapshot/history files, unknown decision vocabulary, deciding on
+ * a fingerprint the queue does not compute — so the registry boundary can
+ * surface any of them verbatim as a tool error (same discipline as
+ * LogError / SoundingError in the tool layer).
+ * openspec/changes/harbor-master
+ */
+export class HarborError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "HarborError";
+  }
+}
+
+/** A settings file that cannot be honored as written. */
+export class SettingsError extends HarborError {
+  constructor(message: string) {
+    super(`settings: ${message}`);
+    this.name = "SettingsError";
+  }
+}

package/core/src/harbor/fingerprint.ts

@@ -0,0 +1,29 @@
+/**
+ * The proposal fingerprint: a stable identity for one expedition proposal,
+ * computed from exactly its kind and its evidence keys (design.md,
+ * decision 3). Timestamps are excluded on purpose — unchanged evidence
+ * keeps the fingerprint stable, which is what makes refusal-respect
+ * possible; drift growth or new land changes the evidence set and therefore
+ * the fingerprint, which is what reopens a declined proposal.
+ *
+ * Evidence keys are plain strings owned by the proposal engine
+ * (`vessel/<id>#<stale-entry-count>` for drift — the drift-sensitive count
+ * reopens a declined vessel when its drift changes, `vessel/<id>#<pass>`
+ * for gaps, `<kind>:<path>` for landscape entries).
+ */
+import { createHash } from "node:crypto";
+
+/** The three proposal kinds, in the order the harbor capability names them. */
+export const PROPOSAL_KINDS = ["repair", "gap", "new-land"] as const;
+
+export type ProposalKind = (typeof PROPOSAL_KINDS)[number];
+
+/**
+ * sha256 over `kind` + the sorted, deduplicated evidence keys. Order of the
+ * input keys is irrelevant — the same evidence always yields the same
+ * fingerprint; any change to the evidence set yields a different one.
+ */
+export function proposalFingerprint(kind: ProposalKind, evidenceKeys: string[]): string {
+  const keys = [...new Set(evidenceKeys)].sort();
+  return createHash("sha256").update(`${kind}\n${keys.join("\n")}`).digest("hex");
+}

package/core/src/harbor/history.ts

@@ -0,0 +1,178 @@
+/**
+ * The decision history: the Governor's accepted/declined verdicts on
+ * expedition proposals — and the night watch's records — stored append-only
+ * as JSONL under `<target>/.portolan/harbor/history.jsonl`: one line per
+ * record, same shape discipline as the ship's log (design.md, decision 4).
+ * Dedupe reads the LAST record per fingerprint, so an overturned refusal is
+ * the Governor's latest will, and nothing already written is ever altered.
+ *
+ * Night-watch records (openspec/changes/night-watch, design decision 3):
+ * an auto-executed launch appends `accepted` with `by: "night-watch"`
+ * BEFORE the launcher runs; if the launch then fails, a `launch-failed`
+ * outcome is appended after it — accept-then-append-failure keeps the audit
+ * trail honest, and because the failure is the last word on that
+ * fingerprint, a failed launch leaves the proposal not-accepted and queued.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { HarborError } from "./errors";
+import { harborDir } from "./snapshot";
+
+export const HISTORY_FILE = "history.jsonl";
+
+/** The closed decision vocabulary. */
+export const DECISIONS = ["accepted", "declined"] as const;
+
+export type GovernorDecision = (typeof DECISIONS)[number];
+
+/** Attribution the night watch writes; session decisions carry no `by`. */
+export const NIGHT_WATCH = "night-watch";
+
+/** Attribution the manual `run` command writes: the Governor's own launch. */
+export const GOVERNOR = "governor";
+
+/** Who may append a launch outcome (the closed attribution vocabulary). */
+const LAUNCH_ATTRIBUTIONS = new Set([NIGHT_WATCH, GOVERNOR]);
+
+/** One recorded decision; `decidedAt` is ISO, like a receipt's `recordedAt`. */
+export interface DecisionRecord {
+  fingerprint: string;
+  decision: GovernorDecision;
+  decidedAt: string;
+  /** Who decided; absent = the Governor in session, `night-watch` = the night watch. */
+  by?: string;
+}
+
+/**
+ * A launch outcome: appended after a night-watch acceptance when the
+ * external launcher failed (non-zero exit, timeout, or spawn failure). The
+ * failed proposal stays queued — the queue filters on `declined` only.
+ */
+export interface LaunchOutcomeRecord {
+  fingerprint: string;
+  outcome: "launch-failed";
+  recordedAt: string;
+  /** Who launched: the night watch or the Governor's manual run. */
+  by: string;
+  /** Deterministic reason: exit status, timeout, or spawn failure. */
+  reason: string;
+}
+
+/** Any record the history file may hold. */
+export type HistoryRecord = DecisionRecord | LaunchOutcomeRecord;
+
+/** Where the decision history lives. */
+export function historyFile(targetRoot: string): string {
+  return join(harborDir(targetRoot), HISTORY_FILE);
+}
+
+function isDecision(record: HistoryRecord): record is DecisionRecord {
+  return (record as DecisionRecord).decision !== undefined;
+}
+
+function parseLine(line: string, file: string, lineNo: number): HistoryRecord {
+  let record: HistoryRecord;
+  try {
+    record = JSON.parse(line) as HistoryRecord;
+    if (isDecision(record)) {
+      if (
+        typeof record?.fingerprint !== "string" ||
+        (record.decision !== "accepted" && record.decision !== "declined") ||
+        typeof record?.decidedAt !== "string" ||
+        (record.by !== undefined && typeof record.by !== "string")
+      ) {
+        throw new Error("not a decision");
+      }
+    } else if (
+      record?.outcome !== "launch-failed" ||
+      typeof record?.fingerprint !== "string" ||
+      typeof record?.recordedAt !== "string" ||
+      typeof record?.by !== "string" ||
+      typeof record?.reason !== "string" ||
+      record.reason.length === 0
+    ) {
+      throw new Error("not a launch outcome");
+    }
+    return record;
+  } catch (err) {
+    const why = err instanceof Error ? err.message : "not a decision";
+    throw new HarborError(`history: corrupt decision history ${file} line ${lineNo}: ${why}`);
+  }
+}
+
+/** Every recorded history row, oldest first. Empty when no history exists. */
+export function readHistory(targetRoot: string): HistoryRecord[] {
+  const file = historyFile(targetRoot);
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line, index) => parseLine(line, file, index + 1));
+}
+
+/** Every recorded Governor/night-watch decision (launch outcomes excluded), oldest first. */
+export function readDecisions(targetRoot: string): DecisionRecord[] {
+  return readHistory(targetRoot).filter(isDecision);
+}
+
+/** The last decision per fingerprint — a map where the latest will wins. */
+export function lastDecisionPerFingerprint(records: DecisionRecord[]): Map<string, DecisionRecord> {
+  const last = new Map<string, DecisionRecord>();
+  for (const record of records) last.set(record.fingerprint, record);
+  return last;
+}
+
+/** The last record of any kind per fingerprint — the latest word wins. */
+export function lastRecordPerFingerprint(records: HistoryRecord[]): Map<string, HistoryRecord> {
+  const last = new Map<string, HistoryRecord>();
+  for (const record of records) last.set(record.fingerprint, record);
+  return last;
+}
+
+/** Append one decision; returns the record as stored. Never rewrites a line. */
+export function appendDecision(
+  targetRoot: string,
+  fingerprint: string,
+  decision: GovernorDecision,
+  options: { by?: string } = {},
+): DecisionRecord {
+  if ((DECISIONS as readonly string[]).includes(decision) === false) {
+    throw new HarborError(
+      `history: unknown decision ${JSON.stringify(decision)}; the vocabulary is ${DECISIONS.join(", ")}`,
+    );
+  }
+  const record: DecisionRecord = { fingerprint, decision, decidedAt: new Date().toISOString() };
+  if (options.by !== undefined) record.by = options.by;
+  mkdirSync(harborDir(targetRoot), { recursive: true });
+  appendFileSync(historyFile(targetRoot), `${JSON.stringify(record)}\n`);
+  return record;
+}
+
+/**
+ * Append a launch failure, attributed to the night watch by default or to
+ * the Governor's manual `run` when `{ by: "governor" }`; the deterministic
+ * `reason` names the failure for the history reader and the report alike.
+ */
+export function appendLaunchFailure(
+  targetRoot: string,
+  fingerprint: string,
+  reason: string,
+  options: { by?: string } = {},
+): LaunchOutcomeRecord {
+  const by = options.by ?? NIGHT_WATCH;
+  if (!LAUNCH_ATTRIBUTIONS.has(by)) {
+    throw new HarborError(
+      `history: launch outcome attribution must be ${NIGHT_WATCH} or ${GOVERNOR}, got ${JSON.stringify(by)}`,
+    );
+  }
+  const record: LaunchOutcomeRecord = {
+    fingerprint,
+    outcome: "launch-failed",
+    recordedAt: new Date().toISOString(),
+    by,
+    reason,
+  };
+  mkdirSync(harborDir(targetRoot), { recursive: true });
+  appendFileSync(historyFile(targetRoot), `${JSON.stringify(record)}\n`);
+  return record;
+}