@goodtek/vibeops 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to VibeOps are documented here.
 
 ## Unreleased
 
+## 3.1.1 - 2026-10-15
+
+### Fixed
+
+- **`task ship` with deletions / renames:** a staged deletion (`D `, e.g. `git rm --cached <path>` + file removed) or a staged rename made ship fail with `fatal: pathspec '<path>' did not match any files`, because every dirty path was passed to `git add`. Ship now parses `git status --porcelain=v1 -z` and runs `git add -A -- :(literal)<path>` only for untracked / unstaged paths; staged changes are committed as they are. Unstaged deletions of tracked files are staged as deletions. Names with spaces or non-ASCII characters (previously quoted by porcelain output) are staged correctly (TASK-022).
+
+## 3.1.0 - 2026-10-03
+
+### Added
+
+- **Worktree-safe lifecycle:** VibeOps never needs to check out the integration branch, so it works when another `git worktree` has `develop` checked out (previously `fatal: 'develop' is already used by worktree at …`).
+  - `task add`: `git fetch <remote> <integration>`, then `git switch -c task/NNN-slug --no-track <remote>/<integration>`.
+  - The local integration branch is fast-forwarded only where safe: in this worktree with `merge --ff-only`; otherwise with `git fetch . refs/remotes/<remote>/<integration>:refs/heads/<integration>` — git itself refuses non-fast-forward updates and branches checked out in any worktree, and that refusal is reported as "left for the owning worktree", not an error.
+  - `task sync`: verifies the merge **before** moving HEAD; leaves the task branch by switching to the integration branch, or `git switch --detach <remote>/<integration>` when another worktree owns it; deletes local + remote task branch.
+  - `task del` / `task ship --new-cycle` (branch recreate) use the same rules; `vibeops pull` refuses to switch (exit 1, names the worktree) instead of failing inside git.
+- **Repository lock:** `task add` (id allocation → TASK file → branch), `task sync`, `task del`, `task ship --new-cycle` branch handling and `vibeops pull` run under an exclusive lock file `<git-common-dir>/vibeops-task.lock` (created atomically with content via temp file + `link`; pid, host, start time, operation, cwd). Another holder → wait up to `lock.waitSeconds` (default 60), then a clear error naming the holder. Stale lock (pid dead on this host, or older than `lock.staleSeconds`, default 600, on any host) → taken over under a breaker file with inode + token re-check, so concurrent takeovers never produce two holders. `.vibeops.json` `lock` is strictly validated. The git common dir must be on a local filesystem.
+- **Collision-free TASK ids:** next id = 1 + max over local `docs/tasks`, `docs/tasks` on `<remote>/<integration>`, every worktree's `docs/tasks`, and VibeOps task branches (local + `git fetch --prune <remote> +refs/heads/task/*:refs/remotes/<remote>/task/*`). A branch counts only in the generated form `task/<NNN>[-<slug>]` (NNN zero-padded ≥ 3 digits, slug = lowercase `a-z0-9` words joined by single hyphens) **and** when its tree contains that TASK file — `task/2026-q4-plan` does not inflate ids. If the remote cannot be fetched, `task add` refuses without creating a TASK file.
+- **Cross-machine id guard:** `task ship` runs `git ls-remote --heads <remote> 'task/*'` right before pushing and refuses when a different task branch with the same TASK number exists on the remote (or when the remote cannot be listed).
+
+### Fixed
+
+- **Shared `refs/stash`:** governance changes were set aside with `stash push` / `stash pop`, which act on the top of the stash list shared by all worktrees — another worktree's entry could be popped and the TASK file lost. Untracked governance files are no longer stashed (they move with the switch); tracked changes are saved with `git stash create` + `git stash store`, re-applied by SHA, and exactly that entry is dropped.
+
+### Changed
+
+- `task sync` checks merge verification before switching branches (a refused sync now leaves HEAD on the task branch).
+- New task branches are created with `--no-track`, so they never inherit `<remote>/<integration>` as upstream; `task ship` sets the upstream on first push as before.
+- Git Context `baseCommit` is recorded as a full SHA (was a 7-character prefix).
+- All git commands run with `LC_ALL=C` / `LANG=C` so parsed output (porcelain, refusal messages) is never localized.
+
 ## 3.0.0 - 2026-10-03
 
 ### Breaking changes

package/README.md

@@ -153,15 +153,53 @@ vibeops llm use auto   # auto | codex-oauth | cursor-agent | openai
 ## Git
 
 - **Init** records branch policy in `.vibeops.json` (`integrationBranch`, `productionBranch`, `host`). Interactive remote setup: ask GitHub/GitLab, create or connect; soft-gate when `gh`/`glab` is missing.
-- **`task add`**: `task/<slug>` from **integration** (e.g. `develop`).
+- **`task add`**: `task/<NNN-slug>` from **`<remote>/<integration>`** (e.g. `origin/develop`), after `git fetch`. See [Worktrees](#worktrees) and [TASK ids](#task-ids).
 - **`task ship`** (state-aware): **no PR** → commit + ship metadata (Status **Shipped**) → push → open MR/PR; **open PR** → commit + push the same branch, CI re-runs, no new PR; **merged PR** → new PR cycle (carries uncommitted work onto the task branch, integrates `develop`, opens a **new** PR). Use `--new-cycle` in non-interactive mode. Commit messages are TASK-id-scoped (`feat(task-001): …`). Refuses when HEAD is not the task branch.
 - **`task merge`**: merge MR/PR into integration (TASK md unchanged) — **only when every check is green** (see [Merge gate](#merge-gate)).
-- **`task sync`**: integration ff-only pull → delete `task/*` branches (TASK md unchanged).
-- **`pull`**: fetch + switch to integration branch + `git pull --ff-only` (one command).
+- **`task sync`**: verify merge → leave the task branch (switch to integration, or detach at `<remote>/<integration>` when another worktree owns it) → fast-forward local integration where safe → delete local + remote `task/*` branch (TASK md unchanged).
+- **`pull`**: fetch + switch to integration branch + `git pull --ff-only` (one command). Refuses (exit 1) when another worktree has the integration branch checked out — run it there.
 - **`task release`**: integration → production PR + merge (skipped on trunk policy).
 - **`status`**: Now / Next card — focus stage, checklist, PR, and the next command to run.
 - No force-push to shared branches.
 
+## Worktrees
+
+VibeOps supports several `git worktree` checkouts of one repo working in parallel. It never needs to check out the integration branch:
+
+- New task branches start from `<remote>/<integration>` (`git switch -c task/NNN-slug --no-track origin/develop`).
+- The local integration branch is fast-forwarded only when safe: in the worktree that has it checked out (`merge --ff-only`), otherwise with `git fetch . refs/remotes/origin/develop:refs/heads/develop`, which git refuses for non-fast-forward updates and for a branch checked out in another worktree — then it is left alone and the log says so (update it in that worktree).
+- `task sync` / `task del` / `task ship --new-cycle` leave the task branch by detaching at `<remote>/<integration>` when the integration branch is checked out elsewhere.
+- Governance changes set aside for a branch switch are restored by stash SHA, never by `stash pop` (the stash list is shared by all worktrees). Untracked files are not stashed.
+- Nothing is ever forced; local integration commits that are not on the remote stop `task add` / `task sync` with fix commands.
+
+### Repository lock
+
+`task add`, `task sync`, `task del`, `task ship --new-cycle` (branch step) and `vibeops pull` take an exclusive lock, `<git-common-dir>/vibeops-task.lock` (shared by all worktrees), recording pid, host, start time, operation and directory. A second command waits, then fails with a message naming the holder.
+
+- The lock file is created atomically with its content (temp file + `link`), so it is never seen half-written.
+- **Stale** = holder on this host whose pid is not running, or a lock older than `staleSeconds` (any host; covers pid reuse). A start time in the future (clock skew) is respected, not stale.
+- Every removal (release or stale takeover) happens under a short breaker file `vibeops-task.lock.break` and only after re-checking the lock's inode and token, so concurrent takeovers of one stale lock never yield two holders.
+- Breaker timings are internal (not in `.vibeops.json`) because the breaker is held for microseconds and only matters after a crash: a breaker older than 30 s is treated as left by a crash; waiting for it is bounded by 60 s (a stale takeover waits at most `waitSeconds`; a release always uses the full 60 s so the lock is not left behind).
+- **The git common dir must be on a local filesystem.** Network filesystems (NFS, SMB, cloud-synced folders) are not supported: their `link` / rename / O_EXCL semantics and clocks are not reliable enough for the lock.
+
+| `.vibeops.json` `lock` key | Default | Allowed | Meaning |
+|---|---|---|---|
+| `waitSeconds` | `60` | integer 0–600 | How long to wait for another holder. |
+| `staleSeconds` | `600` | integer 60–86400 | A lock older than this is stale (any host). On this host a lock is also stale as soon as its pid is no longer running. |
+
+## TASK ids
+
+`task add` picks **1 + the highest TASK number found anywhere** so parallel worktrees and unmerged branches never reuse an id:
+
+1. `docs/tasks` in this worktree (including uncommitted files);
+2. `docs/tasks` on `<remote>/<integration>` (`git ls-tree`);
+3. `docs/tasks` in every worktree (`git worktree list`) — covers task branches whose TASK file is not committed yet;
+4. VibeOps task branches, local and on the remote (`git fetch --prune <remote> '+refs/heads/task/*:refs/remotes/<remote>/task/*'`).
+
+A branch counts only when its name has the **generated form** `task/<NNN>` or `task/<NNN>-<slug>` — NNN is the TASK number zero-padded to at least 3 digits, slug is lowercase `a-z0-9` words joined by single hyphens (exactly what `task add` creates from `TASK-<NNN>-<slug>.md`) — **and** its tree contains `docs/tasks/TASK-<NNN>…md`. Other branches (`task/2026-q4-plan`, `task/task-020-x`) are ignored.
+
+If a configured remote cannot be fetched, `task add` stops without creating a TASK file. Across machines, `task ship` re-checks the remote (`git ls-remote`) right before pushing and refuses if another task branch with the same number already exists there.
+
 ## Merge gate
 
 > **3.0.0 breaking:** a PR/MR with **no checks at all** is refused by default. Repos without CI: set `"merge": {"allowNoChecks": true}` in `.vibeops.json`. Requires **gh ≥ 2.13.0**.

package/dist/commands/pull.js

@@ -2,11 +2,19 @@ import { resolve } from "node:path";
 import { GitConfigError, requireGitConfig } from "../lib/git-config.js";
 import { diagnoseIntegrationSync, printIntegrationSyncDiagnosis, } from "../lib/git-integration-sync.js";
 import { gitFetchRemote, gitPullFastForwardOnly, gitRemoteBranchExists, gitRemoteUrl, gitSwitchToBranch, readGitInfo, } from "../lib/git.js";
+import { branchCheckedOutElsewhere } from "../lib/git-worktree.js";
 import { bold, cyan, dim, log } from "../lib/logger.js";
+import { runUnderTaskLock } from "../lib/task-lock.js";
 /**
  * One-step remote sync: fetch, switch to integration branch, fast-forward pull.
  */
 export async function pullCommand(options = {}) {
+    if (options.dryRun === true)
+        return pullUnlocked(options);
+    // D-006: branch switch / fast-forward are serialized across worktrees.
+    await runUnderTaskLock(resolve(options.cwd ?? process.cwd()), "pull", () => pullUnlocked(options));
+}
+async function pullUnlocked(options) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const dryRun = options.dryRun === true;
     let gitCfg;
@@ -56,6 +64,14 @@ export async function pullCommand(options = {}) {
         log.warn(`git fetch failed (${msg}). Continuing with local refs.`);
     }
     if (needsSwitch) {
+        // Worktree-safe (D-006): git refuses to check out a branch another worktree has.
+        const owner = await branchCheckedOutElsewhere(cwd, integrationBranch);
+        if (owner !== null) {
+            log.error(`${integrationBranch} is checked out in worktree ${owner} — not switching this worktree.`);
+            log.info(dim(`Fetched ${remote}. Update ${integrationBranch} there: vibeops pull --cwd "${owner}"`));
+            process.exitCode = 1;
+            return;
+        }
         const switched = await gitSwitchToBranch(cwd, integrationBranch, remote);
         if (!switched) {
             log.error(`Branch "${integrationBranch}" not found locally or on ${remote}. Push integration first or check the remote URL.`);

package/dist/commands/task-add.js

@@ -9,6 +9,8 @@ import { slugify } from "../lib/slug.js";
 import { fallbackTaskDraft, llmScaffoldTask } from "../lib/task-add-llm.js";
 import { allocateNextTaskNumber, formatTaskId, uniqueTaskPath, } from "../lib/task-scaffold.js";
 import { findBlockingTask, relPath } from "../lib/task-context.js";
+import { allocateTaskId, TaskIdAllocationError } from "../lib/task-id-allocation.js";
+import { readTaskLockConfig, TaskLockConfigError, TaskLockHeldError, withTaskLock, } from "../lib/task-lock.js";
 import { isIncompleteTaskStart, startTaskBranch } from "../lib/task-start.js";
 import { loadActionableTasks, readGitContext } from "../lib/task.js";
 async function loadGitConfigOrNull(root, dryRun) {
@@ -51,6 +53,24 @@ async function finishWithBranch(root, taskId, filePath, gitCfg, opts) {
     log.info(`  Agent: same file — implement`);
     log.info(`  Ship: ${cyan(`vibeops task ship ${taskId}`)}`);
 }
+/**
+ * Run `fn` under the repository task lock (D-006). Lock errors are reported and
+ * end the command with exit code 1.
+ */
+async function underLock(root, lockCfg, fn) {
+    try {
+        return await withTaskLock(root, "task add", fn, lockCfg);
+    }
+    catch (e) {
+        if (e instanceof TaskLockHeldError) {
+            log.error(e.message);
+            log.info(dim("No TASK file was created."));
+            process.exitCode = 1;
+            return "done";
+        }
+        throw e;
+    }
+}
 export async function taskAddCommand(opts = {}) {
     const root = resolve(opts.cwd ?? process.cwd());
     const dryRun = opts.dryRun === true;
@@ -60,76 +80,96 @@ export async function taskAddCommand(opts = {}) {
     const gitCfg = await loadGitConfigOrNull(root, dryRun);
     if (!dryRun && gitCfg === null)
         return;
-    const paths = projectPaths(root);
-    const blocking = await findBlockingTask(paths, root);
-    // Resume: In Progress file exists but task branch / Git Context was never finished.
-    if (blocking !== null && gitCfg !== null) {
-        const incomplete = await isIncompleteTaskStart(root, blocking.filePath);
-        if (incomplete) {
-            log.warn(`${yellow("Incomplete")} — ${bold(blocking.id)} exists but the task branch was not created.`);
-            log.info(`  ${dim("file")}   ${relPath(root, blocking.filePath)}`);
-            log.info(dim("Resuming branch setup (will not create a new TASK)…"));
-            if (!dryRun) {
-                const synced = await ensureIntegrationSynced({
-                    cwd: root,
-                    remote: gitCfg.remote,
-                    integrationBranch: gitCfg.integrationBranch,
-                    fetch: true,
-                });
-                if (!synced.ok) {
-                    printIntegrationSyncDiagnosis(synced.diagnosis);
-                    process.exitCode = 1;
-                    return;
-                }
-                if (synced.pulled)
-                    log.info(dim(synced.diagnosis.summary));
-            }
-            await finishWithBranch(root, blocking.id, blocking.filePath, gitCfg, {
-                dryRun,
-                skipIntegrationPull: true,
-            });
+    let lockCfg;
+    try {
+        lockCfg = await readTaskLockConfig(root);
+    }
+    catch (e) {
+        if (e instanceof TaskLockConfigError) {
+            log.error(e.message);
+            process.exitCode = 1;
             return;
         }
-        const ctx = await readGitContext(blocking.filePath);
-        log.warn(`${yellow("Blocked")} — ${bold(blocking.id)} is still open (${blocking.title || "no title"}).`);
-        if (ctx) {
-            log.info(`  ${dim("branch")}  ${ctx.taskBranch}`);
-        }
-        log.info(`  ${dim("file")}   ${relPath(root, blocking.filePath)}`);
-        log.blank();
-        log.info(`Finish it first: ${cyan(`vibeops task ship ${blocking.id}`)}.`);
-        log.info(`Then run ${cyan("vibeops task add")} again.`);
-        process.exitCode = 1;
-        return;
+        throw e;
     }
-    // Preflight: sync integration BEFORE writing a new TASK file (avoids half-created TASKs).
-    if (!dryRun && gitCfg !== null) {
-        log.step("Checking integration branch…");
-        const synced = await ensureIntegrationSynced({
-            cwd: root,
-            remote: gitCfg.remote,
-            integrationBranch: gitCfg.integrationBranch,
-            fetch: true,
-        });
-        if (!synced.ok) {
-            printIntegrationSyncDiagnosis(synced.diagnosis);
+    const paths = projectPaths(root);
+    // Phase 1 (locked): resume an incomplete add, or preflight the integration branch.
+    const phase1 = async () => {
+        const blocking = await findBlockingTask(paths, root);
+        // Resume: In Progress file exists but task branch / Git Context was never finished.
+        if (blocking !== null && gitCfg !== null) {
+            const incomplete = await isIncompleteTaskStart(root, blocking.filePath);
+            if (incomplete) {
+                log.warn(`${yellow("Incomplete")} — ${bold(blocking.id)} exists but the task branch was not created.`);
+                log.info(`  ${dim("file")}   ${relPath(root, blocking.filePath)}`);
+                log.info(dim("Resuming branch setup (will not create a new TASK)…"));
+                if (!dryRun) {
+                    const synced = await ensureIntegrationSynced({
+                        cwd: root,
+                        remote: gitCfg.remote,
+                        integrationBranch: gitCfg.integrationBranch,
+                        fetch: true,
+                    });
+                    if (!synced.ok) {
+                        printIntegrationSyncDiagnosis(synced.diagnosis);
+                        process.exitCode = 1;
+                        return "done";
+                    }
+                    if (synced.pulled)
+                        log.info(dim(synced.diagnosis.summary));
+                }
+                await finishWithBranch(root, blocking.id, blocking.filePath, gitCfg, {
+                    dryRun,
+                    skipIntegrationPull: true,
+                });
+                return "done";
+            }
+            const ctx = await readGitContext(blocking.filePath);
+            log.warn(`${yellow("Blocked")} — ${bold(blocking.id)} is still open (${blocking.title || "no title"}).`);
+            if (ctx) {
+                log.info(`  ${dim("branch")}  ${ctx.taskBranch}`);
+            }
+            log.info(`  ${dim("file")}   ${relPath(root, blocking.filePath)}`);
             log.blank();
-            log.info(dim("No TASK file was created. Fix the integration branch, then rerun task add."));
+            log.info(`Finish it first: ${cyan(`vibeops task ship ${blocking.id}`)}.`);
+            log.info(`Then run ${cyan("vibeops task add")} again.`);
             process.exitCode = 1;
-            return;
-        }
-        if (synced.pulled) {
-            log.ok(synced.diagnosis.summary);
-        }
-        else if (synced.diagnosis.kind === "no_remote_branch" ||
-            synced.diagnosis.kind === "no_remote") {
-            log.info(dim(synced.diagnosis.summary));
+            return "done";
         }
-        else {
-            log.info(dim(`Integration ${gitCfg.integrationBranch} is ready.`));
+        // Preflight: sync integration BEFORE writing a new TASK file (avoids half-created TASKs).
+        if (!dryRun && gitCfg !== null) {
+            log.step("Checking integration branch…");
+            const synced = await ensureIntegrationSynced({
+                cwd: root,
+                remote: gitCfg.remote,
+                integrationBranch: gitCfg.integrationBranch,
+                fetch: true,
+            });
+            if (!synced.ok) {
+                printIntegrationSyncDiagnosis(synced.diagnosis);
+                log.blank();
+                log.info(dim("No TASK file was created. Fix the integration branch, then rerun task add."));
+                process.exitCode = 1;
+                return "done";
+            }
+            if (synced.pulled) {
+                log.ok(synced.diagnosis.summary);
+            }
+            else if (synced.diagnosis.kind === "no_remote_branch" ||
+                synced.diagnosis.kind === "no_remote") {
+                log.info(dim(synced.diagnosis.summary));
+            }
+            else {
+                log.info(dim(`Integration ${gitCfg.integrationBranch} is ready.`));
+            }
+            log.blank();
         }
-        log.blank();
-    }
+        return "continue";
+    };
+    if ((dryRun ? await phase1() : await underLock(root, lockCfg, phase1)) === "done")
+        return;
+    // Phase 2 (unlocked): ask + draft. The draft uses a provisional id; the final id
+    // is allocated under the lock in phase 3 so a slow prompt / LLM never holds it.
     const ideaDefault = "New work slice";
     const idea = await askInput({
         message: "What are you doing now? (short)",
@@ -137,58 +177,96 @@ export async function taskAddCommand(opts = {}) {
         default: opts.idea?.trim() || ideaDefault,
         required: true,
     });
-    const tasks = await loadActionableTasks(paths.docsTasks);
-    const taskId = formatTaskId(allocateNextTaskNumber(tasks));
+    const provisionalId = formatTaskId(allocateNextTaskNumber(await loadActionableTasks(paths.docsTasks)));
     let title;
     let slug;
-    let markdown;
+    let draftMarkdown;
     if (dryRun || nonInteractive) {
-        const fb = fallbackTaskDraft(taskId, idea);
+        const fb = fallbackTaskDraft(provisionalId, idea);
         title = fb.title;
         slug = fb.slug;
-        markdown = fb.markdown;
+        draftMarkdown = fb.markdown;
     }
     else {
-        const llm = await llmScaffoldTask({ cwd: root, taskId, idea });
+        const llm = await llmScaffoldTask({ cwd: root, taskId: provisionalId, idea });
         if (llm !== null) {
             title = llm.title;
             slug = llm.slug;
-            markdown = llm.markdown;
+            draftMarkdown = llm.markdown;
             log.skip(`Scaffold via ${llm.provider}`);
         }
         else {
             log.warn("LLM unavailable — using minimal TASK template.");
             log.info(dim(`  Run ${cyan("vibeops llm connect")} to set up Codex, Cursor Agent CLI, or OpenAI.`));
-            const fb = fallbackTaskDraft(taskId, idea);
+            const fb = fallbackTaskDraft(provisionalId, idea);
             title = fb.title;
             slug = fb.slug;
-            markdown = fb.markdown;
+            draftMarkdown = fb.markdown;
         }
     }
-    const { filePath } = uniqueTaskPath(paths.docsTasks, taskId, slugify(slug || title), tasks.map((t) => t.filePath));
-    const relFile = relPath(root, filePath);
-    const integration = gitCfg?.integrationBranch ?? "integration";
-    if (dryRun) {
-        log.info(`[dry-run] Would create ${bold(taskId)} → ${cyan(relFile)}`);
-        log.info(dim(`  branch task/${slugify(slug || title).replace(/^(\d+)-/, "$1-")} from ${integration}`));
-        if (gitCfg) {
-            await startTaskBranch({
-                cwd: root,
-                taskFile: filePath,
-                integrationBranch: gitCfg.integrationBranch,
-                remote: gitCfg.remote,
-                dryRun: true,
-            });
+    // Phase 3 (locked): allocate id → write TASK file → create branch.
+    const phase3 = async () => {
+        const tasks = await loadActionableTasks(paths.docsTasks);
+        let taskNumber = allocateNextTaskNumber(tasks);
+        if (gitCfg !== null) {
+            // D-006: ids are unique across the integration branch, every worktree and
+            // every local / remote VibeOps task branch — not just this worktree's docs/tasks.
+            try {
+                const alloc = await allocateTaskId({
+                    cwd: root,
+                    tasksDir: paths.docsTasks,
+                    remote: gitCfg.remote,
+                    integrationBranch: gitCfg.integrationBranch,
+                    fetchRemote: !dryRun,
+                });
+                taskNumber = Math.max(taskNumber, alloc.next);
+            }
+            catch (e) {
+                if (e instanceof TaskIdAllocationError) {
+                    log.error(e.message);
+                    log.info(dim("No TASK file was created."));
+                    process.exitCode = 1;
+                    return "done";
+                }
+                if (!dryRun)
+                    throw e;
+                // dry-run outside a git repo: local docs/tasks only.
+            }
         }
-        return;
-    }
-    if (await pathExists(filePath)) {
-        throw new Error(`TASK file already exists: ${relFile}`);
-    }
-    await writeText(filePath, markdown);
-    log.ok(`Created ${bold(taskId)} → ${cyan(relFile)}`);
-    await finishWithBranch(root, taskId, filePath, gitCfg, {
-        dryRun: false,
-        skipIntegrationPull: true,
-    });
+        const taskId = formatTaskId(taskNumber);
+        const markdown = taskId === provisionalId
+            ? draftMarkdown
+            : draftMarkdown.replace(new RegExp(`\\b${provisionalId}\\b`, "g"), taskId);
+        const { filePath } = uniqueTaskPath(paths.docsTasks, taskId, slugify(slug || title), tasks.map((t) => t.filePath));
+        const relFile = relPath(root, filePath);
+        const integration = gitCfg?.integrationBranch ?? "integration";
+        if (dryRun) {
+            log.info(`[dry-run] Would create ${bold(taskId)} → ${cyan(relFile)}`);
+            log.info(dim(`  branch task/${slugify(slug || title).replace(/^(\d+)-/, "$1-")} from ${gitCfg?.remote ?? "origin"}/${integration}`));
+            if (gitCfg) {
+                await startTaskBranch({
+                    cwd: root,
+                    taskFile: filePath,
+                    integrationBranch: gitCfg.integrationBranch,
+                    remote: gitCfg.remote,
+                    dryRun: true,
+                });
+            }
+            return "done";
+        }
+        if (await pathExists(filePath)) {
+            throw new Error(`TASK file already exists: ${relFile}`);
+        }
+        await writeText(filePath, markdown);
+        log.ok(`Created ${bold(taskId)} → ${cyan(relFile)}`);
+        await finishWithBranch(root, taskId, filePath, gitCfg, {
+            dryRun: false,
+            skipIntegrationPull: true,
+        });
+        return "done";
+    };
+    if (dryRun)
+        await phase3();
+    else
+        await underLock(root, lockCfg, phase3);
 }

package/dist/commands/task-del.js

@@ -4,7 +4,14 @@ import { projectPaths } from "../lib/paths.js";
 import { relPath } from "../lib/task-context.js";
 import { assertTaskDeletable, assertWorkingTreeForDel, closeOpenTaskMergeRequestIfNeeded, deleteTaskBranches, deleteTaskMarkdown, loadGitConfigForDel, resolveDelTarget, taskDelNotFoundMessage, validateTaskBranchForDel, } from "../lib/task-del.js";
 import { readGitContext, statusDisplay } from "../lib/task.js";
+import { runUnderTaskLock } from "../lib/task-lock.js";
 export async function taskDelCommand(taskRef, options = {}) {
+    if (options.dryRun === true)
+        return taskDelUnlocked(taskRef, options);
+    // D-006: branch switch / stash / delete are serialized across worktrees.
+    await runUnderTaskLock(resolve(options.cwd ?? process.cwd()), "task del", () => taskDelUnlocked(taskRef, options));
+}
+async function taskDelUnlocked(taskRef, options) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const dryRun = options.dryRun === true;
     const paths = projectPaths(cwd);

package/dist/commands/task-ship.js

@@ -15,6 +15,7 @@ import { applyTaskShipMemory, fallbackResultSections, llmCompleteTaskShip, write
 import { detectShipPrState, prRefLabel, resolveShipAction, } from "../lib/task-ship-state.js";
 import { finishTaskWithPullRequest } from "../lib/task-push-pr.js";
 import { hasNonEmptySection, parseTaskFilename, readGitContext, readTaskFile, updateInlineStatus, } from "../lib/task.js";
+import { assertTaskIdFreeOnRemote } from "../lib/task-id-allocation.js";
 function describePushFailure(message) {
     const lower = message.toLowerCase();
     if (lower.includes("protected") ||
@@ -245,6 +246,12 @@ async function runUpdateOpenPr(ctx) {
         log.info(`Nothing to ship (working tree clean, PR ${prRefLabel(prCtx.number)} up to date).`);
         return;
     }
+    const idFree = await assertTaskIdFreeOnRemote(cwd, remote, gitCtx.taskBranch);
+    if (!idFree.ok) {
+        log.error(idFree.message);
+        process.exitCode = 1;
+        return;
+    }
     try {
         await gitPush(cwd, remote, gitCtx.taskBranch, false);
         log.ok(`Pushed ${gitCtx.taskBranch} → ${remote}`);

package/dist/commands/task-sync.js

@@ -1,11 +1,13 @@
 import { resolve } from "node:path";
 import { GitConfigError, requireGitConfig } from "../lib/git-config.js";
 import { detectGitHost } from "../lib/git-host.js";
-import { gitBranchExists, gitDeleteBranch, gitDeleteRemoteBranch, gitFetchRemote, gitPullFastForwardOnly, gitRemoteBranchExists, gitRemoteUrl, gitSwitchToBranch, readGitInfo, } from "../lib/git.js";
+import { gitBranchExists, gitDeleteBranch, gitDeleteRemoteBranch, gitFetchRemote, gitRemoteBranchExists, gitRemoteUrl, readGitInfo, } from "../lib/git.js";
+import { branchCheckedOutElsewhere, fastForwardLocalIntegration, leaveTaskBranch, logLocalIntegrationUpdate, } from "../lib/git-worktree.js";
 import { bold, cyan, dim, log } from "../lib/logger.js";
 import { projectPaths } from "../lib/paths.js";
 import { taskNotFoundMessage } from "../lib/resolve-task.js";
 import { relPath } from "../lib/task-context.js";
+import { runUnderTaskLock } from "../lib/task-lock.js";
 import { resolveLifecycleTarget } from "../lib/task-lifecycle-target.js";
 import { checkTaskSyncReady } from "../lib/task-sync-guard.js";
 import { readTaskFile } from "../lib/task.js";
@@ -13,6 +15,13 @@ function isProtectedBranch(name, integration, production) {
     return name === integration || name === production || name === "main" || name === "master";
 }
 export async function taskSyncCommand(taskRef, options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    if (options.dryRun === true)
+        return taskSyncUnlocked(taskRef, options);
+    // D-006: branch switch / stash / delete are serialized across worktrees.
+    await runUnderTaskLock(cwd, "task sync", () => taskSyncUnlocked(taskRef, options));
+}
+async function taskSyncUnlocked(taskRef, options) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const dryRun = options.dryRun === true;
     const paths = projectPaths(cwd);
@@ -57,10 +66,20 @@ export async function taskSyncCommand(taskRef, options = {}) {
         if (meta.status === "shipped" && options.force !== true) {
             log.info(dim("Would verify MR is merged and integration branch contains task commits before cleanup."));
         }
+        const owner = (await readGitInfo(cwd)).isRepo
+            ? await branchCheckedOutElsewhere(cwd, integrationBranch)
+            : null;
         log.info(bold("dry-run — would:"));
         log.info(`  · git fetch ${remote} --prune`);
-        log.info(`  · git switch ${integrationBranch}`);
-        log.info(`  · git pull --ff-only ${remote} ${integrationBranch}`);
+        log.info(`  · verify the MR is merged (${remote}/${integrationBranch} contains the task commits)`);
+        if (owner === null) {
+            log.info(`  · if on ${taskBranch}: git switch ${integrationBranch}`);
+            log.info(`  · fast-forward local ${integrationBranch} to ${remote}/${integrationBranch} (--ff-only)`);
+        }
+        else {
+            log.info(`  · if on ${taskBranch}: git switch --detach ${remote}/${integrationBranch}`);
+            log.info(dim(`  · ${integrationBranch} is checked out in worktree ${owner} — left unchanged`));
+        }
         log.info(`  · git branch -D ${taskBranch}`);
         if (options.noRemoteDelete !== true) {
             log.info(`  · git push ${remote} --delete ${taskBranch} (if exists)`);
@@ -76,9 +95,6 @@ export async function taskSyncCommand(taskRef, options = {}) {
         process.exitCode = 1;
         return;
     }
-    if (git.branch === taskBranch) {
-        log.info(dim(`On ${taskBranch} — switching to ${integrationBranch} first.`));
-    }
     try {
         await gitFetchRemote(cwd, remote);
         log.ok(`Fetched ${remote} (--prune)`);
@@ -87,32 +103,11 @@ export async function taskSyncCommand(taskRef, options = {}) {
         const msg = e instanceof Error ? e.message : String(e);
         log.warn(`git fetch failed (${msg}). Continuing with local refs.`);
     }
-    const switched = await gitSwitchToBranch(cwd, integrationBranch, remote);
-    if (!switched) {
-        log.error(`Integration branch "${integrationBranch}" not found locally or on ${remote}.`);
-        process.exitCode = 1;
-        return;
-    }
-    log.ok(`On ${integrationBranch}`);
-    if (await gitRemoteBranchExists(cwd, remote, integrationBranch)) {
-        try {
-            await gitPullFastForwardOnly(cwd, remote, integrationBranch);
-            log.ok(`Up to date with ${remote}/${integrationBranch} (--ff-only)`);
-        }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            log.error(`Could not fast-forward ${integrationBranch}: ${msg}. Resolve locally, then rerun.`);
-            process.exitCode = 1;
-            return;
-        }
-    }
-    else {
-        log.warn(`No ${remote}/${integrationBranch} — skipped pull.`);
-    }
     const remoteUrl = await gitRemoteUrl(cwd, remote);
     const host = remoteUrl !== null && detectGitHost(remoteUrl) !== null
         ? detectGitHost(remoteUrl)
         : gitCfg.host;
+    // Verify the merge BEFORE moving HEAD or touching any branch.
     const syncGuard = await checkTaskSyncReady({
         cwd,
         taskFile,
@@ -131,6 +126,43 @@ export async function taskSyncCommand(taskRef, options = {}) {
         return;
     }
     log.ok(`Ready to sync — ${integrationBranch} contains the task commits.`);
+    // Worktree-safe (D-006): leave the task branch without requiring the
+    // integration branch when another worktree has it checked out.
+    if (git.branch === taskBranch) {
+        const left = await leaveTaskBranch(cwd, remote, integrationBranch);
+        if (!left.ok) {
+            log.error(left.message);
+            process.exitCode = 1;
+            return;
+        }
+        log.ok(left.on === "integration" ? `On ${integrationBranch}` : `Detached at ${left.ref}`);
+    }
+    if (await gitRemoteBranchExists(cwd, remote, integrationBranch)) {
+        try {
+            const update = await fastForwardLocalIntegration(cwd, remote, integrationBranch);
+            if (update.kind === "up_to_date") {
+                log.ok(`Local ${integrationBranch} is up to date with ${remote}/${integrationBranch}`);
+            }
+            else if (update.kind === "not_fast_forward") {
+                // Same outcome as the former `git pull --ff-only` failure: stop before cleanup.
+                log.error(`Local ${integrationBranch} has commits not on ${remote}/${integrationBranch} — cannot fast-forward (never forced). Push or reset it, then rerun.`);
+                process.exitCode = 1;
+                return;
+            }
+            else {
+                logLocalIntegrationUpdate(update, remote, integrationBranch);
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            log.error(`Could not fast-forward ${integrationBranch}: ${msg}. Resolve locally, then rerun.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else {
+        log.warn(`No ${remote}/${integrationBranch} — skipped fast-forward.`);
+    }
     if (await gitBranchExists(cwd, taskBranch)) {
         try {
             // Guard verified integration contains the work — squash merges leave task/* SHAs