@yagni-app/code-staging 0.0.0 → 0.1.0-staging.997.1

package/dist/extension/pipeline/resume.js

@@ -0,0 +1,106 @@
+/**
+ * PURE resume-decision core — the analogue of `findings.ts#shouldStop`.
+ *
+ * Given the append-only checkpoint journal for a run key and a LIVE workspace
+ * snapshot, decide whether /go can safely resume the bounded review→fix loop,
+ * must warn about a partially-built / diverged tree, or should just run fresh.
+ *
+ * Safety boundary (the whole point): we only auto-resume the EXPENSIVE half (the
+ * review→fix loop) and only when the build half fully completed AND the live git
+ * tree still matches the boundary we checkpointed. A crash mid-build, or a tree
+ * that drifted since the checkpoint, would risk double-applying edits if we
+ * replayed — so those resolve to `warn_partial` (warn + run fresh), never a
+ * silent replay. Anything unknowable fails OPEN to `fresh` (mirrors
+ * `workspaceChanged`). The fold never throws.
+ */
+import { EMPTY_RUN_USAGE } from "./budget.js";
+/** Two snapshots match only when BOTH are present, tracked, and identical (HEAD + status). */
+function snapshotsMatch(a, b) {
+    return Boolean(a) && Boolean(b) && a.tracked && b.tracked && a.head === b.head && a.status === b.status;
+}
+/** The last record of a given kind, or undefined. */
+function lastOfKind(records, kind) {
+    for (let i = records.length - 1; i >= 0; i -= 1) {
+        if (records[i]?.kind === kind)
+            return records[i];
+    }
+    return undefined;
+}
+export function planResume(records, liveSnapshot) {
+    try {
+        if (!Array.isArray(records) || records.length === 0)
+            return { mode: "fresh" };
+        // A terminal run_finish means the run completed (even `round_cap`) — a
+        // completed run is NOT an interrupted one, so it is never resumable. A
+        // finish_done is equally terminal: the FINISH stage only runs after a clean
+        // stop, so a crash in the narrow window before run_finish lands must not
+        // read as "resumable" over a tree the FINISH commit has since moved.
+        if (records.some((r) => r?.kind === "run_finish" || r?.kind === "finish_done"))
+            return { mode: "fresh" };
+        const runStart = records.find((r) => r?.kind === "run_start");
+        if (!runStart)
+            return { mode: "fresh" }; // no anchor → nothing trustworthy to resume
+        const ticket = runStart.ticket;
+        const buildDone = lastOfKind(records, "build_done");
+        if (!buildDone) {
+            // Interrupted during the build half: the tree may hold partial edits, so
+            // replaying review against it would be wrong. Warn; the caller runs fresh.
+            return { mode: "warn_partial", reason: "build_interrupted", ticket };
+        }
+        const roundDones = records.filter((r) => r?.kind === "round_done");
+        const latest = roundDones.length > 0 ? maxByRound(roundDones) : buildDone;
+        // Unknowable tree (not a git work tree) → fail open to fresh rather than
+        // claim a resume we cannot verify.
+        if (!liveSnapshot?.tracked)
+            return { mode: "fresh" };
+        // The live tree must still be exactly where we checkpointed it; otherwise an
+        // orphaned child or a manual edit drifted it and replay is unsafe.
+        if (!snapshotsMatch(latest.snapshot, liveSnapshot)) {
+            return { mode: "warn_partial", reason: "tree_diverged", ticket };
+        }
+        if (roundDones.length === 0) {
+            // Build done, no round completed → resume at round 1 against implement output.
+            return {
+                mode: "resume_loop",
+                round: 1,
+                reviewInput: buildDone.reviewInput ?? "",
+                priorRounds: [],
+                priorUsage: buildDone.usage ?? EMPTY_RUN_USAGE,
+                ...handle(runStart),
+                ticket,
+            };
+        }
+        const maxRound = Math.max(...roundDones.map((r) => r.round ?? 0));
+        const lastRound = roundDones.find((r) => (r.round ?? 0) === maxRound) ?? buildDone;
+        const priorRounds = roundDones
+            .slice()
+            .sort((a, b) => (a.round ?? 0) - (b.round ?? 0))
+            .map((r) => ({ round: r.round ?? 0, lensResults: [], findings: r.findings ?? [] }));
+        return {
+            mode: "resume_loop",
+            round: maxRound + 1,
+            reviewInput: lastRound.reviewInput ?? "",
+            priorRounds,
+            priorUsage: lastRound.usage ?? buildDone.usage ?? EMPTY_RUN_USAGE,
+            ...handle(runStart),
+            ticket,
+        };
+    }
+    catch {
+        return { mode: "fresh" };
+    }
+}
+/** The record carrying the highest `round`. */
+function maxByRound(records) {
+    return records.reduce((a, b) => ((b.round ?? 0) >= (a.round ?? 0) ? b : a));
+}
+/** Pull the optional backend handle off the run_start record (omit undefined keys). */
+function handle(runStart) {
+    const out = {};
+    if (runStart.runId)
+        out.runId = runStart.runId;
+    if (runStart.workItemId)
+        out.workItemId = runStart.workItemId;
+    return out;
+}
+//# sourceMappingURL=resume.js.map

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

@@ -0,0 +1,112 @@
+/**
+ * The /go run registry (spec §3b — detached-by-default).
+ *
+ * Detached runs outlive the prompt that started them, so /go needs one place
+ * that answers "what is running / finished / interrupted?": a module-scoped
+ * IN-MEMORY registry (the live truth for THIS process: in-flight guard,
+ * MAX_CONCURRENT_RUNS, the completion promise) mirrored to an append-only
+ * NDJSON file at `~/.yagni-code/registry.ndjson` (dir 0700, file 0600 —
+ * mirrors checkpoint.ts) so a LATER session can list finished runs, spot an
+ * interrupted one, and resume into its worktree.
+ *
+ * The mirror is append-only and torn-line-tolerant (same crash model as
+ * checkpoint.ts): every state change appends the FULL row again and readers
+ * fold last-write-wins by runId, so a torn final write costs at most the last
+ * update, never the file. All writes are fail-soft — registry bookkeeping must
+ * never break /go.
+ *
+ * Liveness is decided by the PURE {@link classifyRunLiveness}: a non-terminal
+ * row is `in_flight` when this process holds it, otherwise the run's checkpoint
+ * journal decides — recent activity (< 30 min) means it is probably running in
+ * another process (`active_elsewhere`), stale means `interrupted` (a resume
+ * candidate).
+ */
+import type { CheckpointRecord, StopReason } from "./types.js";
+/** Bound on simultaneously in-flight /go runs in one process (spec §3b). */
+export declare const MAX_CONCURRENT_RUNS = 3;
+/**
+ * A non-terminal row whose journal has been quiet this long is treated as
+ * INTERRUPTED (its process died) rather than still running elsewhere. Sits
+ * comfortably past the 5-min run heartbeat and the server reaper's 30-min
+ * staleness window so the two views agree.
+ */
+export declare const JOURNAL_STALE_MS: number;
+/**
+ * One registry row (the spec's frozen shape). `status` is `running` until the
+ * run reaches a terminal outcome, then the honest stop reason; `cleaned` marks
+ * a terminal row whose worktree /go-clean has removed. `runId` is the LOCAL
+ * run identity (minted before the backend run row exists — the worktree dir and
+ * UI key derive from its first 8 chars), not the backend runs-row id.
+ */
+export interface RunRegistryRow {
+    runId: string;
+    ticket: string;
+    sessionKey: string;
+    repo?: string;
+    /** Absent for an in-place (--here) run. */
+    worktreePath?: string;
+    branch?: string;
+    status: RunRegistryStatus;
+    startedAt: number;
+    commitSha?: string;
+    prUrl?: string;
+}
+export type RunRegistryStatus = "running" | "cleaned" | StopReason;
+/** Everything except `running` is terminal (the run is not in flight anywhere). */
+export declare function isTerminalStatus(status: RunRegistryStatus): boolean;
+/** How a registry row relates to live execution right now. */
+export type RunLiveness = "in_flight" | "active_elsewhere" | "interrupted" | "terminal";
+/**
+ * PURE liveness verdict for one row. `inFlight` is this process's in-memory
+ * truth; `lastJournalTs` is the newest checkpoint-journal timestamp for the
+ * row's sessionKey (fall back to `startedAt` when the run never journaled).
+ */
+export declare function classifyRunLiveness(row: RunRegistryRow, opts: {
+    inFlight: boolean;
+    lastJournalTs?: number;
+    now: number;
+}): RunLiveness;
+/** The newest checkpoint timestamp in a run's journal (0 when empty). */
+export declare function lastJournalTs(records: CheckpointRecord[]): number;
+/**
+ * Fold raw NDJSON mirror lines into rows, last-write-wins by runId, preserving
+ * first-seen order. Pure + torn-line-tolerant: unparseable or shape-less lines
+ * are dropped (the classic crash artifact), never fatal.
+ */
+export declare function foldRegistryLines(lines: string[]): RunRegistryRow[];
+export declare function _setRegistryHomeForTest(dir: string | null): void;
+/** The append-only NDJSON mirror file. */
+export declare function registryFile(): string;
+/** Where detached run worktrees live (never inside the repo — spec §6). */
+export declare function worktreesDir(): string;
+/** Test seam: clear the in-memory half (simulates a process restart; the mirror survives). */
+export declare function _resetRunRegistryForTest(): void;
+/** Mark a run in-flight in this process and mirror the row. Never throws. */
+export declare function beginRun(row: RunRegistryRow): void;
+/** Attach the detached completion promise to an in-flight run (fail-soft no-op when absent). */
+export declare function trackRunPromise(runId: string, promise: Promise<void>): void;
+/**
+ * Settle an in-flight run: merge the terminal patch, drop it from the in-memory
+ * active set, and mirror the final row. Safe to call for an unknown runId: the
+ * patch lands against the last known mirror row when one exists, or against the
+ * patch itself when the caller supplied a full row (the /go-clean path, whose
+ * rows may come through an injected registry read).
+ */
+export declare function settleRun(runId: string, patch: Partial<RunRegistryRow> & {
+    status: RunRegistryStatus;
+}): void;
+/** How many runs this process currently has in flight. */
+export declare function activeRunCount(): number;
+/** The in-flight row for a ticket in THIS process, if any (the same-ticket guard). */
+export declare function findActiveRunByTicket(ticket: string): RunRegistryRow | undefined;
+/** Is this runId in flight in THIS process? */
+export declare function isRunInFlight(runId: string): boolean;
+/** Test seam: await every in-flight run's completion promise. */
+export declare function _awaitActiveRunsForTest(): Promise<void>;
+/**
+ * The merged registry view: the NDJSON mirror folded last-write-wins, with this
+ * process's in-memory rows overlaid (they are the fresher truth when a mirror
+ * write was lost). Never throws; an unreadable mirror yields the in-memory rows.
+ */
+export declare function loadRegistryRows(): RunRegistryRow[];
+//# sourceMappingURL=runRegistry.d.ts.map

package/dist/extension/pipeline/runRegistry.js

@@ -0,0 +1,202 @@
+/**
+ * The /go run registry (spec §3b — detached-by-default).
+ *
+ * Detached runs outlive the prompt that started them, so /go needs one place
+ * that answers "what is running / finished / interrupted?": a module-scoped
+ * IN-MEMORY registry (the live truth for THIS process: in-flight guard,
+ * MAX_CONCURRENT_RUNS, the completion promise) mirrored to an append-only
+ * NDJSON file at `~/.yagni-code/registry.ndjson` (dir 0700, file 0600 —
+ * mirrors checkpoint.ts) so a LATER session can list finished runs, spot an
+ * interrupted one, and resume into its worktree.
+ *
+ * The mirror is append-only and torn-line-tolerant (same crash model as
+ * checkpoint.ts): every state change appends the FULL row again and readers
+ * fold last-write-wins by runId, so a torn final write costs at most the last
+ * update, never the file. All writes are fail-soft — registry bookkeeping must
+ * never break /go.
+ *
+ * Liveness is decided by the PURE {@link classifyRunLiveness}: a non-terminal
+ * row is `in_flight` when this process holds it, otherwise the run's checkpoint
+ * journal decides — recent activity (< 30 min) means it is probably running in
+ * another process (`active_elsewhere`), stale means `interrupted` (a resume
+ * candidate).
+ */
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { codeStateHome } from "../stateHome.js";
+/** Bound on simultaneously in-flight /go runs in one process (spec §3b). */
+export const MAX_CONCURRENT_RUNS = 3;
+/**
+ * A non-terminal row whose journal has been quiet this long is treated as
+ * INTERRUPTED (its process died) rather than still running elsewhere. Sits
+ * comfortably past the 5-min run heartbeat and the server reaper's 30-min
+ * staleness window so the two views agree.
+ */
+export const JOURNAL_STALE_MS = 30 * 60_000;
+/** Everything except `running` is terminal (the run is not in flight anywhere). */
+export function isTerminalStatus(status) {
+    return status !== "running";
+}
+/**
+ * PURE liveness verdict for one row. `inFlight` is this process's in-memory
+ * truth; `lastJournalTs` is the newest checkpoint-journal timestamp for the
+ * row's sessionKey (fall back to `startedAt` when the run never journaled).
+ */
+export function classifyRunLiveness(row, opts) {
+    if (isTerminalStatus(row.status))
+        return "terminal";
+    if (opts.inFlight)
+        return "in_flight";
+    const last = opts.lastJournalTs ?? row.startedAt;
+    return opts.now - last > JOURNAL_STALE_MS ? "interrupted" : "active_elsewhere";
+}
+/** The newest checkpoint timestamp in a run's journal (0 when empty). */
+export function lastJournalTs(records) {
+    let max = 0;
+    for (const r of records) {
+        if (typeof r?.ts === "number" && r.ts > max)
+            max = r.ts;
+    }
+    return max;
+}
+/**
+ * Fold raw NDJSON mirror lines into rows, last-write-wins by runId, preserving
+ * first-seen order. Pure + torn-line-tolerant: unparseable or shape-less lines
+ * are dropped (the classic crash artifact), never fatal.
+ */
+export function foldRegistryLines(lines) {
+    const byId = new Map();
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (!row || typeof row.runId !== "string" || typeof row.ticket !== "string")
+                continue;
+            if (typeof row.sessionKey !== "string" || typeof row.status !== "string")
+                continue;
+            byId.set(row.runId, row);
+        }
+        catch {
+            /* torn/garbage line — drop it, keep the rest */
+        }
+    }
+    return [...byId.values()];
+}
+// ---------------------------------------------------------------------------
+// State-dir seams (mirrors checkpoint.ts `_setCheckpointHomeForTest`).
+// ---------------------------------------------------------------------------
+let homeOverride = null;
+export function _setRegistryHomeForTest(dir) {
+    homeOverride = dir;
+}
+function registryHome() {
+    return codeStateHome(homeOverride);
+}
+/** The append-only NDJSON mirror file. */
+export function registryFile() {
+    return join(registryHome(), "registry.ndjson");
+}
+/** Where detached run worktrees live (never inside the repo — spec §6). */
+export function worktreesDir() {
+    return join(registryHome(), "worktrees");
+}
+const active = new Map();
+/** Test seam: clear the in-memory half (simulates a process restart; the mirror survives). */
+export function _resetRunRegistryForTest() {
+    active.clear();
+}
+/** Fail-soft append of one full row to the mirror (self-heals a torn previous write). */
+function appendRow(row) {
+    try {
+        mkdirSync(registryHome(), { recursive: true, mode: 0o700 });
+        const file = registryFile();
+        let prefix = "";
+        try {
+            const existing = readFileSync(file);
+            if (existing.length > 0 && existing[existing.length - 1] !== 0x0a)
+                prefix = "\n";
+        }
+        catch {
+            /* no file yet — nothing to heal */
+        }
+        appendFileSync(file, `${prefix}${JSON.stringify(row)}\n`, { mode: 0o600 });
+    }
+    catch {
+        /* fail-soft: registry bookkeeping must never break /go */
+    }
+}
+/** Mark a run in-flight in this process and mirror the row. Never throws. */
+export function beginRun(row) {
+    active.set(row.runId, { row });
+    appendRow(row);
+}
+/** Attach the detached completion promise to an in-flight run (fail-soft no-op when absent). */
+export function trackRunPromise(runId, promise) {
+    const entry = active.get(runId);
+    if (entry)
+        entry.promise = promise;
+}
+/**
+ * Settle an in-flight run: merge the terminal patch, drop it from the in-memory
+ * active set, and mirror the final row. Safe to call for an unknown runId: the
+ * patch lands against the last known mirror row when one exists, or against the
+ * patch itself when the caller supplied a full row (the /go-clean path, whose
+ * rows may come through an injected registry read).
+ */
+export function settleRun(runId, patch) {
+    const entry = active.get(runId);
+    const base = entry?.row ??
+        loadRegistryRows().find((r) => r.runId === runId) ??
+        (isFullRow(patch) ? patch : undefined);
+    active.delete(runId);
+    if (!base)
+        return;
+    appendRow({ ...base, ...patch, runId: base.runId ?? runId });
+}
+/** Does a settle patch carry the whole row shape (usable as its own base)? */
+function isFullRow(patch) {
+    return (typeof patch.runId === "string" &&
+        typeof patch.ticket === "string" &&
+        typeof patch.sessionKey === "string" &&
+        typeof patch.startedAt === "number");
+}
+/** How many runs this process currently has in flight. */
+export function activeRunCount() {
+    return active.size;
+}
+/** The in-flight row for a ticket in THIS process, if any (the same-ticket guard). */
+export function findActiveRunByTicket(ticket) {
+    for (const entry of active.values()) {
+        if (entry.row.ticket === ticket)
+            return entry.row;
+    }
+    return undefined;
+}
+/** Is this runId in flight in THIS process? */
+export function isRunInFlight(runId) {
+    return active.has(runId);
+}
+/** Test seam: await every in-flight run's completion promise. */
+export async function _awaitActiveRunsForTest() {
+    await Promise.all([...active.values()].map((e) => e.promise ?? Promise.resolve()));
+}
+/**
+ * The merged registry view: the NDJSON mirror folded last-write-wins, with this
+ * process's in-memory rows overlaid (they are the fresher truth when a mirror
+ * write was lost). Never throws; an unreadable mirror yields the in-memory rows.
+ */
+export function loadRegistryRows() {
+    let rows = [];
+    try {
+        rows = foldRegistryLines(readFileSync(registryFile(), "utf8").split("\n"));
+    }
+    catch {
+        rows = [];
+    }
+    const byId = new Map(rows.map((r) => [r.runId, r]));
+    for (const entry of active.values())
+        byId.set(entry.row.runId, entry.row);
+    return [...byId.values()];
+}
+//# sourceMappingURL=runRegistry.js.map

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

@@ -0,0 +1,152 @@
+/**
+ * The `/go` run-session adapter.
+ *
+ * Wraps the device-token `/api/yagni-code/runs*` endpoints so a YAGNI Code
+ * pipeline run becomes a tracked `runs` row visible on the Work page: open the
+ * run (`start`), stream each pipeline stage (`stage`), bank an in-loop
+ * correction (`correction`), and close it with an honest outcome (`finish`).
+ *
+ * CRITICAL invariant: recording must NEVER break the pipeline. Every call is
+ * fail-soft — it never throws. `start` resolves to a typed outcome that
+ * distinguishes a tracked run from an untracked one (flag off, unauthorized, or
+ * the backend unreachable/erroring) so the caller can surface a notice instead
+ * of failing silently; the post-start verbs (`stage`/`correction`/`finish`) stay
+ * silent no-ops. `/go` runs to completion regardless of the recording outcome.
+ *
+ * Mirrors the fetch-seam shape of {@link makeRecordEngineeringContextTool}
+ * (`baseUrl` + injectable `getToken` + `fetchImpl`) so it is unit-testable
+ * without a network and reuses the same auth convention.
+ */
+/** Options for {@link makeRunSession}. */
+export interface RunSessionOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    /**
+     * Backoff sleep + jitter seams, threaded into {@link resilientFetch} so the
+     * retry path is deterministic and instant under test. Default to the real
+     * timer / Math.random in production.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    /**
+     * Opt-in debug sink for diagnosing a recording failure (the fail-soft path
+     * otherwise collapses 402/5xx/2xx-bad-body/unreachable into one silent
+     * "error"). Only ever receives a token-free line: the path, the numeric HTTP
+     * status, a capped slice of the SERVER response body, or a network error
+     * message. NEVER the request headers (the bearer token) or the request body.
+     * Injected for deterministic tests; defaults to an env-gated stderr writer.
+     */
+    debug?: (line: string) => void;
+    /**
+     * Environment seam for the debug gate, matching `config.ts`/`verify.ts`. The
+     * debug sink only fires when `YAGNI_CODE_DEBUG` is set here (default
+     * `process.env`), so existing callers that inject neither `debug` nor `env`
+     * stay silent unless the operator opts in.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/** The handle returned by a successful `start` (or supplied via `bind`). */
+export interface RunSessionHandle {
+    runId: string;
+    workItemId: string;
+}
+/**
+ * The result of a successful `start`: the handle plus the server's governance
+ * verdict (`gated` = the work item needs approval in the app before it shows as
+ * executing, so /go should warn rather than silently proceed).
+ */
+export interface RunStartResult extends RunSessionHandle {
+    gated: boolean;
+    gatedReason?: string;
+}
+/**
+ * Why a run could not be recorded, derived from the endpoint's HTTP status so
+ * the caller can show an actionable notice:
+ *  - `disabled`     — 404: the `yagni_code.work_tracking` flag is off for this
+ *                     workspace (the write endpoints 404 to hide themselves).
+ *  - `unauthorized` — 401/403: the device token is missing/expired or lacks the
+ *                     `yagni_code:write` scope (re-run `yagni login`).
+ *  - `error`        — anything else: an over-budget 402, a 5xx, a 2xx with an
+ *                     unrecognized body, or an unreachable backend / thrown
+ *                     network error.
+ */
+export type RunTrackingFailure = "disabled" | "unauthorized" | "error";
+/**
+ * The outcome of opening a run. `tracked: true` carries the handle + gate
+ * verdict; `tracked: false` carries the reason so `/go` can warn that this run
+ * won't appear on the Work page. `start` never returns null and never throws.
+ */
+export type RunStartOutcome = ({
+    tracked: true;
+} & RunStartResult) | {
+    tracked: false;
+    reason: RunTrackingFailure;
+};
+/** Arguments to open a run. */
+export interface StartArgs {
+    arg: string;
+    repo?: string;
+    branch?: string;
+}
+/** A pipeline stage boundary event. */
+export interface StageArgs {
+    stage: string;
+    phase: "start" | "finish";
+    round?: number;
+    findings?: number;
+}
+/** An in-loop correction captured during the run. */
+export interface CorrectionArgs {
+    stage?: string;
+    question: string;
+    decision: string;
+    rationale?: string;
+}
+/**
+ * The /go PLAN, recorded onto the work item (a `plan_recorded` activity beat) so
+ * it is clear what the run set out to do. `body` is the plan markdown; the server
+ * scrubs secrets + caps it before persisting.
+ */
+export interface RecordPlanArgs {
+    stage: string;
+    body: string;
+}
+/** How a run ended; maps to the run-status enum server-side. */
+export interface FinishArgs {
+    outcome: "completed" | "stopped" | "failed";
+    stopReason?: string;
+    prUrl?: string;
+    prNumber?: number;
+    branch?: string;
+    commitSha?: string;
+    rounds?: number;
+    /**
+     * Short "what was done" recap; the server records it as a `run_outcome`
+     * activity (the end-of-run beat on the Work-page timeline). Optional + additive:
+     * `finish` already spreads the whole args object, so it flows through untouched.
+     */
+    outcomeSummary?: string;
+}
+/** The run-session object returned by {@link makeRunSession}. */
+export interface RunSession {
+    /** Adopt an externally-known handle (used by tests + cloud callers). */
+    bind(h: RunSessionHandle): void;
+    /** Open the run; resolves to a tracked outcome (handle + gate verdict) or an untracked reason. Never throws. */
+    start(b: StartArgs): Promise<RunStartOutcome>;
+    /** Stream a stage boundary; no-op until a handle exists. */
+    stage(b: StageArgs): Promise<void>;
+    /** Bank an in-loop correction; no-op until a handle exists. */
+    correction(b: CorrectionArgs): Promise<void>;
+    /** Record the /go plan onto the work item; no-op until a handle exists. */
+    recordPlan(b: RecordPlanArgs): Promise<void>;
+    /**
+     * Bump the run's server-side last-activity heartbeat so a long-but-alive run is
+     * not reaped as stale. No-op until a handle exists; never throws.
+     */
+    heartbeat(): Promise<void>;
+    /** Close the run with an outcome; no-op until a handle exists. */
+    finish(b: FinishArgs): Promise<void>;
+}
+export declare function makeRunSession(opts: RunSessionOptions): RunSession;
+//# sourceMappingURL=runSession.d.ts.map