gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/dist/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/dist/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/dist/resources/extensions/gsd/skills/gsd-headless/SKILL.md

@@ -21,6 +21,8 @@ gsd headless [flags] [command] [args...]
 - `--supervised` — forward interactive UI requests to orchestrator via stdout/stdin
 - `--response-timeout N` — timeout for orchestrator response in supervised mode (default 30000)
 - `--max-restarts N` — auto-restart on crash with backoff (default 3, 0 to disable)
+- `--answers <path>` — pre-supply answers and secrets from JSON file
+- `--events <types>` — filter JSONL output to specific event types (comma-separated, implies `--json`)
 
 **Exit codes:** 0=complete, 1=error/timeout, 2=blocked
 
@@ -164,9 +166,44 @@ done
 
 Event types: `agent_start`, `agent_end`, `tool_execution_start`, `tool_execution_end`, `extension_ui_request`, `message_update`, `error`.
 
+### Filtered Event Stream
+
+Use `--events` to receive only specific event types — reduces noise for orchestrators:
+
+```bash
+# Only phase-relevant events
+gsd headless --events agent_end,extension_ui_request auto 2>/dev/null
+
+# Only tool execution events
+gsd headless --events tool_execution_start,tool_execution_end auto
+```
+
+The filter applies only to stdout output. Internal processing (completion detection, supervised mode, answer injection) is unaffected — all events are still processed internally.
+
+Available event types: `agent_start`, `agent_end`, `tool_execution_start`, `tool_execution_end`, `tool_execution_update`, `extension_ui_request`, `message_start`, `message_end`, `message_update`, `turn_start`, `turn_end`.
+
 ## Answer Injection
 
-Pre-supply answers for non-interactive runs. See [references/answer-injection.md](references/answer-injection.md) for schema and usage.
+Pre-supply answers and secrets for headless runs via `--answers`:
+
+```bash
+gsd headless --answers answers.json auto
+```
+
+Answer file schema:
+```json
+{
+  "questions": { "question_id": "selected_option" },
+  "secrets": { "API_KEY": "sk-..." },
+  "defaults": { "strategy": "first_option" }
+}
+```
+
+- **questions** — question ID → answer (string or string[])
+- **secrets** — env var → value, injected into child process env
+- **defaults.strategy** — `"first_option"` (default) or `"cancel"` for unmatched
+
+See [references/answer-injection.md](references/answer-injection.md) for full details.
 
 ## GSD Project Structure
 

package/dist/resources/extensions/gsd/skills/gsd-headless/references/answer-injection.md

@@ -2,6 +2,15 @@
 
 Pre-supply answers to eliminate interactive prompts during headless execution.
 
+## CLI Usage
+
+```bash
+gsd headless --answers answers.json auto
+gsd headless --answers answers.json new-milestone --context spec.md --auto
+```
+
+The `--answers` flag takes a path to a JSON file containing pre-supplied answers and secrets.
+
 ## Answer File Schema
 
 ```json
@@ -23,18 +32,37 @@ Pre-supply answers to eliminate interactive prompts during headless execution.
 ### Fields
 
 - **questions**: Map question ID → answer. String for single-select, string[] for multi-select.
-- **secrets**: Map env var name → value. Used for `secure_env_collect` tool calls. Values are never logged.
+- **secrets**: Map env var name → value. Injected as environment variables into the RPC child process. The child's `checkExistingEnvKeys()` detects them in `process.env` and marks them as "already set" — no interactive prompt needed.
 - **defaults.strategy**: Fallback for unmatched questions.
-  - `"first_option"` — auto-select first available option
+  - `"first_option"` — auto-select first available option (default)
   - `"cancel"` — cancel the request
 
+## Secrets Mechanism
+
+Secrets are injected via the `RpcClient` `env` option, which merges them into the child process's `process.env`. This means:
+
+1. The headless orchestrator reads the answer file
+2. Secret values are passed as `env` to `RpcClient`
+3. The child process spawns with these env vars set
+4. When `secure_env_collect` runs, `checkExistingEnvKeys()` finds the keys already in `process.env`
+5. The tool skips the interactive prompt and reports the keys as "already configured"
+
+Secrets are never logged or included in event streams.
+
 ## How It Works
 
 Two-phase correlation:
 1. **Observe** `tool_execution_start` events for `ask_user_questions` — extracts question metadata (ID, options, allowMultiple)
 2. **Match** subsequent `extension_ui_request` events to metadata, respond with pre-supplied answer
 
-Handles out-of-order events (extension_ui_request can arrive before tool_execution_start in RPC mode) via deferred processing queue.
+Handles out-of-order events (extension_ui_request can arrive before tool_execution_start in RPC mode) via deferred processing queue with 500ms timeout.
+
+## Coexistence with --supervised
+
+Both `--answers` and `--supervised` can be active simultaneously. Priority order:
+1. Answer injector tries first
+2. If no answer found, supervised mode takes over
+3. If no orchestrator response, auto-responder kicks in after timeout
 
 ## Without Answer Injection
 
@@ -48,7 +76,8 @@ Answer injection overrides these defaults with specific answers when precision m
 
 ## Diagnostics
 
-The injector tracks stats:
+The injector tracks stats printed in the summary:
 - `questionsAnswered` / `questionsDefaulted`
-- `secretsProvided` / `secretsMissing`
-- `fireAndForgetConsumed` / `confirmationsHandled`
+- `secretsProvided`
+
+Unused question IDs and secret keys are warned about at the end.

package/dist/resources/extensions/gsd/state.ts

@@ -103,9 +103,17 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
   // Parallel worker isolation
   const milestoneLock = process.env.GSD_MILESTONE_LOCK;
   if (milestoneLock) {
-    return milestoneIds.includes(milestoneLock) ? milestoneLock : null;
+    if (!milestoneIds.includes(milestoneLock)) return null;
+    // Locked milestone that is parked should not be active
+    const lockedParked = resolveMilestoneFile(basePath, milestoneLock, "PARKED");
+    if (lockedParked) return null;
+    return milestoneLock;
   }
   for (const mid of milestoneIds) {
+    // Skip parked milestones — they are not eligible for active status
+    const parkedFile = resolveMilestoneFile(basePath, mid, "PARKED");
+    if (parkedFile) continue;
+
     const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
     const content = roadmapFile ? await loadFile(roadmapFile) : null;
     if (!content) {
@@ -224,7 +232,22 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
   const roadmapCache = new Map<string, Roadmap>();
   const completeMilestoneIds = new Set<string>();
 
+  // Track parked milestone IDs so Phase 2 can check without re-reading disk
+  const parkedMilestoneIds = new Set<string>();
+
   for (const mid of milestoneIds) {
+    // Skip parked milestones — they do NOT count as complete (don't satisfy depends_on)
+    // But still parse their roadmap for title extraction in Phase 2.
+    const parkedFile = resolveMilestoneFile(basePath, mid, "PARKED");
+    if (parkedFile) {
+      parkedMilestoneIds.add(mid);
+      // Cache roadmap for title extraction (but don't add to completeMilestoneIds)
+      const prf = resolveMilestoneFile(basePath, mid, "ROADMAP");
+      const prc = prf ? await cachedLoadFile(prf) : null;
+      if (prc) roadmapCache.set(mid, parseRoadmap(prc));
+      continue;
+    }
+
     const rf = resolveMilestoneFile(basePath, mid, "ROADMAP");
     const rc = rf ? await cachedLoadFile(rf) : null;
     if (!rc) {
@@ -247,6 +270,16 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
   let activeMilestoneHasDraft = false;
 
   for (const mid of milestoneIds) {
+    // Skip parked milestones — register them as 'parked' and move on
+    if (parkedMilestoneIds.has(mid)) {
+      const roadmap = roadmapCache.get(mid) ?? null;
+      const title = roadmap
+        ? roadmap.title.replace(/^M\d+(?:-[a-z0-9]{6})?[^:]*:\s*/, '')
+        : mid;
+      registry.push({ id: mid, title, status: 'parked' });
+      continue;
+    }
+
     const roadmap = roadmapCache.get(mid) ?? null;
 
     if (!roadmap) {
@@ -352,8 +385,9 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
   };
 
   if (!activeMilestone) {
-    // Check whether any milestones are pending (dep-blocked) vs all complete
+    // Check whether any milestones are pending (dep-blocked) or parked
     const pendingEntries = registry.filter(entry => entry.status === 'pending');
+    const parkedEntries = registry.filter(entry => entry.status === 'parked');
     if (pendingEntries.length > 0) {
       // All incomplete milestones are dep-blocked — no progress possible
       const blockerDetails = pendingEntries
@@ -376,6 +410,24 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
         },
       };
     }
+    if (parkedEntries.length > 0) {
+      // All non-complete milestones are parked — nothing active, but not "all complete"
+      const parkedIds = parkedEntries.map(e => e.id).join(', ');
+      return {
+        activeMilestone: null,
+        activeSlice: null,
+        activeTask: null,
+        phase: 'pre-planning',
+        recentDecisions: [],
+        blockers: [],
+        nextAction: `All remaining milestones are parked (${parkedIds}). Run /gsd unpark <id> or create a new milestone.`,
+        registry,
+        requirements,
+        progress: {
+          milestones: milestoneProgress,
+        },
+      };
+    }
     // All milestones complete
     const lastEntry = registry[registry.length - 1];
     return {