@opengsd/gsd-pi 1.2.0-dev.e8563f58 → 1.2.0-dev.fbdca60b

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

@@ -74,6 +74,7 @@ import {
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { evaluateAllCompleteSettlement } from "../milestone-settlement.js";
+import { hasHeldMilestoneLease, reclaimMissingMilestoneLease } from "./milestone-lease-reclaim.js";
 
 function now(): number {
   return Date.now();
@@ -209,6 +210,7 @@ export async function decideOrchestratorDispatch(
 
   if (active && activeSession && shouldAdoptActiveMilestone(state, activeSession, activeDispatchBasePath)) {
     activeSession.currentMilestoneId = active.id;
+    activeSession.milestoneLeaseToken = null;
   }
   const dispatchMid = active?.id ?? activeSession?.currentMilestoneId ?? "";
   const dispatchMidTitle = active?.title ?? "";
@@ -609,6 +611,37 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     };
   }
 
+  private async mergePendingCompleteMilestone(milestoneId: string): Promise<{ ok: true } | { ok: false; reason: string }> {
+    const result = this.buildLifecycle().exitMilestone(
+      milestoneId,
+      { merge: true },
+      this.ctx.ui,
+    );
+    if (!result.ok) {
+      const detail = result.cause instanceof Error
+        ? result.cause.message
+        : result.reason;
+      return {
+        ok: false,
+        reason: `Milestone ${milestoneId} is complete, but the system-owned merge failed: ${detail}`,
+      };
+    }
+
+    this.s.milestoneMergedInPhases = true;
+    this.s.milestoneSettlement = { ok: true, reason: "settled" };
+    try {
+      const projectRoot = this.s.originalBasePath || this.s.canonicalProjectRoot || this.runtimeBasePath;
+      const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
+      await rebuildMarkdownProjectionsFromDb(projectRoot);
+    } catch (err) {
+      logWarning(
+        "engine",
+        `markdown projection rebuild after settlement merge failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    return { ok: true };
+  }
+
   private clearPendingDispatch(): void {
     this.s.pendingOrchestrationDispatch = null;
   }
@@ -688,9 +721,6 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         reason: `No Unit manifest is registered for ${unitType}`,
       };
     }
-    if (isolationMode !== "worktree") {
-      return { ok: true, reason: "not-required" };
-    }
     const writeScope =
       manifest.tools.mode === "all" || manifest.tools.mode === "docs"
         ? "source-writing"
@@ -699,7 +729,23 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     const activeBasePath = this.getLiveDispatchBasePath();
     const snapshot = await deriveState(activeBasePath);
     const milestoneId = snapshot.activeMilestone?.id ?? null;
-    const expectedBranch = milestoneId ? autoWorktreeBranch(milestoneId) : null;
+    const buildExpectedBranch = (mode: ReturnType<typeof getIsolationMode>) =>
+      mode !== "none" && milestoneId ? autoWorktreeBranch(milestoneId) : null;
+    // The milestone lease coordinates concurrent workers on an isolated
+    // milestone worktree/branch. `none` mode has no per-milestone isolation
+    // and does not reliably claim a lease, so requiring one there would
+    // falsely fail dispatch; enforce it only in isolated modes.
+    const buildLease = (mode: ReturnType<typeof getIsolationMode>) =>
+      milestoneId && this.s.workerId
+        ? {
+            required: writeScope === "source-writing" && mode !== "none",
+            held: hasHeldMilestoneLease(this.s, milestoneId),
+            owner: this.s.workerId,
+          }
+        : undefined;
+    if (writeScope === "source-writing") {
+      reclaimMissingMilestoneLease(this.s, milestoneId, isolationMode, "orchestrator");
+    }
     let result = safety.validateUnitRoot({
       unitType,
       unitId,
@@ -708,7 +754,8 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       unitRoot: activeBasePath,
       milestoneId,
       isolationMode,
-      expectedBranch,
+      expectedBranch: buildExpectedBranch(isolationMode),
+      lease: buildLease(isolationMode),
     });
     if (!result.ok) {
       const repaired = await repairAutoWorktreeSafetyFailure({
@@ -725,16 +772,20 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
           this.rebuildScope(this.s.basePath, this.s.currentMilestoneId);
           return { ok: true };
         },
-        revalidate: () => safety.validateUnitRoot({
-          unitType,
-          unitId,
-          writeScope,
-          projectRoot: this.runtimeBasePath,
-          unitRoot: this.getLiveDispatchBasePath(),
-          milestoneId,
-          isolationMode: this.getEffectiveUnitIsolationMode(this.runtimeBasePath),
-          expectedBranch,
-        }),
+        revalidate: () => {
+          const revalidatedMode = this.getEffectiveUnitIsolationMode(this.runtimeBasePath);
+          return safety.validateUnitRoot({
+            unitType,
+            unitId,
+            writeScope,
+            projectRoot: this.runtimeBasePath,
+            unitRoot: this.getLiveDispatchBasePath(),
+            milestoneId,
+            isolationMode: revalidatedMode,
+            expectedBranch: buildExpectedBranch(revalidatedMode),
+            lease: buildLease(revalidatedMode),
+          });
+        },
       });
       result = repaired.result;
       if (result.ok) {
@@ -942,6 +993,35 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       if (!decision) {
         const settlementBlock = this.evaluateNoRemainingUnitsSettlement(reconciliation.stateSnapshot);
         if (settlementBlock) {
+          const settlement = this.s.milestoneSettlement;
+          if (settlement && !settlement.ok && settlement.reason === "merge-pending") {
+            const merged = await this.mergePendingCompleteMilestone(settlement.milestoneId);
+            if (merged.ok) {
+              const terminalOutcome = noRemainingUnitsOutcome(reconciliation.stateSnapshot);
+              const stopped: AutoAdvanceResult = {
+                kind: "stopped",
+                reason: terminalOutcome.displayReason,
+                stateSnapshot: reconciliation.stateSnapshot,
+                terminalOutcome,
+              };
+              this.status.phase = "stopped";
+              this.status.activeUnit = undefined;
+              this.lastAdvanceKey = null;
+              this.dispatchHistory.clearOnRecovery();
+              this.bumpTransition();
+              this.journalTransition({ name: "advance-stopped", reason: stopped.reason });
+              this.postAdvanceRecord(stopped);
+              return stopped;
+            }
+            settlementBlock.reason = merged.reason;
+            settlementBlock.terminalOutcome = {
+              code: "settlement-blocked",
+              displayReason: merged.reason,
+              nextAction: `Fix the merge failure, then retry \`/gsd dispatch complete-milestone ${settlement.milestoneId}\`.`,
+              milestoneId: settlement.milestoneId,
+              allMilestonesComplete: false,
+            };
+          }
           this.status.phase = "paused";
           this.status.activeUnit = undefined;
           this.lastAdvanceKey = null;

package/src/resources/extensions/gsd/auto/phase-helpers.ts

@@ -0,0 +1,199 @@
+// Project/App: gsd-pi
+// File Purpose: Shared helpers used across auto-loop phase modules.
+
+import { setRuntimeKv } from "../db/runtime-kv.js";
+import { debugLog } from "../debug-logger.js";
+import { normalizeRealPath } from "../paths.js";
+import { resolveWorktreeProjectRoot, normalizeWorktreePathForCompare } from "../worktree-root.js";
+import { decideVerificationRetry, verificationRetryKey } from "./verification-retry-policy.js";
+import type { AutoSession } from "./session.js";
+import type { IterationContext, IterationData, LoopState, PhaseResult } from "./types.js";
+import type { Phase } from "../types.js";
+
+const STUCK_RECOVERY_ATTEMPTS_KEY = "stuck_recovery_attempts";
+
+/** Compare two paths for physical identity, tolerating trailing slashes and symlinks. */
+export function isSamePathLocal(a: string, b: string): boolean {
+  return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
+}
+
+export function isIsolatedWorktreeSession(s: AutoSession): boolean {
+  return Boolean(s.originalBasePath)
+    && Boolean(s.basePath)
+    && !isSamePathLocal(s.originalBasePath, s.basePath);
+}
+
+export function persistStuckRecoveryAttempts(s: AutoSession, loopState: LoopState): void {
+  const scopeId = normalizeRealPath(
+    s.scope?.workspace.projectRoot ?? (s.originalBasePath || s.basePath),
+  );
+  if (!scopeId) return;
+  try {
+    setRuntimeKv("global", scopeId, STUCK_RECOVERY_ATTEMPTS_KEY, loopState.stuckRecoveryAttempts);
+  } catch (err) {
+    debugLog("autoLoop", {
+      phase: "save-stuck-state-failed",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+export async function applyVerificationRetryPolicy(
+  ic: IterationContext,
+  unitType: string | undefined,
+  phase: "artifact-verification-retry" | "verification-retry" | "pre-execution-retry",
+): Promise<PhaseResult | null> {
+  const { ctx, pi, s, deps } = ic;
+  const retryInfo = s.pendingVerificationRetry;
+  const key = unitType && retryInfo
+    ? verificationRetryKey(unitType, retryInfo.unitId)
+    : undefined;
+  const decision = decideVerificationRetry({
+    unitType,
+    retryInfo,
+    previousFailureHash: key ? s.verificationRetryFailureHashes.get(key) : undefined,
+  });
+
+  if (decision.action === "pause") {
+    s.pendingVerificationRetry = null;
+    debugLog("autoLoop", {
+      phase: `${phase}-paused`,
+      reason: decision.reason,
+      unitType,
+      unitId: retryInfo?.unitId,
+      failureHash: decision.failureHash,
+    });
+    ctx.ui.notify(
+      decision.reason === "duplicate-failure-context"
+        ? `Verification retry for ${unitType ?? "unit"} ${retryInfo?.unitId ?? "unknown"} produced the same failure context. Pausing auto-mode instead of re-dispatching.`
+        : "Verification retry requested without retry context. Pausing auto-mode instead of re-dispatching.",
+      "warning",
+    );
+    await deps.pauseAuto(ctx, pi);
+    return { action: "break", reason: decision.reason };
+  }
+
+  s.verificationRetryFailureHashes.set(decision.key, decision.failureHash);
+  debugLog("autoLoop", {
+    phase: `${phase}-backoff`,
+    iteration: ic.iteration,
+    unitType,
+    unitId: retryInfo?.unitId,
+    attempt: retryInfo?.attempt,
+    delayMs: decision.delayMs,
+    baseDelayMs: decision.baseDelayMs,
+    failureHash: decision.failureHash,
+  });
+  await new Promise<void>((resolve) => setTimeout(resolve, decision.delayMs));
+  return null;
+}
+
+export function rememberRetryDispatch(
+  s: AutoSession,
+  unit: { type: string; id: string } | null,
+  iterData: IterationData,
+): void {
+  if (!unit) return;
+  s.pendingVerificationRetryDispatch = {
+    unitType: unit.type,
+    unitId: unit.id,
+    prompt: iterData.prompt,
+    pauseAfterUatDispatch: iterData.pauseAfterUatDispatch,
+    state: iterData.state,
+    mid: iterData.mid,
+    midTitle: iterData.midTitle,
+  };
+}
+
+/**
+ * Resolve the base path for milestone reports.
+ * Prefers originalBasePath (project root) over basePath (which may be a worktree).
+ */
+export function _resolveReportBasePath(s: Pick<AutoSession, "originalBasePath" | "basePath">): string {
+  return resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
+}
+
+/**
+ * Resolve the authoritative project base for dispatch guards.
+ * Prior-milestone completion lives at the project root, even when the active
+ * unit is running inside an auto worktree.
+ */
+export function _resolveDispatchGuardBasePath(
+  s: Pick<AutoSession, "originalBasePath" | "basePath">,
+): string {
+  return resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
+}
+
+const PLAN_V2_GATE_PHASES: ReadonlySet<Phase> = new Set([
+  "executing",
+  "summarizing",
+  "validating-milestone",
+  "completing-milestone",
+]);
+
+export function shouldRunPlanV2Gate(phase: Phase): boolean {
+  return PLAN_V2_GATE_PHASES.has(phase);
+}
+
+export function _resolveCurrentUnitStartedAtForTest(
+  currentUnit: { startedAt: number } | null | undefined,
+): number | undefined {
+  return currentUnit?.startedAt;
+}
+
+export async function emitCancelledUnitEnd(
+  ic: IterationContext,
+  unitType: string,
+  unitId: string,
+  unitStartSeq: number,
+  errorContext?: { message: string; category: string; stopReason?: string; isTransient?: boolean; retryAfterMs?: number },
+): Promise<void> {
+  ic.deps.emitJournalEvent({
+    ts: new Date().toISOString(),
+    flowId: ic.flowId,
+    seq: ic.nextSeq(),
+    eventType: "unit-end",
+    data: {
+      unitType,
+      unitId,
+      status: "cancelled",
+      artifactVerified: false,
+      ...(errorContext ? { errorContext } : {}),
+    },
+    causedBy: { flowId: ic.flowId, seq: unitStartSeq },
+  });
+}
+
+export function _buildCancelledUnitStopReason(
+  unitType: string,
+  unitId: string,
+  errorContext?: { message: string; category: string },
+): {
+  notifyMessage: string;
+  stopReason: string;
+  loopReason: "session-failed" | "unit-aborted";
+} {
+  const cancellationMessage = errorContext?.message ?? "unknown";
+  const isSessionCreationFailure = errorContext?.category === "session-failed";
+
+  if (isSessionCreationFailure) {
+    return {
+      notifyMessage: `Session creation failed for ${unitType} ${unitId}: ${cancellationMessage}. Stopping auto-mode.`,
+      stopReason: `Session creation failed: ${cancellationMessage}`,
+      loopReason: "session-failed",
+    };
+  }
+
+  return {
+    notifyMessage: `Unit ${unitType} ${unitId} aborted after dispatch: ${cancellationMessage}. Stopping auto-mode.`,
+    stopReason: `Unit aborted: ${cancellationMessage}`,
+    loopReason: "unit-aborted",
+  };
+}
+
+export function _isPauseOriginCancelledResult(
+  isPaused: boolean,
+  errorContext?: { message: string; category: string },
+): boolean {
+  return isPaused && !errorContext;
+}