@mikode13/harness 11.0.0 → 11.1.0

package/dist/tools/infrastructure/removeWorktreeTool.js

@@ -0,0 +1,172 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { WorkspaceBusyError } from '#src/recovery/domain/recoveryStore';
+import { FolderClaims } from '#src/recovery/infrastructure/folderClaims';
+import { definePreparingTool } from "./defineTool.js";
+import { git, listWorktrees } from "./worktrees.js";
+function within(path, folder) {
+    return path === folder || path.startsWith(`${folder}${sep}`);
+}
+/**
+ * The paths `git status --porcelain -z` names, each with its two-letter code. A rename or copy
+ * names its source after it, which is skipped.
+ */
+function statusEntries(status) {
+    const fields = status.split('\0');
+    const entries = [];
+    for (let index = 0; index < fields.length; index++) {
+        const field = fields[index] ?? '';
+        if (field.length < 4)
+            continue;
+        const code = field.slice(0, 2);
+        entries.push({ code, path: field.slice(3) });
+        if (code.startsWith('R') || code.startsWith('C'))
+            index++;
+    }
+    return entries;
+}
+async function gitOutput(args, cwd, signal) {
+    const { stdout, stderr, exitCode } = await git(args, cwd, signal);
+    if (exitCode !== 0) {
+        throw new Error(`git could not tell what removing ${cwd} would lose, so nothing was removed: ${stderr.trim()}`);
+    }
+    return stdout;
+}
+/**
+ * What removing the worktree at `path` would lose, and a fingerprint of all it rests on: its
+ * HEAD, its branch, the commits at risk, and each file `git status` names, by size and time of
+ * change. Throws when
+ * any of it cannot be read, since a removal must never be asked about with less than it loses.
+ */
+async function inspect(path, branch, signal) {
+    const head = (await gitOutput(['rev-parse', '--verify', 'HEAD'], path, signal)).trim();
+    const changed = statusEntries(await gitOutput(['status', '--porcelain=v1', '-z', '--untracked-files=all'], path, signal));
+    // A folder `.gitignore` excludes whole is named once, however much it holds.
+    const ignored = statusEntries(await gitOutput(['status', '--porcelain=v1', '-z', '--untracked-files=normal', '--ignored=matching'], path, signal)).filter(({ code }) => code === '!!');
+    // The commits only a detached HEAD holds, which are lost with it.
+    const atRisk = [];
+    if (branch === undefined) {
+        const listed = (await gitOutput(['rev-list', 'HEAD', '--not', '--branches', '--tags', '--remotes'], path, signal))
+            .split('\n')
+            .filter(line => line !== '');
+        if (!listed.every(line => /^[0-9a-f]{40,64}$/.test(line))) {
+            throw new Error(`git could not list the commits only ${path} holds, so nothing was removed: it answered "${listed.join(' ')}".`);
+        }
+        atRisk.push(...listed);
+    }
+    const files = await Promise.all([...changed, ...ignored].map(async ({ code, path: file }) => {
+        const stats = await lstat(join(path, file)).catch(() => undefined);
+        return `${code} ${file} ${String(stats?.size)} ${String(stats?.mtimeMs)}`;
+    }));
+    return {
+        removal: {
+            path,
+            ...(branch === undefined ? {} : { branch }),
+            uncommitted: changed.length,
+            ignored: ignored.length,
+            commitsOnlyHere: atRisk.length,
+        },
+        fingerprint: JSON.stringify([head, branch ?? null, atRisk, files.sort()]),
+    };
+}
+/**
+ * The worktree of this repository at `target`, checked as removable: not the main folder, not
+ * one the agent works in, and not locked. Throws a message for the model otherwise.
+ */
+async function removableWorktree(target, { base, roots }, signal) {
+    const worktrees = await listWorktrees(base, signal);
+    const [main] = worktrees;
+    if (main?.path === target) {
+        throw new Error(`${target} is the repository's main folder, not a worktree. Only a worktree can be removed.`);
+    }
+    const worktree = worktrees.find(listed => listed.path === target);
+    if (!worktree) {
+        const others = worktrees.slice(1).map(listed => listed.path);
+        throw new Error(`${target} is not a worktree of this repository. Its worktrees: ${others.join(', ') || 'none'}.`);
+    }
+    const own = await Promise.all(
+    // From the working directory, as the workspace reads them.
+    roots.map(root => realpath(resolve(root.path)).catch(() => resolve(root.path))));
+    if (own.some(root => within(root, target) || within(target, root))) {
+        throw new Error(`You work in ${target}, so it cannot be removed from this run.`);
+    }
+    if (worktree.locked) {
+        throw new Error(`${target} is locked. The user must unlock it to remove it.`);
+    }
+    return worktree;
+}
+/**
+ * `removeWorktree`: removes a git worktree of the repository the first root is in, its folder
+ * and every file in it, never its branch, which keeps its commits. Each call is `destructive`,
+ * so it is asked about, and the request names what is lost: changes no commit has, files
+ * `.gitignore` excludes, and with a detached HEAD the commits no branch, tag or remote holds. It
+ * refuses the repository's main folder, a worktree the agent works in, which holds one of its
+ * roots or lies inside one, and a locked one.
+ *
+ * Once approved it claims the worktree (`FolderClaims`), so no run that may write in it starts,
+ * and removes nothing while one works; it checks again that nothing it rests on changed while
+ * the user was asked, and otherwise removes nothing, so the model calls it again to have the
+ * user asked anew. A folder `.gitignore` excludes whole is checked as a folder, never looked
+ * into, and its result tells the model so.
+ */
+export function createRemoveWorktreeTool({ base, roots, stateDirectory, }) {
+    return definePreparingTool({
+        name: 'removeWorktree',
+        description: 'Removes a git worktree of this repository: its folder and every file in it, committed or not. Its branch stays, with its commits. Only when the user asks for it.',
+        input: z.object({
+            path: z
+                .string()
+                .describe('The folder of the worktree, absolute or relative to the first root.'),
+        }),
+        summarize: ({ path }) => path,
+        prepare: async ({ path }, signal) => {
+            const asked = resolve(base, path);
+            const target = await realpath(asked).catch(() => {
+                throw new Error(`There is no folder at ${asked}.`);
+            });
+            const worktree = await removableWorktree(target, { base, roots }, signal);
+            const { removal, fingerprint } = await inspect(target, worktree.branch, signal);
+            return {
+                risk: 'destructive',
+                worktree: removal,
+                run: async (runSignal) => {
+                    let release;
+                    try {
+                        release = await new FolderClaims(stateDirectory).claimRemoval(target);
+                    }
+                    catch (error) {
+                        if (!(error instanceof WorkspaceBusyError))
+                            throw error;
+                        throw new Error(`A run, or a move through a history, may write in ${target}, so nothing was removed. The harness removes no worktree a run may write in; tell the user, and try again once it ends.`, { cause: error });
+                    }
+                    try {
+                        const now = await removableWorktree(target, { base, roots }, runSignal);
+                        const current = await inspect(target, now.branch, runSignal);
+                        if (current.fingerprint !== fingerprint) {
+                            throw new Error(`${target} changed since the user was asked, so nothing was removed. Call removeWorktree again to have them asked with what it holds now.`);
+                        }
+                        // Forced: what it holds unsaved is what the user approved losing.
+                        const removed = await git(['worktree', 'remove', '--force', '--', target], base, runSignal);
+                        if (removed.exitCode !== 0) {
+                            throw new Error(`git could not remove ${target}: ${removed.stderr.trim()}`);
+                        }
+                    }
+                    finally {
+                        await release();
+                    }
+                    const done = `Removed the worktree at ${target}.`;
+                    const kept = removal.branch === undefined
+                        ? ''
+                        : ` Its branch ${removal.branch} stays, with its commits.`;
+                    // Told to the model, which may have to mention it: an ignored folder went unchecked.
+                    const ignored = removal.ignored === 0
+                        ? ''
+                        : ` It held ${String(removal.ignored)} ${removal.ignored === 1 ? 'path' : 'paths'} .gitignore excludes, removed whole without looking into them, so anything written in them while the user was asked went too.`;
+                    return `${done}${kept}${ignored}`;
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=removeWorktreeTool.js.map

package/dist/tools/infrastructure/removeWorktreeTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"removeWorktreeTool.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/removeWorktreeTool.ts"],"names":[],"mappings":"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","sourcesContent":["import { lstat, realpath } from 'node:fs/promises';\nimport { join, resolve, sep } from 'node:path';\nimport { z } from 'zod';\nimport type { WorktreeRemoval } from '#src/agent/domain/approval';\nimport { WorkspaceBusyError } from '#src/recovery/domain/recoveryStore';\nimport { FolderClaims } from '#src/recovery/infrastructure/folderClaims';\nimport type { WorkspaceRoot } from '../domain/accessPolicy.ts';\nimport type { PreparingTool } from '../domain/preparedCall.ts';\nimport { definePreparingTool } from './defineTool.ts';\nimport { git, listWorktrees } from './worktrees.ts';\n\nfunction within(path: string, folder: string): boolean {\n\treturn path === folder || path.startsWith(`${folder}${sep}`);\n}\n\n/**\n * The paths `git status --porcelain -z` names, each with its two-letter code. A rename or copy\n * names its source after it, which is skipped.\n */\nfunction statusEntries(status: string): { code: string; path: string }[] {\n\tconst fields = status.split('\\0');\n\tconst entries: { code: string; path: string }[] = [];\n\tfor (let index = 0; index < fields.length; index++) {\n\t\tconst field = fields[index] ?? '';\n\t\tif (field.length < 4) continue;\n\t\tconst code = field.slice(0, 2);\n\t\tentries.push({ code, path: field.slice(3) });\n\t\tif (code.startsWith('R') || code.startsWith('C')) index++;\n\t}\n\treturn entries;\n}\n\nasync function gitOutput(args: string[], cwd: string, signal: AbortSignal): Promise<string> {\n\tconst { stdout, stderr, exitCode } = await git(args, cwd, signal);\n\tif (exitCode !== 0) {\n\t\tthrow new Error(\n\t\t\t`git could not tell what removing ${cwd} would lose, so nothing was removed: ${stderr.trim()}`,\n\t\t);\n\t}\n\treturn stdout;\n}\n\n/**\n * What removing the worktree at `path` would lose, and a fingerprint of all it rests on: its\n * HEAD, its branch, the commits at risk, and each file `git status` names, by size and time of\n * change. Throws when\n * any of it cannot be read, since a removal must never be asked about with less than it loses.\n */\nasync function inspect(\n\tpath: string,\n\tbranch: string | undefined,\n\tsignal: AbortSignal,\n): Promise<{ removal: WorktreeRemoval; fingerprint: string }> {\n\tconst head = (await gitOutput(['rev-parse', '--verify', 'HEAD'], path, signal)).trim();\n\tconst changed = statusEntries(\n\t\tawait gitOutput(['status', '--porcelain=v1', '-z', '--untracked-files=all'], path, signal),\n\t);\n\t// A folder `.gitignore` excludes whole is named once, however much it holds.\n\tconst ignored = statusEntries(\n\t\tawait gitOutput(\n\t\t\t['status', '--porcelain=v1', '-z', '--untracked-files=normal', '--ignored=matching'],\n\t\t\tpath,\n\t\t\tsignal,\n\t\t),\n\t).filter(({ code }) => code === '!!');\n\t// The commits only a detached HEAD holds, which are lost with it.\n\tconst atRisk: string[] = [];\n\tif (branch === undefined) {\n\t\tconst listed = (\n\t\t\tawait gitOutput(\n\t\t\t\t['rev-list', 'HEAD', '--not', '--branches', '--tags', '--remotes'],\n\t\t\t\tpath,\n\t\t\t\tsignal,\n\t\t\t)\n\t\t)\n\t\t\t.split('\\n')\n\t\t\t.filter(line => line !== '');\n\t\tif (!listed.every(line => /^[0-9a-f]{40,64}$/.test(line))) {\n\t\t\tthrow new Error(\n\t\t\t\t`git could not list the commits only ${path} holds, so nothing was removed: it answered \"${listed.join(' ')}\".`,\n\t\t\t);\n\t\t}\n\t\tatRisk.push(...listed);\n\t}\n\tconst files = await Promise.all(\n\t\t[...changed, ...ignored].map(async ({ code, path: file }) => {\n\t\t\tconst stats = await lstat(join(path, file)).catch(() => undefined);\n\t\t\treturn `${code} ${file} ${String(stats?.size)} ${String(stats?.mtimeMs)}`;\n\t\t}),\n\t);\n\treturn {\n\t\tremoval: {\n\t\t\tpath,\n\t\t\t...(branch === undefined ? {} : { branch }),\n\t\t\tuncommitted: changed.length,\n\t\t\tignored: ignored.length,\n\t\t\tcommitsOnlyHere: atRisk.length,\n\t\t},\n\t\tfingerprint: JSON.stringify([head, branch ?? null, atRisk, files.sort()]),\n\t};\n}\n\n/**\n * The worktree of this repository at `target`, checked as removable: not the main folder, not\n * one the agent works in, and not locked. Throws a message for the model otherwise.\n */\nasync function removableWorktree(\n\ttarget: string,\n\t{ base, roots }: { base: string; roots: readonly WorkspaceRoot[] },\n\tsignal: AbortSignal,\n) {\n\tconst worktrees = await listWorktrees(base, signal);\n\tconst [main] = worktrees;\n\tif (main?.path === target) {\n\t\tthrow new Error(\n\t\t\t`${target} is the repository's main folder, not a worktree. Only a worktree can be removed.`,\n\t\t);\n\t}\n\tconst worktree = worktrees.find(listed => listed.path === target);\n\tif (!worktree) {\n\t\tconst others = worktrees.slice(1).map(listed => listed.path);\n\t\tthrow new Error(\n\t\t\t`${target} is not a worktree of this repository. Its worktrees: ${others.join(', ') || 'none'}.`,\n\t\t);\n\t}\n\tconst own = await Promise.all(\n\t\t// From the working directory, as the workspace reads them.\n\t\troots.map(root => realpath(resolve(root.path)).catch(() => resolve(root.path))),\n\t);\n\tif (own.some(root => within(root, target) || within(target, root))) {\n\t\tthrow new Error(`You work in ${target}, so it cannot be removed from this run.`);\n\t}\n\tif (worktree.locked) {\n\t\tthrow new Error(`${target} is locked. The user must unlock it to remove it.`);\n\t}\n\treturn worktree;\n}\n\n/**\n * `removeWorktree`: removes a git worktree of the repository the first root is in, its folder\n * and every file in it, never its branch, which keeps its commits. Each call is `destructive`,\n * so it is asked about, and the request names what is lost: changes no commit has, files\n * `.gitignore` excludes, and with a detached HEAD the commits no branch, tag or remote holds. It\n * refuses the repository's main folder, a worktree the agent works in, which holds one of its\n * roots or lies inside one, and a locked one.\n *\n * Once approved it claims the worktree (`FolderClaims`), so no run that may write in it starts,\n * and removes nothing while one works; it checks again that nothing it rests on changed while\n * the user was asked, and otherwise removes nothing, so the model calls it again to have the\n * user asked anew. A folder `.gitignore` excludes whole is checked as a folder, never looked\n * into, and its result tells the model so.\n */\nexport function createRemoveWorktreeTool({\n\tbase,\n\troots,\n\tstateDirectory,\n}: {\n\t/** The real path of the first root. */\n\tbase: string;\n\troots: readonly WorkspaceRoot[];\n\t/** Where the histories are kept, as a real path: their runs' claims are there. */\n\tstateDirectory: string;\n}): PreparingTool {\n\treturn definePreparingTool({\n\t\tname: 'removeWorktree',\n\t\tdescription:\n\t\t\t'Removes a git worktree of this repository: its folder and every file in it, committed or not. Its branch stays, with its commits. Only when the user asks for it.',\n\t\tinput: z.object({\n\t\t\tpath: z\n\t\t\t\t.string()\n\t\t\t\t.describe('The folder of the worktree, absolute or relative to the first root.'),\n\t\t}),\n\t\tsummarize: ({ path }) => path,\n\t\tprepare: async ({ path }, signal) => {\n\t\t\tconst asked = resolve(base, path);\n\t\t\tconst target = await realpath(asked).catch(() => {\n\t\t\t\tthrow new Error(`There is no folder at ${asked}.`);\n\t\t\t});\n\t\t\tconst worktree = await removableWorktree(target, { base, roots }, signal);\n\t\t\tconst { removal, fingerprint } = await inspect(target, worktree.branch, signal);\n\t\t\treturn {\n\t\t\t\trisk: 'destructive',\n\t\t\t\tworktree: removal,\n\t\t\t\trun: async runSignal => {\n\t\t\t\t\tlet release: () => Promise<void>;\n\t\t\t\t\ttry {\n\t\t\t\t\t\trelease = await new FolderClaims(stateDirectory).claimRemoval(target);\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\tif (!(error instanceof WorkspaceBusyError)) throw error;\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t`A run, or a move through a history, may write in ${target}, so nothing was removed. The harness removes no worktree a run may write in; tell the user, and try again once it ends.`,\n\t\t\t\t\t\t\t{ cause: error },\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst now = await removableWorktree(target, { base, roots }, runSignal);\n\t\t\t\t\t\tconst current = await inspect(target, now.branch, runSignal);\n\t\t\t\t\t\tif (current.fingerprint !== fingerprint) {\n\t\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t\t`${target} changed since the user was asked, so nothing was removed. Call removeWorktree again to have them asked with what it holds now.`,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Forced: what it holds unsaved is what the user approved losing.\n\t\t\t\t\t\tconst removed = await git(\n\t\t\t\t\t\t\t['worktree', 'remove', '--force', '--', target],\n\t\t\t\t\t\t\tbase,\n\t\t\t\t\t\t\trunSignal,\n\t\t\t\t\t\t);\n\t\t\t\t\t\tif (removed.exitCode !== 0) {\n\t\t\t\t\t\t\tthrow new Error(`git could not remove ${target}: ${removed.stderr.trim()}`);\n\t\t\t\t\t\t}\n\t\t\t\t\t} finally {\n\t\t\t\t\t\tawait release();\n\t\t\t\t\t}\n\t\t\t\t\tconst done = `Removed the worktree at ${target}.`;\n\t\t\t\t\tconst kept =\n\t\t\t\t\t\tremoval.branch === undefined\n\t\t\t\t\t\t\t? ''\n\t\t\t\t\t\t\t: ` Its branch ${removal.branch} stays, with its commits.`;\n\t\t\t\t\t// Told to the model, which may have to mention it: an ignored folder went unchecked.\n\t\t\t\t\tconst ignored =\n\t\t\t\t\t\tremoval.ignored === 0\n\t\t\t\t\t\t\t? ''\n\t\t\t\t\t\t\t: ` It held ${String(removal.ignored)} ${removal.ignored === 1 ? 'path' : 'paths'} .gitignore excludes, removed whole without looking into them, so anything written in them while the user was asked went too.`;\n\t\t\t\t\treturn `${done}${kept}${ignored}`;\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t});\n}\n"]}

package/dist/tools/infrastructure/workspaceWrites.d.ts

@@ -25,6 +25,10 @@ export declare class WorkspaceWrites {
      * Everything this run writes to this history, its commands' changes included, from any set of
      * tools. Created on its first write, and registered before anything is awaited, so two tools
      * asking at once get the same one.
+     *
+     * @throws {EditRefusedError} for a set of tools that may write outside the folders of the set
+     * that started the session: the run claims those alone, so a worktree removed meanwhile could
+     * lose what it writes there.
      */
     sessionFor(context: RunContext): WriteSession;
 }

package/dist/tools/infrastructure/workspaceWrites.js

@@ -1,9 +1,14 @@
+import { sep } from 'node:path';
+import { EditRefusedError } from "../domain/fileEdits.js";
 import { FileEditor } from "./fileEditor.js";
 import { WriteSession } from "./writeSession.js";
 // One session per run and history on disk, whichever set of tools asks for it: two sets built
 // apart over one workspace, such as two stages of a workflow, record one run. Each keeps its own
 // policy. Kept by the run's context, so nothing here outlives a run.
 const sessions = new WeakMap();
+function within(path, folder) {
+    return path === folder || path.startsWith(`${folder}${sep}`);
+}
 /**
  * The writing side of a workspace, shared by every write tool built over it: one policy and
  * one recovery store. Every set of tools over the same history shares the run's `WriteSession`,
@@ -27,6 +32,10 @@ export class WorkspaceWrites {
      * Everything this run writes to this history, its commands' changes included, from any set of
      * tools. Created on its first write, and registered before anything is awaited, so two tools
      * asking at once get the same one.
+     *
+     * @throws {EditRefusedError} for a set of tools that may write outside the folders of the set
+     * that started the session: the run claims those alone, so a worktree removed meanwhile could
+     * lose what it writes there.
      */
     sessionFor(context) {
         let ofRun = sessions.get(context);
@@ -34,23 +43,28 @@ export class WorkspaceWrites {
             ofRun = new Map();
             sessions.set(context, ofRun);
         }
-        let session = ofRun.get(this.store.workspaceId);
-        if (!session) {
-            const created = new WriteSession({
-                store: this.store,
-                // So every turn of the run, in every role, can be tied to what it wrote.
-                onStart: runId => {
-                    context.historyRun.runId = runId;
-                },
-                // A run that changed nothing is not in the history, so its turns wrote nothing.
-                onDiscard: () => {
-                    delete context.historyRun.runId;
-                },
-            });
-            context.onFinish(end => created.finish(end));
-            ofRun.set(this.store.workspaceId, created);
-            session = created;
+        const started = ofRun.get(this.store.workspaceId);
+        if (started) {
+            const outside = this.store.writeFolders.filter(folder => !started.folders.some(claimed => within(folder, claimed)));
+            if (outside.length > 0) {
+                throw new EditRefusedError(`This run already writes to this workspace's history with tools that may write only in ${started.folders.join(', ')}; tools that may also write in ${outside.join(', ')} cannot join it, so nothing was changed. It is a limit of the harness: in one run, every set of tools that writes to a history may write only where the first one may. Tell the user.`);
+            }
+            return started.session;
         }
+        const session = new WriteSession({
+            store: this.store,
+            session: context.session,
+            // So every turn of the run, in every role, can be tied to what it wrote.
+            onStart: runId => {
+                context.historyRun.runId = runId;
+            },
+            // A run that changed nothing is not in the history, so its turns wrote nothing.
+            onDiscard: () => {
+                delete context.historyRun.runId;
+            },
+        });
+        context.onFinish(end => session.finish(end));
+        ofRun.set(this.store.workspaceId, { session, folders: this.store.writeFolders });
         return session;
     }
 }

package/dist/tools/infrastructure/workspaceWrites.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspaceWrites.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/workspaceWrites.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,8FAA8F;AAC9F,iGAAiG;AACjG,qEAAqE;AACrE,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAyC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,OAAO,eAAe;IAC3B,8FAA8F;IACrF,SAAS,CAA4B;IAC7B,MAAM,CAAe;IACrB,KAAK,CAAgB;IAEtC,YAAY,EACX,MAAM,EACN,KAAK,EACL,SAAS,GAKT;QACA,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;IAED,0EAA0E;IAC1E,SAAS,CAAC,OAAmB;QAC5B,OAAO,IAAI,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,OAAmB;QAC7B,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;YAClB,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAChD,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC;gBAChC,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,yEAAyE;gBACzE,OAAO,EAAE,KAAK,CAAC,EAAE;oBAChB,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,KAAK,CAAC;gBAClC,CAAC;gBACD,gFAAgF;gBAChF,SAAS,EAAE,GAAG,EAAE;oBACf,OAAO,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;gBACjC,CAAC;aACD,CAAC,CAAC;YACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC7C,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC3C,OAAO,GAAG,OAAO,CAAC;QACnB,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;CACD","sourcesContent":["import type { RunContext } from '#src/agent/domain/runContext';\nimport type { RecoveryStore } from '#src/recovery/domain/recoveryStore';\nimport type { AccessPolicy } from '../domain/accessPolicy.ts';\nimport { FileEditor } from './fileEditor.ts';\nimport type { FileFormatter } from './fileFormatter.ts';\nimport { WriteSession } from './writeSession.ts';\n\n// One session per run and history on disk, whichever set of tools asks for it: two sets built\n// apart over one workspace, such as two stages of a workflow, record one run. Each keeps its own\n// policy. Kept by the run's context, so nothing here outlives a run.\nconst sessions = new WeakMap<RunContext, Map<string, WriteSession>>();\n\n/**\n * The writing side of a workspace, shared by every write tool built over it: one policy and\n * one recovery store. Every set of tools over the same history shares the run's `WriteSession`,\n * ended with that run.\n */\nexport class WorkspaceWrites {\n\t/** What the edit tools run on each file they create or change, when the consumer gave one. */\n\treadonly formatter: FileFormatter | undefined;\n\tprivate readonly policy: AccessPolicy;\n\tprivate readonly store: RecoveryStore;\n\n\tconstructor({\n\t\tpolicy,\n\t\tstore,\n\t\tformatter,\n\t}: {\n\t\tpolicy: AccessPolicy;\n\t\tstore: RecoveryStore;\n\t\tformatter?: FileFormatter;\n\t}) {\n\t\tthis.policy = policy;\n\t\tthis.store = store;\n\t\tthis.formatter = formatter;\n\t}\n\n\t/** An editor over this run's session, under this set of tools' policy. */\n\teditorFor(context: RunContext): FileEditor {\n\t\treturn new FileEditor({ policy: this.policy, session: this.sessionFor(context) });\n\t}\n\n\t/**\n\t * Everything this run writes to this history, its commands' changes included, from any set of\n\t * tools. Created on its first write, and registered before anything is awaited, so two tools\n\t * asking at once get the same one.\n\t */\n\tsessionFor(context: RunContext): WriteSession {\n\t\tlet ofRun = sessions.get(context);\n\t\tif (!ofRun) {\n\t\t\tofRun = new Map();\n\t\t\tsessions.set(context, ofRun);\n\t\t}\n\t\tlet session = ofRun.get(this.store.workspaceId);\n\t\tif (!session) {\n\t\t\tconst created = new WriteSession({\n\t\t\t\tstore: this.store,\n\t\t\t\t// So every turn of the run, in every role, can be tied to what it wrote.\n\t\t\t\tonStart: runId => {\n\t\t\t\t\tcontext.historyRun.runId = runId;\n\t\t\t\t},\n\t\t\t\t// A run that changed nothing is not in the history, so its turns wrote nothing.\n\t\t\t\tonDiscard: () => {\n\t\t\t\t\tdelete context.historyRun.runId;\n\t\t\t\t},\n\t\t\t});\n\t\t\tcontext.onFinish(end => created.finish(end));\n\t\t\tofRun.set(this.store.workspaceId, created);\n\t\t\tsession = created;\n\t\t}\n\t\treturn session;\n\t}\n}\n"]}
+{"version":3,"file":"workspaceWrites.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/workspaceWrites.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,8FAA8F;AAC9F,iGAAiG;AACjG,qEAAqE;AACrE,MAAM,QAAQ,GAAG,IAAI,OAAO,EAGzB,CAAC;AAEJ,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC3C,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,eAAe;IAC3B,8FAA8F;IACrF,SAAS,CAA4B;IAC7B,MAAM,CAAe;IACrB,KAAK,CAAgB;IAEtC,YAAY,EACX,MAAM,EACN,KAAK,EACL,SAAS,GAKT;QACA,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;IAED,0EAA0E;IAC1E,SAAS,CAAC,OAAmB;QAC5B,OAAO,IAAI,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAmB;QAC7B,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;YAClB,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,OAAO,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAC7C,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CACnE,CAAC;YACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,gBAAgB,CACzB,yFAAyF,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,kCAAkC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,uLAAuL,CAC9V,CAAC;YACH,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,CAAC;QACxB,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC;YAChC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,yEAAyE;YACzE,OAAO,EAAE,KAAK,CAAC,EAAE;gBAChB,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,KAAK,CAAC;YAClC,CAAC;YACD,gFAAgF;YAChF,SAAS,EAAE,GAAG,EAAE;gBACf,OAAO,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;YACjC,CAAC;SACD,CAAC,CAAC;QACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7C,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;QACjF,OAAO,OAAO,CAAC;IAChB,CAAC;CACD","sourcesContent":["import type { RunContext } from '#src/agent/domain/runContext';\nimport type { RecoveryStore } from '#src/recovery/domain/recoveryStore';\nimport type { AccessPolicy } from '../domain/accessPolicy.ts';\nimport { sep } from 'node:path';\nimport { EditRefusedError } from '../domain/fileEdits.ts';\nimport { FileEditor } from './fileEditor.ts';\nimport type { FileFormatter } from './fileFormatter.ts';\nimport { WriteSession } from './writeSession.ts';\n\n// One session per run and history on disk, whichever set of tools asks for it: two sets built\n// apart over one workspace, such as two stages of a workflow, record one run. Each keeps its own\n// policy. Kept by the run's context, so nothing here outlives a run.\nconst sessions = new WeakMap<\n\tRunContext,\n\tMap<string, { session: WriteSession; folders: readonly string[] }>\n>();\n\nfunction within(path: string, folder: string): boolean {\n\treturn path === folder || path.startsWith(`${folder}${sep}`);\n}\n\n/**\n * The writing side of a workspace, shared by every write tool built over it: one policy and\n * one recovery store. Every set of tools over the same history shares the run's `WriteSession`,\n * ended with that run.\n */\nexport class WorkspaceWrites {\n\t/** What the edit tools run on each file they create or change, when the consumer gave one. */\n\treadonly formatter: FileFormatter | undefined;\n\tprivate readonly policy: AccessPolicy;\n\tprivate readonly store: RecoveryStore;\n\n\tconstructor({\n\t\tpolicy,\n\t\tstore,\n\t\tformatter,\n\t}: {\n\t\tpolicy: AccessPolicy;\n\t\tstore: RecoveryStore;\n\t\tformatter?: FileFormatter;\n\t}) {\n\t\tthis.policy = policy;\n\t\tthis.store = store;\n\t\tthis.formatter = formatter;\n\t}\n\n\t/** An editor over this run's session, under this set of tools' policy. */\n\teditorFor(context: RunContext): FileEditor {\n\t\treturn new FileEditor({ policy: this.policy, session: this.sessionFor(context) });\n\t}\n\n\t/**\n\t * Everything this run writes to this history, its commands' changes included, from any set of\n\t * tools. Created on its first write, and registered before anything is awaited, so two tools\n\t * asking at once get the same one.\n\t *\n\t * @throws {EditRefusedError} for a set of tools that may write outside the folders of the set\n\t * that started the session: the run claims those alone, so a worktree removed meanwhile could\n\t * lose what it writes there.\n\t */\n\tsessionFor(context: RunContext): WriteSession {\n\t\tlet ofRun = sessions.get(context);\n\t\tif (!ofRun) {\n\t\t\tofRun = new Map();\n\t\t\tsessions.set(context, ofRun);\n\t\t}\n\t\tconst started = ofRun.get(this.store.workspaceId);\n\t\tif (started) {\n\t\t\tconst outside = this.store.writeFolders.filter(\n\t\t\t\tfolder => !started.folders.some(claimed => within(folder, claimed)),\n\t\t\t);\n\t\t\tif (outside.length > 0) {\n\t\t\t\tthrow new EditRefusedError(\n\t\t\t\t\t`This run already writes to this workspace's history with tools that may write only in ${started.folders.join(', ')}; tools that may also write in ${outside.join(', ')} cannot join it, so nothing was changed. It is a limit of the harness: in one run, every set of tools that writes to a history may write only where the first one may. Tell the user.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn started.session;\n\t\t}\n\t\tconst session = new WriteSession({\n\t\t\tstore: this.store,\n\t\t\tsession: context.session,\n\t\t\t// So every turn of the run, in every role, can be tied to what it wrote.\n\t\t\tonStart: runId => {\n\t\t\t\tcontext.historyRun.runId = runId;\n\t\t\t},\n\t\t\t// A run that changed nothing is not in the history, so its turns wrote nothing.\n\t\t\tonDiscard: () => {\n\t\t\t\tdelete context.historyRun.runId;\n\t\t\t},\n\t\t});\n\t\tcontext.onFinish(end => session.finish(end));\n\t\tofRun.set(this.store.workspaceId, { session, folders: this.store.writeFolders });\n\t\treturn session;\n\t}\n}\n"]}

package/dist/tools/infrastructure/worktrees.d.ts

@@ -0,0 +1,49 @@
+/** Runs git in `cwd`, its output unaffected by the user's colour settings. */
+export declare function git(args: string[], cwd: string, signal?: AbortSignal): Promise<import("./runProcess.ts").ProcessResult>;
+/**
+ * Whether `git version` names a git new enough for worktrees: `git version 2.39.3 (Apple
+ * Git-146)` is, `git version 2.34.1` is not. An answer it cannot read is not.
+ */
+export declare function supportsWorktrees(versionOutput: string): boolean;
+/** One worktree of a repository, as `git worktree list` gives it. */
+export interface ListedWorktree {
+    /** Its folder, as a real path. */
+    path: string;
+    /** The branch it has checked out; absent when its HEAD is detached. */
+    branch?: string;
+    locked: boolean;
+}
+/**
+ * Every worktree of the repository `cwd` belongs to, the main folder first.
+ *
+ * @throws {Error} when git is older than 2.36, or `cwd` is in no git repository.
+ */
+export declare function listWorktrees(cwd: string, signal?: AbortSignal): Promise<ListedWorktree[]>;
+/**
+ * Creates a git worktree of `repository` on a new branch, `branch`, started at `from`, so an
+ * agent can work there apart from other runs on the same repository: it is a folder of its own,
+ * with a history of runs of its own. Give its `path` as an agent's root.
+ *
+ * Without `path`, it goes in a folder beside the repository's main folder, named after it:
+ * `../<repository>-worktrees/<branch>`, any `/` in the branch made a `-`. A relative `path` is
+ * from the working directory. The harness never removes it; the user does, or an agent given
+ * `removeWorktree` when the user asks it to.
+ *
+ * @throws {UnrecoverableError} when git is older than 2.36, `repository` is in no git
+ * repository, `branch` is not a valid new branch or already exists, `from` names no commit, or
+ * the folder already exists and is not empty. A failure leaves no branch or folder it made
+ * behind.
+ */
+export declare function createWorktree({ repository, branch, from, path, }: {
+    /** A folder of the repository: its main folder, or one of its worktrees. */
+    repository: string;
+    /** The new branch the worktree checks out. */
+    branch: string;
+    /** The revision the branch starts at, such as `main` or a commit. */
+    from: string;
+    /** Where the worktree goes. */
+    path?: string;
+}): Promise<{
+    path: string;
+    branch: string;
+}>;

package/dist/tools/infrastructure/worktrees.js

@@ -0,0 +1,154 @@
+import { mkdir, readdir, realpath, rmdir } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { UnrecoverableError } from '#src/shared/domain/errors';
+import { runProcess } from "./runProcess.js";
+// Never cancelled: creating a worktree is short, and the consumer waits for it.
+const uncancelled = new AbortController().signal;
+/** Runs git in `cwd`, its output unaffected by the user's colour settings. */
+export function git(args, cwd, signal = uncancelled) {
+    return runProcess('git', ['-c', 'color.ui=never', ...args], { cwd, signal });
+}
+function firstLine(text) {
+    return text.trim().split('\n')[0] ?? '';
+}
+// The first git whose `worktree list` takes `-z`, without which a path holding a newline is
+// misread.
+const oldestGit = [2, 36];
+/**
+ * Whether `git version` names a git new enough for worktrees: `git version 2.39.3 (Apple
+ * Git-146)` is, `git version 2.34.1` is not. An answer it cannot read is not.
+ */
+export function supportsWorktrees(versionOutput) {
+    const match = /^git version (\d+)\.(\d+)/.exec(versionOutput.trim());
+    if (!match)
+        return false;
+    const [major, minor] = [Number(match[1]), Number(match[2])];
+    return major > oldestGit[0] || (major === oldestGit[0] && minor >= oldestGit[1]);
+}
+/** Throws, naming the version found, unless this machine's git is new enough for worktrees. */
+async function checkGit(cwd, signal) {
+    const { stdout, stderr, exitCode } = await git(['version'], cwd, signal);
+    if (exitCode !== 0)
+        throw new Error(`git could not be run: ${firstLine(stderr)}`);
+    if (!supportsWorktrees(stdout)) {
+        throw new Error(`worktrees need git ${oldestGit.join('.')} or later, and this machine has ${firstLine(stdout) || 'an unknown version'}`);
+    }
+}
+/**
+ * Every worktree of the repository `cwd` belongs to, the main folder first.
+ *
+ * @throws {Error} when git is older than 2.36, or `cwd` is in no git repository.
+ */
+export async function listWorktrees(cwd, signal) {
+    await checkGit(cwd, signal);
+    const { stdout, stderr, exitCode } = await git(['worktree', 'list', '--porcelain', '-z'], cwd, signal);
+    if (exitCode !== 0)
+        throw new Error(`git could not list the worktrees: ${firstLine(stderr)}`);
+    const worktrees = [];
+    let current;
+    // One attribute per NUL-terminated field, and an empty field between worktrees.
+    for (const field of stdout.split('\0')) {
+        if (field.startsWith('worktree ')) {
+            current = { path: field.slice('worktree '.length), locked: false };
+            worktrees.push(current);
+        }
+        else if (current && field.startsWith('branch refs/heads/')) {
+            current.branch = field.slice('branch refs/heads/'.length);
+        }
+        else if (current && (field === 'locked' || field.startsWith('locked '))) {
+            current.locked = true;
+        }
+    }
+    // git prints the paths it was given; a link in one must not hide a match.
+    return Promise.all(worktrees.map(async (worktree) => ({
+        ...worktree,
+        path: await realpath(worktree.path).catch(() => worktree.path),
+    })));
+}
+/**
+ * Removes the branch this call made, once its worktree could not be added: only while it still
+ * points at `sha`, which `update-ref` checks as it deletes, and no worktree has it.
+ */
+async function removeOwnBranch(cwd, branch, sha) {
+    const worktrees = await listWorktrees(cwd).catch(() => undefined);
+    if (!worktrees?.every(worktree => worktree.branch !== branch))
+        return;
+    await git(['update-ref', '-d', `refs/heads/${branch}`, sha], cwd);
+}
+function failed(what, cause) {
+    return new UnrecoverableError(`The worktree could not be created: ${what}`, { cause });
+}
+/**
+ * Creates a git worktree of `repository` on a new branch, `branch`, started at `from`, so an
+ * agent can work there apart from other runs on the same repository: it is a folder of its own,
+ * with a history of runs of its own. Give its `path` as an agent's root.
+ *
+ * Without `path`, it goes in a folder beside the repository's main folder, named after it:
+ * `../<repository>-worktrees/<branch>`, any `/` in the branch made a `-`. A relative `path` is
+ * from the working directory. The harness never removes it; the user does, or an agent given
+ * `removeWorktree` when the user asks it to.
+ *
+ * @throws {UnrecoverableError} when git is older than 2.36, `repository` is in no git
+ * repository, `branch` is not a valid new branch or already exists, `from` names no commit, or
+ * the folder already exists and is not empty. A failure leaves no branch or folder it made
+ * behind.
+ */
+export async function createWorktree({ repository, branch, from, path, }) {
+    const cwd = resolve(repository);
+    // First: an older git could make the branch and then fail to list the worktrees.
+    await checkGit(cwd).catch((error) => {
+        throw failed(error instanceof Error ? error.message : String(error), 'Update git.');
+    });
+    const valid = await git(['check-ref-format', '--branch', branch], cwd);
+    if (valid.exitCode !== 0) {
+        throw failed(`"${branch}" is not a valid branch name`, firstLine(valid.stderr) || 'git refused it.');
+    }
+    // Resolved first, so a revision that starts with a dash can never be read as an option.
+    const commit = await git(['rev-parse', '--verify', '--quiet', '--end-of-options', `${from}^{commit}`], cwd);
+    if (commit.exitCode !== 0) {
+        throw failed(`"${from}" names no commit`, firstLine(commit.stderr) || 'git found no such revision.');
+    }
+    const sha = commit.stdout.trim();
+    const ref = `refs/heads/${branch}`;
+    if ((await git(['show-ref', '--verify', '--quiet', ref], cwd)).exitCode === 0) {
+        throw failed(`the branch "${branch}" already exists`, 'Name a new branch.');
+    }
+    let target;
+    if (path === undefined) {
+        const [main] = await listWorktrees(cwd).catch((error) => {
+            // git's own words: no repository is one cause among others.
+            throw failed(error instanceof Error ? error.message : String(error), `In ${cwd}.`);
+        });
+        if (!main)
+            throw failed(`${cwd} is in no git repository`, 'git listed no worktree.');
+        target = join(dirname(main.path), `${basename(main.path)}-worktrees`, branch.replaceAll('/', '-'));
+    }
+    else {
+        target = resolve(path);
+    }
+    // git takes an empty folder, but would create the branch before refusing a full one.
+    const held = await readdir(target).catch((error) => error.code === 'ENOENT' ? [] : undefined);
+    if (held === undefined || held.length > 0) {
+        throw failed(`${target} already exists`, 'Give the worktree a folder that does not.');
+    }
+    // The first folder this call made, if any, which it removes again should git fail.
+    const made = path === undefined ? await mkdir(dirname(target), { recursive: true }) : undefined;
+    const removeMade = async () => {
+        if (made !== undefined)
+            await rmdir(made).catch(() => undefined);
+    };
+    // Made apart and first: git refuses a branch that exists, so the one made here is this call's.
+    const created = await git(['branch', '--no-track', branch, sha], cwd);
+    if (created.exitCode !== 0) {
+        await removeMade();
+        throw failed(`the branch "${branch}" could not be made`, firstLine(created.stderr));
+    }
+    const added = await git(['worktree', 'add', '--', target, branch], cwd);
+    if (added.exitCode !== 0) {
+        await removeOwnBranch(cwd, branch, sha);
+        await removeMade();
+        throw failed('git refused it', firstLine(added.stderr));
+    }
+    return { path: await realpath(target), branch };
+}
+//# sourceMappingURL=worktrees.js.map

package/dist/tools/infrastructure/worktrees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktrees.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/worktrees.ts"],"names":[],"mappings":"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","sourcesContent":["import { mkdir, readdir, realpath, rmdir } from 'node:fs/promises';\nimport { basename, dirname, join, resolve } from 'node:path';\nimport { UnrecoverableError } from '#src/shared/domain/errors';\nimport { runProcess } from './runProcess.ts';\n\n// Never cancelled: creating a worktree is short, and the consumer waits for it.\nconst uncancelled = new AbortController().signal;\n\n/** Runs git in `cwd`, its output unaffected by the user's colour settings. */\nexport function git(args: string[], cwd: string, signal: AbortSignal = uncancelled) {\n\treturn runProcess('git', ['-c', 'color.ui=never', ...args], { cwd, signal });\n}\n\nfunction firstLine(text: string): string {\n\treturn text.trim().split('\\n')[0] ?? '';\n}\n\n// The first git whose `worktree list` takes `-z`, without which a path holding a newline is\n// misread.\nconst oldestGit = [2, 36] as const;\n\n/**\n * Whether `git version` names a git new enough for worktrees: `git version 2.39.3 (Apple\n * Git-146)` is, `git version 2.34.1` is not. An answer it cannot read is not.\n */\nexport function supportsWorktrees(versionOutput: string): boolean {\n\tconst match = /^git version (\\d+)\\.(\\d+)/.exec(versionOutput.trim());\n\tif (!match) return false;\n\tconst [major, minor] = [Number(match[1]), Number(match[2])];\n\treturn major > oldestGit[0] || (major === oldestGit[0] && minor >= oldestGit[1]);\n}\n\n/** Throws, naming the version found, unless this machine's git is new enough for worktrees. */\nasync function checkGit(cwd: string, signal?: AbortSignal): Promise<void> {\n\tconst { stdout, stderr, exitCode } = await git(['version'], cwd, signal);\n\tif (exitCode !== 0) throw new Error(`git could not be run: ${firstLine(stderr)}`);\n\tif (!supportsWorktrees(stdout)) {\n\t\tthrow new Error(\n\t\t\t`worktrees need git ${oldestGit.join('.')} or later, and this machine has ${firstLine(stdout) || 'an unknown version'}`,\n\t\t);\n\t}\n}\n\n/** One worktree of a repository, as `git worktree list` gives it. */\nexport interface ListedWorktree {\n\t/** Its folder, as a real path. */\n\tpath: string;\n\t/** The branch it has checked out; absent when its HEAD is detached. */\n\tbranch?: string;\n\tlocked: boolean;\n}\n\n/**\n * Every worktree of the repository `cwd` belongs to, the main folder first.\n *\n * @throws {Error} when git is older than 2.36, or `cwd` is in no git repository.\n */\nexport async function listWorktrees(cwd: string, signal?: AbortSignal): Promise<ListedWorktree[]> {\n\tawait checkGit(cwd, signal);\n\tconst { stdout, stderr, exitCode } = await git(\n\t\t['worktree', 'list', '--porcelain', '-z'],\n\t\tcwd,\n\t\tsignal,\n\t);\n\tif (exitCode !== 0) throw new Error(`git could not list the worktrees: ${firstLine(stderr)}`);\n\tconst worktrees: ListedWorktree[] = [];\n\tlet current: ListedWorktree | undefined;\n\t// One attribute per NUL-terminated field, and an empty field between worktrees.\n\tfor (const field of stdout.split('\\0')) {\n\t\tif (field.startsWith('worktree ')) {\n\t\t\tcurrent = { path: field.slice('worktree '.length), locked: false };\n\t\t\tworktrees.push(current);\n\t\t} else if (current && field.startsWith('branch refs/heads/')) {\n\t\t\tcurrent.branch = field.slice('branch refs/heads/'.length);\n\t\t} else if (current && (field === 'locked' || field.startsWith('locked '))) {\n\t\t\tcurrent.locked = true;\n\t\t}\n\t}\n\t// git prints the paths it was given; a link in one must not hide a match.\n\treturn Promise.all(\n\t\tworktrees.map(async worktree => ({\n\t\t\t...worktree,\n\t\t\tpath: await realpath(worktree.path).catch(() => worktree.path),\n\t\t})),\n\t);\n}\n\n/**\n * Removes the branch this call made, once its worktree could not be added: only while it still\n * points at `sha`, which `update-ref` checks as it deletes, and no worktree has it.\n */\nasync function removeOwnBranch(cwd: string, branch: string, sha: string): Promise<void> {\n\tconst worktrees = await listWorktrees(cwd).catch(() => undefined);\n\tif (!worktrees?.every(worktree => worktree.branch !== branch)) return;\n\tawait git(['update-ref', '-d', `refs/heads/${branch}`, sha], cwd);\n}\n\nfunction failed(what: string, cause: string): UnrecoverableError {\n\treturn new UnrecoverableError(`The worktree could not be created: ${what}`, { cause });\n}\n\n/**\n * Creates a git worktree of `repository` on a new branch, `branch`, started at `from`, so an\n * agent can work there apart from other runs on the same repository: it is a folder of its own,\n * with a history of runs of its own. Give its `path` as an agent's root.\n *\n * Without `path`, it goes in a folder beside the repository's main folder, named after it:\n * `../<repository>-worktrees/<branch>`, any `/` in the branch made a `-`. A relative `path` is\n * from the working directory. The harness never removes it; the user does, or an agent given\n * `removeWorktree` when the user asks it to.\n *\n * @throws {UnrecoverableError} when git is older than 2.36, `repository` is in no git\n * repository, `branch` is not a valid new branch or already exists, `from` names no commit, or\n * the folder already exists and is not empty. A failure leaves no branch or folder it made\n * behind.\n */\nexport async function createWorktree({\n\trepository,\n\tbranch,\n\tfrom,\n\tpath,\n}: {\n\t/** A folder of the repository: its main folder, or one of its worktrees. */\n\trepository: string;\n\t/** The new branch the worktree checks out. */\n\tbranch: string;\n\t/** The revision the branch starts at, such as `main` or a commit. */\n\tfrom: string;\n\t/** Where the worktree goes. */\n\tpath?: string;\n}): Promise<{ path: string; branch: string }> {\n\tconst cwd = resolve(repository);\n\t// First: an older git could make the branch and then fail to list the worktrees.\n\tawait checkGit(cwd).catch((error: unknown) => {\n\t\tthrow failed(error instanceof Error ? error.message : String(error), 'Update git.');\n\t});\n\tconst valid = await git(['check-ref-format', '--branch', branch], cwd);\n\tif (valid.exitCode !== 0) {\n\t\tthrow failed(\n\t\t\t`\"${branch}\" is not a valid branch name`,\n\t\t\tfirstLine(valid.stderr) || 'git refused it.',\n\t\t);\n\t}\n\t// Resolved first, so a revision that starts with a dash can never be read as an option.\n\tconst commit = await git(\n\t\t['rev-parse', '--verify', '--quiet', '--end-of-options', `${from}^{commit}`],\n\t\tcwd,\n\t);\n\tif (commit.exitCode !== 0) {\n\t\tthrow failed(\n\t\t\t`\"${from}\" names no commit`,\n\t\t\tfirstLine(commit.stderr) || 'git found no such revision.',\n\t\t);\n\t}\n\n\tconst sha = commit.stdout.trim();\n\tconst ref = `refs/heads/${branch}`;\n\tif ((await git(['show-ref', '--verify', '--quiet', ref], cwd)).exitCode === 0) {\n\t\tthrow failed(`the branch \"${branch}\" already exists`, 'Name a new branch.');\n\t}\n\n\tlet target: string;\n\tif (path === undefined) {\n\t\tconst [main] = await listWorktrees(cwd).catch((error: unknown) => {\n\t\t\t// git's own words: no repository is one cause among others.\n\t\t\tthrow failed(error instanceof Error ? error.message : String(error), `In ${cwd}.`);\n\t\t});\n\t\tif (!main) throw failed(`${cwd} is in no git repository`, 'git listed no worktree.');\n\t\ttarget = join(\n\t\t\tdirname(main.path),\n\t\t\t`${basename(main.path)}-worktrees`,\n\t\t\tbranch.replaceAll('/', '-'),\n\t\t);\n\t} else {\n\t\ttarget = resolve(path);\n\t}\n\t// git takes an empty folder, but would create the branch before refusing a full one.\n\tconst held = await readdir(target).catch((error: unknown) =>\n\t\t(error as NodeJS.ErrnoException).code === 'ENOENT' ? [] : undefined,\n\t);\n\tif (held === undefined || held.length > 0) {\n\t\tthrow failed(`${target} already exists`, 'Give the worktree a folder that does not.');\n\t}\n\t// The first folder this call made, if any, which it removes again should git fail.\n\tconst made = path === undefined ? await mkdir(dirname(target), { recursive: true }) : undefined;\n\tconst removeMade = async () => {\n\t\tif (made !== undefined) await rmdir(made).catch(() => undefined);\n\t};\n\n\t// Made apart and first: git refuses a branch that exists, so the one made here is this call's.\n\tconst created = await git(['branch', '--no-track', branch, sha], cwd);\n\tif (created.exitCode !== 0) {\n\t\tawait removeMade();\n\t\tthrow failed(`the branch \"${branch}\" could not be made`, firstLine(created.stderr));\n\t}\n\tconst added = await git(['worktree', 'add', '--', target, branch], cwd);\n\tif (added.exitCode !== 0) {\n\t\tawait removeOwnBranch(cwd, branch, sha);\n\t\tawait removeMade();\n\t\tthrow failed('git refused it', firstLine(added.stderr));\n\t}\n\treturn { path: await realpath(target), branch };\n}\n"]}

package/dist/tools/infrastructure/writeSession.d.ts

@@ -1,3 +1,4 @@
+import type { Session } from '#src/shared/domain/session';
 import { type RecoveryStore, type RunJournal, type RunStatus } from '#src/recovery/domain/recoveryStore';
 /**
  * Everything one top-level run writes, across all its roles and rounds. Its journal starts on
@@ -10,17 +11,20 @@ export declare class WriteSession {
     private readonly maxChanges;
     private readonly onStart;
     private readonly onDiscard;
+    private readonly session;
     private journal;
     private changes;
     private stopped;
     private writing;
-    constructor({ store, maxChanges, onStart, onDiscard, }: {
+    constructor({ store, maxChanges, onStart, onDiscard, session, }: {
         store: RecoveryStore;
         maxChanges?: number;
         /** Told the run's id once its journal has started, before its first change is recorded. */
         onStart?: (runId: string) => void;
         /** Told when the run ended having changed nothing, so the history no longer has it. */
         onDiscard?: () => void;
+        /** The session the run belongs to, recorded with it. */
+        session?: Session;
     });
     /** The journal for one more change, counted against the run's limit. */
     journalForChange(): Promise<RunJournal>;

package/dist/tools/infrastructure/writeSession.js

@@ -13,16 +13,18 @@ export class WriteSession {
     maxChanges;
     onStart;
     onDiscard;
+    session;
     journal;
     changes = 0;
     stopped;
     // The end of the last write waiting or running, which the next one starts after.
     writing = Promise.resolve();
-    constructor({ store, maxChanges = defaultMaxChanges, onStart, onDiscard, }) {
+    constructor({ store, maxChanges = defaultMaxChanges, onStart, onDiscard, session, }) {
         this.store = store;
         this.maxChanges = maxChanges;
         this.onStart = onStart;
         this.onDiscard = onDiscard;
+        this.session = session;
     }
     /** The journal for one more change, counted against the run's limit. */
     async journalForChange() {
@@ -31,7 +33,9 @@ export class WriteSession {
         if (this.changes >= this.maxChanges) {
             throw new EditRefusedError(`This run has made ${String(this.maxChanges)} changes, the most one run may make`);
         }
-        this.journal ??= this.store.startRun().then(started => {
+        this.journal ??= this.store
+            .startRun(this.session ? { session: this.session } : {})
+            .then(started => {
             this.onStart?.(started.runId);
             return started;
         });
@@ -43,7 +47,7 @@ export class WriteSession {
             // A failed start is not kept, so the next change tries again.
             this.journal = undefined;
             if (error instanceof WorkspaceBusyError) {
-                throw new EditRefusedError('Another run, or a move through its history, holds this workspace, so nothing was changed', {
+                throw new EditRefusedError('Another run, a move through its history, or the removal of its worktree holds this workspace, so nothing was changed. The harness lets one run at a time write to a workspace; tell the user, who can wait for it to end or give this chat a worktree of its own.', {
                     cause: error,
                 });
             }