@opengsd/gsd-pi 1.4.0 → 1.5.0

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

@@ -1199,11 +1199,11 @@ export function teardownAutoWorktree(
   const branch = autoWorktreeBranch(milestoneId);
   const { preserveBranch = false, preserveWorktree = false } = opts;
   const previousCwd = safeCwd(originalBasePath);
+  let clearActiveWorkspace = true;
 
   // Wrap the entire teardown body in a single try/finally so activeWorkspace
-  // is ALWAYS cleared — even if process.chdir throws (e.g. originalBasePath
-  // was deleted before teardown ran). Previously the finally only covered
-  // removeWorktree, leaving the registry stale on a chdir failure (H3 fix).
+  // is cleared on completion or irrecoverable failure — even if process.chdir
+  // throws (e.g. originalBasePath was deleted before teardown ran).
   try {
     try {
       process.chdir(originalBasePath);
@@ -1245,18 +1245,28 @@ export function teardownAutoWorktree(
     // 3. Remove the worktree unless this exit path explicitly preserves it
     //    (slice-parallel dispatch stops the parent loop but keeps the parent
     //    milestone worktree for restart/re-entry).
+    let worktreeRemoved = preserveWorktree;
     if (!preserveWorktree) {
-      removeWorktree(originalBasePath, milestoneId, {
+      worktreeRemoved = removeWorktree(originalBasePath, milestoneId, {
         branch,
         deleteBranch: !preserveBranch,
       });
+      if (!worktreeRemoved) {
+        logWarning(
+          "worktree",
+          `Worktree removal aborted for ${milestoneId}; uncommitted work was preserved. ` +
+            `Manual quarantine recovery may be needed before retrying teardown.`,
+          { worktree: milestoneId },
+        );
+        clearActiveWorkspace = false;
+      }
     }
 
     // Verify cleanup succeeded — warn if the worktree directory is still on disk.
     // On Windows, bash-based cleanup can silently fail when paths contain
     // backslashes (#1436), leaving ~1 GB+ orphaned directories.
     const wtDir = worktreePath(originalBasePath, milestoneId);
-    if (!preserveWorktree && existsSync(wtDir)) {
+    if (!preserveWorktree && worktreeRemoved && existsSync(wtDir)) {
       logWarning(
         "reconcile",
         `Worktree directory still exists after teardown: ${wtDir}. ` +
@@ -1280,10 +1290,12 @@ export function teardownAutoWorktree(
       }
     }
   } finally {
-    // Clear module state unconditionally — regardless of which step above
-    // failed. A stale activeWorkspace causes getActiveAutoWorktreeContext()
-    // to return wrong data for subsequent operations.
-    setActiveWorkspace(null);
+    // Clear module state when teardown completed or failed irrecoverably.
+    // When removeWorktree returns false (quarantine failure), preserve the
+    // registry so recovery logic still sees the active milestone worktree.
+    if (clearActiveWorkspace) {
+      setActiveWorkspace(null);
+    }
   }
 }
 
@@ -1791,14 +1803,31 @@ export function mergeMilestoneToMain(
     } catch (err) {
       logWarning("worktree", `clearProjectRootStateFiles failed during already-merged cleanup: ${err instanceof Error ? err.message : String(err)}`);
     }
+    let worktreeRemoved = true;
     try {
-      removeWorktree(originalBasePath_, milestoneId, {
+      worktreeRemoved = removeWorktree(originalBasePath_, milestoneId, {
         branch: milestoneBranch,
         deleteBranch: false,
       });
     } catch (err) {
+      worktreeRemoved = false;
       logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+
+    if (!worktreeRemoved) {
+      logWarning(
+        "worktree",
+        `Skipping milestone branch deletion for ${milestoneBranch}; worktree removal was aborted to preserve uncommitted milestone work.`,
+      );
+      nudgeGitBranchCache(previousCwd);
+      try {
+        process.chdir(originalBasePath_);
+      } catch (err) {
+        logWarning("worktree", `chdir to project root after already-merged cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      return { commitMessage, pushed: false, prCreated: false, codeFilesChanged: true };
+    }
+
     try {
       nativeBranchDelete(originalBasePath_, milestoneBranch);
     } catch (err) {
@@ -2270,16 +2299,26 @@ export function mergeMilestoneToMain(
 
   const finalizeMilestoneCleanup = (): void => {
     // 12. Remove worktree directory first (must happen before branch deletion)
+    let worktreeRemoved = true;
     try {
-      removeWorktree(originalBasePath_, milestoneId, {
+      worktreeRemoved = removeWorktree(originalBasePath_, milestoneId, {
         branch: milestoneBranch,
         deleteBranch: false,
       });
     } catch (err) {
+      worktreeRemoved = false;
       // Best-effort -- worktree dir may already be gone
       logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 
+    if (!worktreeRemoved) {
+      logWarning(
+        "worktree",
+        `Skipping milestone branch deletion for ${milestoneBranch}; worktree removal was aborted to preserve uncommitted milestone work.`,
+      );
+      return;
+    }
+
     // 13. Delete milestone branch (after worktree removal so ref is unlocked)
     try {
       nativeBranchDelete(originalBasePath_, milestoneBranch);

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

@@ -236,7 +236,7 @@ import {
   getSlice,
   getTask,
 } from "./gsd-db.js";
-import { closeWorkflowDatabase } from "./db-workspace.js";
+import { checkpointWorkflowDatabase, closeWorkflowDatabase } from "./db-workspace.js";
 import { markLatestActiveForWorkerCanceled } from "./db/unit-dispatches.js";
 import { writeUnitRuntimeRecord } from "./unit-runtime.js";
 import { countPendingCaptures } from "./captures.js";
@@ -1051,6 +1051,12 @@ export function stopAutoRemote(projectRoot: string): {
  * The normal stop path stays SIGTERM-only so cooperative sessions can clean up;
  * this path is only for the explicit "Force start" action.
  */
+// Grace window between SIGTERM and SIGKILL so the target can run its cleanup
+// handler (lock release, DB snapshot flush, worktree teardown). Polled so a
+// process that exits early is not made to wait the full window.
+const FORCE_STOP_GRACE_MS = 3000;
+const FORCE_STOP_POLL_MS = 100;
+
 export function forceStopAutoRemote(projectRoot: string): {
   found: boolean;
   pid?: number;
@@ -1071,6 +1077,13 @@ export function forceStopAutoRemote(projectRoot: string): {
 
   try {
     process.kill(lock.pid, "SIGTERM");
+    // Poll for graceful exit before escalating. Synchronous sleep keeps this
+    // function sync for its callers (Atomics.wait times out with no notify).
+    const deadline = Date.now() + FORCE_STOP_GRACE_MS;
+    while (Date.now() < deadline) {
+      if (!isLockProcessAlive(lock)) break;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, FORCE_STOP_POLL_MS);
+    }
     if (isLockProcessAlive(lock)) {
       process.kill(lock.pid, "SIGKILL");
     }
@@ -1615,6 +1628,11 @@ export async function stopAuto(
   const installTerminalCloseoutOutcome = completionStopRequested && preserveCloseoutTranscript;
   const preserveCompletionSurface = completionStopRequested || preserveCloseoutTranscript;
   s.completionStopInProgress = preserveCompletionSurface;
+  try {
+    checkpointWorkflowDatabase();
+  } catch (e) {
+    debugLog("stop-checkpoint-failed", { error: e instanceof Error ? e.message : String(e) });
+  }
   playNotificationBell("stop", loadedPreferences?.notifications);
 
   // #4764 — telemetry: record the exit reason, isolation mode, whether an auto
@@ -2299,7 +2317,7 @@ export function buildWorktreeLifecycleDeps(): WorktreeLifecycleDeps {
   //   C4 (#5627) — GitServiceImpl constructor → gitServiceFactory
   //
   // Final WorktreeLifecycleDeps shape: 3 fields (gitServiceFactory,
-  // worktreeProjection, mergeMilestoneToMain transaction runner). Down from 18 at slice-7
+  // worktreeProjection, mergeMilestone transaction runner). Down from 18 at slice-7
   // closure.
   return {
     gitServiceFactory: (basePath: string) => {
@@ -2308,7 +2326,7 @@ export function buildWorktreeLifecycleDeps(): WorktreeLifecycleDeps {
       return new GitServiceImpl(basePath, gitConfig);
     },
     worktreeProjection: new WorktreeStateProjection(),
-    mergeMilestoneToMain: createMilestoneMergeTransaction(mergeMilestoneToMain),
+    mergeMilestone: createMilestoneMergeTransaction(mergeMilestoneToMain),
   };
 }
 
@@ -2357,6 +2375,7 @@ function buildLoopDeps(pi: ExtensionAPI, ctx: ExtensionContext): LoopDeps {
     stopAuto,
     pauseAuto,
     clearUnitTimeout,
+    checkpointWorkflowDatabase,
     updateProgressWidget,
     ...cmux,
     handleLostSessionLock: (ctx: ExtensionContext | undefined, lockStatus: SessionLockStatus | undefined) => {

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -710,12 +710,14 @@ export function registerDbTools(pi: ExtensionAPI): void {
         inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
         expectedOutput: Type.Array(Type.String(), { description: "Array<string> of files this task creates or overwrites; pass [\"path\"] or [], never prose or a single string" }),
         observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
+        targetRepositories: Type.Optional(Type.Array(Type.String(), { description: "Repository id(s) this task touches (parent workspace); must match a Declared Repository. Omit for single-repo projects." })),
       }), { description: "Optional full task replacement for the slice. Omit for incremental planning, then call gsd_plan_task once per task." })),
       // ── Enrichment metadata (optional — defaults to empty) ────────────
       successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block" })),
       proofLevel: Type.Optional(Type.String({ description: "Slice proof level" })),
       integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure" })),
       observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact" })),
+      targetRepositories: Type.Optional(Type.Array(Type.String(), { description: "Slice-wide default repository id(s) (parent workspace); must match a Declared Repository. Omit for single-repo projects." })),
       // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
       actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
       triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'plan-phase complete')" })),
@@ -789,6 +791,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
       expectedOutput: Type.Array(Type.String(), { description: "Array<string> of files this task creates or overwrites; pass [\"path\"] or [], never prose or a single string" }),
       observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
+      targetRepositories: Type.Optional(Type.Array(Type.String(), { description: "Repository id(s) this task touches (parent workspace); must match a Declared Repository. Omit for single-repo projects." })),
       // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
       actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
       triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'plan-phase complete')" })),

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -32,6 +32,12 @@ import {
   recordAutoToolSurfaceSnapshot,
   recordToolInvocationError,
 } from "../auto-runtime-state.js";
+import {
+  isDeterministicPolicyError,
+  isQueuedUserMessageSkip,
+  isToolInvocationError,
+  isToolUnavailableError,
+} from "../auto-tool-tracking.js";
 import { applyProviderPayloadPolicy } from "../provider-payload-policy.js";
 
 import { checkToolCallLoop, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
@@ -77,9 +83,24 @@ import { clearPendingAutoStart } from "../pending-auto-start.js";
 import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
 import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.js";
 import { flushAllManifests } from "../workflow-manifest.js";
+import { recordUnitHarnessAbort, type UnitHarnessAbortRecord } from "../unit-runtime.js";
 
 let approvalQuestionAbortInFlight = false;
 
+function recordCurrentUnitHarnessAbort(
+  abort: Omit<UnitHarnessAbortRecord, "recordedAt"> & { recordedAt?: number },
+): void {
+  const dash = getAutoRuntimeSnapshot();
+  if (!dash.active || !dash.basePath || !dash.currentUnit) return;
+  recordUnitHarnessAbort(
+    dash.basePath,
+    dash.currentUnit.type,
+    dash.currentUnit.id,
+    dash.currentUnit.startedAt,
+    abort,
+  );
+}
+
 type WelcomeScreenModule = {
   buildWelcomeScreenLines(opts: { version: string; remoteChannel?: string; width?: number }): string[];
 };
@@ -209,10 +230,26 @@ const WORKFLOW_GSD_TOOL_NAMES = [
   ...Object.values(AUTO_UNIT_SCOPED_TOOLS).flat(),
 ].filter(isGsdManagedTool);
 
+const WORKFLOW_ONLY_AUTO_BASE_TOOL_NAMES = [
+  "find",
+  "glob",
+  "grep",
+  "ls",
+  "read",
+  "subagent",
+] as const;
+
 function isGsdManagedTool(name: string): boolean {
   return name.startsWith("gsd_") || name === "memory_query" || name === "capture_thought" || name === "gsd_graph";
 }
 
+function autoBaseToolNamesForUnit(unitType: string | undefined): readonly string[] {
+  const manifest = unitType ? resolveManifest(unitType) : null;
+  return manifest?.tools.mode === "workflow-only"
+    ? WORKFLOW_ONLY_AUTO_BASE_TOOL_NAMES
+    : MINIMAL_AUTO_BASE_TOOL_NAMES;
+}
+
 /**
  * Resolves requested tool names against active tools using exact and MCP-scoped matches.
  *
@@ -275,7 +312,7 @@ export function buildMinimalAutoGsdToolSet(
     return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
   }
   const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
-  const autoBaseTools = new Set<string>(MINIMAL_AUTO_BASE_TOOL_NAMES);
+  const autoBaseTools = new Set<string>(autoBaseToolNamesForUnit(unitType));
   const availableBaseTools = registeredToolNames.filter((name) => autoBaseTools.has(name));
   const preserved = [...new Set([
     ...activeToolNames.filter((name) => autoBaseTools.has(name)),
@@ -599,6 +636,72 @@ function formatLoopGuardBlockReason(reason: string | undefined): string | undefi
   );
 }
 
+function isGateResultPersistenceTool(toolName: string): boolean {
+  return toolName === "gsd_save_gate_result" || toolName === "gsd_uat_result_save";
+}
+
+function resultDetails(result: unknown): Record<string, unknown> {
+  if (!result || typeof result !== "object") return {};
+  const details = (result as { details?: unknown }).details;
+  return details && typeof details === "object" ? details as Record<string, unknown> : {};
+}
+
+function isAbortedExecutionToolResult(toolName: string, result: unknown): boolean {
+  if (toolName !== "gsd_exec" && toolName !== "gsd_uat_exec") return false;
+  const details = resultDetails(result);
+  return details.aborted === true || details.force_resolved === true || details.timed_out === true;
+}
+
+function isRetryableHarnessToolError(toolName: string, result: unknown, errorText: string): boolean {
+  if (isGateResultPersistenceTool(toolName)) return false;
+  if (isDeterministicPolicyError(errorText)) return false;
+  if (toolName === "gsd_exec" || toolName === "gsd_uat_exec") {
+    if (isAbortedExecutionToolResult(toolName, result)) return true;
+    if (isToolUnavailableError(errorText)) return true;
+    if (isQueuedUserMessageSkip(errorText)) return true;
+    return isToolInvocationError(errorText);
+  }
+  if (isToolUnavailableError(errorText)) return true;
+  if (isQueuedUserMessageSkip(errorText)) return true;
+  return false;
+}
+
+function recordRetryableHarnessToolError(toolName: string, result: unknown, errorText: string): void {
+  if (!isRetryableHarnessToolError(toolName, result, errorText)) return;
+  recordCurrentUnitHarnessAbort({
+    kind: "tool-error",
+    reason: errorText || "Tool execution failed before the unit could complete its gate evaluation.",
+    toolName,
+  });
+}
+
+function recordRetryableTurnAbort(event: { abortOrigin?: unknown; messages?: unknown[] }): void {
+  const origin = typeof event.abortOrigin === "string" ? event.abortOrigin : undefined;
+  if (origin === "session-transition") return;
+
+  const messages = Array.isArray(event.messages) ? event.messages : [];
+  const lastMsg = messages[messages.length - 1];
+  const stopReason = lastMsg && typeof lastMsg === "object"
+    ? (lastMsg as { stopReason?: unknown }).stopReason
+    : undefined;
+  if (stopReason !== "aborted" && stopReason !== "error") return;
+
+  const errorMessage = lastMsg && typeof lastMsg === "object"
+    ? (lastMsg as { errorMessage?: unknown }).errorMessage
+    : undefined;
+  const reason = [
+    "Agent turn aborted before the unit could complete its gate evaluation.",
+    origin ? `origin=${origin}` : undefined,
+    typeof stopReason === "string" ? `stopReason=${stopReason}` : undefined,
+    typeof errorMessage === "string" && errorMessage.trim() ? `error=${errorMessage.trim()}` : undefined,
+  ].filter(Boolean).join(" ");
+
+  recordCurrentUnitHarnessAbort({
+    kind: "turn-abort",
+    reason,
+  });
+}
+
 function beginSourceObservationStoreForCurrentUnit(
   ctx?: { cwd?: string },
 ): ReturnType<typeof getSourceObservationStore> | null {
@@ -902,8 +1005,8 @@ export function registerHooks(
     await prepareWorkflowMcpForHookContext(ctx, basePath);
 
     // Migrate legacy .gsd/milestones/ to flat-phase .gsd/phases/ when detected.
-    // Best-effort — never blocks session startup. Skipped inside auto-worktrees
-    // (migration already ran on the project root before the worktree was created).
+    // Fail closed on migration errors: resolvers assume flat-phase paths after
+    // startup, so continuing with nested disk state corrupts later checks.
     try {
       const { isInAutoWorktree } = await import("../auto-worktree.js");
       if (!isInAutoWorktree(basePath)) {
@@ -917,11 +1020,21 @@ export function registerHooks(
           } else {
             safetyLogWarning(
               "bootstrap",
-              "flat-phase migration deferred: legacy .gsd/milestones/ layout detected but the workflow database could not be opened — will retry on next session",
+              "flat-phase migration required: legacy .gsd/milestones/ layout detected but the workflow database could not be opened — fix database access before starting GSD",
+            );
+            throw new Error(
+              "flat-phase migration required but the workflow database could not be opened; fix database access before starting GSD",
             );
           }
         }
       }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      safetyLogWarning("bootstrap", `flat-phase migration failed: ${message}`);
+      throw new Error(`flat-phase migration failed: ${message}`);
+    }
+
+    try {
       const projectRoot = resolveWorktreeProjectRoot(basePath);
       const { pruneStaleFlatPhaseBackups } = await import("../flat-phase-migration.js");
       const pruned = pruneStaleFlatPhaseBackups(projectRoot);
@@ -932,7 +1045,7 @@ export function registerHooks(
         );
       }
     } catch (err) {
-      safetyLogWarning("bootstrap", `flat-phase migration: ${err instanceof Error ? err.message : String(err)}`);
+      safetyLogWarning("bootstrap", `flat-phase backup pruning: ${err instanceof Error ? err.message : String(err)}`);
     }
 
     // Apply show_token_cost preference (#1515)
@@ -1090,6 +1203,7 @@ export function registerHooks(
 
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
     approvalQuestionAbortInFlight = false;
+    recordRetryableTurnAbort(event);
     resetToolCallLoopGuard();
     resetPendingGatePauseGuard();
     await resetAskUserQuestionsTurnCache();
@@ -1315,6 +1429,12 @@ export function registerHooks(
     // ── Loop guard: block repeated identical tool calls ──
     const loopCheck = checkToolCallLoop(toolName, event.input as Record<string, unknown>);
     if (loopCheck.block) {
+      recordCurrentUnitHarnessAbort({
+        kind: "tool-loop-guard",
+        reason: loopCheck.reason ?? "Tool-call loop guard blocked a repeated tool call.",
+        toolName,
+        count: loopCheck.count,
+      });
       return { block: true, reason: formatLoopGuardBlockReason(loopCheck.reason) };
     }
 
@@ -1603,6 +1723,7 @@ export function registerHooks(
       // Let recordToolInvocationError classify the failure so non-gsd_ harness
       // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
+      recordRetryableHarnessToolError(toolName, resultPayload, errorText);
     } else if (isAutoActive()) {
       clearToolInvocationError();
     }
@@ -1799,6 +1920,7 @@ export function registerHooks(
   // for every finalized tool call on every engine, so error classification
   // and evidence persistence here cover external engines that skip tool_result.
   pi.on("tool_execution_end", async (event) => {
+    const toolName = canonicalToolName(event.toolName);
     markToolEnd(event.toolCallId);
     // #2883/#4974: Capture deterministic invocation/policy errors
     // so postUnitPreVerification can break the retry loop instead of re-dispatching.
@@ -1809,6 +1931,7 @@ export function registerHooks(
       // Let recordToolInvocationError classify the failure so non-gsd_ harness
       // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
+      recordRetryableHarnessToolError(toolName, event.result, errorText);
     } else if (isAutoActive()) {
       clearToolInvocationError();
     }

package/src/resources/extensions/gsd/bootstrap/schedule-wakeup-tool.ts

@@ -6,22 +6,85 @@ import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 
 import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
 import { scheduleAutoWakeup } from "../auto/schedule-wakeup.js";
+import { logWarning } from "../workflow-logger.js";
 import { resolveCtxCwd } from "./dynamic-tools.js";
 
 const MAX_WAKEUP_DELAY_SECONDS = 24 * 60 * 60;
+const INTERACTIVE_WAKEUP_CUSTOM_TYPE = "gsd-schedule-wakeup";
+
+// One pending interactive wakeup per session, keyed by base path — the same
+// scoping auto-mode uses for its wakeup map (see `wakeupKey`). Re-arming cancels
+// only that session's prior timer, so repeated polling never stacks overlapping
+// wakeups, and concurrent projects in one host process don't cancel each other.
+const pendingInteractiveWakeups = new Map<string, ReturnType<typeof setTimeout>>();
+
+function scheduleInteractiveWakeup(
+  pi: ExtensionAPI,
+  key: string,
+  delaySeconds: number,
+  prompt: string,
+  reason: string,
+): void {
+  const existing = pendingInteractiveWakeups.get(key);
+  if (existing) clearTimeout(existing);
+
+  const handle = setTimeout(() => {
+    if (pendingInteractiveWakeups.get(key) === handle) {
+      pendingInteractiveWakeups.delete(key);
+    }
+    try {
+      void Promise.resolve(pi.sendMessage(
+        {
+          customType: INTERACTIVE_WAKEUP_CUSTOM_TYPE,
+          content: prompt,
+          display: true,
+          details: { delaySeconds, reason },
+        },
+        { triggerTurn: true },
+      )).catch((error) => {
+        logWarning(
+          "bootstrap",
+          `ScheduleWakeup interactive dispatch failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      });
+    } catch (error) {
+      logWarning(
+        "bootstrap",
+        `ScheduleWakeup interactive dispatch failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }, delaySeconds * 1000);
+  pendingInteractiveWakeups.set(key, handle);
+  if (
+    typeof handle === "object" &&
+    handle !== null &&
+    "unref" in handle &&
+    typeof handle.unref === "function"
+  ) {
+    handle.unref();
+  }
+}
+
+export function _resetInteractiveWakeupsForTest(): void {
+  for (const handle of pendingInteractiveWakeups.values()) {
+    clearTimeout(handle);
+  }
+  pendingInteractiveWakeups.clear();
+}
 
 export function registerScheduleWakeupTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "ScheduleWakeup",
     label: "Schedule Wakeup",
     description:
-      "In GSD auto-mode, pause the current unit and continue the same session after a delay. " +
-      "Use this for long external processes that need polling without ending the unit as no-artifact.",
-    promptSnippet: "Schedule a same-session auto-mode wakeup after a delay.",
+      "Schedule a delayed continuation turn. In GSD auto-mode, continue the current unit in the same session; " +
+      "outside auto-mode, start a new triggered turn with the supplied wakeup prompt.",
+    promptSnippet: "Schedule a wakeup prompt after a delay.",
     promptGuidelines: [
       "Use ScheduleWakeup at the end of an execute-task turn when waiting for a long external process.",
       "Include a prompt that says exactly what external state to check next and what artifact to write when done.",
       "Re-arm ScheduleWakeup on each polling turn if the external process is still running.",
+      "Outside auto-mode, use ScheduleWakeup when the user asks you to check back or poll later.",
     ],
     parameters: Type.Object({
       delaySeconds: Type.Number({
@@ -40,27 +103,32 @@ export function registerScheduleWakeupTool(pi: ExtensionAPI): void {
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const dash = getAutoRuntimeSnapshot();
       const currentUnit = dash.currentUnit;
-      const basePath = dash.basePath || resolveCtxCwd(ctx);
+      const delaySeconds = Math.max(
+        1,
+        Math.min(MAX_WAKEUP_DELAY_SECONDS, Math.floor(params.delaySeconds)),
+      );
+      const reason = params.reason ?? "";
 
       if (!dash.active || !currentUnit) {
+        const interactiveKey = dash.basePath || resolveCtxCwd(ctx);
+        scheduleInteractiveWakeup(pi, interactiveKey, delaySeconds, params.prompt, reason);
         return {
-          content: [{ type: "text", text: "ScheduleWakeup is only available during an active GSD auto-mode unit." }],
-          details: { operation: "schedule_wakeup", error: "auto_mode_inactive" },
-          isError: true,
+          content: [{
+            type: "text",
+            text: `Wakeup scheduled for ${delaySeconds}s. GSD will start a new turn with the wakeup prompt.`,
+          }],
+          details: { operation: "schedule_wakeup", delaySeconds, mode: "interactive" },
         };
       }
 
-      const delaySeconds = Math.max(
-        1,
-        Math.min(MAX_WAKEUP_DELAY_SECONDS, Math.floor(params.delaySeconds)),
-      );
+      const basePath = dash.basePath || resolveCtxCwd(ctx);
       scheduleAutoWakeup({
         basePath,
         unitType: currentUnit.type,
         unitId: currentUnit.id,
         delayMs: delaySeconds * 1000,
         prompt: params.prompt,
-        reason: params.reason ?? "",
+        reason,
         createdAt: Date.now(),
       });
 

package/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts

@@ -25,6 +25,8 @@
 
 import { createHash } from "node:crypto";
 import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
 
 const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 
@@ -130,8 +132,16 @@ export function checkToolCallLoop(
   perToolLastMutationEpoch.set(toolName, mutationEpoch);
 
   // Read-only navigation tools are normal context gathering; Guard 1 still
-  // catches true reread loops with identical arguments.
-  if (PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName)) {
+  // catches true reread loops with identical arguments. Browser Automation
+  // Contract tools (browser_*) are the same shape: a browser-backed UAT makes
+  // many distinct-arg calls (read a message, count edits, inspect a card, …),
+  // so the arg-independent per-tool cap misfires on legitimate verification;
+  // Guard 1's identical-signature streak still catches a genuinely stuck
+  // browser loop.
+  if (
+    PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName) ||
+    hasBrowserContractPrefix(canonicalToolName(toolName))
+  ) {
     return { block: false, count: consecutiveCount };
   }
 

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1169,7 +1169,7 @@ function allowsControlledSubagentDispatch(
   policy: ToolsPolicy,
 ): policy is ToolsPolicy & { readonly allowedSubagents: readonly string[] } {
   return (
-    (policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    (policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
     Array.isArray((policy as { readonly allowedSubagents?: unknown }).allowedSubagents)
   );
 }
@@ -1199,6 +1199,7 @@ function warnMissingControlledDispatchAgentClasses(unitType: string, mode: strin
 const PLANNING_SAFE_TOOLS = new Set([
   "read", "grep", "find", "ls", "glob",
   "ask_user_questions",
+  "memory_query",
   "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
   "search_and_read",
 ]);
@@ -1265,6 +1266,9 @@ type PlanningUnitBlockResult = {
  *                  → allows Bash for project verification commands, keeps
  *                    writes restricted to .gsd/, and permits subagent dispatch
  *                    only when the manifest declares allowedSubagents.
+ *   - "workflow-only"
+ *                  → allows reads, GSD workflow tools, and declared read-only
+ *                    subagents; blocks generic Bash and direct file writes.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -1354,6 +1358,24 @@ export function shouldBlockPlanningUnit(
     return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
   }
 
+  if (policy.mode === "workflow-only") {
+    if (tool === "bash") {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `bash is not permitted; use the unit's dedicated GSD workflow tools for durable validation output`,
+      );
+    }
+    if (PLANNING_WRITE_TOOLS.has(tool)) {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `cannot ${tool} "${pathOrCommand}" — direct artifact writes are disabled; call the required GSD workflow tool instead`,
+      );
+    }
+    return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the workflow-only allowlist`);
+  }
+
   if (tool === "bash") {
     if (policy.mode === "verification") {
       if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };