@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

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

@@ -177,24 +177,18 @@ import {
 import { GitServiceImpl } from "./git-service.js";
 import { nativeCheckoutBranch } from "./native-git-bridge.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
-import {
-  createAutoWorktree,
-  enterAutoWorktree,
-  enterBranchModeForMilestone,
-  teardownAutoWorktree,
-  isInAutoWorktree,
-  getAutoWorktreePath,
-  getAutoWorktreeOriginalBase,
-  mergeMilestoneToMain,
-  autoWorktreeBranch,
-  syncWorktreeStateBack,
-  readResourceVersion,
-  checkResourcesStale,
-  escapeStaleWorktree,
-} from "./auto-worktree.js";
+import { autoWorktreeBranch, enterBranchModeForMilestone } from "./auto-worktree-branch-lifecycle.js";
+import { createAutoWorktree } from "./auto-worktree-creation.js";
+import { enterAutoWorktree, isInAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
+import { checkResourcesStale, readResourceVersion } from "./auto-worktree-resource-version.js";
+import { escapeStaleWorktree } from "./auto-worktree-runtime-cleanup.js";
+import { getAutoWorktreeOriginalBase } from "./auto-worktree-session-registry.js";
+import { syncWorktreeStateBack } from "./auto-worktree-sync.js";
+import { teardownAutoWorktree } from "./auto-worktree-teardown.js";
 import { pruneQueueOrder } from "./queue-order.js";
 import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
-import { createMilestoneMergeTransaction } from "./milestone-merge-transaction.js";
+import { createDefaultMilestoneMergeTransaction } from "./milestone-merge-transaction.js";
 
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import {
@@ -236,7 +230,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 +1045,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 +1071,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 +1622,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 +2311,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 +2320,7 @@ export function buildWorktreeLifecycleDeps(): WorktreeLifecycleDeps {
       return new GitServiceImpl(basePath, gitConfig);
     },
     worktreeProjection: new WorktreeStateProjection(),
-    mergeMilestoneToMain: createMilestoneMergeTransaction(mergeMilestoneToMain),
+    mergeMilestone: createDefaultMilestoneMergeTransaction(),
   };
 }
 
@@ -2357,6 +2369,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/dynamic-tools.ts

@@ -14,7 +14,7 @@ import {
   type WorkflowDatabaseOpenResult,
   type WorkflowDatabaseStatus,
 } from "../db-workspace.js";
-import { getAutoWorktreePath } from "../auto-worktree.js";
+import { getAutoWorktreePath } from "../auto-worktree-path-resolution.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { worktreesDirs } from "../worktree-placement.js";
 

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

@@ -32,9 +32,15 @@ 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";
+import { checkToolCallLoop, configureToolCallLoopGuard, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
 import { saveActivityLog } from "../activity-log.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)),
@@ -557,6 +594,22 @@ async function applyCompactionThresholdOverride(ctx: ExtensionContext): Promise<
   }
 }
 
+/**
+ * Apply user-tunable tool-call loop guard thresholds (#1198) from GSD
+ * preferences plus GSD_TOOL_LOOP_* env overrides. Runs at session boundaries
+ * so both interactive sessions and `/gsd auto` pick up the configuration.
+ * Non-fatal: falls back to built-in defaults when preferences cannot be loaded.
+ */
+async function applyToolCallLoopGuardConfig(basePath: string): Promise<void> {
+  try {
+    const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+    const prefs = loadEffectiveGSDPreferences(basePath);
+    configureToolCallLoopGuard(prefs?.preferences.tool_call_loop_guard);
+  } catch {
+    configureToolCallLoopGuard(null);
+  }
+}
+
 function clearDeferredApprovalGate(basePath?: string): void {
   if (!basePath) {
     deferredApprovalGates.clear();
@@ -599,6 +652,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 {
@@ -893,6 +1012,7 @@ export function registerHooks(
     }
     resetWriteGateState(basePath);
     resetToolCallLoopGuard();
+    await applyToolCallLoopGuardConfig(basePath);
     approvalQuestionAbortInFlight = false;
     clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
@@ -902,8 +1022,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 +1037,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 +1062,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)
@@ -974,6 +1104,7 @@ export function registerHooks(
     initSessionNotifications(ctx);
     resetWriteGateState(basePath);
     resetToolCallLoopGuard();
+    await applyToolCallLoopGuardConfig(basePath);
     clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
     clearDiscussionFlowState(basePath);
@@ -1090,6 +1221,7 @@ export function registerHooks(
 
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
     approvalQuestionAbortInFlight = false;
+    recordRetryableTurnAbort(event);
     resetToolCallLoopGuard();
     resetPendingGatePauseGuard();
     await resetAskUserQuestionsTurnCache();
@@ -1315,6 +1447,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) };
     }
 
@@ -1587,7 +1725,7 @@ export function registerHooks(
       }
     }
     if (!event.isError) {
-      recordToolCallLoopMutation(toolName);
+      recordToolCallLoopMutation(toolName, event.details);
       refreshSourceObservationAfterMutation(toolName, event.input, ctx);
       clearSourceObservationsAfterShell(toolName);
     }
@@ -1603,6 +1741,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 +1938,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 +1949,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/system-context.ts

@@ -14,7 +14,7 @@ import { resolveModelWithFallbacksForUnit } from "../preferences-models.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
 import { extractIntroAndRules } from "../knowledge-parser.js";
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
-import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
+import { getActiveAutoWorktreeContext } from "../auto-worktree-session-registry.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-session-state.js";
 import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";