@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.6ccd27b3

package/src/resources/extensions/gsd/roadmap-slices.ts

@@ -154,6 +154,29 @@ function parseTableSlices(section: string): RoadmapSliceEntry[] {
   return slices;
 }
 
+function looksLikeTable(section: string): boolean {
+  const lines = section.split("\n");
+
+  // Checkbox format takes precedence — embedded demo tables must not switch mode (#721).
+  if (lines.some(line => /^\s*-\s+\[[ xX]\]/.test(line))) {
+    return false;
+  }
+
+  const pipeLines = lines.filter(line => /^\s*\|/.test(line));
+  if (pipeLines.length < 2) return false;
+
+  const hasSeparatorRow = pipeLines.some((line, index) => {
+    if (index === 0) return false;
+    const cells = line.split("|").map(c => c.trim()).filter(Boolean);
+    return /^\s*\|[\s:-]+\|/.test(line) && cells.length >= 2 && cells.every(c => /^[\s:-]+$/.test(c));
+  });
+
+  if (hasSeparatorRow) return true;
+
+  // Tables without a separator row still expose slice IDs in data rows.
+  return pipeLines.some(line => /\bS\d+\b/.test(line));
+}
+
 export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
   const slicesSection = extractSlicesSection(content);
   if (!slicesSection) {
@@ -165,9 +188,11 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
 
   // Try table format first — if the section contains pipe-delimited rows with
   // slice IDs, parse them as a table (#1736).
-  const tableSlices = parseTableSlices(slicesSection);
-  if (tableSlices.length > 0) {
-    return tableSlices;
+  if (looksLikeTable(slicesSection)) {
+    const tableSlices = parseTableSlices(slicesSection);
+    if (tableSlices.length > 0) {
+      return tableSlices;
+    }
   }
 
   // Standard checkbox format

package/src/resources/extensions/gsd/safety/destructive-confirmation.ts

@@ -0,0 +1,134 @@
+/**
+ * One-shot confirmation token for destructive bash commands.
+ *
+ * The destructive-command guard hard-blocks classified commands (force push,
+ * rm -rf, SQL drop, etc.) in all modes. The block instructs the model to
+ * confirm via ask_user_questions and re-issue the command. This module is the
+ * missing escape hatch: it records the user's confirmation and lets the exact
+ * confirmed command through exactly once.
+ *
+ * Design constraints:
+ *  - In-memory only, never persisted. A confirmation token written to disk
+ *    could silently auto-approve a destructive command in a later session —
+ *    confirmation must be re-obtained every process lifetime.
+ *  - One-shot. Consuming a token clears it, so a second destructive command
+ *    (even an identical one) re-blocks and re-prompts.
+ *  - Command-bound. The token only matches the exact (normalized) command
+ *    string the user confirmed. A reworded command re-blocks, which is safe.
+ *  - Per basePath, so concurrent workspaces in one process never share tokens.
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+
+import { resolve } from "node:path";
+
+/**
+ * Question-id substring that marks an ask_user_questions call as a
+ * destructive-command confirmation. The tool_result handler promotes the
+ * pending command to a confirmed token when an affirmative answer arrives for
+ * a question whose id contains this marker.
+ */
+export const DESTRUCTIVE_CONFIRM_GATE_MARKER = "destructive_confirm";
+
+interface DestructiveConfirmationState {
+  /** Command awaiting confirmation, captured when the guard blocked it. */
+  pendingCommand: string | null;
+  /** Confirmed command cleared on first matching consume. */
+  confirmedCommand: string | null;
+}
+
+const statesByBasePath = new Map<string, DestructiveConfirmationState>();
+
+function stateKey(basePath: string): string {
+  return resolve(basePath);
+}
+
+function getState(basePath: string): DestructiveConfirmationState {
+  const key = stateKey(basePath);
+  let state = statesByBasePath.get(key);
+  if (!state) {
+    state = { pendingCommand: null, confirmedCommand: null };
+    statesByBasePath.set(key, state);
+  }
+  return state;
+}
+
+/**
+ * Normalize a command for stable matching across block → confirm → retry.
+ * Trims surrounding whitespace and collapses internal runs of whitespace so
+ * cosmetic reformatting of the same command still matches the token.
+ */
+export function normalizeDestructiveCommand(command: string): string {
+  return command.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Whether an ask_user_questions question id is a destructive-confirm gate.
+ */
+export function isDestructiveConfirmGateId(questionId: unknown): boolean {
+  return typeof questionId === "string" && questionId.includes(DESTRUCTIVE_CONFIRM_GATE_MARKER);
+}
+
+/**
+ * Record that a destructive command was blocked and is awaiting confirmation.
+ * Called by the guard at block time. Overwrites any prior pending command —
+ * only the most recently blocked command can be confirmed.
+ */
+export function requestDestructiveConfirmation(
+  command: string,
+  basePath: string = process.cwd(),
+): void {
+  const state = getState(basePath);
+  state.pendingCommand = normalizeDestructiveCommand(command);
+  // A fresh request invalidates any stale confirmed token for a different
+  // command so confirmation cannot leak across distinct destructive actions.
+  state.confirmedCommand = null;
+}
+
+/**
+ * Promote the pending command to a confirmed, one-shot token. Called by the
+ * tool_result handler when the user gives an affirmative answer to a
+ * destructive-confirm gate. Returns the confirmed command, or null if there
+ * was nothing pending (e.g. confirmation arrived without a preceding block).
+ */
+export function confirmDestructiveCommand(
+  basePath: string = process.cwd(),
+): string | null {
+  const state = getState(basePath);
+  if (!state.pendingCommand) return null;
+  state.confirmedCommand = state.pendingCommand;
+  state.pendingCommand = null;
+  return state.confirmedCommand;
+}
+
+/**
+ * Check whether the given command has been confirmed, consuming the token if
+ * so. Returns true exactly once per confirmation; subsequent calls (or a
+ * non-matching command) return false. Called by the guard before blocking.
+ */
+export function consumeDestructiveConfirmation(
+  command: string,
+  basePath: string = process.cwd(),
+): boolean {
+  const state = getState(basePath);
+  if (!state.confirmedCommand) return false;
+  if (state.confirmedCommand !== normalizeDestructiveCommand(command)) return false;
+  state.confirmedCommand = null;
+  return true;
+}
+
+/**
+ * Inspect the pending command without consuming it (diagnostics/tests).
+ */
+export function peekPendingDestructiveCommand(
+  basePath: string = process.cwd(),
+): string | null {
+  return getState(basePath).pendingCommand;
+}
+
+/**
+ * Clear all destructive-confirmation state for a basePath (tests / flow reset).
+ */
+export function resetDestructiveConfirmation(basePath: string = process.cwd()): void {
+  statesByBasePath.delete(stateKey(basePath));
+}

package/src/resources/extensions/gsd/safety/evidence-collector.ts

@@ -57,9 +57,10 @@ const EXECUTION_TOOL_NAMES = new Set([
   "functions.exec_command",
   "gsd_exec",
   "gsd_exec_search",
+  "gsd_uat_exec",
   "powershell",
 ]);
-const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_exec(?:_search)?$/;
+const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_(?:uat_)?exec(?:_search)?$/;
 
 // ─── Module State ───────────────────────────────────────────────────────────
 
@@ -206,11 +207,17 @@ export function clearEvidenceFromDisk(
  * Exit codes and output are filled in by recordToolResult after execution.
  */
 export function recordToolCall(toolCallId: string, toolName: string, input: Record<string, unknown>): void {
+  // Idempotent by toolCallId: native tools reach this via both
+  // tool_execution_start and tool_call; external (pre-executed) tools only
+  // via tool_execution_start. First recording wins.
+  if (unitEvidence.some(e => e.toolCallId === toolCallId)) return;
   if (isExecutionToolName(toolName)) {
     unitEvidence.push({
       kind: "bash",
       toolCallId,
-      command: String(input.command ?? input.cmd ?? input.query ?? ""),
+      // gsd_exec / gsd_uat_exec carry the script body in `script` (or `code`);
+      // bash-style tools use `command`/`cmd`; gsd_exec_search uses `query`.
+      command: String(input.command ?? input.script ?? input.cmd ?? input.code ?? input.query ?? ""),
       exitCode: -1,
       outputSnippet: "",
       timestamp: Date.now(),
@@ -249,11 +256,36 @@ export function recordToolResult(
   if (entry.kind === "bash") {
     const text = extractResultText(result);
     entry.outputSnippet = text.slice(0, 500);
-    const exitMatch = text.match(/Command exited with code (\d+)/);
-    entry.exitCode = exitMatch ? Number(exitMatch[1]) : (isError ? 1 : 0);
+    entry.exitCode = resolveExitCode(text, isError);
   }
 }
 
+/**
+ * Resolve the exit code from a tool result's text. Handles the bash tool's
+ * prose marker, the gsd_exec / gsd_uat_exec JSON envelope (`"exit_code": N`),
+ * and a last-resort read of the run's persisted `.gsd/exec/<id>.meta.json`
+ * (covers truncated result text).
+ */
+function resolveExitCode(text: string, isError: boolean): number {
+  const proseMatch = text.match(/Command exited with code (\d+)/);
+  if (proseMatch) return Number(proseMatch[1]);
+
+  const jsonMatch = text.match(/"exit_code"\s*:\s*(-?\d+)/);
+  if (jsonMatch) return Number(jsonMatch[1]);
+
+  const metaMatch = text.match(/"meta_path"\s*:\s*"([^"]+)"/);
+  if (metaMatch) {
+    try {
+      const meta = JSON.parse(readFileSync(metaMatch[1], "utf-8")) as Record<string, unknown>;
+      if (typeof meta.exit_code === "number") return meta.exit_code;
+    } catch {
+      // Fall through to the isError heuristic
+    }
+  }
+
+  return isError ? 1 : 0;
+}
+
 // ─── Internals ──────────────────────────────────────────────────────────────
 
 function extractResultText(result: unknown): string {

package/src/resources/extensions/gsd/safety/evidence-cross-ref.ts

@@ -121,9 +121,14 @@ function findMatches(
   const exact = bashCalls.filter(b => b.command.trim() === normalized);
   if (exact.length > 0) return exact;
 
-  // Substring match: claimed is contained in actual or actual in claimed
+  // Substring match: claimed is contained in actual or actual in claimed.
+  // A claimed verification command typically appears verbatim inside a
+  // larger gsd_exec script body (cd prefix, multi-line scripts), so
+  // script-containing-claim is the common direction. Blank-command entries
+  // must be excluded — `"x".includes("")` is true, so they'd match anything.
   const substring = bashCalls.filter(
-    b => b.command.includes(normalized) || normalized.includes(b.command),
+    b => b.command.trim().length > 0 &&
+      (b.command.includes(normalized) || normalized.includes(b.command)),
   );
   if (substring.length > 0) return substring;
 

package/src/resources/extensions/gsd/safety/file-change-validator.ts

@@ -39,6 +39,20 @@ export interface FileChangeAudit {
 
 // ─── Public API ─────────────────────────────────────────────────────────────
 
+/**
+ * Build the effective allowlist for a unit's file-change audit.
+ *
+ * When GSD manages .gitignore (manage_gitignore unset or true), ensureGitignore()
+ * appends baseline patterns at auto-start and the edit rides into the task's
+ * auto-commit — so .gitignore changes must not be attributed to the task.
+ */
+export function effectiveFileChangeAllowlist(
+  baseAllowlist: string[],
+  manageGitignore: boolean | undefined,
+): string[] {
+  return manageGitignore === false ? baseAllowlist : [...baseAllowlist, ".gitignore"];
+}
+
 /**
  * Validate file changes after auto-commit for an execute-task unit.
  * Returns null if task data is unavailable or DB is not loaded.

package/src/resources/extensions/gsd/session-lock.ts

@@ -387,7 +387,7 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
     // #3218: Provide actionable workaround when lock recovery fails
     const lockDirPath = lockTarget + ".lock";
     const reason = existingPid
-      ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.`
+      ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nRun \`/gsd stop\` for graceful shutdown, or choose "Force start" from \`/gsd auto\` to terminate it.`
       : `Another auto-mode session lock is stuck on this project.\nRun: rm -rf "${lockDirPath}" && rm -f "${lp}"`;
 
     return { acquired: false, reason, existingPid };

package/src/resources/extensions/gsd/skill-activation.ts

@@ -134,11 +134,8 @@ const SAFE_SKILL_NAME = /^[a-z0-9][a-z0-9-]*$/;
 function formatSkillActivationBlock(skillNames: string[]): string {
   const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
   if (safe.length === 0) return "";
-  // Use explicit parameter syntax so LLMs pass { skill: "..." } instead of { name: "..." }.
-  // The function-call-like syntax `Skill('name')` led LLMs to infer a positional
-  // parameter name, causing tool validation failures — see #2224.
-  const calls = safe.map(name => `Call Skill({ skill: '${name}' })`).join('. ');
-  return `<skill_activation>${calls}.</skill_activation>`;
+  const reads = safe.map(name => `Read the installed '${name}' skill file from <available_skills>`).join(". ");
+  return `<skill_activation>${reads}.</skill_activation>`;
 }
 
 /**
@@ -157,7 +154,7 @@ function formatSkillRecommendationsBlock(unitType: string | undefined, skillName
   if (!unitType) return "";
   const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
   if (safe.length === 0) return "";
-  return `<skill_recommendations unit="${unitType}">For this unit type, also consider invoking: ${safe.join(", ")}. Use Skill({ skill: 'name' }) when relevant — these are recommendations, not requirements.</skill_recommendations>`;
+  return `<skill_recommendations unit="${unitType}">For this unit type, also consider reading these installed skill files from <available_skills>: ${safe.join(", ")}. These are recommendations, not requirements.</skill_recommendations>`;
 }
 
 export function buildSkillActivationBlock(params: {

package/src/resources/extensions/gsd/state-transition-matrix.ts

@@ -131,6 +131,48 @@ export function findTransition(
   );
 }
 
+/**
+ * Edge-keyed legality check for the Phase Transition Invariant (ADR-030).
+ * `advance()` derives the next Phase and asserts the (from → to) edge here.
+ *
+ * The matrix is an assertion, not a decision-maker — `deriveState` already
+ * chose the Phase. A self-edge is trivially legal (no transition to assert). An
+ * edge is legal when some matrix entry permits it, honoring the `*` wildcard
+ * rows (e.g. any → blocked via manual-block, any → executing via
+ * retryable-failure).
+ *
+ * Note: the matrix is currently a sparse hardening spec, not a complete
+ * legal-edge graph, so `advance()` consumes this in advisory mode (telemetry
+ * only). It must be expanded to cover every edge `deriveState` emits before
+ * enforcement flips on.
+ */
+export function isLegalEdge(from: Phase, to: Phase): boolean {
+  if (from === to) return true;
+  return STATE_TRANSITION_MATRIX.some(
+    (entry) => (entry.from === from || entry.from === "*") && entry.to === to,
+  );
+}
+
+/**
+ * Thrown when an illegal derived Phase edge survives reconciliation. Carries
+ * both endpoints so Recovery Classification can report them. Recognized by
+ * class in `classifyFailure` and mapped to the `illegal-transition` kind.
+ */
+export class IllegalPhaseTransitionError extends Error {
+  // Explicit fields, not constructor parameter properties — strip-types
+  // consumers (workspace-index subprocess, integration tests) reject the
+  // parameter-property syntax with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX.
+  readonly from: Phase;
+  readonly to: Phase;
+
+  constructor(from: Phase, to: Phase) {
+    super(`Illegal phase transition ${from} -> ${to} survived reconciliation`);
+    this.name = "IllegalPhaseTransitionError";
+    this.from = from;
+    this.to = to;
+  }
+}
+
 export function validateTransitionMatrix(requiredEvents: readonly string[]): MatrixValidationResult {
   const seen = new Set<string>();
   const duplicateKeys: string[] = [];

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

@@ -13,6 +13,11 @@ import type {
   MilestoneRegistryEntry,
 } from './types.js';
 
+// Pre-migration fallback ONLY (ADR-017): deriveState must work on projects
+// whose DB does not exist yet (before md-importer runs), so it parses markdown
+// projections when `isDbAvailable()` is false or the DB has no rows. Once the
+// DB is populated, decision reads go through gsd-db queries — these parsers
+// must never be consulted when DB data is present.
 import {
   parseRoadmap,
   parsePlan,
@@ -55,6 +60,7 @@ import {
   getAllMilestones,
   getMilestone,
   getMilestoneSlices,
+  getSlicesByMilestoneIds,
   getSliceTasks,
   getReplanHistory,
   getSlice,
@@ -71,27 +77,10 @@ import {
   readinessNeedsDiscussion,
 } from './milestone-readiness.js';
 
-function formatNeedsAttentionBlocker(milestoneId: string): string {
-  return [
-    `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
-    `Fix options:`,
-    `1. Review the validation details: \`/gsd status\``,
-    `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
-    `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
-    `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
-    `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
-  ].join("\n");
-}
-
-function formatNeedsRemediationBlocker(milestoneId: string): string {
-  return [
-    `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
-    `Fix options:`,
-    `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
-    `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
-    `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
-  ].join("\n");
-}
+import {
+  needsAttentionBlockerGuidance as formatNeedsAttentionBlocker,
+  needsRemediationBlockerGuidance as formatNeedsRemediationBlocker,
+} from './guidance.js';
 
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
@@ -489,13 +478,18 @@ async function buildRegistryAndFindActive(
   let activeMilestoneHasDraft = false;
   let firstDeferredQueuedShell: { id: string; title: string; deps: string[]; hasDraftContext: boolean } | null = null;
 
+  const activeMilestoneIds = milestones
+    .filter((m) => !parkedMilestoneIds.has(m.id))
+    .map((m) => m.id);
+  const slicesByMilestone = getSlicesByMilestoneIds(activeMilestoneIds);
+
   for (const m of milestones) {
     if (parkedMilestoneIds.has(m.id)) {
       registry.push({ id: m.id, title: stripMilestonePrefix(m.title) || m.id, status: 'parked' });
       continue;
     }
 
-    const slices = getMilestoneSlices(m.id);
+    const slices = slicesByMilestone.get(m.id) ?? [];
 
     // DB-authoritative completeness (#4179): only trust completeMilestoneIds,
     // which is itself derived from DB status. SUMMARY-file presence alone must

package/src/resources/extensions/gsd/status-guards.ts

@@ -1,17 +1,68 @@
 /**
- * Status predicates for GSD state-machine guards.
+ * Status predicates and the canonical status vocabulary for GSD state-machine
+ * guards (ADR-030).
  *
- * The DB stores status as free-form strings. Three values indicate
- * "closed": "complete" (canonical), "done" (legacy / alias),
- * "closed" (legacy/imported), and
- * "skipped" (user-directed skip via rethink or backtrack).
- * Every inline `status === "complete" || status === "done"` should
- * use isClosedStatus() instead.
+ * The DB column is free-form `string` so legacy/imported rows still load. Three
+ * raw values besides canonical "complete"/"skipped" indicate "closed": "done"
+ * (legacy alias), "closed" (legacy/imported), and "skipped" (user-directed skip
+ * via rethink or backtrack). `RAW_CLOSED_STATUSES` is the single source for both
+ * `isClosedStatus()` and the SQL terminal-status fragment
+ * (`db/sql-constants.ts` derives `TERMINAL_STATUS_SQL` from it), replacing the
+ * prior independent definitions.
+ *
+ * `toStatus()` is the single seam where a free-form string becomes the canonical
+ * `Status` vocabulary; the Status Transition Core writes canonical, so the store
+ * converges over time without a forced migration.
+ */
+
+/**
+ * Canonical, normalized entity-status vocabulary across milestones, slices, and
+ * tasks — the single source for both the `Status` type and the runtime
+ * membership set. The in-memory domain speaks `Status`; the DB column stays
+ * free-form.
+ */
+export const CANONICAL_STATUSES = [
+  "pending", "queued", "active", "parked", "in_progress", "blocked", "complete", "skipped", "deferred",
+] as const;
+export type Status = (typeof CANONICAL_STATUSES)[number];
+const CANONICAL_STATUS_SET: ReadonlySet<string> = new Set(CANONICAL_STATUSES);
+
+/**
+ * Raw status values that mean a unit is closed — the single source of truth.
+ * Includes legacy/imported aliases ("done", "closed") alongside canonical
+ * "complete"/"skipped" because the DB column is free-form and older rows /
+ * imports still carry them. Order matters: `TERMINAL_STATUS_SQL` is derived
+ * from this array verbatim.
+ */
+export const RAW_CLOSED_STATUSES = ["complete", "done", "skipped", "closed"] as const;
+const RAW_CLOSED_SET: ReadonlySet<string> = new Set(RAW_CLOSED_STATUSES);
+
+/** Free-form aliases mapped to their canonical Status on read. */
+const ALIAS_TO_CANONICAL: Readonly<Record<string, Status>> = {
+  done: "complete",
+  closed: "complete",
+  planned: "pending",
+  "in-progress": "in_progress",
+};
+
+/**
+ * Normalize a free-form DB status string into the canonical `Status`
+ * vocabulary. Maps known aliases (done/closed → complete, planned → pending,
+ * in-progress → in_progress). An unrecognized/legacy value is **quarantined** —
+ * preserved verbatim rather than silently remapped to a wrong canonical state —
+ * so reads never fail and reconciliation/telemetry can surface it.
  */
+export function toStatus(raw: string): Status {
+  const value = raw.trim();
+  if (CANONICAL_STATUS_SET.has(value)) return value as Status;
+  const alias = ALIAS_TO_CANONICAL[value];
+  if (alias) return alias;
+  return value as Status;
+}
 
 /** Returns true when a milestone, slice, or task status indicates closure. */
 export function isClosedStatus(status: string): boolean {
-  return status === "complete" || status === "done" || status === "skipped" || status === "closed";
+  return RAW_CLOSED_SET.has(status);
 }
 
 /** Returns true when a slice status indicates it was deferred by a decision. */

package/src/resources/extensions/gsd/stop-notice.ts

@@ -0,0 +1,75 @@
+// Project/App: gsd-pi
+// File Purpose: Stop Notice module — single owner of the auto/step-mode
+// stop/pause notice vocabulary. Both sides of the wire live here: the
+// formatters that produce the canonical prefixes (used by stopAuto/pauseAuto)
+// and the classifiers that recognize them (used by the headless host to pick
+// exit codes). Wording changes in this file keep emitter and detector in
+// lockstep; round-trip tests enforce it.
+
+export type StopNoticeKind = "stopped" | "blocked";
+
+/** A reason string of the form "Blocked: …" marks a blocked stop. */
+export function isBlockedStopReason(reason?: string | null): boolean {
+  return /^Blocked:\s*/i.test(reason ?? "");
+}
+
+/** Strip the "Blocked: " marker for display. */
+export function stopNoticeDisplayReason(reason?: string | null): string {
+  return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
+}
+
+export function stopNoticeKind(reason?: string | null): StopNoticeKind {
+  return isBlockedStopReason(reason) ? "blocked" : "stopped";
+}
+
+/** Canonical stop-notice prefix: "Auto-mode blocked — reason" / "Auto-mode stopped". */
+export function formatStopNoticePrefix(reason?: string | null): string {
+  const displayReason = stopNoticeDisplayReason(reason);
+  const prefix = stopNoticeKind(reason) === "blocked" ? "Auto-mode blocked" : "Auto-mode stopped";
+  return displayReason ? `${prefix} — ${displayReason}` : prefix;
+}
+
+// ─── Classification (headless host side) ────────────────────────────────
+// The canonical lowercase prefixes the headless event loop recognizes in
+// notify messages. Emitters above and ad-hoc emitters elsewhere must start
+// their terminal notices with one of these.
+
+export const PAUSED_NOTICE_PREFIXES = ["auto-mode paused", "step-mode paused"] as const;
+
+export const TERMINAL_NOTICE_PREFIXES = [
+  "auto-mode stopped",
+  "step-mode stopped",
+  "auto-mode complete",
+  "no active milestone",
+  "auto-mode idle",
+] as const;
+
+/** Manual-resolution notices emitted before auto-mode can formally pause/stop. */
+export function isManualResolutionNotice(message: string): boolean {
+  return (
+    message.includes("resolve manually and re-run /gsd auto") ||
+    message.includes("resolve conflicts manually and run /gsd auto to resume") ||
+    message.includes("resolve and run /gsd auto to resume")
+  );
+}
+
+export function isPauseNotice(message: string): boolean {
+  return PAUSED_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+
+export function isTerminalNotice(message: string): boolean {
+  return TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+
+/** Pauses that do not require operator intervention in headless mode. */
+export function isNonBlockingPauseNotice(message: string): boolean {
+  return message.includes("idempotent advance: unit already active");
+}
+
+export function isBlockedNoticeMessage(message: string): boolean {
+  return (
+    message.includes("blocked:") ||
+    (isPauseNotice(message) && !isNonBlockingPauseNotice(message)) ||
+    isManualResolutionNotice(message)
+  );
+}

package/src/resources/extensions/gsd/tests/auto-abort-pause-regression.test.ts

@@ -2,7 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 
 import { _buildAbortedPauseContext, isUserInitiatedAbortMessage } from "../bootstrap/agent-end-recovery.js";
-import { _buildCancelledUnitStopReason, _isPauseOriginCancelledResult } from "../auto/phases.js";
+import { _buildCancelledUnitStopReason, _isPauseOriginCancelledResult } from "../auto/phase-helpers.js";
 
 test("aborted agent_end maps errorMessage into structured aborted pause context", () => {
   const withMessage = _buildAbortedPauseContext({ errorMessage: "provider aborted request" });

package/src/resources/extensions/gsd/tests/auto-blocked-remediation-message.test.ts

@@ -1,7 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 
-import { runPreDispatch } from "../auto/phases.ts";
+import { runPreDispatch } from "../auto/pre-dispatch.ts";
 
 test("blocked remediation warning uses /gsd dispatch reassess and hides internal tool name", async () => {
   const notifications: Array<{ message: string; level?: string }> = [];