@opengsd/gsd-pi 1.3.0-dev.eed73bea → 1.4.0-dev.5fc22c6f

package/src/resources/extensions/gsd/tests/artifact-retry-cap.test.ts

@@ -29,21 +29,22 @@ test("#2007 bug 1: MAX_ARTIFACT_VERIFICATION_RETRIES constant is defined", () =>
   assert.equal(MAX_ARTIFACT_VERIFICATION_RETRIES, 3);
 });
 
-test("#2007 bug 1: retry state can represent each allowed attempt before exhaustion", () => {
+test("#2007 bug 1: retry state keeps attempt separate from failure context", () => {
   const s = new AutoSession();
   const retryKey = "execute-task:M001/S01/T01";
+  const failureContext = "Missing expected artifact";
 
   for (let attempt = 1; attempt <= MAX_ARTIFACT_VERIFICATION_RETRIES; attempt++) {
     s.verificationRetryCount.set(retryKey, attempt);
     s.pendingVerificationRetry = {
       unitId: "M001/S01/T01",
-      failureContext: `Missing expected artifact (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
+      failureContext,
       attempt,
     };
 
     assert.equal(s.verificationRetryCount.get(retryKey), attempt);
     assert.equal(s.pendingVerificationRetry.attempt, attempt);
-    assert.match(s.pendingVerificationRetry.failureContext, /attempt \d\/3/);
+    assert.equal(s.pendingVerificationRetry.failureContext, failureContext);
   }
 });
 

package/src/resources/extensions/gsd/tests/auto-artifact-paths.test.ts

@@ -4,7 +4,7 @@ import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "nod
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { resolveExpectedArtifactPath } from "../auto-artifact-paths.ts";
+import { resolveExpectedArtifactPath, resolveSliceResearchLocation, resolveExistingSliceResearchPath } from "../auto-artifact-paths.ts";
 import { clearPathCache, _clearGsdRootCache, isLegacyMilestonesLayout, milestonesDir } from "../paths.ts";
 
 test("worktree artifact resolution falls back to project .gsd artifacts", () => {
@@ -359,3 +359,100 @@ test("canonical worktree + project-root legacy dir produces legacy filename (#bu
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+// ── resolveSliceResearchLocation / resolveExistingSliceResearchPath ───────────
+//
+// Added in the code-quality consolidation PR as the shared dual-path resolver
+// for slice RESEARCH files (worktree projection first, then canonical path
+// fallback). These tests guard: missing file → null pair; existing legacy-
+// layout file → correct absolute and relative paths.
+
+test("resolveSliceResearchLocation returns null pair when no RESEARCH file exists", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-research-missing-")));
+  try {
+    const milestoneDir = join(root, ".gsd", "milestones", "M001");
+    mkdirSync(join(milestoneDir, "slices", "S01"), { recursive: true });
+    // Content-bearing dir so it is not treated as META-only, but no RESEARCH file.
+    writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# context\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const result = resolveSliceResearchLocation(root, "M001", "S01");
+    assert.strictEqual(result.absolutePath, null, "absolutePath must be null when no RESEARCH exists");
+    assert.strictEqual(result.relativePath, null, "relativePath must be null when no RESEARCH exists");
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resolveExistingSliceResearchPath returns null when no RESEARCH file exists", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-research-null-")));
+  try {
+    const milestoneDir = join(root, ".gsd", "milestones", "M001");
+    mkdirSync(join(milestoneDir, "slices", "S01"), { recursive: true });
+    writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# context\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    assert.strictEqual(
+      resolveExistingSliceResearchPath(root, "M001", "S01"),
+      null,
+      "must return null when RESEARCH file is absent",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resolveSliceResearchLocation finds existing RESEARCH in legacy layout", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-research-legacy-")));
+  try {
+    const milestoneDir = join(root, ".gsd", "milestones", "M001");
+    const sliceDir = join(milestoneDir, "slices", "S01");
+    mkdirSync(sliceDir, { recursive: true });
+    writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# context\n");
+    const researchFile = join(sliceDir, "S01-RESEARCH.md");
+    writeFileSync(researchFile, "# slice research\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const result = resolveSliceResearchLocation(root, "M001", "S01");
+    assert.ok(result.absolutePath !== null, "absolutePath must be non-null when RESEARCH exists");
+    assert.ok(result.relativePath !== null, "relativePath must be non-null when RESEARCH exists");
+    assert.equal(result.absolutePath, researchFile, "absolutePath must point to the RESEARCH file");
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resolveExistingSliceResearchPath returns absolute path when RESEARCH exists (legacy layout)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-research-existing-")));
+  try {
+    const milestoneDir = join(root, ".gsd", "milestones", "M001");
+    const sliceDir = join(milestoneDir, "slices", "S01");
+    mkdirSync(sliceDir, { recursive: true });
+    writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# context\n");
+    const researchFile = join(sliceDir, "S01-RESEARCH.md");
+    writeFileSync(researchFile, "# research\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const result = resolveExistingSliceResearchPath(root, "M001", "S01");
+    assert.ok(result !== null, "must return non-null when RESEARCH exists");
+    assert.equal(result, researchFile, "must return the absolute path to the RESEARCH file");
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/auto-budget-alerts.test.ts

@@ -8,6 +8,7 @@ import {
   getNewBudgetAlertLevel,
   resolveCompactionThresholdPercent,
   shouldRerootStepSessionForContext,
+  shouldWarnStepSessionForContext,
 } from "../auto.js";
 import {
   getUnitCostSpikeAction,
@@ -73,11 +74,19 @@ test("resolveCompactionThresholdPercent defaults to 60 and accepts ratio prefs",
   assert.equal(resolveCompactionThresholdPercent(0.4), 60);
 });
 
-test("shouldRerootStepSessionForContext uses compaction threshold pref", () => {
-  assert.equal(shouldRerootStepSessionForContext(59.9, 0.6), false);
-  assert.equal(shouldRerootStepSessionForContext(60, 0.6), true);
-  assert.equal(shouldRerootStepSessionForContext(273.8, 0.6), true);
-  assert.equal(shouldRerootStepSessionForContext(undefined, 0.6), false);
+test("shouldWarnStepSessionForContext uses compaction threshold pref", () => {
+  assert.equal(shouldWarnStepSessionForContext(59.9, 0.6), false);
+  assert.equal(shouldWarnStepSessionForContext(60, 0.6), true);
+  assert.equal(shouldWarnStepSessionForContext(72, 0.6), true);
+  assert.equal(shouldWarnStepSessionForContext(undefined, 0.6), false);
+});
+
+test("shouldRerootStepSessionForContext only fires at the hard context threshold", () => {
+  assert.equal(shouldRerootStepSessionForContext(72), false);
+  assert.equal(shouldRerootStepSessionForContext(89.9), false);
+  assert.equal(shouldRerootStepSessionForContext(90), true);
+  assert.equal(shouldRerootStepSessionForContext(273.8), true);
+  assert.equal(shouldRerootStepSessionForContext(undefined), false);
 });
 
 test("resolveUnitCostSpikeMultiplier disables the spike pause for burn-max", () => {

package/src/resources/extensions/gsd/tests/auto-migrating-recovery.test.ts

@@ -49,6 +49,24 @@ test("recoverFailedMigration returns false when both .gsd and .gsd.migrating exi
   assert.ok(existsSync(join(base, ".gsd.migrating")), ".gsd.migrating must still exist");
 });
 
+test("recoverFailedMigration removes orphan when .gsd is a real intact directory", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-migrating-real-orphan-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const localGsd = join(base, ".gsd");
+  mkdirSync(join(localGsd, "phases"), { recursive: true });
+  mkdirSync(join(localGsd, "activity"), { recursive: true });
+  writeFileSync(join(localGsd, "STATE.md"), "# State\n", "utf-8");
+  writeFileSync(join(localGsd, "gsd.db"), "not empty\n", "utf-8");
+  mkdirSync(join(base, ".gsd.migrating"), { recursive: true });
+
+  const recovered = recoverFailedMigration(base);
+
+  assert.equal(recovered, true, "expected orphan cleanup to succeed");
+  assert.ok(existsSync(localGsd), ".gsd real directory must remain");
+  assert.ok(!existsSync(join(base, ".gsd.migrating")), ".gsd.migrating orphan must be removed");
+});
+
 test("recoverFailedMigration removes orphan when .gsd is an intact external-state junction", (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-migrating-orphan-"));
   const stateDir = mkdtempSync(join(tmpdir(), "gsd-migrating-state-"));

package/src/resources/extensions/gsd/tests/auto-model-selection.test.ts

@@ -63,6 +63,62 @@ test("resolvePreferredModelConfig synthesizes heavy routing ceiling when models
   }
 });
 
+test("resolvePreferredModelConfig treats token-profile model defaults as synthesized routing", () => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = makeTempDir("gsd-routing-profile-project-");
+  const tempGsdHome = makeTempDir("gsd-routing-profile-home-");
+
+  try {
+    mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+    writeFileSync(
+      join(tempProject, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "token_profile: quality",
+        "dynamic_routing:",
+        "  enabled: true",
+        "  tier_models:",
+        "    light: claude-haiku-4-5",
+        "    standard: claude-sonnet-4-6",
+        "    heavy: claude-opus-4-6",
+        "---",
+      ].join("\n"),
+      "utf-8",
+    );
+    process.env.GSD_HOME = tempGsdHome;
+    process.chdir(tempProject);
+
+    const config = resolvePreferredModelConfig(
+      "plan-slice",
+      {
+        provider: "anthropic",
+        id: "claude-sonnet-4-6",
+      },
+      true,
+      tempProject,
+      [
+        "anthropic/claude-haiku-4-5",
+        "anthropic/claude-sonnet-4-6",
+        "anthropic/claude-opus-4-6",
+      ],
+      "anthropic/claude-sonnet-4-6",
+    );
+
+    assert.deepEqual(config, {
+      primary: "claude-opus-4-6",
+      fallbacks: [],
+      source: "synthesized",
+    });
+  } finally {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  }
+});
+
 test("resolvePreferredModelConfig falls back to auto start model when heavy tier is absent", () => {
   const originalCwd = process.cwd();
   const originalGsdHome = process.env.GSD_HOME;
@@ -152,6 +208,128 @@ test("resolvePreferredModelConfig keeps explicit phase models as the ceiling", (
   }
 });
 
+// #1115 regression: a token_profile with dynamic_routing enabled but NO
+// tier_models pins must still resolve the profile's per-phase model as a
+// synthesized routing ceiling. Before the fix, resolvePreferredModelConfig
+// bailed to undefined here (explicit detection skips profile defaults, and the
+// synthesis path required tier_models), so auto dispatch fell back to the
+// start model for every unit and silently discarded the profile.
+test("resolvePreferredModelConfig resolves profile per-phase models as synthesized when tier_models are absent", () => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = makeTempDir("gsd-routing-profile-notier-");
+  const tempGsdHome = makeTempDir("gsd-routing-profile-notier-home-");
+
+  try {
+    mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+    writeFileSync(
+      join(tempProject, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "token_profile: budget",
+        "dynamic_routing:",
+        "  enabled: true",
+        "---",
+      ].join("\n"),
+      "utf-8",
+    );
+    process.env.GSD_HOME = tempGsdHome;
+    process.chdir(tempProject);
+
+    const availableModelIds = [
+      "anthropic/claude-haiku-4-5",
+      "anthropic/claude-sonnet-4-6",
+      "anthropic/claude-opus-4-6",
+    ];
+    const start = { provider: "anthropic", id: "claude-sonnet-4-6" };
+    // preferredModelId is intentionally left undefined so profile tier
+    // resolution is exercised rather than pinning every tier to the session
+    // model (a heavy session model can satisfy every tier).
+    const resolve = (unitType: string) =>
+      resolvePreferredModelConfig(unitType, start, true, tempProject, availableModelIds);
+
+    // budget profile: research=light, planning=standard, execution=standard,
+    // execution_simple=light, completion=light (PROFILE_TIER_MAP).
+    assert.deepEqual(resolve("research-milestone"), {
+      primary: "claude-haiku-4-5",
+      fallbacks: [],
+      source: "synthesized",
+    });
+    assert.deepEqual(resolve("plan-milestone"), {
+      primary: "claude-sonnet-4-6",
+      fallbacks: [],
+      source: "synthesized",
+    });
+    assert.deepEqual(resolve("execute-task"), {
+      primary: "claude-sonnet-4-6",
+      fallbacks: [],
+      source: "synthesized",
+    });
+    assert.deepEqual(resolve("execute-task-simple"), {
+      primary: "claude-haiku-4-5",
+      fallbacks: [],
+      source: "synthesized",
+    });
+    assert.deepEqual(resolve("complete-slice"), {
+      primary: "claude-haiku-4-5",
+      fallbacks: [],
+      source: "synthesized",
+    });
+  } finally {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  }
+});
+
+// #1115 guard: the explicit flat-rate opt-out must suppress synthesized routing
+// even on the profile-derived (no tier_models) path — the opt-out moved ahead
+// of both synthesis branches, so a flat-rate start model with
+// allow_flat_rate_providers:false yields no config (start model is used as-is).
+test("resolvePreferredModelConfig honors flat-rate opt-out on the profile path (no tier_models)", () => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = makeTempDir("gsd-routing-flatrate-notier-");
+  const tempGsdHome = makeTempDir("gsd-routing-flatrate-notier-home-");
+
+  try {
+    mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+    writeFileSync(
+      join(tempProject, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "token_profile: budget",
+        "dynamic_routing:",
+        "  enabled: true",
+        "  allow_flat_rate_providers: false",
+        "---",
+      ].join("\n"),
+      "utf-8",
+    );
+    process.env.GSD_HOME = tempGsdHome;
+    process.chdir(tempProject);
+
+    const config = resolvePreferredModelConfig(
+      "execute-task",
+      // claude-code is a built-in flat-rate provider.
+      { provider: "claude-code", id: "claude-opus-4-6" },
+      true,
+      tempProject,
+      ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],
+    );
+
+    assert.equal(config, undefined);
+  } finally {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  }
+});
+
 test("selectAndApplyModel honors explicit phase models without downgrading (#3617)", async () => {
   const originalCwd = process.cwd();
   const originalGsdHome = process.env.GSD_HOME;

package/src/resources/extensions/gsd/tests/auto-pause-double-entry-guard.test.ts

@@ -14,6 +14,7 @@ import { capturePauseAutoUnitIdentity, pauseAuto, isAutoActive } from "../auto.t
 import { _resetPendingResolve, _setCurrentResolve } from "../auto/resolve.ts";
 import { autoSession } from "../auto-runtime-state.ts";
 import { _isPauseOriginCancelledResult } from "../auto/phase-helpers.ts";
+import { handleAutoCommand } from "../commands/handlers/auto.ts";
 
 test("pauseAuto sets s.active = false synchronously before first await (blocks concurrent re-entry)", async () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-double-pause-guard-"));
@@ -80,6 +81,41 @@ test("pauseAuto marks paused and cancels the in-flight unit before first await",
   }
 });
 
+test("/gsd pause aborts the active pi turn before first await", async () => {
+  autoSession.reset();
+  autoSession.active = true;
+  let abortCount = 0;
+  const ctx = {
+    hasUI: false,
+    isIdle: () => false,
+    abort: () => {
+      abortCount += 1;
+    },
+    sessionManager: {
+      getSessionFile: () => null,
+    },
+    ui: {
+      setStatus() {},
+      setWidget() {},
+      notify() {},
+    },
+  } as any;
+
+  try {
+    const pausePromise = handleAutoCommand("pause", ctx, {} as any);
+
+    assert.equal(
+      abortCount,
+      1,
+      "pauseAuto must abort the active pi turn before reporting auto-mode paused",
+    );
+
+    await pausePromise.catch(() => {});
+  } finally {
+    autoSession.reset();
+  }
+});
+
 test("transient-abort errorContext is not classified as pause-origin cancellation", () => {
   // The phases.ts fix passes unitResult.errorContext to pauseAuto for transient aborts.
   // _isPauseOriginCancelledResult must return false when errorContext is present, ensuring

package/src/resources/extensions/gsd/tests/auto-paused-ui-cleanup.test.ts

@@ -3,13 +3,14 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 
 import {
   anchorProcessCwdForAutoResume,
   cleanupAfterLoopExit,
+  maybeRerootStepSessionForHighContext,
   pauseAuto,
   rerootCommandSession,
   stopAuto,
@@ -478,8 +479,8 @@ test("cleanupAfterLoopExit preserves step-mode surface and worktree session afte
   }
 });
 
-test("cleanupAfterLoopExit re-roots step-mode session when context exceeds compaction threshold", async (t) => {
-  const base = mkdtempSync(join(tmpdir(), "gsd-step-reroot-"));
+test("cleanupAfterLoopExit warns but does not re-root step-mode session at soft compaction threshold", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-step-soft-context-"));
   const worktree = join(base, ".gsd", "worktrees", "M001");
   const previousCwd = process.cwd();
   const newSessionWorkspaces: string[] = [];
@@ -515,7 +516,59 @@ test("cleanupAfterLoopExit re-roots step-mode session when context exceeds compa
       },
     } as any);
 
-    assert.deepEqual(newSessionWorkspaces, [worktree], "hot step-mode cleanup should re-root in the active worktree");
+    assert.deepEqual(newSessionWorkspaces, [], "soft context pressure must not force a new command session");
+    assert.equal(
+      notifyMessages.some((msg) => msg.includes("context at 72.0%") && msg.includes("Use /compact")),
+      true,
+      "soft threshold should warn with a non-disruptive compaction prompt",
+    );
+    assert.equal(autoSession.basePath, worktree);
+    assert.equal(realpathSync(process.cwd()), realpathSync(worktree));
+  } finally {
+    autoSession.reset();
+    process.chdir(previousCwd);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("cleanupAfterLoopExit re-roots step-mode session at hard context threshold", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-step-reroot-"));
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const previousCwd = process.cwd();
+  const newSessionWorkspaces: string[] = [];
+  const notifyMessages: string[] = [];
+
+  t.mock.method(WorktreeLifecycle.prototype, "restoreToProjectRoot", function () {});
+
+  mkdirSync(worktree, { recursive: true });
+  process.chdir(worktree);
+  autoSession.reset();
+  autoSession.active = true;
+  autoSession.paused = false;
+  autoSession.stepMode = true;
+  autoSession.preserveStepSurfaceAfterLoopExit = true;
+  autoSession.basePath = worktree;
+  autoSession.originalBasePath = base;
+  autoSession.cmdCtx = {
+    getContextUsage: () => ({ percent: 92, tokens: 920_000, contextWindow: 1_000_000 }),
+    newSession: async ({ workspaceRoot }: { workspaceRoot: string }) => {
+      newSessionWorkspaces.push(workspaceRoot);
+      return { cancelled: false };
+    },
+  } as any;
+
+  try {
+    await cleanupAfterLoopExit({
+      hasUI: true,
+      ui: {
+        setStatus: () => {},
+        setWidget: () => {},
+        setHeader: () => {},
+        notify: (_msg: string) => notifyMessages.push(_msg),
+      },
+    } as any);
+
+    assert.deepEqual(newSessionWorkspaces, [worktree], "critical context pressure should re-root in the active worktree");
     assert.equal(
       notifyMessages.some((msg) => msg.includes("Fresh session ready for /gsd next")),
       true,
@@ -530,6 +583,131 @@ test("cleanupAfterLoopExit re-roots step-mode session when context exceeds compa
   }
 });
 
+test("maybeRerootStepSessionForHighContext re-roots at the hard threshold even when the soft pref is set above it", async () => {
+  // Regression: the hard 90% re-root must not be gated behind the configurable
+  // soft warn threshold, which is allowed up to 0.95. At 92% usage with a 0.95
+  // soft pref the soft warn predicate is false, but the session must still
+  // re-root because usage crossed the fixed hard boundary.
+  const dir = mkdtempSync(join(tmpdir(), "gsd-hard-reroot-high-soft-"));
+  const project = join(dir, "project");
+  const gsdHomeDir = join(dir, "home");
+  const previousCwd = process.cwd();
+  const previousGsdHome = process.env.GSD_HOME;
+
+  mkdirSync(join(project, ".gsd"), { recursive: true });
+  mkdirSync(gsdHomeDir, { recursive: true });
+  writeFileSync(
+    join(project, ".gsd", "PREFERENCES.md"),
+    ["---", "version: 1", "context_management:", "  compaction_threshold_percent: 0.95", "---", ""].join("\n"),
+    "utf-8",
+  );
+
+  process.env.GSD_HOME = gsdHomeDir;
+  process.chdir(project);
+
+  const newSessionWorkspaces: string[] = [];
+  const notifyMessages: string[] = [];
+  const cmdCtx = {
+    getContextUsage: () => ({ percent: 92, tokens: 920_000, contextWindow: 1_000_000 }),
+    newSession: async ({ workspaceRoot }: { workspaceRoot: string }) => {
+      newSessionWorkspaces.push(workspaceRoot);
+      return { cancelled: false };
+    },
+  } as any;
+  const ctx = { ui: { notify: (msg: string) => notifyMessages.push(msg) } } as any;
+
+  try {
+    const result = await maybeRerootStepSessionForHighContext(ctx, project, cmdCtx, project);
+
+    assert.equal(result.rerooted, true, "92% usage must re-root even when the soft pref is 95%");
+    assert.deepEqual(newSessionWorkspaces, [project], "hard context pressure must re-root the command session");
+    const rerootMessage = notifyMessages.find((msg) => msg.includes("Fresh session ready for /gsd next"));
+    assert.ok(rerootMessage, "hard re-root should notify the user");
+    // The re-root was triggered by the 90% hard limit, so the notification must
+    // cite that limit and not the configured 95% soft compaction threshold.
+    assert.match(
+      rerootMessage,
+      /hard threshold: 90%/,
+      "hard re-root notification must cite the 90% hard threshold",
+    );
+    assert.equal(
+      rerootMessage.includes("95%"),
+      false,
+      "hard re-root notification must not cite the configured soft compaction threshold",
+    );
+  } finally {
+    process.chdir(previousCwd);
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("maybeRerootStepSessionForHighContext writes a compaction snapshot only at the hard boundary", async () => {
+  // Regression: the snapshot is reserved for the hard re-root. Soft-only
+  // pressure must warn without writing a compaction snapshot.
+  const dir = mkdtempSync(join(tmpdir(), "gsd-soft-no-snapshot-"));
+  const project = join(dir, "project");
+  const gsdHomeDir = join(dir, "home");
+  const previousCwd = process.cwd();
+  const previousGsdHome = process.env.GSD_HOME;
+
+  mkdirSync(join(project, ".gsd"), { recursive: true });
+  mkdirSync(gsdHomeDir, { recursive: true });
+  writeFileSync(
+    join(project, ".gsd", "PREFERENCES.md"),
+    ["---", "version: 1", "context_management:", "  compaction_threshold_percent: 0.6", "---", ""].join("\n"),
+    "utf-8",
+  );
+
+  process.env.GSD_HOME = gsdHomeDir;
+  process.chdir(project);
+
+  const newSessionWorkspaces: string[] = [];
+  const notifyMessages: string[] = [];
+  let contextPercent = 72;
+  const cmdCtx = {
+    getContextUsage: () => ({ percent: contextPercent, tokens: contextPercent * 10_000, contextWindow: 1_000_000 }),
+    newSession: async ({ workspaceRoot }: { workspaceRoot: string }) => {
+      newSessionWorkspaces.push(workspaceRoot);
+      return { cancelled: false };
+    },
+  } as any;
+  const ctx = { ui: { notify: (msg: string) => notifyMessages.push(msg) } } as any;
+  const snapshotPath = join(project, ".gsd", "last-snapshot.md");
+
+  try {
+    const softResult = await maybeRerootStepSessionForHighContext(ctx, project, cmdCtx, project);
+    assert.equal(softResult.rerooted, false, "soft pressure must not re-root");
+    assert.deepEqual(newSessionWorkspaces, [], "soft pressure must not open a new session");
+    assert.equal(
+      existsSync(snapshotPath),
+      false,
+      "soft-only pressure must not write a compaction snapshot",
+    );
+    assert.equal(
+      notifyMessages.some((msg) => msg.includes("context at 72.0%") && msg.includes("Use /compact")),
+      true,
+      "soft threshold should warn with a non-disruptive compaction prompt",
+    );
+
+    contextPercent = 92;
+    const hardResult = await maybeRerootStepSessionForHighContext(ctx, project, cmdCtx, project);
+    assert.equal(hardResult.rerooted, true, "hard pressure must re-root");
+    assert.deepEqual(newSessionWorkspaces, [project], "hard pressure should re-root once");
+    assert.equal(
+      existsSync(snapshotPath),
+      true,
+      "hard boundary must write the compaction snapshot",
+    );
+  } finally {
+    process.chdir(previousCwd);
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("cleanupAfterLoopExit restores project root through lifecycle and preserves chdir", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-cleanup-lifecycle-"));
   const worktree = join(base, ".gsd", "worktrees", "M001");