@goodtek/vibeops 2.5.2 → 3.1.0

package/dist/lib/git-integration-sync.js

@@ -1,4 +1,5 @@
-import { gitFetchRemote, gitGovernanceOnlyDirty, gitLeftRightCount, gitPullFastForwardOnly, gitRemoteBranchExists, gitRemoteUrl, gitRevParse, gitSwitchToBranch, readGitInfo, restoreGovernanceStashAfterSwitch, stashGovernanceIfBlocking, } from "./git.js";
+import { gitBranchExists, gitFetch, gitGovernanceOnlyDirty, gitLeftRightCount, gitRemoteBranchExists, gitRemoteUrl, gitRevParse, readGitInfo, } from "./git.js";
+import { fastForwardLocalIntegration, logLocalIntegrationUpdate, resolveIntegrationBaseRef, } from "./git-worktree.js";
 import { cyan, dim, log } from "./logger.js";
 function remoteRef(remote, branch) {
     return `${remote}/${branch}`;
@@ -43,7 +44,7 @@ export async function diagnoseIntegrationSync(cwd, remote, integrationBranch) {
                     "git status",
                     `# Blocking (non-governance): ${blocking.join(", ")}${more}`,
                     "git stash push -u -m \"vibeops: before sync\"",
-                    `git checkout ${integrationBranch}`,
+                    `git switch ${integrationBranch}   # or run in the worktree that has it (git worktree list)`,
                     `git pull --ff-only ${remote} ${integrationBranch}`,
                     "git stash pop   # if you stashed",
                     "vibeops task add",
@@ -52,8 +53,20 @@ export async function diagnoseIntegrationSync(cwd, remote, integrationBranch) {
         }
         // Governance-only dirty (.vibeops.json after init, docs, …) — proceed.
     }
-    const localSha = await gitRevParse(cwd, integrationBranch);
     const remoteSha = await gitRevParse(cwd, remoteRef(remote, integrationBranch));
+    const localSha = (await gitBranchExists(cwd, integrationBranch))
+        ? await gitRevParse(cwd, `refs/heads/${integrationBranch}`)
+        : null;
+    if (localSha === null && remoteSha !== null) {
+        // No local integration branch (e.g. a fresh worktree) — task branches start
+        // from the remote-tracking ref, nothing to fast-forward.
+        return {
+            ok: true,
+            kind: "ok",
+            summary: `No local ${integrationBranch} — using ${remote}/${integrationBranch}.`,
+            fixes: [],
+        };
+    }
     if (localSha === null || remoteSha === null) {
         return {
             ok: false,
@@ -61,7 +74,7 @@ export async function diagnoseIntegrationSync(cwd, remote, integrationBranch) {
             summary: `Could not resolve ${integrationBranch} or ${remote}/${integrationBranch}.`,
             fixes: [
                 `git fetch ${remote}`,
-                `git checkout ${integrationBranch}`,
+                `git switch ${integrationBranch}   # or run in the worktree that has it (git worktree list)`,
                 `git pull --ff-only ${remote} ${integrationBranch}`,
             ],
         };
@@ -84,7 +97,7 @@ export async function diagnoseIntegrationSync(cwd, remote, integrationBranch) {
             summary: `Local ${integrationBranch} and ${remote}/${integrationBranch} have diverged (local +${ahead}, remote +${behind}).`,
             fixes: [
                 `git fetch ${remote}`,
-                `git checkout ${integrationBranch}`,
+                `git switch ${integrationBranch}   # or run in the worktree that has it (git worktree list)`,
                 `# Prefer remote (discards local-only commits on ${integrationBranch}):`,
                 `git reset --hard ${remote}/${integrationBranch}`,
                 `# Or keep local commits: git pull --rebase ${remote} ${integrationBranch}`,
@@ -100,7 +113,7 @@ export async function diagnoseIntegrationSync(cwd, remote, integrationBranch) {
             kind: "ahead",
             summary: `Local ${integrationBranch} is ${ahead} commit(s) ahead of ${remote}/${integrationBranch} — fast-forward pull cannot apply.`,
             fixes: [
-                `git checkout ${integrationBranch}`,
+                `git switch ${integrationBranch}   # or run in the worktree that has it (git worktree list)`,
                 `# Push local commits, or reset to remote if they should not exist:`,
                 `git push -u ${remote} ${integrationBranch}`,
                 `# or: git reset --hard ${remote}/${integrationBranch}`,
@@ -139,94 +152,87 @@ export function printIntegrationSyncDiagnosis(d) {
     }
 }
 /**
- * Fetch + ensure local integration can be used as the base for a new task branch.
- * Switches to the integration branch, then `--ff-only` pull when needed. Never force-resets.
- * Governance-only dirt is stashed around switch/pull so post-`init` `.vibeops.json` edits do not block.
+ * Worktree-safe integration preflight (D-006). Never checks out the integration
+ * branch (another worktree may own it) and never force-resets:
+ * 1. `git fetch <remote> <integration>`;
+ * 2. diagnose (app dirt / local ahead / diverged → refuse with fixes);
+ * 3. fast-forward the local integration ref only where safe
+ *    ({@link fastForwardLocalIntegration});
+ * 4. return the base ref for the task branch (`<remote>/<integration>`).
  */
 export async function ensureIntegrationSynced(opts) {
     const { cwd, remote, integrationBranch } = opts;
     const doFetch = opts.fetch !== false;
     if (opts.dryRun === true) {
         const d = await diagnoseIntegrationSync(cwd, remote, integrationBranch);
-        return { ok: d.ok || d.kind === "no_remote_branch", diagnosis: d, pulled: false };
-    }
-    if ((await gitRemoteUrl(cwd, remote)) === null) {
-        const d = await diagnoseIntegrationSync(cwd, remote, integrationBranch);
-        return { ok: true, diagnosis: d, pulled: false };
+        const ok = d.ok || d.kind === "no_remote_branch";
+        return {
+            ok,
+            diagnosis: d,
+            pulled: false,
+            baseRef: ok ? await resolveIntegrationBaseRef(cwd, remote, integrationBranch) : null,
+        };
     }
-    if (doFetch) {
+    if ((await gitRemoteUrl(cwd, remote)) !== null && doFetch) {
         try {
-            await gitFetchRemote(cwd, remote);
+            await gitFetch(cwd, remote, integrationBranch);
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
             log.warn(dim(`git fetch failed (${msg}) — diagnosing with local refs.`));
         }
     }
-    const git = await readGitInfo(cwd);
-    if (git.branch !== integrationBranch) {
-        const switched = await gitSwitchToBranch(cwd, integrationBranch, remote);
-        if (!switched) {
-            return {
-                ok: false,
-                diagnosis: {
-                    ok: false,
-                    kind: "pull_failed",
-                    summary: `Could not switch to integration branch "${integrationBranch}".`,
-                    fixes: [
-                        "git status",
-                        `git checkout ${integrationBranch}`,
-                        `# If checkout fails due to local changes: git stash -u`,
-                        `git pull --ff-only ${remote} ${integrationBranch}`,
-                        "vibeops task add",
-                    ],
-                },
-                pulled: false,
-            };
-        }
-    }
-    let diagnosis = await diagnoseIntegrationSync(cwd, remote, integrationBranch);
+    const diagnosis = await diagnoseIntegrationSync(cwd, remote, integrationBranch);
     if (!diagnosis.ok) {
-        return { ok: false, diagnosis, pulled: false };
+        return { ok: false, diagnosis, pulled: false, baseRef: null };
     }
-    if (diagnosis.kind === "no_remote_branch") {
-        return { ok: true, diagnosis, pulled: false };
+    const baseRef = await resolveIntegrationBaseRef(cwd, remote, integrationBranch);
+    if (baseRef === null) {
+        return {
+            ok: false,
+            diagnosis: {
+                ok: false,
+                kind: "pull_failed",
+                summary: `Integration branch "${integrationBranch}" not found locally or on ${remote}.`,
+                fixes: ["vibeops init   # or create and push the integration branch"],
+            },
+            pulled: false,
+            baseRef: null,
+        };
     }
-    const localSha = await gitRevParse(cwd, integrationBranch);
-    const remoteSha = await gitRevParse(cwd, remoteRef(remote, integrationBranch));
-    if (localSha !== null && remoteSha !== null && localSha === remoteSha) {
-        return { ok: true, diagnosis, pulled: false };
+    if (diagnosis.kind === "no_remote" || diagnosis.kind === "no_remote_branch") {
+        return { ok: true, diagnosis, pulled: false, baseRef };
     }
-    // Stash governance dirt so ff-only pull cannot be blocked by `.vibeops.json` etc.
-    const stashed = await stashGovernanceIfBlocking(cwd);
     try {
-        await gitPullFastForwardOnly(cwd, remote, integrationBranch);
-        diagnosis = {
-            ok: true,
-            kind: "ok",
-            summary: `Pulled latest ${remote}/${integrationBranch} (--ff-only).`,
-            fixes: [],
-        };
-        return { ok: true, diagnosis, pulled: true };
+        const update = await fastForwardLocalIntegration(cwd, remote, integrationBranch);
+        logLocalIntegrationUpdate(update, remote, integrationBranch);
+        if (update.kind === "fast_forwarded") {
+            return {
+                ok: true,
+                diagnosis: {
+                    ok: true,
+                    kind: "ok",
+                    summary: `Fast-forwarded ${integrationBranch} to ${remote}/${integrationBranch}.`,
+                    fixes: [],
+                },
+                pulled: true,
+                baseRef,
+            };
+        }
+        return { ok: true, diagnosis, pulled: false, baseRef };
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        diagnosis = await diagnoseIntegrationSync(cwd, remote, integrationBranch);
-        if (diagnosis.ok) {
-            diagnosis = {
+        return {
+            ok: false,
+            diagnosis: {
                 ok: false,
                 kind: "pull_failed",
-                summary: `git pull --ff-only failed: ${msg}`,
-                fixes: [
-                    `git checkout ${integrationBranch}`,
-                    `git pull --ff-only ${remote} ${integrationBranch}`,
-                    "vibeops task add",
-                ],
-            };
-        }
-        return { ok: false, diagnosis, pulled: false };
-    }
-    finally {
-        await restoreGovernanceStashAfterSwitch(cwd, stashed);
+                summary: `Could not fast-forward ${integrationBranch}: ${msg}`,
+                fixes: [`git merge --ff-only ${remote}/${integrationBranch}   # in the worktree that has ${integrationBranch}`],
+            },
+            pulled: false,
+            baseRef: null,
+        };
     }
 }

package/dist/lib/git-worktree.js

@@ -0,0 +1,214 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { gitBranchExists, gitRemoteBranchExists, gitRemoteUrl, gitRevParse, restoreGovernanceStashAfterSwitch, runGit, stashGovernanceIfBlocking, } from "./git.js";
+import { dim, log } from "./logger.js";
+/** Parse `git worktree list --porcelain` output. */
+export function parseWorktreePorcelain(stdout) {
+    const out = [];
+    for (const block of stdout.split(/\n\s*\n/)) {
+        const lines = block.split("\n").filter((l) => l.length > 0);
+        if (lines.length === 0)
+            continue;
+        let path = null;
+        let head = null;
+        let branch = null;
+        let bare = false;
+        let detached = false;
+        for (const line of lines) {
+            if (line.startsWith("worktree "))
+                path = line.slice("worktree ".length);
+            else if (line.startsWith("HEAD "))
+                head = line.slice("HEAD ".length);
+            else if (line.startsWith("branch ")) {
+                const ref = line.slice("branch ".length);
+                branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+            }
+            else if (line === "bare")
+                bare = true;
+            else if (line === "detached")
+                detached = true;
+        }
+        if (path !== null)
+            out.push({ path, head, branch, bare, detached });
+    }
+    return out;
+}
+export async function listWorktrees(cwd) {
+    const { stdout } = await runGit(cwd, ["worktree", "list", "--porcelain"]);
+    return parseWorktreePorcelain(stdout);
+}
+async function canonical(p) {
+    try {
+        return await realpath(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/** Absolute top-level path of the worktree containing `cwd`. */
+export async function currentWorktreeRoot(cwd) {
+    const { stdout } = await runGit(cwd, ["rev-parse", "--show-toplevel"]);
+    return canonical(stdout.trim());
+}
+/**
+ * Path of another worktree (not the one containing `cwd`) that has `branch`
+ * checked out, or null.
+ */
+export async function branchCheckedOutElsewhere(cwd, branch) {
+    const here = await currentWorktreeRoot(cwd);
+    for (const wt of await listWorktrees(cwd)) {
+        if (wt.branch !== branch)
+            continue;
+        if ((await canonical(wt.path)) === here)
+            continue;
+        return wt.path;
+    }
+    return null;
+}
+/** Branch checked out in the worktree containing `cwd` (null when detached). */
+async function currentBranch(cwd) {
+    try {
+        const { stdout } = await runGit(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+        const b = stdout.trim();
+        return b.length > 0 ? b : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ref new task branches start from: `<remote>/<integration>` when the
+ * remote-tracking ref exists, else the local integration branch (no remote yet).
+ * Null when neither exists.
+ */
+export async function resolveIntegrationBaseRef(cwd, remote, integrationBranch) {
+    if ((await gitRemoteUrl(cwd, remote)) !== null &&
+        (await gitRemoteBranchExists(cwd, remote, integrationBranch))) {
+        return `${remote}/${integrationBranch}`;
+    }
+    if (await gitBranchExists(cwd, integrationBranch))
+        return integrationBranch;
+    return null;
+}
+/**
+ * Fast-forward the local integration branch to `<remote>/<integration>` without
+ * ever forcing and without touching another worktree:
+ * - checked out in this worktree → `git merge --ff-only <remote>/<integration>`;
+ * - otherwise → `git fetch . refs/remotes/<remote>/<integration>:refs/heads/<integration>`. git itself
+ *   refuses a non-fast-forward update and refuses to update a branch checked out
+ *   in any worktree; those refusals are reported (`not_fast_forward` /
+ *   `owned_elsewhere`), not treated as failures. No check-then-update race.
+ * A missing local branch is not created.
+ */
+export async function fastForwardLocalIntegration(cwd, remote, integrationBranch) {
+    const remoteRef = `${remote}/${integrationBranch}`;
+    if (!(await gitRemoteBranchExists(cwd, remote, integrationBranch))) {
+        return { kind: "no_remote_branch" };
+    }
+    if (!(await gitBranchExists(cwd, integrationBranch)))
+        return { kind: "no_local_branch" };
+    if ((await currentBranch(cwd)) === integrationBranch) {
+        const before = await gitRevParse(cwd, `refs/heads/${integrationBranch}`);
+        const remoteSha = await gitRevParse(cwd, `refs/remotes/${remoteRef}`);
+        if (before === remoteSha)
+            return { kind: "up_to_date" };
+        const stashed = await stashGovernanceIfBlocking(cwd);
+        try {
+            await runGit(cwd, ["merge", "--ff-only", remoteRef]);
+        }
+        catch (e) {
+            if (/not possible to fast-forward|diverg|non-fast-forward/i.test(errorText(e))) {
+                return { kind: "not_fast_forward" };
+            }
+            throw e;
+        }
+        finally {
+            await restoreGovernanceStashAfterSwitch(cwd, stashed);
+        }
+        return { kind: "fast_forwarded", where: "here" };
+    }
+    const before = await gitRevParse(cwd, `refs/heads/${integrationBranch}`);
+    try {
+        // Fetch from this repository (`.`) into the local branch: same git safety as
+        // `git fetch <remote> <b>:<b>` (refuses non-fast-forward, refuses a branch
+        // checked out in any worktree) using the remote-tracking ref the caller just
+        // fetched — no second network round-trip.
+        await runGit(cwd, [
+            "fetch",
+            ".",
+            `refs/remotes/${remoteRef}:refs/heads/${integrationBranch}`,
+        ]);
+    }
+    catch (e) {
+        const text = errorText(e);
+        if (/refusing to fetch into branch|checked out at/i.test(text)) {
+            const owner = await branchCheckedOutElsewhere(cwd, integrationBranch);
+            return { kind: "owned_elsewhere", worktree: owner ?? "(another worktree)" };
+        }
+        if (/non-fast-forward|rejected/i.test(text))
+            return { kind: "not_fast_forward" };
+        throw e;
+    }
+    const after = await gitRevParse(cwd, `refs/heads/${integrationBranch}`);
+    return after === before ? { kind: "up_to_date" } : { kind: "fast_forwarded", where: "ref" };
+}
+function errorText(e) {
+    if (e && typeof e === "object") {
+        const o = e;
+        return `${typeof o.stderr === "string" ? o.stderr : ""}\n${typeof o.message === "string" ? o.message : ""}`;
+    }
+    return String(e);
+}
+/** One-line log for {@link fastForwardLocalIntegration} results. */
+export function logLocalIntegrationUpdate(r, remote, integrationBranch) {
+    switch (r.kind) {
+        case "fast_forwarded":
+            log.ok(`Fast-forwarded local ${integrationBranch} to ${remote}/${integrationBranch}`);
+            return;
+        case "owned_elsewhere":
+            log.info(dim(`Local ${integrationBranch} is checked out in worktree ${r.worktree} — left unchanged (update it there).`));
+            return;
+        case "not_fast_forward":
+            log.warn(`Local ${integrationBranch} has commits not on ${remote}/${integrationBranch} — left unchanged (never forced).`);
+            return;
+        default:
+            return;
+    }
+}
+/**
+ * Move HEAD off the task branch so it can be deleted. Switches to the integration
+ * branch when no other worktree has it checked out; otherwise detaches at
+ * `<remote>/<integration>` (or the local integration ref without a remote).
+ */
+export async function leaveTaskBranch(cwd, remote, integrationBranch) {
+    const owner = await branchCheckedOutElsewhere(cwd, integrationBranch);
+    const base = await resolveIntegrationBaseRef(cwd, remote, integrationBranch);
+    if (base === null) {
+        return {
+            ok: false,
+            message: `Integration branch "${integrationBranch}" not found locally or on ${remote}.`,
+        };
+    }
+    const stashed = await stashGovernanceIfBlocking(cwd);
+    try {
+        if (owner === null) {
+            if (await gitBranchExists(cwd, integrationBranch)) {
+                await runGit(cwd, ["switch", integrationBranch]);
+            }
+            else {
+                await runGit(cwd, ["switch", "-c", integrationBranch, "--track", base]);
+            }
+            return { ok: true, on: "integration", ref: integrationBranch };
+        }
+        await runGit(cwd, ["switch", "--detach", base]);
+        log.info(dim(`${integrationBranch} is checked out in worktree ${owner} — detached this worktree at ${base}.`));
+        return { ok: true, on: "detached", ref: base };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { ok: false, message: `Could not leave the task branch: ${msg}` };
+    }
+    finally {
+        await restoreGovernanceStashAfterSwitch(cwd, stashed);
+    }
+}

package/dist/lib/git.js

@@ -4,9 +4,16 @@ import { dim, log } from "./logger.js";
 const exec = promisify(execFile);
 /** Avoid `maxBuffer` errors on large `git commit` / `git add` output. */
 const DEFAULT_GIT_MAX_BUFFER = 64 * 1024 * 1024;
+/**
+ * Environment for every git call: output that VibeOps parses (porcelain, refusal
+ * messages) must not be localized.
+ */
+export function gitEnv() {
+    return { ...process.env, LC_ALL: "C", LANG: "C", LANGUAGE: "C" };
+}
 async function tryGit(cwd, args) {
     try {
-        const { stdout } = await exec("git", args, { cwd });
+        const { stdout } = await exec("git", args, { cwd, env: gitEnv() });
         return { stdout };
     }
     catch {
@@ -16,6 +23,7 @@ async function tryGit(cwd, args) {
 export async function runGit(cwd, args, options = {}) {
     const { stdout, stderr } = await exec("git", args, {
         cwd,
+        env: gitEnv(),
         maxBuffer: options.maxBuffer ?? DEFAULT_GIT_MAX_BUFFER,
     });
     return { stdout, stderr };
@@ -134,69 +142,68 @@ export async function gitCreateBranch(cwd, name, startPoint) {
     await runGit(cwd, args);
 }
 /**
- * When only governance / VibeOps paths are dirty, stash them so `git switch` can proceed.
- * Callers that switch branches should restore with {@link restoreGovernanceStashAfterSwitch}.
+ * When only governance / VibeOps paths are dirty, set aside the TRACKED
+ * governance modifications so `git switch` can proceed. Untracked files are not
+ * stashed — they move with the switch.
+ *
+ * `refs/stash` is shared by every worktree of a repository, so this never uses
+ * `stash push` / `stash pop` (which act on the top entry, possibly another
+ * worktree's). It creates a stash commit (`git stash create`), records it in the
+ * stash list for safety (`git stash store`), and returns its SHA; restore with
+ * {@link restoreGovernanceStashAfterSwitch}, which applies and drops exactly that
+ * entry. Returns null when nothing was set aside.
  */
 export async function stashGovernanceIfBlocking(cwd) {
     const git = await readGitInfo(cwd);
     if (git.dirty !== true)
-        return false;
+        return null;
     const gov = await gitGovernanceOnlyDirty(cwd);
     if (!gov.onlyGovernance || gov.allPaths.length === 0)
-        return false;
-    const entries = parsePorcelain(await gitStatusPorcelain(cwd));
-    const tracked = [];
-    const untracked = [];
-    for (const e of entries) {
-        if (!isGovernanceDocumentationPath(e.path))
-            continue;
-        if (e.untracked)
-            untracked.push(e.path);
-        else
-            tracked.push(e.path);
-    }
-    let didStash = false;
-    if (tracked.length > 0) {
-        await runGit(cwd, [
-            "stash",
-            "push",
-            "-m",
-            "vibeops: governance before branch switch",
-            "--",
-            ...tracked,
-        ]);
-        didStash = true;
-    }
-    if (untracked.length > 0) {
-        try {
-            await runGit(cwd, [
-                "stash",
-                "push",
-                "-u",
-                "-m",
-                "vibeops: governance untracked before branch switch",
-                "--",
-                ...untracked,
-            ]);
-            didStash = true;
-        }
-        catch {
-            // Untracked generated files (e.g. cursor-implement-*.md) may not stash; switch can still proceed.
-        }
-    }
-    return didStash;
+        return null;
+    const tracked = parsePorcelain(await gitStatusPorcelain(cwd))
+        .filter((e) => !e.untracked && isGovernanceDocumentationPath(e.path))
+        .map((e) => e.path);
+    if (tracked.length === 0)
+        return null;
+    const message = "vibeops: governance before branch switch";
+    const { stdout } = await runGit(cwd, ["stash", "create", message]);
+    const sha = stdout.trim();
+    if (sha.length === 0)
+        return null;
+    await runGit(cwd, ["stash", "store", "-q", "-m", message, sha]);
+    await runGit(cwd, ["restore", "--source=HEAD", "--staged", "--worktree", "--", ...tracked]);
+    return sha;
 }
-/** Re-apply governance paths stashed for a branch switch (e.g. new `docs/tasks/*.md`). */
-export async function restoreGovernanceStashAfterSwitch(cwd, didStash) {
-    if (!didStash)
+/**
+ * Re-apply the governance changes set aside by {@link stashGovernanceIfBlocking}
+ * (by SHA) and drop exactly that stash entry — never another worktree's.
+ */
+export async function restoreGovernanceStashAfterSwitch(cwd, stashSha) {
+    if (stashSha === null)
         return;
     try {
-        await runGit(cwd, ["stash", "pop"]);
-        log.info(dim("Restored stashed governance paths on the task branch."));
+        await runGit(cwd, ["stash", "apply", "-q", stashSha]);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message.split("\n")[0] : String(e);
+        log.warn(`Could not restore governance changes (${msg}). They are kept in the stash list: ${dim(`git stash apply ${stashSha}`)}`);
+        return;
+    }
+    try {
+        const { stdout } = await runGit(cwd, ["stash", "list", "--format=%H"]);
+        const index = stdout.split("\n").indexOf(stashSha);
+        if (index >= 0) {
+            const ref = `stash@{${index}}`;
+            // Re-check right before dropping: the list is shared with other worktrees.
+            if ((await gitRevParse(cwd, ref)) === stashSha) {
+                await runGit(cwd, ["stash", "drop", "-q", ref]);
+            }
+        }
+        log.info(dim("Restored governance changes after the branch switch."));
     }
     catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        log.warn(`Could not restore stashed governance files (${msg}). Run ${dim("git stash pop")} manually.`);
+        const msg = e instanceof Error ? e.message.split("\n")[0] : String(e);
+        log.warn(`Restored governance changes; could not drop stash entry ${stashSha} (${msg}).`);
     }
 }
 export async function gitCheckout(cwd, ref) {
@@ -207,12 +214,14 @@ export async function gitCheckout(cwd, ref) {
     await runGit(cwd, ["switch", ref]);
     await restoreGovernanceStashAfterSwitch(cwd, stashed);
 }
-export async function gitCheckoutNewBranch(cwd, name, startPoint) {
+export async function gitCheckoutNewBranch(cwd, name, startPoint, opts = {}) {
     const stashed = await stashGovernanceIfBlocking(cwd);
     if (stashed) {
         log.info(dim("Stashed governance-only changes (.vibeops/, docs/) before branch switch."));
     }
     const args = ["switch", "-c", name];
+    if (opts.noTrack === true)
+        args.push("--no-track");
     if (typeof startPoint === "string" && startPoint.length > 0)
         args.push(startPoint);
     await runGit(cwd, args);