@anhlp/alp-runtime 0.0.0-beta.1

package/dist/workspace.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Phase C isolation (plans/reference/ALPD.md §16): a writing assignment may run in its
+ * own git worktree, so writers do not share a checkout. Its work is committed to a
+ * branch when it ends, and the requester merges the change into its checkout or
+ * discards it. Branches outlive their worktrees, so work is never deleted silently.
+ */
+export type Worktree = {
+    /** The requester's checkout, which receives the change on merge. */
+    checkout: string;
+    /** The worktree's top level, and the assignment's working directory inside it. */
+    path: string;
+    workdir: string;
+    branch: string;
+    /** The requester's state when the assignment started: HEAD plus uncommitted tracked changes. */
+    base: string;
+    /** checkoutFingerprint of the requester's checkout then, to tell whether it changed since. */
+    fingerprint?: string;
+};
+export type WorktreeChange = {
+    commit: string;
+    files: string[];
+    stat: string;
+};
+/** The environment ALP runs git in: the caller's, without git's own context, and never prompting. */
+export declare function gitEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The top level of the git checkout containing `directory`, or undefined outside git. */
+export declare function checkoutOf(directory: string): Promise<string | undefined>;
+/** The key that writers of one checkout share: its top level, or the directory itself outside git. */
+export declare function checkoutKey(directory: string): Promise<string>;
+/** Whether the checkout containing `directory` has a local branch of that name. */
+export declare function branchExists(directory: string, branch: string): Promise<boolean>;
+/** Creates a worktree for `id` from the current state of the checkout containing `workdir`. */
+/**
+ * Creates a worktree for `id` from the current state of the checkout containing `workdir`,
+ * or, with `from`, from an earlier assignment's committed change, keeping that assignment's
+ * base so a merge applies both changes together.
+ */
+export declare function createWorktree(workdir: string, root: string, id: string, from?: Pick<Worktree, 'base' | 'fingerprint'> & {
+    commit: string;
+}): Promise<Worktree>;
+/**
+ * Checks out an assignment's existing branch again at its worktree's place, after
+ * reclaimWorktrees committed and removed it, so the assignment continues there.
+ */
+export declare function reattachWorktree(worktree: Worktree): Promise<Worktree>;
+/** A digest of a checkout's state: HEAD, its uncommitted changes, and the names of untracked files. */
+export declare function checkoutFingerprint(checkout: string): Promise<string | undefined>;
+/**
+ * Links the project's node_modules into the same place in a worktree that has none,
+ * so its build and tests run; returns what undoes it. Commits never see the link,
+ * because ALP removes it before the worktree is committed again.
+ */
+export declare function linkModules(projectDir: string, worktreeDir: string): Promise<() => Promise<void>>;
+/** Commits whatever the assignment left in its worktree and describes the change from its base. */
+export declare function commitWorktree(worktree: Worktree, message: string): Promise<WorktreeChange>;
+/**
+ * Applies the change to the requester's working tree without committing or touching
+ * its index. A patch that applies cleanly is applied as is; otherwise each file is
+ * merged three ways against the requester's current file, leaving conflict markers.
+ * Where a file was deleted on one side or is binary, the requester's version is kept
+ * and reported as a conflict.
+ */
+export declare function mergeWorktree(worktree: Worktree, change: WorktreeChange): Promise<{
+    status: "empty";
+    files: never[];
+    conflicts?: undefined;
+} | {
+    status: "applied";
+    files: string[];
+    conflicts?: undefined;
+} | {
+    status: "conflicts";
+    files: string[];
+    conflicts: string[];
+}>;
+/** Removes the worktree directory; the branch stays unless `deleteBranch`. */
+export declare function removeWorktree(worktree: Worktree, { deleteBranch }?: {
+    deleteBranch?: boolean | undefined;
+}): Promise<void>;
+/**
+ * After a crash: commits work left in worktrees under `root` to their branches and
+ * removes the directories. Returns the branches that were kept.
+ */
+export declare function reclaimWorktrees(root: string): Promise<string[]>;
+/**
+ * A disposable copy of a checkout for an assignment that may build and test but
+ * must not touch the requester's tree (ALPD §26): a detached worktree at the
+ * requester's HEAD with its uncommitted changes applied as uncommitted changes, so
+ * `git diff` and `git status` there show what they show the requester, plus its
+ * untracked files.
+ * A top-level node_modules is linked, not copied. Nothing in it is ever merged.
+ */
+export type Copy = {
+    checkout: string;
+    path: string;
+    workdir: string;
+};
+export declare function createCopy(workdir: string, root: string, id: string): Promise<Copy>;
+export declare function removeCopy(copy: Copy): Promise<void>;
+/** After a crash: removes copies left under `root`; they hold nothing to keep. */
+export declare function reclaimCopies(root: string): Promise<number>;

package/dist/workspace.js

@@ -0,0 +1,259 @@
+// packages/runtime/src/workspace.ts
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFile, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+var IDENTITY = ["-c", "user.name=ALP", "-c", "user.email=alp@localhost", "-c", "commit.gpgsign=false"];
+var GIT_CONTEXT = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_COMMON_DIR",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_PREFIX",
+  "GIT_NAMESPACE",
+  "GIT_IMPLICIT_WORK_TREE",
+  "GIT_GRAFT_FILE",
+  "GIT_REPLACE_REF_BASE",
+  "GIT_NO_REPLACE_OBJECTS",
+  "GIT_SHALLOW_FILE",
+  "GIT_CONFIG",
+  "GIT_CONFIG_PARAMETERS",
+  "GIT_CONFIG_COUNT"
+];
+function gitEnvironment(env = process.env) {
+  const clean = { ...env, GIT_TERMINAL_PROMPT: "0" };
+  for (const key of Object.keys(clean)) {
+    if (GIT_CONTEXT.includes(key) || /^GIT_CONFIG_(KEY|VALUE)_\d+$/.test(key)) delete clean[key];
+  }
+  return clean;
+}
+function git(cwd, args, input) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, { cwd, stdio: [input === void 0 ? "ignore" : "pipe", "pipe", "pipe"], windowsHide: true, env: gitEnvironment() });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.once("error", reject);
+    child.once("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    if (child.stdin) {
+      child.stdin.on("error", () => {
+      });
+      child.stdin.end(input);
+    }
+  });
+}
+async function checked(cwd, args, input) {
+  const result = await git(cwd, args, input);
+  if (result.code !== 0) throw new Error(`git ${args[0]} failed: ${(result.stderr || result.stdout).trim()}`);
+  return result.stdout.trim();
+}
+function blob(cwd, revision, file) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", ["cat-file", "blob", `${revision}:${file}`], { cwd, stdio: ["ignore", "pipe", "ignore"], windowsHide: true, env: gitEnvironment() });
+    const chunks = [];
+    child.stdout.on("data", (chunk) => chunks.push(chunk));
+    child.once("error", reject);
+    child.once("close", (code) => resolve(code === 0 ? Buffer.concat(chunks) : void 0));
+  });
+}
+var binary = (content) => content.subarray(0, 8e3).includes(0);
+var same = (a, b) => a === b || !!a && !!b && a.equals(b);
+async function mergeText(ours, base, theirs) {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "alp-merge-"));
+  try {
+    const [o, b, t] = ["ours", "base", "theirs"].map((name) => path.join(directory, name));
+    await Promise.all([writeFile(o, ours), writeFile(b, base), writeFile(t, theirs)]);
+    const result = await git(directory, ["merge-file", "-p", "-L", "yours", "-L", "base", "-L", "assignment", o, b, t]);
+    if (result.code < 0 || result.code > 127) throw new Error(`git merge-file failed: ${result.stderr.trim()}`);
+    return { content: result.stdout, conflict: result.code > 0 };
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+async function checkoutOf(directory) {
+  const result = await git(directory, ["rev-parse", "--show-toplevel"]).catch(() => void 0);
+  return result?.code === 0 ? realpath(result.stdout.trim()) : void 0;
+}
+async function checkoutKey(directory) {
+  return await checkoutOf(directory) ?? realpath(directory).catch(() => path.resolve(directory));
+}
+async function branchExists(directory, branch) {
+  const result = await git(directory, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]).catch(() => void 0);
+  return result?.code === 0;
+}
+async function createWorktree(workdir, root, id, from) {
+  const checkout = await checkoutOf(workdir);
+  if (!checkout) throw new Error("Worktree isolation needs a git repository");
+  const head = await git(checkout, ["rev-parse", "--verify", "HEAD"]);
+  if (head.code !== 0) throw new Error("Worktree isolation needs at least one commit");
+  const fingerprint = from ? from.fingerprint : await checkoutFingerprint(checkout);
+  const base = from ? from.base : await checked(checkout, ["stash", "create"]) || head.stdout.trim();
+  const target = path.join(root, id);
+  const branch = `alp/${id}`;
+  await mkdir(root, { recursive: true, mode: 448 });
+  await checked(checkout, ["worktree", "add", "--quiet", "-b", branch, target, from ? from.commit : base]);
+  const relative = path.relative(checkout, await realpath(workdir));
+  return { checkout, path: target, workdir: path.join(target, relative), branch, base, ...fingerprint ? { fingerprint } : {} };
+}
+async function reattachWorktree(worktree) {
+  if (!await branchExists(worktree.checkout, worktree.branch)) throw new Error(`Branch ${worktree.branch} of the worktree no longer exists`);
+  if (await stat(worktree.path).catch(() => void 0)) return worktree;
+  await mkdir(path.dirname(worktree.path), { recursive: true, mode: 448 });
+  await git(worktree.checkout, ["worktree", "prune"]);
+  await checked(worktree.checkout, ["worktree", "add", "--quiet", worktree.path, worktree.branch]);
+  return worktree;
+}
+async function checkoutFingerprint(checkout) {
+  const head = await git(checkout, ["rev-parse", "--verify", "HEAD"]);
+  if (head.code !== 0) return void 0;
+  const diff = await git(checkout, ["diff", "--binary", "HEAD"]);
+  const untracked = await git(checkout, ["ls-files", "--others", "--exclude-standard", "-z"]);
+  return createHash("sha256").update(head.stdout).update("\0").update(diff.stdout).update("\0").update(untracked.stdout).digest("hex");
+}
+async function linkModules(projectDir, worktreeDir) {
+  const source = path.join(projectDir, "node_modules");
+  const target = path.join(worktreeDir, "node_modules");
+  if (!(await stat(source).catch(() => void 0))?.isDirectory() || await lstat(target).catch(() => void 0)) return async () => {
+  };
+  await symlink(source, target, "dir");
+  return async () => {
+    await unlink(target).catch(() => {
+    });
+  };
+}
+async function commitWorktree(worktree, message) {
+  await checked(worktree.path, ["add", "-A"]);
+  const staged = await git(worktree.path, ["diff", "--cached", "--quiet"]);
+  if (staged.code === 1) await checked(worktree.path, [...IDENTITY, "commit", "--quiet", "--no-verify", "-m", message]);
+  const commit = await checked(worktree.path, ["rev-parse", "HEAD"]);
+  const names = await checked(worktree.path, ["diff", "--name-only", worktree.base, commit]);
+  const stat2 = await checked(worktree.path, ["diff", "--shortstat", worktree.base, commit]);
+  return { commit, files: names ? names.split("\n") : [], stat: stat2 };
+}
+async function mergeWorktree(worktree, change) {
+  if (!change.files.length) return { status: "empty", files: [] };
+  const patch = await checked(worktree.checkout, ["diff", "--binary", worktree.base, change.commit]);
+  if ((await git(worktree.checkout, ["apply", "--whitespace=nowarn"], `${patch}
+`)).code === 0) return { status: "applied", files: change.files };
+  const conflicts = [];
+  for (const file of change.files) {
+    const target = path.join(worktree.checkout, file);
+    const ours = await readFile(target).catch(() => void 0);
+    const base = await blob(worktree.checkout, worktree.base, file);
+    const theirs = await blob(worktree.checkout, change.commit, file);
+    if (same(ours, theirs)) continue;
+    if (same(ours, base)) {
+      if (theirs) {
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, theirs);
+      } else {
+        await rm(target, { force: true });
+      }
+      continue;
+    }
+    if (!ours || !theirs || binary(ours) || binary(theirs) || base && binary(base)) {
+      conflicts.push(file);
+      continue;
+    }
+    const merged = await mergeText(ours, base ?? Buffer.alloc(0), theirs);
+    await writeFile(target, merged.content);
+    if (merged.conflict) conflicts.push(file);
+  }
+  return conflicts.length ? { status: "conflicts", files: change.files, conflicts } : { status: "applied", files: change.files };
+}
+async function removeWorktree(worktree, { deleteBranch = false } = {}) {
+  await git(worktree.checkout, ["worktree", "remove", "--force", worktree.path]);
+  await rm(worktree.path, { recursive: true, force: true });
+  await git(worktree.checkout, ["worktree", "prune"]);
+  if (deleteBranch) await git(worktree.checkout, ["branch", "-D", worktree.branch]);
+}
+async function reclaimWorktrees(root) {
+  const kept = [];
+  const entries = await readdir(root).catch(() => []);
+  for (const name of entries) {
+    const target = path.join(root, name);
+    if (!(await stat(target).catch(() => void 0))?.isDirectory()) continue;
+    const common = await git(target, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).catch(() => void 0);
+    if (common?.code !== 0) {
+      await rm(target, { recursive: true, force: true });
+      continue;
+    }
+    const checkout = path.dirname(common.stdout.trim());
+    const branch = (await git(target, ["rev-parse", "--abbrev-ref", "HEAD"])).stdout.trim();
+    await git(target, ["add", "-A"]);
+    if ((await git(target, ["diff", "--cached", "--quiet"])).code === 1) {
+      await git(target, [...IDENTITY, "commit", "--quiet", "--no-verify", "-m", "alp: work left by an interrupted assignment"]);
+    }
+    await removeWorktree({ checkout, path: target, workdir: target, branch, base: "" });
+    kept.push(branch);
+  }
+  return kept;
+}
+async function createCopy(workdir, root, id) {
+  const checkout = await checkoutOf(workdir);
+  if (!checkout) throw new Error("A review copy needs a git repository");
+  const head = await git(checkout, ["rev-parse", "--verify", "HEAD"]);
+  if (head.code !== 0) throw new Error("A review copy needs at least one commit");
+  const target = path.join(root, id);
+  await mkdir(root, { recursive: true, mode: 448 });
+  await checked(checkout, ["worktree", "add", "--quiet", "--detach", target, head.stdout.trim()]);
+  try {
+    const patch = (await git(checkout, ["diff", "--binary", "HEAD"])).stdout;
+    if (patch.trim()) await checked(target, ["apply", "--whitespace=nowarn", "--binary"], patch);
+    const untracked = (await checked(checkout, ["ls-files", "--others", "--exclude-standard", "-z"])).split("\0").filter(Boolean);
+    for (const file of untracked) {
+      const from = path.join(checkout, file);
+      if (!(await lstat(from).catch(() => void 0))?.isFile()) continue;
+      await mkdir(path.dirname(path.join(target, file)), { recursive: true });
+      await copyFile(from, path.join(target, file));
+    }
+    const modules = path.join(checkout, "node_modules");
+    if ((await stat(modules).catch(() => void 0))?.isDirectory()) await symlink(modules, path.join(target, "node_modules"), "dir");
+  } catch (error) {
+    await removeCopy({ checkout, path: target, workdir: target });
+    throw error;
+  }
+  const relative = path.relative(checkout, await realpath(workdir));
+  return { checkout, path: target, workdir: path.join(target, relative) };
+}
+async function removeCopy(copy) {
+  await git(copy.checkout, ["worktree", "remove", "--force", copy.path]).catch(() => void 0);
+  await rm(copy.path, { recursive: true, force: true });
+  await git(copy.checkout, ["worktree", "prune"]).catch(() => void 0);
+}
+async function reclaimCopies(root) {
+  let removed = 0;
+  for (const name of await readdir(root).catch(() => [])) {
+    const target = path.join(root, name);
+    const common = await git(target, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).catch(() => void 0);
+    if (common?.code === 0) await removeCopy({ checkout: path.dirname(common.stdout.trim()), path: target, workdir: target });
+    else await rm(target, { recursive: true, force: true });
+    removed++;
+  }
+  return removed;
+}
+export {
+  branchExists,
+  checkoutFingerprint,
+  checkoutKey,
+  checkoutOf,
+  commitWorktree,
+  createCopy,
+  createWorktree,
+  gitEnvironment,
+  linkModules,
+  mergeWorktree,
+  reattachWorktree,
+  reclaimCopies,
+  reclaimWorktrees,
+  removeCopy,
+  removeWorktree
+};

package/dist/worktree-domain.d.ts

@@ -0,0 +1,88 @@
+import { type Verification, type VerifyConfig } from '@anhlp/alp-core/verify';
+import { type WorktreeChange } from './workspace.js';
+import type { RuntimeOptions } from './contracts.js';
+import type { Session, Assignment } from './session-state.js';
+type WorktreeContext = {
+    options: RuntimeOptions;
+    leases: Map<string, {
+        assignment: string;
+        agent: string;
+    }>;
+    rootOf(sessionId: string): string;
+    lineage(sessionId: string): string[];
+    runLog(rootId: string, entry: Record<string, unknown>): void;
+    runHooks(sessionId: string, session: Session, event: string, details?: Record<string, unknown>, taskId?: string): Promise<string | undefined>;
+    touchTask(rootId: string, id: string): void;
+};
+/** Checkout mutation and verification retain one shared queue per checkout. */
+export declare function createWorktreeDomain({ options, leases, rootOf, lineage, runLog, runHooks, touchTask }: WorktreeContext): {
+    settleWorktree: (parentId: string, parent: Session, assignment: Assignment) => Promise<{
+        branch: string;
+        files: never[];
+        note: string;
+        error?: undefined;
+    } | {
+        note: string;
+        branch: string;
+        base: string;
+        commit: string;
+        files: string[];
+        stat: string;
+        error?: undefined;
+    } | {
+        next: string;
+        branch: string;
+        base: string;
+        commit: string;
+        files: string[];
+        stat: string;
+        note?: undefined;
+        error?: undefined;
+    } | {
+        branch: string;
+        error: string;
+        files?: undefined;
+        note?: undefined;
+    }>;
+    worktreeTool: (sessionId: string, session: Session, args: unknown, action: "merge" | "discard") => Promise<{
+        success: boolean;
+        contentItems: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    inCheckout: <T>(checkout: string, work: () => Promise<T>) => Promise<T>;
+    verifyIn: (project: string, directory: string, config: VerifyConfig) => Promise<Verification>;
+    verificationResult: (verification: Verification | {
+        passed: boolean;
+        commands: Array<Record<string, any>>;
+        cwd?: string;
+        skipped?: string;
+    }) => {
+        output?: any;
+        steps: {
+            idle?: any;
+            timedOut?: any;
+            step: any;
+            command: any;
+            exitCode: any;
+            ms: any;
+        }[];
+        skipped?: string | undefined;
+        passed: boolean;
+    };
+    noteVerification: (rootId: string, project: string, taskId: string | undefined, assignmentId: string | undefined, where: "worktree" | "checkout", verification: Verification) => void;
+    continuedBrief: (from: string, continued: {
+        agent: string;
+        change: WorktreeChange;
+        verification?: Verification;
+    }) => string;
+    verifyTool: (sessionId: string, session: Session, args: unknown) => Promise<{
+        success: boolean;
+        contentItems: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+};
+export {};

package/dist/worktree-domain.js

@@ -0,0 +1,196 @@
+// packages/runtime/src/worktree-domain.ts
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { describeVerification, runVerify, verifyConfig } from "@anhlp/alp-core/verify";
+import { recordVerification, loadTasks } from "@anhlp/alp-core/tasks";
+import { checkoutFingerprint, checkoutKey, commitWorktree, linkModules, mergeWorktree, removeWorktree } from "./workspace.js";
+import { writes } from "./catalog.js";
+import { nativeEnvironment } from "./providers.js";
+import { mainOf } from "./tools.js";
+import { errorData, plainObject, toolResult } from "./tool-results.js";
+function createWorktreeDomain({ options, leases, rootOf, lineage, runLog, runHooks, touchTask }) {
+  const merging = /* @__PURE__ */ new Map();
+  async function settleWorktree(parentId, parent, assignment) {
+    const worktree = assignment.worktree;
+    try {
+      const change = await commitWorktree(worktree, `alp: ${assignment.agent} assignment ${assignment.id}`);
+      if (!change.files.length) {
+        await removeWorktree(worktree, { deleteBranch: true });
+        return { branch: worktree.branch, files: [], note: "No changes; the worktree was removed" };
+      }
+      const described = { branch: worktree.branch, base: worktree.base, commit: change.commit, files: change.files, stat: change.stat };
+      if (parent.closed) {
+        await removeWorktree(worktree);
+        runLog(rootOf(parentId), { event: "worktree.kept", assignmentId: assignment.id, branch: worktree.branch });
+        return { ...described, note: "The requester closed; the change stays on the branch" };
+      }
+      parent.worktrees.set(assignment.id, { agent: assignment.agent, worktree, change, ...assignment.taskId ? { taskId: assignment.taskId } : {} });
+      return { ...described, next: "Apply it with alp_merge, or drop it with alp_discard" };
+    } catch (error) {
+      await removeWorktree(worktree).catch(() => {
+      });
+      return { branch: worktree.branch, error: errorData(error).message };
+    }
+  }
+  async function worktreeTool(sessionId, session, args, action) {
+    if (!plainObject(args, ["assignmentId", "skipVerify"]) || typeof args.assignmentId !== "string" || args.skipVerify !== void 0 && (action !== "merge" || typeof args.skipVerify !== "string" || !args.skipVerify.trim())) {
+      return toolResult(false, { error: action === "merge" ? "assignmentId is required; skipVerify, when given, says why to merge without verification" : "assignmentId is required" });
+    }
+    const pending = session.worktrees.get(args.assignmentId);
+    if (!pending) {
+      return toolResult(false, { error: session.assignments.has(args.assignmentId) ? "The assignment is still running; wait for its result" : "No unmerged worktree change with that assignment id" });
+    }
+    const { worktree, change } = pending;
+    if (action === "discard") {
+      session.worktrees.delete(args.assignmentId);
+      await removeWorktree(worktree, { deleteBranch: true });
+      runLog(rootOf(sessionId), { event: "worktree.discarded", assignmentId: args.assignmentId, branch: worktree.branch });
+      return toolResult(true, { discarded: args.assignmentId, branch: worktree.branch });
+    }
+    if (!writes(session.mapping.mode)) return toolResult(false, { error: "Merging needs workspace-write or full-access" });
+    if ([...session.assignments.values()].some((assignment) => assignment.mode !== "read-only" && assignment.isolation === "shared")) {
+      return toolResult(false, { error: "A writer assignment is working in this checkout; merge after its result" });
+    }
+    session.worktrees.delete(args.assignmentId);
+    const checkout = await checkoutKey(session.mapping.workdir);
+    const holder = leases.get(checkout);
+    if (holder && !lineage(sessionId).includes(holder.assignment)) {
+      session.worktrees.set(args.assignmentId, pending);
+      return toolResult(false, { error: `${holder.agent} in another session is writing this checkout; merge after it finishes` });
+    }
+    const project = session.mapping.agent.projectRoot;
+    const rootId = rootOf(sessionId);
+    let config;
+    try {
+      config = await verifyConfig(project);
+    } catch (error) {
+      session.worktrees.set(args.assignmentId, pending);
+      return toolResult(false, { error: errorData(error).message });
+    }
+    let verified;
+    if (config && args.skipVerify === void 0) {
+      const verification = verified = await verifyIn(project, worktreeDirectory(worktree, project), config);
+      noteVerification(rootId, project, pending.taskId, args.assignmentId, "worktree", verification);
+      if (!verification.passed) {
+        session.worktrees.set(args.assignmentId, { ...pending, verification });
+        return toolResult(false, {
+          assignmentId: args.assignmentId,
+          error: `${describeVerification(verification)} in the assignment's worktree; nothing was applied`,
+          verification: verificationResult(verification),
+          branch: worktree.branch,
+          next: verification.skipped ? "The check could not run, which says nothing about the change; call alp_merge again, or alp_merge it with skipVerify saying why" : `Delegate again with continueFrom "${args.assignmentId}"${pending.taskId ? ` and taskId ${pending.taskId}` : ""} to fix it in a worktree that starts from this change; or alp_discard it; or alp_merge it with skipVerify saying why`
+        });
+      }
+    } else if (config && pending.taskId) {
+      await recordVerification(project, pending.taskId, { passed: false, skipped: args.skipVerify }, session.mapping.agent.name).catch(() => {
+      });
+      runLog(rootId, { event: "verify", assignmentId: args.assignmentId, where: "worktree", skipped: args.skipVerify });
+    }
+    const refused = await runHooks(sessionId, session, "merge", { assignment: args.assignmentId, branch: worktree.branch }, pending.taskId);
+    if (refused) {
+      session.worktrees.set(args.assignmentId, pending);
+      return toolResult(false, { assignmentId: args.assignmentId, error: `A merge hook refused it; nothing was applied:
+${refused}`, branch: worktree.branch, next: `Fix what it reports in a new assignment with continueFrom "${args.assignmentId}", or alp_discard it` });
+    }
+    let merged;
+    let moved = false;
+    try {
+      ({ merged, moved } = await inCheckout(checkout, async () => {
+        const before = await checkoutFingerprint(worktree.checkout).catch(() => void 0);
+        return { merged: await mergeWorktree(worktree, change), moved: !worktree.fingerprint || before !== worktree.fingerprint };
+      }));
+    } catch (error) {
+      session.worktrees.set(args.assignmentId, pending);
+      return toolResult(false, { error: errorData(error).message, branch: worktree.branch, next: "Merge the branch yourself, or alp_discard it" });
+    }
+    await removeWorktree(worktree, { deleteBranch: merged.status !== "conflicts" });
+    runLog(rootId, { event: "worktree.merged", assignmentId: args.assignmentId, branch: worktree.branch, ...merged });
+    let checked;
+    if (config && args.skipVerify === void 0 && merged.status === "applied" && moved) {
+      checked = await inCheckout(checkout, () => verifyIn(project, session.mapping.workdir, config));
+      noteVerification(rootId, project, pending.taskId, args.assignmentId, "checkout", checked);
+    }
+    return toolResult(true, {
+      assignmentId: args.assignmentId,
+      ...merged,
+      ...merged.status === "conflicts" ? { branch: worktree.branch } : {},
+      ...verified ? { verification: verificationResult(checked ?? verified), ...checked ? { verifiedIn: "your checkout, which changed since the assignment started" } : {} } : {},
+      ...args.skipVerify !== void 0 && config ? { verification: { skipped: args.skipVerify } } : {},
+      next: merged.status === "conflicts" ? `Resolve the conflict markers in the listed files, then verify${config ? " with alp_verify" : ""}` : checked && !checked.passed ? `The change passed in its worktree but ${describeVerification(checked)} in your checkout, which changed meanwhile; fix it, then run alp_verify` : "Review the applied change; it is not committed"
+    });
+  }
+  function inCheckout(checkout, work) {
+    const previous = merging.get(checkout) ?? Promise.resolve();
+    const attempt = previous.catch(() => {
+    }).then(work);
+    merging.set(checkout, attempt);
+    void attempt.finally(() => {
+      if (merging.get(checkout) === attempt) merging.delete(checkout);
+    }).catch(() => {
+    });
+    return attempt;
+  }
+  function worktreeDirectory(worktree, project) {
+    let real = project;
+    try {
+      real = realpathSync(project);
+    } catch {
+    }
+    return path.join(worktree.path, path.relative(worktree.checkout, real));
+  }
+  async function verifyIn(project, directory, config) {
+    const same = path.resolve(directory) === path.resolve(project);
+    const unlinkModules = same ? async () => {
+    } : await linkModules(project, directory).catch(() => async () => {
+    });
+    try {
+      return await runVerify(directory, config, { env: nativeEnvironment(options) });
+    } finally {
+      await unlinkModules();
+    }
+  }
+  function verificationResult(verification) {
+    const failed = verification.commands.find((command) => command.exitCode !== 0);
+    return {
+      passed: verification.passed,
+      ...verification.skipped ? { skipped: verification.skipped } : {},
+      steps: verification.commands.map(({ step, command, exitCode, ms, timedOut, idle }) => ({ step, command, exitCode, ms, ...timedOut ? { timedOut } : {}, ...idle ? { idle } : {} })),
+      ...failed?.output ? { output: failed.output } : {}
+    };
+  }
+  function noteVerification(rootId, project, taskId, assignmentId, where, verification) {
+    runLog(rootId, { event: "verify", ...assignmentId ? { assignmentId } : {}, ...taskId ? { taskId } : {}, where, passed: verification.passed, detail: describeVerification(verification) });
+    if (taskId) void recordVerification(project, taskId, { ...verification, where }, "alpd").then(() => touchTask(rootId, taskId), () => {
+    });
+  }
+  function continuedBrief(from, continued) {
+    const failed = continued.verification?.commands.find((command) => command.exitCode !== 0);
+    return `Your worktree starts from the change of ${continued.agent}'s assignment ${from}, committed on your branch (${continued.change.files.length} files: ${continued.change.files.slice(0, 20).join(", ")}). Build on it rather than starting over.` + (continued.verification && !continued.verification.passed ? ` The project's checks failed on it: ${describeVerification(continued.verification)}, running \`${failed?.command}\`. The end of its output:
+${failed?.output.slice(-1500) ?? ""}` : "");
+  }
+  async function verifyTool(sessionId, session, args) {
+    if (!plainObject(args, ["taskId"]) || args.taskId !== void 0 && typeof args.taskId !== "string") return toolResult(false, { error: "alp_verify takes only taskId" });
+    if (args.taskId !== void 0 && (session.parent || session.mapping.agent.name !== mainOf(session.mapping))) return toolResult(false, { error: "Only main records a verification on a task; call alp_verify without taskId" });
+    const project = session.mapping.agent.projectRoot;
+    let config;
+    try {
+      config = await verifyConfig(project);
+    } catch (error) {
+      return toolResult(false, { error: errorData(error).message });
+    }
+    if (!config) return toolResult(false, { error: "This project has no verify commands (verify in .alp/settings.json); run its checks yourself" });
+    if (args.taskId !== void 0) {
+      const task = (await loadTasks(project)).tasks.find((entry) => entry.id === args.taskId);
+      if (!task) return toolResult(false, { error: `No task ${args.taskId}` });
+      if (task.status === "closed") return toolResult(false, { error: `${args.taskId} is closed` });
+    }
+    const checkout = await checkoutKey(session.mapping.workdir);
+    const verification = await inCheckout(checkout, () => verifyIn(project, session.mapping.workdir, config));
+    noteVerification(rootOf(sessionId), project, args.taskId, void 0, "checkout", verification);
+    return toolResult(true, { ...verificationResult(verification), summary: describeVerification(verification), ...args.taskId ? { recordedOn: args.taskId } : {} });
+  }
+  return { settleWorktree, worktreeTool, inCheckout, verifyIn, verificationResult, noteVerification, continuedBrief, verifyTool };
+}
+export {
+  createWorktreeDomain
+};