@kylecheng3146/agent-ops 0.2.8 → 0.3.0

package/dist/runtime/src/hooks/completion-gate.js

@@ -1,20 +1,37 @@
-import { join } from "node:path";
+import { lstat, readdir } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
 import { checkTaskCompletionEvidence, findIncompleteSubtask } from "../task/completion.js";
 import { collectBaseChangePaths, collectChangeSurface } from "../verify/change-surface.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+import { readWorktreeRecord } from "../parallel/service.js";
 const FINGERPRINT = /^[a-f0-9]{64}$/u;
 const SESSION = /^[^\0\r\n]{1,256}$/u;
+function gateDirectory(root) {
+    return join(root, ".agent-ops", "tasks", "completion-gate");
+}
 function shellQuote(value) {
     return `'${value.replaceAll("'", "'\"'\"'")}'`;
 }
+async function isDirectory(path) {
+    try {
+        return (await lstat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function gateResult(action, status, code, remedy) {
     return { action, status, code, ...(remedy === undefined ? {} : { remedy }) };
 }
 function statePath(root, sessionId) {
-    return join(root, ".agent-ops", "tasks", "completion-gate", `${sha256(sessionId)}.json`);
+    return join(gateDirectory(root), `${sha256(sessionId)}.json`);
+}
+function validRoot(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 4096 &&
+        !value.includes("\0") && isAbsolute(value);
 }
 function parseState(source, sessionId) {
     if (source === null)
@@ -30,8 +47,9 @@ function parseState(source, sessionId) {
         throw new AgentOpsError("COMPLETION_GATE_STATE_INVALID", "Completion-gate state is invalid.");
     }
     const record = value;
-    if (Object.keys(record).sort().join(",") !==
-        "baselineFingerprint,permitFingerprint,schemaVersion,sessionId" ||
+    const keys = Object.keys(record).filter((key) => key !== "root").sort().join(",");
+    if (keys !== "baselineFingerprint,permitFingerprint,schemaVersion,sessionId" ||
+        ("root" in record && !validRoot(record.root)) ||
         record.schemaVersion !== 1 ||
         record.sessionId !== sessionId ||
         typeof record.baselineFingerprint !== "string" ||
@@ -55,6 +73,32 @@ export class FileCompletionGateStore {
         const path = statePath(this.#root, sessionId);
         return await withPrivateFileLock(path, this.#root, async () => parseState(await readPrivateFile(path, this.#root), sessionId));
     }
+    /** Every recorded session. An unreadable record is skipped, not repaired. */
+    async all() {
+        let names;
+        try {
+            names = await readdir(gateDirectory(this.#root));
+        }
+        catch {
+            return [];
+        }
+        const states = [];
+        for (const name of names.filter((entry) => /^[a-f0-9]{64}\.json$/u.test(entry))) {
+            try {
+                const source = await readPrivateFile(join(gateDirectory(this.#root), name), this.#root);
+                const record = source === null ? null : JSON.parse(source);
+                if (typeof record?.sessionId === "string") {
+                    const state = await this.read(record.sessionId);
+                    if (state !== null)
+                        states.push(state);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return states;
+    }
     async mutate(sessionId, action) {
         if (!SESSION.test(sessionId)) {
             throw new AgentOpsError("COMPLETION_GATE_SESSION_INVALID", "Completion gate requires a valid session identity.");
@@ -68,6 +112,11 @@ export class FileCompletionGateStore {
         });
     }
 }
+/** What the gate measures: the whole Git-visible change surface of `root`. */
+export async function currentGateFingerprint(root, gitRunner) {
+    const surface = await collectChangeSurface(gitRunner);
+    return await calculateSourceFingerprint(root, { mode: "worktree", changedFiles: surface.paths }, gitRunner);
+}
 export class CompletionGateService {
     #options;
     #store;
@@ -76,8 +125,63 @@ export class CompletionGateService {
         this.#store = options.stateStore ?? new FileCompletionGateStore(options.root);
     }
     async #fingerprint() {
-        const surface = await collectChangeSurface(this.#options.gitRunner);
-        return await calculateSourceFingerprint(this.#options.root, { mode: "worktree", changedFiles: surface.paths }, this.#options.gitRunner);
+        return await currentGateFingerprint(this.#options.root, this.#options.gitRunner);
+    }
+    /**
+     * Starts (or restarts) a session's record at a known baseline: the current
+     * source by default, or an explicit one a caller wants every Stop measured
+     * against.
+     */
+    async seed(sessionId, baselineFingerprint) {
+        const baseline = baselineFingerprint ?? await this.#fingerprint();
+        await this.#store.mutate(sessionId, () => ({
+            schemaVersion: 1,
+            sessionId,
+            baselineFingerprint: baseline,
+            permitFingerprint: null
+        }));
+    }
+    /** Points this checkout's record for a session at another worktree, or clears it. */
+    async redirect(sessionId, root) {
+        if (root === null && (await this.#store.read(sessionId))?.root === undefined) {
+            return;
+        }
+        const fingerprint = await this.#fingerprint();
+        await this.#store.mutate(sessionId, (current) => {
+            const { root: _previous, ...base } = current ?? {
+                schemaVersion: 1,
+                sessionId,
+                baselineFingerprint: fingerprint,
+                permitFingerprint: null
+            };
+            return root === null ? base : { ...base, root };
+        });
+    }
+    /**
+     * Moves every session whose baseline is `from` to `to`: a merge that moved
+     * HEAD under a session which changed nothing must not read as its change.
+     */
+    async rebase(from, to) {
+        let moved = 0;
+        for (const state of await this.#store.all()) {
+            if (state.baselineFingerprint !== from)
+                continue;
+            await this.#store.mutate(state.sessionId, (current) => current === null || current.baselineFingerprint !== from
+                ? current ?? state
+                : { ...current, baselineFingerprint: to });
+            moved += 1;
+        }
+        return moved;
+    }
+    async sessions() {
+        return await this.#store.all();
+    }
+    /**
+     * Whether the session's attached task would let it stop right now: complete,
+     * with current evidence and review. Null means it would.
+     */
+    async validate(sessionId) {
+        return await this.#validateTask(sessionId);
     }
     /**
      * The fingerprint the task's evidence should carry. Committed work leaves an
@@ -120,6 +224,12 @@ export class CompletionGateService {
             permitFingerprint: null
         });
         const changed = state.baselineFingerprint !== fingerprint;
+        if (!changed &&
+            this.#options.config.worktree?.mode === "auto" &&
+            state.root === undefined &&
+            await readWorktreeRecord(this.#options.root) === null) {
+            return gateResult("continue", "UNKNOWN", "COMPLETION_GATE_WORKTREE_MODE", `worktree.mode is auto. Session: ${sessionId}. Before your first edit run agent-ops worktree add <name> --session ${shellQuote(sessionId)} and work only inside the printed path.`);
+        }
         return gateResult("continue", changed ? "UNKNOWN" : "PASS", changed ? "COMPLETION_GATE_CHANGED" : "COMPLETION_GATE_READY", changed
             ? `Git-visible changes require an attached completed task, current PASS evidence, and a PASS review. Session: ${sessionId}. Create with --session ${sessionId}; one-time permit: agent-ops allow-stop --session ${sessionId}.`
             : undefined);
@@ -165,7 +275,19 @@ export class CompletionGateService {
         }
         return null;
     }
+    /** `agent-ops worktree remove --force`: discards work that exists nowhere else. */
+    #isForcedRemove(event) {
+        const commands = event.event === "command" ? [event] :
+            event.event === "command-batch" ? event.commands : [];
+        return commands.some(({ command, args }) => {
+            const words = [command, ...args];
+            return words.includes("worktree") && words.includes("remove") && words.includes("--force");
+        });
+    }
     async handle(event) {
+        if (this.#isForcedRemove(event)) {
+            return gateResult("block", "UNKNOWN", "WORKTREE_REMOVE_CONFIRMATION", "Allow this only if the user wants the worktree's uncommitted or unmerged work discarded.");
+        }
         if (this.#isPermitCommand(event)) {
             return gateResult("block", "UNKNOWN", "COMPLETION_GATE_PERMIT_CONFIRMATION", "Allow this command only to grant one Stop for the current source fingerprint.");
         }
@@ -192,7 +314,19 @@ export class CompletionGateService {
         if (state === null) {
             return gateResult("block", "UNKNOWN", "COMPLETION_GATE_NOT_INITIALIZED", "The session baseline is unavailable; continue once so PreInvocation can initialize it.");
         }
-        if (state.baselineFingerprint !== fingerprint && state.permitFingerprint !== fingerprint) {
+        const changed = state.baselineFingerprint !== fingerprint && state.permitFingerprint !== fingerprint;
+        if (state.root !== undefined && state.root !== this.#options.root) {
+            // This checkout only has to stay untouched; the work, its task and its
+            // evidence live in the worktree, and that gate decides.
+            if (changed) {
+                return gateResult("block", "FAIL", "COMPLETION_GATE_MAIN_CHANGED", `This session works in ${state.root}, but this checkout changed too. Move those edits into the worktree, or ask the user for a one-time permit.`);
+            }
+            if (!await isDirectory(state.root) || this.#options.forRoot === undefined) {
+                return gateResult("block", "UNKNOWN", "COMPLETION_GATE_WORKTREE_MISSING", `The worktree ${state.root} is unavailable. Run agent-ops worktree list, then resume or remove it.`);
+            }
+            return await (await this.#options.forRoot(state.root)).handle(event);
+        }
+        if (changed) {
             const failure = await this.#validateTask(sessionId);
             if (failure !== null)
                 return failure;

package/dist/runtime/src/hooks/dispatch.js

@@ -52,6 +52,11 @@ export async function dispatchHookEvent(event, options) {
     if (event.event === "unsupported") {
         return continueWith("UNKNOWN", "HOOK_EVENT_UNSUPPORTED");
     }
+    if (event.event === "file-write") {
+        return options.worktreeGuard === undefined
+            ? continueWith("PASS", "HOOK_NOOP")
+            : await options.worktreeGuard(event);
+    }
     if (event.event === "session-start" &&
         options.capabilities.includes("lifecycle-summary") &&
         options.advisory !== undefined) {

package/dist/runtime/src/install/doctor.js

@@ -495,7 +495,10 @@ export async function doctorInstallation(options) {
         await checkProbe("smoke-availability", options.probes?.smokeAvailability),
         await checkReviewTargets(config.config, options.probes?.reviewTarget, options.checkReviewTargetAuth === true, options.checkAuthTargets),
         await checkHostSandbox(options.probes?.hostRestriction),
-        checkVerificationCommands(config.config)
+        checkVerificationCommands(config.config),
+        ...(options.probes?.worktrees === undefined
+            ? []
+            : [await checkProbe("worktrees", options.probes.worktrees)])
     ];
     return {
         checks,

package/dist/runtime/src/install/harness.js

@@ -311,7 +311,7 @@ export function managedRules(descriptor, context) {
         lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
-        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "");
+        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops worktree add <name> --session <session-id>` from the main", "checkout before your first edit, and work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify, review and", "`task complete` with the printed `--base`; leave the worktree (Claude", "Code: ExitWorktree with action keep) and run `agent-ops worktree finish", "<name>` from the main checkout. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "");
     }
     if (context.capabilities.includes("lifecycle-summary")) {
         lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");

package/dist/runtime/src/install/plan.js

@@ -102,7 +102,10 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         },
         pathMappings: existing?.pathMappings ?? [],
         securityExceptions: existing?.securityExceptions ?? [],
-        ...(reviewRoles === undefined ? {} : { reviewRoles: [...reviewRoles] })
+        ...(reviewRoles === undefined ? {} : { reviewRoles: [...reviewRoles] }),
+        ...(existing?.worktree === undefined
+            ? {}
+            : { worktree: structuredClone(existing.worktree) })
     };
 }
 async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = [], completionGateEnabled = false) {

package/dist/runtime/src/parallel/finish.js

@@ -0,0 +1,263 @@
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
+import { currentGateFingerprint } from "../hooks/completion-gate.js";
+import { collectChangeSurface } from "../verify/change-surface.js";
+import { aggregateVerificationStatus, executeConfiguredCommand } from "../verify/command-executor.js";
+import { assertWorktreeName, readWorktreeRecord, removeCheckout, resolveCheckouts, worktreePath } from "./service.js";
+export const NOTES_REF = "agent-ops";
+const LOCK_NAME = "agent-ops-finish.lock";
+const LOCK_POLL_MS = 2_000;
+const LOCK_WAIT_MS = 30 * 60 * 1000;
+// A holder that has not finished in this long has died without its pid being
+// reused by something we can see; the lock is reclaimed.
+const LOCK_STALE_MS = 2 * 60 * 60 * 1000;
+const MAX_INTENTS = 20;
+/**
+ * The work and the moved target touch the same lines. The rebase was undone;
+ * this carries what the agent needs to redo it deliberately: the files, and
+ * what the tasks already merged into the target meant to achieve.
+ */
+export class WorktreeConflictError extends AgentOpsError {
+    files;
+    intents;
+    target;
+    constructor(record, target, head, files, intents) {
+        super("WORKTREE_REBASE_CONFLICT", [
+            `Rebasing ${record.branch} onto ${record.targetBranch} (${target}) conflicts in: ${files.join(", ")}.`,
+            "The rebase was aborted and the branch is unchanged.",
+            intents.length === 0
+                ? "No agent-ops notes describe the target-side commits."
+                : ["What the target-side work intended:", ...intents.map(({ commit, note }) => `--- ${commit}\n${note}`)].join("\n"),
+            `Resolve it in ${record.path}: git rebase ${target}, satisfy both intents, git rebase --continue;`,
+            "then create a new task whose criteria cover both intents, attach it to this session,",
+            `run verify, review and task complete with --base ${target}, and finish again.`,
+            `One attempt only: if that verification or review fails, git reset --hard ${head}`,
+            "and stop to report instead of retrying."
+        ].join("\n"));
+        this.files = files;
+        this.intents = intents;
+        this.target = target;
+    }
+}
+function finishError(code, message) {
+    return new AgentOpsError(code, message);
+}
+async function git(deps, cwd, args, code, message) {
+    const result = await deps.git(cwd, args);
+    if (result.exitCode !== 0) {
+        const detail = result.stderr.trim().split("\n")[0];
+        throw finishError(code, detail === undefined || detail === "" ? message : `${message} ${detail}`);
+    }
+    return result.stdout.trim();
+}
+function runner(deps, cwd) {
+    return {
+        run: async (args) => {
+            const result = await deps.git(cwd, args);
+            return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout, "utf8") };
+        }
+    };
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function staleLock(path) {
+    try {
+        const owner = JSON.parse(await readFile(join(path, "owner.json"), "utf8"));
+        if (typeof owner.pid !== "number" || typeof owner.at !== "number")
+            return true;
+        return !alive(owner.pid) || Date.now() - owner.at > LOCK_STALE_MS;
+    }
+    catch {
+        // A holder between mkdir and writing its owner file looks like this too;
+        // only an old ownerless lock is abandoned.
+        try {
+            return Date.now() - (await stat(path)).mtimeMs > 60_000;
+        }
+        catch {
+            return true;
+        }
+    }
+}
+/**
+ * One finish at a time per repository: each one moves the target, and every
+ * later one must rebase onto that. The lock lives in the Git common directory
+ * so every worktree of the repository sees the same one.
+ */
+export async function withFinishLock(deps, commonDir, action) {
+    const path = join(commonDir, LOCK_NAME);
+    const deadline = Date.now() + (deps.lockWaitMs ?? LOCK_WAIT_MS);
+    const sleep = deps.sleep ?? (async (ms) => await new Promise((resolve) => setTimeout(resolve, ms)));
+    for (;;) {
+        try {
+            await mkdir(path);
+            await writeFile(join(path, "owner.json"), JSON.stringify({ pid: process.pid, at: Date.now() }));
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (await staleLock(path)) {
+                await rm(path, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw finishError("WORKTREE_FINISH_BUSY", "Another worktree finish is still running; try again later.");
+            }
+            await sleep(LOCK_POLL_MS);
+        }
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await rm(path, { recursive: true, force: true });
+    }
+}
+/**
+ * The branch's own change, independent of where it is based: hunk positions
+ * and blob ids move with a rebase, the change itself does not.
+ */
+async function patchHash(deps, cwd, target) {
+    const diff = await git(deps, cwd, ["diff", "--no-color", "--no-ext-diff", "--no-textconv", `${target}...HEAD`], "WORKTREE_DIFF_FAILED", "Git could not diff the branch.");
+    return sha256(diff.split("\n")
+        .filter((line) => !line.startsWith("index "))
+        .map((line) => line.startsWith("@@") ? "@@" : line)
+        .join("\n"));
+}
+async function reverify(deps, root, config) {
+    const results = [];
+    for (const command of config.verification.commands) {
+        results.push(await executeConfiguredCommand(command, {
+            cwd: command.cwd === "." ? root : await resolveContainedPath(root, command.cwd),
+            trusted: true,
+            ...(deps.processRunner === undefined ? {} : { runner: deps.processRunner })
+        }));
+    }
+    return aggregateVerificationStatus(results) === "PASS"
+        ? []
+        : results.filter((result) => result.required && result.status !== "PASS").map(({ commandId }) => commandId);
+}
+async function targetIntents(deps, cwd, target) {
+    const commits = (await git(deps, cwd, ["log", "--format=%H", `HEAD..${target}`], "WORKTREE_LOG_FAILED", "Git could not list the target-side commits.")).split("\n").filter(Boolean);
+    const intents = [];
+    for (const commit of commits) {
+        const note = await deps.git(cwd, ["notes", `--ref=${NOTES_REF}`, "show", commit]);
+        if (note.exitCode === 0 && note.stdout.trim() !== "") {
+            intents.push({ commit, note: note.stdout.trim() });
+            if (intents.length >= MAX_INTENTS)
+                break;
+        }
+    }
+    return intents;
+}
+function noteText(record, task) {
+    return [
+        `agent-ops task ${task.task.id}: ${task.task.title}`,
+        `worktree: ${record.name} (${record.branch})`,
+        "criteria:",
+        ...task.task.criteria.map(({ id, description }) => `- ${id}: ${description}`)
+    ].join("\n");
+}
+/**
+ * Brings a worktree's reviewed work into the branch the main checkout is on,
+ * by fast-forward only, then retires the worktree. Run from the main checkout.
+ */
+export async function finishWorktree(deps, options) {
+    const name = assertWorktreeName(options.name);
+    const { mainRoot, currentRoot, commonDir } = await resolveCheckouts(deps, options.cwd);
+    if (currentRoot !== mainRoot) {
+        throw finishError("WORKTREE_NESTED", `Run worktree finish from the main checkout (${mainRoot}); Claude Code: ExitWorktree with action keep first.`);
+    }
+    const record = await readWorktreeRecord(worktreePath(mainRoot, name));
+    if (record === null) {
+        throw finishError("WORKTREE_NOT_FOUND", `No agent-ops worktree named ${name}; see agent-ops worktree list.`);
+    }
+    return await withFinishLock(deps, commonDir, async () => {
+        const mainRunner = runner(deps, mainRoot);
+        const worktreeRunner = runner(deps, record.path);
+        if ((await collectChangeSurface(mainRunner)).paths.length > 0) {
+            throw finishError("WORKTREE_MAIN_DIRTY", "The main checkout has uncommitted changes; a fast-forward would mix them in.");
+        }
+        const onBranch = (await deps.git(mainRoot, ["symbolic-ref", "--short", "-q", "HEAD"])).stdout.trim();
+        if (onBranch !== record.targetBranch) {
+            throw finishError("WORKTREE_TARGET_MOVED", `The main checkout is on ${onBranch || "a detached HEAD"}; switch it back to ${record.targetBranch} to finish.`);
+        }
+        if ((await collectChangeSurface(worktreeRunner)).paths.length > 0) {
+            throw finishError("WORKTREE_DIRTY", `Commit or discard the uncommitted changes in ${record.path} first.`);
+        }
+        const target = await git(deps, mainRoot, ["rev-parse", "--verify", `${record.targetBranch}^{commit}`], "WORKTREE_TARGET_MISSING", `${record.targetBranch} does not resolve to a commit.`);
+        const ahead = Number(await git(deps, record.path, ["rev-list", "--count", `${target}..HEAD`], "WORKTREE_LOG_FAILED", "Git could not compare the branch with its target."));
+        if (ahead === 0) {
+            throw finishError("WORKTREE_NOTHING_TO_MERGE", `${record.branch} has no commits beyond ${record.targetBranch}; remove the worktree instead.`);
+        }
+        const worktreeConfig = await deps.loadConfig(record.path);
+        const worktreeGate = await deps.gate(record.path, worktreeConfig);
+        const problem = await worktreeGate.validate(record.sessionId);
+        if (problem !== null) {
+            throw finishError("WORKTREE_TASK_INCOMPLETE", `The worktree's task is not ready to merge (${problem.code}). ${problem.remedy ?? ""}`.trim());
+        }
+        const task = await deps.tasks(record.path).status({ sessionId: record.sessionId });
+        const head = await git(deps, record.path, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
+        const fastForward = (await deps.git(record.path, ["merge-base", "--is-ancestor", target, "HEAD"])).exitCode === 0;
+        if (!fastForward) {
+            const before = await patchHash(deps, record.path, target);
+            const rebase = await deps.git(record.path, ["rebase", "--no-autostash", target]);
+            if (rebase.exitCode !== 0) {
+                const files = (await deps.git(record.path, ["diff", "--name-only", "--diff-filter=U"])).stdout
+                    .split("\n").map((line) => line.trim()).filter(Boolean);
+                await deps.git(record.path, ["rebase", "--abort"]);
+                await deps.git(record.path, ["reset", "--hard", head]);
+                throw new WorktreeConflictError(record, target, head, files, await targetIntents(deps, record.path, target));
+            }
+            const reset = async () => { await deps.git(record.path, ["reset", "--hard", head]); };
+            if (await patchHash(deps, record.path, target) !== before) {
+                await reset();
+                throw finishError("WORKTREE_REBASE_CHANGED", `Rebasing onto ${target} changed the branch's own diff, so the review no longer covers it. The branch was reset; rebase it yourself and review the result as a new task.`);
+            }
+            if (await deps.trust.status(record.path, worktreeConfig) !== "TRUSTED") {
+                await reset();
+                throw finishError("WORKTREE_UNTRUSTED", "Re-verifying the rebased branch runs repository commands; run agent-ops trust grant in the worktree.");
+            }
+            const failed = await reverify(deps, record.path, worktreeConfig);
+            if (failed.length > 0) {
+                await reset();
+                throw finishError("WORKTREE_REVERIFY_FAILED", `After rebasing onto ${target}, verification failed: ${failed.join(", ")}. The branch was reset; fix it as a new task and finish again.`);
+            }
+        }
+        const mainConfig = await deps.loadConfig(mainRoot);
+        const gateEnabled = mainConfig.features.completionGate.enabled;
+        const before = gateEnabled ? await currentGateFingerprint(mainRoot, mainRunner) : "";
+        await git(deps, mainRoot, ["merge", "--ff-only", record.branch], "WORKTREE_MERGE_FAILED", `Git could not fast-forward ${record.targetBranch}.`);
+        const mergedHead = await git(deps, mainRoot, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
+        // The merge happened; everything below is cleanup, reported, never undone.
+        const warnings = [];
+        const attempt = async (label, step) => {
+            try {
+                await step();
+            }
+            catch (error) {
+                warnings.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        };
+        await attempt("note", async () => await git(deps, mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-f", "-m", noteText(record, task), mergedHead], "WORKTREE_NOTE_FAILED", "Git could not write the agent-ops note."));
+        if (gateEnabled) {
+            await attempt("gate", async () => {
+                const mainGate = await deps.gate(mainRoot, mainConfig);
+                await mainGate.redirect(record.sessionId, null);
+                await mainGate.rebase(before, await currentGateFingerprint(mainRoot, mainRunner));
+            });
+        }
+        await attempt("trust", async () => await deps.trust.revoke(record.path, worktreeConfig));
+        await attempt("remove", async () => await removeCheckout(deps, record, true));
+        return { record, mergedHead, rebased: !fastForward, taskId: task.task.id, warnings };
+    });
+}

package/dist/runtime/src/parallel/guard.js

@@ -0,0 +1,59 @@
+import { realpath } from "node:fs/promises";
+import { basename, dirname, join, sep } from "node:path";
+import { insideWorktreeDirectory } from "./service.js";
+/** The main checkout of the repository `runner` runs in, or null. */
+export async function resolveMainRoot(runner) {
+    const result = await runner.run(["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+    if (result.exitCode !== 0)
+        return null;
+    try {
+        const commonDir = await realpath(new TextDecoder().decode(result.stdout).trim());
+        return basename(commonDir) === ".git" ? dirname(commonDir) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The real path of `path`, resolved through its deepest existing ancestor: a
+ * Write creates files that do not exist yet, and a symlinked spelling of the
+ * repository must not decide whether an edit lands in the main checkout.
+ */
+export async function canonicalPath(path) {
+    const pending = [];
+    let current = path;
+    for (;;) {
+        try {
+            return join(await realpath(current), ...pending.reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return path;
+            pending.push(basename(current));
+            current = parent;
+        }
+    }
+}
+/**
+ * In worktree auto mode the main checkout is shared by every session, so no
+ * session writes it directly: each edit belongs in that session's own
+ * `.worktrees/<name>`. Paths outside the repository are not this guard's
+ * business.
+ */
+export async function evaluateWorktreeWrite(mainRoot, paths, sessionId) {
+    for (const path of paths) {
+        const target = await canonicalPath(path);
+        const inMain = target === mainRoot || target.startsWith(`${mainRoot}${sep}`);
+        if (inMain && !insideWorktreeDirectory(mainRoot, target)) {
+            const session = sessionId ?? "<session-id>";
+            return {
+                action: "block",
+                status: "FAIL",
+                code: "WORKTREE_REQUIRED",
+                remedy: `worktree.mode is auto, so the main checkout is shared and not edited directly. Run \`agent-ops worktree add <name> --session ${session}\` in ${mainRoot}, enter the printed path (Claude Code: EnterWorktree with that path), and edit there.`
+            };
+        }
+    }
+    return { action: "continue", status: "PASS", code: "WORKTREE_WRITE_ALLOWED" };
+}