@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -25,15 +25,13 @@ import {
   updateSliceStatus,
   insertSlice,
   getMilestone,
-  getMilestoneSlices,
-  getLatestAssessmentByScope,
   updateMilestoneStatus,
-  refreshOpenDatabaseFromDisk,
   getCompletedMilestoneTaskFileHints,
   getMilestoneCommitAttributionShas,
   recordMilestoneCommitAttribution,
   transaction,
 } from "./gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { isValidationTerminal } from "./state.js";
 import { getErrorMessage } from "./error-utils.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -59,7 +57,8 @@ import {
 } from "node:fs";
 import { execFileSync } from "node:child_process";
 
-import { dirname, join } from "node:path";
+import { LAYOUT_SEGMENTS } from "./layout-policy.js";
+import { dirname, join, resolve } from "node:path";
 import {
   resolveExpectedArtifactPath,
   diagnoseExpectedArtifact,
@@ -70,9 +69,13 @@ import { validateArtifact } from "./schemas/validate.js";
 import { getProjectResearchStatus } from "./project-research-policy.js";
 import { isGsdWorktreePath } from "./worktree-root.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { loadAllCaptures, loadPendingCaptures } from "./captures.js";
-import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
+import {
+  proveMilestoneCloseout,
+  type CloseoutProofFailureReason,
+} from "./milestone-closeout-proof.js";
 
 // Re-export so existing consumers of auto-recovery.ts keep working.
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
@@ -82,6 +85,53 @@ export {
 } from "./milestone-summary-classifier.js";
 export { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 
+/**
+ * Optional override for the legacy roadmap parser used by verifyExpectedArtifact.
+ * Production leaves this null so the real parseLegacyRoadmap runs; tests inject
+ * a throwing function to deterministically exercise the parse-failure catches
+ * (auto-recovery.ts:515 plan-milestone and :622 complete-slice). Those catches
+ * are otherwise unreachable because parseLegacyRoadmap is internally defensive
+ * against every malformed input.
+ * @internal
+ */
+let _roadmapParserFn: ((content: string) => { slices: Array<{ id: string; done: boolean; depends?: string[] }> }) | null = null;
+
+/**
+ * Inject an override for the legacy roadmap parser, returning a function that
+ * restores the default (real parser) behavior. No production caller.
+ * @internal
+ */
+export function _setRoadmapParserFnForTests(
+  fn: ((content: string) => { slices: Array<{ id: string; done: boolean; depends?: string[] }> }) | null,
+): () => void {
+  const previous = _roadmapParserFn;
+  _roadmapParserFn = fn;
+  return () => { _roadmapParserFn = previous; };
+}
+
+function parseRoadmapForRecovery(content: string): ReturnType<NonNullable<typeof _roadmapParserFn>> {
+  if (_roadmapParserFn) return _roadmapParserFn(content);
+  return parseLegacyRoadmap(content) as unknown as ReturnType<NonNullable<typeof _roadmapParserFn>>;
+}
+
+/**
+ * Optional override for the detached GitHub milestone finalize invoked after DB
+ * closeout in refreshRecoveryDbForArtifact. Production leaves this null so the
+ * real finalizeMilestoneGitHubSync runs; tests inject a throwing function to
+ * deterministically exercise the best-effort catch (auto-recovery.ts:232),
+ * which otherwise needs a real GitHub remote + network failure.
+ * @internal
+ */
+let _githubFinalizeFn: ((basePath: string, mid: string) => void | Promise<void>) | null = null;
+
+export function _setGithubFinalizeFnForTests(
+  fn: ((basePath: string, mid: string) => void | Promise<void>) | null,
+): () => void {
+  const previous = _githubFinalizeFn;
+  _githubFinalizeFn = fn;
+  return () => { _githubFinalizeFn = previous; };
+}
+
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
 
 export function diagnoseWorktreeIntegrityFailure(basePath: string): string | null {
@@ -117,6 +167,19 @@ export type ArtifactRecoveryDbRefreshResult =
   | { ok: true }
   | { ok: false; fatal: boolean; message: string; reason: string };
 
+function closeoutProofRecoveryReason(reason: CloseoutProofFailureReason): string {
+  switch (reason) {
+    case "slice-missing":
+      return "complete-milestone-slices-missing";
+    case "summary-artifact-missing":
+      return "complete-milestone-summary-missing";
+    case "summary-artifact-failed":
+      return "complete-milestone-summary-failed";
+    default:
+      return `complete-milestone-${reason}`;
+  }
+}
+
 export function refreshRecoveryDbForArtifact(
   unitType: string,
   unitId: string,
@@ -125,7 +188,7 @@ export function refreshRecoveryDbForArtifact(
   if (unitType !== "plan-slice" && unitType !== "execute-task" && unitType !== "complete-milestone") return { ok: true };
   if (!isDbAvailable()) return { ok: true };
 
-  if (!refreshOpenDatabaseFromDisk()) {
+  if (!refreshWorkflowDatabaseFromDisk()) {
     return {
       ok: false,
       fatal: unitType === "execute-task" || unitType === "complete-milestone",
@@ -156,61 +219,45 @@ export function refreshRecoveryDbForArtifact(
     }
     if (isClosedStatus(milestone.status)) return { ok: true };
 
-    const validation = getLatestAssessmentByScope(mid, "milestone-validation");
-    if (validation?.status !== "pass") {
-      return {
-        ok: false,
-        fatal: true,
-        reason: "complete-milestone-validation-not-pass",
-        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but milestone-validation is "${validation?.status ?? "absent"}" in the DB.`,
-      };
-    }
-
-    const slices = getMilestoneSlices(mid);
-    if (slices.length === 0) {
-      return {
-        ok: false,
-        fatal: true,
-        reason: "complete-milestone-slices-missing",
-        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but no slices exist in the DB.`,
-      };
-    }
-    const openSlice = slices.find((slice) => !isClosedStatus(slice.status));
-    if (openSlice) {
-      return {
-        ok: false,
-        fatal: true,
-        reason: "complete-milestone-slice-open",
-        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but slice ${openSlice.id} is still "${openSlice.status}" in the DB.`,
-      };
-    }
-    for (const slice of slices) {
-      const openTask = getSliceTasks(mid, slice.id).find((task) => !isClosedStatus(task.status));
-      if (openTask) {
+    const artifactBasePath = resolveArtifactVerificationBase(unitId, basePath);
+    const closeoutProof = proveMilestoneCloseout(mid, {
+      allowOpenMilestone: true,
+      summaryArtifactBasePath: artifactBasePath,
+      implementationEvidence: {
+        basePath,
+        requirement: "present",
+      },
+    });
+    if (!closeoutProof.ok) {
+      if (closeoutProof.reason === "implementation-evidence-missing") {
         return {
           ok: false,
           fatal: true,
-          reason: "complete-milestone-task-open",
-          message: `Stuck recovery found complete-milestone ${unitId} artifacts, but task ${slice.id}/${openTask.id} is still "${openTask.status}" in the DB.`,
+          reason: "complete-milestone-implementation-missing",
+          message: `Stuck recovery found complete-milestone ${unitId} artifacts, but implementation evidence is not present.`,
         };
       }
-    }
-
-    if (hasImplementationArtifacts(basePath, mid) !== "present") {
       return {
         ok: false,
         fatal: true,
-        reason: "complete-milestone-implementation-missing",
-        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but implementation evidence is not present.`,
+        reason: closeoutProofRecoveryReason(closeoutProof.reason),
+        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but ${closeoutProof.message}`,
       };
     }
 
     updateMilestoneStatus(mid, "complete", new Date().toISOString());
-    void import("../github-sync/sync.js")
-      .then(({ finalizeMilestoneGitHubSync }) => finalizeMilestoneGitHubSync(basePath, mid))
-      .catch((err) => {
-        logWarning("recovery", `GitHub milestone finalize failed after DB closeout: ${getErrorMessage(err)}`);
-      });
+    // Detached GitHub sync — best-effort. Test seam: when
+    // _githubFinalizeFn is injected, route through it so the catch
+    // (:232) is deterministically reachable (otherwise it needs a real
+    // GitHub remote + network failure). Production leaves it null. The
+    // seam is wrapped so a synchronous throw becomes a rejected promise,
+    // matching the real import-then-call deferred semantics.
+    const finalizePromise = _githubFinalizeFn
+      ? new Promise<void>((resolve) => { resolve(_githubFinalizeFn!(basePath, mid)); })
+      : import("../github-sync/sync.js").then(({ finalizeMilestoneGitHubSync }) => finalizeMilestoneGitHubSync(basePath, mid));
+    void finalizePromise.catch((err) => {
+      logWarning("recovery", `GitHub milestone finalize failed after DB closeout: ${getErrorMessage(err)}`);
+    });
     return { ok: true };
   }
 
@@ -276,15 +323,15 @@ function escapeRegExp(value: string): string {
 }
 
 function hasCheckedTaskCompletionOnDisk(base: string, mid: string, sid: string, tid: string): boolean {
-  const tasksDir = resolveTasksDir(base, mid, sid);
-  if (!tasksDir) return false;
-  if (!existsSync(join(tasksDir, `${tid}-SUMMARY.md`))) return false;
+  const slicePath = resolveSlicePath(base, mid, sid);
+  if (!slicePath) return false;
 
   const planAbs = resolveSliceFile(base, mid, sid, "PLAN");
   if (!planAbs || !existsSync(planAbs)) return false;
 
   const planContent = readFileSync(planAbs, "utf-8");
-  const cbRe = new RegExp(`^\\s*-\\s+\\[[xX]\\]\\s+\\*\\*${escapeRegExp(tid)}:`, "m");
+  // Match legacy (`**T01: Title**`) and flat-phase (`**T01**: Title`) checkbox lines.
+  const cbRe = new RegExp(`^\\s*-\\s+\\[[xX]\\]\\s+\\*\\*${escapeRegExp(tid)}(?:\\*\\*)?:`, "m");
   return cbRe.test(planContent);
 }
 
@@ -367,11 +414,13 @@ export function verifyExpectedArtifact(
     if (blockerPath && existsSync(blockerPath)) {
       return true;
     }
+    const slicePath = resolveSlicePath(base, mid, sid);
+    if (!slicePath) return false;
+
     const plusIdx = batchPart.indexOf("+");
     if (plusIdx === -1) {
       // Legacy format "reactive" without batch IDs — fall back to "any summary"
-      const tDir = resolveTasksDir(base, mid, sid);
-      if (!tDir) return false;
+      const tDir = resolveTasksDir(base, mid, sid) ?? slicePath;
       const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
       return summaryFiles.length > 0;
     }
@@ -379,8 +428,7 @@ export function verifyExpectedArtifact(
     const batchIds = batchPart.slice(plusIdx + 1).split(",").filter(Boolean);
     if (batchIds.length === 0) return false;
 
-    const tDir = resolveTasksDir(base, mid, sid);
-    if (!tDir) return false;
+    const tDir = resolveTasksDir(base, mid, sid) ?? slicePath;
 
     const existingSummaries = new Set(
       resolveTaskFiles(tDir, "SUMMARY").map((f) =>
@@ -455,7 +503,7 @@ export function verifyExpectedArtifact(
       return false;
     }
     try {
-      const roadmap = parseLegacyRoadmap(readFileSync(roadmapFile, "utf-8"));
+      const roadmap = parseRoadmapForRecovery(readFileSync(roadmapFile, "utf-8"));
       const milestoneResearchFile = resolveExpectedArtifactPath("research-milestone", mid, base);
       const hasMilestoneResearch = !!milestoneResearchFile && existsSync(milestoneResearchFile);
       for (const slice of roadmap.slices) {
@@ -480,7 +528,33 @@ export function verifyExpectedArtifact(
   }
 
   const artifactBase = resolveArtifactVerificationBase(unitId, base);
-  const absPath = resolveExpectedArtifactPath(unitType, unitId, artifactBase);
+  let absPath = resolveExpectedArtifactPath(unitType, unitId, artifactBase);
+  // Worktree→project-root fallback: a milestone running in a worktree may not
+  // have its CONTEXT/ROADMAP/SUMMARY projected into the worktree yet (the
+  // worktree only has the META dir until planning writes its projections).
+  // When the worktree base yields null or a non-existent path, fall back to the
+  // project root — where the artifact genuinely lives. Without this, a
+  // discuss-milestone unit with CONTEXT at phases/NN-slug/ in the project root
+  // but not in the worktree resolves to null → "resolveExpectedArtifactPath
+  // returned null" → finalize-retry loop (#852).
+  //
+  // #870: the fallback must fire whenever the artifact is missing at
+  // `artifactBase`, NOT only when `artifactBase !== base`. When the real call
+  // site passes the worktree path as `base` (auto-post-unit.ts:1726 uses
+  // `s.currentUnit.workspaceRoot ?? s.basePath`), resolveCanonicalMilestoneRoot
+  // round-trips the worktree path back to itself, so `artifactBase === base`
+  // while still being a worktree path that lacks the projected artifact. The
+  // old `if (artifactBase !== base)` guard skipped the fallback in exactly that
+  // case, stranding CONTEXT at the project root and producing a stuck-loop.
+  if (!absPath || !existsSync(absPath)) {
+    const projectRoot = resolve(resolveWorktreeProjectRoot(artifactBase));
+    if (projectRoot && projectRoot !== artifactBase) {
+      const projectPath = resolveExpectedArtifactPath(unitType, unitId, projectRoot);
+      if (projectPath && existsSync(projectPath)) {
+        absPath = projectPath;
+      }
+    }
+  }
   // For unit types with no registered artifact contract (null path), treat the
   // completion state as stale so the key gets evicted (#313).
   if (!absPath) {
@@ -515,7 +589,7 @@ export function verifyExpectedArtifact(
 
   if (unitType === "plan-milestone") {
     try {
-      const roadmap = parseLegacyRoadmap(readFileSync(absPath, "utf-8"));
+      const roadmap = parseRoadmapForRecovery(readFileSync(absPath, "utf-8"));
       if (roadmap.slices.length === 0) {
         logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap has zero slices at ${absPath}`);
         return false;
@@ -534,11 +608,15 @@ export function verifyExpectedArtifact(
     if (mid && sid) {
       try {
         let taskIds: string[] | null = null;
+        let dbPrimary = false;
         if (isDbAvailable()) {
-          const refreshed = refreshOpenDatabaseFromDisk();
+          const refreshed = refreshWorkflowDatabaseFromDisk();
           if (refreshed) {
             const tasks = getSliceTasks(mid, sid);
-            if (tasks.length > 0) taskIds = tasks.map(t => t.id);
+            if (tasks.length > 0) {
+              taskIds = tasks.map(t => t.id);
+              dbPrimary = true;
+            }
           }
         }
 
@@ -546,7 +624,7 @@ export function verifyExpectedArtifact(
           // LEGACY: DB unavailable or no tasks in DB. Require actual task
           // entries so an empty scaffold cannot advance the pipeline (#699).
           const planContent = readFileSync(absPath, "utf-8");
-          const hasCheckboxTask = /^\s*- \[[xX ]\] \*\*T\d+:/m.test(planContent);
+          const hasCheckboxTask = /^\s*- \[[xX ]\] \*\*T\d+/m.test(planContent);
           const hasHeadingTask = /^\s*#{2,4}\s+T\d+\s*(?:--|—|:)/m.test(planContent);
           if (!hasCheckboxTask && !hasHeadingTask) {
             logWarning("recovery", `verify-fail ${unitType} ${unitId}: plan has no task checkbox/heading (len=${planContent.length}) at ${absPath}`);
@@ -556,19 +634,26 @@ export function verifyExpectedArtifact(
           if (plan.tasks.length > 0) taskIds = plan.tasks.map((t: { id: string }) => t.id);
         }
 
+        // Per-task plan file check: applies when a tasks/ directory is present on
+        // disk (legacy layout), regardless of whether DB is primary. Flat-phase
+        // projects have no tasks/ dir, so the check is naturally skipped there.
+        // When DB is NOT primary and there is no tasks/ dir either, the missing
+        // dir itself is evidence of an incomplete plan (non-flat-phase projects must
+        // have a tasks/ dir).
         if (taskIds && taskIds.length > 0) {
           const tasksDir = join(dirname(absPath), "tasks");
-          if (!existsSync(tasksDir)) {
+          if (existsSync(tasksDir)) {
+            for (const tid of taskIds) {
+              const taskPlanFile = join(tasksDir, `${tid}-PLAN.md`);
+              if (!existsSync(taskPlanFile)) {
+                logWarning("recovery", `verify-fail ${unitType} ${unitId}: task plan missing ${taskPlanFile}`);
+                return false;
+              }
+            }
+          } else if (!dbPrimary && !absPath.replace(/\\/g, "/").includes(`.gsd/${LAYOUT_SEGMENTS.level1}`)) {
             logWarning("recovery", `verify-fail ${unitType} ${unitId}: tasks dir missing at ${tasksDir}`);
             return false;
           }
-          for (const tid of taskIds) {
-            const taskPlanFile = join(tasksDir, `${tid}-PLAN.md`);
-            if (!existsSync(taskPlanFile)) {
-              logWarning("recovery", `verify-fail ${unitType} ${unitId}: task plan missing ${taskPlanFile}`);
-              return false;
-            }
-          }
         }
       } catch (err) {
         // Parse failure — don't block; slice plan may have non-standard format
@@ -607,11 +692,12 @@ export function verifyExpectedArtifact(
   if (unitType === "complete-slice") {
     const { milestone: mid, slice: sid } = parseUnitId(unitId);
     if (mid && sid) {
-      const dir = resolveSlicePath(base, mid, sid);
-      if (dir) {
-        const uatPath = join(dir, buildSliceFileName(sid, "UAT"));
-        if (!existsSync(uatPath)) return false;
-      }
+      // resolveSliceFile only finds existing files; UAT may not exist yet.
+      // Fall back to the canonical expected location so a missing UAT always
+      // returns false (not a silent pass when resolveSliceFile returns null).
+      const uatPath = resolveSliceFile(base, mid, sid, "UAT")
+        ?? join(base, relSliceFile(base, mid, sid, "UAT"));
+      if (!existsSync(uatPath)) return false;
 
       const dbSlice = getSlice(mid, sid);
       if (dbSlice) {
@@ -624,7 +710,7 @@ export function verifyExpectedArtifact(
         if (roadmapFile && existsSync(roadmapFile)) {
           try {
             const roadmapContent = readFileSync(roadmapFile, "utf-8");
-            const roadmap = parseLegacyRoadmap(roadmapContent);
+            const roadmap = parseRoadmapForRecovery(roadmapContent);
             const slice = roadmap.slices.find((s) => s.id === sid);
             if (slice && !slice.done) return false;
           } catch (e) {
@@ -642,14 +728,23 @@ export function verifyExpectedArtifact(
   // A milestone with only .gsd/ plan files and zero implementation code is
   // not genuinely complete — the LLM wrote plan files but skipped actual work.
   if (unitType === "complete-milestone") {
-    const summaryOutcome = classifyMilestoneSummaryContent(readFileSync(absPath, "utf-8"));
-    if (summaryOutcome === "failure") return false;
     const { milestone: mid } = parseUnitId(unitId);
-    if (mid && isDbAvailable()) {
-      const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
-      if (!closeoutGate.ok) return false;
+    if (!mid) return false;
+    const closeoutProof = proveMilestoneCloseout(mid, {
+      refreshFromDisk: true,
+      summaryArtifactBasePath: artifactBase,
+      implementationEvidence: {
+        basePath: base,
+        requirement: "not-absent",
+      },
+    });
+    if (!closeoutProof.ok) {
+      if (!isDbAvailable() && closeoutProof.reason === "db-unavailable") {
+        const summaryOutcome = classifyMilestoneSummaryContent(readFileSync(absPath, "utf-8"));
+        return summaryOutcome !== "failure" && hasImplementationArtifacts(base, mid) !== "absent";
+      }
+      return false;
     }
-    if (hasImplementationArtifacts(base, mid) === "absent") return false;
   }
 
   return true;
@@ -687,11 +782,12 @@ export function writeReactiveExecuteBlocker(
   const blockerPath = resolveExpectedArtifactPath("reactive-execute", unitId, base);
   if (!blockerPath) return null;
 
-  const tasksDir = resolveTasksDir(base, mid, sid);
+  const slicePath = resolveSlicePath(base, mid, sid);
+  if (!slicePath) return null;
+
+  const tasksDir = resolveTasksDir(base, mid, sid) ?? slicePath;
   const existingSummaries = new Set(
-    tasksDir
-      ? resolveTaskFiles(tasksDir, "SUMMARY").map((f) => f.replace(/-SUMMARY\.md$/i, "").toUpperCase())
-      : [],
+    resolveTaskFiles(tasksDir, "SUMMARY").map((f) => f.replace(/-SUMMARY\.md$/i, "").toUpperCase()),
   );
 
   const summaryPresent = batchIds.filter((tid) => existingSummaries.has(tid.toUpperCase()));

package/src/resources/extensions/gsd/auto-runtime-state.ts

@@ -9,8 +9,23 @@ import {
   markToolEnd as markTrackedToolEnd,
   markToolStart as markTrackedToolStart,
 } from "./auto-tool-tracking.js";
+// Re-exported as a pure pass-through. Must stay UNGATED (no autoSession.active
+// argument, unlike markToolStart at the bottom of this file) so it is true in
+// foreground where the foreground approval-gate pause consults it.
+export { isInteractiveElicitationInFlight } from "./auto-tool-tracking.js";
+import {
+  createToolSurfaceSnapshot,
+  type ToolSurfaceSnapshot,
+  type ToolSurfaceSnapshotInput,
+} from "./tool-surface-snapshot.js";
+
+export type {
+  ToolSurfaceSnapshot,
+  ToolSurfaceSnapshotInput,
+} from "./tool-surface-snapshot.js";
 
 export const autoSession = new AutoSession();
+let currentToolSurfaceSnapshot: ToolSurfaceSnapshot | null = null;
 
 export type AutoRuntimeSnapshot = {
   active: boolean;
@@ -20,6 +35,7 @@ export type AutoRuntimeSnapshot = {
   orchestrationPhase?: "idle" | "running" | "paused" | "stopped" | "error";
   orchestrationTransitionCount?: number;
   orchestrationLastTransitionAt?: number;
+  toolSurface: ToolSurfaceSnapshot | null;
 };
 
 export function getAutoRuntimeSnapshot(): AutoRuntimeSnapshot {
@@ -32,13 +48,36 @@ export function getAutoRuntimeSnapshot(): AutoRuntimeSnapshot {
     orchestrationPhase: orchestrationStatus?.phase,
     orchestrationTransitionCount: orchestrationStatus?.transitionCount,
     orchestrationLastTransitionAt: orchestrationStatus?.lastTransitionAt,
+    toolSurface: autoSession.active || autoSession.paused ? currentToolSurfaceSnapshot : null,
   };
 }
 
+export function recordAutoToolSurfaceSnapshot(input: ToolSurfaceSnapshotInput): ToolSurfaceSnapshot {
+  currentToolSurfaceSnapshot = createToolSurfaceSnapshot(input);
+  return currentToolSurfaceSnapshot;
+}
+
+export function clearAutoToolSurfaceSnapshot(): void {
+  currentToolSurfaceSnapshot = null;
+}
+
 export function isAutoActive(): boolean {
   return autoSession.active;
 }
 
+/**
+ * The unit type of the unit auto-mode is currently dispatching, or undefined
+ * when auto is inactive or between units. This is the authoritative phase
+ * signal for auto-mode (set in auto/unit-phase.ts before each dispatch), so
+ * consumers never have to regex-infer the phase from prompt text. Can be a
+ * `hook/<name>` pseudo-type during hook dispatch — callers that need a real
+ * GSD phase should validate against their known phase set.
+ */
+export function getActiveAutoUnitType(): string | undefined {
+  if (!autoSession.active) return undefined;
+  return autoSession.currentUnit?.type ?? undefined;
+}
+
 export function isAutoPaused(): boolean {
   return autoSession.paused;
 }