@mikode13/harness 9.2.0 → 9.3.1

package/dist/recovery/domain/recoveryStore.d.ts

@@ -36,6 +36,22 @@ export interface JournalEntry {
  */
 export interface Manifest {
     files: Record<string, FileState>;
+    /**
+     * Covered paths it could not copy, such as a folder, a link or a file too large: what they
+     * held is unknown, so a change to one can be named but not undone.
+     */
+    uncopyable?: string[];
+}
+/**
+ * A path a command changed into, or from, something the history cannot copy, such as a file
+ * over the size limit: what it held before or after is unknown. Undo and redo leave it as it is,
+ * and report it as a conflict.
+ */
+export interface UnrecordedChange {
+    /** The real path, absolute. */
+    path: string;
+    /** The command it was seen around. */
+    by: string;
 }
 /** What one observation cost: before and after together. */
 export interface ObservationMeasure {
@@ -71,6 +87,12 @@ export interface RunRecord {
     startedAt: string;
     finishedAt?: string;
     status: RunStatus;
+    /**
+     * It finished with an observation still open, such as a command whose changes could not be
+     * compared after it ran: its journal may not hold all it changed yet. The next run or move
+     * settles it, as for an interrupted run, and keeps its status.
+     */
+    unsettled?: true;
     /** The process that ran it, so a run whose process died can be told from a live one. */
     pid: number;
 }
@@ -103,6 +125,11 @@ export interface RunJournal {
      * files cost, is kept with it.
      */
     observed(sequence: number, measure?: ObservationMeasure): Promise<void>;
+    /**
+     * Records that `by` changed `path` into, or from, something the history cannot copy. A move
+     * over the run leaves it as it is, and is not complete.
+     */
+    unrecorded(path: string, by: string): Promise<void>;
     /** How many bytes of content this run stored that the store did not hold yet. */
     readonly storedBytes: number;
     /** The path of every change it recorded as applied, in order: each one reached a file. */
@@ -114,20 +141,27 @@ export interface RunJournal {
      */
     contentState(): string;
     /**
-     * Whether a change it recorded may have reached a file: one prepared and not abandoned. It
-     * holds whatever happens to the record afterwards.
+     * Whether a change it recorded may have reached a file: one prepared and not abandoned, or one
+     * it could not copy. It holds whatever happens to the record afterwards, except once `finish`
+     * settled an observation the run left open and found that the run changed nothing: the run
+     * left the history, so it is `false`.
      */
     readonly changed: boolean;
     /**
      * Ends the run and releases the workspace for the next writer. A run that `changed` nothing
      * leaves the history, and the workspace is back at the run before it. If removing it fails,
-     * the store still treats it as gone, and the next run or move finishes removing it.
+     * the store still treats it as gone, and the next run or move finishes removing it. A run that
+     * ends with an observation open is settled from its manifest now, or by the next run or move
+     * if that fails.
      */
     finish(status: Exclude<RunStatus, 'running' | 'interrupted'>): Promise<void>;
 }
 /** The point before any run: going there takes the workspace back to how it was. */
 export declare const historyStart = "start";
-/** A file a move left as it was, because it did not hold what the history expected there. */
+/**
+ * A file a move left as it was: it did not hold what the history expected there, or a command
+ * changed it into, or from, something the history cannot copy.
+ */
 export interface MoveConflict {
     path: string;
     /** The run whose change could not be undone or redone. */
@@ -169,6 +203,12 @@ export declare class NothingToMoveError extends Error {
  * workspace itself. Only one run writes to a workspace at a time.
  */
 export interface RecoveryStore {
+    /**
+     * The history on disk this store keeps, from the real paths of its root and its state
+     * directory: two stores opened over one history, under any spelling of those paths, have the
+     * same one.
+     */
+    readonly workspaceId: string;
     /**
      * Starts recording a run and holds the workspace for it until `finish`. The new run's parent
      * is the run the workspace is at, and the workspace is at the new run from then on. Runs a
@@ -215,7 +255,8 @@ export interface RecoveryStore {
     /** Every move of the workspace, oldest first. */
     listRevisions(): Promise<Revision[]>;
     /**
-     * A run's record and its changes, in the order they were prepared.
+     * A run's record, its changes, in the order they were prepared, and the changes it could not
+     * copy.
      *
      * @throws {UnknownRunError} when `runId` was never a run of this workspace.
      * @throws {HistoryExpiredError} when retention removed `runId` or chained it into a later run.
@@ -223,6 +264,7 @@ export interface RecoveryStore {
     readRun(runId: string): Promise<{
         record: RunRecord;
         entries: JournalEntry[];
+        unrecorded: UnrecordedChange[];
     }>;
     /** The bytes a hash names. */
     readContent(hash: string): Promise<Buffer>;

package/dist/recovery/domain/recoveryStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"recoveryStore.js","sourceRoot":"","sources":["../../../src/recovery/domain/recoveryStore.ts"],"names":[],"mappings":"AAgIA,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC;AAsCpC,2FAA2F;AAC3F,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC5C,YAAY,SAA0B;QACrC,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC;QACpF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IAClC,CAAC;CACD;AA4DD,uFAAuF;AACvF,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC7C,uEAAuE;IAC9D,QAAQ,CAAS;IAC1B,wDAAwD;IAC/C,MAAM,CAAS;IAExB,YAAY,QAAgB,EAAE,MAAc;QAC3C,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;QACxF,KAAK,CAAC,iCAAiC,IAAI,CAAC,QAAQ,CAAC,cAAc,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACnC,KAAK,CAAS;IAEvB,YAAY,KAAa;QACxB,KAAK,CAAC,0BAA0B,KAAK,mBAAmB,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD","sourcesContent":["/**\n * What one path held at one moment: nothing, or a regular file with this content and mode.\n * `hash` names the content in the store, so the bytes themselves never travel in a record.\n */\nexport type FileState = { exists: false } | { exists: true; hash: string; mode: number };\n\n/**\n * One change to one file. It is recorded as `prepared` before the file is touched, and only\n * then applied, so a run that stops halfway always leaves a record of what it may have done.\n * `abandoned` means the change was prepared but never happened.\n */\nexport interface JournalEntry {\n\tsequence: number;\n\t/** The file's real path, absolute: a run may write to more than one root of its workspace. */\n\tpath: string;\n\tbefore: FileState;\n\tafter: FileState;\n\t/** Folders the change creates for a new file, outermost first: undo removes them if empty. */\n\tcreatedFolders?: string[];\n\t/**\n\t * The command whose run the change was seen around, for a change no tool of the harness made\n\t * itself. It was found by comparing the file before and after, not journaled before it was made.\n\t */\n\tobservedBy?: string;\n\tstatus: 'prepared' | 'applied' | 'abandoned';\n}\n\n/**\n * What a group of files held right before something outside the journal ran, such as a\n * command: the content of each, by its real path, absolute. It is stored as content, and the\n * journal names its hash before the command starts.\n */\nexport interface Manifest {\n\tfiles: Record<string, FileState>;\n}\n\n/** What one observation cost: before and after together. */\nexport interface ObservationMeasure {\n\t/** Files captured before, and compared after. */\n\tfiles: number;\n\tbytesRead: number;\n\t/** New content stored, which the store did not hold already. */\n\tbytesStored: number;\n\t/** Spent capturing and comparing, not running what was observed. */\n\tdurationMs: number;\n}\n\n/**\n * `interrupted` is a run whose process died while it was writing. The next run to take the\n * workspace settles each change it left `prepared`, from what the file holds now.\n */\nexport type RunStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';\n\nexport interface RunRecord {\n\trunId: string;\n\t/** The real path of the workspace root the run wrote to. */\n\troot: string;\n\t/**\n\t * The run the workspace was at when this one started, so runs form a tree: going back to an\n\t * earlier run and writing again starts a new branch. Absent for the first run.\n\t */\n\tparentRunId?: string;\n\t/**\n\t * Runs whose changes retention chained into this one, oldest first. They are no longer in\n\t * the history: this run now goes back to where the oldest of them started.\n\t */\n\tabsorbed?: string[];\n\t/** The journal file that holds the run's changes. Absent while it is the first one written. */\n\tjournal?: string;\n\tstartedAt: string;\n\tfinishedAt?: string;\n\tstatus: RunStatus;\n\t/** The process that ran it, so a run whose process died can be told from a live one. */\n\tpid: number;\n}\n\n/**\n * The recovery record of one run that writes. Every method returns only once what it records\n * is on disk: a change is never made before the record that would undo it exists. Once a step\n * fails to reach the journal, the journal refuses every later step, because a line written\n * after a broken one could not be read back.\n */\nexport interface RunJournal {\n\treadonly runId: string;\n\t/** Stores `content` and returns the hash that names it. Content stored before is reused. */\n\tsaveContent(content: Buffer): Promise<string>;\n\t/** Records a change about to be made, and returns its sequence number. */\n\tprepare(change: Omit<JournalEntry, 'sequence' | 'status'>): Promise<number>;\n\t/** The change was made. */\n\tapplied(sequence: number): Promise<void>;\n\t/** The change was not made, and the file still holds its `before`. */\n\tabandoned(sequence: number): Promise<void>;\n\t/**\n\t * Records that `by`, such as a command, is about to change files the journal cannot see it\n\t * change, and that the stored `manifest` holds what they hold now. Each change it makes is\n\t * then recorded as its own entry, prepared and applied at once, before `observed`. If the run\n\t * stops first, the next run settles it: every file of the manifest that changed since is\n\t * recorded as changed by `by`. A file it created is not in the manifest, and is then missed.\n\t */\n\tobserve(manifest: string, by: string): Promise<number>;\n\t/**\n\t * Every change the observation found is recorded. `measure`, what capturing and comparing the\n\t * files cost, is kept with it.\n\t */\n\tobserved(sequence: number, measure?: ObservationMeasure): Promise<void>;\n\t/** How many bytes of content this run stored that the store did not hold yet. */\n\treadonly storedBytes: number;\n\t/** The path of every change it recorded as applied, in order: each one reached a file. */\n\treadonly appliedPaths: readonly string[];\n\t/**\n\t * What the files this run changed hold now, as one hash of their paths and states. A file back\n\t * to what it held before the run's first change to it counts as unchanged, so a change undone\n\t * gives the state from before it.\n\t */\n\tcontentState(): string;\n\t/**\n\t * Whether a change it recorded may have reached a file: one prepared and not abandoned. It\n\t * holds whatever happens to the record afterwards.\n\t */\n\treadonly changed: boolean;\n\t/**\n\t * Ends the run and releases the workspace for the next writer. A run that `changed` nothing\n\t * leaves the history, and the workspace is back at the run before it. If removing it fails,\n\t * the store still treats it as gone, and the next run or move finishes removing it.\n\t */\n\tfinish(status: Exclude<RunStatus, 'running' | 'interrupted'>): Promise<void>;\n}\n\n/** The point before any run: going there takes the workspace back to how it was. */\nexport const historyStart = 'start';\n\n/** A file a move left as it was, because it did not hold what the history expected there. */\nexport interface MoveConflict {\n\tpath: string;\n\t/** The run whose change could not be undone or redone. */\n\trunId: string;\n}\n\n/**\n * One move of the workspace through its history, kept so an agent that runs next can tell\n * that its conversation is about a state the workspace has left.\n */\nexport interface Revision {\n\t/** Counts the moves of this workspace, from 1. */\n\trevision: number;\n\t/** The run the workspace was at; absent for the start of the history. */\n\tfrom?: string;\n\t/** The run the workspace is at now; absent for the start of the history. */\n\tto?: string;\n\tat: string;\n\t/** Why the user went there, when the host asked. */\n\treason?: string;\n\t/** Every file reached the state the history expected. Otherwise `conflicts` names those that did not. */\n\tcomplete: boolean;\n\tconflicts: MoveConflict[];\n}\n\nexport interface MoveOptions {\n\t/** Why the user is moving the workspace, recorded with the move. */\n\treason?: string;\n\t/**\n\t * Where the workspace must be for the move to happen: a run, or `historyStart`. Checked under\n\t * the workspace lock, so a move confirmed against one state never runs from another.\n\t */\n\tfrom?: string;\n}\n\n/** There is nothing to undo at the start of the history, or nothing to redo at its tip. */\nexport class NothingToMoveError extends Error {\n\tconstructor(direction: 'undo' | 'redo') {\n\t\tsuper(direction === 'undo' ? 'There is no run to undo' : 'There is no run to redo');\n\t\tthis.name = 'NothingToMoveError';\n\t}\n}\n\n/**\n * Where the runs that write to one workspace keep what is needed to undo them, outside the\n * workspace itself. Only one run writes to a workspace at a time.\n */\nexport interface RecoveryStore {\n\t/**\n\t * Starts recording a run and holds the workspace for it until `finish`. The new run's parent\n\t * is the run the workspace is at, and the workspace is at the new run from then on. Runs a\n\t * dead process left `running` are settled first.\n\t *\n\t * @throws {WorkspaceBusyError} when another live run is writing to the workspace.\n\t */\n\tstartRun(): Promise<RunJournal>;\n\t/**\n\t * Every run, oldest first, and the run the workspace is at (`head`), absent before the first.\n\t * A run still recorded as `running` whose process is gone is listed as `interrupted`.\n\t */\n\tlistRuns(): Promise<{ head?: string; runs: RunRecord[] }>;\n\t/**\n\t * Moves the workspace to the state right after `target`, or to how it was before any run\n\t * with `historyStart`. It undoes runs one by one back to the closest common ancestor, then\n\t * redoes runs one by one forward to `target`. Each file is written only if it holds the\n\t * state the history expects there; one that does not is left as it is and reported, and the\n\t * move is then not `complete`. A move the process did not finish is finished by the next\n\t * move or run.\n\t *\n\t * @throws {WorkspaceBusyError} when a run or another move holds the workspace.\n\t * @throws {WorkspaceMovedError} when `from` was given and the workspace is elsewhere.\n\t * @throws {UnknownRunError} when `target` is not in the history.\n\t * @throws {HistoryExpiredError} when retention chained `target` into a later run.\n\t */\n\tgoTo(target: string, options?: MoveOptions): Promise<Revision>;\n\t/**\n\t * Moves the workspace to the run before the one it is at.\n\t *\n\t * @throws {NothingToMoveError} at the start of the history.\n\t */\n\tundo(options?: MoveOptions): Promise<Revision>;\n\t/**\n\t * Moves the workspace to the next run: towards where it was most recently, or the newest\n\t * branch.\n\t *\n\t * @throws {NothingToMoveError} when no run follows the one it is at.\n\t */\n\tredo(options?: MoveOptions): Promise<Revision>;\n\t/** Every move of the workspace, oldest first. */\n\tlistRevisions(): Promise<Revision[]>;\n\t/**\n\t * A run's record and its changes, in the order they were prepared.\n\t *\n\t * @throws {UnknownRunError} when `runId` was never a run of this workspace.\n\t * @throws {HistoryExpiredError} when retention removed `runId` or chained it into a later run.\n\t */\n\treadRun(runId: string): Promise<{ record: RunRecord; entries: JournalEntry[] }>;\n\t/** The bytes a hash names. */\n\treadContent(hash: string): Promise<Buffer>;\n}\n\n/** A move was asked from one point of the history, and the workspace is at another. */\nexport class WorkspaceMovedError extends Error {\n\t/** Where the move expected the workspace: a run, or `historyStart`. */\n\treadonly expected: string;\n\t/** Where the workspace is: a run, or `historyStart`. */\n\treadonly actual: string;\n\n\tconstructor(expected: string, actual: string) {\n\t\tconst name = (point: string) => (point === historyStart ? 'the start' : `run ${point}`);\n\t\tsuper(`The workspace is no longer at ${name(expected)}: it is at ${name(actual)}`);\n\t\tthis.name = 'WorkspaceMovedError';\n\t\tthis.expected = expected;\n\t\tthis.actual = actual;\n\t}\n}\n\nexport class WorkspaceBusyError extends Error {\n\treadonly runId: string;\n\n\tconstructor(runId: string) {\n\t\tsuper(`The workspace is busy: ${runId} is writing to it`);\n\t\tthis.name = 'WorkspaceBusyError';\n\t\tthis.runId = runId;\n\t}\n}\n"]}
+{"version":3,"file":"recoveryStore.js","sourceRoot":"","sources":["../../../src/recovery/domain/recoveryStore.ts"],"names":[],"mappings":"AAgKA,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC;AAyCpC,2FAA2F;AAC3F,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC5C,YAAY,SAA0B;QACrC,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC;QACpF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IAClC,CAAC;CACD;AAqED,uFAAuF;AACvF,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC7C,uEAAuE;IAC9D,QAAQ,CAAS;IAC1B,wDAAwD;IAC/C,MAAM,CAAS;IAExB,YAAY,QAAgB,EAAE,MAAc;QAC3C,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;QACxF,KAAK,CAAC,iCAAiC,IAAI,CAAC,QAAQ,CAAC,cAAc,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACnC,KAAK,CAAS;IAEvB,YAAY,KAAa;QACxB,KAAK,CAAC,0BAA0B,KAAK,mBAAmB,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD","sourcesContent":["/**\n * What one path held at one moment: nothing, or a regular file with this content and mode.\n * `hash` names the content in the store, so the bytes themselves never travel in a record.\n */\nexport type FileState = { exists: false } | { exists: true; hash: string; mode: number };\n\n/**\n * One change to one file. It is recorded as `prepared` before the file is touched, and only\n * then applied, so a run that stops halfway always leaves a record of what it may have done.\n * `abandoned` means the change was prepared but never happened.\n */\nexport interface JournalEntry {\n\tsequence: number;\n\t/** The file's real path, absolute: a run may write to more than one root of its workspace. */\n\tpath: string;\n\tbefore: FileState;\n\tafter: FileState;\n\t/** Folders the change creates for a new file, outermost first: undo removes them if empty. */\n\tcreatedFolders?: string[];\n\t/**\n\t * The command whose run the change was seen around, for a change no tool of the harness made\n\t * itself. It was found by comparing the file before and after, not journaled before it was made.\n\t */\n\tobservedBy?: string;\n\tstatus: 'prepared' | 'applied' | 'abandoned';\n}\n\n/**\n * What a group of files held right before something outside the journal ran, such as a\n * command: the content of each, by its real path, absolute. It is stored as content, and the\n * journal names its hash before the command starts.\n */\nexport interface Manifest {\n\tfiles: Record<string, FileState>;\n\t/**\n\t * Covered paths it could not copy, such as a folder, a link or a file too large: what they\n\t * held is unknown, so a change to one can be named but not undone.\n\t */\n\tuncopyable?: string[];\n}\n\n/**\n * A path a command changed into, or from, something the history cannot copy, such as a file\n * over the size limit: what it held before or after is unknown. Undo and redo leave it as it is,\n * and report it as a conflict.\n */\nexport interface UnrecordedChange {\n\t/** The real path, absolute. */\n\tpath: string;\n\t/** The command it was seen around. */\n\tby: string;\n}\n\n/** What one observation cost: before and after together. */\nexport interface ObservationMeasure {\n\t/** Files captured before, and compared after. */\n\tfiles: number;\n\tbytesRead: number;\n\t/** New content stored, which the store did not hold already. */\n\tbytesStored: number;\n\t/** Spent capturing and comparing, not running what was observed. */\n\tdurationMs: number;\n}\n\n/**\n * `interrupted` is a run whose process died while it was writing. The next run to take the\n * workspace settles each change it left `prepared`, from what the file holds now.\n */\nexport type RunStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';\n\nexport interface RunRecord {\n\trunId: string;\n\t/** The real path of the workspace root the run wrote to. */\n\troot: string;\n\t/**\n\t * The run the workspace was at when this one started, so runs form a tree: going back to an\n\t * earlier run and writing again starts a new branch. Absent for the first run.\n\t */\n\tparentRunId?: string;\n\t/**\n\t * Runs whose changes retention chained into this one, oldest first. They are no longer in\n\t * the history: this run now goes back to where the oldest of them started.\n\t */\n\tabsorbed?: string[];\n\t/** The journal file that holds the run's changes. Absent while it is the first one written. */\n\tjournal?: string;\n\tstartedAt: string;\n\tfinishedAt?: string;\n\tstatus: RunStatus;\n\t/**\n\t * It finished with an observation still open, such as a command whose changes could not be\n\t * compared after it ran: its journal may not hold all it changed yet. The next run or move\n\t * settles it, as for an interrupted run, and keeps its status.\n\t */\n\tunsettled?: true;\n\t/** The process that ran it, so a run whose process died can be told from a live one. */\n\tpid: number;\n}\n\n/**\n * The recovery record of one run that writes. Every method returns only once what it records\n * is on disk: a change is never made before the record that would undo it exists. Once a step\n * fails to reach the journal, the journal refuses every later step, because a line written\n * after a broken one could not be read back.\n */\nexport interface RunJournal {\n\treadonly runId: string;\n\t/** Stores `content` and returns the hash that names it. Content stored before is reused. */\n\tsaveContent(content: Buffer): Promise<string>;\n\t/** Records a change about to be made, and returns its sequence number. */\n\tprepare(change: Omit<JournalEntry, 'sequence' | 'status'>): Promise<number>;\n\t/** The change was made. */\n\tapplied(sequence: number): Promise<void>;\n\t/** The change was not made, and the file still holds its `before`. */\n\tabandoned(sequence: number): Promise<void>;\n\t/**\n\t * Records that `by`, such as a command, is about to change files the journal cannot see it\n\t * change, and that the stored `manifest` holds what they hold now. Each change it makes is\n\t * then recorded as its own entry, prepared and applied at once, before `observed`. If the run\n\t * stops first, the next run settles it: every file of the manifest that changed since is\n\t * recorded as changed by `by`. A file it created is not in the manifest, and is then missed.\n\t */\n\tobserve(manifest: string, by: string): Promise<number>;\n\t/**\n\t * Every change the observation found is recorded. `measure`, what capturing and comparing the\n\t * files cost, is kept with it.\n\t */\n\tobserved(sequence: number, measure?: ObservationMeasure): Promise<void>;\n\t/**\n\t * Records that `by` changed `path` into, or from, something the history cannot copy. A move\n\t * over the run leaves it as it is, and is not complete.\n\t */\n\tunrecorded(path: string, by: string): Promise<void>;\n\t/** How many bytes of content this run stored that the store did not hold yet. */\n\treadonly storedBytes: number;\n\t/** The path of every change it recorded as applied, in order: each one reached a file. */\n\treadonly appliedPaths: readonly string[];\n\t/**\n\t * What the files this run changed hold now, as one hash of their paths and states. A file back\n\t * to what it held before the run's first change to it counts as unchanged, so a change undone\n\t * gives the state from before it.\n\t */\n\tcontentState(): string;\n\t/**\n\t * Whether a change it recorded may have reached a file: one prepared and not abandoned, or one\n\t * it could not copy. It holds whatever happens to the record afterwards, except once `finish`\n\t * settled an observation the run left open and found that the run changed nothing: the run\n\t * left the history, so it is `false`.\n\t */\n\treadonly changed: boolean;\n\t/**\n\t * Ends the run and releases the workspace for the next writer. A run that `changed` nothing\n\t * leaves the history, and the workspace is back at the run before it. If removing it fails,\n\t * the store still treats it as gone, and the next run or move finishes removing it. A run that\n\t * ends with an observation open is settled from its manifest now, or by the next run or move\n\t * if that fails.\n\t */\n\tfinish(status: Exclude<RunStatus, 'running' | 'interrupted'>): Promise<void>;\n}\n\n/** The point before any run: going there takes the workspace back to how it was. */\nexport const historyStart = 'start';\n\n/**\n * A file a move left as it was: it did not hold what the history expected there, or a command\n * changed it into, or from, something the history cannot copy.\n */\nexport interface MoveConflict {\n\tpath: string;\n\t/** The run whose change could not be undone or redone. */\n\trunId: string;\n}\n\n/**\n * One move of the workspace through its history, kept so an agent that runs next can tell\n * that its conversation is about a state the workspace has left.\n */\nexport interface Revision {\n\t/** Counts the moves of this workspace, from 1. */\n\trevision: number;\n\t/** The run the workspace was at; absent for the start of the history. */\n\tfrom?: string;\n\t/** The run the workspace is at now; absent for the start of the history. */\n\tto?: string;\n\tat: string;\n\t/** Why the user went there, when the host asked. */\n\treason?: string;\n\t/** Every file reached the state the history expected. Otherwise `conflicts` names those that did not. */\n\tcomplete: boolean;\n\tconflicts: MoveConflict[];\n}\n\nexport interface MoveOptions {\n\t/** Why the user is moving the workspace, recorded with the move. */\n\treason?: string;\n\t/**\n\t * Where the workspace must be for the move to happen: a run, or `historyStart`. Checked under\n\t * the workspace lock, so a move confirmed against one state never runs from another.\n\t */\n\tfrom?: string;\n}\n\n/** There is nothing to undo at the start of the history, or nothing to redo at its tip. */\nexport class NothingToMoveError extends Error {\n\tconstructor(direction: 'undo' | 'redo') {\n\t\tsuper(direction === 'undo' ? 'There is no run to undo' : 'There is no run to redo');\n\t\tthis.name = 'NothingToMoveError';\n\t}\n}\n\n/**\n * Where the runs that write to one workspace keep what is needed to undo them, outside the\n * workspace itself. Only one run writes to a workspace at a time.\n */\nexport interface RecoveryStore {\n\t/**\n\t * The history on disk this store keeps, from the real paths of its root and its state\n\t * directory: two stores opened over one history, under any spelling of those paths, have the\n\t * same one.\n\t */\n\treadonly workspaceId: string;\n\t/**\n\t * Starts recording a run and holds the workspace for it until `finish`. The new run's parent\n\t * is the run the workspace is at, and the workspace is at the new run from then on. Runs a\n\t * dead process left `running` are settled first.\n\t *\n\t * @throws {WorkspaceBusyError} when another live run is writing to the workspace.\n\t */\n\tstartRun(): Promise<RunJournal>;\n\t/**\n\t * Every run, oldest first, and the run the workspace is at (`head`), absent before the first.\n\t * A run still recorded as `running` whose process is gone is listed as `interrupted`.\n\t */\n\tlistRuns(): Promise<{ head?: string; runs: RunRecord[] }>;\n\t/**\n\t * Moves the workspace to the state right after `target`, or to how it was before any run\n\t * with `historyStart`. It undoes runs one by one back to the closest common ancestor, then\n\t * redoes runs one by one forward to `target`. Each file is written only if it holds the\n\t * state the history expects there; one that does not is left as it is and reported, and the\n\t * move is then not `complete`. A move the process did not finish is finished by the next\n\t * move or run.\n\t *\n\t * @throws {WorkspaceBusyError} when a run or another move holds the workspace.\n\t * @throws {WorkspaceMovedError} when `from` was given and the workspace is elsewhere.\n\t * @throws {UnknownRunError} when `target` is not in the history.\n\t * @throws {HistoryExpiredError} when retention chained `target` into a later run.\n\t */\n\tgoTo(target: string, options?: MoveOptions): Promise<Revision>;\n\t/**\n\t * Moves the workspace to the run before the one it is at.\n\t *\n\t * @throws {NothingToMoveError} at the start of the history.\n\t */\n\tundo(options?: MoveOptions): Promise<Revision>;\n\t/**\n\t * Moves the workspace to the next run: towards where it was most recently, or the newest\n\t * branch.\n\t *\n\t * @throws {NothingToMoveError} when no run follows the one it is at.\n\t */\n\tredo(options?: MoveOptions): Promise<Revision>;\n\t/** Every move of the workspace, oldest first. */\n\tlistRevisions(): Promise<Revision[]>;\n\t/**\n\t * A run's record, its changes, in the order they were prepared, and the changes it could not\n\t * copy.\n\t *\n\t * @throws {UnknownRunError} when `runId` was never a run of this workspace.\n\t * @throws {HistoryExpiredError} when retention removed `runId` or chained it into a later run.\n\t */\n\treadRun(\n\t\trunId: string,\n\t): Promise<{ record: RunRecord; entries: JournalEntry[]; unrecorded: UnrecordedChange[] }>;\n\t/** The bytes a hash names. */\n\treadContent(hash: string): Promise<Buffer>;\n}\n\n/** A move was asked from one point of the history, and the workspace is at another. */\nexport class WorkspaceMovedError extends Error {\n\t/** Where the move expected the workspace: a run, or `historyStart`. */\n\treadonly expected: string;\n\t/** Where the workspace is: a run, or `historyStart`. */\n\treadonly actual: string;\n\n\tconstructor(expected: string, actual: string) {\n\t\tconst name = (point: string) => (point === historyStart ? 'the start' : `run ${point}`);\n\t\tsuper(`The workspace is no longer at ${name(expected)}: it is at ${name(actual)}`);\n\t\tthis.name = 'WorkspaceMovedError';\n\t\tthis.expected = expected;\n\t\tthis.actual = actual;\n\t}\n}\n\nexport class WorkspaceBusyError extends Error {\n\treadonly runId: string;\n\n\tconstructor(runId: string) {\n\t\tsuper(`The workspace is busy: ${runId} is writing to it`);\n\t\tthis.name = 'WorkspaceBusyError';\n\t\tthis.runId = runId;\n\t}\n}\n"]}

package/dist/recovery/domain/runChanges.js

@@ -9,17 +9,26 @@ const binaryProbeBytes = 8000;
  * repository.
  */
 export async function showChanges(store, runId, { maxLines = 1000, visible } = {}) {
-    const { record, entries } = await store.readRun(runId);
+    const { record, entries, unrecorded } = await store.readRun(runId);
     const all = changedFiles(record, entries);
     const changes = [];
     for (const change of all)
         if (!visible || (await visible(change.path)))
             changes.push(change);
+    const uncopied = [];
+    for (const change of unrecorded) {
+        if (!visible || (await visible(change.path)))
+            uncopied.push(change);
+    }
     const output = [];
-    const hidden = all.length - changes.length;
+    const hidden = all.length + unrecorded.length - changes.length - uncopied.length;
     if (hidden > 0) {
         output.push(`# ${String(hidden)} changed ${hidden === 1 ? 'file is' : 'files are'} not shown: you may not read ${hidden === 1 ? 'it' : 'them'}`);
     }
+    // Named first: no diff can show them, and they must not be cut away with the diffs.
+    for (const { path, by } of uncopied) {
+        output.push(`# ${displayPath(record.root, path)}: changed while the command "${by}" ran, into or from something the history cannot copy (a folder, a link, or a file over 64 MB); undo leaves it as it is`);
+    }
     for (const [index, change] of changes.entries()) {
         const name = displayPath(record.root, change.path);
         const lines = await renderFile(store, name, change);

package/dist/recovery/domain/runChanges.js.map

@@ -1 +1 @@
-{"version":3,"file":"runChanges.js","sourceRoot":"","sources":["../../../src/recovery/domain/runChanges.ts"],"names":[],"mappings":"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","sourcesContent":["import { unifiedDiff } from '#src/diff/domain/unifiedDiff';\nimport { type FileChange, fileChanges, sameState } from './fileChanges.ts';\nimport type { JournalEntry, RecoveryStore, RunRecord } from './recoveryStore.ts';\n\nconst binaryProbeBytes = 8000;\n\nexport interface ShowChangesOptions {\n\t/**\n\t * The most lines of diff shown. What does not fit is named instead, in at most two more lines.\n\t */\n\tmaxLines?: number;\n\t/**\n\t * Whether a file, by its real path, may be shown. A file it may not show is neither shown nor\n\t * named: only how many there were is said. Defaults to every file.\n\t */\n\tvisible?: (path: string) => Promise<boolean>;\n}\n\n/**\n * What a run changed, as a git-style diff per file, in the order the run first touched each one.\n * It shows each file from before the run's first change to after its last, so a file the run\n * created and then deleted does not appear. A change a live run has prepared but not made yet\n * is named, not shown. It reports the run's recorded effects, not a comparison of the whole\n * repository.\n */\nexport async function showChanges(\n\tstore: RecoveryStore,\n\trunId: string,\n\t{ maxLines = 1000, visible }: ShowChangesOptions = {},\n): Promise<string> {\n\tconst { record, entries } = await store.readRun(runId);\n\tconst all = changedFiles(record, entries);\n\tconst changes: FileChange[] = [];\n\tfor (const change of all) if (!visible || (await visible(change.path))) changes.push(change);\n\tconst output: string[] = [];\n\tconst hidden = all.length - changes.length;\n\tif (hidden > 0) {\n\t\toutput.push(\n\t\t\t`# ${String(hidden)} changed ${hidden === 1 ? 'file is' : 'files are'} not shown: you may not read ${hidden === 1 ? 'it' : 'them'}`,\n\t\t);\n\t}\n\n\tfor (const [index, change] of changes.entries()) {\n\t\tconst name = displayPath(record.root, change.path);\n\t\tconst lines = await renderFile(store, name, change);\n\t\tconst room = maxLines - output.length;\n\t\tif (lines.length <= room) {\n\t\t\toutput.push(...lines);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst rest = changes.slice(index + 1).map(next => displayPath(record.root, next.path));\n\t\tconst shown = Math.max(0, room);\n\t\toutput.push(...lines.slice(0, shown));\n\t\toutput.push(`... ${String(lines.length - shown)} more lines of the diff of ${name} not shown`);\n\t\tif (rest.length > 0) {\n\t\t\toutput.push(`... ${String(rest.length)} more changed files not shown: ${rest.join(', ')}`);\n\t\t}\n\t\tbreak;\n\t}\n\n\treturn output.join('\\n');\n}\n\n/**\n * The files a run changed, in the order it first touched each one. A file left as it was, such\n * as one the run created and then deleted, is not a change; one it may or may not have changed,\n * or is changing now, is.\n */\nexport function changedFiles(record: RunRecord, entries: JournalEntry[]): FileChange[] {\n\treturn fileChanges(entries, record.status !== 'running').filter(\n\t\tchange => change.uncertain || change.pending || !sameState(change.before, change.after),\n\t);\n}\n\nasync function renderFile(\n\tstore: RecoveryStore,\n\tname: string,\n\tchange: FileChange,\n): Promise<string[]> {\n\tconst { before, after } = change;\n\tconst lines: string[] = [];\n\tif (change.uncertain) {\n\t\tlines.push(`# ${name}: the run stopped while changing this file; it may not hold this change`);\n\t}\n\tif (change.observedBy.length > 0) {\n\t\tconst commands = change.observedBy.map(command => `\"${command}\"`).join(', ');\n\t\tlines.push(\n\t\t\t`# ${name}: changed while the command ${commands} ran, seen by comparing before and after`,\n\t\t);\n\t}\n\tif (change.pending) {\n\t\tlines.push(`# ${name}: the run is changing this file now; that change is not shown`);\n\t\tif (sameState(before, after)) return lines;\n\t}\n\tlines.push(`diff --git a/${name} b/${name}`);\n\tif (!before.exists && after.exists) lines.push(`new file mode ${gitMode(after.mode)}`);\n\tif (before.exists && !after.exists) lines.push(`deleted file mode ${gitMode(before.mode)}`);\n\tif (before.exists && after.exists && before.mode !== after.mode) {\n\t\tlines.push(`old mode ${gitMode(before.mode)}`, `new mode ${gitMode(after.mode)}`);\n\t}\n\tif (before.exists && after.exists && before.hash === after.hash) return lines;\n\n\tconst oldContent = before.exists ? await store.readContent(before.hash) : Buffer.alloc(0);\n\tconst newContent = after.exists ? await store.readContent(after.hash) : Buffer.alloc(0);\n\tconst oldName = before.exists ? `a/${name}` : '/dev/null';\n\tconst newName = after.exists ? `b/${name}` : '/dev/null';\n\n\tif (!isText(oldContent) || !isText(newContent)) {\n\t\tlines.push(`Binary files ${oldName} and ${newName} differ`);\n\t\treturn lines;\n\t}\n\tconst hunks = unifiedDiff(oldContent.toString('utf8'), newContent.toString('utf8'));\n\t// An empty file created or deleted has no hunks, as in git.\n\tif (hunks !== '') lines.push(`--- ${oldName}`, `+++ ${newName}`, ...hunks.split('\\n'));\n\treturn lines;\n}\n\n/**\n * Git's test, a NUL byte near the start, plus content that is not valid UTF-8: decoding would\n * replace its bytes, and two different files could then show no difference.\n */\nexport function isText(content: Buffer): boolean {\n\tif (content.subarray(0, binaryProbeBytes).includes(0)) return false;\n\treturn Buffer.from(content.toString('utf8'), 'utf8').equals(content);\n}\n\n/** A regular file's mode as git writes it, such as `100644`. */\nfunction gitMode(mode: number): string {\n\treturn (0o100000 | mode).toString(8);\n}\n\n/**\n * Relative to the run's root when inside it; a file in another root keeps its real path. Both\n * are real absolute paths, with `/` as the separator on every supported platform.\n */\nexport function displayPath(root: string, path: string): string {\n\treturn path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;\n}\n"]}
+{"version":3,"file":"runChanges.js","sourceRoot":"","sources":["../../../src/recovery/domain/runChanges.ts"],"names":[],"mappings":"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","sourcesContent":["import { unifiedDiff } from '#src/diff/domain/unifiedDiff';\nimport { type FileChange, fileChanges, sameState } from './fileChanges.ts';\nimport type { JournalEntry, RecoveryStore, RunRecord } from './recoveryStore.ts';\n\nconst binaryProbeBytes = 8000;\n\nexport interface ShowChangesOptions {\n\t/**\n\t * The most lines of diff shown. What does not fit is named instead, in at most two more lines.\n\t */\n\tmaxLines?: number;\n\t/**\n\t * Whether a file, by its real path, may be shown. A file it may not show is neither shown nor\n\t * named: only how many there were is said. Defaults to every file.\n\t */\n\tvisible?: (path: string) => Promise<boolean>;\n}\n\n/**\n * What a run changed, as a git-style diff per file, in the order the run first touched each one.\n * It shows each file from before the run's first change to after its last, so a file the run\n * created and then deleted does not appear. A change a live run has prepared but not made yet\n * is named, not shown. It reports the run's recorded effects, not a comparison of the whole\n * repository.\n */\nexport async function showChanges(\n\tstore: RecoveryStore,\n\trunId: string,\n\t{ maxLines = 1000, visible }: ShowChangesOptions = {},\n): Promise<string> {\n\tconst { record, entries, unrecorded } = await store.readRun(runId);\n\tconst all = changedFiles(record, entries);\n\tconst changes: FileChange[] = [];\n\tfor (const change of all) if (!visible || (await visible(change.path))) changes.push(change);\n\tconst uncopied: typeof unrecorded = [];\n\tfor (const change of unrecorded) {\n\t\tif (!visible || (await visible(change.path))) uncopied.push(change);\n\t}\n\tconst output: string[] = [];\n\tconst hidden = all.length + unrecorded.length - changes.length - uncopied.length;\n\tif (hidden > 0) {\n\t\toutput.push(\n\t\t\t`# ${String(hidden)} changed ${hidden === 1 ? 'file is' : 'files are'} not shown: you may not read ${hidden === 1 ? 'it' : 'them'}`,\n\t\t);\n\t}\n\n\t// Named first: no diff can show them, and they must not be cut away with the diffs.\n\tfor (const { path, by } of uncopied) {\n\t\toutput.push(\n\t\t\t`# ${displayPath(record.root, path)}: changed while the command \"${by}\" ran, into or from something the history cannot copy (a folder, a link, or a file over 64 MB); undo leaves it as it is`,\n\t\t);\n\t}\n\tfor (const [index, change] of changes.entries()) {\n\t\tconst name = displayPath(record.root, change.path);\n\t\tconst lines = await renderFile(store, name, change);\n\t\tconst room = maxLines - output.length;\n\t\tif (lines.length <= room) {\n\t\t\toutput.push(...lines);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst rest = changes.slice(index + 1).map(next => displayPath(record.root, next.path));\n\t\tconst shown = Math.max(0, room);\n\t\toutput.push(...lines.slice(0, shown));\n\t\toutput.push(`... ${String(lines.length - shown)} more lines of the diff of ${name} not shown`);\n\t\tif (rest.length > 0) {\n\t\t\toutput.push(`... ${String(rest.length)} more changed files not shown: ${rest.join(', ')}`);\n\t\t}\n\t\tbreak;\n\t}\n\n\treturn output.join('\\n');\n}\n\n/**\n * The files a run changed, in the order it first touched each one. A file left as it was, such\n * as one the run created and then deleted, is not a change; one it may or may not have changed,\n * or is changing now, is.\n */\nexport function changedFiles(record: RunRecord, entries: JournalEntry[]): FileChange[] {\n\treturn fileChanges(entries, record.status !== 'running').filter(\n\t\tchange => change.uncertain || change.pending || !sameState(change.before, change.after),\n\t);\n}\n\nasync function renderFile(\n\tstore: RecoveryStore,\n\tname: string,\n\tchange: FileChange,\n): Promise<string[]> {\n\tconst { before, after } = change;\n\tconst lines: string[] = [];\n\tif (change.uncertain) {\n\t\tlines.push(`# ${name}: the run stopped while changing this file; it may not hold this change`);\n\t}\n\tif (change.observedBy.length > 0) {\n\t\tconst commands = change.observedBy.map(command => `\"${command}\"`).join(', ');\n\t\tlines.push(\n\t\t\t`# ${name}: changed while the command ${commands} ran, seen by comparing before and after`,\n\t\t);\n\t}\n\tif (change.pending) {\n\t\tlines.push(`# ${name}: the run is changing this file now; that change is not shown`);\n\t\tif (sameState(before, after)) return lines;\n\t}\n\tlines.push(`diff --git a/${name} b/${name}`);\n\tif (!before.exists && after.exists) lines.push(`new file mode ${gitMode(after.mode)}`);\n\tif (before.exists && !after.exists) lines.push(`deleted file mode ${gitMode(before.mode)}`);\n\tif (before.exists && after.exists && before.mode !== after.mode) {\n\t\tlines.push(`old mode ${gitMode(before.mode)}`, `new mode ${gitMode(after.mode)}`);\n\t}\n\tif (before.exists && after.exists && before.hash === after.hash) return lines;\n\n\tconst oldContent = before.exists ? await store.readContent(before.hash) : Buffer.alloc(0);\n\tconst newContent = after.exists ? await store.readContent(after.hash) : Buffer.alloc(0);\n\tconst oldName = before.exists ? `a/${name}` : '/dev/null';\n\tconst newName = after.exists ? `b/${name}` : '/dev/null';\n\n\tif (!isText(oldContent) || !isText(newContent)) {\n\t\tlines.push(`Binary files ${oldName} and ${newName} differ`);\n\t\treturn lines;\n\t}\n\tconst hunks = unifiedDiff(oldContent.toString('utf8'), newContent.toString('utf8'));\n\t// An empty file created or deleted has no hunks, as in git.\n\tif (hunks !== '') lines.push(`--- ${oldName}`, `+++ ${newName}`, ...hunks.split('\\n'));\n\treturn lines;\n}\n\n/**\n * Git's test, a NUL byte near the start, plus content that is not valid UTF-8: decoding would\n * replace its bytes, and two different files could then show no difference.\n */\nexport function isText(content: Buffer): boolean {\n\tif (content.subarray(0, binaryProbeBytes).includes(0)) return false;\n\treturn Buffer.from(content.toString('utf8'), 'utf8').equals(content);\n}\n\n/** A regular file's mode as git writes it, such as `100644`. */\nfunction gitMode(mode: number): string {\n\treturn (0o100000 | mode).toString(8);\n}\n\n/**\n * Relative to the run's root when inside it; a file in another root keeps its real path. Both\n * are real absolute paths, with `/` as the separator on every supported platform.\n */\nexport function displayPath(root: string, path: string): string {\n\treturn path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;\n}\n"]}

package/dist/recovery/infrastructure/fileRecoveryStore.d.ts

@@ -1,4 +1,5 @@
-import { type JournalEntry, type MoveOptions, type Revision, type RecoveryStore, type RunJournal, type RunRecord } from '../domain/recoveryStore.ts';
+import type { ILogger } from '#src/shared/domain/logger';
+import { type JournalEntry, type MoveOptions, type Revision, type RecoveryStore, type RunJournal, type RunRecord, type UnrecordedChange } from '../domain/recoveryStore.ts';
 /** Where an application keeps state that is neither configuration nor cache, per platform. */
 export declare function defaultStateDirectory(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;
 /**
@@ -21,11 +22,13 @@ export declare function defaultStateDirectory(env?: NodeJS.ProcessEnv, platform?
  * same instant could both believe they hold it.
  */
 export declare class FileRecoveryStore implements RecoveryStore {
+    readonly workspaceId: string;
     private readonly root;
     private readonly directory;
     private readonly keepRuns;
+    private readonly logger;
     private constructor();
-    static open({ root, directory, keepRuns, }: {
+    static open({ root, directory, keepRuns, logger, }: {
         root: string;
         /** Defaults to the platform's state directory. */
         directory?: string;
@@ -35,6 +38,8 @@ export declare class FileRecoveryStore implements RecoveryStore {
          * no next run to be chained into, so pruning can leave two runs besides the new one.
          */
         keepRuns?: number;
+        /** Where it reports a failure it absorbs. Defaults to standard error. */
+        logger?: ILogger;
     }): Promise<FileRecoveryStore>;
     startRun(): Promise<RunJournal>;
     listRuns(): Promise<{
@@ -44,6 +49,7 @@ export declare class FileRecoveryStore implements RecoveryStore {
     readRun(runId: string): Promise<{
         record: RunRecord;
         entries: JournalEntry[];
+        unrecorded: UnrecordedChange[];
     }>;
     private readRecord;
     private runDirectory;
@@ -102,24 +108,50 @@ export declare class FileRecoveryStore implements RecoveryStore {
      * saved are freed by the next prune.
      */
     private discardRun;
-    /** Removes the stored contents no kept run refers to. */
+    /**
+     * Removes the stored contents no kept run refers to. An observation still open refers to its
+     * manifest and to every content in it, which settling it needs.
+     */
     private collectContent;
     private appendRevision;
     /**
-     * Marks every other run still recorded as `running` as `interrupted`: this run holds the lock,
-     * so their processes are gone. Each change one left `prepared` is settled from what its file
-     * holds now: its `after` means it was made, its `before` that it was not. A file that holds
-     * neither stays `prepared`, because nothing tells whether the change reached it.
+     * Settles every other run left unfinished: one still recorded as `running` is `interrupted`,
+     * since this run holds the lock and its process is gone, and one that finished `unsettled`
+     * keeps its status.
      */
     private settleInterrupted;
+    /**
+     * Settles a run that finished with an observation open, under its own lock, before it releases
+     * the workspace. If that fails, its record stays `unsettled`, and the next run or move settles
+     * it, so the failure is reported and not thrown.
+     */
+    private settleAtFinish;
+    /**
+     * Settles what a run left unfinished. Each change it left `prepared` is settled from what its
+     * file holds now: its `after` means it was made, its `before` that it was not. A file that holds
+     * neither stays `prepared`, because nothing tells whether the change reached it. Each
+     * observation it left open is settled from its manifest. A run still `running` becomes
+     * `interrupted`; any other keeps its status. Whether the run is still in the history: one that
+     * changed nothing leaves it if it was still `running`, or if it is `finishing`, which unties
+     * its turns from it. One that finished is kept otherwise, since the turns of a conversation may
+     * name it.
+     */
+    private settleRun;
     /**
      * The lines that record what a command an interrupted run was observing changed: every file of
      * its manifest that holds something else now, as changed by that command, and then the end of
      * the observation. A file recorded after the observation began is left alone: the run
-     * recorded it itself. One that is now a folder, a link or too large to record is left out.
+     * recorded it itself. One that is now a folder, a link or too large to record, or that was one
+     * and is no longer, or that cannot be read, is recorded as a change the history could not copy.
      */
     private settleObservation;
-    /** What `path` holds now, with its content stored, or `undefined` for what no entry records. */
+    private warnUnreadable;
+    /**
+     * What `path` holds now, with its content stored, or `undefined` for what no entry records.
+     * A file it cannot read is `unreadable`, and reported: it cannot be undone either, and settling
+     * never waits on it, or every later run would fail to start. A failure to store its content is
+     * thrown, so the observation stays open and settling it is tried again.
+     */
     private saveState;
     private readEntries;
     /**