@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/src/resources/extensions/browser-tools/engine/managed-gsd-browser.ts

@@ -32,6 +32,18 @@ interface ManagedConnection {
   launch: GsdBrowserMcpLaunchConfig;
 }
 
+type ConnectManagedGsdBrowser = (
+  launch: GsdBrowserMcpLaunchConfig,
+  signal?: AbortSignal,
+) => Promise<ManagedConnection>;
+
+type CloseManagedGsdBrowserConnection = (connection: ManagedConnection) => Promise<void>;
+
+interface PendingManagedConnection {
+  promise: Promise<ManagedConnection>;
+  abortController: AbortController;
+}
+
 interface McpContentItem {
   type: string;
   text?: string;
@@ -69,8 +81,6 @@ interface ManagedBrowserToolSpec {
   compatibility?: { producesImages?: boolean };
 }
 
-const connections = new Map<string, ManagedConnection>();
-const pendingConnections = new Map<string, Promise<ManagedConnection>>();
 const DEFAULT_MAX_LINES = 2_000;
 const DEFAULT_MAX_BYTES = 50 * 1024;
 const MCP_CALL_TIMEOUT_MS = 60_000;
@@ -368,6 +378,120 @@ function buildConnectionKey(launch: GsdBrowserMcpLaunchConfig): string {
   });
 }
 
+function combineAbortSignals(
+  poolSignal: AbortSignal,
+  callerSignal?: AbortSignal,
+): AbortSignal {
+  if (!callerSignal) return poolSignal;
+  if (typeof AbortSignal.any === "function") {
+    return AbortSignal.any([poolSignal, callerSignal]);
+  }
+
+  const controller = new AbortController();
+  const abort = (): void => {
+    if (!controller.signal.aborted) controller.abort();
+  };
+  if (poolSignal.aborted || callerSignal.aborted) {
+    abort();
+  } else {
+    poolSignal.addEventListener("abort", abort, { once: true });
+    callerSignal.addEventListener("abort", abort, { once: true });
+  }
+  return controller.signal;
+}
+
+export class ManagedGsdBrowserConnectionPool {
+  private readonly connections = new Map<string, ManagedConnection>();
+  private readonly pendingConnections = new Map<string, PendingManagedConnection>();
+  private readonly connect: ConnectManagedGsdBrowser;
+  private readonly closeConnection: CloseManagedGsdBrowserConnection;
+  private generation = 0;
+  private closing = false;
+
+  constructor(
+    connect: ConnectManagedGsdBrowser,
+    closeConnection: CloseManagedGsdBrowserConnection,
+  ) {
+    this.connect = connect;
+    this.closeConnection = closeConnection;
+  }
+
+  get activeCount(): number {
+    return this.connections.size;
+  }
+
+  get pendingCount(): number {
+    return this.pendingConnections.size;
+  }
+
+  getOrConnect(
+    launch: GsdBrowserMcpLaunchConfig,
+    signal?: AbortSignal,
+  ): Promise<ManagedConnection> {
+    if (this.closing) {
+      return Promise.reject(new Error("gsd-browser connection pool is closing"));
+    }
+
+    const key = buildConnectionKey(launch);
+    const existing = this.connections.get(key);
+    if (existing) return Promise.resolve(existing);
+
+    const pending = this.pendingConnections.get(key);
+    if (pending) return pending.promise;
+
+    const generation = this.generation;
+    const abortController = new AbortController();
+    const connectionSignal = combineAbortSignals(abortController.signal, signal);
+    const connectionPromise = this.connect(launch, connectionSignal)
+      .then(async (connection) => {
+        if (this.closing || this.generation !== generation) {
+          await this.closeConnection(connection);
+          throw new Error("gsd-browser connection closed during startup");
+        }
+        this.connections.set(key, connection);
+        return connection;
+      })
+      .finally(() => {
+        if (this.pendingConnections.get(key)?.promise === connectionPromise) {
+          this.pendingConnections.delete(key);
+        }
+      });
+
+    this.pendingConnections.set(key, { promise: connectionPromise, abortController });
+    return connectionPromise;
+  }
+
+  async closeAll(): Promise<void> {
+    this.closing = true;
+    this.generation += 1;
+
+    const activeConnections = Array.from(this.connections.values());
+    const pendingConnections = Array.from(this.pendingConnections.values());
+    this.connections.clear();
+    this.pendingConnections.clear();
+    for (const pending of pendingConnections) {
+      pending.abortController.abort();
+    }
+
+    const closingActive = activeConnections.map((connection) => this.closeConnection(connection));
+    const closingPending = pendingConnections.map(async (pending) => {
+      try {
+        const connection = await pending.promise;
+        await this.closeConnection(connection);
+      } catch {
+        // Failed or invalidated connection attempts have already cleaned up.
+      }
+    });
+
+    try {
+      await Promise.allSettled([...closingActive, ...closingPending]);
+    } finally {
+      this.closing = false;
+      this.generation += 1;
+    }
+  }
+}
+
 async function connectManagedGsdBrowser(
   launch: GsdBrowserMcpLaunchConfig,
   signal?: AbortSignal,
@@ -399,6 +523,24 @@ async function connectManagedGsdBrowser(
   }
 }
 
+async function closeManagedGsdBrowserConnection(connection: ManagedConnection): Promise<void> {
+  try {
+    await connection.client.close();
+  } catch {
+    // Best-effort cleanup.
+  }
+  try {
+    await connection.transport.close();
+  } catch {
+    // Best-effort cleanup.
+  }
+}
+
+const connectionPool = new ManagedGsdBrowserConnectionPool(
+  connectManagedGsdBrowser,
+  closeManagedGsdBrowserConnection,
+);
+
 async function getOrConnectManagedGsdBrowser(
   ctx?: ExtensionContext,
   signal?: AbortSignal,
@@ -406,22 +548,7 @@ async function getOrConnectManagedGsdBrowser(
   const launch = resolveGsdBrowserMcpLaunchConfig(resolveProjectRoot(ctx), process.env, {
     sessionSuffix: resolveManagedSessionSuffix(ctx),
   });
-  const key = buildConnectionKey(launch);
-  const existing = connections.get(key);
-  if (existing) return existing;
-
-  const pending = pendingConnections.get(key);
-  if (pending) return pending;
-
-  const connectionPromise = connectManagedGsdBrowser(launch, signal);
-  pendingConnections.set(key, connectionPromise);
-  try {
-    const connection = await connectionPromise;
-    connections.set(key, connection);
-    return connection;
-  } finally {
-    pendingConnections.delete(key);
-  }
+  return connectionPool.getOrConnect(launch, signal);
 }
 
 function isUnknownMcpToolError(error: unknown): boolean {
@@ -743,21 +870,7 @@ export function registerManagedGsdBrowserTools(pi: ExtensionAPI): void {
 }
 
 export async function closeManagedGsdBrowser(): Promise<void> {
-  const closing = Array.from(connections.entries()).map(async ([key, connection]) => {
-    try {
-      await connection.client.close();
-    } catch {
-      // Best-effort cleanup.
-    }
-    try {
-      await connection.transport.close();
-    } catch {
-      // Best-effort cleanup.
-    }
-    connections.delete(key);
-  });
-  await Promise.allSettled(closing);
-  pendingConnections.clear();
+  await connectionPool.closeAll();
 }
 
 export async function _resetManagedGsdBrowserForTest(): Promise<void> {

package/src/resources/extensions/browser-tools/tests/gsd-browser-launch-config.test.mjs

@@ -9,6 +9,7 @@ import { dirname, join } from "node:path";
 const {
   resolveBundledGsdBrowserCliPath,
   resolveGsdBrowserDaemonStartInvocation,
+  resolveGsdBrowserDaemonStopInvocation,
   resolveGsdBrowserMcpLaunchConfig,
 } = await import("../../shared/gsd-browser-cli.ts");
 
@@ -55,6 +56,31 @@ describe("resolveGsdBrowserMcpLaunchConfig identity flags", () => {
     assert.equal(args[1], "mcp");
   });
 
+  it("appends GSD_BROWSER_MCP_EXTRA_ARGS after the identity flags (string form)", () => {
+    const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example-project", {
+      GSD_BROWSER_MCP_EXTRA_ARGS: "--stealth --browser-path /usr/bin/chromium",
+    });
+
+    // Managed flags stay intact and the extra flags trail them.
+    assert.ok(args.indexOf("--identity-project") >= 0);
+    assert.deepEqual(args.slice(-3), ["--stealth", "--browser-path", "/usr/bin/chromium"]);
+    assert.ok(args.indexOf("--stealth") > args.indexOf("--identity-project"));
+  });
+
+  it("accepts GSD_BROWSER_MCP_EXTRA_ARGS as a JSON array", () => {
+    const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example-project", {
+      GSD_BROWSER_MCP_EXTRA_ARGS: '["--stealth"]',
+    });
+    assert.equal(args[args.length - 1], "--stealth");
+  });
+
+  it("forwards GSD_BROWSER_MCP_EXTRA_ARGS to the daemon-start invocation", () => {
+    const env = { GSD_BROWSER_MCP_EXTRA_ARGS: "--stealth" };
+    const daemon = resolveGsdBrowserDaemonStartInvocation("/tmp/example-project", env);
+    assert.equal(daemon.args[daemon.args.length - 1], "--stealth");
+    assert.ok(daemon.args.indexOf("daemon") >= 0 && daemon.args.indexOf("start") >= 0);
+  });
+
   it("uses a path-safe identity-project identifier", () => {
     const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example/project", {});
     const projectId = args[args.indexOf("--identity-project") + 1];
@@ -154,3 +180,21 @@ describe("resolveGsdBrowserDaemonStartInvocation", () => {
     );
   });
 });
+
+describe("resolveGsdBrowserDaemonStopInvocation", () => {
+  it("mirrors MCP session and identity flags with daemon stop", () => {
+    const launch = resolveGsdBrowserMcpLaunchConfig("/tmp/example-project", {});
+    const daemon = resolveGsdBrowserDaemonStopInvocation("/tmp/example-project", {});
+
+    assert.equal(daemon.command, launch.command);
+    assert.equal(daemon.cwd, launch.cwd);
+    assert.deepEqual(
+      daemon.args.slice(daemon.args.indexOf("--session")),
+      launch.args.slice(launch.args.indexOf("--session")),
+    );
+    assert.deepEqual(
+      daemon.args.slice(0, daemon.args.indexOf("--session")),
+      [...launch.args.slice(0, launch.args.indexOf("mcp")), "daemon", "stop"],
+    );
+  });
+});

package/src/resources/extensions/browser-tools/tests/managed-gsd-browser-tools.test.mjs

@@ -4,6 +4,7 @@ import assert from "node:assert/strict";
 const {
   MANAGED_BROWSER_TOOL_SPECS,
   MANAGED_GSD_BROWSER_TOOL_NAMES,
+  ManagedGsdBrowserConnectionPool,
   findMissingContractCoverage,
   normalizeManagedArgs,
   registerManagedGsdBrowserTools,
@@ -29,6 +30,17 @@ const GSD_BROWSER_SERVED_TOOLS = [
   "browser_act",
 ];
 
+function makeLaunchConfig() {
+  return {
+    command: "gsd-browser",
+    args: ["mcp"],
+    cwd: "/tmp/example-project",
+    projectRoot: "/tmp/example-project",
+    serverName: "gsd-browser",
+    sessionName: "test-session",
+  };
+}
+
 describe("registerManagedGsdBrowserTools", () => {
   it("registers the curated Pi browser contract", () => {
     const tools = [];
@@ -72,6 +84,87 @@ describe("findMissingContractCoverage", () => {
   });
 });
 
+describe("ManagedGsdBrowserConnectionPool", () => {
+  it("closes a pending connection that resolves after the pool is closed", async () => {
+    const closed = [];
+    let resolveConnect;
+    const pool = new ManagedGsdBrowserConnectionPool(async () => {
+      return new Promise((resolve) => {
+        resolveConnect = resolve;
+      });
+    }, async (connection) => {
+      closed.push(connection.id);
+    });
+
+    const launch = makeLaunchConfig();
+
+    const pending = pool.getOrConnect(launch);
+    const closedPool = pool.closeAll();
+    resolveConnect({ id: "late-connection" });
+
+    await assert.rejects(
+      pending,
+      /closed during startup/,
+      "pending callers must not receive a reusable connection after close",
+    );
+    await closedPool;
+
+    assert.deepEqual(closed, ["late-connection"]);
+    assert.equal(pool.activeCount, 0);
+    assert.equal(pool.pendingCount, 0);
+  });
+
+  it("aborts pending connection attempts when the pool is closed", async () => {
+    let receivedSignal;
+    const pool = new ManagedGsdBrowserConnectionPool(async (_launch, signal) => {
+      receivedSignal = signal;
+      return new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(new Error("connect aborted")), { once: true });
+      });
+    }, async () => {});
+
+    const pending = pool.getOrConnect(makeLaunchConfig());
+    const closedPool = pool.closeAll();
+
+    await assert.rejects(pending, /connect aborted/);
+    await closedPool;
+
+    assert.equal(receivedSignal?.aborted, true);
+    assert.equal(pool.activeCount, 0);
+    assert.equal(pool.pendingCount, 0);
+  });
+
+  it("rejects new connection attempts started while the pool is closing", async () => {
+    let resolveConnect;
+    let connectCount = 0;
+    const pool = new ManagedGsdBrowserConnectionPool(async () => {
+      connectCount += 1;
+      return new Promise((resolve) => {
+        resolveConnect = resolve;
+      });
+    }, async () => {});
+
+    const pending = pool.getOrConnect(makeLaunchConfig());
+    const closedPool = pool.closeAll();
+
+    // A caller that arrives during the in-flight closeAll must not open a new
+    // connection that could survive shutdown.
+    await assert.rejects(
+      pool.getOrConnect(makeLaunchConfig()),
+      /closing/,
+      "getOrConnect must reject while the pool is closing",
+    );
+
+    resolveConnect({ id: "pending-connection" });
+    await assert.rejects(pending, /closed during startup/);
+    await closedPool;
+
+    assert.equal(connectCount, 1, "no second connection is started during shutdown");
+    assert.equal(pool.activeCount, 0);
+    assert.equal(pool.pendingCount, 0);
+  });
+});
+
 describe("contract tool translations", () => {
   it("translates browser_click into a single-step batch call", () => {
     const calls = MANAGED_BROWSER_TOOL_SPECS.browser_click.translate.build({ selector: "#save" });

package/src/resources/extensions/gsd/activity-log.ts

@@ -138,7 +138,7 @@ export function saveActivityLog(
     state.nextSeq += 1;
     state.lastSnapshotKeyByUnit.set(unitKey, key);
 
-    if (isUnifiedAuditEnabled()) {
+    if (isUnifiedAuditEnabled(basePath)) {
       emitUokAuditEvent(
         basePath,
         buildAuditEnvelope({

package/src/resources/extensions/gsd/auto/closeout.ts

@@ -3,8 +3,10 @@
 
 import { importExtensionModule, type ExtensionAPI, type ExtensionContext } from "@gsd/pi-coding-agent";
 
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { join, basename } from "node:path";
-import { existsSync, cpSync } from "node:fs";
+import { existsSync, cpSync, readFileSync } from "node:fs";
 import type { AutoSession } from "./session.js";
 import type { LoopDeps } from "./loop-deps.js";
 import type { GSDState } from "../types.js";
@@ -16,7 +18,7 @@ import { getIsolationMode } from "../preferences.js";
 import { isDbAvailable, getMilestone } from "../gsd-db.js";
 import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
 import { isClosedStatus } from "../status-guards.js";
-import { gsdRoot } from "../paths.js";
+import { gsdRoot, PLANNING_ARTIFACT_SUFFIXES } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { debugLog } from "../debug-logger.js";
@@ -98,7 +100,15 @@ export async function _runMilestoneMergeWithStashRestore(
 ): Promise<{ action: "break"; reason: string } | null> {
   const { ctx, pi, s, deps } = ic;
 
-  const projectRoot = s.originalBasePath || s.basePath;
+  // Resolve the project root once, before the merge can flip session path
+  // pointers (worktree teardown mutates s.basePath / s.scope). The guarded
+  // merge's preflight/postflight stash restore, the pre-merge ignored-markdown
+  // snapshot, the dirty-projection check, and the rebuild must all target this
+  // same tree; otherwise `.gsd` markdown restored on one tree can be silently
+  // overwritten by a rebuild on another. canonicalProjectRoot is the
+  // authoritative `.gsd`/DB writer path (see AutoSession.canonicalProjectRoot).
+  const projectRoot = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+  const ignoredProjectionSnapshot = snapshotIgnoredGsdMarkdownProjections(projectRoot);
   const mergeResult = deps.lifecycle.exitMilestone(
     milestoneId,
     {
@@ -113,12 +123,12 @@ export async function _runMilestoneMergeWithStashRestore(
   );
 
   if (mergeResult.ok) {
-    await markMilestoneMergedAndRebuild(s);
+    await markMilestoneMergedAndRebuild(s, projectRoot, ignoredProjectionSnapshot);
     return null;
   }
 
   if (mergeResult.reason === "postflight-stash-restore-failed") {
-    await markMilestoneMergedAndRebuild(s);
+    await markMilestoneMergedAndRebuild(s, projectRoot, ignoredProjectionSnapshot);
   }
 
   if (mergeResult.reason === "preflight-dirty-overlap" || mergeResult.reason === "preflight-unmerged-conflicts") {
@@ -180,10 +190,23 @@ export async function _runMilestoneMergeWithStashRestore(
   return null;
 }
 
-async function markMilestoneMergedAndRebuild(s: AutoSession): Promise<void> {
+type GsdMarkdownSnapshot = Map<string, string>;
+
+async function markMilestoneMergedAndRebuild(
+  s: AutoSession,
+  rebuildBasePath: string,
+  ignoredProjectionSnapshot: GsdMarkdownSnapshot | null,
+): Promise<void> {
   s.milestoneMergedInPhases = true;
+  if (hasDirtyGsdMarkdownProjections(rebuildBasePath, ignoredProjectionSnapshot)) {
+    logWarning(
+      "engine",
+      "skipping markdown projection rebuild after milestone merge because restored .gsd edits are dirty",
+    );
+    return;
+  }
+
   try {
-    const rebuildBasePath = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
     const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
     await rebuildMarkdownProjectionsFromDb(rebuildBasePath);
   } catch (err) {
@@ -194,6 +217,90 @@ async function markMilestoneMergedAndRebuild(s: AutoSession): Promise<void> {
   }
 }
 
+function hasDirtyGsdMarkdownProjections(
+  basePath: string,
+  ignoredProjectionSnapshot: GsdMarkdownSnapshot | null,
+): boolean {
+  try {
+    const output = execFileSync(
+      "git",
+      ["status", "--porcelain", "-z", "--untracked-files=all", "--", ".gsd"],
+      { cwd: basePath, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const entries = output.split("\0").filter(Boolean);
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i];
+      if (entry.length <= 3) continue;
+      const status = entry.slice(0, 2);
+      const path = entry.slice(3);
+      if (isGeneratedGsdMarkdownProjection(path)) return true;
+      if ((status === "R " || status === "C ") && i + 1 < entries.length) {
+        const dest = entries[++i];
+        if (isGeneratedGsdMarkdownProjection(dest)) return true;
+      }
+    }
+  } catch (err) {
+    void err;
+    // Fall through to ignored-file snapshot comparison below.
+  }
+  return ignoredGsdMarkdownProjectionSnapshotChanged(basePath, ignoredProjectionSnapshot);
+}
+
+function isGeneratedGsdMarkdownProjection(path: string): boolean {
+  const normalized = path.replace(/\\/g, "/");
+  if (normalized === ".gsd/DECISIONS.md") return true;
+  if (!normalized.startsWith(".gsd/milestones/") && !normalized.startsWith(".gsd/phases/")) {
+    return false;
+  }
+  return isGeneratedPlanningArtifactFileName(basename(normalized));
+}
+
+function isGeneratedPlanningArtifactFileName(fileName: string): boolean {
+  if (!fileName.endsWith(".md")) return false;
+  const stem = fileName.slice(0, -".md".length).toUpperCase();
+  for (const suffix of PLANNING_ARTIFACT_SUFFIXES) {
+    if (!stem.endsWith(`-${suffix}`)) continue;
+    const idPrefix = stem.slice(0, -suffix.length - 1);
+    return /^(?:[MST]\d+|\d{2,})(?:-[A-Z0-9]+)*$/.test(idPrefix);
+  }
+  return false;
+}
+
+function snapshotIgnoredGsdMarkdownProjections(basePath: string): GsdMarkdownSnapshot | null {
+  try {
+    const output = execFileSync(
+      "git",
+      ["ls-files", "--others", "--ignored", "--exclude-standard", "-z", "--", ".gsd"],
+      { cwd: basePath, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const snapshot: GsdMarkdownSnapshot = new Map();
+    for (const path of output.split("\0")) {
+      if (!isGeneratedGsdMarkdownProjection(path)) continue;
+      snapshot.set(path, hashFile(join(basePath, path)));
+    }
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+
+function hashFile(path: string): string {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+function ignoredGsdMarkdownProjectionSnapshotChanged(
+  basePath: string,
+  before: GsdMarkdownSnapshot | null,
+): boolean {
+  if (!before) return true;
+  const after = snapshotIgnoredGsdMarkdownProjections(basePath);
+  if (!after || after.size !== before.size) return true;
+  for (const [path, hash] of before) {
+    if (after.get(path) !== hash) return true;
+  }
+  return false;
+}
+
 export async function _runMilestoneMergeOnceWithStashRestore(
   ic: IterationContext,
   milestoneId: string,

package/src/resources/extensions/gsd/auto/orchestrator.ts

@@ -34,7 +34,8 @@ import {
   preDispatchHealthGate,
   recordHealthSnapshot,
 } from "../doctor-proactive.js";
-import { checkResourcesStale, autoWorktreeBranch, mergeMilestoneToMain } from "../auto-worktree.js";
+import { autoWorktreeBranch } from "../auto-worktree-branch-lifecycle.js";
+import { checkResourcesStale } from "../auto-worktree-resource-version.js";
 import { getSessionLockStatus } from "../session-lock.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { emitJournalEvent as _emitJournalEvent } from "../journal.js";
@@ -49,7 +50,7 @@ import { getPriorSliceCompletionBlocker } from "../dispatch-guard.js";
 import { GitServiceImpl } from "../git-service.js";
 import { WorktreeStateProjection } from "../worktree-state-projection.js";
 import { WorktreeLifecycle } from "../worktree-lifecycle.js";
-import { createMilestoneMergeTransaction } from "../milestone-merge-transaction.js";
+import { createDefaultMilestoneMergeTransaction } from "../milestone-merge-transaction.js";
 import { createWorkspace, scopeMilestone } from "../workspace.js";
 import { supportsStructuredQuestions } from "../workflow-mcp.js";
 import { getRegisteredToolSnapshot, getToolBaselineSnapshot } from "../auto-model-selection.js";
@@ -731,7 +732,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return new GitServiceImpl(basePath, gitConfig);
       },
       worktreeProjection: new WorktreeStateProjection(),
-      mergeMilestone: createMilestoneMergeTransaction(mergeMilestoneToMain),
+      mergeMilestone: createDefaultMilestoneMergeTransaction(),
     });
   }
 
@@ -1195,17 +1196,23 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return skipped;
       }
 
-      // Stuck-loop detection: when the window is saturated with copies of
-      // `nextKey` (count >= STUCK_WINDOW_SIZE), consult the Dispatch History
-      // module's full detect-stuck rule set for the verdict instead of the old
-      // bare saturation count. This keeps the saturation threshold (the window
-      // deliberately records benign idempotent repeats, so earlier-firing
-      // rules would false-positive on pause/resume re-advances) while gaining
-      // retry-budget suppression and diagnosable rule reasons. A saturated
-      // window with no verdict means the dispatch ledger says we are inside
-      // the unit's retry-backoff budget — let the retry proceed.
-      const stuckVerdict =
-        matchingCount >= STUCK_WINDOW_SIZE ? this.dispatchHistory.detectStuck() : null;
+      // Stuck-loop detection: consult the Dispatch History module's full
+      // detect-stuck rule set once the window is *full* — not only when a
+      // single key saturates it. Gating on a single key's saturation count
+      // (matchingCount >= STUCK_WINDOW_SIZE) let two-unit oscillations slip
+      // through forever: an execute-task ↔ complete-slice loop (a slice gate
+      // that keeps reopening the same task, #1225) fills the window with two
+      // alternating keys, so neither key ever reaches the saturation count and
+      // detect-stuck's oscillation/repeat rules were never even invoked. Firing
+      // on window saturation instead covers both shapes. Consecutive same-key
+      // re-advances (the benign pause/resume churn the old count gate guarded
+      // against) are already short-circuited above by the idempotency skip, and
+      // legitimate retry backoff is still suppressed inside detect-stuck via the
+      // dispatch ledger — a saturated window with no verdict means we are inside
+      // the unit's retry-backoff budget, so let the retry proceed.
+      const windowSaturated =
+        this.dispatchHistory.getRecentWindow().length >= STUCK_WINDOW_SIZE;
+      const stuckVerdict = windowSaturated ? this.dispatchHistory.detectStuck() : null;
       if (stuckVerdict) {
         // #442: before declaring a stuck loop, verify the unit didn't actually
         // complete on disk (stale DB) and recover if so — legacy graduated

package/src/resources/extensions/gsd/auto/pre-dispatch.ts

@@ -440,7 +440,8 @@ export async function runPreDispatch(
       if (stop) return stop;
     }
 
-    // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
+    // PR creation (auto_pr) is handled by the publication handoff in
+    // the milestone merge transaction (#2302).
 
     deps.invalidateAllCaches();
 
@@ -551,7 +552,8 @@ export async function runPreDispatch(
         // #2909 / #5538-followup: preflight stash + always-on postflight pop.
         const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
         if (stop) return stop;
-        // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
+        // PR creation (auto_pr) is handled by the publication handoff in
+        // the milestone merge transaction (#2302).
       }
       const unmappedActive = countUnmappedActiveRequirements();
       const completionStopReason = formatCompletePhaseNextAction(unmappedActive);
@@ -654,7 +656,8 @@ export async function runPreDispatch(
       // #2909 / #5538-followup: preflight stash + always-on postflight pop.
       const stop = await _runMilestoneMergeOnceWithStashRestore(ic, s.currentMilestoneId);
       if (stop) return stop;
-      // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
+      // PR creation (auto_pr) is handled by the publication handoff in
+      // the milestone merge transaction (#2302).
     }
     deps.sendDesktopNotification(
       "GSD",