@yagni-app/code 0.1.0 → 0.2.1

package/dist/extension/pipeline/activity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PURE curation layer for the live `/go` activity feed (spec §3).
+ *
+ * Mirrors `events.ts`: deterministic functions over canned `JsonEvent`s, with no
+ * clock, no I/O, and no model call. This is where "summary, not every event" is
+ * enforced — we surface assistant narration and concrete tool actions and drop
+ * everything else. Every function is defensive on missing / oddly-shaped data:
+ * it never throws, only ever reads basenames (no absolute paths leak into the
+ * feed), and falls back to the bare tool name when args are unusable.
+ */
+import { type ActivityLine, type JsonEvent, type StageTag } from "./types.js";
+/**
+ * Deterministic, defensive label for a tool action. Reads only the fields the
+ * spec table names, only ever surfaces a basename, and falls back to the bare
+ * tool name whenever the expected arg is missing or not a usable string.
+ */
+export declare function toolLabel(toolName: string, args?: Record<string, unknown>): string;
+/**
+ * The first non-empty line of an assistant text part, collapsed and clipped to
+ * `NARRATION_MAX`. Returns null when there is no usable headline.
+ */
+export declare function narrationHeadline(text: string): string | null;
+/**
+ * Curate one raw NDJSON event into an `ActivityLine`, or null to drop it.
+ *
+ * - assistant `message_end` with a text part -> narration (drops pure tool-call
+ *   turns and empty headlines)
+ * - `tool_execution_start` -> running action carrying its `toolCallId` + label
+ * - `tool_execution_end` -> resolving action (done / error) with no text; the
+ *   feed model resolves it against the running line by `toolCallId`
+ * - everything else -> null
+ *
+ * `tag` travels alongside the line (the feed attributes it to a stage / lens);
+ * the curated line content itself is stage-agnostic, so `tag` is not read here.
+ */
+export declare function eventToLine(ev: JsonEvent, _tag: StageTag): ActivityLine | null;
+//# sourceMappingURL=activity.d.ts.map

package/dist/extension/pipeline/activity.js

@@ -0,0 +1,151 @@
+/**
+ * PURE curation layer for the live `/go` activity feed (spec §3).
+ *
+ * Mirrors `events.ts`: deterministic functions over canned `JsonEvent`s, with no
+ * clock, no I/O, and no model call. This is where "summary, not every event" is
+ * enforced — we surface assistant narration and concrete tool actions and drop
+ * everything else. Every function is defensive on missing / oddly-shaped data:
+ * it never throws, only ever reads basenames (no absolute paths leak into the
+ * feed), and falls back to the bare tool name when args are unusable.
+ */
+import { NARRATION_MAX } from "./types.js";
+/** ~40 chars of a bash command is enough to recognize it without flooding the row. */
+const BASH_LABEL_MAX = 40;
+/** First usable non-empty string among the candidates, else undefined. */
+function firstString(...vals) {
+    for (const v of vals) {
+        if (typeof v === "string" && v.trim())
+            return v;
+    }
+    return undefined;
+}
+/** Last path segment only — never an absolute path. Empty string if unusable. */
+function basename(value) {
+    if (typeof value !== "string")
+        return "";
+    const parts = value.split(/[/\\]/).filter(Boolean);
+    return parts.length > 0 ? parts[parts.length - 1] : "";
+}
+/** Collapse whitespace and clip to `max`, appending an ellipsis when cut. */
+function clip(text, max) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= max)
+        return collapsed;
+    return `${collapsed.slice(0, max - 1)}…`;
+}
+/** Turn `record_decision` into a readable `record decision`. */
+function humanize(toolName) {
+    return toolName.replace(/_/g, " ");
+}
+/**
+ * Deterministic, defensive label for a tool action. Reads only the fields the
+ * spec table names, only ever surfaces a basename, and falls back to the bare
+ * tool name whenever the expected arg is missing or not a usable string.
+ */
+export function toolLabel(toolName, args) {
+    const a = args ?? {};
+    switch (toolName) {
+        case "read": {
+            const f = firstString(a.path, a.file_path);
+            return f ? `read ${basename(f)}` : toolName;
+        }
+        case "edit":
+        case "write": {
+            const f = firstString(a.path, a.file_path);
+            return f ? `edit ${basename(f)}` : toolName;
+        }
+        case "bash": {
+            const cmd = firstString(a.command);
+            return cmd ? `bash ${clip(cmd, BASH_LABEL_MAX)}` : toolName;
+        }
+        case "grep": {
+            const pattern = firstString(a.pattern);
+            return pattern ? `grep "${clip(pattern, BASH_LABEL_MAX)}"` : toolName;
+        }
+        case "find":
+        case "ls": {
+            const target = firstString(a.path, a.pattern);
+            return target ? `find ${basename(target) || target}` : toolName;
+        }
+        case "ask_yagni":
+        case "review_business_match":
+        case "record_decision":
+            return humanize(toolName);
+        default:
+            return toolName;
+    }
+}
+/**
+ * The first non-empty line of an assistant text part, collapsed and clipped to
+ * `NARRATION_MAX`. Returns null when there is no usable headline.
+ */
+export function narrationHeadline(text) {
+    if (typeof text !== "string")
+        return null;
+    const firstLine = text.split("\n").find((l) => l.trim().length > 0);
+    if (!firstLine)
+        return null;
+    const headline = clip(firstLine, NARRATION_MAX);
+    return headline.length > 0 ? headline : null;
+}
+/** The last text part of an assistant `message_end`, if any. */
+function lastAssistantText(ev) {
+    if (ev.message?.role !== "assistant")
+        return undefined;
+    const parts = ev.message.content ?? [];
+    for (let i = parts.length - 1; i >= 0; i--) {
+        const part = parts[i];
+        if (part.type === "text" && typeof part.text === "string")
+            return part.text;
+    }
+    return undefined;
+}
+/**
+ * Curate one raw NDJSON event into an `ActivityLine`, or null to drop it.
+ *
+ * - assistant `message_end` with a text part -> narration (drops pure tool-call
+ *   turns and empty headlines)
+ * - `tool_execution_start` -> running action carrying its `toolCallId` + label
+ * - `tool_execution_end` -> resolving action (done / error) with no text; the
+ *   feed model resolves it against the running line by `toolCallId`
+ * - everything else -> null
+ *
+ * `tag` travels alongside the line (the feed attributes it to a stage / lens);
+ * the curated line content itself is stage-agnostic, so `tag` is not read here.
+ */
+export function eventToLine(ev, _tag) {
+    switch (ev.type) {
+        case "message_end": {
+            const text = lastAssistantText(ev);
+            if (text === undefined)
+                return null;
+            const headline = narrationHeadline(text);
+            if (!headline)
+                return null;
+            return { kind: "narration", text: headline, state: "done" };
+        }
+        case "tool_execution_start": {
+            const line = {
+                kind: "action",
+                text: toolLabel(ev.toolName ?? "", ev.args),
+                state: "running",
+            };
+            if (ev.toolCallId !== undefined)
+                line.toolCallId = ev.toolCallId;
+            return line;
+        }
+        case "tool_execution_end": {
+            const line = {
+                kind: "action",
+                text: "",
+                state: ev.isError ? "error" : "done",
+            };
+            if (ev.toolCallId !== undefined)
+                line.toolCallId = ev.toolCallId;
+            return line;
+        }
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=activity.js.map

package/dist/extension/pipeline/activityFeed.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The TERMINAL renderer for the live `/go` feed (spec §4).
+ *
+ * State lives in {@link RunState}; this file is presentation only. It renders
+ * the boxed panel painted above the editor, owning no I/O and no clock: the
+ * caller (the `/go` handler) injects the elapsed string and the spinner frame so
+ * `render` stays a pure function of current state and is fully deterministic in
+ * tests.
+ *
+ * Every constraint here is a TUI constraint and stays here rather than moving
+ * into the model: `ROW_MAX` (terminal width), `MAX_VISIBLE_ACTIONS` (pi's
+ * 10-line widget cap), and the flat ring buffer's `FEED_WINDOW` bound. The
+ * desktop renders the same state into a scrolling pane where none of them apply.
+ */
+import { type ActivityLine, type PipelineProgress, type PipelineResult, type StageTag } from "./types.js";
+/** The minimal slice of pi's `Theme` the feed styles with (a subset, like the masthead). */
+export interface FeedTheme {
+    bold(s: string): string;
+    fg(color: string, s: string): string;
+}
+/** Spinner frames advanced by the caller; `render` is handed one frame, never a timer. */
+export declare const SPINNER_FRAMES: string[];
+/**
+ * Cap on the action rows actually rendered for the buffer stage. The ring buffer
+ * still holds up to FEED_WINDOW entries (state), but pi's aboveEditor widget keeps
+ * only the first MAX_WIDGET_LINES (10) lines and appends a "(widget truncated)"
+ * marker above that, dropping the NEWEST rows. We paint at most this many of the
+ * most-recent rows so the panel is header(1) + 5 stage rows + 4 actions = exactly
+ * 10 lines: at pi's ceiling (it truncates only ABOVE 10), and showing the newest
+ * actions rather than pi's first-10 (which would keep the oldest and add the marker).
+ */
+export declare const MAX_VISIBLE_ACTIONS = 4;
+export declare class ActivityFeed {
+    private readonly run;
+    /**
+     * The stage whose actions the ring buffer currently holds, and the buffer
+     * itself. Terminal-only: this flat, arrival-ordered ring is what lets the panel
+     * paint interleaved rows from the parallel review lenses under one `review`
+     * row, and it is bounded by FEED_WINDOW — the "can't get noisy" guarantee.
+     */
+    private bufferStageId;
+    private actions;
+    constructor(ticket: string);
+    /** Fold a structured progress signal into stage transitions + the header tally. */
+    applyProgress(p: PipelineProgress): void;
+    /** Fold one curated line: narration updates a stage summary; actions ride the ring buffer. */
+    applyEvent(line: ActivityLine, tag: StageTag): void;
+    /** The boxed panel lines (spec §4). Pure: spinner frame + elapsed are injected. */
+    render(theme: FeedTheme, elapsed?: string, spinnerFrame?: string): string[];
+    /**
+     * One compact line summarizing the finished run (spec §4). This is the feed's
+     * own terse outcome glyph-line and is intentionally DISTINCT from goCommand's
+     * `formatSummary`: that one is the durable `sendUserMessage` record and must
+     * also work on headless (no-feed) runs, so the two carry deliberately different
+     * phrasings rather than sharing one outcome-copy source.
+     */
+    finalLine(result: PipelineResult): string;
+}
+//# sourceMappingURL=activityFeed.d.ts.map

package/dist/extension/pipeline/activityFeed.js

@@ -0,0 +1,175 @@
+/**
+ * The TERMINAL renderer for the live `/go` feed (spec §4).
+ *
+ * State lives in {@link RunState}; this file is presentation only. It renders
+ * the boxed panel painted above the editor, owning no I/O and no clock: the
+ * caller (the `/go` handler) injects the elapsed string and the spinner frame so
+ * `render` stays a pure function of current state and is fully deterministic in
+ * tests.
+ *
+ * Every constraint here is a TUI constraint and stays here rather than moving
+ * into the model: `ROW_MAX` (terminal width), `MAX_VISIBLE_ACTIONS` (pi's
+ * 10-line widget cap), and the flat ring buffer's `FEED_WINDOW` bound. The
+ * desktop renders the same state into a scrolling pane where none of them apply.
+ */
+import { BRAND_NAME } from "../branding.js";
+import { RunState } from "./runState.js";
+import { FEED_WINDOW, } from "./types.js";
+/** Spinner frames advanced by the caller; `render` is handed one frame, never a timer. */
+export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Defensive cap so a row never blows the terminal width even with a long summary. */
+const ROW_MAX = 96;
+/**
+ * Cap on the action rows actually rendered for the buffer stage. The ring buffer
+ * still holds up to FEED_WINDOW entries (state), but pi's aboveEditor widget keeps
+ * only the first MAX_WIDGET_LINES (10) lines and appends a "(widget truncated)"
+ * marker above that, dropping the NEWEST rows. We paint at most this many of the
+ * most-recent rows so the panel is header(1) + 5 stage rows + 4 actions = exactly
+ * 10 lines: at pi's ceiling (it truncates only ABOVE 10), and showing the newest
+ * actions rather than pi's first-10 (which would keep the oldest and add the marker).
+ */
+export const MAX_VISIBLE_ACTIONS = 4;
+/** Compact outcome phrasing per stop reason (no em-dashes). */
+const FINAL_REASON = {
+    clean: "clean, no blockers remain",
+    round_cap: "round cap reached, blockers remain",
+    aborted: "aborted before review completed",
+    failed: "a stage failed before completing",
+    no_changes: "no changes produced, the implement stage wrote nothing. Re-run /go",
+    budget_exceeded: "budget ceiling reached, stopped before finishing",
+    partial: "a stage stopped early, partial changes left in your working tree",
+};
+function glyphForStatus(status, spinnerFrame) {
+    switch (status) {
+        case "done":
+            return "✔";
+        case "active":
+            return spinnerFrame;
+        case "failed":
+            return "✗";
+        default:
+            return "○";
+    }
+}
+function glyphForAction(state, spinnerFrame) {
+    if (state === "done")
+        return "✔";
+    if (state === "error")
+        return "✗";
+    return spinnerFrame;
+}
+const themeColorForStatus = {
+    done: "success",
+    active: "accent",
+    failed: "error",
+    pending: "dim",
+};
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+function clipRow(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}
+function countBlocking(result) {
+    return result.findings.filter((f) => f.severity === "critical" || f.severity === "high").length;
+}
+export class ActivityFeed {
+    run;
+    /**
+     * The stage whose actions the ring buffer currently holds, and the buffer
+     * itself. Terminal-only: this flat, arrival-ordered ring is what lets the panel
+     * paint interleaved rows from the parallel review lenses under one `review`
+     * row, and it is bounded by FEED_WINDOW — the "can't get noisy" guarantee.
+     */
+    bufferStageId;
+    actions = [];
+    constructor(ticket) {
+        // The terminal surface has no run id and no clock: `render` is handed the
+        // elapsed string and spinner frame, so timestamps are never read here.
+        this.run = new RunState({ runId: "", ticket, startedAt: 0 });
+    }
+    /** Fold a structured progress signal into stage transitions + the header tally. */
+    applyProgress(p) {
+        // A per-lens signal is a desktop concern: it must not steal the buffer from
+        // the review stage that owns it, nor reset it mid fan-out.
+        if (p.kind === "stage_start" && !p.lens && p.stageId !== this.bufferStageId) {
+            this.bufferStageId = p.stageId;
+            this.actions = [];
+        }
+        this.run.applyProgress(p);
+    }
+    /** Fold one curated line: narration updates a stage summary; actions ride the ring buffer. */
+    applyEvent(line, tag) {
+        this.run.applyLine(line, tag);
+        if (line.kind !== "action")
+            return;
+        if (line.state === "running") {
+            if (this.bufferStageId === undefined)
+                this.bufferStageId = tag.stageId;
+            this.actions.push({ ...line });
+            if (this.actions.length > FEED_WINDOW)
+                this.actions.shift();
+            return;
+        }
+        if (line.toolCallId === undefined)
+            return;
+        const match = this.actions.find((a) => a.toolCallId === line.toolCallId);
+        if (match)
+            match.state = line.state;
+    }
+    /** The boxed panel lines (spec §4). Pure: spinner frame + elapsed are injected. */
+    render(theme, elapsed, spinnerFrame = SPINNER_FRAMES[0]) {
+        const { ticket, round, findingsTotal, findingsBlocking } = this.run.header();
+        const headerParts = [`${BRAND_NAME} · /go ${ticket}`, `round ${round}`, plural(findingsTotal, "finding")];
+        if (findingsBlocking > 0)
+            headerParts.push(`${findingsBlocking} blocking`);
+        if (elapsed)
+            headerParts.push(elapsed);
+        const header = theme.bold(clipRow(headerParts.join(" · "), ROW_MAX));
+        const lines = [header];
+        // Only the lens-less stage rows: the review fan-out's per-lens children are
+        // the desktop's business, and surfacing them here would break the 10-line cap.
+        for (const s of this.run.stageAgents()) {
+            // The FINISH row only exists once the stage actually starts (a clean stop):
+            // hiding it while pending keeps every non-clean run's panel byte-identical
+            // to the pre-FINISH layout and inside pi's 10-line widget cap.
+            if (s.id === "finish" && s.status === "pending")
+                continue;
+            const glyph = glyphForStatus(s.status, spinnerFrame);
+            const label = s.stageId.padEnd(9);
+            const row = clipRow(`${glyph} ${label}${s.summary}`.trimEnd(), ROW_MAX);
+            lines.push(theme.fg(themeColorForStatus[s.status], row));
+            // The ring buffer renders under its OWNING stage (see RunState), so a
+            // just-finished stage's resolved actions stay briefly visible beneath its ✔
+            // row. This keeps the immediate stage_done paint useful rather than blanking
+            // the actions the instant the stage flips to "done".
+            if (s.stageId === this.bufferStageId) {
+                // Only the most-recent rows render. A taller panel trips pi's
+                // MAX_WIDGET_LINES=10 truncation, which keeps the FIRST 10 lines and
+                // drops the newest actions plus a "(widget truncated)" marker; capping
+                // here keeps the newest actions visible and avoids the marker.
+                for (const a of this.actions.slice(-MAX_VISIBLE_ACTIONS)) {
+                    const aGlyph = glyphForAction(a.state, spinnerFrame);
+                    lines.push(theme.fg("dim", clipRow(`   ↳ ${aGlyph} ${a.text}`, ROW_MAX)));
+                }
+            }
+        }
+        return lines;
+    }
+    /**
+     * One compact line summarizing the finished run (spec §4). This is the feed's
+     * own terse outcome glyph-line and is intentionally DISTINCT from goCommand's
+     * `formatSummary`: that one is the durable `sendUserMessage` record and must
+     * also work on headless (no-feed) runs, so the two carry deliberately different
+     * phrasings rather than sharing one outcome-copy source.
+     */
+    finalLine(result) {
+        const glyph = result.stopReason === "clean" ? "✔" : result.stopReason === "round_cap" ? "⚠" : "✗";
+        const blocking = countBlocking(result);
+        return (`${glyph} ${BRAND_NAME} /go ${this.run.header().ticket}: ${FINAL_REASON[result.stopReason]} · ` +
+            `${plural(result.rounds.length, "round")} · ${plural(result.findings.length, "finding")} (${blocking} blocking)`);
+    }
+}
+//# sourceMappingURL=activityFeed.js.map

package/dist/extension/pipeline/budget.d.ts

@@ -0,0 +1,48 @@
+/**
+ * R3-b - run-level budget / turn ceiling, enforced orchestrator-side.
+ *
+ * The frontier harnesses bound a run with a turn/budget ceiling; /go had none, so
+ * a pathological loop could spend without limit. These PURE helpers aggregate the
+ * per-stage usage the runner already records (StageResult.usage) across the whole
+ * run (build stages + every review lens + each fix) and report when an aggregate
+ * crosses a ceiling. The orchestrator stops honestly with `budget_exceeded` rather
+ * than running on.
+ *
+ * The turn cap is enforced here via aggregated `usage.turns` (not a pi --max-turns
+ * flag, which is unverified in the pi flag set; that is on the upstream-pi
+ * wishlist). Ceilings are generous safety bounds, not tight budgets, so a normal
+ * run never trips them.
+ */
+import type { ReviewRound, StageResult } from "./types.js";
+/** Aggregated usage across a whole run. */
+export interface RunUsage {
+    turns: number;
+    cost: number;
+    input: number;
+    output: number;
+}
+/** The run-level ceilings. */
+export interface RunBudget {
+    /** Max aggregate assistant turns across all stages. */
+    maxTurns: number;
+    /** Max aggregate cost (same unit as StageUsage.cost). */
+    maxCost: number;
+    /** Max aggregate input+output tokens. */
+    maxTokens: number;
+}
+/**
+ * Generous default ceilings: a 3-round /go fans out review across 3 lenses on top
+ * of the build half, so dozens of turns and millions of tokens are normal; these
+ * only catch a runaway. Tunable per lane.
+ */
+export declare const DEFAULT_RUN_BUDGET: RunBudget;
+export declare const EMPTY_RUN_USAGE: RunUsage;
+export declare function addRunUsage(a: RunUsage, b: RunUsage): RunUsage;
+/** Sum usage across the build/fix stages AND every review lens result. */
+export declare function aggregateRunUsage(stages: StageResult[], rounds: ReviewRound[]): RunUsage;
+/**
+ * Return an honest reason string when an aggregate usage crosses any ceiling, else
+ * null. Checked at each stage boundary so the run stops at the first crossing.
+ */
+export declare function exceedsBudget(usage: RunUsage, budget: RunBudget): string | null;
+//# sourceMappingURL=budget.d.ts.map

package/dist/extension/pipeline/budget.js

@@ -0,0 +1,68 @@
+/**
+ * R3-b - run-level budget / turn ceiling, enforced orchestrator-side.
+ *
+ * The frontier harnesses bound a run with a turn/budget ceiling; /go had none, so
+ * a pathological loop could spend without limit. These PURE helpers aggregate the
+ * per-stage usage the runner already records (StageResult.usage) across the whole
+ * run (build stages + every review lens + each fix) and report when an aggregate
+ * crosses a ceiling. The orchestrator stops honestly with `budget_exceeded` rather
+ * than running on.
+ *
+ * The turn cap is enforced here via aggregated `usage.turns` (not a pi --max-turns
+ * flag, which is unverified in the pi flag set; that is on the upstream-pi
+ * wishlist). Ceilings are generous safety bounds, not tight budgets, so a normal
+ * run never trips them.
+ */
+/**
+ * Generous default ceilings: a 3-round /go fans out review across 3 lenses on top
+ * of the build half, so dozens of turns and millions of tokens are normal; these
+ * only catch a runaway. Tunable per lane.
+ */
+export const DEFAULT_RUN_BUDGET = {
+    maxTurns: 400,
+    maxCost: 50,
+    maxTokens: 8_000_000,
+};
+export const EMPTY_RUN_USAGE = { turns: 0, cost: 0, input: 0, output: 0 };
+export function addRunUsage(a, b) {
+    return {
+        turns: a.turns + b.turns,
+        cost: a.cost + b.cost,
+        input: a.input + b.input,
+        output: a.output + b.output,
+    };
+}
+/** Sum usage across the build/fix stages AND every review lens result. */
+export function aggregateRunUsage(stages, rounds) {
+    const acc = { ...EMPTY_RUN_USAGE };
+    const add = (u) => {
+        acc.turns += u.turns;
+        acc.cost += u.cost;
+        acc.input += u.input;
+        acc.output += u.output;
+    };
+    for (const s of stages)
+        add(s.usage);
+    for (const r of rounds)
+        for (const l of r.lensResults)
+            add(l.usage);
+    return acc;
+}
+/**
+ * Return an honest reason string when an aggregate usage crosses any ceiling, else
+ * null. Checked at each stage boundary so the run stops at the first crossing.
+ */
+export function exceedsBudget(usage, budget) {
+    if (usage.turns > budget.maxTurns) {
+        return `turn ceiling reached (${usage.turns} of ${budget.maxTurns} model turns)`;
+    }
+    if (usage.cost > budget.maxCost) {
+        return `cost ceiling reached (${usage.cost.toFixed(2)} of ${budget.maxCost})`;
+    }
+    const tokens = usage.input + usage.output;
+    if (tokens > budget.maxTokens) {
+        return `token ceiling reached (${tokens} of ${budget.maxTokens} tokens)`;
+    }
+    return null;
+}
+//# sourceMappingURL=budget.js.map

package/dist/extension/pipeline/checkpoint.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Fail-soft {@link CheckpointStore} implementations — the durable substrate
+ * behind /go resume.
+ *
+ * Three stores, all sharing the iron contract: NEVER throw, NEVER block /go.
+ *  - {@link makeFileCheckpointStore} — the durable PRIMARY. An append-only NDJSON
+ *    file at `~/.yagni-code/runs/<sha1(sessionKey)>.ndjson` (mkdir 0700, file
+ *    0600 — mirrors credentials.ts). Session-independent and auth-free, so a
+ *    LATER pi session (or one started after `/new`) can still read where /go
+ *    left off, even when the backend was unreachable. A torn final write is
+ *    harmless: load drops any unparseable line (the classic crash artifact).
+ *  - {@link makePiJournalCheckpointStore} — a MIRROR into pi's native append-only
+ *    session journal via `pi.appendEntry` / `sessionManager.getEntries`, the
+ *    pi-idiomatic persistence the user asked about. Constructed from function
+ *    seams so it is unit-testable without a pi process.
+ *  - {@link makeCombinedCheckpointStore} — writes to all stores; reads from the
+ *    first non-empty (file primary).
+ */
+import type { CheckpointStore } from "./types.js";
+export declare function _setCheckpointHomeForTest(dir: string | null): void;
+export declare function makeFileCheckpointStore(sessionKey: string): CheckpointStore;
+/** The pi customType under which checkpoint records live in the session journal. */
+export declare const PI_CHECKPOINT_CUSTOM_TYPE = "yagni-go-checkpoint";
+/** Function seams onto pi's ExtensionAPI/SessionManager (so this is testable without pi). */
+export interface PiJournalSeams {
+    appendEntry: (customType: string, data: unknown) => void;
+    getEntries: () => unknown[];
+}
+export declare function makePiJournalCheckpointStore(sessionKey: string, seams: PiJournalSeams): CheckpointStore;
+export declare function makeCombinedCheckpointStore(stores: CheckpointStore[]): CheckpointStore;
+//# sourceMappingURL=checkpoint.d.ts.map