@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/tui/companionplan.ts

@@ -0,0 +1,247 @@
+// The companion the host wrapper runs for a containerised TUI.
+//
+// `qcr tui` in a container has no docker.sock. So the wrapper (scripts/qcr-host.sh,
+// plain sh on the host) starts the companion container itself, and a second
+// container runs the TUI. The wrapper does not know the companion's mounts: the
+// image does, in `CompanionLifecycle`. `qcr companion plan` prints them as text
+// lines the wrapper reads, so the sh side holds no copy of the mount list that
+// could drift from the one tests pin:
+//
+//   name <container>     the companion container's name
+//   plan <hash>          fingerprint of the run argv; the container carries it
+//                        as a label, and a different one means a recreate
+//                        (mount drift, a new image, a new flag)
+//   mkdir <path>         a host dir to create as the caller before docker runs
+//                        (docker would invent it root-owned)
+//   tui-mount <path>     a host dir the TUI container mounts at its own path
+//   tui-volume <v>:<dst> a named volume the TUI container mounts (the tmux socket)
+//   tui-env <NAME=value> an env var for the TUI container
+//   run <arg>            one argument of `docker run`, in order
+//
+// Every path is the host's own, and the TUI container mounts what it shares
+// with the companion at the same path, so the config both derive from the same
+// env resolves identically on either side.
+//
+// The companion's ssh access (rule 8: full ssh) is
+// the three sources the wrapper found on the host and named in `HOST_SSH_ENV`
+// (agent socket, ssh config, known_hosts), mounted read-only by the plan. What
+// the plan never contains: ~/.ssh whole, a private key, docker.sock.
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join } from "node:path";
+import { COMPANION_DEFAULTS, type CompanionConfig } from "../config.js";
+import { operatorStateHome } from "../install.js";
+import {
+  CompanionLifecycle,
+  CONTAINER,
+  HOST_SSH_ENV,
+  companionInjectDir,
+  tmuxVolume,
+  type CompanionFs,
+  type DockerRunner,
+} from "./companion.js";
+
+/** The host's own paths, handed to both containers by the wrapper. */
+export const HOST_ENV_NAMES = [
+  "QCR_HOST_HOME",
+  "QCR_HOST_XDG_CONFIG_HOME",
+  "QCR_HOST_XDG_STATE_HOME",
+] as const;
+
+/** The wrapper-run companion has a name and a pi home of its own, so it never
+ * adopts, recreates or shares a login with a clone-route companion on the same
+ * machine (the owner's dev TUI, `qcr companion up`). */
+export const LAPTOP_COMPANION = {
+  container_name: "qcr-tui-companion",
+  pihome_volume: "qcr-companion-pihome",
+} as const;
+
+function absolute(name: string, value: string | undefined): string {
+  const v = (value ?? "").trim();
+  if (v === "" || !isAbsolute(v) || /[\n\r]/.test(v))
+    throw new Error(`${name} must be an absolute path on one line (got ${JSON.stringify(value)})`);
+  return v;
+}
+
+/**
+ * The install env both containers derive their paths from: the host's HOME and
+ * XDG dirs, with the config home at `<xdg config>/qcr` (so `profiles/` is the
+ * ruled `~/.config/qcr/profiles`) and the state home beside the host's
+ * other qcr state. Never the container's own HOME. `QCR_CONFIG` passes through:
+ * it names the config the TUI reads, and the companion's mirror is a copy of it.
+ */
+export function laptopInstallEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const home = absolute("QCR_HOST_HOME", env["QCR_HOST_HOME"]);
+  const xdgConfig = (env["QCR_HOST_XDG_CONFIG_HOME"] ?? "").trim() || join(home, ".config");
+  const xdgState = (env["QCR_HOST_XDG_STATE_HOME"] ?? "").trim() || join(home, ".local", "state");
+  absolute("QCR_HOST_XDG_CONFIG_HOME", xdgConfig);
+  absolute("QCR_HOST_XDG_STATE_HOME", xdgState);
+  return {
+    HOME: home,
+    XDG_CONFIG_HOME: xdgConfig,
+    XDG_STATE_HOME: xdgState,
+    QCR_CONFIG_HOME: join(xdgConfig, "qcr"),
+    QCR_STATE_HOME: join(xdgState, "qcr", "home"),
+    ...(env["QCR_INSTALL"] ? { QCR_INSTALL: env["QCR_INSTALL"] } : {}),
+    ...(env["QCR_CONFIG"] ? { QCR_CONFIG: env["QCR_CONFIG"] } : {}),
+    // The host's ssh sources the wrapper found (rule 8), for the plan's mounts.
+    ...Object.fromEntries(
+      Object.values(HOST_SSH_ENV)
+        .filter((name) => (env[name] ?? "").trim() !== "")
+        .map((name) => [name, env[name]]),
+    ),
+  };
+}
+
+/**
+ * The `[companion]` section of the wrapper-run companion: the channels
+ * (`feed`, `alerts`, `evidence`, the workspace the inject dir lives in) are
+ * host dirs under the operator state home, which no container mounts whole.
+ * No tracker and no reviewed repo: under-equipped, never broken.
+ */
+export function laptopCompanionConfig(
+  env: NodeJS.ProcessEnv,
+  base: CompanionConfig = COMPANION_DEFAULTS,
+): CompanionConfig {
+  const ops = join(operatorStateHome(laptopInstallEnv(env)), "companion");
+  return {
+    ...base,
+    ...LAPTOP_COMPANION,
+    image: (env["QCR_IMAGE"] ?? "").trim() || base.image,
+    repo_dir: join(ops, "workspace"),
+    tracker_dir: "",
+    tracker_docs_dir: "",
+    reviewed_repo_dir: "",
+    evidence_dir: join(ops, "evidence"),
+    feed_dir: join(ops, "feed"),
+    alerts_dir: join(ops, "alerts"),
+    build_context: "",
+  };
+}
+
+// No file of the host is visible to the planner, and none is asked about: a
+// present-or-not decision (the reviewed repo) is already made by the config.
+const NO_HOST_FILES: CompanionFs = {
+  exists: () => false,
+  read: () => undefined,
+  mode: () => undefined,
+};
+
+/** The lifecycle of the wrapper-run companion, for a process that has none of
+ * the host's files (the planner, or the TUI container). */
+export function laptopLifecycle(
+  env: NodeJS.ProcessEnv,
+  docker: DockerRunner,
+  base?: CompanionConfig,
+  /** The planner passes none (no host file is visible to it); the TUI passes
+   * the real one, so `syncConfigMirror` finds the config the wrapper mounted. */
+  fs: CompanionFs = NO_HOST_FILES,
+): CompanionLifecycle {
+  return new CompanionLifecycle(
+    laptopCompanionConfig(env, base),
+    docker,
+    laptopInstallEnv(env),
+    () => {},
+    fs,
+    () => "",
+    "tmux-socket",
+  ).withoutMemory();
+}
+
+export interface CompanionPlan {
+  name: string;
+  hash: string;
+  mkdirs: string[];
+  tuiMounts: string[];
+  /** `<volume>:<destination>` */
+  tuiVolumes: string[];
+  tuiEnv: string[];
+  run: string[];
+}
+
+const noDocker: DockerRunner = async () => ({
+  ok: false,
+  stdout: "",
+  stderr: "the planner runs no docker",
+  code: null,
+});
+
+/** What the wrapper needs to run the companion and to mount its shared dirs
+ * into the TUI container. Pure over `env`. */
+export function companionPlan(env: NodeJS.ProcessEnv): CompanionPlan {
+  const lc = laptopLifecycle(env, noDocker);
+  const homes = lc.hostHomes();
+  const cfg = lc.cfg;
+  const inject = dirname(companionInjectDir(cfg));
+  const mkdirs = [
+    cfg.repo_dir,
+    inject,
+    cfg.feed_dir,
+    cfg.alerts_dir,
+    cfg.evidence_dir,
+    homes.profiles,
+    homes.portrait,
+    homes.configMirror,
+    homes.state,
+    homes.github,
+  ];
+  // What the TUI reads or writes of the companion's files, at the host's paths.
+  const tuiMounts = [
+    cfg.feed_dir,
+    cfg.alerts_dir,
+    cfg.evidence_dir,
+    inject,
+    homes.configMirror,
+    homes.state,
+    homes.github,
+  ];
+  const run = lc.runArgv();
+  // The agent socket's path moves with every login, so the hash names that the
+  // companion has one, not where: a TUI started from another shell adopts the
+  // running companion. A dead socket fails `docker start`, and the wrapper
+  // recreates the container then.
+  const agent = lc.sshSources().agent;
+  const hashed = run.map((a) =>
+    agent !== undefined && a.startsWith(`${agent}:`) ? `<ssh-agent>${a.slice(agent.length)}` : a,
+  );
+  const hash = createHash("sha256").update(hashed.join("\n")).digest("hex").slice(0, 16);
+  // After `run --detach`: the label is read back by the wrapper to tell a
+  // current container from a drifted one.
+  run.splice(2, 0, "--label", `qcr.plan=${hash}`);
+  const installEnv = laptopInstallEnv(env);
+  const tuiEnv = [
+    ...HOST_ENV_NAMES.map((n) => `${n}=${env[n] ?? ""}`).filter((l) => !l.endsWith("=")),
+    `QCR_STATE_HOME=${installEnv.QCR_STATE_HOME ?? ""}`,
+    ...(installEnv["QCR_INSTALL"] ? [`QCR_INSTALL=${installEnv["QCR_INSTALL"]}`] : []),
+    `QCR_IMAGE=${cfg.image}`,
+  ];
+  return {
+    name: cfg.container_name,
+    hash,
+    mkdirs: unique(mkdirs),
+    tuiMounts: unique(tuiMounts),
+    tuiVolumes: [`${tmuxVolume(cfg)}:${CONTAINER.tmuxDir}`],
+    tuiEnv,
+    run,
+  };
+}
+
+function unique(xs: string[]): string[] {
+  return [...new Set(xs)];
+}
+
+/** The plan as the lines the wrapper reads. A value with a newline would split
+ * a line, so it is refused rather than escaped. */
+export function renderPlan(plan: CompanionPlan): string {
+  const lines: Array<[string, string]> = [
+    ["name", plan.name],
+    ["plan", plan.hash],
+    ...plan.mkdirs.map((p): [string, string] => ["mkdir", p]),
+    ...plan.tuiMounts.map((p): [string, string] => ["tui-mount", p]),
+    ...plan.tuiVolumes.map((v): [string, string] => ["tui-volume", v]),
+    ...plan.tuiEnv.map((e): [string, string] => ["tui-env", e]),
+    ...plan.run.map((a): [string, string] => ["run", a]),
+  ];
+  for (const [kind, value] of lines)
+    if (/[\n\r]/.test(value)) throw new Error(`plan: a ${kind} value holds a newline`);
+  return lines.map(([k, v]) => `${k} ${v}`).join("\n") + "\n";
+}

package/src/tui/companiontab.ts

@@ -0,0 +1,83 @@
+// Companion startup healing.
+//
+// The companion's startup can fail and later heal, so asking for it while it
+// is down must re-run the startup rather than shrug. The conversation itself
+// lives in the permanent sidebar column (src/tui/sidebar.ts), so once the
+// retry succeeds there is nothing to open — the column is already on screen
+// and the only thing left to do is give it the keyboard.
+import type { App } from "./app.js";
+
+export interface CompanionTabDeps {
+  /** Live view of the companion's state — startup may fail and later heal. */
+  available: () => boolean;
+  /** The real startup error when unavailable (never a mislabel). */
+  failure?: () => string | undefined;
+  /** Re-runs the full startup (build image if missing, up, rollover, spawn). */
+  retry?: () => Promise<void>;
+}
+
+/**
+ * The companion's start, wherever it is asked for — the boot bring-up and
+ * the operator's later retry. The feed / alert / tui-actions channels are
+ * wired after the first start that leaves the companion up, whichever path
+ * that was, so a companion healed by retry gets its view feed, alerts and
+ * action channel too. Wired at most once — every wiring chains pollers.
+ *
+ * A start asked for while another is still in flight joins it rather than
+ * starting again: two overlapping starts each run the day rollover, and the
+ * later one kills the conversation the earlier one just spawned.
+ */
+export function companionStarter(deps: {
+  start: () => Promise<void>;
+  up: () => boolean;
+  wire: () => Promise<void>;
+}): () => Promise<void> {
+  let wired = false;
+  let inFlight: Promise<void> | undefined;
+  const once = async (): Promise<void> => {
+    await deps.start();
+    if (wired || !deps.up()) return;
+    wired = true;
+    await deps.wire();
+  };
+  return () => {
+    inFlight ??= once().finally(() => {
+      inFlight = undefined;
+    });
+    return inFlight;
+  };
+}
+
+export function installCompanionTabHooks(app: App, deps: CompanionTabDeps): void {
+  let retrying = false;
+  const notRunning = (theApp: App): void =>
+    theApp.notice(`companion not running: ${deps.failure?.() ?? "not started"}`);
+
+  app.hooks.companionEnsure = async (theApp) => {
+    if (deps.available()) {
+      theApp.focusCompanion();
+      return;
+    }
+    // No retry wired, or one already in flight: say what is actually wrong.
+    // "not started" is the last resort — a mislabel here points the operator
+    // at a cause (such as a --no-companion flag) that is not the real one.
+    if (retrying || !deps.retry) {
+      notRunning(theApp);
+      return;
+    }
+    retrying = true;
+    theApp.notice("companion starting…");
+    theApp.repaint();
+    try {
+      await deps.retry();
+    } finally {
+      retrying = false;
+    }
+    theApp.repaint();
+    if (!deps.available()) {
+      notRunning(theApp);
+      return;
+    }
+    theApp.focusCompanion();
+  };
+}

package/src/tui/confighome.ts

@@ -0,0 +1,155 @@
+// The deploy tab's config-home half: `deploy.sh release <version>` ships the
+// install's config home — config.toml and the profiles/ beside it — to the VM,
+// and the tab says whether the VM runs the one this machine would ship.
+// Both ends are fingerprinted by the same script (`scripts/config-fingerprint.sh`,
+// over `scripts/install-locator.sh`), locally and inside the container; this
+// module only reads and compares the two answers. Pure — shared by the tab's
+// render and the companion feed, so the two can never say different things.
+// The tab also says which post-scan re-tune a pending profile change is, from
+// the setup re-tune log (`setup/retunelog.js`, a type-only leaf of the
+// single-shepherd fence).
+import { retuneLine, type RetuneRecord, type RetunesRead } from "../setup/retunelog.js";
+
+/** `scripts/config-fingerprint.sh` output: what a config home ships, as the
+ * config file's hash and one hash over every file under its profiles/. */
+export interface ConfigFingerprint {
+  config: string;
+  profiles: string;
+}
+
+/** One end's config home: its fingerprint; `"none"` when that end has no
+ * shippable home (the PC: only a checkout config, so deploy.sh refuses; the
+ * VM: nothing was ever shipped, it reads its checkout config); or
+ * `"unparseable"` when the script answered something else. */
+export type ConfigRead = ConfigFingerprint | "none" | "unparseable";
+
+export function parseConfigFingerprint(stdout: string): ConfigRead {
+  const text = stdout.trim();
+  if (text === "none") return "none";
+  const m = /^config=([0-9a-f]{64}) profiles=([0-9a-f]{64})$/.exec(text);
+  return m ? { config: m[1]!, profiles: m[2]! } : "unparseable";
+}
+
+/**
+ * Does the VM run the config home this machine would ship? Honest-unknown both
+ * ways: an end that was not read, or read as garbage, makes the
+ * answer `unknown` — never "matches" (that would hide an undeployed profile)
+ * and never "changed" (that would invent one).
+ */
+export type ConfigDrift =
+  | { kind: "unknown"; why: string }
+  | { kind: "no-home" }
+  | { kind: "never-shipped" }
+  | { kind: "same" }
+  | { kind: "changed"; config: boolean; profiles: boolean };
+
+export function configDrift(local?: ConfigRead, deployed?: ConfigRead): ConfigDrift {
+  if (local === undefined)
+    return { kind: "unknown", why: "the local config home could not be fingerprinted" };
+  if (local === "unparseable")
+    return { kind: "unknown", why: "the local config home's fingerprint was unreadable" };
+  if (local === "none") return { kind: "no-home" };
+  if (deployed === undefined)
+    return { kind: "unknown", why: "the VM's config home could not be read (ssh/docker failed)" };
+  if (deployed === "unparseable")
+    return { kind: "unknown", why: "the VM's config home fingerprint was unreadable" };
+  if (deployed === "none") return { kind: "never-shipped" };
+  const config = local.config !== deployed.config;
+  const profiles = local.profiles !== deployed.profiles;
+  return config || profiles ? { kind: "changed", config, profiles } : { kind: "same" };
+}
+
+/** The one sentence for a drift — painted in the tab and published to the
+ * companion, so the two can never say different things. */
+export function configDriftText(d: ConfigDrift): string {
+  switch (d.kind) {
+    case "unknown":
+      return `unknown — ${d.why}; r retries`;
+    case "no-home":
+      return "no config home on this machine — deploy refuses until there is one (`qcr install migrate` moves a checkout config.toml there)";
+    case "never-shipped":
+      return "config home not deployed — the VM still reads its checkout config (the next sync ships the home)";
+    case "same":
+      return "config home deployed — the VM runs this config and these profiles";
+    case "changed":
+      return d.profiles && d.config
+        ? "config.toml and profile changed, not deployed"
+        : d.profiles
+          ? "profile changed, not deployed"
+          : "config.toml changed, not deployed";
+  }
+}
+
+// ---- the re-tunes a deploy would ship -----------------------------------------
+
+/**
+ * Which post-scan re-tunes (`<state home>/setup/retunes.json`, written by the
+ * companion's `setup_retune`) the VM does not run yet. The config drift is the
+ * authority on whether the profile is behind; the re-tune log only says which
+ * change that is, so it is consulted only while the profile is (or may be)
+ * behind:
+ *
+ *   - drift `same`, `no-home`, or only config.toml changed → none: the VM runs
+ *     these profiles (or nothing could ship them);
+ *   - `never-shipped` → every logged re-tune that wrote a file is pending;
+ *   - profiles `changed` → those written after the VM's last deploy (the
+ *     BUILD_SHA marker's time, written on this machine by deploy.sh); with no
+ *     readable deploy time, the latest re-tune, as unknown;
+ *   - drift `unknown` → the re-tunes since the last deploy, as unknown (with
+ *     no readable deploy time either, the latest re-tune, as unknown).
+ *
+ * An unreadable log is unknown with its reason, never "no re-tunes".
+ */
+export type PendingRetunes =
+  | { state: "none" }
+  | { state: "pending"; retunes: RetuneRecord[] }
+  | { state: "unknown"; why: string; retunes: RetuneRecord[] };
+
+export function pendingRetunes(
+  log: RetunesRead | undefined,
+  drift: ConfigDrift,
+  deployedAt: string | undefined,
+): PendingRetunes {
+  if (drift.kind === "same" || drift.kind === "no-home") return { state: "none" };
+  if (drift.kind === "changed" && !drift.profiles) return { state: "none" };
+  if (log === undefined || log.state === "absent") return { state: "none" };
+  if (log.state === "unreadable") return { state: "unknown", why: log.error, retunes: [] };
+  const written = log.retunes.filter((r) => r.files.length > 0);
+  if (written.length === 0) return { state: "none" };
+  if (drift.kind === "never-shipped") return { state: "pending", retunes: written };
+  // Compared as instants, never as strings: the BUILD_SHA marker is written
+  // to the second (`…:32Z`) and a re-tune to the millisecond (`…:32.123Z`),
+  // so a string compare reads a re-tune in the deploy's own second as shipped.
+  const deployed = deployedAt === undefined ? Number.NaN : Date.parse(deployedAt);
+  const known = Number.isFinite(deployed);
+  const since = known ? written.filter((r) => !(Date.parse(r.at) < deployed)) : [];
+  if (!known) {
+    const why =
+      drift.kind === "unknown"
+        ? `${drift.why}; when the VM was last deployed is unknown`
+        : "when the VM was last deployed is unknown";
+    return { state: "unknown", why, retunes: written.slice(-1) };
+  }
+  if (drift.kind === "unknown") {
+    return since.length === 0
+      ? { state: "none" }
+      : { state: "unknown", why: drift.why, retunes: since };
+  }
+  return since.length === 0 ? { state: "none" } : { state: "pending", retunes: since };
+}
+
+/** The deploy tab's lines for the pending re-tunes (plain text; the tab inks
+ * them). Each re-tune, then each change with its reason. */
+export function pendingRetuneLines(p: PendingRetunes): string[] {
+  if (p.state === "none") return [];
+  const head =
+    p.state === "pending"
+      ? `${p.retunes.length} post-scan re-tune${p.retunes.length === 1 ? "" : "s"} not deployed — a release ships ${p.retunes.length === 1 ? "it" : "them"}:`
+      : `whether these re-tunes are deployed is unknown — ${p.why}`;
+  const out = [head];
+  for (const r of p.retunes) {
+    out.push(`  ${retuneLine(r)}`);
+    for (const c of r.changes) out.push(`    ${c.input}: ${c.from} → ${c.to} — ${c.why}`);
+  }
+  return out;
+}

package/src/tui/connect.ts

@@ -0,0 +1,68 @@
+// VM ssh bootstrap — the GCP metadata key (~/.ssh/google_compute_engine)
+// is passphrase-protected, and every TUI ssh runs BatchMode (fail-fast, no
+// prompts). The passphrase therefore gets entered exactly once, here, on the
+// operator's real terminal: `ssh <host> true` births the ControlMaster socket
+// the ssh config then shares for 4h (ControlPersist), and every poll/digest
+// ssh rides it.
+//
+// This is only reached from the board (key s), never from the startup path:
+// nothing external may gate the first frame, so startup runs the
+// non-interactive triage in `sshtriage.ts` instead and reports the cause and
+// the exact remedy; pressing `s` is the operator asking for this prompt.
+import { spawnSync } from "node:child_process";
+import type { TuiConfig } from "../config.js";
+import { transportOf } from "./remote.js";
+
+export function masterCheckArgv(cfg: TuiConfig): string[] {
+  return ["-O", "check", cfg.ssh_host];
+}
+
+export function masterConnectArgv(cfg: TuiConfig): string[] {
+  return ["-o", "ConnectTimeout=15", cfg.ssh_host, "true"];
+}
+
+export interface ConnectResult {
+  /** `"local"`: `[tui] target = "local"` — there is no master to
+   * establish and no ssh process is ever spawned; the call is a silent no-op. */
+  kind: "alive" | "connected" | "failed" | "local";
+  detail?: string;
+}
+
+/** Synchronous ssh — interactive runs inherit the terminal so OpenSSH's own
+ * passphrase prompt appears natively. Injectable; tests never spawn. */
+export type SyncSsh = (
+  argv: string[],
+  interactive: boolean,
+) => { status: number | null; stderr: string };
+
+export const realSyncSsh: SyncSsh = (argv, interactive) => {
+  const r = interactive
+    ? spawnSync("ssh", argv, { stdio: "inherit" })
+    : spawnSync("ssh", argv, { stdio: ["ignore", "ignore", "pipe"], timeout: 10_000 });
+  return { status: r.status, stderr: String(r.stderr ?? "") };
+};
+
+export function ensureSshMaster(
+  cfg: TuiConfig,
+  ssh: SyncSsh = realSyncSsh,
+  say: (line: string) => void = console.log,
+): ConnectResult {
+  // The laptop topology has no ssh anywhere. Guarded here (not only
+  // at the call sites) so the board's `s` reconnect hook and any future caller
+  // inherit the guarantee: in local mode this function spawns nothing.
+  if (transportOf(cfg) === "local") return { kind: "local" };
+  if (ssh(masterCheckArgv(cfg), false).status === 0) return { kind: "alive" };
+  say(
+    `connecting to ${cfg.ssh_host} — enter the GCP key passphrase if asked (once; the connection is shared for 4h)`,
+  );
+  const r = ssh(masterConnectArgv(cfg), true);
+  if (r.status === 0) {
+    say(`connected — ssh master to ${cfg.ssh_host} established`);
+    return { kind: "connected" };
+  }
+  const detail = r.stderr.trim() || `ssh exit ${String(r.status)}`;
+  say(
+    `ssh to ${cfg.ssh_host} failed: ${detail} — the board will show unreachable (press s to retry)`,
+  );
+  return { kind: "failed", detail };
+}

package/src/tui/deploy-ceremony.ts

@@ -0,0 +1,104 @@
+// Durable ownership journal for the TUI's deploy ceremony. Hot reload re-execs
+// the TUI unconditionally, so drain ownership cannot live only in a closure:
+// losing it would leave the daemon drained with no visible continuation.
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Every phase the journal may hold — the type and the reader's check both
+ * come from this one list, so a phase the TUI can write is one it can read. */
+export const DURABLE_DEPLOY_PHASES = [
+  "engaging-drain",
+  "abort-requested",
+  "waiting-rounds",
+  "syncing",
+  "awaiting-lift",
+  "deploy-failed",
+  "drain-failed",
+  "lifting-after-abort",
+] as const;
+
+export type DurableDeployPhase = (typeof DURABLE_DEPLOY_PHASES)[number];
+
+export interface DeployCeremonyRecord {
+  version: 1;
+  phase: DurableDeployPhase;
+  /** The release version the ceremony ships; the detached runner is started
+   * with it, so a reload mid-ceremony still knows what it was shipping. */
+  target_version?: string;
+  /** Snapshot that proved the pre-deploy drain. Auto-lift must be observed on
+   * a strictly newer daemon generation, never inferred from this one. */
+  pre_deploy_snapshot_at?: string;
+  /** True only after a fresh status snapshot visibly showed the drain ON. */
+  drain_observed?: boolean;
+  /** First fresh undrained snapshot seen after the command receipt. A second
+   * newer one proves an external drain-off even if ON was never observed. */
+  first_undrained_snapshot_at?: string;
+  /** Stable local detached-process identity; survives mandatory TUI re-exec. */
+  deploy_run_id?: string;
+  updated_at: string;
+}
+
+export interface DeployCeremonyStore {
+  read(): DeployCeremonyRecord | undefined;
+  write(record: DeployCeremonyRecord): void;
+  clear(): void;
+}
+
+function valid(value: unknown): value is DeployCeremonyRecord {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.version === 1 &&
+    typeof v.phase === "string" &&
+    (DURABLE_DEPLOY_PHASES as readonly string[]).includes(v.phase) &&
+    (v.target_version === undefined || typeof v.target_version === "string") &&
+    (v.pre_deploy_snapshot_at === undefined || typeof v.pre_deploy_snapshot_at === "string") &&
+    (v.drain_observed === undefined || typeof v.drain_observed === "boolean") &&
+    (v.first_undrained_snapshot_at === undefined ||
+      typeof v.first_undrained_snapshot_at === "string") &&
+    (v.deploy_run_id === undefined || typeof v.deploy_run_id === "string") &&
+    typeof v.updated_at === "string"
+  );
+}
+
+export class MemoryDeployCeremonyStore implements DeployCeremonyStore {
+  private record: DeployCeremonyRecord | undefined;
+  read(): DeployCeremonyRecord | undefined {
+    return this.record;
+  }
+  write(record: DeployCeremonyRecord): void {
+    this.record = { ...record };
+  }
+  clear(): void {
+    this.record = undefined;
+  }
+}
+
+export class FileDeployCeremonyStore implements DeployCeremonyStore {
+  constructor(private readonly path: string) {}
+
+  read(): DeployCeremonyRecord | undefined {
+    try {
+      const value: unknown = JSON.parse(readFileSync(this.path, "utf8"));
+      return valid(value) ? value : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  write(record: DeployCeremonyRecord): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const tmp = `${this.path}.tmp-${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, this.path);
+  }
+
+  clear(): void {
+    try {
+      rmSync(this.path, { force: true });
+    } catch {
+      // A journal cleanup failure cannot change daemon state. A stale journal
+      // is safer than forgetting a drain and is re-evaluated on next boot.
+    }
+  }
+}