@namzu/cli 35.0.0 → 36.1.0

package/dist/checkpoints/manifest.d.ts

@@ -0,0 +1,107 @@
+/**
+ * What a turn's file history looks like on disk.
+ *
+ *   <root>/turns/<turnId>.json   one manifest per turn, version 1
+ *   <root>/blobs/<sha256>        content-addressed file bodies, before and after
+ *
+ * Every write is temp-file, fsync, rename: a reader, or a crash, sees the
+ * old file or the new one, never half. Blobs are immutable, so two turns
+ * (or a fork and its parent) share one body, and a body is verified against
+ * its name before it is ever written back over a user's file.
+ */
+export declare const MANIFEST_VERSION = 1;
+export interface BlobRef {
+    /** Full sha256, hex. */
+    readonly sha256: string;
+    readonly size: number;
+    /** Permission bits, so an undo does not reset them. */
+    readonly mode: number;
+    /** False when the body was too large to keep: the hash still identifies it. */
+    readonly stored?: boolean;
+}
+export type EntryState = 'pending' | 'done' | 'failed';
+export interface ManifestEntry {
+    /** Absolute, symlinks resolved. */
+    path: string;
+    /** Relative to the project folder, for display. */
+    rel: string;
+    /** `cwd`, or `additional:<n>` once extra directories are covered. */
+    root: string;
+    before: BlobRef | null;
+    after: BlobRef | null;
+    tool: string;
+    toolUseId: string;
+    state: EntryState;
+}
+export type SkipReason = 'too-large' | 'outside-cwd' | 'sandbox' | 'snapshot-failed';
+export type TurnStatus = 'applied' | 'undone' | 'partially_undone';
+export interface Manifest {
+    version: 1;
+    turnId: string;
+    seq: number;
+    label: string;
+    startedAt: number;
+    /** Last time an edit settled in this turn; retention counts from here. */
+    lastEditAt: number;
+    status: TurnStatus;
+    undone?: {
+        at: number;
+        by: string;
+        files: string[];
+    };
+    /** Bodies saved when an undo went ahead over a file the operator had changed. */
+    copies?: {
+        path: string;
+        sha256: string;
+        size: number;
+        mode: number;
+        at: number;
+    }[];
+    entries: ManifestEntry[];
+    skipped: {
+        path: string;
+        reason: SkipReason;
+    }[];
+    /** A shell call ran in this turn: undo cannot reverse what it changed. */
+    uncoveredShell: boolean;
+    /** Retention removed this turn's bodies. */
+    pruned?: boolean;
+    /** Set on a manifest a fork adopted from its parent. */
+    forkedFrom?: string;
+}
+/** A turn id is a file name: refuse anything that could leave the directory. */
+export declare function isSafeTurnId(id: string): boolean;
+export declare const turnsDir: (root: string) => string;
+export declare const blobsDir: (root: string) => string;
+export declare const manifestPath: (root: string, turnId: string) => string;
+export declare const blobPath: (root: string, sha256: string) => string;
+export declare function hashBytes(data: Uint8Array): string;
+/** Streams, so a file past the snapshot cap is identified without being held. */
+export declare function hashFile(path: string): Promise<string>;
+/** Publish `data` at `path`: fsynced temp file, then rename. */
+export declare function writeDurable(path: string, data: Uint8Array | string): Promise<void>;
+export declare function putBlob(root: string, data: Uint8Array): Promise<string>;
+export declare class BlobUnavailableError extends Error {
+    readonly sha256: string;
+    constructor(sha256: string, why: string);
+}
+/** The body, checked against its name: a damaged blob is never written back. */
+export declare function readBlob(root: string, sha256: string): Promise<Buffer>;
+export declare const blobExists: (root: string, sha256: string) => Promise<boolean>;
+export declare function writeManifest(root: string, manifest: Manifest): Promise<void>;
+/** Structural check; null when the file is not a manifest this reader understands. */
+export declare function parseManifest(text: string): Manifest | null;
+/** Every readable manifest under `root`; files that do not parse are named, not fatal. */
+export declare function readManifests(root: string): Promise<{
+    manifests: Manifest[];
+    unreadable: string[];
+}>;
+export declare function removeManifest(root: string, turnId: string): Promise<void>;
+/** Bodies on disk, with their sizes. */
+export declare function listBlobs(root: string): Promise<Map<string, number>>;
+export declare function removeBlob(root: string, sha256: string): Promise<void>;
+/** Every body a manifest names, kept ones only. */
+export declare function referencedBlobs(manifest: Manifest): Set<string>;
+/** Share a body with another history: hard link, or a copy where links are refused. */
+export declare function shareBlob(from: string, to: string, sha256: string): Promise<void>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/checkpoints/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/checkpoints/manifest.ts"],"names":[],"mappings":"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"}

package/dist/checkpoints/store.d.ts

@@ -1,88 +1,328 @@
 /**
- * File checkpoints: the state of every file the model changed, before it
- * changed it, per turn — so `/restore N` puts the working tree back to
- * where it was before turn N.
+ * File history: the state of every file the model changed, before AND after
+ * it changed it, per turn, kept on disk with the conversation it belongs to.
  *
- * Not git. A checkpoint is taken by the tool wrapper immediately before an
- * `edit` or `write` runs, whatever the repository's state, and it records
- * absence too, so a file the model created is removed on restore. Kept per
- * session in its `<session-id>/file-history/` directory and dropped when the session
- * closes: a checkpoint outlives a turn, not a session — the conversation
- * can be forked and resumed, and its files are the working tree's.
+ * Not git. The tool wrapper records a file immediately before an `edit` or
+ * `write` runs, whatever the repository's state, and once more when the call
+ * has settled; absence is recorded too, so a file the model created can be
+ * taken away again. A turn is a manifest keyed by the journal's `TurnId`
+ * (`<root>/turns/<turnId>.json`), its file bodies are content-addressed
+ * blobs (`<root>/blobs/<sha256>`), and both are written temp-and-rename, so
+ * the history survives the session, the process and a crash. Closing a
+ * session releases memory and deletes nothing: history ends with the
+ * conversation (`dispose`), by age, or by the size cap — never by a quit.
+ *
+ * Undoing a turn is a plan (`undo-plan.ts`) over these manifests and the
+ * disk. It writes a file only while the disk still holds what the turn left
+ * there; everything else is reported, not overwritten.
  */
 import { sep } from 'node:path';
+import { type SkipReason, type TurnStatus } from './manifest.js';
+import { type ConflictReason, type PlanFile } from './undo-plan.js';
+export type { SkipReason, TurnStatus } from './manifest.js';
+export type { ConflictReason, PlanAction, PlanFile, UndoPlan } from './undo-plan.js';
 export interface CheckpointTurn {
-    /** 1-based, in the order turns began. */
+    /** 1-based, in the order turns first recorded a change in this conversation. */
     readonly index: number;
+    readonly turnId: string;
     /** The prompt that started the turn, cut to a line. */
     readonly label: string;
     readonly startedAt: number;
-    /** Host paths snapshotted in this turn, first change first. */
+    readonly status: TurnStatus;
+    /** Host paths changed in this turn, first change first. */
     readonly files: readonly string[];
 }
+export interface SkippedPath {
+    readonly path: string;
+    readonly reason: SkipReason;
+    /** The turn that was running when the path was skipped. */
+    readonly turn: number;
+}
+export type SnapshotResult = 'recorded' | 'already' | 'outside' | 'too-large';
+export interface RestoreConflict {
+    readonly path: string;
+    /** The turn (as `/restore` numbers it) whose change was left in place. */
+    readonly turn: number;
+    readonly reason: ConflictReason;
+}
 export interface RestoreReport {
     readonly turn: number;
     /** Files written back to their pre-turn content. */
     readonly restored: readonly string[];
     /** Files removed because they did not exist before the turn. */
     readonly removed: readonly string[];
+    /** Files left as they are, because putting them back could lose something. */
+    readonly conflicts: readonly RestoreConflict[];
+    /** Files whose write failed; they were left as they were. */
+    readonly failed: readonly string[];
+    /** Files the undone turns changed that no history covers. */
+    readonly notCovered: readonly {
+        path: string;
+        reason: SkipReason;
+    }[];
+    /** An undone turn also ran shell commands, which `/restore` cannot reverse. */
+    readonly uncoveredShell: boolean;
+    /** Turns that were fully undone, newest first. */
+    readonly undoneTurns: readonly number[];
+    /** Turns some of whose files were left in place. They stay listed. */
+    readonly partialTurns: readonly number[];
+}
+/** Which call a snapshot is for. All optional: a bare path still records. */
+export interface SnapshotMeta {
+    /** The journal turn the tool call belongs to. */
+    readonly turnId?: string;
+    readonly tool?: string;
+    readonly toolUseId?: string;
+}
+/** What a reply's undo stands at, from the manifests alone. */
+export type TurnUndoState = TurnStatus | 'none' | 'expired';
+export interface TurnUndoStatus {
+    readonly turnId: string;
+    readonly status: TurnUndoState;
+    /** Files the reply changed that a history covers. */
+    readonly files: number;
+    /** Of those, files the reply created. */
+    readonly added: number;
+    /** Of those, files the reply deleted. */
+    readonly removed: number;
+    readonly uncoveredShell: boolean;
+    readonly skipped: readonly {
+        path: string;
+        reason: SkipReason;
+    }[];
+}
+export type UndoFileResult = 'restored' | 'removed' | 'skipped' | 'failed' | 'noop';
+export interface UndoPreview {
+    readonly turnId: string;
+    readonly status: TurnStatus;
+    readonly planToken: string;
+    readonly files: readonly PlanFile[];
+    readonly skipped: readonly {
+        path: string;
+        reason: SkipReason;
+    }[];
+    readonly uncoveredShell: boolean;
+    /** Later replies that changed files this turn changed. */
+    readonly laterTurnsOnSameFiles: readonly string[];
+}
+export interface UndoOptions {
+    /** From the preview the operator saw. A different plan is refused, not applied. */
+    readonly planToken: string;
+    readonly alsoUndoLater?: boolean;
+    /**
+     * Per path. A conflict is skipped unless it is `keep_copy`: the file as it
+     * is now is saved first, then the turn's version goes back.
+     */
+    readonly resolutions?: Readonly<Record<string, 'skip' | 'keep_copy'>>;
+    readonly by?: string;
+}
+export type UndoOutcome = {
+    readonly kind: 'applied';
+    readonly turnId: string;
+    readonly status: TurnStatus;
+    /** The target turn's files. */
+    readonly files: Readonly<Record<string, UndoFileResult>>;
+    /** Later replies undone along with it. */
+    readonly later: Readonly<Record<string, Readonly<Record<string, UndoFileResult>>>>;
+    /** Files the operator had changed, saved before being replaced. */
+    readonly copies: readonly {
+        path: string;
+        sha256: string;
+    }[];
+    /** Every path that was written or removed: the model's picture of them is stale. */
+    readonly changed: readonly string[];
+} | {
+    readonly kind: 'plan-changed';
+    readonly plan: UndoPreview;
+};
+/** Test seams: a fault between planning and writing. Never set in production. */
+export interface StoreTestHooks {
+    /** Before a step re-reads the disk. A change made here must abort that path. */
+    beforeStep?(path: string): void | Promise<void>;
+    /** After the disk was re-checked, before the write. Throwing is a failed write. */
+    beforeWrite?(path: string): void | Promise<void>;
+}
+export interface StoreOptions {
+    /** Retention: oldest turns are expired once their bodies exceed this. Default 512 MiB. */
+    readonly maxBytes?: number;
+    /** Retention: a turn expires this long after its last edit. Default 30 days. */
+    readonly maxAgeMs?: number;
+    readonly now?: () => number;
+    readonly hooks?: StoreTestHooks;
 }
 /** Files larger than this are not snapshotted; the transcript says so. */
 export declare const CHECKPOINT_MAX_BYTES: number;
+export declare const CHECKPOINT_RETENTION_BYTES: number;
+export declare const CHECKPOINT_RETENTION_MS: number;
 export declare class FileCheckpointStore {
     /**
-     * Where blobs go: the session's `file-history/` (`SessionPaths.fileHistory`).
-     * A function is read at each turn's first snapshot, so a store that
+     * Where history goes: the session's `file-history/` (`SessionPaths.fileHistory`).
+     * A function is read at each turn's first write, so a store that
      * outlives a conversation switch (`/resume`, `/new`) writes into the
      * conversation the turn belongs to, not the one the process started in.
      */
     private readonly root;
-    /** Only files under here are checkpointed. */
+    /** Only files under here are covered. */
     private readonly cwd;
-    private readonly turns;
+    private readonly options;
+    private readonly histories;
+    /** The same histories once loaded, for the synchronous readers. */
+    private readonly ready;
+    private readonly byId;
+    private readonly tails;
     private current;
-    private readonly skipped;
-    /** Every `file-history/` a blob was written under, so closing drops them all. */
-    private readonly roots;
+    private readonly now;
+    private readonly maxBytes;
+    private readonly maxAgeMs;
     constructor(
     /**
-     * Where blobs go: the session's `file-history/` (`SessionPaths.fileHistory`).
-     * A function is read at each turn's first snapshot, so a store that
+     * Where history goes: the session's `file-history/` (`SessionPaths.fileHistory`).
+     * A function is read at each turn's first write, so a store that
      * outlives a conversation switch (`/resume`, `/new`) writes into the
      * conversation the turn belongs to, not the one the process started in.
      */
     root: string | (() => string), 
-    /** Only files under here are checkpointed. */
-    cwd: string);
+    /** Only files under here are covered. */
+    cwd: string, options?: StoreOptions);
+    /** One operation at a time per conversation: a snapshot must not land mid-undo. */
+    private locked;
     private currentRoot;
-    /** The next tool write belongs to this turn. Returns its index. */
-    beginTurn(label: string): number;
-    /** Whether a host path is one this store would checkpoint. */
+    private realCwdPromise;
+    private realCwd;
+    /**
+     * The file a path really is, symlinks resolved, or null when that lies
+     * outside the project. Entries are keyed by it: an edit written through
+     * a link changes the target, so that is what an undo must put back,
+     * and a link is never replaced by a regular file.
+     */
+    private canonical;
+    private insideReal;
+    /** Whether a host path is one this store would cover. */
     covers(hostPath: string): boolean;
     /**
-     * Record the file's current content before it changes. Once per path
-     * per turn: the first snapshot is the pre-turn state, and a second edit
-     * to the same file within a turn must not overwrite it.
+     * The next tool writes belong to this turn. `turnId` is the journal's own;
+     * a caller with none (a test, a host command) gets a generated one.
+     * Returns the id.
      */
-    snapshot(hostPath: string): Promise<'recorded' | 'already' | 'outside' | 'too-large'>;
-    /** Turns that changed at least one file. */
+    beginTurn(label: string, turnId?: string): string;
+    private newRec;
+    /** The turn a write belongs to. Under the lock, after the history is loaded. */
+    private resolveRec;
+    private rootOf;
+    /**
+     * Read this conversation's history, settle what a crash left half-done, and
+     * expire what retention says is old. Idempotent; the first call does the work.
+     */
+    open(): Promise<void>;
+    /** Call under `locked(root)`. */
+    private load;
+    private read;
+    /**
+     * A crash can leave an entry `pending`: the before body is saved, the call
+     * may or may not have written. The disk decides — still the before state
+     * means nothing happened and the entry goes; anything else is the result.
+     */
+    private reconcile;
+    /** Expire by age, then by size, oldest first; then drop bodies nothing names. */
+    private sweep;
+    private expire;
+    private persist;
+    /** Bodies no entry names any more, other than `except`'s own. */
+    private collect;
+    /**
+     * The file's state as a ref. With `keep`, a body within the cap is saved;
+     * a larger one is identified by its hash alone.
+     */
+    private capture;
+    /**
+     * Record the file's current content before it changes. Once per path per
+     * turn: the first snapshot is the pre-turn state, and a second edit to the
+     * same file within a turn must not overwrite it.
+     */
+    snapshot(hostPath: string, meta?: SnapshotMeta): Promise<SnapshotResult>;
+    private snapshotNow;
+    /**
+     * The call has settled: record where the file ended up. A failed call that
+     * left the file as it found it takes its entry back; one that changed it,
+     * even halfway, keeps it, because the undo is then real.
+     */
+    settle(hostPath: string, outcome: {
+        ok: boolean;
+        first: boolean;
+        turnId?: string;
+    }): Promise<void>;
+    /** Note a path no history covers. Once per path per reason per turn. */
+    recordSkip(hostPath: string, reason: SkipReason, turnId?: string): Promise<void>;
+    private skipNow;
+    /**
+     * A shell call ran in this turn: whatever it changed is not covered. Saved
+     * with the turn once the turn has a manifest; until then it rides along.
+     */
+    noteShell(turnId?: string): Promise<void>;
+    private currentHistory;
+    /** Turns of the current conversation that changed at least one file and can still be undone. */
     list(): readonly CheckpointTurn[];
-    /** Paths that were too large to checkpoint, so a restore cannot bring them back. */
-    skippedPaths(): readonly string[];
     /**
-     * Put every file back to its state before turn `index`, undoing that
-     * turn and every later one. Later turns are applied first, so a file
-     * touched in several turns ends at its oldest recorded state.
+     * Where each reply's undo stands. Reads the manifests only, never the disk,
+     * so it is cheap to ask on open. With `turnIds`, one row per id asked for
+     * (`none` for a reply that changed nothing here); without, every reply the
+     * history knows.
+     */
+    undoStatus(turnIds?: readonly string[]): Promise<TurnUndoStatus[]>;
+    /** Paths no history covers, with why: an undo cannot bring them back. */
+    skippedPaths(): readonly SkippedPath[];
+    /** What undoing `turnId` would do, from the manifests and the disk. Writes nothing. */
+    previewUndo(turnId: string, opts?: {
+        alsoUndoLater?: boolean;
+    }): Promise<UndoPreview>;
+    private plan;
+    /** What is on disk at a path now, never following a link. */
+    private diskState;
+    /**
+     * Take back a turn's changes. Re-plans first and refuses a plan other than
+     * the one the operator saw; then, per file, re-reads the disk right before
+     * writing and leaves a file alone if it moved. Not all-or-nothing: what was
+     * restored, skipped and failed is reported, and a rerun finishes safely.
+     */
+    undo(turnId: string, opts: UndoOptions): Promise<UndoOutcome>;
+    private applyPlan;
+    /**
+     * Put the tree back to before turn `index`: undo that turn and every later
+     * one, newest first, each through the same drift-checked plan as a single
+     * undo. A file the operator (or a shell call) changed since is left alone
+     * and reported, never overwritten. Nothing is deleted: the undone turns
+     * keep their manifests and bodies, marked undone.
      */
     restore(index: number): Promise<RestoreReport>;
-    /** Drop every blob. The session is over. */
-    close(): Promise<void>;
-    /** A write outside any turn — a host command, say — gets a turn of its own. */
-    private turnForStrayWrite;
+    private restoreNow;
+    /**
+     * A fork starts with its parent's history up to the fork point: the same
+     * manifests, the same immutable bodies hard-linked rather than copied.
+     * `untilTurnId` is the last parent turn the fork keeps; none keeps all.
+     */
+    adoptFork(parentRoot: string, opts?: {
+        untilTurnId?: string;
+    }): Promise<number>;
+    /**
+     * The session is over: finish what is in flight and drop the memory. Every
+     * file stays — history belongs to the conversation, not the process.
+     */
+    release(): Promise<void>;
+    /**
+     * The conversation is gone (deleted or archived): remove its history. The
+     * only path that deletes any.
+     */
+    dispose(): Promise<void>;
 }
 /** What `/restore` prints with no argument. */
-export declare function renderCheckpoints(turns: readonly CheckpointTurn[], cwd: string): string;
+export declare function renderCheckpoints(turns: readonly CheckpointTurn[], cwd: string, skipped?: readonly SkippedPath[]): string;
 /** What `/restore N` prints. */
 export declare function renderRestore(report: RestoreReport, cwd: string): string;
+/**
+ * What the model reads before its next turn: the operator took files back,
+ * so what it remembers of them is wrong, and the files left alone hold
+ * someone else's content, not the pre-turn version.
+ */
+export declare function renderRestoreNote(report: RestoreReport, cwd: string): string;
 export { sep as PATH_SEPARATOR };
 //# sourceMappingURL=store.d.ts.map

package/dist/checkpoints/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/checkpoints/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAgD,GAAG,EAAE,MAAM,WAAW,CAAA;AAE7E,MAAM,WAAW,cAAc;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAiBD,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,QAAkB,CAAA;AAGnD,qBAAa,mBAAmB;IAS9B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG;IAhBrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;;IAGzC;;;;;OAKG;IACc,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC;IAC9C,8CAA8C;IAC7B,GAAG,EAAE,MAAM;IAG7B,OAAO,CAAC,WAAW;IAInB,mEAAmE;IACnE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAYhC,8DAA8D;IAC9D,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKjC;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IA6B3F,4CAA4C;IAC5C,IAAI,IAAI,SAAS,cAAc,EAAE;IAWjC,oFAAoF;IACpF,YAAY,IAAI,SAAS,MAAM,EAAE;IAIjC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAiCpD,4CAA4C;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB;CAIzB;AAOD,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAYvF;AAED,gCAAgC;AAChC,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMxE;AAED,OAAO,EAAE,GAAG,IAAI,cAAc,EAAE,CAAA"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/checkpoints/store.ts"],"names":[],"mappings":"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"}

package/dist/checkpoints/undo-plan.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What undoing a turn would do to each file, decided without touching one.
+ *
+ * Pure: the manifests and the disk's current state go in, a plan comes out.
+ * The preview and the apply both call it, so what the operator was shown is
+ * what runs, and `planToken` is how the apply knows nothing moved in between.
+ *
+ * A file is only ever written when the disk still holds exactly what the
+ * turn left there. Anything else is a conflict and is skipped by default.
+ */
+import type { BlobRef, EntryState, TurnStatus } from './manifest.js';
+/** What is on disk at a path right now. */
+export type DiskState = {
+    kind: 'absent';
+} | {
+    kind: 'file';
+    sha256: string;
+    mode: number;
+} | {
+    kind: 'symlink';
+}
+/** A directory, or anything else that is not a file. */
+ | {
+    kind: 'other';
+}
+/** The path now resolves outside the project. */
+ | {
+    kind: 'outside';
+};
+export type PlanAction = 'restore' | 'delete' | 'noop' | 'conflict';
+export type ConflictReason = 'drifted' | 'later-reply' | 'unavailable' | 'symlink' | 'outside-cwd';
+export interface PlanEntry {
+    path: string;
+    rel: string;
+    before: BlobRef | null;
+    after: BlobRef | null;
+    state: EntryState;
+    /** The body undo would write back is gone. */
+    beforeMissing: boolean;
+}
+export interface PlanTurn {
+    turnId: string;
+    seq: number;
+    status: TurnStatus;
+    /** Retention removed the bodies. */
+    pruned: boolean;
+    entries: readonly PlanEntry[];
+}
+export interface PlanInput {
+    turnId: string;
+    /** Also undo later replies that changed the same files, newest first. */
+    alsoUndoLater: boolean;
+    turns: readonly PlanTurn[];
+    /** The current state of every path any involved entry names. */
+    disk: ReadonlyMap<string, DiskState>;
+    /** Compare permission bits too. False on Windows, where they are not the file's own. */
+    compareMode?: boolean;
+}
+export interface PlanFile {
+    /** The turn whose change this step takes back. */
+    turnId: string;
+    path: string;
+    rel: string;
+    action: PlanAction;
+    reason?: ConflictReason;
+    /** The later replies standing in the way. */
+    blockedBy?: string[];
+    /** The disk state this step expects to find, as a token. */
+    cur: string;
+}
+export interface UndoPlan {
+    turnId: string;
+    alsoUndoLater: boolean;
+    planToken: string;
+    /** In the order they must run: later replies first, the target last. */
+    files: PlanFile[];
+}
+export declare class PlanError extends Error {
+    constructor(message: string);
+}
+export declare function diskToken(state: DiskState, compareMode?: boolean): string;
+export declare function planUndo(input: PlanInput): UndoPlan;
+//# sourceMappingURL=undo-plan.d.ts.map

package/dist/checkpoints/undo-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo-plan.d.ts","sourceRoot":"","sources":["../../src/checkpoints/undo-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAEpE,2CAA2C;AAC3C,MAAM,MAAM,SAAS,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,wDAAwD;GACtD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE;AACnB,iDAAiD;GAC/C;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAEtB,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAEnE,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,GAAG,SAAS,GAAG,aAAa,CAAA;AAElG,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IACrB,KAAK,EAAE,UAAU,CAAA;IACjB,8CAA8C;IAC9C,aAAa,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,QAAQ;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,UAAU,CAAA;IAClB,oCAAoC;IACpC,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,SAAS,SAAS,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,aAAa,EAAE,OAAO,CAAA;IACtB,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC1B,gEAAgE;IAChE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACpC,wFAAwF;IACxF,WAAW,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,MAAM,WAAW,QAAQ;IACxB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,UAAU,CAAA;IAClB,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,QAAQ;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,OAAO,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,KAAK,EAAE,QAAQ,EAAE,CAAA;CACjB;AAED,qBAAa,SAAU,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI3B;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,UAAO,GAAG,MAAM,CAOtE;AA8CD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,CA2HnD"}

package/dist/checkpoints/wrap.d.ts

@@ -12,4 +12,8 @@ import type { FileCheckpointStore } from './store.js';
 /** Tools whose `path` names a file they will change. */
 export declare const CHECKPOINTED_TOOLS: readonly string[];
 export declare function withCheckpoints(tool: ToolDefinition, store: FileCheckpointStore): ToolDefinition;
+/** Tools that change files by running something: undo cannot reverse them. */
+export declare const SHELL_TOOLS: readonly string[];
+/** Note, per turn, that a shell call ran, so the history can say what it does not cover. */
+export declare function withShellNote(tool: ToolDefinition, store: FileCheckpointStore): ToolDefinition;
 //# sourceMappingURL=wrap.d.ts.map

package/dist/checkpoints/wrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../src/checkpoints/wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAe,cAAc,EAAc,MAAM,YAAY,CAAA;AAEzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAsB,CAAA;AAQtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,mBAAmB,GAAG,cAAc,CAoBhG"}
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../src/checkpoints/wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAe,cAAc,EAAc,MAAM,YAAY,CAAA;AAEzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAsB,CAAA;AAQtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,mBAAmB,GAAG,cAAc,CA0DhG;AAED,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAAgC,CAAA;AAEzE,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,mBAAmB,GAAG,cAAc,CAQ9F"}