@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/src/resources/extensions/gsd/reopen-reason.ts

@@ -0,0 +1,109 @@
+// Project/App: gsd-pi
+// File Purpose: Persist a reopened task's failure diagnosis and inject it into the re-dispatched execute-task prompt.
+// GSD Extension — follow-up to #1225 (#1272)
+//
+// When complete-slice's gate reopens a task via gsd_task_reopen, the operator
+// supplies a `reason` explaining exactly what the full-suite gate caught and
+// how to fix it. That reason previously only landed in the workflow event log
+// (audit trail) and never reached the re-dispatched executor, so the executor
+// re-ran the original (green) verify and re-completed the task without touching
+// the regression. This module is the "inject unresolved context into the next
+// dispatch" mechanism for reopen reasons — a lightweight, file-based sibling of
+// escalation.js#claimOverrideForInjection, keyed by (milestone, slice, task).
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { legacyMilestonesDir, resolveSlicePath, resolveTasksDir } from "./paths.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { logWarning } from "./workflow-logger.js";
+
+interface ReopenReasonArtifact {
+  version: 1;
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  reason: string;
+  createdAt: string;
+}
+
+/**
+ * Canonical reopen-reason artifact path, parallel to T##-SUMMARY.md and
+ * T##-ESCALATION.json:
+ *   .gsd/milestones/{M}/slices/{S}/tasks/{T}-REOPEN.json
+ * Flat-phase: the artifact sits directly in the phase dir. Legacy layouts
+ * without a tasks/ subdir return null (caller degrades gracefully).
+ */
+export function reopenReasonArtifactPath(
+  basePath: string, milestoneId: string, sliceId: string, taskId: string,
+): string | null {
+  const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  if (tDir) return join(tDir, `${taskId}-REOPEN.json`);
+  if (existsSync(legacyMilestonesDir(basePath))) return null;
+  const phaseDir = resolveSlicePath(basePath, milestoneId, sliceId);
+  if (!phaseDir) return null;
+  return join(phaseDir, `${taskId}-REOPEN.json`);
+}
+
+/**
+ * Persist the reopen reason so the next execute-task dispatch can surface it.
+ * A no-op when the reason is empty or the artifact path cannot be resolved —
+ * reopen itself must still succeed even if we cannot attach context.
+ */
+export function writeReopenReason(
+  basePath: string, milestoneId: string, sliceId: string, taskId: string, reason: string,
+): void {
+  const trimmed = reason.trim();
+  if (!trimmed) return;
+  const path = reopenReasonArtifactPath(basePath, milestoneId, sliceId, taskId);
+  if (!path) {
+    logWarning("tool", `reopen-reason: cannot resolve artifact path for ${milestoneId}/${sliceId}/${taskId}; reopen reason not attached to next dispatch`);
+    return;
+  }
+  const artifact: ReopenReasonArtifact = {
+    version: 1,
+    milestoneId, sliceId, taskId,
+    reason: trimmed,
+    createdAt: new Date().toISOString(),
+  };
+  mkdirSync(join(path, ".."), { recursive: true });
+  atomicWriteSync(path, JSON.stringify(artifact, null, 2));
+}
+
+/**
+ * If a reopen reason is pending for this task, claim it (one-shot: the artifact
+ * is deleted on read) and return the markdown block to prepend to the executor's
+ * prompt. Returns null when nothing is pending or the artifact is malformed.
+ */
+export function claimReopenReasonForInjection(
+  basePath: string, milestoneId: string, sliceId: string, taskId: string,
+): { injectionBlock: string } | null {
+  const path = reopenReasonArtifactPath(basePath, milestoneId, sliceId, taskId);
+  if (!path || !existsSync(path)) return null;
+  let art: ReopenReasonArtifact | null = null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<ReopenReasonArtifact>;
+    if (parsed && parsed.version === 1 && typeof parsed.reason === "string" && parsed.reason.trim()) {
+      art = parsed as ReopenReasonArtifact;
+    }
+  } catch {
+    art = null;
+  }
+  // Claim (delete) regardless of validity so a malformed artifact doesn't
+  // wedge every future dispatch of this task.
+  try { unlinkSync(path); } catch { /* already gone */ }
+  if (!art) return null;
+  return { injectionBlock: formatReopenReasonBlock(art) };
+}
+
+function formatReopenReasonBlock(art: ReopenReasonArtifact): string {
+  return [
+    `## Reopened — Reason (from ${art.taskId})`,
+    "",
+    "This task was previously marked complete but a downstream gate (e.g. complete-slice's full-suite run) reopened it. The verify command in your task plan passed in isolation — it did **not** catch the regression below. Do **not** call `gsd_task_complete` until you have reproduced and fixed exactly what this diagnosis describes, then re-run the specific failing command it names (not just the original scoped verify).",
+    "",
+    "**Diagnosis / fix instructions from the gate:**",
+    "",
+    art.reason.trim(),
+  ].join("\n");
+}

package/src/resources/extensions/gsd/rule-registry.ts

@@ -22,8 +22,9 @@ import type {
 } from "./types.js";
 import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { parseUnitId } from "./unit-id.js";
+import { resolveMilestonePath } from "./paths.js";
 import { queryJournal, type JournalEntry } from "./journal.js";
 import { readUnitRuntimeRecord, type UnitRuntimePhase } from "./unit-runtime.js";
 import { extractFrontmatterVerdict } from "./verdict-parser.js";
@@ -32,13 +33,45 @@ import { extractFrontmatterVerdict } from "./verdict-parser.js";
 
 export function resolveHookArtifactPath(basePath: string, unitId: string, artifactName: string): string {
   const { milestone, slice, task } = parseUnitId(unitId);
-  if (task !== undefined && slice !== undefined) {
-    return join(basePath, ".gsd", "milestones", milestone, "slices", slice, "tasks", `${task}-${artifactName}`);
+
+  // Prefer the active phase directory (flat-phase layout: .gsd/phases/<NN>-.../).
+  // Configured gate artifacts are canonical phase-level files (e.g.
+  // BROWSER-RUNTIME-EVIDENCE.md), so resolve the exact declared name first,
+  // then a task-prefixed variant for retry sentinels / rework briefs.
+  const candidates: string[] = [];
+  const phaseDir = resolveMilestonePath(basePath, milestone);
+  const isFlatPhaseDir = phaseDir !== null
+    && !(dirname(phaseDir).endsWith("/milestones") || dirname(phaseDir).endsWith("\\milestones"));
+  if (isFlatPhaseDir) {
+    candidates.push(join(phaseDir, artifactName));
+    if (task !== undefined) {
+      candidates.push(join(phaseDir, `${task}-${artifactName}`));
+    }
   }
-  if (slice !== undefined) {
-    return join(basePath, ".gsd", "milestones", milestone, "slices", slice, artifactName);
+
+  // Legacy nested layout fallbacks (.gsd/milestones/<M>/slices/<S>/tasks/...).
+  const legacyBase = join(basePath, ".gsd", "milestones", milestone);
+  let legacyDefault: string;
+  if (task !== undefined && slice !== undefined) {
+    legacyDefault = join(legacyBase, "slices", slice, "tasks", `${task}-${artifactName}`);
+    candidates.push(legacyDefault);
+    candidates.push(join(legacyBase, "slices", slice, "tasks", artifactName));
+    candidates.push(join(legacyBase, "slices", slice, artifactName));
+  } else if (slice !== undefined) {
+    legacyDefault = join(legacyBase, "slices", slice, artifactName);
+    candidates.push(legacyDefault);
+  } else {
+    legacyDefault = join(legacyBase, artifactName);
   }
-  return join(basePath, ".gsd", "milestones", milestone, artifactName);
+  candidates.push(join(legacyBase, artifactName));
+
+  const existing = candidates.find((candidate) => existsSync(candidate));
+  if (existing) return existing;
+
+  // Nothing on disk yet: prefer the active phase path when the phase dir is
+  // known, otherwise fall back to the legacy default (preserves pre-flat-phase
+  // behavior for missing-artifact diagnostics).
+  return isFlatPhaseDir ? join(phaseDir!, artifactName) : legacyDefault;
 }
 
 // ─── Dispatch Rule Conversion ──────────────────────────────────────────────
@@ -126,6 +159,13 @@ export class RuleRegistry {
     forceRun?: boolean;
   }> = [];
   cycleCounts: Map<string, number> = new Map();
+  /**
+   * Cycle keys that have already been granted a one-shot re-dispatch after a
+   * lost/interrupted dispatch (hook charged a cycle but never produced its own
+   * unit-end). Bounds the dispatch-cycle refund to exactly one per gate so a
+   * hook that repeatedly fails to complete cannot loop forever.
+   */
+  redispatchedGateKeys: Set<string> = new Set();
   retryPending: boolean = false;
   retryTrigger: { unitType: string; unitId: string; retryArtifact?: string } | null = null;
   hookFailure: HookFailureState | null = null;
@@ -364,6 +404,14 @@ export class RuleRegistry {
       pendingRetry: false,
     };
 
+    return this._buildHookDispatch(config, triggerUnitId);
+  }
+
+  /** Construct the sidecar dispatch for a hook without mutating registry state. */
+  private _buildHookDispatch(
+    config: PostUnitHookConfig,
+    triggerUnitId: string,
+  ): HookDispatchResult {
     const { milestone: mid, slice: sid, task: tid } = parseUnitId(triggerUnitId);
     let prompt = config.prompt
       .replace(/\{milestoneId\}/g, mid ?? "")
@@ -375,12 +423,29 @@ export class RuleRegistry {
     return {
       hookName: config.name,
       prompt,
-      model: config.model,
+      // Model selection (including fallbacks[]) is handled by
+      // resolveModelWithFallbacksForUnit for the `hook/<name>` unit type (#1229).
       unitType: `hook/${config.name}`,
       unitId: triggerUnitId,
     };
   }
 
+  /**
+   * Reconstruct the in-flight hook's dispatch from the restored `activeHook`
+   * state, without mutating the registry. Used to reconcile a persisted
+   * `activeHook` whose session-local dispatch was lost across a pause/resume
+   * or crash-recovery, so the hook actually runs instead of being charged
+   * against the next unrelated unit's close-out (#1246).
+   */
+  getPendingHookDispatch(basePath: string): HookDispatchResult | null {
+    if (!this.activeHook) return null;
+    const config = resolvePostUnitHooks(basePath).find(
+      h => h.name === this.activeHook!.hookName,
+    );
+    if (!config) return null;
+    return this._buildHookDispatch(config, this.activeHook.triggerUnitId);
+  }
+
   private _assessHookCompletion(
     basePath: string,
     hook: HookExecutionState,
@@ -503,6 +568,30 @@ export class RuleRegistry {
     observedCleanExecution: boolean,
   ): HookDispatchResult | null {
     if (!observedCleanExecution) {
+      // The hook was charged a cycle at dispatch but never produced its own
+      // unit-end — its dispatch was lost/interrupted (pause/resume, crash
+      // recovery). Refund that dispatch-consumed cycle exactly once so the gate
+      // is re-dispatched at least once instead of hard-blocking on a hook that
+      // never actually ran.
+      //
+      // This refund is intentionally UNCONDITIONAL on the first lost dispatch —
+      // it must NOT be gated on `currentCycle >= max_cycles`. A lost dispatch is
+      // a non-run: charging its cycle at dispatch time must not consume the
+      // hook's real-run budget. Gating the refund on "budget already exhausted"
+      // lets a lost dispatch below max_cycles silently eat a genuine cycle, so
+      // the hook gets one fewer real run than configured — reintroducing #1244
+      // for max_cycles >= 2 (see the "does not steal a real-run cycle" test).
+      // The redispatchedGateKeys flag bounds this to a single refund per gate,
+      // so repeated lost dispatches still terminate (total dispatches never
+      // exceed max_cycles + 1) and a hook that keeps failing blocks normally.
+      const cycleKey = hookCycleKey(config, hook);
+      if (!this.redispatchedGateKeys.has(cycleKey)) {
+        this.redispatchedGateKeys.add(cycleKey);
+        const currentCycle = this.cycleCounts.get(cycleKey);
+        if (typeof currentCycle === "number" && currentCycle > 0) {
+          this.cycleCounts.set(cycleKey, currentCycle - 1);
+        }
+      }
       return this._rerunGateOrBlock(config, hook, basePath, {
         reason: `hook/${config.name} did not complete cleanly before the trigger unit resumed`,
       });
@@ -839,6 +928,7 @@ export class RuleRegistry {
     this.activeHook = null;
     this.hookQueue = [];
     this.cycleCounts.clear();
+    this.redispatchedGateKeys.clear();
     this.retryPending = false;
     this.retryTrigger = null;
     this.hookFailure = null;
@@ -855,6 +945,7 @@ export class RuleRegistry {
   persistState(basePath: string): void {
     const state: PersistedHookState = {
       cycleCounts: Object.fromEntries(this.cycleCounts),
+      redispatchedGateKeys: Array.from(this.redispatchedGateKeys),
       activeHook: this.activeHook ? { ...this.activeHook } : null,
       hookQueue: this.hookQueue.map(entry => ({
         hookName: entry.config.name,
@@ -888,6 +979,14 @@ export class RuleRegistry {
           }
         }
       }
+      this.redispatchedGateKeys.clear();
+      if (Array.isArray(state.redispatchedGateKeys)) {
+        for (const key of state.redispatchedGateKeys) {
+          if (typeof key === "string") {
+            this.redispatchedGateKeys.add(key);
+          }
+        }
+      }
       this.activeHook = state.activeHook && typeof state.activeHook === "object"
         ? { ...state.activeHook }
         : null;
@@ -918,7 +1017,7 @@ export class RuleRegistry {
       if (existsSync(filePath)) {
         writeFileSync(
           filePath,
-          JSON.stringify({ cycleCounts: {}, activeHook: null, hookQueue: [], savedAt: new Date().toISOString() }, null, 2),
+          JSON.stringify({ cycleCounts: {}, redispatchedGateKeys: [], activeHook: null, hookQueue: [], savedAt: new Date().toISOString() }, null, 2),
           "utf-8",
         );
       }
@@ -1014,7 +1113,10 @@ export class RuleRegistry {
     return {
       hookName: hook.name,
       prompt,
-      model: hook.model,
+      // Model selection (including fallbacks[]) is resolved by dispatchHookUnit
+      // via resolveModelWithFallbacksForUnit for the `hook/<name>` unit type,
+      // matching the auto-mode path. Emitting the primary-only model here would
+      // discard the configured fallback chain (#1229).
       unitType: `hook/${hook.name}`,
       unitId,
     };

package/src/resources/extensions/gsd/session-status-io.ts

@@ -48,6 +48,11 @@ const PARALLEL_DIR = "parallel";
 const STATUS_SUFFIX = ".status.json";
 const SIGNAL_SUFFIX = ".signal.json";
 const DEFAULT_STALE_TIMEOUT_MS = 30_000;
+// How long a paused worker waits for the coordinator to lift the pause before
+// it degrades to in-process serialization (#1273). Kept below the stale
+// timeout so the wait never races the coordinator's liveness detection.
+const DEFAULT_RESUME_WAIT_MS = 10_000;
+const DEFAULT_RESUME_POLL_MS = 250;
 
 function isSessionStatus(data: unknown): data is SessionStatus {
   return data !== null && typeof data === "object" && "milestoneId" in data && "pid" in data;
@@ -143,6 +148,35 @@ export function consumeSignal(basePath: string, milestoneId: string): SignalMess
   return msg;
 }
 
+/**
+ * Wait for a coordinator to lift a `pause` on a worker by sending `resume`
+ * (or `stop`). Polls the signal file until one of those arrives or the timeout
+ * elapses. Intervening `pause`/`rebase` signals are consumed and ignored so a
+ * repeated pause doesn't reset the wait.
+ *
+ * A worker's `pause` is only ever lifted by the interactive/dashboard resumer;
+ * unattended `gsd headless auto` owns no resumer, so callers use the `"timeout"`
+ * result to degrade to in-process serialization instead of stranding the worker
+ * at a terminal pause it cannot resume (#1273).
+ */
+export async function awaitWorkerResume(
+  basePath: string,
+  milestoneId: string,
+  opts: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<"resume" | "stop" | "timeout"> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_RESUME_WAIT_MS;
+  const pollMs = opts.pollMs ?? DEFAULT_RESUME_POLL_MS;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const msg = consumeSignal(basePath, milestoneId);
+    if (msg?.signal === "resume") return "resume";
+    if (msg?.signal === "stop") return "stop";
+    if (Date.now() >= deadline) return "timeout";
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
 // ─── Stale Detection ───────────────────────────────────────────────────────
 
 /** Check whether a session is stale (PID dead or heartbeat timed out). */

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

@@ -9,8 +9,8 @@
  */
 
 import { existsSync, readdirSync, readFileSync, type Dirent } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { getSkillDirectories } from "@gsd/pi-coding-agent";
 import { gsdHome } from "./gsd-home.js";
 import { getInstalledSkills, normalizeSkillName } from "./skills.js";
 
@@ -20,28 +20,47 @@ export interface DiscoveredSkill {
   location: string;
 }
 
-/** Snapshot of normalized skill names at auto-mode start */
-let baselineSkills: Set<string> | null = null;
+/**
+ * Snapshot state. `searchDirs` is captured at snapshot time so every detection
+ * pass during the session scans the same project + user dirs (the bug fix:
+ * previously only user dirs were scanned, so skills installed into the project
+ * mid-session were silently missed).
+ */
+interface SkillSnapshotState {
+  baselineNames: Set<string>;
+  searchDirs: string[];
+}
+
+let snapshot: SkillSnapshotState | null = null;
 
 /**
  * Snapshot the current installed skill catalog. Call at auto-mode start.
+ * `cwd` is the project base path; skills dropped into `<cwd>/.agents/skills/`,
+ * `<cwd>/.claude/skills/`, or `<cwd>/.gsd/skills/` mid-session are detected.
  */
-export function snapshotSkills(): void {
-  baselineSkills = snapshotCurrentSkillNames();
+export function snapshotSkills(options?: { cwd?: string }): void {
+  const searchDirs = getSkillDirectories({
+    cwd: options?.cwd ?? process.cwd(),
+    gsdHome: gsdHome(),
+  }).map((entry) => entry.path);
+  snapshot = {
+    baselineNames: snapshotCurrentSkillNames(searchDirs),
+    searchDirs,
+  };
 }
 
 /**
  * Clear the snapshot. Call when auto-mode stops.
  */
 export function clearSkillSnapshot(): void {
-  baselineSkills = null;
+  snapshot = null;
 }
 
 /**
  * Check if a snapshot is active (auto-mode is running with discovery).
  */
 export function hasSkillSnapshot(): boolean {
-  return baselineSkills !== null;
+  return snapshot !== null;
 }
 
 /**
@@ -49,12 +68,12 @@ export function hasSkillSnapshot(): boolean {
  * Returns skill metadata for any new skills found in the loader catalog or on disk.
  */
 export function detectNewSkills(): DiscoveredSkill[] {
-  if (!baselineSkills) return [];
+  if (!snapshot) return [];
 
   const newSkills: DiscoveredSkill[] = [];
-  for (const skill of getCurrentSkillsForDiscovery()) {
+  for (const skill of getCurrentSkillsForDiscovery(snapshot.searchDirs)) {
     const normalized = normalizeSkillName(skill.name);
-    if (baselineSkills.has(normalized)) continue;
+    if (snapshot.baselineNames.has(normalized)) continue;
     newSkills.push(skill);
   }
 
@@ -84,7 +103,13 @@ export async function refreshCatalogForNewSkills(options?: {
     }
   }
 
-  snapshotSkills();
+  // Re-snapshot, preserving the search dirs captured at auto-mode start.
+  if (snapshot) {
+    snapshot = {
+      baselineNames: snapshotCurrentSkillNames(),
+      searchDirs: snapshot.searchDirs,
+    };
+  }
   const names = newSkills.map((skill) => skill.name).join(", ");
   options?.notify?.(`GSD: loaded new skills: ${names}`, "info");
   return newSkills;
@@ -132,19 +157,18 @@ function escapeXml(value: string): string {
   });
 }
 
-function skillSearchDirs(): string[] {
-  return [
-    join(gsdHome(), "agent", "skills"),
-    join(homedir(), ".agents", "skills"),
-    join(homedir(), ".claude", "skills"),
-  ];
+function snapshotCurrentSkillNames(searchDirsOverride?: string[]): Set<string> {
+  // Uses explicit dirs, the snapshot's search dirs when active, or user-only dirs
+  // (no project context) when called before a snapshot is taken.
+  const searchDirs = searchDirsOverride ?? snapshot?.searchDirs ?? defaultSearchDirs();
+  return new Set(getCurrentSkillsForDiscovery(searchDirs).map(skill => normalizeSkillName(skill.name)));
 }
 
-function snapshotCurrentSkillNames(): Set<string> {
-  return new Set(getCurrentSkillsForDiscovery().map(skill => normalizeSkillName(skill.name)));
+function defaultSearchDirs(): string[] {
+  return getSkillDirectories({ cwd: process.cwd(), gsdHome: gsdHome() }).map((entry) => entry.path);
 }
 
-function getCurrentSkillsForDiscovery(): DiscoveredSkill[] {
+function getCurrentSkillsForDiscovery(searchDirs: string[]): DiscoveredSkill[] {
   const skills = new Map<string, DiscoveredSkill>();
   for (const skill of getInstalledSkills()) {
     const normalized = normalizeSkillName(skill.name);
@@ -155,7 +179,7 @@ function getCurrentSkillsForDiscovery(): DiscoveredSkill[] {
     });
   }
 
-  for (const skill of getDiskSkills()) {
+  for (const skill of getDiskSkills(searchDirs)) {
     const normalized = normalizeSkillName(skill.name);
     if (!skills.has(normalized)) skills.set(normalized, skill);
   }
@@ -163,9 +187,9 @@ function getCurrentSkillsForDiscovery(): DiscoveredSkill[] {
   return [...skills.values()];
 }
 
-function getDiskSkills(): DiscoveredSkill[] {
+function getDiskSkills(searchDirs: string[]): DiscoveredSkill[] {
   const skills = new Map<string, DiscoveredSkill>();
-  for (const dir of skillSearchDirs()) {
+  for (const dir of searchDirs) {
     if (!existsSync(dir)) continue;
     let entries: Dirent[];
     try {

package/src/resources/extensions/gsd/slice-parallel-orchestrator.ts

@@ -30,7 +30,9 @@ import { isAbsolute, join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath, removeWorktree } from "./worktree-manager.js";
-import { autoWorktreeBranch, runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
+import { autoWorktreeBranch } from "./auto-worktree-branch-lifecycle.js";
+import { syncGsdStateToWorktreeByScope } from "./auto-worktree-sync.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 import {
   writeSessionStatus,