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

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

@@ -0,0 +1,32 @@
+/**
+ * The no-op guard: does the build half actually produce a change?
+ *
+ * The pipeline's review half is diff-driven — each reviewer runs `git diff`
+ * itself. So an implement stage that exits 0 having changed NOTHING (a cheap
+ * model narrating a "## Files changed" summary without calling write/edit, an
+ * empty plan handoff, etc.) leaves an empty tree, the reviewers correctly find
+ * nothing, and the run would otherwise report `clean` — a false "reviewed and
+ * clean" for work that never happened. This module gives the orchestrator a
+ * cheap, honest signal to stop with `no_changes` instead.
+ *
+ * `workspaceChanged` is PURE (unit-tested directly). `snapshotWorkspace` is the
+ * thin, injectable git seam — it shells out like `reviewTool.ts#runGit` because
+ * pi's ExtensionContext exposes no exec. It is resilient: any git error (no repo,
+ * git missing) yields `tracked: false`, and the pure comparator then FAILS OPEN
+ * (assumes a change) rather than mis-firing `no_changes`.
+ */
+import type { WorkspaceSnapshot } from "./types.js";
+/**
+ * Did the working tree change between two snapshots? A different HEAD means a
+ * stage committed; a different porcelain status means an uncommitted edit. When
+ * EITHER snapshot is untracked we cannot assess the tree, so we fail open and
+ * report `true` — the guard only stops a run it is certain produced nothing.
+ */
+export declare function workspaceChanged(before: WorkspaceSnapshot, after: WorkspaceSnapshot): boolean;
+/**
+ * Capture the repo's HEAD + porcelain status at `cwd`. `git rev-parse HEAD`
+ * failing (empty result) means the cwd is not a usable git work tree, so we
+ * report `tracked: false` and skip the second call.
+ */
+export declare function snapshotWorkspace(cwd: string, signal?: AbortSignal): Promise<WorkspaceSnapshot>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/extension/pipeline/workspace.js

@@ -0,0 +1,73 @@
+/**
+ * The no-op guard: does the build half actually produce a change?
+ *
+ * The pipeline's review half is diff-driven — each reviewer runs `git diff`
+ * itself. So an implement stage that exits 0 having changed NOTHING (a cheap
+ * model narrating a "## Files changed" summary without calling write/edit, an
+ * empty plan handoff, etc.) leaves an empty tree, the reviewers correctly find
+ * nothing, and the run would otherwise report `clean` — a false "reviewed and
+ * clean" for work that never happened. This module gives the orchestrator a
+ * cheap, honest signal to stop with `no_changes` instead.
+ *
+ * `workspaceChanged` is PURE (unit-tested directly). `snapshotWorkspace` is the
+ * thin, injectable git seam — it shells out like `reviewTool.ts#runGit` because
+ * pi's ExtensionContext exposes no exec. It is resilient: any git error (no repo,
+ * git missing) yields `tracked: false`, and the pure comparator then FAILS OPEN
+ * (assumes a change) rather than mis-firing `no_changes`.
+ */
+import { execFile } from "node:child_process";
+/**
+ * Did the working tree change between two snapshots? A different HEAD means a
+ * stage committed; a different porcelain status means an uncommitted edit. When
+ * EITHER snapshot is untracked we cannot assess the tree, so we fail open and
+ * report `true` — the guard only stops a run it is certain produced nothing.
+ */
+export function workspaceChanged(before, after) {
+    if (!before.tracked || !after.tracked)
+        return true;
+    return after.head !== before.head || after.status !== before.status;
+}
+/**
+ * Run one git command, resolving to trimmed stdout or "" on any error.
+ *
+ * `signal` is deliberately NOT passed into execFile: Node's built-in abort
+ * handling kills via the child's pid, and when the spawn itself failed (missing
+ * cwd, missing git) an abort landing in the same tick resolves that to pid 0 —
+ * signalling the WHOLE process group and killing the parent (observed as the
+ * test runner dying with 128+SIGTERM). Abort is wired manually with an explicit
+ * pid guard instead; a killed child still reaches the callback, which resolves
+ * "" as for any other error.
+ */
+function runGit(args, cwd, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve("");
+        const child = execFile("git", args, { cwd, maxBuffer: 32 * 1024 * 1024 }, (err, stdout) => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(err ? "" : stdout.toString().trim());
+        });
+        const onAbort = () => {
+            try {
+                if (child.pid)
+                    child.kill("SIGTERM");
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Capture the repo's HEAD + porcelain status at `cwd`. `git rev-parse HEAD`
+ * failing (empty result) means the cwd is not a usable git work tree, so we
+ * report `tracked: false` and skip the second call.
+ */
+export async function snapshotWorkspace(cwd, signal) {
+    const head = await runGit(["rev-parse", "HEAD"], cwd, signal);
+    if (!head)
+        return { tracked: false, head: "", status: "" };
+    const status = await runGit(["status", "--porcelain"], cwd, signal);
+    return { tracked: true, head, status };
+}
+//# sourceMappingURL=workspace.js.map

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

@@ -0,0 +1,107 @@
+/**
+ * Run-worktree plumbing for worktree-by-default /go (spec §3b).
+ *
+ * A /go run gets its own detached worktree + run branch BEFORE anything else
+ * (`git worktree add -b yagni/<slug>-<shortId> ~/.yagni-code/worktrees/<shortId>
+ * HEAD`), so repoCtx, sessionKey, and every snapshot are resolved against the
+ * worktree path and the run can never fold the user's live tree into its diff.
+ *
+ * Three impure seams, each with the pure decision parts unit-testable:
+ *  - {@link createRunWorktree} — the `git worktree add` shell-out (throws with
+ *    git's stderr so the caller can fall back to in-place honestly).
+ *  - {@link bootstrapWorktree} — best-effort `<pm> install --prefer-offline`
+ *    with an 8-minute cap, because a fresh worktree has no node_modules and
+ *    without it every verify/typecheck exits `command not found`. Fail-OPEN
+ *    with an honest note; an opt-in `.yagni-code/bootstrap` file (same trust
+ *    model as `.yagni-code/verify`: only read when the operator set
+ *    `YAGNI_CODE_ALLOW_VERIFY_OVERRIDE=1`) overrides the detected install. The
+ *    install runs under {@link buildVerifyEnv} so repo-triggered commands never
+ *    inherit YAGNI/AI tokens (invariant §0.9).
+ *  - {@link commitWip} — the WIP commit on a NON-clean terminal outcome
+ *    (`wip(yagni): <ticket> - <stopReason>`), clearly marked and worktree-local,
+ *    so round_cap/partial work is never lost and /go-clean can remove the tree.
+ *
+ * All naming helpers ({@link slugifyTicket}, {@link runBranchName}) are pure.
+ */
+/** Wall-clock cap on the best-effort worktree bootstrap install (spec §3b). */
+export declare const BOOTSTRAP_TIMEOUT_MS: number;
+/**
+ * Turn arbitrary ticket text into a git-ref-safe slug: lowercase, non-alnum runs
+ * collapse to `-`, trimmed, capped. Empty input (an all-symbol ticket) falls
+ * back to "run" so the branch name is always valid.
+ */
+export declare function slugifyTicket(ticket: string): string;
+/** The run branch: `yagni/<ticket-slug>-<runShortId>` (spec §3b). */
+export declare function runBranchName(ticket: string, runShortId: string): string;
+/** Result of one shell-free exec: exit code + combined output. */
+export interface ExecResult {
+    code: number;
+    output: string;
+}
+/** The impure exec seam (default: execFile with a scrubbed env); injected in tests. */
+export type WorktreeExec = (argv: string[], cwd: string, signal?: AbortSignal) => Promise<ExecResult>;
+export interface CreateWorktreeOpts {
+    /** The repo the user ran /go from (any path inside it works for git). */
+    repoCwd: string;
+    /** Absolute worktree destination (under ~/.yagni-code/worktrees/<shortId>). */
+    worktreePath: string;
+    /** The new run branch to create at HEAD. */
+    branch: string;
+    signal?: AbortSignal;
+    /** Injectable git seam for tests. */
+    gitImpl?: (argv: string[], cwd: string, signal?: AbortSignal) => Promise<string>;
+}
+/**
+ * Create the run worktree + branch FIRST: `git worktree add -b <branch> <path>
+ * HEAD`, with the parent worktrees dir created 0700. Throws (with git's stderr)
+ * on failure so the caller can degrade honestly to an in-place run.
+ */
+export declare function createRunWorktree(opts: CreateWorktreeOpts): Promise<void>;
+/** The bootstrap outcome: `note` is the honest fail-open explanation when it could not run. */
+export interface BootstrapOutcome {
+    /** Did an install (or override) run to a clean exit? */
+    ran: boolean;
+    /** The command label (`pnpm install --prefer-offline` / the override line). */
+    command?: string;
+    /** Honest note when bootstrap was skipped or failed (surfaced to the user). */
+    note?: string;
+}
+export interface BootstrapOpts {
+    readFile?: (path: string) => string;
+    exec?: WorktreeExec;
+    timeoutMs?: number;
+    /**
+     * Allow the repo-local `.yagni-code/bootstrap` override (same trust model as
+     * `.yagni-code/verify`: repo-defined commands only run when the operator
+     * opted in). Defaults to the same env gate verify uses.
+     */
+    allowRepoOverride?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Best-effort worktree bootstrap (layer 1 of spec §3b): install dependencies so
+ * verify/typecheck can run at all. Detection mirrors the verify gate's package
+ * manager detection; ONLY an install is run — never a repo build script we'd
+ * have to guess at. Every failure path is fail-open with an honest note; the
+ * verify gate's infra-failure classification (layer 2) covers whatever this
+ * could not provide.
+ */
+export declare function bootstrapWorktree(worktreePath: string, opts?: BootstrapOpts): Promise<BootstrapOutcome>;
+/**
+ * Remove a run worktree via `git worktree remove` (run from the repo the user
+ * is in, so git also prunes its worktree metadata). NOT forced: git itself
+ * refuses a dirty worktree, which backstops /go-clean's own clean check.
+ * Throws with git's stderr on failure so the caller can report it honestly.
+ */
+export declare function removeWorktree(worktreePath: string, repoCwd: string, signal?: AbortSignal, gitImpl?: (argv: string[], cwd: string, signal?: AbortSignal) => Promise<string>): Promise<void>;
+/** The WIP commit subject for a non-clean terminal outcome (house copy: no em-dashes). */
+export declare function wipCommitMessage(ticket: string, stopReason: string): string;
+/**
+ * Commit everything in the worktree as a clearly-marked WIP commit so a
+ * round_cap/partial/failed run's work is never lost and /go-clean can remove
+ * the (now clean) worktree. Returns the commit sha, or undefined when there was
+ * nothing to commit or the commit failed (fail-soft: an uncommittable worktree
+ * just stays dirty and /go-clean skips it with a note).
+ */
+export declare function commitWip(worktreePath: string, message: string, gitImpl?: (argv: string[], cwd: string, signal?: AbortSignal) => Promise<string>, signal?: AbortSignal): Promise<string | undefined>;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/extension/pipeline/worktree.js

@@ -0,0 +1,200 @@
+/**
+ * Run-worktree plumbing for worktree-by-default /go (spec §3b).
+ *
+ * A /go run gets its own detached worktree + run branch BEFORE anything else
+ * (`git worktree add -b yagni/<slug>-<shortId> ~/.yagni-code/worktrees/<shortId>
+ * HEAD`), so repoCtx, sessionKey, and every snapshot are resolved against the
+ * worktree path and the run can never fold the user's live tree into its diff.
+ *
+ * Three impure seams, each with the pure decision parts unit-testable:
+ *  - {@link createRunWorktree} — the `git worktree add` shell-out (throws with
+ *    git's stderr so the caller can fall back to in-place honestly).
+ *  - {@link bootstrapWorktree} — best-effort `<pm> install --prefer-offline`
+ *    with an 8-minute cap, because a fresh worktree has no node_modules and
+ *    without it every verify/typecheck exits `command not found`. Fail-OPEN
+ *    with an honest note; an opt-in `.yagni-code/bootstrap` file (same trust
+ *    model as `.yagni-code/verify`: only read when the operator set
+ *    `YAGNI_CODE_ALLOW_VERIFY_OVERRIDE=1`) overrides the detected install. The
+ *    install runs under {@link buildVerifyEnv} so repo-triggered commands never
+ *    inherit YAGNI/AI tokens (invariant §0.9).
+ *  - {@link commitWip} — the WIP commit on a NON-clean terminal outcome
+ *    (`wip(yagni): <ticket> - <stopReason>`), clearly marked and worktree-local,
+ *    so round_cap/partial work is never lost and /go-clean can remove the tree.
+ *
+ * All naming helpers ({@link slugifyTicket}, {@link runBranchName}) are pure.
+ */
+import { execFile } from "node:child_process";
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { composeAbortSignal } from "./resilience.js";
+import { buildVerifyEnv, detectPackageManager } from "./verify.js";
+/** Wall-clock cap on the best-effort worktree bootstrap install (spec §3b). */
+export const BOOTSTRAP_TIMEOUT_MS = 8 * 60_000;
+/** Cap on the slug half of a run branch name (keeps refs readable). */
+const SLUG_MAX = 40;
+/**
+ * Turn arbitrary ticket text into a git-ref-safe slug: lowercase, non-alnum runs
+ * collapse to `-`, trimmed, capped. Empty input (an all-symbol ticket) falls
+ * back to "run" so the branch name is always valid.
+ */
+export function slugifyTicket(ticket) {
+    const slug = ticket
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, SLUG_MAX)
+        .replace(/-+$/, "");
+    return slug || "run";
+}
+/** The run branch: `yagni/<ticket-slug>-<runShortId>` (spec §3b). */
+export function runBranchName(ticket, runShortId) {
+    return `yagni/${slugifyTicket(ticket)}-${runShortId}`;
+}
+const defaultExec = (argv, cwd, signal) => new Promise((resolve, reject) => {
+    execFile(argv[0], argv.slice(1), { cwd, signal, env: buildVerifyEnv(), maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const output = `${stdout ?? ""}${stderr ?? ""}`;
+        if (err) {
+            const code = err.code;
+            if (typeof code === "number")
+                return resolve({ code, output });
+            return reject(err); // spawn error / abort — no numeric exit
+        }
+        resolve({ code: 0, output });
+    });
+});
+/** Best-effort git in `cwd`; rejects with stderr detail on failure. */
+function git(argv, cwd, signal) {
+    return new Promise((resolve, reject) => {
+        execFile("git", argv, { cwd, signal, maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (err) {
+                reject(new Error(stderr.toString().trim() || err.message));
+                return;
+            }
+            resolve(stdout.toString().trim());
+        });
+    });
+}
+/**
+ * Create the run worktree + branch FIRST: `git worktree add -b <branch> <path>
+ * HEAD`, with the parent worktrees dir created 0700. Throws (with git's stderr)
+ * on failure so the caller can degrade honestly to an in-place run.
+ */
+export async function createRunWorktree(opts) {
+    const gitImpl = opts.gitImpl ?? git;
+    mkdirSync(dirname(opts.worktreePath), { recursive: true, mode: 0o700 });
+    await gitImpl(["worktree", "add", "-b", opts.branch, opts.worktreePath, "HEAD"], opts.repoCwd, opts.signal);
+}
+function tryRead(readFile, path) {
+    try {
+        return readFile(path);
+    }
+    catch {
+        return null;
+    }
+}
+/** First non-comment, non-empty line of an override file, whitespace-split to argv. */
+function parseOverride(body) {
+    for (const raw of body.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const argv = line.split(/\s+/);
+        if (argv.length > 0)
+            return argv;
+    }
+    return null;
+}
+/**
+ * Best-effort worktree bootstrap (layer 1 of spec §3b): install dependencies so
+ * verify/typecheck can run at all. Detection mirrors the verify gate's package
+ * manager detection; ONLY an install is run — never a repo build script we'd
+ * have to guess at. Every failure path is fail-open with an honest note; the
+ * verify gate's infra-failure classification (layer 2) covers whatever this
+ * could not provide.
+ */
+export async function bootstrapWorktree(worktreePath, opts = {}) {
+    const readFile = opts.readFile ?? ((p) => readFileSync(p, "utf8"));
+    const exec = opts.exec ?? defaultExec;
+    const timeoutMs = opts.timeoutMs ?? BOOTSTRAP_TIMEOUT_MS;
+    const allowOverride = opts.allowRepoOverride ?? process.env.YAGNI_CODE_ALLOW_VERIFY_OVERRIDE === "1";
+    let argv = null;
+    let label = "";
+    const overrideBody = allowOverride ? tryRead(readFile, join(worktreePath, ".yagni-code", "bootstrap")) : null;
+    if (overrideBody) {
+        argv = parseOverride(overrideBody);
+        label = argv ? argv.join(" ") : "";
+    }
+    if (!argv) {
+        // No package.json at the worktree root => nothing we know how to bootstrap.
+        if (tryRead(readFile, join(worktreePath, "package.json")) == null) {
+            return { ran: false };
+        }
+        const pm = detectPackageManager(worktreePath, readFile);
+        argv = [pm, "install", "--prefer-offline"];
+        label = argv.join(" ");
+    }
+    try {
+        const signal = composeAbortSignal(opts.signal, AbortSignal.timeout(timeoutMs));
+        const { code, output } = await exec(argv, worktreePath, signal);
+        if (code !== 0) {
+            const tail = output.trim().split("\n").slice(-3).join(" ").slice(0, 200);
+            return {
+                ran: false,
+                command: label,
+                note: `worktree bootstrap (${label}) exited ${code}${tail ? `: ${tail}` : ""}. Verify/typecheck may not be able to run in this worktree.`,
+            };
+        }
+        return { ran: true, command: label };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ran: false,
+            command: label,
+            note: `worktree bootstrap (${label}) could not run: ${msg}. Verify/typecheck may not be able to run in this worktree.`,
+        };
+    }
+}
+/**
+ * Remove a run worktree via `git worktree remove` (run from the repo the user
+ * is in, so git also prunes its worktree metadata). NOT forced: git itself
+ * refuses a dirty worktree, which backstops /go-clean's own clean check.
+ * Throws with git's stderr on failure so the caller can report it honestly.
+ */
+export async function removeWorktree(worktreePath, repoCwd, signal, gitImpl) {
+    const run = gitImpl ?? git;
+    await run(["worktree", "remove", worktreePath], repoCwd, signal);
+}
+/** The WIP commit subject for a non-clean terminal outcome (house copy: no em-dashes). */
+export function wipCommitMessage(ticket, stopReason) {
+    return `wip(yagni): ${ticket} - ${stopReason}`;
+}
+/**
+ * Commit everything in the worktree as a clearly-marked WIP commit so a
+ * round_cap/partial/failed run's work is never lost and /go-clean can remove
+ * the (now clean) worktree. Returns the commit sha, or undefined when there was
+ * nothing to commit or the commit failed (fail-soft: an uncommittable worktree
+ * just stays dirty and /go-clean skips it with a note).
+ */
+export async function commitWip(worktreePath, message, gitImpl, signal) {
+    const run = gitImpl ?? git;
+    try {
+        const status = await run(["status", "--porcelain"], worktreePath, signal);
+        if (!status.trim())
+            return undefined; // already clean — nothing to preserve
+        await run(["add", "-A"], worktreePath, signal);
+        try {
+            await run(["commit", "-m", message], worktreePath, signal);
+        }
+        catch {
+            // Most likely a missing git identity in a fresh environment; retry once
+            // with an explicit YAGNI Code identity rather than losing the WIP commit.
+            await run(["-c", "user.name=YAGNI Code", "-c", "user.email=code@yagni.app", "commit", "-m", message], worktreePath, signal);
+        }
+        return await run(["rev-parse", "HEAD"], worktreePath, signal);
+    }
+    catch {
+        return undefined; // fail-soft: the worktree stays dirty; /go-clean reports it honestly
+    }
+}
+//# sourceMappingURL=worktree.js.map

package/dist/extension/provider.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderConfig } from "@earendil-works/pi-coding-agent";
+import type { ModelEntry } from "./config.js";
+/**
+ * Build the pi `ProviderConfig` for the `yagni` provider from a fetched catalog.
+ *
+ * The provider speaks the `openai-completions` API against `${baseUrl}/v1` and
+ * authenticates with the `$YAGNI_TOKEN` env var (resolved by pi at request time).
+ * pi — not this extension — performs the actual model calls.
+ */
+export declare function buildYagniProvider(catalog: ModelEntry[], baseUrl: string): ProviderConfig;
+//# sourceMappingURL=provider.d.ts.map

package/dist/extension/provider.js

@@ -0,0 +1,26 @@
+/**
+ * Build the pi `ProviderConfig` for the `yagni` provider from a fetched catalog.
+ *
+ * The provider speaks the `openai-completions` API against `${baseUrl}/v1` and
+ * authenticates with the `$YAGNI_TOKEN` env var (resolved by pi at request time).
+ * pi — not this extension — performs the actual model calls.
+ */
+export function buildYagniProvider(catalog, baseUrl) {
+    const models = catalog.map((m) => ({
+        id: m.id,
+        name: m.name,
+        reasoning: m.reasoning ?? false,
+        input: m.input ?? ["text"],
+        cost: m.cost,
+        contextWindow: m.contextWindow,
+        maxTokens: m.maxTokens,
+    }));
+    return {
+        name: "YAGNI",
+        baseUrl: `${baseUrl}/v1`,
+        apiKey: "$YAGNI_TOKEN",
+        api: "openai-completions",
+        models,
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/extension/recall.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Ambient judgment recall (spec §4, M1 — degraded-tolerant).
+ *
+ * After the `read` tool returns, fetch the compact recorded judgment for that
+ * path (`GET /recall`) and append a `⟦YAGNI recall⟧ …` block to the tool result
+ * so the agent sees the decisions/corrections already banked for this file —
+ * zero extra turns, no model call.
+ *
+ * pi-recall-surface finding (verified against pi 0.80.2
+ * `dist/core/extensions/types.d.ts`): the interactive `tool_result` event is
+ * documented "Fired after a tool executes. Can modify result." and its handler
+ * result `ToolResultEventResult` exposes `content?: (TextContent | ImageContent)[]`.
+ * So RESULT MODIFICATION is supported: we return the original content plus the
+ * recall block. (The documented `before_agent_start` brief-injection fallback is
+ * therefore NOT needed here.)
+ *
+ * Everything is fail-soft and bounded:
+ *  - `AbortSignal.timeout` + a hard deadline race cap the fetch at 1500ms, so
+ *    recall NEVER blocks a read beyond the timeout — even if the shared
+ *    authed-fetch seam attempts a 401 refresh underneath.
+ *  - per-path session cache (a path is fetched at most once per session).
+ *  - skipped entirely when the corpus is thin (<3 active decisions) or eval mode.
+ *  - any failure degrades to no injection.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Recall must never block a read beyond this (spec §4). */
+export declare const RECALL_TIMEOUT_MS = 1500;
+/** Below this many active decisions, recall is skipped entirely (spec: <3). */
+export declare const RECALL_MIN_DECISIONS = 3;
+/** Client-side caps mirror the backend (compact by construction). */
+export declare const RECALL_MAX_DECISIONS = 5;
+export declare const RECALL_MAX_CORRECTIONS = 3;
+/** The compact recall payload from GET /api/yagni-code/recall (§2). */
+export interface RecallDecision {
+    id: string;
+    question: string;
+    decision: string;
+}
+export interface RecallCorrection {
+    summary: string;
+}
+export interface RecallResult {
+    decisions: RecallDecision[];
+    corrections: RecallCorrection[];
+    /** True when the workspace has <3 active decisions total — skip injection. */
+    thin: boolean;
+}
+/** Transport seam for {@link fetchRecall}. */
+export interface RecallClientOpts {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    /** Override the 1500ms cap (tests). */
+    timeoutMs?: number;
+    /** Optional repo full name to scope recall. */
+    repo?: string;
+}
+/** Defensive parse of a /recall response into a {@link RecallResult}, or null. */
+export declare function normalizeRecall(data: unknown): RecallResult | null;
+/**
+ * Pure: derive the repo-relative path the backend expects from a read tool's
+ * `path` argument and the session cwd. Rebases an absolute path INSIDE the tree
+ * to a relative one (an outside path stays absolute), and strips a leading `./`.
+ */
+export declare function toRepoRelativePath(readPath: string, cwd: string): string;
+/**
+ * Pure: render the compact `⟦YAGNI recall⟧` block, or null when there is
+ * nothing to inject (missing result, thin corpus, or empty). No em-dashes.
+ */
+export declare function formatRecallBlock(result: RecallResult | null): string | null;
+/**
+ * GET /recall for a repo-relative path, bounded at {@link RECALL_TIMEOUT_MS}.
+ * Uses the shared authed fetch (inherits the 401 refresh-retry), but the hard
+ * deadline still caps the total wait. Returns null on any non-2xx, timeout, or
+ * error (fail-soft).
+ */
+export declare function fetchRecall(opts: RecallClientOpts, path: string, signal?: AbortSignal): Promise<RecallResult | null>;
+/** Injectable deps for {@link registerAmbientRecall}. */
+export interface RegisterRecallDeps extends RecallClientOpts {
+    /** Active-decision count from GET /context; recall is skipped when <3. */
+    decisionsCount?: number;
+    /** Eval mode disables recall entirely. */
+    evalMode?: boolean;
+    /** Recall fetcher (default: {@link fetchRecall}); injected in tests. */
+    fetchRecallImpl?: typeof fetchRecall;
+}
+/**
+ * Wire the `tool_result` handler that appends recall to a `read` result. No-op
+ * (nothing registered) when the corpus is thin (<3 decisions) or in eval mode,
+ * so there is zero overhead in those cases.
+ */
+export declare function registerAmbientRecall(pi: ExtensionAPI, deps: RegisterRecallDeps): void;
+//# sourceMappingURL=recall.d.ts.map