@kylecheng3146/agent-ops 0.3.3 → 0.3.5

package/dist/packages/cli/src/args.js

@@ -86,6 +86,8 @@ export function parseArgs(argv) {
     let versionSeen = false;
     let worktreeName;
     let force = false;
+    let worktreeFrom;
+    let worktreeTargetBranch;
     let worktree;
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
@@ -266,6 +268,22 @@ export function parseArgs(argv) {
                 }
                 force = true;
                 break;
+            case "--from": {
+                if (worktreeFrom !== undefined) {
+                    duplicate(token);
+                }
+                worktreeFrom = readOptionValue(argv, index, token);
+                index += 1;
+                break;
+            }
+            case "--target-branch": {
+                if (worktreeTargetBranch !== undefined) {
+                    duplicate(token);
+                }
+                worktreeTargetBranch = readOptionValue(argv, index, token);
+                index += 1;
+                break;
+            }
             case "--rerun":
                 if (rerun) {
                     duplicate(token);
@@ -381,6 +399,8 @@ export function parseArgs(argv) {
             yes ||
             rerun ||
             worktree !== undefined ||
+            worktreeFrom !== undefined ||
+            worktreeTargetBranch !== undefined ||
             force) {
             throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Only --json may be combined with global help or version.");
         }
@@ -536,11 +556,22 @@ export function parseArgs(argv) {
             dryRun ||
             yes ||
             rerun)) {
-        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "worktree accepts only a name, --session and --json.");
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "worktree accepts only a name, --session, --from, --target-branch and --json.");
     }
     if (force && !(command === "worktree" && action === "remove")) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--force may be used only with worktree remove.");
     }
+    if ((worktreeFrom !== undefined || worktreeTargetBranch !== undefined) &&
+        !(command === "worktree" && action === "add")) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--from and --target-branch may be used only with worktree add.");
+    }
+    if (worktreeFrom !== undefined && worktreeFrom.trim() === "") {
+        throw new CliArgumentError("CLI_INVALID_VALUE", "Invalid value for --from.", "--from");
+    }
+    if (worktreeTargetBranch !== undefined &&
+        !/^[A-Za-z0-9._/-]{1,128}$/u.test(worktreeTargetBranch)) {
+        throw new CliArgumentError("CLI_INVALID_VALUE", `Invalid value for --target-branch: ${worktreeTargetBranch}`, "--target-branch");
+    }
     if (command === "worktree" && action !== "add" && action !== "resume" && sessionId !== undefined) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", `worktree ${action} takes the session from the worktree; omit --session.`);
     }
@@ -563,6 +594,8 @@ export function parseArgs(argv) {
         ...(evidence.length === 0 ? {} : { evidence }),
         ...(sessionId === undefined ? {} : { sessionId }),
         ...(base === undefined ? {} : { base }),
+        ...(worktreeFrom === undefined ? {} : { worktreeFrom }),
+        ...(worktreeTargetBranch === undefined ? {} : { worktreeTargetBranch }),
         ...(checkAuth ? { checkAuth } : {}),
         ...(checkAuthTargets.length === 0 ? {} : { checkAuthTargets }),
         rerun,

package/dist/packages/cli/src/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFile } from "node:fs/promises";
+import { readFile, readdir, stat } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -43,7 +43,8 @@ import { errorEnvelope } from "./output.js";
 import { runAgyHeadless } from "./agy-headless.js";
 import { runWorktreeCommand } from "./commands/parallel.js";
 import { ensureSessionWorktree, resolveCheckouts } from "../../../runtime/src/parallel/service.js";
-import { listWorktrees, worktreeDoctorResult } from "../../../runtime/src/parallel/manage.js";
+import { listWorktrees, branchLockDoctorResult, worktreeDoctorResult } from "../../../runtime/src/parallel/manage.js";
+import { detectGhostFiles, ghostFilesDoctorResult } from "../../../runtime/src/install/doctor.js";
 const HOOK_RUNTIME_PATH = fileURLToPath(new URL("./hook-entry.js", import.meta.url));
 async function readOptionalText(path) {
     try {
@@ -106,6 +107,48 @@ async function worktreeDoctorProbe(root) {
     }
     return worktreeDoctorResult(statuses, Date.now());
 }
+const GHOST_SCAN_ALLOWLIST = new Set([
+    ".git", ".worktrees", ".agent-ops", ".tmp", "node_modules", "dist"
+]);
+async function worktreeBranchLockProbe(root) {
+    try {
+        const result = await worktreeDependencies().git(root, ["worktree", "list", "--porcelain"]);
+        if (result.exitCode !== 0) {
+            return { status: "UNKNOWN", message: "Git could not list worktrees." };
+        }
+        return branchLockDoctorResult(result.stdout);
+    }
+    catch {
+        return { status: "UNKNOWN", message: "Git could not list worktrees." };
+    }
+}
+async function rootGhostFilesProbe(root) {
+    try {
+        const listing = await worktreeDependencies().git(root, ["ls-files", "--others", "--exclude-standard", "-z"]);
+        const untracked = listing.exitCode === 0
+            ? new Set(listing.stdout.split("\0").filter((entry) => entry.length > 0 && !entry.includes("/")))
+            : new Set();
+        const names = (await readdir(root)).filter((name) => !GHOST_SCAN_ALLOWLIST.has(name)).slice(0, 512);
+        const candidates = await Promise.all(names.map(async (name) => {
+            try {
+                const info = await stat(join(root, name));
+                return {
+                    name,
+                    size: info.size,
+                    isFile: info.isFile(),
+                    tracked: !untracked.has(name)
+                };
+            }
+            catch {
+                return { name, size: -1, isFile: false, tracked: true };
+            }
+        }));
+        return ghostFilesDoctorResult(detectGhostFiles(candidates.filter((candidate) => candidate.size >= 0)));
+    }
+    catch {
+        return { status: "UNKNOWN", message: "The repository root could not be scanned." };
+    }
+}
 const argv = process.argv.slice(2);
 function runAgy(args, options = {}) {
     return execFileSync("agy", [...args], {
@@ -301,7 +344,9 @@ else {
                                     : { status };
                             },
                             reviewTarget: async (target, deep) => await probeReviewTarget(target, { cwd: root, deep }),
-                            worktrees: async () => await worktreeDoctorProbe(root)
+                            worktrees: async () => await worktreeDoctorProbe(root),
+                            worktreeBranchLock: async () => await worktreeBranchLockProbe(root),
+                            rootGhostFiles: async () => await rootGhostFilesProbe(root)
                         },
                         ...(args.checkAuth === true
                             ? { checkReviewTargetAuth: true }

package/dist/packages/cli/src/cli.js

@@ -191,10 +191,15 @@ Options:
 Give one writing session its own Git worktree, so parallel sessions stop
 voiding each other's verification and review. Run it from the main checkout.
 
-  add <name>   Create .worktrees/<name> on branch agent-ops/<name> from HEAD,
-               copy the ignored agent-ops files and .worktreeinclude matches,
-               inherit trust for an identical config, run worktree.setup, and
-               point the session's completion gate at the new worktree.
+  add <name>   Create .worktrees/<name> on branch agent-ops/<name> from HEAD
+               (or --from <commit|branch|tag>), copy the ignored agent-ops
+               files and .worktreeinclude matches, inherit trust for an
+               identical config, run worktree.setup, and point the session's
+               completion gate at the new worktree. When the main checkout is
+               detached, --target-branch <branch> is required and names the
+               branch finish merges back into.
+               A branch already checked out in another worktree is rejected
+               before Git runs; see agent-ops worktree list.
   finish <name>
                Once its task is complete, fast-forward the main checkout's
                branch to the worktree's (after a clean rebase and
@@ -211,6 +216,10 @@ voiding each other's verification and review. Run it from the main checkout.
 
 Options:
   --session <id>   add, resume: the conversation that will work there (required)
+  --from <ref>     add: branch the new worktree from this commit, branch or tag (default HEAD)
+  --target-branch <branch>
+                   add: branch finish merges back into (defaults to the current
+                   branch; required when the main checkout is detached)
   --force          remove: discard uncommitted or unmerged work
   --json
 `

package/dist/packages/cli/src/commands/parallel.js

@@ -82,7 +82,9 @@ export async function runWorktreeCommand(options) {
     const result = await addWorktree(options.deps, {
         cwd: options.cwd,
         name: args.worktreeName,
-        sessionId
+        sessionId,
+        ...(args.worktreeFrom === undefined ? {} : { from: args.worktreeFrom }),
+        ...(args.worktreeTargetBranch === undefined ? {} : { targetBranch: args.worktreeTargetBranch })
     });
     return okEnvelope("WORKTREE_CREATED", { ...result, text: addText(result) });
 }

package/dist/packages/cli/src/commands/review.js

@@ -111,8 +111,7 @@ async function currentEvidence(options, context, criterionId, commandId, configH
             continue;
         }
         const evidence = validation.value;
-        if (evidence.schemaVersion !== 2 ||
-            evidence.taskId !== context.taskId ||
+        if (evidence.taskId !== context.taskId ||
             evidence.criterionId !== criterionId ||
             evidence.commandId !== commandId ||
             evidence.configHash !== configHash ||
@@ -137,6 +136,9 @@ async function preflightReview(options, context, sourceFingerprint) {
         options.gitRunner === undefined) {
         return { ok: false, reason: "stale-verification" };
     }
+    if (context.criteria.some((criterion) => !options.config.verification.commands.some(({ id, required }) => required && (criterion.verifierIds ?? []).includes(id)))) {
+        return { ok: false, reason: "missing-verification-evidence" };
+    }
     const configHash = calculateConfigHash(options.config);
     const commands = [];
     for (const criterion of context.criteria) {
@@ -146,7 +148,13 @@ async function preflightReview(options, context, sourceFingerprint) {
                 return { ok: false, reason: "missing-verification-evidence" };
             }
             const found = await currentEvidence(options, context, criterion.id, commandId, configHash, sourceFingerprint);
-            const selected = newestEvidence(found.current);
+            const compatible = command.evidence.kind === "test-count"
+                ? found.current.filter(({ evidence }) => evidence.schemaVersion === 3)
+                : found.current;
+            if (command.required && found.current.length > 0 && compatible.length === 0) {
+                return { ok: false, reason: "stale-verification" };
+            }
+            const selected = newestEvidence(compatible);
             if (command.required !== true) {
                 if (selected !== undefined) {
                     commands.push({

package/dist/packages/cli/src/commands/verify.js

@@ -57,7 +57,7 @@ function publicReport(report) {
     };
 }
 function formatResult(result) {
-    const testCount = result.testCount === null ? "" : ` (tests: ${result.testCount})`;
+    const testCount = result.testCount === null ? "" : ` (passed tests: ${result.testCount})`;
     const lines = [
         `- ${result.status} ${safe(result.commandId)}${testCount}`
     ];

package/dist/packages/cli/src/hook-process.js

@@ -10,7 +10,7 @@ import { redactSecrets } from "../../../runtime/src/security/redact.js";
 import { claudeStopRecursionMarker } from "../../../runtime/src/adapters/claude/input.js";
 import { HARNESS_IDS, harnessDescriptor } from "../../../runtime/src/install/harness.js";
 import { evaluateWorktreeWrite, resolveMainRoot } from "../../../runtime/src/parallel/guard.js";
-import { ensureSessionWorktree } from "../../../runtime/src/parallel/service.js";
+import { ensureSessionWorktree, recordSessionOrigin } from "../../../runtime/src/parallel/service.js";
 import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
 import { FileTaskStore } from "../../../runtime/src/task/store.js";
@@ -354,6 +354,15 @@ export async function runHookProcess(argv, io, cliVersion, dependencies = {}) {
                         : async (sessionId) => (await ensureSessionWorktree(dependencies.worktree, { cwd: mainRoot, sessionId })).path);
             }
             : undefined;
+        if (hookEvent === "SessionStart" && config.worktree?.mode === "auto" &&
+            dependencies.worktree !== undefined && typeof parsedInput === "object" && parsedInput !== null) {
+            const fields = parsedInput;
+            const sessionId = harnessId === "agy" ? fields.conversationId : fields.session_id;
+            if (typeof sessionId === "string") {
+                // Advisory: a session that records nothing falls back to HEAD at add time.
+                await recordSessionOrigin(dependencies.worktree, { cwd: root, sessionId }).catch(() => undefined);
+            }
+        }
         const output = await runHookCommand({
             harness: harness,
             event: hookEvent,

package/dist/runtime/src/contracts.js

@@ -1,6 +1,6 @@
 export const CONFIG_SCHEMA_VERSION = 3;
 export const TASK_SCHEMA_VERSION = 1;
-export const EVIDENCE_SCHEMA_VERSION = 2;
+export const EVIDENCE_SCHEMA_VERSION = 3;
 /** @deprecated Use the document-specific schema version constants. */
 export const SCHEMA_VERSION = CONFIG_SCHEMA_VERSION;
 /**

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

@@ -396,6 +396,30 @@ function checkVerificationCommands(config) {
     }
     return check("verification-commands", "PASS", `Required verifiers: ${required.map(({ id }) => id).join(", ")}.`);
 }
+const GHOST_NAME_PATTERN = /[\s\x00-\x1f\x7f\u2000-\u206f\ufeff]/u;
+/** Names doctor treats as unparseable pollution rather than user files. Contentful tracked files never reach this predicate. */
+export function isGhostFileName(name) {
+    return name.length === 0 || GHOST_NAME_PATTERN.test(name);
+}
+/** Root entries worth flagging: untracked regular files that are empty or unparseably named. Warns, never blocks. */
+export function detectGhostFiles(entries) {
+    return entries
+        .filter((entry) => entry.isFile && !entry.tracked && (entry.size === 0 || isGhostFileName(entry.name)))
+        .map((entry) => entry.name)
+        .sort();
+}
+/** Doctor's reading of the repository root: stray pollution is worth a look, not a failure. */
+export function ghostFilesDoctorResult(names) {
+    if (names.length === 0) {
+        return { status: "PASS", message: "No stray files at the repository root." };
+    }
+    return {
+        status: "DEGRADED",
+        message: `Unexpected file(s) at the repository root: ${names.join(", ")}.`,
+        code: "ROOT_GHOST_FILE",
+        remediation: `Inspect and remove them: ${names.map((name) => `rm ${JSON.stringify(name)}`).join("; ")}.`
+    };
+}
 /**
  * What the surrounding host withholds from a reviewer. Reported separately
  * from `review-targets` on purpose: a sandbox that blocks the network makes an
@@ -498,7 +522,13 @@ export async function doctorInstallation(options) {
         checkVerificationCommands(config.config),
         ...(options.probes?.worktrees === undefined
             ? []
-            : [await checkProbe("worktrees", options.probes.worktrees)])
+            : [await checkProbe("worktrees", options.probes.worktrees)]),
+        ...(options.probes?.worktreeBranchLock === undefined
+            ? []
+            : [await checkProbe("worktree-branch-lock", options.probes.worktreeBranchLock)]),
+        ...(options.probes?.rootGhostFiles === undefined
+            ? []
+            : [await checkProbe("root-ghost-files", options.probes.rootGhostFiles)])
     ];
     return {
         checks,

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

@@ -5,7 +5,7 @@ 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";
+import { assertWorktreeName, parseWorktreeListPorcelain, 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;
@@ -191,8 +191,9 @@ function noteText(record, tasks) {
     ].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.
+ * Brings a worktree's reviewed work into its target branch by fast-forward
+ * only, then retires the worktree. Run from the main checkout, which may be on
+ * another branch: then only the target's ref moves.
  */
 export async function finishWorktree(deps, options) {
     const name = assertWorktreeName(options.name);
@@ -207,12 +208,24 @@ export async function finishWorktree(deps, options) {
     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.`);
+        // On the target, the merge rewrites the checkout's files, so its changes
+        // would mix in. Anywhere else only the target's ref moves and the checkout
+        // is never touched.
+        const onTarget = onBranch === record.targetBranch;
+        if (onTarget) {
+            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.");
+            }
+        }
+        else {
+            const listing = await deps.git(mainRoot, ["worktree", "list", "--porcelain"]);
+            const holder = listing.exitCode === 0
+                ? parseWorktreeListPorcelain(listing.stdout).find(({ branch }) => branch === record.targetBranch)
+                : undefined;
+            if (holder !== undefined) {
+                throw finishError("WORKTREE_BRANCH_CHECKED_OUT", `${record.targetBranch} is checked out at ${holder.path}; moving it would desync that checkout. Switch it away or finish from there.`);
+            }
         }
         if ((await collectChangeSurface(worktreeRunner)).paths.length > 0) {
             throw finishError("WORKTREE_DIRTY", `Commit or discard the uncommitted changes in ${record.path} first.`);
@@ -276,8 +289,17 @@ export async function finishWorktree(deps, options) {
         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.");
+        let mergedHead;
+        if (onTarget) {
+            await git(deps, mainRoot, ["merge", "--ff-only", record.branch], "WORKTREE_MERGE_FAILED", `Git could not fast-forward ${record.targetBranch}.`);
+            mergedHead = await git(deps, mainRoot, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
+        }
+        else {
+            // Compare-and-swap on the target's value read above: a target that moved
+            // since fails here instead of being overwritten.
+            mergedHead = await git(deps, mainRoot, ["rev-parse", "--verify", `${record.branch}^{commit}`], "WORKTREE_LOG_FAILED", `Git could not read ${record.branch}.`);
+            await git(deps, mainRoot, ["update-ref", "-m", `agent-ops finish ${record.branch}`, `refs/heads/${record.targetBranch}`, mergedHead, target], "WORKTREE_MERGE_FAILED", `Git could not fast-forward ${record.targetBranch}.`);
+        }
         // The merge happened; everything below is cleanup, reported, never undone.
         const warnings = [];
         const attempt = async (label, step) => {

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

@@ -3,7 +3,7 @@ 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";
+import { assertSessionId, assertWorktreeName, bindSession, insideWorktreeDirectory, parseWorktreeListPorcelain, 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".
@@ -95,6 +95,35 @@ export function worktreeDoctorResult(statuses, now) {
             remediation: "Resume, finish or remove them; see agent-ops worktree list."
         };
 }
+/** Branches checked out in more than one worktree. Scans every worktree: Git's branch lock does not distinguish agent-ops checkouts from foreign ones. */
+export function detectDuplicateBranchCheckouts(porcelain) {
+    const byBranch = new Map();
+    for (const entry of parseWorktreeListPorcelain(porcelain)) {
+        if (entry.branch === null)
+            continue;
+        const paths = byBranch.get(entry.branch) ?? [];
+        paths.push(entry.path);
+        byBranch.set(entry.branch, paths);
+    }
+    return [...byBranch]
+        .filter(([, paths]) => paths.length > 1)
+        .map(([branch, paths]) => ({ branch, paths: [...paths].sort() }))
+        .sort((left, right) => left.branch.localeCompare(right.branch));
+}
+/** Doctor's reading of the branch lock: a duplicated checkout blocks switching back, so it fails. */
+export function branchLockDoctorResult(porcelain) {
+    const duplicates = detectDuplicateBranchCheckouts(porcelain);
+    if (duplicates.length === 0) {
+        return { status: "PASS", message: "No branch is checked out in more than one worktree." };
+    }
+    const detail = duplicates.map(({ branch, paths }) => `${branch} (${paths.join(", ")})`).join("; ");
+    return {
+        status: "FAIL",
+        message: `Branch checked out more than once: ${detail}.`,
+        code: "WORKTREE_BRANCH_LOCKED",
+        remediation: "Run git worktree list; switch the extra checkout to another branch, or remove it (agent-ops worktree remove <name> --force discards that work)."
+    };
+}
 async function requireRecord(mainRoot, name) {
     const record = await readWorktreeRecord(worktreePath(mainRoot, name));
     if (record === null) {

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

@@ -1,10 +1,11 @@
 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 { sha256 } from "../fs/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";
+import { readPrivateFile, withPrivateFileLock, 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
@@ -17,6 +18,7 @@ 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 TARGET_BRANCH = /^[A-Za-z0-9._/-]{1,128}$/u;
 const DEFAULT_SETUP_TIMEOUT_MS = 10 * 60 * 1000;
 function worktreeError(code, message) {
     return new AgentOpsError(code, message);
@@ -61,6 +63,40 @@ export function worktreePath(mainRoot, name) {
 export function insideWorktreeDirectory(mainRoot, path) {
     return path.startsWith(`${join(mainRoot, WORKTREE_DIRECTORY)}${sep}`);
 }
+/**
+ * Parses `git worktree list --porcelain` into path/branch pairs.
+ * Detached checkouts yield a null branch.
+ */
+export function parseWorktreeListPorcelain(output) {
+    const entries = [];
+    let currentPath;
+    let currentBranch;
+    const flush = () => {
+        if (currentPath !== undefined) {
+            entries.push({ path: currentPath, branch: currentBranch ?? null });
+        }
+        currentPath = undefined;
+        currentBranch = undefined;
+    };
+    for (const line of output.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            flush();
+            currentPath = line.slice("worktree ".length).trim();
+        }
+        else if (line.startsWith("branch ")) {
+            const ref = line.slice("branch ".length).trim();
+            currentBranch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+        }
+        else if (line === "detached") {
+            currentBranch = null;
+        }
+        else if (line === "") {
+            flush();
+        }
+    }
+    flush();
+    return entries.filter((entry) => entry.path.length > 0);
+}
 async function exists(path) {
     try {
         await lstat(path);
@@ -186,18 +222,48 @@ export async function removeCheckout(deps, record, force) {
     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`.
+ * Creates `.worktrees/<name>` on `agent-ops/<name>` from `from` and makes it a
+ * working agent-ops checkout for `sessionId`. With neither `from` nor
+ * `targetBranch`, the branch recorded when the session began is both; without
+ * a record, HEAD and its branch. When the main checkout is detached and
+ * nothing is recorded, `targetBranch` names the branch `finish` merges back
+ * into. A branch already checked out in another worktree is rejected before
+ * Git runs, so the failure names the conflicting path.
  */
 export async function addWorktree(deps, options) {
     const name = assertWorktreeName(options.name);
     const sessionId = assertSessionId(options.sessionId);
+    if (options.targetBranch !== undefined && !TARGET_BRANCH.test(options.targetBranch)) {
+        throw worktreeError("WORKTREE_TARGET_INVALID", `Invalid --target-branch ${options.targetBranch}; use 1-128 letters, digits, '.', '_', '/' or '-'.`);
+    }
+    if (options.from !== undefined && options.from.trim() === "") {
+        throw worktreeError("WORKTREE_BASE_INVALID", "Invalid --from: a commit hash, branch or tag is required.");
+    }
     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.");
+    // Without an explicit target or base, the branch the main checkout was on
+    // when the session began, not the one it is on now: the user may have
+    // switched since.
+    const origin = options.targetBranch === undefined && options.from === undefined
+        ? await readSessionOrigin(mainRoot, sessionId) : null;
+    if (origin !== null &&
+        (await deps.git(mainRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${origin}`])).exitCode !== 0) {
+        throw worktreeError("WORKTREE_ORIGIN_MISSING", `The session began on ${origin}, which no longer exists; pass --target-branch to agent-ops worktree add.`);
+    }
+    const headRef = await deps.git(mainRoot, ["symbolic-ref", "--short", "-q", "HEAD"]);
+    const targetBranch = options.targetBranch ?? origin ?? headRef.stdout.trim();
+    if (targetBranch === "") {
+        throw worktreeError("WORKTREE_TARGET_REQUIRED", "The main checkout is detached; pass --target-branch <branch> naming the branch finish merges back into.");
+    }
+    if (!TARGET_BRANCH.test(targetBranch)) {
+        throw worktreeError("WORKTREE_TARGET_INVALID", `Invalid target branch ${targetBranch}; use 1-128 letters, digits, '.', '_', '/' or '-'.`);
+    }
+    const fromRef = options.from ?? (origin === null ? "HEAD" : `refs/heads/${origin}`);
+    const base = await git(deps, mainRoot, ["rev-parse", "--verify", `${fromRef}^{commit}`], options.from === undefined ? "WORKTREE_NO_COMMIT" : "WORKTREE_BASE_INVALID", options.from === undefined
+        ? "The main checkout has no commit to branch from."
+        : `Cannot resolve --from ${options.from} to a commit.`);
     const path = worktreePath(mainRoot, name);
     const branch = `${WORKTREE_BRANCH_PREFIX}${name}`;
     if (await exists(path)) {
@@ -206,6 +272,17 @@ export async function addWorktree(deps, options) {
     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 listing = await deps.git(mainRoot, ["worktree", "list", "--porcelain"]);
+    if (listing.exitCode === 0) {
+        for (const entry of parseWorktreeListPorcelain(listing.stdout)) {
+            if (entry.branch !== targetBranch && entry.branch !== branch)
+                continue;
+            const listed = await realpath(entry.path).catch(() => entry.path);
+            if (listed === mainRoot)
+                continue;
+            throw worktreeError("WORKTREE_BRANCH_CHECKED_OUT", `Branch ${entry.branch} is already checked out at ${entry.path}; switch it back, finish or remove that worktree first (see agent-ops worktree list).`);
+        }
+    }
     const mainConfig = await deps.loadConfig(mainRoot);
     const mainTrust = await deps.trust.status(mainRoot, mainConfig);
     const setupSteps = mainConfig.worktree?.setup ?? [];
@@ -279,3 +356,32 @@ export async function ensureSessionWorktree(deps, options) {
         return existing;
     return (await addWorktree(deps, { cwd: mainRoot, name, sessionId: options.sessionId })).record;
 }
+function sessionOriginPath(mainRoot, sessionId) {
+    return join(mainRoot, ".agent-ops", "tasks", "session-origin", sha256(sessionId));
+}
+/** The branch recorded when `sessionId` began, or null. */
+export async function readSessionOrigin(mainRoot, sessionId) {
+    const value = (await readPrivateFile(sessionOriginPath(mainRoot, sessionId), mainRoot).catch(() => null))?.trim();
+    return value !== undefined && TARGET_BRANCH.test(value) ? value : null;
+}
+/**
+ * Pins the branch the main checkout is on to `sessionId`, first write wins:
+ * SessionStart fires again on resume, compact and clear, by which time the
+ * user may have moved. Nothing is recorded from inside a worktree or on a
+ * detached HEAD, so a later add falls back to reading HEAD itself.
+ */
+export async function recordSessionOrigin(deps, options) {
+    if (!SESSION.test(options.sessionId))
+        return;
+    const { mainRoot, currentRoot } = await resolveCheckouts(deps, options.cwd);
+    if (currentRoot !== mainRoot)
+        return;
+    const branch = (await deps.git(mainRoot, ["symbolic-ref", "--short", "-q", "HEAD"])).stdout.trim();
+    if (!TARGET_BRANCH.test(branch))
+        return;
+    const path = sessionOriginPath(mainRoot, options.sessionId);
+    await withPrivateFileLock(path, mainRoot, async () => {
+        if (await readPrivateFile(path, mainRoot) === null)
+            await writePrivateFile(path, `${branch}\n`, mainRoot);
+    });
+}