gsd-pi 2.28.0-dev.e19bf89 → 2.29.0-dev.23d50d0

package/src/resources/extensions/gsd/prompts/workflow-start.md

@@ -0,0 +1,28 @@
+# Workflow Template: {{templateName}}
+
+You are executing a **{{templateName}}** workflow (template: `{{templateId}}`).
+
+## Context
+
+- **Description:** {{description}}
+- **Issue reference:** {{issueRef}}
+- **Date:** {{date}}
+- **Branch:** {{branch}}
+- **Artifact directory:** {{artifactDir}}
+- **Phases:** {{phases}}
+- **Complexity:** {{complexity}}
+
+## Workflow Definition
+
+Follow the workflow defined below. Execute each phase in order, completing one before moving to the next. At each phase gate, confirm with the user before proceeding.
+
+{{workflowContent}}
+
+## Execution Rules
+
+1. **Follow the phases in order.** Do not skip phases unless the workflow explicitly allows it.
+2. **Artifact discipline.** If an artifact directory is specified, write all planning/summary documents there.
+3. **Atomic commits.** Commit working code after each meaningful change. Use conventional commit format: `<type>(<scope>): <description>`.
+4. **Verify before shipping.** Run the project's test suite and build before marking the workflow complete.
+5. **Gate between phases.** After each phase, summarize what was done and ask the user to confirm before moving to the next phase.
+6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

package/src/resources/extensions/gsd/queue-order.ts

@@ -9,10 +9,10 @@
  * survives branch switches and is shared across sessions.
  */
 
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { milestoneIdSort } from "./milestone-ids.js";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -45,6 +45,12 @@ function queueOrderPath(basePath: string): string {
   return join(gsdRoot(basePath), "QUEUE-ORDER.json");
 }
 
+// ─── Type Guards ─────────────────────────────────────────────────────────────
+
+function isQueueOrderFile(data: unknown): data is QueueOrderFile {
+  return data !== null && typeof data === "object" && "order" in data! && Array.isArray((data as QueueOrderFile).order);
+}
+
 // ─── Read / Write ────────────────────────────────────────────────────────────
 
 /**
@@ -52,15 +58,8 @@ function queueOrderPath(basePath: string): string {
  * the file is corrupt/unreadable.
  */
 export function loadQueueOrder(basePath: string): string[] | null {
-  const p = queueOrderPath(basePath);
-  if (!existsSync(p)) return null;
-  try {
-    const data: QueueOrderFile = JSON.parse(readFileSync(p, "utf-8"));
-    if (!Array.isArray(data.order)) return null;
-    return data.order;
-  } catch {
-    return null;
-  }
+  const data = loadJsonFileOrNull(queueOrderPath(basePath), isQueueOrderFile);
+  return data?.order ?? null;
 }
 
 /**
@@ -71,7 +70,7 @@ export function saveQueueOrder(basePath: string, order: string[]): void {
     order,
     updatedAt: new Date().toISOString(),
   };
-  writeFileSync(queueOrderPath(basePath), JSON.stringify(data, null, 2) + "\n", "utf-8");
+  saveJsonFile(queueOrderPath(basePath), data);
 }
 
 // ─── Sorting ─────────────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/routing-history.ts

@@ -2,10 +2,10 @@
 // Tracks success/failure per tier per unit-type pattern to improve
 // classification accuracy over time.
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import type { ComplexityTier } from "./types.js";
+import { loadJsonFile, saveJsonFile } from "./json-persistence.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -267,24 +267,20 @@ function historyPath(base: string): string {
   return join(gsdRoot(base), HISTORY_FILE);
 }
 
+function isRoutingHistoryData(data: unknown): data is RoutingHistoryData {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as RoutingHistoryData).version === 1 &&
+    typeof (data as RoutingHistoryData).patterns === "object" &&
+    (data as RoutingHistoryData).patterns !== null
+  );
+}
+
 function loadHistory(base: string): RoutingHistoryData {
-  try {
-    const raw = readFileSync(historyPath(base), "utf-8");
-    const parsed = JSON.parse(raw);
-    if (parsed.version === 1 && parsed.patterns) {
-      return parsed as RoutingHistoryData;
-    }
-  } catch {
-    // File doesn't exist or is corrupt — start fresh
-  }
-  return createEmptyHistory();
+  return loadJsonFile(historyPath(base), isRoutingHistoryData, createEmptyHistory);
 }
 
 function saveHistory(base: string, data: RoutingHistoryData): void {
-  try {
-    mkdirSync(gsdRoot(base), { recursive: true });
-    writeFileSync(historyPath(base), JSON.stringify(data, null, 2) + "\n", "utf-8");
-  } catch {
-    // Non-fatal — don't let history failures break auto-mode
-  }
+  saveJsonFile(historyPath(base), data);
 }

package/src/resources/extensions/gsd/session-lock.ts

@@ -0,0 +1,284 @@
+/**
+ * GSD Session Lock — OS-level exclusive locking for auto-mode sessions.
+ *
+ * Prevents multiple GSD processes from running auto-mode concurrently on
+ * the same project. Uses proper-lockfile for OS-level file locking (flock/
+ * lockfile) which eliminates the TOCTOU race condition that existed with
+ * the old advisory JSON lock approach.
+ *
+ * The lock file (.gsd/auto.lock) contains JSON metadata (PID, start time,
+ * unit info) for diagnostics, but the actual exclusion is enforced by the
+ * OS-level lock held via proper-lockfile.
+ *
+ * Lifecycle:
+ *   acquireSessionLock()  — called at the START of bootstrapAutoSession
+ *   validateSessionLock() — called periodically during dispatch to detect takeover
+ *   releaseSessionLock()  — called on clean stop/pause
+ */
+
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { atomicWriteSync } from "./atomic-write.js";
+
+const _require = createRequire(import.meta.url);
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface SessionLockData {
+  pid: number;
+  startedAt: string;
+  unitType: string;
+  unitId: string;
+  unitStartedAt: string;
+  completedUnits: number;
+  sessionFile?: string;
+}
+
+export type SessionLockResult =
+  | { acquired: true }
+  | { acquired: false; reason: string; existingPid?: number };
+
+// ─── Module State ───────────────────────────────────────────────────────────
+
+/** Release function from proper-lockfile — calling it releases the OS lock. */
+let _releaseFunction: (() => void) | null = null;
+
+/** The path we currently hold a lock on. */
+let _lockedPath: string | null = null;
+
+/** Our PID at lock acquisition time. */
+let _lockPid: number = 0;
+
+const LOCK_FILE = "auto.lock";
+
+function lockPath(basePath: string): string {
+  return join(gsdRoot(basePath), LOCK_FILE);
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Attempt to acquire an exclusive session lock for the given project.
+ *
+ * This uses proper-lockfile for OS-level file locking. If another process
+ * already holds the lock, this returns { acquired: false } with details.
+ *
+ * The lock file also contains JSON metadata about the session for
+ * diagnostic purposes (PID, unit info, etc.).
+ */
+export function acquireSessionLock(basePath: string): SessionLockResult {
+  const lp = lockPath(basePath);
+
+  // Ensure the directory exists
+  mkdirSync(dirname(lp), { recursive: true });
+
+  // Write our lock data first (the content is informational; the OS lock is the real guard)
+  const lockData: SessionLockData = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    unitType: "starting",
+    unitId: "bootstrap",
+    unitStartedAt: new Date().toISOString(),
+    completedUnits: 0,
+  };
+
+  let lockfile: typeof import("proper-lockfile");
+  try {
+    lockfile = _require("proper-lockfile") as typeof import("proper-lockfile");
+  } catch {
+    // proper-lockfile not available — fall back to PID-based check
+    return acquireFallbackLock(basePath, lp, lockData);
+  }
+
+  try {
+    // Try to acquire an exclusive OS-level lock on the lock file.
+    // We lock the directory (gsdRoot) since proper-lockfile works best
+    // on directories, and the lock file itself may not exist yet.
+    const gsdDir = gsdRoot(basePath);
+    mkdirSync(gsdDir, { recursive: true });
+
+    const release = lockfile.lockSync(gsdDir, {
+      realpath: false,
+      stale: 300_000, // 5 minutes — consider lock stale if holder hasn't updated
+      update: 10_000, // Update lock mtime every 10s to prove liveness
+    });
+
+    _releaseFunction = release;
+    _lockedPath = basePath;
+    _lockPid = process.pid;
+
+    // Write the informational lock data
+    atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
+
+    return { acquired: true };
+  } catch (err) {
+    // Lock is held by another process
+    const existingData = readExistingLockData(lp);
+    const existingPid = existingData?.pid;
+    const reason = existingPid
+      ? `Another auto-mode session (PID ${existingPid}) is already running on this project.`
+      : `Another auto-mode session is already running on this project.`;
+
+    return { acquired: false, reason, existingPid };
+  }
+}
+
+/**
+ * Fallback lock acquisition when proper-lockfile is not available.
+ * Uses PID-based liveness checking (the old approach, but with the lock
+ * written BEFORE initialization rather than after).
+ */
+function acquireFallbackLock(
+  basePath: string,
+  lp: string,
+  lockData: SessionLockData,
+): SessionLockResult {
+  // Check if an existing lock is held by a live process
+  const existing = readExistingLockData(lp);
+  if (existing && existing.pid !== process.pid) {
+    if (isPidAlive(existing.pid)) {
+      return {
+        acquired: false,
+        reason: `Another auto-mode session (PID ${existing.pid}) is already running on this project.`,
+        existingPid: existing.pid,
+      };
+    }
+    // Stale lock from dead process — we can take over
+  }
+
+  // Write our lock data
+  atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
+  _lockedPath = basePath;
+  _lockPid = process.pid;
+
+  return { acquired: true };
+}
+
+/**
+ * Update the lock file metadata (called on each unit dispatch).
+ * Does NOT re-acquire the OS lock — just updates the JSON content.
+ */
+export function updateSessionLock(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  completedUnits: number,
+  sessionFile?: string,
+): void {
+  if (_lockedPath !== basePath && _lockedPath !== null) return;
+
+  const lp = lockPath(basePath);
+  try {
+    const data: SessionLockData = {
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+      unitType,
+      unitId,
+      unitStartedAt: new Date().toISOString(),
+      completedUnits,
+      sessionFile,
+    };
+    atomicWriteSync(lp, JSON.stringify(data, null, 2));
+  } catch {
+    // Non-fatal: lock update failure
+  }
+}
+
+/**
+ * Validate that we still own the session lock.
+ *
+ * Returns true if we still hold the lock, false if another process
+ * has taken over (indicating we should gracefully stop).
+ *
+ * This is called periodically during the dispatch loop.
+ */
+export function validateSessionLock(basePath: string): boolean {
+  // If we have an OS-level lock, we're still the owner
+  if (_releaseFunction && _lockedPath === basePath) {
+    return true;
+  }
+
+  // Fallback: check the lock file PID
+  const lp = lockPath(basePath);
+  const existing = readExistingLockData(lp);
+  if (!existing) {
+    // Lock file was deleted — we lost ownership
+    return false;
+  }
+
+  return existing.pid === process.pid;
+}
+
+/**
+ * Release the session lock. Called on clean stop/pause.
+ */
+export function releaseSessionLock(basePath: string): void {
+  // Release the OS-level lock
+  if (_releaseFunction) {
+    try {
+      _releaseFunction();
+    } catch {
+      // Lock may already be released
+    }
+    _releaseFunction = null;
+  }
+
+  // Remove the lock file
+  const lp = lockPath(basePath);
+  try {
+    if (existsSync(lp)) unlinkSync(lp);
+  } catch {
+    // Non-fatal
+  }
+
+  _lockedPath = null;
+  _lockPid = 0;
+}
+
+/**
+ * Check if a session lock exists and return its data (for crash recovery).
+ * Does NOT acquire the lock.
+ */
+export function readSessionLockData(basePath: string): SessionLockData | null {
+  return readExistingLockData(lockPath(basePath));
+}
+
+/**
+ * Check if the process that wrote the lock is still alive.
+ */
+export function isSessionLockProcessAlive(data: SessionLockData): boolean {
+  return isPidAlive(data.pid);
+}
+
+/**
+ * Returns true if we currently hold a session lock for the given path.
+ */
+export function isSessionLockHeld(basePath: string): boolean {
+  return _lockedPath === basePath && _lockPid === process.pid;
+}
+
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+
+function readExistingLockData(lp: string): SessionLockData | null {
+  try {
+    if (!existsSync(lp)) return null;
+    const raw = readFileSync(lp, "utf-8");
+    return JSON.parse(raw) as SessionLockData;
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (pid === process.pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EPERM") return true;
+    return false;
+  }
+}

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

@@ -11,9 +11,6 @@
  */
 
 import {
-  writeFileSync,
-  readFileSync,
-  renameSync,
   unlinkSync,
   readdirSync,
   mkdirSync,
@@ -21,6 +18,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+import { loadJsonFileOrNull, writeJsonFileAtomic } from "./json-persistence.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -49,9 +47,16 @@ export interface SignalMessage {
 const PARALLEL_DIR = "parallel";
 const STATUS_SUFFIX = ".status.json";
 const SIGNAL_SUFFIX = ".signal.json";
-const TMP_SUFFIX = ".tmp";
 const DEFAULT_STALE_TIMEOUT_MS = 30_000;
 
+function isSessionStatus(data: unknown): data is SessionStatus {
+  return data !== null && typeof data === "object" && "milestoneId" in data && "pid" in data;
+}
+
+function isSignalMessage(data: unknown): data is SignalMessage {
+  return data !== null && typeof data === "object" && "signal" in data && "sentAt" in data;
+}
+
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
 function parallelDir(basePath: string): string {
@@ -86,25 +91,13 @@ function isPidAlive(pid: number): boolean {
 
 /** Write session status atomically (write to .tmp, then rename). */
 export function writeSessionStatus(basePath: string, status: SessionStatus): void {
-  try {
-    ensureParallelDir(basePath);
-    const dest = statusPath(basePath, status.milestoneId);
-    const tmp = dest + TMP_SUFFIX;
-    writeFileSync(tmp, JSON.stringify(status, null, 2), "utf-8");
-    renameSync(tmp, dest);
-  } catch { /* non-fatal */ }
+  ensureParallelDir(basePath);
+  writeJsonFileAtomic(statusPath(basePath, status.milestoneId), status);
 }
 
 /** Read a specific milestone's session status. */
 export function readSessionStatus(basePath: string, milestoneId: string): SessionStatus | null {
-  try {
-    const p = statusPath(basePath, milestoneId);
-    if (!existsSync(p)) return null;
-    const raw = readFileSync(p, "utf-8");
-    return JSON.parse(raw) as SessionStatus;
-  } catch {
-    return null;
-  }
+  return loadJsonFileOrNull(statusPath(basePath, milestoneId), isSessionStatus);
 }
 
 /** Read all session status files from .gsd/parallel/. */
@@ -114,13 +107,10 @@ export function readAllSessionStatuses(basePath: string): SessionStatus[] {
 
   const results: SessionStatus[] = [];
   try {
-    const entries = readdirSync(dir);
-    for (const entry of entries) {
+    for (const entry of readdirSync(dir)) {
       if (!entry.endsWith(STATUS_SUFFIX)) continue;
-      try {
-        const raw = readFileSync(join(dir, entry), "utf-8");
-        results.push(JSON.parse(raw) as SessionStatus);
-      } catch { /* skip corrupt files */ }
+      const status = loadJsonFileOrNull(join(dir, entry), isSessionStatus);
+      if (status) results.push(status);
     }
   } catch { /* non-fatal */ }
   return results;
@@ -138,27 +128,19 @@ export function removeSessionStatus(basePath: string, milestoneId: string): void
 
 /** Write a signal file for a worker to consume. */
 export function sendSignal(basePath: string, milestoneId: string, signal: SessionSignal): void {
-  try {
-    ensureParallelDir(basePath);
-    const dest = signalPath(basePath, milestoneId);
-    const tmp = dest + TMP_SUFFIX;
-    const msg: SignalMessage = { signal, sentAt: Date.now(), from: "coordinator" };
-    writeFileSync(tmp, JSON.stringify(msg, null, 2), "utf-8");
-    renameSync(tmp, dest);
-  } catch { /* non-fatal */ }
+  ensureParallelDir(basePath);
+  const msg: SignalMessage = { signal, sentAt: Date.now(), from: "coordinator" };
+  writeJsonFileAtomic(signalPath(basePath, milestoneId), msg);
 }
 
 /** Read and delete a signal file (atomic consume). Returns null if no signal pending. */
 export function consumeSignal(basePath: string, milestoneId: string): SignalMessage | null {
-  try {
-    const p = signalPath(basePath, milestoneId);
-    if (!existsSync(p)) return null;
-    const raw = readFileSync(p, "utf-8");
-    unlinkSync(p);
-    return JSON.parse(raw) as SignalMessage;
-  } catch {
-    return null;
+  const p = signalPath(basePath, milestoneId);
+  const msg = loadJsonFileOrNull(p, isSignalMessage);
+  if (msg) {
+    try { unlinkSync(p); } catch { /* non-fatal */ }
   }
+  return msg;
 }
 
 // ─── Stale Detection ───────────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/auto-budget-alerts.test.ts

@@ -5,7 +5,7 @@ import {
   getBudgetAlertLevel,
   getBudgetEnforcementAction,
   getNewBudgetAlertLevel,
-} from "../auto.js";
+} from "../auto-budget.js";
 
 test("getBudgetAlertLevel returns the expected threshold bucket", () => {
   assert.equal(getBudgetAlertLevel(0.10), 0);

package/src/resources/extensions/gsd/tests/auto-skip-loop.test.ts

@@ -17,8 +17,8 @@ import { tmpdir } from "node:os";
 import {
   _getUnitConsecutiveSkips,
   _resetUnitConsecutiveSkips,
-  MAX_CONSECUTIVE_SKIPS,
 } from "../auto.ts";
+import { MAX_CONSECUTIVE_SKIPS } from "../auto/session.ts";
 import { persistCompletedKey, removePersistedKey, loadPersistedKeys } from "../auto-recovery.ts";
 import { createTestContext } from "./test-helpers.ts";