@kylecheng3146/agent-ops 0.2.8 → 0.3.0

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

@@ -0,0 +1,147 @@
+import { readdir, realpath, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { collectChangeSurface } from "../verify/change-surface.js";
+import { assertSessionId, assertWorktreeName, bindSession, insideWorktreeDirectory, readWorktreeRecord, removeCheckout, resolveCheckouts, worktreePath, writeWorktreeRecord } from "./service.js";
+/**
+ * A baseline no source state hashes to. A resumed session inherits whatever
+ * the last one left in the worktree, so none of it counts as "unchanged".
+ */
+export const RESUMED_BASELINE = sha256("agent-ops-worktree-resumed");
+export const IDLE_DAYS = 7;
+function manageError(code, message) {
+    return new AgentOpsError(code, message);
+}
+async function mainCheckout(deps, cwd) {
+    const { mainRoot, currentRoot } = await resolveCheckouts(deps, cwd);
+    if (currentRoot !== mainRoot) {
+        throw manageError("WORKTREE_NESTED", `Run this from the main checkout (${mainRoot}).`);
+    }
+    return mainRoot;
+}
+async function mtime(path) {
+    try {
+        return (await stat(path)).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** The last time anything agent-ops tracks moved in the worktree. */
+async function lastActivity(record) {
+    const gate = join(record.path, ".agent-ops", "tasks", "completion-gate");
+    const times = [
+        Date.parse(record.createdAt) || 0,
+        await mtime(join(record.path, ".agent-ops", "tasks", "state.json")),
+        ...await Promise.all((await readdir(gate).catch(() => []))
+            .map(async (name) => await mtime(join(gate, name))))
+    ];
+    return new Date(Math.max(...times)).toISOString();
+}
+async function describe(deps, record) {
+    const runner = {
+        run: async (args) => {
+            const result = await deps.git(record.path, args);
+            return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout, "utf8") };
+        }
+    };
+    const dirty = (await collectChangeSurface(runner).catch(() => ({ paths: ["?"] }))).paths.length > 0;
+    const count = await deps.git(record.path, ["rev-list", "--count", `${record.targetBranch}..HEAD`]);
+    const taskStatus = await deps.tasks(record.path).status({ sessionId: record.sessionId })
+        .then((task) => `${task.task.id} ${task.status}`)
+        .catch(() => "none");
+    return {
+        record,
+        dirty,
+        ahead: count.exitCode === 0 ? Number(count.stdout.trim()) : 0,
+        taskStatus,
+        lastActivity: await lastActivity(record)
+    };
+}
+/** Every agent-ops worktree of this repository, from any of its checkouts. */
+export async function listWorktrees(deps, cwd) {
+    const { mainRoot } = await resolveCheckouts(deps, cwd);
+    const listing = await deps.git(mainRoot, ["worktree", "list", "--porcelain"]);
+    if (listing.exitCode !== 0) {
+        throw manageError("WORKTREE_LIST_FAILED", "Git could not list worktrees.");
+    }
+    const statuses = [];
+    for (const line of listing.stdout.split("\n")) {
+        if (!line.startsWith("worktree "))
+            continue;
+        // Git prints forward slashes on Windows; mainRoot is a native real path.
+        const listed = resolve(line.slice("worktree ".length));
+        const path = await realpath(listed).catch(() => listed);
+        if (!insideWorktreeDirectory(mainRoot, path))
+            continue;
+        const record = await readWorktreeRecord(path);
+        if (record !== null)
+            statuses.push(await describe(deps, record));
+    }
+    return statuses.sort((left, right) => left.record.name.localeCompare(right.record.name));
+}
+export function idleWorktrees(statuses, now) {
+    return statuses.filter(({ lastActivity: at }) => now - Date.parse(at) > IDLE_DAYS * 24 * 60 * 60 * 1000);
+}
+/** Doctor's reading of the worktrees: idle ones are worth a look, not a failure. */
+export function worktreeDoctorResult(statuses, now) {
+    const idle = idleWorktrees(statuses, now);
+    return idle.length === 0
+        ? { status: "PASS", message: `${statuses.length} agent-ops worktree(s), none idle.` }
+        : {
+            status: "DEGRADED",
+            message: `Idle for more than ${IDLE_DAYS} days: ${idle.map(({ record }) => record.name).join(", ")}.`,
+            remediation: "Resume, finish or remove them; see agent-ops worktree list."
+        };
+}
+async function requireRecord(mainRoot, name) {
+    const record = await readWorktreeRecord(worktreePath(mainRoot, name));
+    if (record === null) {
+        throw manageError("WORKTREE_NOT_FOUND", `No agent-ops worktree named ${name}; see agent-ops worktree list.`);
+    }
+    return record;
+}
+/**
+ * Hands a worktree whose session ended to a new one: the task, the gate and
+ * the record follow the new id, and the new session's first Stop has to
+ * account for everything already in the worktree.
+ */
+export async function resumeWorktree(deps, options) {
+    const name = assertWorktreeName(options.name);
+    const sessionId = assertSessionId(options.sessionId);
+    const mainRoot = await mainCheckout(deps, options.cwd);
+    const previous = await requireRecord(mainRoot, name);
+    const tasks = deps.tasks(previous.path);
+    const attached = await tasks.status({ sessionId: previous.sessionId }).catch(() => null);
+    if (attached !== null)
+        await tasks.attach(sessionId, attached.task.id);
+    const record = { ...previous, sessionId };
+    await writeWorktreeRecord(record);
+    const mainConfig = await deps.loadConfig(mainRoot);
+    if (mainConfig.features.completionGate.enabled && previous.sessionId !== sessionId) {
+        await (await deps.gate(mainRoot, mainConfig)).redirect(previous.sessionId, null);
+    }
+    await bindSession(deps, record, mainConfig, RESUMED_BASELINE);
+    return record;
+}
+/**
+ * Deletes a worktree and its branch. Work that exists nowhere else — an
+ * uncommitted change or a commit the target lacks — needs `force`.
+ */
+export async function removeWorktree(deps, options) {
+    const name = assertWorktreeName(options.name);
+    const mainRoot = await mainCheckout(deps, options.cwd);
+    const status = await describe(deps, await requireRecord(mainRoot, name));
+    if ((status.dirty || status.ahead > 0) && !options.force) {
+        throw manageError("WORKTREE_UNMERGED", `${name} has ${status.dirty ? "uncommitted changes" : ""}${status.dirty && status.ahead > 0 ? " and " : ""}${status.ahead > 0 ? `${status.ahead} commit(s) not in ${status.record.targetBranch}` : ""}. Finish it, or remove it with --force to discard that work (the user is asked).`);
+    }
+    const { record } = status;
+    const mainConfig = await deps.loadConfig(mainRoot);
+    if (mainConfig.features.completionGate.enabled) {
+        await (await deps.gate(mainRoot, mainConfig)).redirect(record.sessionId, null);
+    }
+    await deps.trust.revoke(record.path, await deps.loadConfig(record.path)).catch(() => undefined);
+    await removeCheckout(deps, record, true);
+    return status;
+}

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

@@ -0,0 +1,263 @@
+import { chmod, copyFile, lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { basename, dirname, join, sep } from "node:path";
+import { calculateConfigHash } from "../config/hash.js";
+import { parseInstallManifest } from "../fs/manifest.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { writeSessionMarker } from "../hooks/codex-loop.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+/**
+ * One Git worktree per writing session, so parallel sessions stop sharing the
+ * change surface every fingerprint is taken over. Worktrees live inside the
+ * main checkout, kept out of its surface by `.git/info/exclude` — never by
+ * `.gitignore`, whose edit would itself be a change the gate has to explain.
+ */
+export const WORKTREE_DIRECTORY = ".worktrees";
+export const WORKTREE_BRANCH_PREFIX = "agent-ops/";
+export const WORKTREE_RECORD_PATH = ".agent-ops/tasks/worktree.json";
+const EXCLUDE_LINE = `/${WORKTREE_DIRECTORY}/`;
+const NAME = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/u;
+const SESSION = /^[^\0\r\n]{1,256}$/u;
+const DEFAULT_SETUP_TIMEOUT_MS = 10 * 60 * 1000;
+function worktreeError(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 worktreeError(code, detail === undefined || detail === "" ? message : `${message} ${detail}`);
+    }
+    return result.stdout.trim();
+}
+export function assertWorktreeName(name) {
+    if (name === undefined || !NAME.test(name) || name.includes("..")) {
+        throw worktreeError("WORKTREE_NAME_INVALID", "A worktree name is 1-64 lowercase letters, digits, '.', '_' or '-', starting and ending with a letter or digit.");
+    }
+    return name;
+}
+export function assertSessionId(sessionId) {
+    if (sessionId === undefined || !SESSION.test(sessionId)) {
+        throw worktreeError("WORKTREE_SESSION_REQUIRED", "Pass --session <id>: the conversation that will work in this worktree.");
+    }
+    return sessionId;
+}
+/**
+ * The main checkout and the checkout `cwd` is in. They differ inside a linked
+ * worktree. A repository whose common directory is not `<root>/.git` (bare,
+ * or a separate git dir) has no main checkout to put worktrees in.
+ */
+export async function resolveCheckouts(deps, cwd) {
+    const commonDir = await realpath(await git(deps, cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"], "WORKTREE_NOT_GIT", "Worktrees require a Git repository."));
+    const currentRoot = await realpath(await git(deps, cwd, ["rev-parse", "--show-toplevel"], "WORKTREE_NOT_GIT", "Worktrees require a Git checkout."));
+    if (basename(commonDir) !== ".git") {
+        throw worktreeError("WORKTREE_LAYOUT_UNSUPPORTED", "Worktrees need a main checkout whose Git directory is <root>/.git.");
+    }
+    return { mainRoot: dirname(commonDir), currentRoot, commonDir };
+}
+export function worktreePath(mainRoot, name) {
+    return join(mainRoot, WORKTREE_DIRECTORY, name);
+}
+/** True when `path` is inside `<mainRoot>/.worktrees/`. */
+export function insideWorktreeDirectory(mainRoot, path) {
+    return path.startsWith(`${join(mainRoot, WORKTREE_DIRECTORY)}${sep}`);
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureExcluded(deps, mainRoot, commonDir) {
+    const probe = await deps.git(mainRoot, ["check-ignore", "-q", "--no-index", `${WORKTREE_DIRECTORY}/probe`]);
+    if (probe.exitCode === 0)
+        return;
+    const path = join(commonDir, "info", "exclude");
+    let current = "";
+    try {
+        current = await readFile(path, "utf8");
+    }
+    catch {
+        await mkdir(dirname(path), { recursive: true });
+    }
+    if (current.split(/\r?\n/u).includes(EXCLUDE_LINE))
+        return;
+    const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+    await writeFile(path, `${current}${separator}${EXCLUDE_LINE}\n`);
+}
+function portableRelative(path) {
+    return path.length > 0 && !path.startsWith("/") && !path.startsWith("~") &&
+        !path.includes("\\") && !path.includes("\0") &&
+        path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/**
+ * Files Git does not carry into a new worktree but the session needs there:
+ * what agent-ops installed (rules, hooks, its own config) and whatever
+ * `.worktreeinclude` names (gitignore syntax: `.env`, `local.properties`).
+ * Only files missing from the new checkout are copied, so a tracked file
+ * always keeps the branch's version.
+ */
+async function carriedFiles(deps, mainRoot) {
+    // The config is what makes the new checkout an agent-ops checkout at all:
+    // carried even when no manifest lists it.
+    const paths = new Set([".agent-ops/config.json"]);
+    const manifestSource = await readFile(join(mainRoot, ".agent-ops", "manifest.json"), "utf8").catch(() => null);
+    if (manifestSource !== null) {
+        paths.add(".agent-ops/manifest.json");
+        try {
+            const manifest = parseInstallManifest(manifestSource);
+            for (const { path } of [...manifest.artifacts, ...manifest.markers, ...(manifest.hooks ?? [])]) {
+                paths.add(path);
+            }
+        }
+        catch {
+            // An unreadable manifest still leaves the manifest itself to copy.
+        }
+    }
+    if (await exists(join(mainRoot, ".worktreeinclude"))) {
+        const listed = await git(deps, mainRoot, ["ls-files", "-z", "--others", "--ignored", "--exclude-from=.worktreeinclude"], "WORKTREE_INCLUDE_INVALID", ".worktreeinclude could not be read.");
+        for (const path of listed.split("\0"))
+            paths.add(path);
+    }
+    return [...paths].filter((path) => portableRelative(path) &&
+        !path.startsWith(`${WORKTREE_DIRECTORY}/`) &&
+        !path.startsWith(".agent-ops/tasks/") &&
+        !path.startsWith(".agent-ops/reviews/")).sort();
+}
+async function copyMissing(mainRoot, target, paths) {
+    const copied = [];
+    for (const path of paths) {
+        const source = join(mainRoot, ...path.split("/"));
+        const destination = join(target, ...path.split("/"));
+        let entry;
+        try {
+            entry = await lstat(source);
+        }
+        catch {
+            continue;
+        }
+        if (!entry.isFile() || await exists(destination))
+            continue;
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(source, destination);
+        await chmod(destination, entry.mode & 0o777);
+        copied.push(path);
+    }
+    return copied;
+}
+export async function readWorktreeRecord(root) {
+    const source = await readPrivateFile(join(root, ...WORKTREE_RECORD_PATH.split("/")), root).catch(() => null);
+    if (source === null)
+        return null;
+    try {
+        const value = JSON.parse(source);
+        return value.schemaVersion === 1 && typeof value.name === "string" &&
+            typeof value.branch === "string" && typeof value.path === "string" &&
+            typeof value.mainRoot === "string" && typeof value.targetBranch === "string" &&
+            typeof value.base === "string" && typeof value.sessionId === "string" &&
+            typeof value.createdAt === "string"
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeWorktreeRecord(record) {
+    await writePrivateFile(join(record.path, ...WORKTREE_RECORD_PATH.split("/")), `${JSON.stringify(record, null, 2)}\n`, record.path);
+}
+/** Points the session at the worktree from both sides of the gate. */
+export async function bindSession(deps, record, mainConfig, baselineFingerprint) {
+    for (const harness of ["claude", "codex"]) {
+        if (await exists(join(record.mainRoot, `.${harness}`))) {
+            await writeSessionMarker({ root: record.path, harness, sessionId: record.sessionId });
+        }
+    }
+    if (!mainConfig.features.completionGate.enabled)
+        return;
+    const worktreeConfig = await deps.loadConfig(record.path);
+    await (await deps.gate(record.path, worktreeConfig)).seed(record.sessionId, baselineFingerprint);
+    await (await deps.gate(record.mainRoot, mainConfig)).redirect(record.sessionId, record.path);
+}
+export async function removeCheckout(deps, record, force) {
+    await git(deps, record.mainRoot, ["worktree", "remove", ...(force ? ["--force"] : []), record.path], "WORKTREE_REMOVE_FAILED", `Git could not remove ${record.path}.`);
+    await git(deps, record.mainRoot, ["branch", force ? "-D" : "-d", record.branch], "WORKTREE_REMOVE_FAILED", `Git could not delete ${record.branch}.`);
+}
+/**
+ * Creates `.worktrees/<name>` on `agent-ops/<name>` from the main checkout's
+ * HEAD and makes it a working agent-ops checkout for `sessionId`.
+ */
+export async function addWorktree(deps, options) {
+    const name = assertWorktreeName(options.name);
+    const sessionId = assertSessionId(options.sessionId);
+    const { mainRoot, currentRoot, commonDir } = await resolveCheckouts(deps, options.cwd);
+    if (currentRoot !== mainRoot) {
+        throw worktreeError("WORKTREE_NESTED", `Run worktree commands from the main checkout (${mainRoot}), not from inside a worktree.`);
+    }
+    const targetBranch = await git(deps, mainRoot, ["symbolic-ref", "--short", "-q", "HEAD"], "WORKTREE_DETACHED_HEAD", "The main checkout must be on a branch to merge back into.");
+    const base = await git(deps, mainRoot, ["rev-parse", "--verify", "HEAD^{commit}"], "WORKTREE_NO_COMMIT", "The main checkout has no commit to branch from.");
+    const path = worktreePath(mainRoot, name);
+    const branch = `${WORKTREE_BRANCH_PREFIX}${name}`;
+    if (await exists(path)) {
+        throw worktreeError("WORKTREE_EXISTS", `${path} already exists; pick another name or resume it.`);
+    }
+    if ((await deps.git(mainRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`])).exitCode === 0) {
+        throw worktreeError("WORKTREE_EXISTS", `Branch ${branch} already exists; pick another name.`);
+    }
+    const mainConfig = await deps.loadConfig(mainRoot);
+    const mainTrust = await deps.trust.status(mainRoot, mainConfig);
+    const setupSteps = mainConfig.worktree?.setup ?? [];
+    if (setupSteps.length > 0 && mainTrust !== "TRUSTED") {
+        throw worktreeError("WORKTREE_SETUP_UNTRUSTED", "worktree.setup runs repository commands; run agent-ops trust grant in the main checkout first.");
+    }
+    await ensureExcluded(deps, mainRoot, commonDir);
+    await git(deps, mainRoot, ["worktree", "add", "-b", branch, path, base], "WORKTREE_ADD_FAILED", "Git could not create the worktree.");
+    const record = {
+        schemaVersion: 1,
+        name,
+        branch,
+        path: await realpath(path),
+        mainRoot,
+        targetBranch,
+        base,
+        sessionId,
+        createdAt: deps.now?.() ?? new Date().toISOString()
+    };
+    let trusted = false;
+    try {
+        const copied = await copyMissing(mainRoot, record.path, await carriedFiles(deps, mainRoot));
+        const worktreeConfig = await deps.loadConfig(record.path);
+        // The same commands the user already trusted, and nothing else: any
+        // difference in config leaves the new checkout untrusted.
+        if (mainTrust === "TRUSTED" && calculateConfigHash(worktreeConfig) === calculateConfigHash(mainConfig)) {
+            await deps.trust.grant(record.path, worktreeConfig);
+            trusted = true;
+        }
+        const setup = [];
+        for (const step of setupSteps) {
+            const result = await deps.runSetup(record.path, {
+                ...step,
+                timeoutMs: step.timeoutMs ?? DEFAULT_SETUP_TIMEOUT_MS
+            });
+            const label = [step.command, ...step.args].join(" ");
+            if (result.exitCode !== 0) {
+                throw worktreeError("WORKTREE_SETUP_FAILED", `Setup step failed (${label}, exit ${String(result.exitCode)}); the worktree was removed. ${result.output.trim().split("\n").slice(-5).join("\n")}`.trim());
+            }
+            setup.push(label);
+        }
+        await writeWorktreeRecord(record);
+        await bindSession(deps, record, mainConfig);
+        return { record, copied, trusted, setup };
+    }
+    catch (error) {
+        if (mainConfig.features.completionGate.enabled) {
+            await (await deps.gate(mainRoot, mainConfig)).redirect(sessionId, null).catch(() => undefined);
+        }
+        if (trusted)
+            await deps.trust.revoke(record.path, mainConfig).catch(() => undefined);
+        await removeCheckout(deps, record, true).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/runtime/src/schema/validate.js

@@ -300,7 +300,8 @@ export function validateConfig(value) {
         "reviewRoles",
         "schemaVersion",
         "securityExceptions",
-        "verification"
+        "verification",
+        "worktree"
     ], CONFIG_SCHEMA_VERSION);
     if (isFailure(root)) {
         return root;
@@ -411,8 +412,56 @@ export function validateConfig(value) {
             roles.add(role.value.role);
         }
     }
+    if (root.worktree !== undefined) {
+        const worktree = validateWorktree(root.worktree, "$.worktree");
+        if (!worktree.ok) {
+            return worktree;
+        }
+    }
     return success(root);
 }
+function validateWorktree(value, path) {
+    if (!isRecord(value)) {
+        return failure("INVALID_TYPE", path, "worktree must be an object.");
+    }
+    const unknown = unknownFieldFailure(value, ["mode", "setup"], path);
+    if (unknown !== undefined) {
+        return unknown;
+    }
+    if (value.mode !== "auto" && value.mode !== "off") {
+        return failure("INVALID_WORKTREE_MODE", `${path}.mode`, `Unsupported worktree mode: ${String(value.mode)}`);
+    }
+    if (value.setup === undefined) {
+        return success(value);
+    }
+    if (!Array.isArray(value.setup)) {
+        return failure("INVALID_TYPE", `${path}.setup`, "setup must be an array.");
+    }
+    for (const [index, step] of value.setup.entries()) {
+        const stepPath = `${path}.setup[${index}]`;
+        if (!isRecord(step)) {
+            return failure("INVALID_TYPE", stepPath, "Expected a setup command object.");
+        }
+        const stepUnknown = unknownFieldFailure(step, ["args", "command", "timeoutMs"], stepPath);
+        if (stepUnknown !== undefined) {
+            return stepUnknown;
+        }
+        if (!isNonEmptyString(step.command)) {
+            return failure("INVALID_COMMAND", `${stepPath}.command`, "command must be a non-empty string.");
+        }
+        if (!isStringArray(step.args) ||
+            step.args.some((argument) => argument.includes("\0"))) {
+            return failure("INVALID_ARGS", `${stepPath}.args`, "args must be an array of strings.");
+        }
+        if (step.timeoutMs !== undefined &&
+            (!Number.isSafeInteger(step.timeoutMs) ||
+                step.timeoutMs <= 0 ||
+                step.timeoutMs > MAX_TIMEOUT_MS)) {
+            return failure("INVALID_TIMEOUT", `${stepPath}.timeoutMs`, "timeoutMs must be a positive integer.");
+        }
+    }
+    return success(value);
+}
 function validateReviewRole(value, path) {
     if (!isRecord(value)) {
         return failure("INVALID_TYPE", path, "Expected a review role object.");

package/docs/en/guides/configuration.md

@@ -132,6 +132,48 @@ agent-ops doctor --check-auth # one real print call per target
 reports what to do but never fixes it: every target authenticates through
 interactive OAuth, so there is no `--fix`. Run `<target> login` yourself.
 
+### Parallel sessions in worktrees
+
+Verification, review and the completion gate all fingerprint the whole Git
+change surface, so two conversations editing one checkout void each other's
+evidence. Give each editing conversation its own worktree instead:
+
+```json
+{
+  "worktree": {
+    "mode": "auto",
+    "setup": [{ "command": "pnpm", "args": ["install", "--frozen-lockfile"] }]
+  }
+}
+```
+
+- `mode: "auto"` routes every editing conversation through
+  `agent-ops worktree add <name> --session <id>`, run from the main checkout.
+  On Claude Code a direct Edit or Write of the main checkout outside
+  `.worktrees/` is denied (run `agent-ops update` once so the PreToolUse hook
+  matches the file tools). Absent or `"off"` keeps today's single checkout.
+- `add` creates `.worktrees/<name>` on branch `agent-ops/<name>` from the main
+  checkout's HEAD and excludes `/.worktrees/` through `.git/info/exclude`,
+  never `.gitignore`. It copies the ignored files agent-ops installed and any
+  file matched by a root `.worktreeinclude` (gitignore syntax, for example
+  `.env` or `local.properties`); a file Git already checked out is never
+  overwritten. Trust is inherited only when the main checkout is trusted and
+  the worktree's effective config is identical.
+- `setup` commands run in the new worktree (default timeout ten minutes) for
+  what Git does not carry, such as installed dependencies. They are part of
+  the trusted config, so they need no separate approval; a failing step
+  removes the worktree again.
+- The session's completion gate follows it: Claude Code enters the worktree
+  with EnterWorktree, and a host that cannot move a session (agy) is judged by
+  the worktree's gate through a redirect the main checkout records.
+- `agent-ops worktree finish <name>` merges by fast-forward only, one finish
+  at a time. If the target moved, it rebases; a clean rebase whose own patch
+  is unchanged is re-verified before merging, and a conflict is reported with
+  the `refs/notes/agent-ops` intent of the work that landed first.
+- `worktree list`, `resume <name> --session <id>` and `remove <name>` manage
+  what is left; `remove --force` discards work and asks the user first.
+  `doctor` reports worktrees idle for more than seven days.
+
 ### Project-local loop profile
 
 `--profile loop` is an opt-in project-scope profile. Select `codex`, `claude`,

package/docs/en/spec/delegation.md

@@ -29,3 +29,13 @@ Concurrent delegated writers MUST NOT share one working tree.
 - Evidence: `agent-ops verify` returns a status other than `UNKNOWN` for the run.
 - Positive: `Read-only scans run in parallel; the single edit runs in the coordinator worktree.`
 - Negative: `Two subagents edit the same files while verification runs.`
+
+## DELEGATE-ISOLATION-002
+
+Parallel editing conversations in one repository MUST each work in their own agent-ops worktree.
+
+- Trigger: `worktree.mode` is `auto`, or a second conversation will edit the repository while another is still open.
+- Action: Run `agent-ops worktree add <name> --session <id>` from the main checkout before the first edit, work only in the printed path, and merge with `agent-ops worktree finish <name>` after the task completes against the printed `--base`.
+- Evidence: `agent-ops worktree list` shows one worktree per editing session, and each finish reports a fast-forward merge.
+- Positive: `Two conversations edit .worktrees/login and .worktrees/cart; each verifies, reviews and finishes on its own.`
+- Negative: `Two conversations edit the main checkout at once, so each one's verification and review is voided by the other's writes.`

package/docs/zh-TW/guides/configuration.md

@@ -116,6 +116,46 @@ agent-ops doctor --check-auth # 每個目標一次真實 print 呼叫
 不會代為修復：所有目標都經由互動式 OAuth 認證，因此沒有 `--fix`。
 請自行執行 `<target> login`。
 
+### 在 worktree 中並行 session
+
+Verification、review 與 completion gate 都對整個 Git change surface 計算
+fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方的 evidence。
+請讓每個修改中的對話使用自己的 worktree：
+
+```json
+{
+  "worktree": {
+    "mode": "auto",
+    "setup": [{ "command": "pnpm", "args": ["install", "--frozen-lockfile"] }]
+  }
+}
+```
+
+- `mode: "auto"` 讓每個修改中的對話都先在主 checkout 執行
+  `agent-ops worktree add <name> --session <id>`。Claude Code 直接以 Edit 或
+  Write 修改主 checkout 中 `.worktrees/` 以外的檔案會被拒絕（需先執行一次
+  `agent-ops update`，讓 PreToolUse hook 比對檔案工具）。未設定或 `"off"` 則維持
+  目前的單一 checkout。
+- `add` 從主 checkout 的 HEAD 建立 `.worktrees/<name>` 與 branch
+  `agent-ops/<name>`，並透過 `.git/info/exclude`（而非 `.gitignore`）排除
+  `/.worktrees/`。它會複製 agent-ops 安裝的 ignored 檔案，以及根目錄
+  `.worktreeinclude`（gitignore 語法，例如 `.env` 或 `local.properties`）比對到
+  的檔案；Git 已 checkout 的檔案一律不覆寫。只有主 checkout 已 trusted 且
+  worktree 的 effective config 完全相同時才繼承 trust。
+- `setup` 指令在新 worktree 中執行（預設 timeout 十分鐘），處理 Git 不會帶過去
+  的東西，例如已安裝的相依套件。它屬於 trusted config 的一部分，不需另外核准；
+  任一步驟失敗會移除該 worktree。
+- Session 的 completion gate 會跟著它：Claude Code 以 EnterWorktree 進入
+  worktree；無法移動 session 的 host（agy）則透過主 checkout 記錄的 redirect，
+  由 worktree 的 gate 判定。
+- `agent-ops worktree finish <name>` 只以 fast-forward 合併，一次只執行一個
+  finish。Target 若已前進會先 rebase；沒有衝突且自身 patch 不變的 rebase 會先
+  重新驗證再合併；衝突則連同先合併那份工作在 `refs/notes/agent-ops` 的意圖一起
+  回報。
+- `worktree list`、`resume <name> --session <id>` 與 `remove <name>` 管理剩下的
+  worktree；`remove --force` 會丟棄工作，執行前會先詢問使用者。`doctor` 會回報
+  閒置超過七天的 worktree。
+
 ### Project-local loop profile
 
 `--profile loop` 是明確 opt-in 的 project-scope profile。請選擇 `codex`、

package/docs/zh-TW/spec/delegation.md

@@ -1,6 +1,6 @@
 # 委派
 
-English source version: 2026-07-23. Revalidate: when the English specification changes.
+English source version: 2026-09-24. Revalidate: when the English specification changes.
 
 ## DELEGATE-SCOPE-001
 
@@ -31,3 +31,13 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 - Evidence: `agent-ops verify` 該次執行回傳非 `UNKNOWN` 的狀態。
 - Positive: `唯讀掃描並行執行；唯一的修改在協調者工作區進行。`
 - Negative: `兩個 subagent 在驗證執行期間修改相同檔案。`
+
+## DELEGATE-ISOLATION-002
+
+同一個 repository 中並行修改檔案的對話 MUST 各自在自己的 agent-ops worktree 中工作。
+
+- Trigger: `worktree.mode` 為 `auto`，或另一個對話仍開著時，第二個對話也要修改這個 repository。
+- Action: 第一次修改前，在主 checkout 執行 `agent-ops worktree add <name> --session <id>`，只在印出的路徑中工作；task 以印出的 `--base` 完成後，用 `agent-ops worktree finish <name>` 合併。
+- Evidence: `agent-ops worktree list` 顯示每個修改中的 session 各有一個 worktree，且每次 finish 都回報 fast-forward 合併。
+- Positive: `兩個對話分別修改 .worktrees/login 與 .worktrees/cart；各自驗證、review 並 finish。`
+- Negative: `兩個對話同時修改主 checkout，彼此的寫入讓對方的驗證與 review 全部作廢。`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",

package/schemas/config.schema.json

@@ -119,6 +119,41 @@
         }
       }
     },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "enum": ["auto", "off"]
+        },
+        "setup": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["command", "args"],
+            "properties": {
+              "command": {
+                "$ref": "#/$defs/nonEmptyString"
+              },
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[^\\u0000]*$"
+                }
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 2147483647
+              }
+            }
+          }
+        }
+      }
+    },
     "securityExceptions": {
       "type": "array",
       "items": {