@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -1,20 +1,22 @@
 // Project/App: gsd-pi
 // File Purpose: Registers GSD extension runtime hooks and token-saving tool policies.
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { ALWAYS_PRESERVED_SHIM_TOOL_NAMES } from "@gsd/pi-ai";
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
-import { buildMilestoneFileName, clearPathCache, milestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { applyAskUserQuestionsGateResult, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeBash, shouldBlockWorktreeWrite, isGateQuestionId, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { buildMilestoneFileName, canonicalPhaseDirName, clearPathCache, milestonesDir, legacyMilestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
+import { applyAskUserQuestionsGateResult, clearDiscussionFlowState, currentWriteGateSnapshot, formatPendingAskUserQuestionsGateMessage, formatTimedOutAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeBash, shouldBlockWorktreeWrite, isGateQuestionId, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { canonicalToolName } from "../engine-hook-contract.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { clearAutoCompletionStopInProgress, clearToolInvocationError, getAutoRuntimeSnapshot, getSourceObservationStore, isAutoActive, isAutoCompletionStopInProgress, isAutoPaused, isInteractiveElicitationInFlight, markToolEnd, markToolStart, 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, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
+import { checkToolCallLoop, 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";
 import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
@@ -42,7 +44,15 @@ import { supportsSourceObservationsForUnit } from "../source-observations.js";
 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 } from "../unit-runtime.js";
 let approvalQuestionAbortInFlight = false;
+function recordCurrentUnitHarnessAbort(abort) {
+    const dash = getAutoRuntimeSnapshot();
+    if (!dash.active || !dash.basePath || !dash.currentUnit)
+        return;
+    recordUnitHarnessAbort(dash.basePath, dash.currentUnit.type, dash.currentUnit.id, dash.currentUnit.startedAt, abort);
+}
 async function loadWelcomeScreenModule() {
     const candidates = [];
     const gsdBinPath = process.env.GSD_BIN_PATH;
@@ -138,22 +148,7 @@ export const MINIMAL_GSD_TOOL_NAMES = [
     "capture_thought",
     "gsd_capture_thought",
 ];
-export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
-    "ask_user_questions",
-    "bash",
-    "bg_shell",
-    "edit",
-    "find",
-    "glob",
-    "grep",
-    "fetch_page",
-    "search-the-web",
-    "ls",
-    "read",
-    "subagent",
-    "write",
-    "ToolSearch",
-];
+export { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 function withPreservedShimTools(toolNames) {
     return [...new Set([...toolNames, ...ALWAYS_PRESERVED_SHIM_TOOL_NAMES])];
 }
@@ -173,9 +168,23 @@ const WORKFLOW_GSD_TOOL_NAMES = [
     ...MINIMAL_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",
+];
 function isGsdManagedTool(name) {
     return name.startsWith("gsd_") || name === "memory_query" || name === "capture_thought" || name === "gsd_graph";
 }
+function autoBaseToolNamesForUnit(unitType) {
+    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.
  *
@@ -226,7 +235,7 @@ export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registered
         return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
     }
     const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
-    const autoBaseTools = new Set(MINIMAL_AUTO_BASE_TOOL_NAMES);
+    const autoBaseTools = new Set(autoBaseToolNamesForUnit(unitType));
     const availableBaseTools = registeredToolNames.filter((name) => autoBaseTools.has(name));
     const preserved = [...new Set([
             ...activeToolNames.filter((name) => autoBaseTools.has(name)),
@@ -436,6 +445,9 @@ function deferApprovalGate(gateId, basePath) {
     // workflow MCP child already verified this gate, deferring would block
     // tools for a gate that can never legitimately arm.
     const snapshot = hostWriteGateAdapter.readState(basePath);
+    deferApprovalGateFromSnapshot(gateId, basePath, snapshot);
+}
+function deferApprovalGateFromSnapshot(gateId, basePath, snapshot) {
     if (isApprovalGateVerifiedInSnapshot(snapshot, gateId))
         return;
     const milestoneId = extractDepthVerificationMilestoneId(gateId);
@@ -446,6 +458,85 @@ function deferApprovalGate(gateId, basePath) {
 function contextBasePath(ctx) {
     return typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
 }
+const LOOP_GUARD_INTERACTIVE_INSTRUCTIONS = [
+    "Do not retry this tool or call other tools this turn — stop and respond to the user in text.",
+    "Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.",
+];
+const LOOP_GUARD_AUTO_INSTRUCTION = "Do not re-issue this blocked tool. In /gsd auto, stop tool calls for this turn and return control to the auto-mode recovery/replan path.";
+function formatLoopGuardBlockReason(reason) {
+    if (!reason || !getAutoRuntimeSnapshot().active)
+        return reason;
+    return LOOP_GUARD_INTERACTIVE_INSTRUCTIONS.reduce((formatted, instruction) => formatted.replace(instruction, LOOP_GUARD_AUTO_INSTRUCTION), reason);
+}
+function isGateResultPersistenceTool(toolName) {
+    return toolName === "gsd_save_gate_result" || toolName === "gsd_uat_result_save";
+}
+function resultDetails(result) {
+    if (!result || typeof result !== "object")
+        return {};
+    const details = result.details;
+    return details && typeof details === "object" ? details : {};
+}
+function isAbortedExecutionToolResult(toolName, result) {
+    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, result, errorText) {
+    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, result, errorText) {
+    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) {
+    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.stopReason
+        : undefined;
+    if (stopReason !== "aborted" && stopReason !== "error")
+        return;
+    const errorMessage = lastMsg && typeof lastMsg === "object"
+        ? lastMsg.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) {
     if (!isAutoActive())
         return null;
@@ -526,7 +617,7 @@ function isContextDraftSummarySave(toolName, input) {
  */
 function resolveAskUserQuestionsGateDetails(event) {
     const hasRoundShape = (value) => !!value && typeof value === "object" &&
-        (value.cancelled !== undefined || value.response !== undefined);
+        (value.cancelled !== undefined || value.timed_out !== undefined || value.response !== undefined);
     const details = event.details;
     if (hasRoundShape(details))
         return details;
@@ -566,8 +657,24 @@ function formatQuestionExchange(questions, answers) {
     return lines.join("\n");
 }
 async function ensureMilestoneShell(basePath, milestoneId) {
+    // When no milestone dir exists yet, prefer the legacy container when it has
+    // at least one milestone subdirectory; an empty milestones/ dir (e.g. one
+    // created by an old bootstrapGsdProject) is not a real legacy layout.
+    const legacy = legacyMilestonesDir(basePath);
+    const isLegacyLayout = existsSync(legacy) && (() => {
+        try {
+            return readdirSync(legacy).some(e => statSync(join(legacy, e)).isDirectory());
+        }
+        catch {
+            return false;
+        }
+    })();
+    const container = isLegacyLayout ? legacy : milestonesDir(basePath);
+    const fallbackDirName = isLegacyLayout
+        ? milestoneId
+        : canonicalPhaseDirName(milestoneId, `New milestone ${milestoneId}`);
     const milestoneDir = resolveMilestonePath(basePath, milestoneId)
-        ?? join(milestonesDir(basePath), milestoneId);
+        ?? join(container, fallbackDirName);
     mkdirSync(milestoneDir, { recursive: true });
     clearPathCache();
     try {
@@ -593,10 +700,14 @@ async function saveDiscussionQuestionRound(basePath, milestoneId, questions, det
     const answers = details?.response?.answers;
     const timestamp = new Date().toISOString();
     const exchange = formatQuestionExchange(questions, answers);
-    const discussionPath = join(milestoneDir, buildMilestoneFileName(milestoneId, "DISCUSSION"));
+    // Layout-aware filename: legacy dirs use MID-SUFFIX.md; flat-phase use NN-SUFFIX.md.
+    const legacyBase = legacyMilestonesDir(basePath);
+    const isLegacyDir = milestoneDir.startsWith(legacyBase + "/") || milestoneDir.startsWith(legacyBase + "\\");
+    const milestoneFileName = (suffix) => isLegacyDir ? `${milestoneId}-${suffix}.md` : buildMilestoneFileName(milestoneId, suffix);
+    const discussionPath = join(milestoneDir, milestoneFileName("DISCUSSION"));
     const existingDiscussion = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
     await saveFile(discussionPath, `${existingDiscussion}## Exchange — ${timestamp}\n\n${exchange}---\n\n`);
-    const draftPath = join(milestoneDir, buildMilestoneFileName(milestoneId, "CONTEXT-DRAFT"));
+    const draftPath = join(milestoneDir, milestoneFileName("CONTEXT-DRAFT"));
     const existingDraft = await loadFile(draftPath);
     const draftHeader = existingDraft
         ?? [
@@ -675,6 +786,43 @@ export function registerHooks(pi, ecosystemHandlers) {
         await applyDisabledModelProviderPolicy(ctx);
         await applyCompactionThresholdOverride(ctx);
         await prepareWorkflowMcpForHookContext(ctx, basePath);
+        // Migrate legacy .gsd/milestones/ to flat-phase .gsd/phases/ when detected.
+        // 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)) {
+                const { needsFlatPhaseMigration } = await import("../flat-phase-migration.js");
+                if (needsFlatPhaseMigration(basePath)) {
+                    const { ensureDbOpen } = await import("./dynamic-tools.js");
+                    const opened = await ensureDbOpen(basePath);
+                    if (opened) {
+                        const { migrateToFlatPhase } = await import("../flat-phase-migration.js");
+                        await migrateToFlatPhase(basePath);
+                    }
+                    else {
+                        safetyLogWarning("bootstrap", "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);
+            if (pruned > 0) {
+                safetyLogWarning("bootstrap", `pruned ${pruned} stale flat-phase migration backup(s) from .gsd-backups/ (retention exceeded)`);
+            }
+        }
+        catch (err) {
+            safetyLogWarning("bootstrap", `flat-phase backup pruning: ${err instanceof Error ? err.message : String(err)}`);
+        }
         // Apply show_token_cost preference (#1515)
         try {
             const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -822,12 +970,24 @@ export function registerHooks(pi, ecosystemHandlers) {
     });
     pi.on("agent_end", async (event, ctx) => {
         approvalQuestionAbortInFlight = false;
+        recordRetryableTurnAbort(event);
         resetToolCallLoopGuard();
         resetPendingGatePauseGuard();
         await resetAskUserQuestionsTurnCache();
         const { handleAgentEnd } = await import("./agent-end-recovery.js");
         const agentEndBasePath = contextBasePath(ctx);
         try {
+            // The manifest is a non-critical projection (the append-only event log is
+            // the authoritative recovery source), so a flush failure must not skip
+            // agent_end recovery. drainManifestWrites still propagates write failures
+            // to explicit flush callers; here we deliberately log and continue so
+            // handleAgentEnd (and the finally below) always run.
+            try {
+                await flushAllManifests();
+            }
+            catch (err) {
+                safetyLogWarning("manifest", `flushAllManifests on agent_end failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
             await handleAgentEnd(pi, event, ctx);
         }
         finally {
@@ -966,14 +1126,16 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         const gateId = approvalGateIdForUnit(unitType, unitId);
         if (gateId) {
+            const basePath = contextBasePath(ctx);
+            const gateSnapshot = currentWriteGateSnapshot(basePath);
             // Skip the gate if this milestone is already depth-verified — the approval
             // pattern matched again on post-verification text (a false-positive re-trigger).
             // Without this guard, the second firing blocks gsd_plan_milestone in the same
             // turn and leaves CONTEXT.md on disk with no DB row (#discuss-milestone-no-db).
             const gateMilestoneId = extractDepthVerificationMilestoneId(gateId);
-            if (gateMilestoneId && isMilestoneDepthVerified(gateMilestoneId, contextBasePath(ctx)))
+            if (gateMilestoneId && isMilestoneDepthVerifiedInSnapshot(gateSnapshot, gateMilestoneId))
                 return;
-            deferApprovalGate(gateId, contextBasePath(ctx));
+            deferApprovalGateFromSnapshot(gateId, basePath, gateSnapshot);
         }
         approvalQuestionAbortInFlight = true;
         ctx.ui.notify(`${unitType ?? "The discussion"}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`, "info");
@@ -1015,7 +1177,13 @@ export function registerHooks(pi, ecosystemHandlers) {
         // ── Loop guard: block repeated identical tool calls ──
         const loopCheck = checkToolCallLoop(toolName, event.input);
         if (loopCheck.block) {
-            return { block: true, reason: loopCheck.reason };
+            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) };
         }
         const deferredGateGuard = shouldBlockDeferredApprovalTool(toolName, event.input, discussionBasePath);
         if (deferredGateGuard.block) {
@@ -1221,6 +1389,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
         if (!event.isError) {
+            recordToolCallLoopMutation(toolName);
             refreshSourceObservationAfterMutation(toolName, event.input, ctx);
             clearSourceObservationsAfterShell(toolName);
         }
@@ -1236,6 +1405,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             // 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();
@@ -1281,6 +1451,23 @@ export function registerHooks(pi, ecosystemHandlers) {
                     }],
             };
         }
+        if (gateResult.status === "timeout") {
+            // Host elicitation timed out before the user answered. The gate stays
+            // pending (fail-closed), but we reset the loop guard and return a
+            // timeout-specific message so the model does NOT immediately re-ask —
+            // that would just hit the same timeout again. Auto-mode pauses and
+            // waits for the user to respond on a new turn (#852).
+            resetToolCallLoopGuard();
+            if (ctx) {
+                await maybePauseAutoForApprovalGate(ctx, pi, true, "Depth confirmation timed out waiting for a response — pausing auto-mode. Reply to resume.");
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: formatTimedOutAskUserQuestionsGateMessage(gateResult.pendingGateId),
+                    }],
+            };
+        }
         if (gateResult.status === "verified") {
             clearDeferredApprovalGate(basePath);
         }
@@ -1298,6 +1485,16 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
             return;
         }
+        if (roundOutcome === "timeout") {
+            // Non-gate (consent/decision) question timed out at the host elicitation.
+            // Same policy as the gate-timeout branch above: reset the loop guard and
+            // pause-and-wait so the model does not re-ask into the same timeout (#852).
+            resetToolCallLoopGuard();
+            if (ctx) {
+                await maybePauseAutoForApprovalGate(ctx, pi, true, "A user question timed out waiting for a response — pausing auto-mode. Reply to resume.");
+            }
+            return;
+        }
         if (roundOutcome === "waiting") {
             resetToolCallLoopGuard();
             if (ctx) {
@@ -1376,6 +1573,7 @@ export function registerHooks(pi, ecosystemHandlers) {
     // 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.
@@ -1386,6 +1584,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             // 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();