@mikode13/harness 11.0.1 → 11.2.0

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

@@ -1,3 +1,4 @@
+import type { Session } from '#src/shared/domain/session';
 /**
  * What one path held at one moment: nothing, or a regular file with this content and mode.
  * `hash` names the content in the store, so the bytes themselves never travel in a record.
@@ -95,6 +96,8 @@ export interface RunRecord {
     unsettled?: true;
     /** The process that ran it, so a run whose process died can be told from a live one. */
     pid: number;
+    /** The session it came from. Absent for a run recorded before runs recorded one. */
+    session?: Session;
 }
 /**
  * The recovery record of one run that writes. Every method returns only once what it records
@@ -209,14 +212,23 @@ export interface RecoveryStore {
      * same one.
      */
     readonly workspaceId: string;
+    /**
+     * What its runs may write in, as real paths: its root and the other folders it was opened
+     * with. A run claims them while it holds the workspace, so no worktree they lie in is removed
+     * meanwhile.
+     */
+    readonly writeFolders: readonly 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
      * dead process left `running` are settled first.
      *
-     * @throws {WorkspaceBusyError} when another live run is writing to the workspace.
+     * @throws {WorkspaceBusyError} when another live run is writing to the workspace, or a
+     * worktree it may write in is being removed.
      */
-    startRun(): Promise<RunJournal>;
+    startRun(options?: {
+        session?: Session;
+    }): Promise<RunJournal>;
     /**
      * Every run, oldest first, and the run the workspace is at (`head`), absent before the first.
      * A run still recorded as `running` whose process is gone is listed as `interrupted`.

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

@@ -1 +1 @@
-{"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"]}
+{"version":3,"file":"recoveryStore.js","sourceRoot":"","sources":["../../../src/recovery/domain/recoveryStore.ts"],"names":[],"mappings":"AAoKA,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;AA4ED,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":["import type { Session } from '#src/shared/domain/session';\n\n/**\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\t/** The session it came from. Absent for a run recorded before runs recorded one. */\n\tsession?: Session;\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 * What its runs may write in, as real paths: its root and the other folders it was opened\n\t * with. A run claims them while it holds the workspace, so no worktree they lie in is removed\n\t * meanwhile.\n\t */\n\treadonly writeFolders: readonly 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, or a\n\t * worktree it may write in is being removed.\n\t */\n\tstartRun(options?: { session?: Session }): 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/infrastructure/fileRecoveryStore.d.ts

@@ -1,3 +1,4 @@
+import type { Session } from '#src/shared/domain/session';
 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. */
@@ -23,12 +24,15 @@ export declare function defaultStateDirectory(env?: NodeJS.ProcessEnv, platform?
  */
 export declare class FileRecoveryStore implements RecoveryStore {
     readonly workspaceId: string;
+    readonly writeFolders: readonly string[];
     private readonly root;
     private readonly directory;
     private readonly keepRuns;
     private readonly logger;
+    private readonly claims;
+    private readonly releases;
     private constructor();
-    static open({ root, directory, keepRuns, logger, }: {
+    static open({ root, directory, keepRuns, logger, writeRoots, }: {
         root: string;
         /** Defaults to the platform's state directory. */
         directory?: string;
@@ -40,8 +44,15 @@ export declare class FileRecoveryStore implements RecoveryStore {
         keepRuns?: number;
         /** Where it reports a failure it absorbs. Defaults to standard error. */
         logger?: ILogger;
+        /**
+         * The folders besides `root` that its runs may write in, such as the other `write` roots,
+         * so no worktree they lie in is removed while a run writes there.
+         */
+        writeRoots?: readonly string[];
     }): Promise<FileRecoveryStore>;
-    startRun(): Promise<RunJournal>;
+    startRun({ session }?: {
+        session?: Session;
+    }): Promise<RunJournal>;
     listRuns(): Promise<{
         head?: string;
         runs: RunRecord[];
@@ -69,6 +80,14 @@ export declare class FileRecoveryStore implements RecoveryStore {
      * most the step in progress, and that step is safe to take again.
      */
     private takeSteps;
+    /**
+     * Claims each file the runs on a route changed outside the folders this store claims: a run
+     * may have written in a folder this store was not opened with, such as a second root a history
+     * reopened by its first root alone does not know. A worktree holding one is not removed while
+     * the move writes there.
+     */
+    private claimFiles;
+    private stepAlong;
     /** Takes one run's changes back to its parent, or forward again, file by file. */
     private step;
     /**

package/dist/recovery/infrastructure/fileRecoveryStore.js

@@ -1,13 +1,14 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { link, mkdir, open, readdir, readFile, realpath, rename, rm, stat, truncate, unlink, } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join } from 'node:path';
+import { dirname, isAbsolute, join, sep } from 'node:path';
+import { FolderClaims } from "./folderClaims.js";
 import { classifyHostFailure, describeFailure, treatErrors, } from '#src/shared/domain/providerFailure';
 import { Logger } from '#src/shared/infrastructure/logger';
 import { fileChanges, sameState } from "../domain/fileChanges.js";
 import { historyStart, NothingToMoveError, WorkspaceBusyError, WorkspaceMovedError, } from "../domain/recoveryStore.js";
 import { chainEntries, nextPruneStep } from "../domain/retention.js";
-import { HistoryExpiredError, redoTarget, route, UnknownRunError } from "../domain/runTree.js";
+import { HistoryExpiredError, redoTarget, route, UnknownRunError, } from "../domain/runTree.js";
 import { currentState, hasRealParents, removeEmptyFolders, removeFile, removeTemporary, temporaryPath, writeFileState, } from "./workspaceFiles.js";
 const appName = 'mikode-harness';
 // The store holds source code the agent touched: only its owner may read it.
@@ -149,18 +150,24 @@ async function storeContent(contentDirectory, content) {
  */
 export class FileRecoveryStore {
     workspaceId;
+    writeFolders;
     root;
     directory;
     keepRuns;
     logger;
-    constructor(root, directory, keepRuns, logger, workspaceId) {
+    claims;
+    // What releases the claim of each run or move holding the workspace.
+    releases = new Map();
+    constructor(root, directory, keepRuns, logger, workspaceId, { claims, folders }) {
         this.root = root;
         this.directory = directory;
         this.keepRuns = keepRuns;
         this.logger = logger;
         this.workspaceId = workspaceId;
+        this.claims = claims;
+        this.writeFolders = folders;
     }
-    static async open({ root, directory = defaultStateDirectory(), keepRuns = defaultKeepRuns, logger = new Logger(), }) {
+    static async open({ root, directory = defaultStateDirectory(), keepRuns = defaultKeepRuns, logger = new Logger(), writeRoots = [], }) {
         if (!Number.isInteger(keepRuns) || keepRuns < 3) {
             throw new RangeError(`keepRuns must be an integer of at least 3; got ${String(keepRuns)}`);
         }
@@ -170,10 +177,17 @@ export class FileRecoveryStore {
         await makeDirectory(join(workspace, 'runs'));
         await makeDirectory(join(workspace, 'content'));
         await writeDurably(join(workspace, 'workspace.json'), JSON.stringify({ root: realRoot }));
+        const folders = [
+            realRoot,
+            ...(await Promise.all(writeRoots.map(path => realpath(path).catch(() => path)))),
+        ];
         // Real, so a state directory reached through a link is the history it holds.
-        return new FileRecoveryStore(realRoot, workspace, keepRuns, logger, await realpath(workspace));
+        return new FileRecoveryStore(realRoot, workspace, keepRuns, logger, await realpath(workspace), {
+            claims: new FolderClaims(await realpath(directory)),
+            folders,
+        });
     }
-    async startRun() {
+    async startRun({ session } = {}) {
         const runId = newRunId();
         try {
             // Inside, because taking the lock can fail after publishing it. Unlocking removes only a
@@ -196,6 +210,7 @@ export class FileRecoveryStore {
                 startedAt: new Date().toISOString(),
                 status: 'running',
                 pid: process.pid,
+                ...(session ? { session } : {}),
             };
             await writeDurably(join(runDirectory, 'run.json'), JSON.stringify(record));
             // After the record, so the head never names a run that does not exist.
@@ -399,6 +414,34 @@ export class FileRecoveryStore {
      */
     async takeSteps(head, runs, pending) {
         const { undo, redo } = route(runs, head.runId, pending.to);
+        const release = await this.claimFiles([...undo, ...redo]);
+        try {
+            return await this.stepAlong(head, runs, pending, { undo, redo });
+        }
+        finally {
+            await release();
+        }
+    }
+    /**
+     * Claims each file the runs on a route changed outside the folders this store claims: a run
+     * may have written in a folder this store was not opened with, such as a second root a history
+     * reopened by its first root alone does not know. A worktree holding one is not removed while
+     * the move writes there.
+     */
+    async claimFiles(runIds) {
+        const outside = new Set();
+        for (const runId of runIds) {
+            const { entries } = await this.readRun(runId);
+            for (const { path } of fileChanges(entries, true)) {
+                if (!this.writeFolders.some(folder => within(path, folder)))
+                    outside.add(path);
+            }
+        }
+        if (outside.size === 0)
+            return () => Promise.resolve();
+        return this.claims.claimWriting(`files-${newRunId()}`, [...outside]);
+    }
+    async stepAlong(head, runs, pending, { undo, redo }) {
         const parents = new Map(runs.map(run => [run.runId, run.parentRunId]));
         let reached = head.runId;
         const save = () => this.writeHead({ ...(reached ? { runId: reached } : {}), revision: head.revision, pending });
@@ -931,6 +974,9 @@ export class FileRecoveryStore {
                 // Written whole before it appears, so a lock that exists always names its holder.
                 await writeDurably(path, JSON.stringify({ runId, pid: process.pid }), { exclusive: true });
                 heldHere.add(runId);
+                // Under the lock: a removal of a worktree this run may write in keeps it out. The
+                // caller unlocks when this throws.
+                this.releases.set(runId, await this.claims.claimWriting(runId, this.writeFolders));
                 return;
             }
             catch (error) {
@@ -958,6 +1004,9 @@ export class FileRecoveryStore {
     async unlock(runId) {
         // First: the run has ended even if removing its lock fails, so that lock is stale.
         heldHere.delete(runId);
+        const release = this.releases.get(runId);
+        this.releases.delete(runId);
+        await release?.();
         const path = join(this.directory, 'lock');
         // Only its own lock: one cleared as stale and taken by another run is not this run's.
         if ((await readLock(path))?.runId === runId)
@@ -1049,6 +1098,9 @@ async function readLock(path) {
     }
     return { runId: 'unknown' };
 }
+function within(path, folder) {
+    return path === folder || path.startsWith(`${folder}${sep}`);
+}
 function contentPath(contentDirectory, hash) {
     // Two levels, so no folder holds every file a workspace ever stored.
     return join(contentDirectory, hash.slice(0, 2), hash);