@kylecheng3146/agent-ops 0.3.1 → 0.3.2

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

@@ -86,6 +86,7 @@ export function parseArgs(argv) {
     let versionSeen = false;
     let worktreeName;
     let force = false;
+    let worktree;
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === undefined) {
@@ -229,6 +230,18 @@ export function parseArgs(argv) {
                 }
                 completionGate = true;
                 break;
+            case "--worktree": {
+                if (worktree !== undefined) {
+                    duplicate(token);
+                }
+                const value = readOptionValue(argv, index, token);
+                if (value !== "auto" && value !== "off") {
+                    throw new CliArgumentError("CLI_INVALID_VALUE", `Worktree mode must be auto or off: ${value}`, token);
+                }
+                worktree = value;
+                index += 1;
+                break;
+            }
             case "--dry-run":
                 if (dryRun) {
                     duplicate(token);
@@ -367,6 +380,7 @@ export function parseArgs(argv) {
             dryRun ||
             yes ||
             rerun ||
+            worktree !== undefined ||
             force) {
             throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Only --json may be combined with global help or version.");
         }
@@ -432,6 +446,9 @@ export function parseArgs(argv) {
     if (completionGate !== undefined && command !== "init") {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--completion-gate may be used only with init.");
     }
+    if (worktree !== undefined && command !== "init" && command !== "update") {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--worktree may be used only with init or update.");
+    }
     if (command === "task") {
         if (harness !== undefined ||
             profiles.length > 0 ||
@@ -551,6 +568,7 @@ export function parseArgs(argv) {
         rerun,
         dryRun,
         json,
-        yes
+        yes,
+        ...(worktree === undefined ? {} : { worktree })
     };
 }

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

@@ -348,6 +348,7 @@ else {
                         trustStore: store,
                         calculateTrustBinding: async (config) => await plannedTrustBinding(root, config),
                         confirm: async (plan, trust) => await confirmPlan(formatUpdatePlan(plan, trust)),
+                        promptWorktree: async (message) => await selectYesNo(message, { input: process.stdin, output: process.stdout }, true),
                         ...(updateArgs.targetVersion === undefined
                             ? {}
                             : { targetVersion: updateArgs.targetVersion })

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

@@ -39,6 +39,7 @@ Options:
   --profile <core|advisory|guardrails|loop>  Repeatable
   --review-target <codex|agy|claude>  Repeatable init option; review pair order
   --completion-gate                  Init only: enable the project-loop completion gate
+  --worktree <auto|off>              Init/update: configure session worktree isolation
   --check-auth                        Doctor only: probe selected review targets'
                                       authentication with one real call
   --check-auth-target <target>        Repeatable doctor filter with --check-auth
@@ -75,6 +76,7 @@ Options:
   --profile <core|advisory|guardrails|loop>  Repeatable
   --review-target <codex|agy|claude>   Repeatable, in fallback-chain order
   --completion-gate                    Enable the project-loop completion gate
+  --worktree <auto|off>                Configure session worktree isolation
   --dry-run                            Print the plan without writing
   --json
   --yes
@@ -114,6 +116,7 @@ Options:
   --scope <project|user>
   --harness <all|both|agy|claude|codex|opencode|comma-separated>
   --target-version <version>   Offline-capable update target
+  --worktree <auto|off>        Configure session worktree isolation
   --dry-run
   --json
   --yes

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

@@ -5,6 +5,7 @@ import { okEnvelope } from "../output.js";
 import { formatOperationPlan } from "../plan-output.js";
 import { toPublicInstallPlan } from "../public-plan.js";
 import { formatTrustChange, planTrustGrant } from "./trust.js";
+import { checkWorktreeEnvWarning, detectWorktreeSetup } from "../../../../runtime/src/install/parallel-setup.js";
 export function formatInstallPlan(plan, trust, warnings = []) {
     const hooks = plan.manifest.hooks ?? [];
     const detectedVerification = plan.detectedVerification;
@@ -14,6 +15,13 @@ export function formatInstallPlan(plan, trust, warnings = []) {
             `Scope: ${plan.scope}`,
             `Harness: ${plan.harness}`,
             `Profiles: ${plan.profiles.join(", ")}`,
+            ...(plan.config.worktree === undefined
+                ? []
+                : [
+                    `Worktree: mode=${plan.config.worktree.mode}${plan.config.worktree.setup && plan.config.worktree.setup.length > 0
+                        ? `, setup=${plan.config.worktree.setup.map((s) => `${s.command} ${s.args.join(" ")}`.trim()).join("; ")}`
+                        : ""}`
+                ]),
             ...(plan.scope === "user" && plan.harness.includes("agy")
                 ? ["Notice: .gemini/GEMINI.md is a shared Gemini rule surface."]
                 : []),
@@ -85,6 +93,11 @@ export async function runInitCommand(options) {
         args.profiles.length === 0) {
         throw new AgentOpsError("INIT_CHOICES_REQUIRED", "Init requires complete scope, harness, and profile choices.");
     }
+    const worktreeConfig = args.worktree === "auto"
+        ? { mode: "auto", setup: await detectWorktreeSetup(options.root) }
+        : args.worktree === "off"
+            ? { mode: "off" }
+            : undefined;
     const plan = await createInstallPlan({
         root: options.root,
         scope: args.scope,
@@ -105,7 +118,10 @@ export async function runInitCommand(options) {
             : { reviewTargets: args.reviewTargets }),
         ...(args.completionGate === undefined
             ? {}
-            : { completionGateEnabled: args.completionGate })
+            : { completionGateEnabled: args.completionGate }),
+        ...(worktreeConfig === undefined
+            ? {}
+            : { worktree: worktreeConfig })
     });
     const trust = await trustChange(options, plan);
     // An installation with no verifier looks finished and is not: every task
@@ -121,7 +137,14 @@ export async function runInitCommand(options) {
                     : ` Detection stopped because — ${plan.verificationBlockers.join("; ")}`)
         ]
         : [];
-    const warnings = [...verificationWarnings, ...(plan.harness.includes("agy") && options.agyWarning !== undefined
+    const worktreeEnvWarning = plan.config.worktree?.mode === "auto"
+        ? await checkWorktreeEnvWarning(options.root)
+        : undefined;
+    const worktreeWarnings = worktreeEnvWarning === undefined ? [] : [worktreeEnvWarning];
+    const warnings = [
+        ...verificationWarnings,
+        ...worktreeWarnings,
+        ...(plan.harness.includes("agy") && options.agyWarning !== undefined
             ? (() => {
                 try {
                     const warning = options.agyWarning();
@@ -131,7 +154,8 @@ export async function runInitCommand(options) {
                     return ["agy could not be probed; run `agent-ops doctor` to verify it."];
                 }
             })()
-            : [])];
+            : [])
+    ];
     if (args.dryRun) {
         return okEnvelope("INIT_PLAN_READY", {
             applied: false,

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

@@ -1,3 +1,6 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { detectWorktreeSetup } from "../../../../runtime/src/install/parallel-setup.js";
 import { applyUpdatePlan, createUpdatePlan } from "../../../../runtime/src/install/update.js";
 import { okEnvelope } from "../output.js";
 import { formatOperationPlan } from "../plan-output.js";
@@ -10,6 +13,13 @@ export function formatUpdatePlan(plan, trust) {
         metadata: [
             `Target version: ${plan.targetVersion}`,
             `Harness: ${plan.installation.harness.join(", ")}`,
+            ...(plan.installation.config.worktree === undefined
+                ? []
+                : [
+                    `Worktree: mode=${plan.installation.config.worktree.mode}${plan.installation.config.worktree.setup && plan.installation.config.worktree.setup.length > 0
+                        ? `, setup=${plan.installation.config.worktree.setup.map((s) => `${s.command} ${s.args.join(" ")}`.trim()).join("; ")}`
+                        : ""}`
+                ]),
             ...(trust === undefined ? [] : formatTrustChange(trust)),
             `Schema migrations: ${plan.migrationSteps.length === 0
                 ? "none"
@@ -47,7 +57,40 @@ async function trustChange(options, plan) {
         ? { action: "skipped", reason: "no-verification-commands" }
         : await planTrustGrant(binding, options.trustStore);
 }
+async function existingConfigHasWorktree(root) {
+    try {
+        const content = await readFile(join(root, ".agent-ops", "config.json"), "utf8");
+        const parsed = JSON.parse(content);
+        return parsed.worktree !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
 export async function runUpdateCommand(options) {
+    let worktree;
+    if (options.args.worktree === "auto") {
+        worktree = {
+            mode: "auto",
+            setup: await detectWorktreeSetup(options.root)
+        };
+    }
+    else if (options.args.worktree === "off") {
+        worktree = { mode: "off" };
+    }
+    else if (options.args.worktree === undefined &&
+        options.promptWorktree !== undefined &&
+        options.isTTY &&
+        !options.args.yes &&
+        !(await existingConfigHasWorktree(options.root))) {
+        const shouldEnable = await options.promptWorktree("Enable Git worktree isolation for parallel agent sessions?");
+        if (shouldEnable) {
+            worktree = {
+                mode: "auto",
+                setup: await detectWorktreeSetup(options.root)
+            };
+        }
+    }
     const plan = await createUpdatePlan({
         root: options.root,
         adapters: options.adapters,
@@ -57,9 +100,9 @@ export async function runUpdateCommand(options) {
         ...(options.registry === undefined
             ? {}
             : { registry: options.registry }),
-        ...(options.targetVersion === undefined
+        ...((options.targetVersion ?? options.args.targetVersion) === undefined
             ? {}
-            : { targetVersion: options.targetVersion }),
+            : { targetVersion: options.targetVersion ?? options.args.targetVersion }),
         ...(options.toolkitVersion === undefined
             ? {}
             : { toolkitVersion: options.toolkitVersion }),
@@ -68,7 +111,8 @@ export async function runUpdateCommand(options) {
             : { hookRuntimePath: options.hookRuntimePath }),
         ...((options.hookTargets ?? options.args.hookTargets) === undefined
             ? {}
-            : { hookTargets: options.hookTargets ?? options.args.hookTargets })
+            : { hookTargets: options.hookTargets ?? options.args.hookTargets }),
+        ...(worktree === undefined ? {} : { worktree })
     });
     const trust = await trustChange(options, plan);
     if (options.args.dryRun) {

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

@@ -193,6 +193,20 @@ export async function completeInitChoices(args, io, setup = {}) {
         const reviewTargets = args.reviewTargets ?? (enabled && eligibleReviewChoices.length > 0
             ? await selectOptions("Review targets (multi-select: tried in listed order)", eligibleReviewChoices, selectorIo, REVIEW_TARGET_ORDER.filter((target) => harness.includes(target)), { startEmpty: true })
             : []);
+        const worktree = args.worktree ?? (scope === "project"
+            ? (await selectOption("Enable Git worktree isolation for parallel agent sessions?", [
+                {
+                    label: "yes",
+                    value: "auto",
+                    description: "Recommended. Isolates each agent session in a dedicated worktree."
+                },
+                {
+                    label: "no",
+                    value: "off",
+                    description: "Keep a single shared checkout."
+                }
+            ], selectorIo))
+            : undefined);
         await probeReviewTargets(reviewTargets, setup);
         return {
             ...args,
@@ -200,7 +214,8 @@ export async function completeInitChoices(args, io, setup = {}) {
             harness,
             profiles,
             ...(completionGate ? { completionGate: true } : {}),
-            ...(reviewTargets.length === 0 ? {} : { reviewTargets })
+            ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
+            ...(worktree !== undefined ? { worktree } : {})
         };
     }
     const session = await createPromptSession(io);
@@ -220,13 +235,17 @@ export async function completeInitChoices(args, io, setup = {}) {
             ? selectReviewTargets(await session.question(`Review targets (${defaultReviewTargets.join(",") || "none"}): `), defaultReviewTargets)
             : []);
         await probeReviewTargets(reviewTargets, setup);
+        const worktree = args.worktree ?? (scope === "project"
+            ? (!/^(n|no)$/i.test((await session.question("Enable Git worktree isolation for parallel agent sessions? [Y/n]: ")).trim()) ? "auto" : "off")
+            : undefined);
         return {
             ...args,
             scope,
             harness,
             profiles,
             ...(completionGate ? { completionGate: true } : {}),
-            ...(reviewTargets.length === 0 ? {} : { reviewTargets })
+            ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
+            ...(worktree !== undefined ? { worktree } : {})
         };
     }
     finally {

package/dist/runtime/src/install/parallel-setup.js

@@ -0,0 +1,63 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+const LOCKFILES = [
+    { path: "bun.lock", packageManager: "bun" },
+    { path: "bun.lockb", packageManager: "bun" },
+    { path: "npm-shrinkwrap.json", packageManager: "npm" },
+    { path: "package-lock.json", packageManager: "npm" },
+    { path: "pnpm-lock.yaml", packageManager: "pnpm" },
+    { path: "yarn.lock", packageManager: "yarn" }
+];
+const SETUP_COMMANDS = {
+    npm: ["ci"],
+    pnpm: ["install", "--frozen-lockfile"],
+    yarn: ["install", "--immutable"],
+    bun: ["install", "--frozen-lockfile"]
+};
+function hasErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+async function regularFileExists(filePath) {
+    try {
+        const status = await lstat(filePath);
+        return status.isFile() && !status.isSymbolicLink();
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Detects project lockfiles and proposes safe, deterministic dependency installation
+ * commands for freshly cloned worktrees. Returns an empty array if detection is
+ * ambiguous or unsupported.
+ */
+export async function detectWorktreeSetup(root) {
+    const detected = await Promise.all(LOCKFILES.map(async (def) => (await regularFileExists(join(root, def.path))) ? def.packageManager : null));
+    const managers = [...new Set(detected.filter((m) => m !== null))];
+    if (managers.length !== 1) {
+        return [];
+    }
+    const manager = managers[0];
+    const args = SETUP_COMMANDS[manager];
+    return [{ command: manager, args: [...args] }];
+}
+/**
+ * Returns a warning message if local environment files (.env) are detected
+ * without a .worktreeinclude file to carry them into new worktrees.
+ */
+export async function checkWorktreeEnvWarning(root) {
+    const hasWorktreeInclude = await regularFileExists(join(root, ".worktreeinclude"));
+    if (hasWorktreeInclude) {
+        return undefined;
+    }
+    const envCandidates = [".env", ".env.local"];
+    for (const candidate of envCandidates) {
+        if (await regularFileExists(join(root, candidate))) {
+            return "Local environment files (.env) detected without .worktreeinclude; consider creating .worktreeinclude to copy them to new worktrees.";
+        }
+    }
+    return undefined;
+}

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

@@ -78,7 +78,7 @@ async function detectVerificationCommands(root) {
         blockers: discovery.decisions.map((decision) => `${decision.adapter}: ${decision.message}`)
     };
 }
-function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false) {
+function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false, worktree) {
     // Absent reviewRoles means external review is disabled; an empty selection
     // must therefore omit the field rather than write an empty array.
     const reviewRoles = reviewTargets.length > 0
@@ -88,6 +88,9 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         existing.verification.commands.length > 0
         ? existing.verification
         : { commands: [...detectedCommands] };
+    const effectiveWorktree = worktree !== undefined
+        ? (worktree === null ? undefined : structuredClone(worktree))
+        : (existing?.worktree === undefined ? undefined : structuredClone(existing.worktree));
     return {
         schemaVersion: CONFIG_SCHEMA_VERSION,
         profiles: [...profiles],
@@ -103,12 +106,10 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         pathMappings: existing?.pathMappings ?? [],
         securityExceptions: existing?.securityExceptions ?? [],
         ...(reviewRoles === undefined ? {} : { reviewRoles: [...reviewRoles] }),
-        ...(existing?.worktree === undefined
-            ? {}
-            : { worktree: structuredClone(existing.worktree) })
+        ...(effectiveWorktree === undefined ? {} : { worktree: effectiveWorktree })
     };
 }
-async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = [], completionGateEnabled = false) {
+async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = [], completionGateEnabled = false, worktree) {
     const current = await readCurrentFile(root, CONFIG_PATH);
     const owned = findOwnedArtifact(existingManifest, CONFIG_PATH);
     if (current !== null && owned === undefined) {
@@ -144,7 +145,7 @@ async function planConfig(root, profiles, existingManifest, suppliedConfig, revi
         existingConfig.verification.commands.length === 0
         ? await detectVerificationCommands(root)
         : { commands: [], blockers: [] };
-    const config = buildConfig(profiles, existingConfig, reviewTargets, detected.commands, completionGateEnabled);
+    const config = buildConfig(profiles, existingConfig, reviewTargets, detected.commands, completionGateEnabled, worktree);
     const content = `${JSON.stringify(config, null, 2)}\n`;
     return {
         operation: {
@@ -493,7 +494,7 @@ export async function createInstallPlan(options) {
         : [];
     const operations = [];
     const artifacts = [];
-    const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? [], completionGateEnabled);
+    const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? [], completionGateEnabled, options.worktree);
     operations.push(config.operation);
     artifacts.push(config.record);
     for (const artifact of contribution.artifacts) {

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

@@ -123,7 +123,10 @@ export async function createUpdatePlan(options) {
         existingConfig: {
             value: configPreview.migrated,
             sourceHash: configPreview.sourceHash
-        }
+        },
+        ...(options.worktree === undefined
+            ? {}
+            : { worktree: options.worktree })
     });
     return {
         targetVersion,

package/package.json

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