forgedock 1.17.0 → 1.18.0

package/bin/stats/stats.test.mjs

@@ -93,6 +93,27 @@ describe("GitHub-only report (fresh machine)", () => {
     assert.equal(runs[0].finished, true);
     assert.equal(runs[0].phases.review.cr, 500000);
   });
+  const rec = (run, ts, event, x = {}) => ({ event, repo: "o/r", issue: 500, run, ts, eid: run + ts + event, ...x });
+  it("collapses a retried issue (two run ids) to the latest run", () => {
+    const runs = runsFromRecords([
+      rec("r_500_1", "2026-01-01T00:00:00Z", "phase_attempt", { phase: "build", cache_read_tokens: 2000000 }),
+      rec("r_500_1", "2026-01-01T00:01:00Z", "run_terminal", { reason: "engine-error" }),
+      rec("r_500_2", "2026-01-02T00:00:00Z", "phase_attempt", { phase: "build", cache_read_tokens: 1000000 }),
+      rec("r_500_2", "2026-01-02T00:01:00Z", "run_terminal", { reason: "merged" }),
+    ]);
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].reason, "merged");
+    assert.equal(runs[0].phases.build.cr, 1000000);
+  });
+  it("lets an unfinished latest run win over an earlier finished retried run", () => {
+    const runs = runsFromRecords([
+      rec("r_500_1", "2026-01-01T00:00:00Z", "phase_attempt", { phase: "build", cache_read_tokens: 2000000 }),
+      rec("r_500_1", "2026-01-01T00:01:00Z", "run_terminal", { reason: "merged" }),
+      rec("r_500_2", "2026-01-02T00:00:00Z", "phase_attempt", { phase: "build", cache_read_tokens: 1000000 }),
+    ]);
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].finished, false);
+  });
 });
 
 describe("local runs, joins, version delta and low-n", () => {
@@ -181,7 +202,7 @@ describe("cache", () => {
     const b = fakeGh();
     const second = fetchGithubRecords({ repo: "o/r", gh: b.gh, env });
     assert.equal(second.fromCache, true);
-    assert.match(b.calls[0], /since=2026-10-06T13:00:00Z/);
+    assert.match(b.calls[0], /since=2026-10-06T12:55:00Z/); // watermark minus the 5 minute overlap window
     assert.deepEqual(second.records.map((r) => r.eid).sort(), first.records.map((r) => r.eid).sort());
     // corrupt cache -> treated as empty -> same result from a full fetch
     writeFileSync(join(cacheDir("o/r", env), "cache.json"), "{not json");
@@ -195,6 +216,73 @@ describe("cache", () => {
     assert.ok(!d.calls[0].includes("since="));
     assert.equal(toModel("o/r", third).issues.length, 5);
   });
+  it("saves a partial checkpoint on a mid-crawl failure and the next run resumes from it", () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-partial") };
+    const ok = fakeGh();
+    const full = fetchGithubRecords({ repo: "o/r", gh: ok.gh, env: { ...ENV }, useCache: false });
+    const withComments = full.items.filter((i) => ok.calls.some((c) => c.includes(`/issues/${i.number}/comments`)));
+    assert.ok(withComments.length >= 2, "fixture needs at least two items with comments");
+    let commentCalls = 0;
+    // The real API honours sort=updated&direction=asc, which the watermark resume relies on; the fixture is unsorted.
+    const asc = (gh) => (args) => {
+      const out = gh(args);
+      return args.some((a) => /\/issues\?/.test(a)) ? JSON.stringify(JSON.parse(out).sort((x, y) => x.updated_at.localeCompare(y.updated_at))) : out;
+    };
+    const flaky = asc((args) => {
+      if (args[args.length - 1].endsWith("/comments") && ++commentCalls === 2) throw new Error("rate limited");
+      return ok.gh(args);
+    });
+    assert.throws(() => fetchGithubRecords({ repo: "o/r", gh: flaky, env }), /rate limited/);
+    const saved = JSON.parse(readFileSync(join(cacheDir("o/r", env), "cache.json"), "utf8"));
+    assert.ok(saved.watermark, "partial watermark persisted");
+    assert.ok(Object.keys(saved.items).length > 0 && Object.keys(saved.items).length < full.items.length);
+    const b = fakeGh();
+    const resumed = fetchGithubRecords({ repo: "o/r", gh: asc(b.gh), env });
+    assert.equal(resumed.fromCache, true);
+    assert.match(b.calls[0], /since=/);
+    assert.deepEqual(resumed.records.map((r) => r.eid).sort(), full.records.map((r) => r.eid).sort());
+  });
+  it("never skips an item updated mid-crawl (keyset crawl, not page-number pagination)", () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-midcrawl") };
+    const ts = (n) => new Date(Date.UTC(2026, 9, 1) + n * 60000).toISOString().replace(/\.\d{3}Z$/, "Z");
+    const store = Array.from({ length: 250 }, (_, i) => ({ number: i + 1, updated_at: ts(i + 1), created_at: ts(0), state: "open", comments: 0, labels: [], user: { type: "Bot" } }));
+    let listCalls = 0;
+    let maxUpdated = 250;
+    // Page-aware fake of the real API: asc by updated_at, honours since (inclusive), per_page and page. After the first
+    // listing call an already-served item is bumped, which moves it to the end of the ordering.
+    const gh = (args) => {
+      const path = args.find((a) => a.startsWith("repos/"));
+      const q = new URLSearchParams(path.split("?")[1]);
+      listCalls++;
+      const since = q.get("since");
+      const sorted = store.filter((i) => !since || i.updated_at >= since).sort((a, b) => a.updated_at.localeCompare(b.updated_at) || a.number - b.number);
+      const per = Number(q.get("per_page")), page = Number(q.get("page") ?? 1);
+      const out = JSON.stringify(sorted.slice((page - 1) * per, page * per));
+      if (listCalls === 1) store[4].updated_at = ts(++maxUpdated);
+      return out;
+    };
+    const first = fetchGithubRecords({ repo: "o/r", gh, env });
+    assert.equal(first.items.length, 250, "every item is cached after the crawl, none skipped by the shift");
+    assert.equal(new Set(first.items.map((i) => i.number)).size, 250);
+    // The bumped item moved past the crawl cursor, so the next incremental run (and its overlap window) still sees it.
+    store[9].updated_at = ts(++maxUpdated); // another item updated after the first run
+    const second = fetchGithubRecords({ repo: "o/r", gh, env });
+    assert.equal(second.fromCache, true);
+    assert.equal(second.items.length, 250);
+    assert.equal(second.items.find((i) => i.number === 10).updatedAt, store[9].updated_at);
+    assert.equal(second.items.find((i) => i.number === 5).updatedAt, store[4].updated_at);
+  });
+  it("terminates and drains a full page whose items all share one updated_at", () => {
+    const env = { ...ENV, FORGE_STATS_CACHE_DIR: join(td, "cache-sameTs") };
+    const store = Array.from({ length: 230 }, (_, i) => ({ number: i + 1, updated_at: "2026-10-02T00:00:00Z", created_at: "2026-10-01T00:00:00Z", comments: 0, labels: [], user: { type: "Bot" } }));
+    const gh = (args) => {
+      const q = new URLSearchParams(args.find((a) => a.startsWith("repos/")).split("?")[1]);
+      const per = Number(q.get("per_page")), page = Number(q.get("page") ?? 1);
+      const since = q.get("since");
+      return JSON.stringify(store.filter((i) => !since || i.updated_at >= since).slice((page - 1) * per, page * per));
+    };
+    assert.equal(fetchGithubRecords({ repo: "o/r", gh, env }).items.length, 230);
+  });
   it("rejects an unsafe repo before any gh call", () => {
     const { gh, calls } = fakeGh();
     assert.throws(() => fetchGithubRecords({ repo: "o/r; rm -rf /", gh }), /invalid repo/);

package/commands/cleanup.md

@@ -241,6 +241,7 @@ Each `/orchestrate` batch creates one claims board (`orchestrate: claims board f
 A board is closed only when **all** identity checks pass and **one** closing condition holds:
 
 - Identity: title starts with `orchestrate: claims board for batch`, body contains `<!-- FORGE:COORD_ISSUE -->`, and the author is trusted: `author_association` `OWNER`, `MEMBER` or `COLLABORATOR`, or a Bot account (the pipeline's GitHub App, reported as `CONTRIBUTOR`). A look-alike issue from an outside account is never closed.
+- Lease/claim comments count only when trusted (same `author_association` `OWNER`/`MEMBER`/`COLLABORATOR` or Bot predicate as the board, mirroring `scripts/trusted-comments.sh`) and when the marker starts the comment body; an untrusted or quoted marker is ignored, so a board falls back to its trusted events or its creation time. Unlike `/orchestrate`'s no-authorship lease check (forge#2644, a bounded self-expiring dispatch refusal), cleanup's action is a destructive issue close, so it must not trust arbitrary commenters.
 - Close when the last `FORGE:LEASE*` comment is a `FORGE:LEASE_RELEASED`.
 - Close when the last `FORGE:LEASE*`/`FORGE:CLAIM*` comment is older than `BOARD_STALE_HOURS` (default 6, far above the 15 minute lease TTL).
 - Close when there is no lease/claim comment and the issue itself is older than `BOARD_STALE_HOURS`.
@@ -272,11 +273,17 @@ while IFS=$'\t' read -r BNUM BCREATED; do
 
   # --paginate emits one array per page: slurp (jq -s) and flatten BEFORE taking `last`,
   # otherwise a board with >30 comments reads a stale event from an earlier page.
+  # Lease/claim comments are trust-filtered with the same predicate as the board (OWNER/MEMBER/
+  # COLLABORATOR or Bot; mirrors scripts/trusted-comments.sh) and the marker must LEAD the body, so an
+  # outside commenter can neither post a fake FORGE:LEASE_RELEASED nor a fake fresh FORGE:LEASE/CLAIM,
+  # and a quoted marker in prose never matches.
   LAST_LEASE=$(gh api --paginate "repos/{GH_REPO}/issues/${BNUM}/comments" 2>/dev/null \
-    | jq -s '[.[][] | select(.body | contains("FORGE:LEASE"))] | last // empty
-             | {released: (.body | contains("FORGE:LEASE_RELEASED")), at: .created_at}' 2>/dev/null || echo "")
+    | jq -s '[.[][] | select((((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR")) or ((.user.type // "") == "Bot")))
+                     | select((.body // "") | test("\\A\\s*<!-- FORGE:LEASE"))] | last // empty
+             | {released: (.body | test("\\A\\s*<!-- FORGE:LEASE_RELEASED")), at: .created_at}' 2>/dev/null || echo "")
   LAST_ACTIVITY=$(gh api --paginate "repos/{GH_REPO}/issues/${BNUM}/comments" 2>/dev/null \
-    | jq -rs '[.[][] | select(.body | contains("FORGE:LEASE") or contains("FORGE:CLAIM"))] | last // empty | .created_at' 2>/dev/null || echo "")
+    | jq -rs '[.[][] | select((((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR")) or ((.user.type // "") == "Bot")))
+                      | select((.body // "") | test("\\A\\s*<!-- FORGE:(LEASE|CLAIM)"))] | last // empty | .created_at' 2>/dev/null || echo "")
 
   REASON=""
   if [ -n "$LAST_LEASE" ] && [ "$(echo "$LAST_LEASE" | jq -r '.released')" = "true" ]; then

package/commands/deploy-pr.md

@@ -183,6 +183,70 @@ else
 fi
 ```
 
+### 2A.5: Version Sync Pre-flight
+
+Applies ONLY when `SOURCE=$STAGING_BRANCH` and `PR_TARGET=$DEFAULT_BRANCH` (a staging deploy). Skip for every other lane. Publishing bumps the version on the default branch only, so the deploy PR fails the Deploy Version Guard until staging carries that version. The publish workflow normally syncs it; this pre-flight is the safety net when that sync failed. <!-- Added: forge#3695 -->
+
+Rule (same as the publish workflow): sync only when the default branch `package.json` version is strictly ahead of the source branch's. If the source is already at or above it, skip. The sync is a version-only commit (`package.json` and `.claude-plugin/plugin.json`), never a merge of the default branch.
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+STAGING_BRANCH=$(yq '.branches.staging // "staging"' "$CONFIG_FILE" 2>/dev/null || echo "staging")
+DEFAULT_BRANCH=$(yq '.branches.default // "main"' "$CONFIG_FILE" 2>/dev/null || echo "main")
+REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE" 2>/dev/null || echo "$(git rev-parse --show-toplevel)")
+
+if [ "$SOURCE" = "$STAGING_BRANCH" ] && [ "$PR_TARGET" = "$DEFAULT_BRANCH" ]; then
+  cd "$REPO_PATH"
+  git fetch origin "$SOURCE" "$DEFAULT_BRANCH" || { echo "version sync: fetch failed — continuing (version guard will report)"; }
+  MAIN_VERSION=$(git show "origin/$DEFAULT_BRANCH:package.json" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(0, 'utf8')).version)")
+  SRC_VERSION=$(git show "origin/$SOURCE:package.json" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync(0, 'utf8')).version)")
+
+  # Numeric semver compare in node (never a string compare: 1.10.0 > 1.9.0).
+  if MAIN_VERSION="$MAIN_VERSION" SRC_VERSION="$SRC_VERSION" node -e "
+    const p = (v) => v.split('.').map(Number);
+    const [m, s] = [p(process.env.MAIN_VERSION), p(process.env.SRC_VERSION)];
+    for (let i = 0; i < 3; i++) { if (m[i] !== s[i]) process.exit(m[i] > s[i] ? 0 : 1); }
+    process.exit(1);
+  "; then
+    echo "$DEFAULT_BRANCH is at $MAIN_VERSION, ahead of $SOURCE ($SRC_VERSION) — version sync needed"
+    if [ "${DRY_RUN:-false}" = "true" ]; then
+      echo "[dry-run] would sync version $MAIN_VERSION to $SOURCE"
+    else
+      SYNC_DIR=$(mktemp -d)
+      git worktree add --detach "$SYNC_DIR" "origin/$SOURCE"
+      (
+        cd "$SYNC_DIR" || exit 1
+        VERSION="$MAIN_VERSION" node -e "
+          const fs = require('fs');
+          for (const f of ['package.json', '.claude-plugin/plugin.json']) {
+            const j = JSON.parse(fs.readFileSync(f, 'utf8'));
+            j.version = process.env.VERSION;
+            fs.writeFileSync(f, JSON.stringify(j, null, 2) + '\\n');
+          }
+        "
+        git add package.json .claude-plugin/plugin.json
+        git commit -m "chore: sync version $MAIN_VERSION to $SOURCE"
+        if ! git push origin "HEAD:$SOURCE"; then
+          # Push rejected (protected branch or race): fall back to a sync PR.
+          SYNC_BRANCH="chore/sync-main-into-staging-$MAIN_VERSION"
+          git push -f origin "HEAD:refs/heads/$SYNC_BRANCH" \
+            && SYNC_PR=$(gh pr create $GH_FLAG --base "$SOURCE" --head "$SYNC_BRANCH" \
+                 --title "chore: sync version $MAIN_VERSION to $SOURCE" \
+                 --body "Version-only sync so the deploy PR passes the Deploy Version Guard. Generated by deploy-pr 2A.5.") \
+            && echo "Opened sync PR $SYNC_PR — wait for CI green and merge (never bypass gating), then re-run"
+        fi
+      )
+      git worktree remove --force "$SYNC_DIR" 2>/dev/null || true
+      git fetch origin "$SOURCE" 2>/dev/null || true   # re-fetch before 2B/2C
+    fi
+  else
+    echo "$SOURCE ($SRC_VERSION) is at or above $DEFAULT_BRANCH ($MAIN_VERSION) — no version sync needed"
+  fi
+fi
+```
+
+If a sync PR was opened instead of a direct push, wait for it to pass CI and merge through the normal gates before continuing to 2B; do not create or update the deploy PR against a stale source version. Phase 2B onward and the `PR_NUMBER` handoff are unchanged.
+
 ### 2B: Gather Commit Summary (for new PR body)
 
 Skip if PR already exists.

package/commands/fix-ci.md

@@ -312,11 +312,18 @@ echo "Failure detail: ${FAILURE_DETAIL}"
 
 ### Phase 1D: Apply targeted fix
 
-Work on the PR's head branch directly. Check out the branch in the repo root (not a worktree — we push to the existing PR head):
+Work on the PR's head in a dedicated detached worktree, never in the main checkout (it is shared with the operator and other agents). The fix is pushed to the existing PR head with `HEAD:refs/heads/...`. Create the worktree once (reuse it on later attempts) and run every fix, format, test, commit and push step from inside it (`cd "$FIX_WT"`); Phase 2A removes it on every exit path:
 
 ```bash
-git checkout "$FIX_TARGET" 2>/dev/null || git checkout -b "$FIX_TARGET" "origin/${FIX_TARGET}" 2>/dev/null
-git pull origin "$FIX_TARGET" --rebase 2>/dev/null || true
+if [ -z "${FIX_WT:-}" ] || [ ! -d "$FIX_WT" ]; then
+  FIX_WT=$(mktemp -d)
+  git -C "$REPO_PATH" fetch origin "$FIX_TARGET" \
+    && git -C "$REPO_PATH" worktree add --detach "$FIX_WT" "origin/${FIX_TARGET}" \
+    || { echo "ERROR: could not create fix worktree"; rmdir "$FIX_WT" 2>/dev/null; LOOP_STATUS="blocked"; break; }
+fi
+git -C "$FIX_WT" fetch origin "$FIX_TARGET" 2>/dev/null || true
+git -C "$FIX_WT" rebase "origin/${FIX_TARGET}" 2>/dev/null || true
+cd "$FIX_WT"
 ```
 
 **Apply fix based on failure class**:
@@ -440,13 +447,14 @@ echo "Committed fix for attempt ${ATTEMPT}"
 **Push** (normal push only — no force):
 
 ```bash
-git push origin "$FIX_TARGET" 2>&1
+git -C "$FIX_WT" push origin HEAD:"refs/heads/${FIX_TARGET}" 2>&1
 PUSH_EXIT=$?
 
 if [ "$PUSH_EXIT" -ne 0 ]; then
   echo "Push failed (exit ${PUSH_EXIT}) — attempting pull-rebase then re-push..."
-  git pull origin "$FIX_TARGET" --rebase 2>&1 && \
-    git push origin "$FIX_TARGET" 2>&1
+  git -C "$FIX_WT" fetch origin "$FIX_TARGET" 2>&1 && \
+    git -C "$FIX_WT" rebase "origin/${FIX_TARGET}" 2>&1 && \
+    git -C "$FIX_WT" push origin HEAD:"refs/heads/${FIX_TARGET}" 2>&1
   PUSH_EXIT=$?
 fi
 
@@ -476,6 +484,12 @@ After the loop exits, determine the final status and report.
 ### 2A: Determine final status
 
 ```bash
+# Remove the fix worktree on every exit path (success, failure, timeout, blocked).
+cd "$REPO_PATH"
+if [ -n "${FIX_WT:-}" ] && [ -d "$FIX_WT" ]; then
+  git -C "$REPO_PATH" worktree remove --force "$FIX_WT" 2>/dev/null || true
+fi
+
 case "$LOOP_STATUS" in
   "success")
     FINAL_STATUS="success"

package/commands/milestone.md

@@ -412,11 +412,18 @@ Before shipping, ensure the milestone branch is up to date with `staging` (picks
 ```bash
 cd {REPO_PATH}
 git fetch origin {STAGING_BRANCH} milestone/{slug}
-git checkout milestone/{slug}
-git merge origin/{STAGING_BRANCH} --no-edit
-# If conflicts, report to user and STOP — do not auto-resolve
-git push origin milestone/{slug}
-git checkout {STAGING_BRANCH}
+# Never mutate the main checkout: sync in a detached worktree at the milestone tip
+SYNC_WT=$(mktemp -d)
+git worktree add --detach "$SYNC_WT" origin/milestone/{slug}
+if git -C "$SYNC_WT" merge origin/{STAGING_BRANCH} --no-edit; then
+  git -C "$SYNC_WT" push origin HEAD:refs/heads/milestone/{slug}
+  git worktree remove --force "$SYNC_WT"
+else
+  # Conflicts: report to user and STOP — do not auto-resolve
+  git -C "$SYNC_WT" merge --abort 2>/dev/null || true
+  git worktree remove --force "$SYNC_WT"
+  echo "STOP: merge conflict syncing milestone/{slug} with {STAGING_BRANCH}"; exit 1
+fi
 ```
 
 ### Step 2.5: Pre-Merge Hunk-Loss Audit (MANDATORY before creating PR)
@@ -425,6 +432,7 @@ git checkout {STAGING_BRANCH}
 
 This step identifies "at-risk hunks" — staging-only content in files the milestone also modifies — and absorbs them into the milestone branch via rebase before the PR is created. After the rebase, even a squash merge will preserve all staging content because it's now part of the milestone branch's commits.
 
+<!-- allowlist:check-spec-bash -->
 ```bash
 cd {REPO_PATH}
 git fetch origin {STAGING_BRANCH} milestone/{slug}
@@ -453,18 +461,19 @@ else
         echo "$AT_RISK" | grep '^--- a/' | sed 's|^--- a/||'
 
         echo "Rebasing milestone/{slug} onto origin/{STAGING_BRANCH} to absorb at-risk hunks..."
-        git checkout milestone/{slug}
-        git rebase origin/{STAGING_BRANCH}
+        REBASE_WT=$(mktemp -d)
+        git worktree add --detach "$REBASE_WT" origin/milestone/{slug}
+        git -C "$REBASE_WT" rebase origin/{STAGING_BRANCH}
 
         REBASE_EXIT=$?
         if [ "$REBASE_EXIT" -ne 0 ]; then
             # Capture conflicting files BEFORE aborting (after abort, unmerged state is gone)
-            CONFLICTING_FILES=$(git diff --name-only --diff-filter=U 2>/dev/null)
+            CONFLICTING_FILES=$(git -C "$REBASE_WT" diff --name-only --diff-filter=U 2>/dev/null)
             [ -z "$CONFLICTING_FILES" ] && CONFLICTING_FILES="unknown — check git status after resolving manually"
 
             # Abort the failed rebase and return to a clean state
-            git rebase --abort 2>/dev/null || true
-            git checkout {STAGING_BRANCH}
+            git -C "$REBASE_WT" rebase --abort 2>/dev/null || true
+            git worktree remove --force "$REBASE_WT"
 
             # Truncate AT_RISK to safe size for issue body (avoid shell quoting issues with large diffs)
             AT_RISK_SNIPPET=$(echo "$AT_RISK" | head -60 | sed "s/'/'\\\\''/g")
@@ -519,6 +528,7 @@ ISSUE_EOF
 ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"fix(milestone): rebase conflict during hunk-loss audit for milestone/{slug}\" --body-file \"${REBASE_ISSUE_BODY_FILE}\" --label \"bug\" --label \"priority:P0\" --label \"needs-human\""))
 ```
 
+<!-- allowlist:check-spec-bash -->
 ```bash
             echo "STOP: Rebase conflict. Created issue for manual resolution (see /issue output above). Do NOT proceed to PR creation."
             echo "Run '/milestone ship {slug}' again after resolving the conflict."
@@ -526,9 +536,9 @@ ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"fi
         fi
 
         # Rebase succeeded — push the rebased branch
-        git push origin milestone/{slug} --force-with-lease
+        git -C "$REBASE_WT" push origin HEAD:refs/heads/milestone/{slug} --force-with-lease
+        git worktree remove --force "$REBASE_WT"
         echo "Rebase complete. Milestone branch now includes all $AT_RISK_COUNT at-risk staging hunks."
-        git checkout {STAGING_BRANCH}
     fi
 fi
 ```
@@ -716,11 +726,18 @@ Syncs the milestone branch with the latest default branch to pick up fast-lane f
 cd {REPO_PATH}
 DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
 git fetch origin $DEFAULT_BRANCH milestone/{slug}
-git checkout milestone/{slug}
-git merge origin/$DEFAULT_BRANCH --no-edit
-# If conflicts, report to user and STOP
-git push origin milestone/{slug}
-git checkout $DEFAULT_BRANCH
+# Never mutate the main checkout: sync in a detached worktree at the milestone tip
+SYNC_WT=$(mktemp -d)
+git worktree add --detach "$SYNC_WT" origin/milestone/{slug}
+if git -C "$SYNC_WT" merge origin/$DEFAULT_BRANCH --no-edit; then
+  git -C "$SYNC_WT" push origin HEAD:refs/heads/milestone/{slug}
+  git worktree remove --force "$SYNC_WT"
+else
+  # If conflicts, report to user and STOP
+  git -C "$SYNC_WT" merge --abort 2>/dev/null || true
+  git worktree remove --force "$SYNC_WT"
+  echo "STOP: merge conflict syncing milestone/{slug} with $DEFAULT_BRANCH"; exit 1
+fi
 ```
 
 Report: "Synced milestone/{slug} with latest `{DEFAULT_BRANCH}`. {N} new commits incorporated."

package/commands/orchestrate/phase-4-execution.md

@@ -3943,7 +3943,10 @@ if [ -n "$TS_CHANGED" ]; then
     echo "=== Integration Build Gate (TypeScript): batch checkpoint ==="
     cd {REPO_PATH}
     git fetch origin ${MILESTONE_BRANCH}
-    git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
+    # Detached worktree: never check out in the main checkout
+    GATE_WT=$(mktemp -d)
+    git worktree add --detach "$GATE_WT" "origin/${MILESTONE_BRANCH}" 2>/dev/null
+    cd "$GATE_WT"
 
     if [ -n "$TS_TYPECHECK" ]; then
         eval "$TS_TYPECHECK" 2>&1 | head -30
@@ -3961,7 +3964,8 @@ if [ -n "$TS_CHANGED" ]; then
         BUILD_EXIT=0
     fi
 
-    git checkout - 2>/dev/null
+    cd {REPO_PATH}
+    git worktree remove --force "$GATE_WT" 2>/dev/null || true
 
     if [ "$TSC_EXIT" -ne 0 ]; then
         echo "BLOCKING: TypeScript errors on ${MILESTONE_BRANCH} after batch checkpoint."
@@ -3977,7 +3981,9 @@ PY_CHANGED=$(git diff origin/{DEFAULT_BRANCH}...origin/${MILESTONE_BRANCH} --nam
 if [ -n "$PY_CHANGED" ]; then
     echo "=== Integration Build Gate (Python): batch checkpoint ==="
     cd {REPO_PATH}
-    git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
+    GATE_WT=$(mktemp -d)
+    git worktree add --detach "$GATE_WT" "origin/${MILESTONE_BRANCH}" 2>/dev/null
+    cd "$GATE_WT"
 
     if [ -n "$PYTHON_FORMAT" ]; then
         eval "$PYTHON_FORMAT" 2>&1 | tail -10
@@ -3987,7 +3993,8 @@ if [ -n "$PY_CHANGED" ]; then
         FORMAT_EXIT=0
     fi
 
-    git checkout - 2>/dev/null
+    cd {REPO_PATH}
+    git worktree remove --force "$GATE_WT" 2>/dev/null || true
 
     if [ "$FORMAT_EXIT" -ne 0 ]; then
         echo "WARNING: Python formatting issues on ${MILESTONE_BRANCH} after batch checkpoint."