@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/tui/rollover.js

@@ -0,0 +1,767 @@
+// Daily rollover — a fresh companion conversation per ops day, with the five
+// carry items handed over as the first message.
+//
+// Rollover fires on the first TUI start of a new day
+// (ops timezone), never mid-use; the sequence is the rotateOverseer pattern from
+// src/sessions.ts — archive the run date-stamped, kill the tmux session,
+// respawn — and the opening context carries: yesterday's EOD digest, the
+// compacted summary of yesterday's conversation, yesterday's conversation
+// tail, unresolved alerts, and the live board snapshot (plus the alert knobs
+// in force, so the companion's tiering matches the config it is judged by).
+//
+// Everything the container owns goes through the DockerRunner seam (the pihome
+// volume is only reachable via `docker exec`); everything the host owns is a
+// plain path, so the tests need neither docker nor pi.
+//
+// The day-open text is delivered as an inject file, not a pi CLI flag:
+// `extensions/inject-bridge.ts` drains its directory on `session_start`
+// (VERIFY-ON-PIN: the drain-then-watch behaviour depends only on our own code,
+// but `pi.sendUserMessage` and the `session_start` event name are pi's), so
+// writing the file before spawning pi is race-free. The alternative — a pi CLI
+// initial-message flag — is undocumented for 0.84.1; if one turns up it is a
+// drop-in replacement for writeDayOpen().
+import { stripModelDocs } from "@quickchatai/pi-quickreview/src/promptdoc.js";
+import { isNoTmuxServer } from "../tmux.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { zoneDateString } from "../eod.js";
+import { parseAlert, readPolicyState } from "./alerts.js";
+import { CONTAINER, companionSessionDir, dockerFailureLine as execReason, } from "./companion.js";
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Bounds for the compacted summary and the raw tail — the opening message is
+ * a briefing, not a transcript. */
+export const SUMMARY_MAX_CHARS = 4000;
+export const TAIL_MAX_CHARS = 2000;
+export const TURN_MAX_CHARS = 400;
+export const HEAD_TURNS = 6;
+export const TAIL_TURNS = 12;
+/**
+ * The rollover state, with "there is no state" and "the state is unreadable"
+ * kept apart.
+ *
+ * This is the read that gates the rollover itself, so collapsing it defeats
+ * it: an unparseable `rollover.json` read as absent would look exactly like a
+ * fresh installation, `decideRollover` would say `first-run`, and the run
+ * would record today's date over it and never retry. Worse,
+ * `interviewDue(marker, undefined)` is true, so a torn state file could
+ * re-fire the first-run interview at a months-old install.
+ *
+ * A structurally invalid payload (no usable `last_open_date`) is unreadable,
+ * not absent — the file is there, we simply cannot understand it.
+ */
+export function readRolloverStateFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return { state: "absent" };
+        return { state: "unreadable", reason: code ?? errText(err) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return { state: "unreadable", reason: errText(err) };
+    }
+    // `null`, a number, an array: valid JSON, still not a state row. Without
+    // this the property read below throws past the catch above.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { state: "unreadable", reason: "not a JSON object" };
+    }
+    const raw = parsed;
+    if (typeof raw.last_open_date !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(raw.last_open_date)) {
+        return { state: "unreadable", reason: "no usable last_open_date" };
+    }
+    return {
+        state: "state",
+        value: {
+            last_open_date: raw.last_open_date,
+            updated_at: String(raw.updated_at ?? ""),
+            last_archive: raw.last_archive,
+            ...(typeof raw.first_run_interviewed === "string"
+                ? { first_run_interviewed: raw.first_run_interviewed }
+                : {}),
+            ...(typeof raw.first_run_owed === "string" ? { first_run_owed: raw.first_run_owed } : {}),
+        },
+    };
+}
+/** Absent or unreadable ⇒ undefined. For read-back and display only: anything
+ * that decides from the state must use `readRolloverStateFile` — see there. */
+export function readRolloverState(path) {
+    const r = readRolloverStateFile(path);
+    return r.state === "state" ? r.value : undefined;
+}
+export function writeRolloverState(path, state) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+    renameSync(tmp, path);
+}
+/**
+ * Today's calendar date in the operations timezone (`cfg.ops.timezone`;
+ * the TUI threads it through — the UTC default only covers callers
+ * with no config in hand). `QCR_FAKE_TODAY=YYYY-MM-DD` overrides it — the
+ * only way to exercise a rollover without waiting for midnight (the smoke
+ * script uses exactly this).
+ */
+export function todayDate(now, env = process.env, timeZone = "UTC") {
+    const fake = env.QCR_FAKE_TODAY?.trim();
+    if (fake && /^\d{4}-\d{2}-\d{2}$/.test(fake))
+        return fake;
+    return zoneDateString(now, timeZone);
+}
+/**
+ * Pure decision: string compare is correct for ISO dates, and a clock that
+ * went backwards (previous > today) is treated as same-day, never a rotate.
+ *
+ * It takes the read, not a `RolloverState | undefined`, on purpose: handed the
+ * collapsed value it cannot tell a fresh installation from a torn state file,
+ * and those two want opposite behaviour (record today vs. touch nothing).
+ */
+export function decideRollover(today, read) {
+    if (read.state === "unreadable")
+        return { kind: "unknown", today, reason: read.reason };
+    if (read.state === "absent")
+        return { kind: "first-run", today };
+    if (read.value.last_open_date >= today)
+        return { kind: "same-day", today };
+    return { kind: "rollover", today, previous: read.value.last_open_date };
+}
+/**
+ * Extract the user/assistant text turns from a pi session .jsonl.
+ *
+ * VERIFY-ON-PIN: the on-disk session-file schema is not documented for 0.84.1.
+ * Three shapes are accepted (`{role,content}`, `{type:"message",message:{…}}`,
+ * `{entry:{role,content}}`) and content may be a string or an array of
+ * `{type:"text",text}` parts. An unrecognised line is skipped, so a schema
+ * drift degrades the summary rather than breaking the rollover.
+ */
+export function parseConversation(jsonl) {
+    const turns = [];
+    for (const line of jsonl.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const node = unwrap(obj);
+        if (!node)
+            continue;
+        const role = node.role;
+        if (role !== "user" && role !== "assistant")
+            continue;
+        const text = contentText(node.content).trim();
+        if (text === "")
+            continue;
+        turns.push({ role, text });
+    }
+    return turns;
+}
+function unwrap(obj) {
+    if (typeof obj !== "object" || obj === null || Array.isArray(obj))
+        return undefined;
+    const v = obj;
+    for (const inner of [v, v.message, v.entry]) {
+        if (typeof inner === "object" && inner !== null && !Array.isArray(inner)) {
+            const cand = inner;
+            if (typeof cand.role === "string")
+                return cand;
+        }
+    }
+    return undefined;
+}
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const part of content) {
+        if (typeof part === "string")
+            parts.push(part);
+        else if (typeof part === "object" && part !== null) {
+            const p = part;
+            if (typeof p.text === "string")
+                parts.push(p.text);
+        }
+    }
+    return parts.join("\n");
+}
+function oneLine(text, max = TURN_MAX_CHARS) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+/** The user-turn role label: the configured owner name, or the
+ * neutral role when none is configured. */
+function ownerLabel(ownerName) {
+    return ownerName?.trim() || "the operator";
+}
+/** Renders turns in chronological order within a character budget. `keep`
+ * says which end survives when the budget runs out: an opening keeps its
+ * oldest turns, an ending its newest. */
+function renderTurns(turns, budget, ownerName, keep = "oldest") {
+    const ordered = keep === "oldest" ? turns : [...turns].reverse();
+    const lines = [];
+    let used = 0;
+    for (const t of ordered) {
+        const line = `- **${t.role === "user" ? ownerLabel(ownerName) : "you"}**: ${oneLine(t.text)}`;
+        if (used + line.length > budget)
+            break;
+        lines.push(line);
+        used += line.length + 1;
+    }
+    if (keep === "newest")
+        lines.reverse();
+    return lines.join("\n");
+}
+/**
+ * Deterministic compaction — no LLM in this path (the daemon's rule applies to
+ * the TUI too). Head + tail sectioning with a hard character budget: the
+ * opening of the day tells the companion how yesterday started, how it ended,
+ * and how much it is not being shown.
+ */
+export function compactConversation(turns, budget = SUMMARY_MAX_CHARS, ownerName) {
+    if (turns.length === 0)
+        return "";
+    const head = turns.slice(0, HEAD_TURNS);
+    const tail = turns.length > HEAD_TURNS ? turns.slice(Math.max(HEAD_TURNS, turns.length - TAIL_TURNS)) : [];
+    const skipped = turns.length - head.length - tail.length;
+    const half = Math.floor((budget - 200) / 2);
+    const sections = [
+        `Yesterday: ${turns.length} turns (${turns.filter((t) => t.role === "user").length} from ${ownerLabel(ownerName)}).`,
+    ];
+    sections.push(`**How it opened**\n${renderTurns(head, half, ownerName)}`);
+    if (skipped > 0)
+        sections.push(`…${skipped} turn${skipped === 1 ? "" : "s"} elided…`);
+    if (tail.length > 0)
+        sections.push(`**How it ended**\n${renderTurns(tail, half, ownerName, "newest")}`);
+    const out = sections.join("\n\n");
+    return out.length <= budget ? out : `${out.slice(0, budget - 1)}…`;
+}
+/** The raw last few turns, verbatim-ish and bounded — the carry item that is
+ * deliberately not summarised. */
+export function conversationTail(turns, budget = TAIL_MAX_CHARS) {
+    if (turns.length === 0)
+        return "";
+    return renderTurns(turns.slice(-6), budget, undefined, "newest");
+}
+// ---- the other carry items --------------------------------------------------
+export function readSnapshot(feedDir) {
+    try {
+        return JSON.parse(readFileSync(join(feedDir, "snapshot.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One paragraph of board state: counts by state, rounds, mode, spend. */
+export function snapshotSummary(snap) {
+    if (!snap)
+        return "";
+    const byState = new Map();
+    for (const p of snap.prs)
+        byState.set(p.state, (byState.get(p.state) ?? 0) + 1);
+    const states = [...byState.entries()]
+        .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+        .map(([s, n]) => `${n} ${s}`);
+    const lines = [
+        `${snap.prs.length} tracked PR${snap.prs.length === 1 ? "" : "s"}${states.length > 0 ? ` (${states.join(", ")})` : ""}; ` +
+            `${snap.running_rounds} round${snap.running_rounds === 1 ? "" : "s"} running; mode ${snap.dry_run ? "dry-run" : "LIVE"}; ` +
+            `spend $${snap.total_spend_usd.toFixed(2)} total${snap.today_spend_usd !== undefined ? ` / $${snap.today_spend_usd.toFixed(2)} today` : ""}.`,
+        `Snapshot written ${snap.written_at}.`,
+    ];
+    const notable = snap.prs
+        .filter((p) => p.state !== "closed")
+        .slice(0, 8)
+        .map((p) => `- #${p.number} ${p.state}${p.last_verdict ? ` (${p.last_verdict})` : ""}${p.paused ? " [paused]" : ""} — ${oneLine(p.title ?? "", 70)}`);
+    return [...lines, ...notable].join("\n");
+}
+/** Digest headline: the feed snapshot carries the daemon's own copy; a local
+ * digest/ dir is the offline fallback. Neither → degraded to "—". */
+export function digestLine(snap, localHeadline) {
+    return (snap?.digest_headline ?? "").trim() || (localHeadline ?? "").trim();
+}
+/**
+ * Alerts that are still open at the moment of rollover: anything sitting
+ * unconsumed in the alerts dir, plus every `alert`-tier cause the policy state
+ * saw on a previous day (a cause that fired yesterday evening and was never
+ * spoken to is exactly the thing a fresh conversation would otherwise forget).
+ */
+export function openAlerts(alertsDir, policyStatePath, today) {
+    const lines = [];
+    if (existsSync(alertsDir)) {
+        for (const f of readdirSync(alertsDir)
+            .filter((n) => n.endsWith(".json") && !n.startsWith("."))
+            .sort()) {
+            let parsed;
+            try {
+                parsed = parseAlert(readFileSync(join(alertsDir, f), "utf8"), f);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.ok)
+                lines.push(`- [${parsed.alert.tier}] ${parsed.alert.title}${parsed.alert.pr !== null ? ` (PR #${parsed.alert.pr})` : ""} — cause \`${parsed.alert.cause}\` (unread)`);
+            else
+                lines.push(`- [malformed] ${f}: ${parsed.error}`);
+        }
+    }
+    const policy = readPolicyState(policyStatePath);
+    if (policy && policy.day !== today) {
+        for (const [cause, mem] of Object.entries(policy.causes)) {
+            if (mem.lastTier !== "alert")
+                continue;
+            lines.push(`- [alert] cause \`${cause}\` last raised ${policy.day}${mem.folds > 0 ? ` (+${mem.folds} folded repeats)` : ""} — carried over`);
+        }
+    }
+    return lines.join("\n");
+}
+/** The knobs the companion's tiering is judged against, verbatim from config. */
+export function alertKnobs(cfg) {
+    return [
+        `- overdue grace: ${cfg.overdue_grace_min} min`,
+        `- stale daemon: ${cfg.stale_alert_s} s`,
+        `- awaiting age: ${cfg.awaiting_age_h} h`,
+        `- per-cause cooldown: ${cfg.cooldown_min} min`,
+    ].join("\n");
+}
+const PLACEHOLDERS = [
+    "date",
+    "digest",
+    "yesterday_summary",
+    "yesterday_tail",
+    "open_alerts",
+    "snapshot_summary",
+    "alert_knobs",
+];
+/** Fill a companion template: the model docs stripped, each `{{key}}` in
+ * `keys` replaced by its trimmed source, and an empty source rendered as `—`
+ * — a missing item is stated, never silent. */
+function renderTemplate(template, keys, sources) {
+    let out = stripModelDocs(template);
+    for (const key of keys) {
+        const value = (sources[key] ?? "").trim();
+        out = out.replaceAll(`{{${key}}}`, value === "" ? "—" : value);
+    }
+    return out;
+}
+/** Fill prompts/companion-day-open.md. An empty source renders as `—`, per the
+ * template's own header — a missing carry item is stated, never silent. */
+export function renderDayOpen(template, sources) {
+    return renderTemplate(template, PLACEHOLDERS, sources);
+}
+/** The inject file the bridge will deliver as the first user message. */
+export function dayOpenFileName(date) {
+    return `${date}-day-open.md`;
+}
+export function readFirstRunMarker(path) {
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw.completed_at !== "string" || raw.completed_at.trim() === "")
+            return undefined;
+        return { completed_at: raw.completed_at };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Should the first-run interview fire on this start? Pure decision:
+ *
+ *   * a delivered interview never fires again (the state records it);
+ *   * no rollover state has ever existed ⇒ first run, interview due — the
+ *     fallback that makes the feature work before/without the wizard;
+ *   * an interview found due but not delivered stays due (`first_run_owed`);
+ *   * otherwise the wizard's marker decides — its presence on an installation
+ *     whose state carries no interview means onboarding finished and the
+ *     greeting is owed.
+ *
+ * An existing installation (state present, no marker, nothing owed) never
+ * gets one.
+ */
+export function interviewDue(marker, state) {
+    if (state?.first_run_interviewed)
+        return false;
+    if (state === undefined)
+        return true;
+    if (state.first_run_owed)
+        return true;
+    return marker !== undefined;
+}
+const FIRST_RUN_PLACEHOLDERS = ["date", "owner", "snapshot_summary"];
+/** Fill prompts/companion-first-run.md — same `—`-for-empty discipline as the
+ * day-open (the owner label is pre-defaulted, so only the snapshot can be empty). */
+export function renderFirstRun(template, sources) {
+    return renderTemplate(template, FIRST_RUN_PLACEHOLDERS, sources);
+}
+export function firstRunFileName(date) {
+    return `${date}-first-run.md`;
+}
+// ---- the sequence -----------------------------------------------------------
+/**
+ * The in-container listing of the newest conversation in `dir`: its path on
+ * stdout, nothing when there is none — exit 0 either way — and a non-zero
+ * exit with the cause on stderr when the dir cannot be listed. A dir that is
+ * not there is a volume that never held a conversation; one that is there
+ * but unreadable is not the same answer, and `ls`'s own status decides, not
+ * the status of a `head` after it.
+ */
+export function newestSessionScript(dir) {
+    return (`d='${dir}'; [ -e "$d" ] || exit 0; ` +
+        `[ -d "$d" ] && [ -r "$d" ] && [ -x "$d" ] || { echo "cannot list $d" >&2; exit 1; }; ` +
+        `set -- "$d"/*.jsonl; [ -e "$1" ] || exit 0; ` +
+        `out=$(ls -1t -- "$@") || exit 1; printf '%s\n' "$out" | head -1`);
+}
+/**
+ * The rollover itself. Call it after the container is up and before
+ * spawnPi; it returns a report and, on a rollover, leaves the tmux session
+ * killed so the caller's spawnPi() births a fresh conversation that opens on
+ * the day-open message.
+ */
+export class CompanionRollover {
+    cfg;
+    docker;
+    opts;
+    now;
+    env;
+    timeZone;
+    constructor(cfg, docker, opts) {
+        this.cfg = cfg;
+        this.docker = docker;
+        this.opts = opts;
+        this.now = opts.now ?? (() => new Date());
+        this.env = opts.env ?? process.env;
+        this.timeZone = opts.timeZone ?? "UTC";
+    }
+    today() {
+        return todayDate(this.now(), this.env, this.timeZone);
+    }
+    /** In-container session dir — the one pi is given (`companionSessionDir`). */
+    sessionDir() {
+        return companionSessionDir(this.cfg.session);
+    }
+    archiveDir(date) {
+        return `${CONTAINER.piHome}/archive/${this.cfg.session}/${date}`;
+    }
+    /**
+     * The newest conversation file on the pihome volume.
+     *
+     * Three answers, never two: `found`, `none` (the exec ran and the volume
+     * holds no conversation) and `unreadable` (the exec itself failed — an exec
+     * immediately after a container recreate can lose that race, see
+     * `companion.ts`). Folding the third into the second would archive nothing,
+     * compact zero turns and hand the companion "nothing happened yesterday" as
+     * its opening context, then record the day so it never retried.
+     *
+     * The script keeps that line inside the container too: a session dir that
+     * is not there (a fresh volume) or holds no conversation is `none`, but one
+     * that cannot be listed, or a listing that fails, exits non-zero — the
+     * listing's status is its own, never a pipeline tail's.
+     */
+    async newestSessionFile() {
+        const res = await this.docker([
+            "exec",
+            this.cfg.container_name,
+            "sh",
+            "-c",
+            newestSessionScript(this.sessionDir()),
+        ]);
+        if (!res.ok)
+            return { state: "unreadable", reason: execReason(res) };
+        const file = res.stdout.trim();
+        return file === "" ? { state: "none" } : { state: "found", file };
+    }
+    /** Archive it date-stamped (rotateOverseer pattern): the copy's
+     * in-container path, or why the copy failed. Copy, never move: if anything
+     * below fails, the original conversation is still where pi left it. */
+    async archive(file, date) {
+        const dest = `${this.archiveDir(date)}/session.jsonl`;
+        const res = await this.docker([
+            "exec",
+            this.cfg.container_name,
+            "sh",
+            "-c",
+            `mkdir -p '${this.archiveDir(date)}' && cp '${file}' '${dest}'`,
+        ]);
+        return res.ok ? { ok: true, dest } : { ok: false, reason: execReason(res) };
+    }
+    /** Read a bounded tail of the conversation file through the docker seam.
+     * A failed exec is `unreadable`, never `""` — an empty conversation and a
+     * conversation we could not fetch produce very different day-opens, and
+     * only one of them is true. */
+    async readConversation(file) {
+        if (file === "")
+            return { state: "read", text: "" };
+        const res = await this.docker([
+            "exec",
+            this.cfg.container_name,
+            "sh",
+            "-c",
+            `tail -c 400000 '${file}'`,
+        ]);
+        return res.ok
+            ? { state: "read", text: res.stdout }
+            : { state: "unreadable", reason: execReason(res) };
+    }
+    /** Stop the old session. No session (or no tmux server) to kill is the
+     * state we want, so it counts as `killed`; any other failure is `failed` —
+     * the session may still be live, and `spawnPi` would adopt it (the
+     * loss-vs-absence rule, applied to the kill). */
+    async killSession() {
+        const res = await this.docker([
+            "exec",
+            this.cfg.container_name,
+            "tmux",
+            "kill-session",
+            "-t",
+            this.cfg.session,
+        ]);
+        // No such session, or no tmux server at all (a freshly started container),
+        // means nothing is running; any other connect error does not.
+        if (res.ok ||
+            /can't find session|session not found/i.test(res.stderr) ||
+            isNoTmuxServer(res.stderr))
+            return { state: "killed" };
+        return { state: "failed", reason: execReason(res) };
+    }
+    /** tmp+rename into the inject dir — the bridge must never drain a torn file. */
+    writeInject(name, text) {
+        mkdirSync(this.opts.injectDir, { recursive: true });
+        const target = join(this.opts.injectDir, name);
+        const tmp = join(this.opts.injectDir, `.${name}.tmp`);
+        writeFileSync(tmp, text);
+        renameSync(tmp, target);
+        return target;
+    }
+    /** Write the day-open message where inject-bridge will drain it. */
+    writeDayOpen(text, date) {
+        return this.writeInject(dayOpenFileName(date), text);
+    }
+    /** Assemble the opening context from the five carry items + the knobs. */
+    buildDayOpen(date, turns) {
+        const snap = readSnapshot(this.cfg.feed_dir);
+        const template = readFileSync(this.opts.templatePath, "utf8");
+        return renderDayOpen(template, {
+            date,
+            digest: digestLine(snap, this.opts.localDigestHeadline?.()),
+            yesterday_summary: compactConversation(turns, undefined, this.opts.ownerName),
+            yesterday_tail: conversationTail(turns),
+            open_alerts: openAlerts(this.cfg.alerts_dir, this.opts.policyStatePath, date),
+            snapshot_summary: snapshotSummary(snap),
+            alert_knobs: alertKnobs(this.cfg),
+        });
+    }
+    /** `prior` is the state `run()` already read, passed in rather than re-read:
+     * a second read could come back unreadable, and a collapsed
+     * `undefined` here silently drops `first_run_interviewed` — the exact
+     * re-arming the comment below exists to prevent. */
+    record(date, archive, prior) {
+        // Preserve the interview mark across rewrites: dropping it on a later
+        // rollover would re-arm a marker-keyed interview forever.
+        const written = {
+            last_open_date: date,
+            updated_at: this.now().toISOString(),
+            ...(archive ? { last_archive: archive } : {}),
+            ...(prior?.first_run_interviewed
+                ? { first_run_interviewed: prior.first_run_interviewed }
+                : {}),
+            ...(prior?.first_run_owed ? { first_run_owed: prior.first_run_owed } : {}),
+        };
+        writeRolloverState(this.opts.statePath, written);
+        // Returned so `maybeInterview` can add its mark to the row we know we
+        // wrote, instead of re-reading the file it was just handed.
+        return written;
+    }
+    /** Assemble the first-run interview from its template. */
+    buildInterview(date) {
+        const template = readFileSync(this.opts.firstRunTemplatePath, "utf8");
+        return renderFirstRun(template, {
+            date,
+            owner: ownerLabel(this.opts.ownerName),
+            snapshot_summary: snapshotSummary(readSnapshot(this.cfg.feed_dir)),
+        });
+    }
+    /**
+     * Deliver the first-run interview if it is due — at most once per
+     * installation, recorded in the rollover state. `prior` is the state as it
+     * stood before this run touched it (the no-state-ever fallback must see the
+     * original absence, not the row `record()` just created). `current` is the
+     * row as it now stands — what `record()` just wrote, or `prior` when this
+     * run wrote nothing. Nothing here ever blocks a start: a missing/broken
+     * template degrades to a step note.
+     */
+    maybeInterview(today, prior, current, steps) {
+        if (!this.opts.firstRunTemplatePath)
+            return {};
+        const marker = this.opts.firstRunMarkerPath
+            ? readFirstRunMarker(this.opts.firstRunMarkerPath)
+            : undefined;
+        if (!interviewDue(marker, prior))
+            return {};
+        // `current`, never a re-read: a re-read that came back unreadable would
+        // collapse to a fabricated row — `last_open_date: today` stamped over a
+        // day we could not see, `last_archive` dropped. `current` is undefined
+        // only when the state was genuinely absent and this run wrote nothing, in
+        // which case today is the row's true date.
+        const state = current ?? {
+            last_open_date: today,
+            updated_at: this.now().toISOString(),
+        };
+        let interview;
+        try {
+            interview = this.buildInterview(today);
+        }
+        catch {
+            // Still owed: the no-state fallback that found it due is gone once the
+            // state exists, so the obligation is written down for the next start.
+            if (!state.first_run_owed)
+                writeRolloverState(this.opts.statePath, { ...state, first_run_owed: today });
+            steps.push("first-run interview template unreadable — skipped (system unaffected); still owed, retried on the next start");
+            return {};
+        }
+        const interviewFile = this.writeInject(firstRunFileName(today), interview);
+        steps.push(`queued first-run interview → ${interviewFile}`);
+        // Mark it delivered so it fires exactly once; later starts run the normal
+        // day-open. An abandoned interview resumes in conversation, never here.
+        const { first_run_owed: _owed, ...delivered } = state;
+        writeRolloverState(this.opts.statePath, { ...delivered, first_run_interviewed: today });
+        return { interviewFile, interview };
+    }
+    /**
+     * first-run → record the date, touch nothing;
+     * same-day  → nothing at all;
+     * rollover  → archive → compact → assemble → kill → (caller respawns);
+     * …and on any of the three, deliver the first-run interview when it
+     * is due (fresh installation, or the wizard's marker with no interview on
+     * record) — exactly once, ever.
+     */
+    async run() {
+        const today = this.today();
+        const read = readRolloverStateFile(this.opts.statePath);
+        const prior = read.state === "state" ? read.value : undefined;
+        // The row as it now stands: `prior` until `record()` replaces it.
+        let current = prior;
+        const verdict = decideRollover(today, read);
+        const steps = [];
+        let archivedTo;
+        let dayOpenFile;
+        let dayOpen;
+        const warnings = [];
+        // An unreadable state file gates everything below it: read as `first-run`
+        // it would record today's date over it and the rollover would never
+        // retry. We return before `maybeInterview` too:
+        // `interviewDue(marker, undefined)` is true, so continuing could re-fire
+        // the first-run interview at an install that had it months ago.
+        if (verdict.kind === "unknown") {
+            const deferred = `rollover state ${this.opts.statePath} exists but cannot be read (${verdict.reason}) — nothing rolled over, recorded or queued; retrying on the next start`;
+            steps.push(deferred);
+            return { verdict, steps, deferred };
+        }
+        if (verdict.kind === "first-run") {
+            current = this.record(today, undefined, prior);
+            steps.push(`first run — companion day set to ${today}`);
+        }
+        else if (verdict.kind === "rollover") {
+            const lookup = await this.newestSessionFile();
+            // A lost exec is not an empty volume. Standing down leaves the
+            // day unrecorded, so the next start runs the whole rollover again; the
+            // cost is one more day on yesterday's conversation, against handing the
+            // companion a fabricated "nothing happened yesterday" that can never be
+            // retried. The deferral is loud in the step log and the caller notices.
+            if (lookup.state === "unreadable") {
+                const deferred = `could not list the previous conversation (${lookup.reason}) — day NOT rolled over; retrying on the next start`;
+                steps.push(deferred);
+                return { verdict, steps, deferred, ...this.maybeInterview(today, prior, current, steps) };
+            }
+            const file = lookup.state === "found" ? lookup.file : "";
+            steps.push(file === "" ? "no previous conversation found" : `found conversation ${file}`);
+            // A failed copy is not a deferral: the conversation is still on the
+            // volume and the day-open below is still assembled from the real turns,
+            // so nothing fabricated is published. It is only the dated archive that
+            // is missing — and going quiet about that is how it would stay missing,
+            // so the cause reaches the operator's notice line (`warnings`).
+            if (file !== "") {
+                const copy = await this.archive(file, verdict.previous);
+                if (copy.ok) {
+                    archivedTo = copy.dest;
+                    steps.push(`archived → ${archivedTo}`);
+                }
+                else {
+                    const warning = `archive FAILED — ${file} is unarchived (it remains on the volume): ${copy.reason}`;
+                    steps.push(warning);
+                    warnings.push(warning);
+                }
+            }
+            const convo = await this.readConversation(file);
+            if (convo.state === "unreadable") {
+                const deferred = `could not read ${file} (${convo.reason}) — day NOT rolled over; retrying on the next start`;
+                steps.push(deferred);
+                return {
+                    verdict,
+                    steps,
+                    archivedTo,
+                    deferred,
+                    ...this.maybeInterview(today, prior, current, steps),
+                    ...(warnings.length ? { warnings } : {}),
+                };
+            }
+            const turns = parseConversation(convo.text);
+            steps.push(`compacted ${turns.length} turn${turns.length === 1 ? "" : "s"}`);
+            dayOpen = this.buildDayOpen(today, turns);
+            steps.push(`assembled opening context (${dayOpen.length} chars)`);
+            // The verdict was read before the awaits above. A second TUI starting
+            // the same morning may have rolled the day over meanwhile and spawned
+            // the fresh conversation; killing now would end THAT one. Its record
+            // says so — stand down and leave the day to it. This narrows the race,
+            // it does not close it: there is no cross-process lock, so a start
+            // whose re-read lands before the other's record can still kill the
+            // conversation the other start just spawned.
+            const now = readRolloverStateFile(this.opts.statePath);
+            if (now.state === "state" && now.value.last_open_date >= today) {
+                const stoodDown = `another start already rolled the day over to ${now.value.last_open_date} — nothing killed or queued`;
+                steps.push(stoodDown);
+                return { verdict, steps, archivedTo, stoodDown, ...(warnings.length ? { warnings } : {}) };
+            }
+            const kill = await this.killSession();
+            if (kill.state === "failed") {
+                // Yesterday's conversation may still be running: a day-open queued now
+                // would land in it, and a recorded day would never retry the rotation.
+                const deferred = `could not stop the companion session ${this.cfg.session} (${kill.reason}) — day NOT rolled over; retrying on the next start`;
+                steps.push(deferred);
+                return {
+                    verdict,
+                    steps,
+                    archivedTo,
+                    deferred,
+                    ...this.maybeInterview(today, prior, current, steps),
+                    ...(warnings.length ? { warnings } : {}),
+                };
+            }
+            steps.push(`killed tmux session ${this.cfg.session}`);
+            dayOpenFile = this.writeDayOpen(dayOpen, today);
+            steps.push(`queued day-open message → ${dayOpenFile}`);
+            current = this.record(today, archivedTo, prior);
+        }
+        const interview = this.maybeInterview(today, prior, current, steps);
+        return {
+            verdict,
+            steps,
+            archivedTo,
+            dayOpenFile,
+            dayOpen,
+            ...interview,
+            ...(warnings.length ? { warnings } : {}),
+        };
+    }
+}
+//# sourceMappingURL=rollover.js.map