@opengsd/gsd-pi 1.9.0-dev.e10b60d4 → 1.10.0-dev.a5e42e99

package/src/resources/extensions/gsd/preferences-models.ts

@@ -9,6 +9,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { getProviders } from "@gsd/pi-ai";
 import { gsdHome } from "./gsd-home.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { canonicalModelForTier, defaultRoutingConfig, resolveModelForTier } from "./model-router.js";
@@ -31,6 +32,33 @@ import { getUnitPhaseChain } from "./unit-registry.js";
 // Re-export types so existing consumers of ./preferences-models.js keep working
 export type { GSDPhaseModelConfig, GSDModelConfig, GSDModelConfigV2, ResolvedModelConfig } from "./preferences-types.js";
 
+type ProviderModelRegistry = {
+  getAll?: () => ReadonlyArray<{ provider: string }>;
+  getAvailable?: () => ReadonlyArray<{ provider: string }>;
+  getAllWithDiscovered?: () => ReadonlyArray<{ provider: string }>;
+};
+
+/**
+ * First-party providers shipped as bundled extensions that delegate to a
+ * vendor CLI (`authMode: "externalCli"`). They are registered into the live
+ * model registry at runtime, so they are absent from the generated `@gsd/pi-ai`
+ * catalog (`getProviders()`), but they are NOT custom: `PREFERENCES.md` can
+ * route to them, so they must defer to `PREFERENCES.md` like any other built-in
+ * provider. Without this exclusion the registry check below would classify the
+ * default `claude-code` provider (and the other CLI providers) as custom and
+ * silently skip `PREFERENCES.md` in auto-mode (#801, extends #4122).
+ *
+ * Kept in sync with the `registerProvider(...)` calls in the bundled CLI
+ * extensions (claude-code-cli, cursor-cli, google-cli). Names are lowercase for
+ * direct comparison against normalized provider ids.
+ */
+const BUILTIN_EXTENSION_PROVIDERS: ReadonlySet<string> = new Set([
+  "claude-code",
+  "cursor-agent",
+  "google-gemini-cli",
+  "google-antigravity",
+]);
+
 /**
  * Resolve which model ID to use for a given auto-mode unit type.
  * Returns undefined if no model preference is set for this unit type.
@@ -321,9 +349,8 @@ export function resolveDefaultSessionModel(
 }
 
 /**
- * Returns true if `provider` is defined as a custom provider in the user's
- * `~/.gsd/agent/models.json` (Ollama, vLLM, LM Studio, OpenAI-compatible
- * proxies, etc.).
+ * Returns true if `provider` is a custom provider. Custom providers may be
+ * declared in `models.json` or registered dynamically by a Pi extension.
  *
  * Used by auto-mode bootstrap to decide whether the session model
  * (set via `/gsd model`) should override `PREFERENCES.md`.  Custom providers
@@ -332,13 +359,16 @@ export function resolveDefaultSessionModel(
  * priority — otherwise auto-mode tries to start the built-in provider from
  * PREFERENCES.md and fails with "Not logged in · Please run /login" (#4122).
  *
- * Reads models.json directly with a lightweight JSON parse to avoid
- * pulling in the full model-registry at this call site.  Falls back to
- * `~/.pi/agent/models.json` for parity with `resolveModelsJsonPath()`.
- * Any read or parse error yields `false` (treat as not-custom) so a
- * malformed models.json never breaks the session bootstrap.
+ * Reads models.json directly with a lightweight JSON parse, then checks the
+ * live model registry for extension-registered providers that are not in the
+ * generated built-in provider catalog (`getProviders()`) and not one of the
+ * bundled external-CLI providers (`BUILTIN_EXTENSION_PROVIDERS`, e.g.
+ * `claude-code`), which register at runtime but are still built-in.  Falls back
+ * to `~/.pi/agent/models.json` for parity with `resolveModelsJsonPath()`. Any
+ * read, parse, or registry error yields `false` (treat as not-custom) so
+ * bootstrap stays non-fatal.
  */
-export function isCustomProvider(provider: string | undefined): boolean {
+export function isCustomProvider(provider: string | undefined, registry?: ProviderModelRegistry): boolean {
   if (!provider) return false;
   const candidates = [
     join(gsdHome(), "agent", "models.json"),
@@ -356,7 +386,21 @@ export function isCustomProvider(provider: string | undefined): boolean {
       // Ignore — malformed models.json must not break bootstrap.
     }
   }
-  return false;
+  try {
+    const normalizedProvider = provider.trim().toLowerCase();
+    if (!normalizedProvider) return false;
+    if (BUILTIN_EXTENSION_PROVIDERS.has(normalizedProvider)) return false;
+    const builtInProviders = new Set(getProviders().map((p) => p.toLowerCase()));
+    if (builtInProviders.has(normalizedProvider)) return false;
+    const registryModels =
+      registry?.getAllWithDiscovered?.()
+      ?? registry?.getAll?.()
+      ?? registry?.getAvailable?.()
+      ?? [];
+    return registryModels.some((m) => m.provider.toLowerCase() === normalizedProvider);
+  } catch {
+    return false;
+  }
 }
 
 /**

package/src/resources/extensions/gsd/preferences-types.ts

@@ -141,6 +141,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "git",
   "post_unit_hooks",
   "pre_dispatch_hooks",
+  "planning_subagent_registry",
   "planning_subagents",
   "dynamic_routing",
   "disabled_model_providers",
@@ -232,6 +233,12 @@ export type PlanningSubagentsConfig = Partial<
   Record<ConfigurablePlanningSubagentUnit, PlanningSubagentUnitConfig>
 >;
 
+export interface PlanningSubagentRegistryEntry {
+  read_only_specialist?: boolean;
+}
+
+export type PlanningSubagentRegistryConfig = Record<string, PlanningSubagentRegistryEntry>;
+
 
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
 
@@ -245,10 +252,10 @@ export interface GSDSkillRule {
 /**
  * Reasoning effort levels. Mirrors `ThinkingLevel` in `@gsd/pi-agent-core`;
  * declared locally so preference parsing/validation does not import the agent
- * core package. `xhigh` is only honored by models whose `thinkingLevelMap`
+ * core package. `xhigh` and `max` are only honored by models whose `thinkingLevelMap`
  * advertises it — unsupported levels are clamped at dispatch (ADR-026).
  */
-export type GSDThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export type GSDThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 /** The nine model-routing phase buckets. */
 export const GSD_MODEL_PHASE_KEYS = [
@@ -491,6 +498,7 @@ export interface GSDPreferences {
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
+  planning_subagent_registry?: PlanningSubagentRegistryConfig;
   planning_subagents?: PlanningSubagentsConfig;
   dynamic_routing?: DynamicRoutingConfig;
   /** Provider IDs to exclude from /model and automatic model routing while leaving tool auth intact. */

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -28,8 +28,8 @@ import {
   type GSDThinkingLevel,
 } from "./preferences-types.js";
 import {
-  ALLOWED_PLANNING_DISPATCH_AGENTS,
   allowedPlanningDispatchAgentsList,
+  isReadOnlyPlanningDispatchAgent,
 } from "./planning-subagent-registry.js";
 
 const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality", "burn-max"]);
@@ -40,6 +40,7 @@ const VALID_THINKING_LEVELS = new Set<GSDThinkingLevel>([
   "medium",
   "high",
   "xhigh",
+  "max",
 ]);
 const KNOWN_MODEL_PHASE_KEYS = new Set<string>(GSD_MODEL_PHASE_KEYS);
 const VALID_UOK_TURN_ACTIONS = new Set<"commit" | "snapshot" | "status-only">([
@@ -93,7 +94,7 @@ function sanitizeModelField(
       } else {
         warnings?.push(
           `${label} thinking "${String(obj.thinking)}" is not a valid thinking level ` +
-          `(off, minimal, low, medium, high, xhigh) — ignored`,
+          `(off, minimal, low, medium, high, xhigh, max) — ignored`,
         );
       }
     }
@@ -486,7 +487,7 @@ export function validatePreferences(preferences: GSDPreferences): {
           if (level !== undefined && !VALID_THINKING_LEVELS.has(level as GSDThinkingLevel)) {
             warnings.push(
               `models.${phase}.thinking "${String(level)}" is not a valid thinking level ` +
-              `(off, minimal, low, medium, high, xhigh) — ignored`,
+              `(off, minimal, low, medium, high, xhigh, max) — ignored`,
             );
             const { thinking: _ignored, ...rest } = entry as Record<string, unknown>;
             // If stripping the bad thinking leaves no usable model, drop the
@@ -521,7 +522,7 @@ export function validatePreferences(preferences: GSDPreferences): {
         if (!VALID_THINKING_LEVELS.has(level as GSDThinkingLevel)) {
           warnings.push(
             `thinking.${phase} "${String(level)}" is not a valid thinking level ` +
-            `(off, minimal, low, medium, high, xhigh) — ignored`,
+            `(off, minimal, low, medium, high, xhigh, max) — ignored`,
           );
           continue;
         }
@@ -752,6 +753,46 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Planning Subagent Registry ──────────────────────────────────────────
+  if (preferences.planning_subagent_registry !== undefined) {
+    if (
+      !preferences.planning_subagent_registry ||
+      typeof preferences.planning_subagent_registry !== "object" ||
+      Array.isArray(preferences.planning_subagent_registry)
+    ) {
+      errors.push("planning_subagent_registry must be an object keyed by agent id");
+    } else {
+      const validRegistry: NonNullable<GSDPreferences["planning_subagent_registry"]> = {};
+
+      for (const [rawAgentId, rawConfig] of Object.entries(preferences.planning_subagent_registry as Record<string, unknown>)) {
+        const agentId = rawAgentId.trim();
+        if (!agentId) {
+          errors.push("planning_subagent_registry includes an empty agent id");
+          continue;
+        }
+        if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) {
+          errors.push(`planning_subagent_registry.${agentId} must be an object with read_only_specialist: true`);
+          continue;
+        }
+
+        const readOnlySpecialist = (rawConfig as Record<string, unknown>).read_only_specialist;
+        if (readOnlySpecialist !== true) {
+          errors.push(
+            `planning_subagent_registry.${agentId}.read_only_specialist must be true to classify ` +
+            `"${agentId}" as a read-only planning specialist`,
+          );
+          continue;
+        }
+
+        validRegistry[agentId] = { read_only_specialist: true };
+      }
+
+      if (Object.keys(validRegistry).length > 0) {
+        validated.planning_subagent_registry = validRegistry;
+      }
+    }
+  }
+
   // ─── Planning Subagents ─────────────────────────────────────────────────
   if (preferences.planning_subagents !== undefined) {
     if (
@@ -785,10 +826,12 @@ export function validatePreferences(preferences: GSDPreferences): {
 
         const sanitizedAllowed: string[] = [];
         for (const agentId of allowed) {
-          if (!ALLOWED_PLANNING_DISPATCH_AGENTS.has(agentId)) {
+          if (!isReadOnlyPlanningDispatchAgent(agentId, validated.planning_subagent_registry)) {
             errors.push(
               `planning_subagents.${unitType}.allowed includes "${agentId}", which is not classified as a ` +
-              `read-only planning specialist. Allowed agents: ${allowedPlanningDispatchAgentsList()}`,
+              `read-only planning specialist. Allowed agents: ` +
+              `${allowedPlanningDispatchAgentsList(validated.planning_subagent_registry)}. ` +
+              `For custom planning agents, add planning_subagent_registry.${agentId}.read_only_specialist: true`,
             );
             continue;
           }

package/src/resources/extensions/gsd/preferences.ts

@@ -817,6 +817,10 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
       : undefined,
     post_unit_hooks: mergePostUnitHooks(base.post_unit_hooks, override.post_unit_hooks),
     pre_dispatch_hooks: mergePreDispatchHooks(base.pre_dispatch_hooks, override.pre_dispatch_hooks),
+    planning_subagent_registry: mergePlanningSubagentRegistry(
+      base.planning_subagent_registry,
+      override.planning_subagent_registry,
+    ),
     planning_subagents: mergePlanningSubagents(base.planning_subagents, override.planning_subagents),
     dynamic_routing: (base.dynamic_routing || override.dynamic_routing)
       ? { ...(base.dynamic_routing ?? {}), ...(override.dynamic_routing ?? {}) } as DynamicRoutingConfig
@@ -968,6 +972,15 @@ function mergePlanningSubagents(
   return Object.keys(merged).length > 0 ? merged : undefined;
 }
 
+function mergePlanningSubagentRegistry(
+  base?: GSDPreferences["planning_subagent_registry"],
+  override?: GSDPreferences["planning_subagent_registry"],
+): GSDPreferences["planning_subagent_registry"] | undefined {
+  if (!base && !override) return undefined;
+  const merged = { ...(base ?? {}), ...(override ?? {}) };
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
 // ─── System Prompt Rendering ──────────────────────────────────────────────────
 
 export function renderPreferencesForSystemPrompt(

package/src/resources/extensions/gsd/templates/PREFERENCES.md

@@ -92,6 +92,9 @@ remote_questions:
 uat_dispatch:
 post_unit_hooks: []
 pre_dispatch_hooks: []
+# planning_subagent_registry:
+#   my-custom-planner:
+#     read_only_specialist: true
 # planning_subagents:
 #   plan-milestone:
 #     allowed: [scout, planner, security]

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

@@ -41,6 +41,7 @@ import { claimMilestoneLease } from "../db/milestone-leases.js";
 import { recordDispatchClaim, markCanceled } from "../db/unit-dispatches.js";
 import { setRuntimeKv, getRuntimeKv } from "../db/runtime-kv.js";
 import { SourceObservationStore } from "../source-observations.js";
+import { autoCommitCurrentBranch } from "../worktree.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -832,6 +833,37 @@ test("runUnit returns cancelled when session creation fails", async () => {
   assert.equal(pi.calls.length, 0);
 });
 
+test("runUnit returns cancelled when command context lacks newSession", async () => {
+  _resetPendingResolve();
+
+  const ctx = {
+    ...makeMockCtx(),
+    ui: {
+      notify: () => {},
+      setStatus: () => {},
+      setWorkingMessage: () => {},
+    },
+    sessionManager: {
+      getEntries: () => [],
+    },
+    modelRegistry: {
+      getProviderAuthMode: () => undefined,
+      isProviderRequestReady: () => true,
+    },
+  } as any;
+  const pi = makeMockPi();
+  const s = makeMockSession();
+  s.cmdCtx = {} as any;
+
+  const result = await runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.errorContext?.category, "session-failed");
+  assert.equal(result.errorContext?.isTransient, false);
+  assert.match(result.errorContext?.message ?? "", /missing newSession/);
+  assert.equal(pi.calls.length, 0);
+});
+
 test("runUnit: TypeError from newSession is classified as structural (isTransient: false)", async () => {
   // Regression for #572: a TypeError thrown from newSession (e.g. "something is
   // not a function") indicates a programming error, not a transient provider
@@ -1582,6 +1614,130 @@ test("autoLoop exits when s.active is set to false", async (t) => {
   );
 });
 
+test("autoLoop stops before dispatch when command context lacks newSession", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.ui.setStatus = () => {};
+  const pi = makeMockPi();
+  const s = makeLoopSession({
+    cmdCtx: {
+      getContextUsage: () => ({ percent: 10, tokens: 1000, limit: 10000 }),
+    },
+  });
+  let stopReason: string | undefined;
+  let preserveWorktree: boolean | undefined;
+  let deriveCalled = false;
+
+  try {
+    const deps = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason, options) => {
+        stopReason = reason;
+        preserveWorktree = options?.preserveWorktree;
+        s.active = false;
+      },
+      deriveState: async () => {
+        deriveCalled = true;
+        throw new Error("deriveState should not run without command session support");
+      },
+    });
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.equal(stopReason, "Auto-mode has no command context for dispatch.");
+    assert.equal(preserveWorktree, true);
+    assert.equal(deriveCalled, false);
+    assert.equal(pi.calls.length, 0);
+  } finally {
+    rmSync(s.basePath, { recursive: true, force: true });
+  }
+});
+
+test("autoLoop commits open unit work when command context lacks newSession", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.ui.setStatus = () => {};
+  const pi = makeMockPi();
+  const s = makeLoopSession({
+    cmdCtx: {
+      getContextUsage: () => ({ percent: 10, tokens: 1000, limit: 10000 }),
+    },
+    currentUnit: { type: "execute-task", id: "T01", startedAt: Date.now() },
+  });
+  const outputPath = join(s.basePath, "executor-output.txt");
+  let autoCommitArgs: { unitType: string; unitId: string } | undefined;
+  let preserveWorktree: boolean | undefined;
+
+  try {
+    const deps = makeMockDeps({
+      autoCommitUnit: async (basePath, unitType, unitId) => {
+        autoCommitArgs = { unitType, unitId };
+        return autoCommitCurrentBranch(basePath, unitType, unitId);
+      },
+      stopAuto: async (_ctx, _pi, _reason, options) => {
+        preserveWorktree = options?.preserveWorktree;
+        s.active = false;
+      },
+      deriveState: async () => {
+        throw new Error("deriveState should not run without command session support");
+      },
+    });
+
+    writeFileSync(outputPath, "open unit work before stop\n", "utf-8");
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.deepEqual(autoCommitArgs, { unitType: "execute-task", unitId: "T01" });
+    assert.equal(preserveWorktree, true);
+    const committed = execSync("git show HEAD:executor-output.txt", {
+      cwd: s.basePath,
+      encoding: "utf-8",
+    });
+    assert.equal(committed, "open unit work before stop\n");
+    assert.equal(pi.calls.length, 0);
+  } finally {
+    rmSync(s.basePath, { recursive: true, force: true });
+  }
+});
+
+test("autoLoop snapshots dirty work when unit dispatch crashes", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.ui.setStatus = () => {};
+  const pi = makeMockPi();
+  const s = makeLoopSession();
+  const outputPath = join(s.basePath, "executor-output.txt");
+  let autoCommitCalls = 0;
+
+  try {
+    const deps = makeMockDeps({
+      ensurePreconditions: () => {
+        writeFileSync(outputPath, "saved before crash\n", "utf-8");
+        throw new Error("dispatch crash after file write");
+      },
+      autoCommitUnit: async (basePath, unitType, unitId) => {
+        autoCommitCalls++;
+        const commitMsg = autoCommitCurrentBranch(basePath, unitType, unitId);
+        s.active = false;
+        return commitMsg;
+      },
+    });
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.equal(autoCommitCalls, 1);
+    const committed = execSync("git show HEAD:executor-output.txt", {
+      cwd: s.basePath,
+      encoding: "utf-8",
+    });
+    assert.equal(committed, "saved before crash\n");
+  } finally {
+    rmSync(s.basePath, { recursive: true, force: true });
+  }
+});
+
 test("autoLoop pauses visibly when Auto Orchestration Module is not wired", async () => {
   _resetPendingResolve();
 

package/src/resources/extensions/gsd/tests/auto-start-index-lock.test.ts

@@ -4,7 +4,7 @@ import { existsSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { hasGitIndexLockForTest } from "../auto-start.ts";
+import { hasGitIndexLockForTest, reconcileFlatPhaseBootstrapLayout } from "../auto-start.ts";
 
 test("bootstrapAutoSession detects .git/index.lock without deleting it", (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-index-lock-"));
@@ -24,3 +24,23 @@ test("bootstrapAutoSession reports no index lock when the lock file is absent",
 
   assert.equal(hasGitIndexLockForTest(base), false);
 });
+
+test("bootstrapAutoSession removes empty legacy milestones dir in flat-phase projects", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-flat-bootstrap-clean-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+  mkdirSync(join(base, ".gsd", "phases"), { recursive: true });
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+
+  assert.equal(reconcileFlatPhaseBootstrapLayout(base), true);
+  assert.equal(existsSync(join(base, ".gsd", "phases")), true);
+  assert.equal(existsSync(join(base, ".gsd", "milestones")), false);
+});
+
+test("bootstrapAutoSession creates phases instead of milestones for empty GSD state", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-flat-bootstrap-init-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  assert.equal(reconcileFlatPhaseBootstrapLayout(base), true);
+  assert.equal(existsSync(join(base, ".gsd", "phases")), true);
+  assert.equal(existsSync(join(base, ".gsd", "milestones")), false);
+});

package/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts

@@ -3,7 +3,8 @@
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, realpathSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -96,6 +97,78 @@ describe("hook dispatch session workspace root", () => {
     assert.equal(dispatched, true);
     assert.deepEqual(newSessionOptions, { workspaceRoot: basePath });
   });
+
+  test("dispatchHookUnit commits in-flight work when command context lacks newSession", async (t) => {
+    const originalCwd = process.cwd();
+    const basePath = realpathSync(mkdtempSync(join(tmpdir(), "gsd-hook-nosnap-")));
+    mkdirSync(join(basePath, ".gsd"), { recursive: true });
+    execSync("git init --initial-branch=main", { cwd: basePath, stdio: "ignore" });
+    execSync("git config user.email test@test.com", { cwd: basePath, stdio: "ignore" });
+    execSync("git config user.name Test", { cwd: basePath, stdio: "ignore" });
+    execSync("git commit --allow-empty -m init", { cwd: basePath, stdio: "ignore" });
+
+    autoSession.reset();
+    autoSession.active = true;
+    autoSession.basePath = basePath;
+    autoSession.originalBasePath = basePath;
+    // Simulate an in-flight unit whose executor already wrote files, then a hook
+    // fires with a command context missing newSession.
+    autoSession.currentUnit = {
+      type: "execute-task",
+      id: "M001/S01/T01",
+      startedAt: Date.now(),
+    };
+    t.after(() => {
+      try {
+        process.chdir(originalCwd);
+      } catch {
+        // best effort cleanup after cwd-sensitive dispatch tests
+      }
+      autoSession.reset();
+      rmSync(basePath, { recursive: true, force: true });
+    });
+
+    const outputPath = join(basePath, "executor-output.txt");
+    writeFileSync(outputPath, "in-flight executor work\n", "utf-8");
+
+    // Command context intentionally lacks newSession — the guard must snapshot
+    // the dirty work before stopping instead of discarding it.
+    const ctx = {
+      ui: {
+        notify: () => {},
+        setStatus: () => {},
+        setWidget: () => {},
+      },
+      modelRegistry: {
+        getAvailable: () => [],
+      },
+      sessionManager: {
+        getSessionFile: () => join(basePath, "session.jsonl"),
+      },
+    };
+    const pi = {
+      sendMessage: () => {},
+      setModel: async () => true,
+    };
+
+    const dispatched = await dispatchHookUnit(
+      ctx as any,
+      pi as any,
+      "review",
+      "execute-task",
+      "M001/S01/T01",
+      "review the completed unit",
+      undefined,
+      basePath,
+    );
+
+    assert.equal(dispatched, false);
+    const committed = execSync("git show HEAD:executor-output.txt", {
+      cwd: basePath,
+      encoding: "utf-8",
+    });
+    assert.equal(committed, "in-flight executor work\n");
+  });
 });
 
 describe("deep setup approval questions pause immediately", () => {