gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/gsd/session-lock.js

@@ -0,0 +1,397 @@
+/**
+ * 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, readdirSync, mkdirSync, unlinkSync, rmSync, statSync } 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);
+// ─── Module State ───────────────────────────────────────────────────────────
+/** Release function from proper-lockfile — calling it releases the OS lock. */
+let _releaseFunction = null;
+/** The path we currently hold a lock on. */
+let _lockedPath = null;
+/** Our PID at lock acquisition time. */
+let _lockPid = 0;
+/** Set to true when proper-lockfile fires onCompromised (mtime drift, sleep, etc.). */
+let _lockCompromised = false;
+/** Whether we've already registered a process.on('exit') handler. */
+let _exitHandlerRegistered = false;
+const LOCK_FILE = "auto.lock";
+function lockPath(basePath) {
+    return join(gsdRoot(basePath), LOCK_FILE);
+}
+// ─── Stray Lock Cleanup ─────────────────────────────────────────────────────
+/**
+ * Remove numbered lock file variants (e.g. "auto 2.lock", "auto 3.lock")
+ * that accumulate from macOS file conflict resolution (iCloud/Dropbox/OneDrive)
+ * or other filesystem-level copy-on-conflict behavior (#1315).
+ *
+ * Also removes stray proper-lockfile directories beyond the canonical `.gsd.lock/`.
+ */
+export function cleanupStrayLockFiles(basePath) {
+    const gsdDir = gsdRoot(basePath);
+    // Clean numbered auto lock files inside .gsd/
+    try {
+        if (existsSync(gsdDir)) {
+            for (const entry of readdirSync(gsdDir)) {
+                // Match "auto <N>.lock" or "auto (<N>).lock" variants but NOT the canonical "auto.lock"
+                if (entry !== LOCK_FILE && /^auto\s.+\.lock$/i.test(entry)) {
+                    try {
+                        unlinkSync(join(gsdDir, entry));
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+        }
+    }
+    catch { /* non-fatal: directory read failure */ }
+    // Clean stray proper-lockfile directories (e.g. ".gsd 2.lock/")
+    // The canonical one is ".gsd.lock/" — anything else is stray.
+    try {
+        const parentDir = dirname(gsdDir);
+        const gsdDirName = gsdDir.split("/").pop() || ".gsd";
+        if (existsSync(parentDir)) {
+            for (const entry of readdirSync(parentDir)) {
+                // Match ".gsd <N>.lock" or ".gsd (<N>).lock" directories but NOT ".gsd.lock"
+                if (entry !== `${gsdDirName}.lock` && entry.startsWith(gsdDirName) && entry.endsWith(".lock")) {
+                    const fullPath = join(parentDir, entry);
+                    try {
+                        const stat = statSync(fullPath);
+                        if (stat.isDirectory()) {
+                            rmSync(fullPath, { recursive: true, force: true });
+                        }
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+}
+/**
+ * Register a single process exit handler that cleans up lock state.
+ * Uses module-level references so it always operates on current state.
+ * Only registers once — subsequent calls are no-ops.
+ */
+function ensureExitHandler(gsdDir) {
+    if (_exitHandlerRegistered)
+        return;
+    _exitHandlerRegistered = true;
+    process.once("exit", () => {
+        try {
+            if (_releaseFunction) {
+                _releaseFunction();
+                _releaseFunction = null;
+            }
+        }
+        catch { /* best-effort */ }
+        // Remove the auto.lock metadata file so crash-recovery doesn't
+        // falsely detect an interrupted session on the next startup.
+        try {
+            const lockFile = join(gsdDir, LOCK_FILE);
+            if (existsSync(lockFile))
+                unlinkSync(lockFile);
+        }
+        catch { /* best-effort */ }
+        try {
+            const lockDir = join(gsdDir + ".lock");
+            if (existsSync(lockDir))
+                rmSync(lockDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    });
+}
+// ─── 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) {
+    const lp = lockPath(basePath);
+    // Re-entrant acquire on the same path: release our current OS lock first so
+    // proper-lockfile clears its update timer before we acquire a fresh lock.
+    if (_releaseFunction && _lockedPath === basePath) {
+        try {
+            _releaseFunction();
+        }
+        catch { /* may already be released */ }
+        _releaseFunction = null;
+        _lockedPath = null;
+        _lockPid = 0;
+        _lockCompromised = false;
+    }
+    // Ensure the directory exists
+    mkdirSync(dirname(lp), { recursive: true });
+    // Clean up numbered lock file variants from cloud sync conflicts (#1315)
+    cleanupStrayLockFiles(basePath);
+    // Write our lock data first (the content is informational; the OS lock is the real guard)
+    const lockData = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        unitType: "starting",
+        unitId: "bootstrap",
+        unitStartedAt: new Date().toISOString(),
+        completedUnits: 0,
+    };
+    let lockfile;
+    try {
+        lockfile = _require("proper-lockfile");
+    }
+    catch {
+        // proper-lockfile not available — fall back to PID-based check
+        return acquireFallbackLock(basePath, lp, lockData);
+    }
+    const gsdDir = gsdRoot(basePath);
+    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.
+        mkdirSync(gsdDir, { recursive: true });
+        const release = lockfile.lockSync(gsdDir, {
+            realpath: false,
+            stale: 1_800_000, // 30 minutes — safe for laptop sleep / long event loop stalls
+            update: 10_000, // Update lock mtime every 10s to prove liveness
+            onCompromised: () => {
+                // proper-lockfile detected mtime drift (system sleep, event loop stall, etc.).
+                // Default handler throws inside setTimeout — an uncaught exception that crashes
+                // or corrupts process state. Instead, set a flag so validateSessionLock() can
+                // detect the compromise gracefully on the next dispatch cycle.
+                _lockCompromised = true;
+                _releaseFunction = null;
+            },
+        });
+        _releaseFunction = release;
+        _lockedPath = basePath;
+        _lockPid = process.pid;
+        _lockCompromised = false;
+        // Safety net: clean up lock dir on process exit if _releaseFunction
+        // wasn't called (e.g., normal exit after clean completion) (#1245).
+        ensureExitHandler(gsdDir);
+        // Write the informational lock data
+        atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
+        return { acquired: true };
+    }
+    catch (err) {
+        // Lock is held by another process — or the .gsd.lock/ directory is stranded.
+        // Check: if auto.lock is gone and no process is alive, the lock dir is stale.
+        const existingData = readExistingLockData(lp);
+        const existingPid = existingData?.pid;
+        // If no lock file or no alive process, try to clean up and re-acquire (#1245)
+        if (!existingData || (existingPid && !isPidAlive(existingPid))) {
+            try {
+                const lockDir = join(gsdDir + ".lock");
+                if (existsSync(lockDir))
+                    rmSync(lockDir, { recursive: true, force: true });
+                if (existsSync(lp))
+                    unlinkSync(lp);
+                // Retry acquisition after cleanup
+                const release = lockfile.lockSync(gsdDir, {
+                    realpath: false,
+                    stale: 1_800_000, // 30 minutes — match primary lock settings
+                    update: 10_000,
+                    onCompromised: () => {
+                        _lockCompromised = true;
+                        _releaseFunction = null;
+                    },
+                });
+                _releaseFunction = release;
+                _lockedPath = basePath;
+                _lockPid = process.pid;
+                _lockCompromised = false;
+                // Safety net — uses centralized handler to avoid double-registration
+                ensureExitHandler(gsdDir);
+                atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
+                return { acquired: true };
+            }
+            catch {
+                // Retry also failed — fall through to the error path
+            }
+        }
+        const reason = existingPid
+            ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.`
+            : `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, lp, lockData) {
+    // 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, unitType, unitId, completedUnits, sessionFile) {
+    if (_lockedPath !== basePath && _lockedPath !== null)
+        return;
+    const lp = lockPath(basePath);
+    try {
+        const data = {
+            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) {
+    // Lock was compromised by proper-lockfile (mtime drift from sleep, stall, etc.)
+    if (_lockCompromised) {
+        return false;
+    }
+    // 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) {
+    // 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
+    }
+    // Remove the proper-lockfile directory (.gsd.lock/) if it exists.
+    // proper-lockfile creates this directory as the OS-level lock mechanism.
+    // If the process exits without calling _releaseFunction (SIGKILL, crash),
+    // this directory is stranded and blocks the next session (#1245).
+    try {
+        const lockDir = join(gsdRoot(basePath) + ".lock");
+        if (existsSync(lockDir))
+            rmSync(lockDir, { recursive: true, force: true });
+    }
+    catch {
+        // Non-fatal
+    }
+    // Clean up numbered lock file variants from cloud sync conflicts (#1315)
+    cleanupStrayLockFiles(basePath);
+    _lockedPath = null;
+    _lockPid = 0;
+    _lockCompromised = false;
+}
+/**
+ * Check if a session lock exists and return its data (for crash recovery).
+ * Does NOT acquire the lock.
+ */
+export function readSessionLockData(basePath) {
+    return readExistingLockData(lockPath(basePath));
+}
+/**
+ * Check if the process that wrote the lock is still alive.
+ */
+export function isSessionLockProcessAlive(data) {
+    return isPidAlive(data.pid);
+}
+/**
+ * Returns true if we currently hold a session lock for the given path.
+ */
+export function isSessionLockHeld(basePath) {
+    return _lockedPath === basePath && _lockPid === process.pid;
+}
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+function readExistingLockData(lp) {
+    try {
+        if (!existsSync(lp))
+            return null;
+        const raw = readFileSync(lp, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function isPidAlive(pid) {
+    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.code === "EPERM")
+            return true;
+        return false;
+    }
+}

package/dist/resources/extensions/gsd/session-status-io.js

@@ -0,0 +1,134 @@
+/**
+ * GSD Session Status I/O
+ *
+ * File-based IPC protocol for coordinator-worker communication in
+ * parallel milestone orchestration. Each worker writes its status to a
+ * file; the coordinator reads all status files to monitor progress.
+ *
+ * Atomic writes (write to .tmp, then rename) prevent partial reads.
+ * Signal files let the coordinator send pause/resume/stop/rebase to workers.
+ * Stale detection combines PID liveness checks with heartbeat timeouts.
+ */
+import { unlinkSync, readdirSync, mkdirSync, existsSync, } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { loadJsonFileOrNull, writeJsonFileAtomic } from "./json-persistence.js";
+// ─── Constants ─────────────────────────────────────────────────────────────
+const PARALLEL_DIR = "parallel";
+const STATUS_SUFFIX = ".status.json";
+const SIGNAL_SUFFIX = ".signal.json";
+const DEFAULT_STALE_TIMEOUT_MS = 30_000;
+function isSessionStatus(data) {
+    return data !== null && typeof data === "object" && "milestoneId" in data && "pid" in data;
+}
+function isSignalMessage(data) {
+    return data !== null && typeof data === "object" && "signal" in data && "sentAt" in data;
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function parallelDir(basePath) {
+    return join(gsdRoot(basePath), PARALLEL_DIR);
+}
+function statusPath(basePath, milestoneId) {
+    return join(parallelDir(basePath), `${milestoneId}${STATUS_SUFFIX}`);
+}
+function signalPath(basePath, milestoneId) {
+    return join(parallelDir(basePath), `${milestoneId}${SIGNAL_SUFFIX}`);
+}
+function ensureParallelDir(basePath) {
+    const dir = parallelDir(basePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Status I/O ────────────────────────────────────────────────────────────
+/** Write session status atomically (write to .tmp, then rename). */
+export function writeSessionStatus(basePath, status) {
+    ensureParallelDir(basePath);
+    writeJsonFileAtomic(statusPath(basePath, status.milestoneId), status);
+}
+/** Read a specific milestone's session status. */
+export function readSessionStatus(basePath, milestoneId) {
+    return loadJsonFileOrNull(statusPath(basePath, milestoneId), isSessionStatus);
+}
+/** Read all session status files from .gsd/parallel/. */
+export function readAllSessionStatuses(basePath) {
+    const dir = parallelDir(basePath);
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (!entry.endsWith(STATUS_SUFFIX))
+                continue;
+            const status = loadJsonFileOrNull(join(dir, entry), isSessionStatus);
+            if (status)
+                results.push(status);
+        }
+    }
+    catch { /* non-fatal */ }
+    return results;
+}
+/** Remove a milestone's session status file. */
+export function removeSessionStatus(basePath, milestoneId) {
+    try {
+        const p = statusPath(basePath, milestoneId);
+        if (existsSync(p))
+            unlinkSync(p);
+    }
+    catch { /* non-fatal */ }
+}
+// ─── Signal I/O ────────────────────────────────────────────────────────────
+/** Write a signal file for a worker to consume. */
+export function sendSignal(basePath, milestoneId, signal) {
+    ensureParallelDir(basePath);
+    const msg = { 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, milestoneId) {
+    const p = signalPath(basePath, milestoneId);
+    const msg = loadJsonFileOrNull(p, isSignalMessage);
+    if (msg) {
+        try {
+            unlinkSync(p);
+        }
+        catch { /* non-fatal */ }
+    }
+    return msg;
+}
+// ─── Stale Detection ───────────────────────────────────────────────────────
+/** Check whether a session is stale (PID dead or heartbeat timed out). */
+export function isSessionStale(status, timeoutMs = DEFAULT_STALE_TIMEOUT_MS) {
+    if (!isPidAlive(status.pid))
+        return true;
+    const elapsed = Date.now() - status.lastHeartbeat;
+    return elapsed > timeoutMs;
+}
+/** Find and remove stale sessions. Returns the milestone IDs that were cleaned up. */
+export function cleanupStaleSessions(basePath, timeoutMs = DEFAULT_STALE_TIMEOUT_MS) {
+    const removed = [];
+    const statuses = readAllSessionStatuses(basePath);
+    for (const status of statuses) {
+        if (isSessionStale(status, timeoutMs)) {
+            removeSessionStatus(basePath, status.milestoneId);
+            // Also clean up any lingering signal file
+            try {
+                const sig = signalPath(basePath, status.milestoneId);
+                if (existsSync(sig))
+                    unlinkSync(sig);
+            }
+            catch { /* non-fatal */ }
+            removed.push(status.milestoneId);
+        }
+    }
+    return removed;
+}

package/dist/resources/extensions/gsd/skill-discovery.js

@@ -0,0 +1,121 @@
+/**
+ * GSD Skill Discovery
+ *
+ * Detects skills installed during auto-mode by comparing the current
+ * skills directory against a snapshot taken at auto-mode start.
+ *
+ * New skills are injected into the system prompt via before_agent_start,
+ * making them visible to all subsequent units without requiring a reload.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@gsd/pi-coding-agent";
+const SKILLS_DIR = join(getAgentDir(), "skills");
+/** Snapshot of skill names at auto-mode start */
+let baselineSkills = null;
+/**
+ * Snapshot the current skills directory. Call at auto-mode start.
+ */
+export function snapshotSkills() {
+    baselineSkills = new Set(listSkillDirs());
+}
+/**
+ * Clear the snapshot. Call when auto-mode stops.
+ */
+export function clearSkillSnapshot() {
+    baselineSkills = null;
+}
+/**
+ * Check if a snapshot is active (auto-mode is running with discovery).
+ */
+export function hasSkillSnapshot() {
+    return baselineSkills !== null;
+}
+/**
+ * Detect skills installed since the snapshot was taken.
+ * Returns skill metadata for any new skills found.
+ */
+export function detectNewSkills() {
+    if (!baselineSkills)
+        return [];
+    const current = listSkillDirs();
+    const newSkills = [];
+    for (const dir of current) {
+        if (baselineSkills.has(dir))
+            continue;
+        const skillMdPath = join(SKILLS_DIR, dir, "SKILL.md");
+        if (!existsSync(skillMdPath))
+            continue;
+        const meta = parseSkillFrontmatter(skillMdPath);
+        if (meta) {
+            newSkills.push({
+                name: meta.name || dir,
+                description: meta.description || `Skill: ${dir}`,
+                location: skillMdPath,
+            });
+        }
+    }
+    return newSkills;
+}
+/**
+ * Format discovered skills as an XML block matching pi's <available_skills> format.
+ * This can be appended to the system prompt so the LLM sees them naturally.
+ */
+export function formatSkillsXml(skills) {
+    if (skills.length === 0)
+        return "";
+    const entries = skills.map(s => `  <skill>
+    <name>${escapeXml(s.name)}</name>
+    <description>${escapeXml(s.description)}</description>
+    <location>${escapeXml(s.location)}</location>
+  </skill>`).join("\n");
+    return `\n<newly_discovered_skills>
+The following skills were installed during this auto-mode session.
+Use the read tool to load a skill's file when the task matches its description.
+
+${entries}
+</newly_discovered_skills>`;
+}
+// ─── Internals ────────────────────────────────────────────────────────────────
+function listSkillDirs() {
+    if (!existsSync(SKILLS_DIR))
+        return [];
+    try {
+        return readdirSync(SKILLS_DIR, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name);
+    }
+    catch {
+        return [];
+    }
+}
+function parseSkillFrontmatter(path) {
+    try {
+        const content = readFileSync(path, "utf-8");
+        // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
+        if (!content.startsWith('---\n'))
+            return null;
+        const endIdx = content.indexOf('\n---', 4);
+        if (endIdx === -1)
+            return null;
+        const fm = content.slice(4, endIdx);
+        const result = {};
+        const nameMatch = fm.match(/^name:\s*(.+)$/m);
+        if (nameMatch)
+            result.name = nameMatch[1].trim();
+        const descMatch = fm.match(/^description:\s*(.+)$/m);
+        if (descMatch)
+            result.description = descMatch[1].trim();
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+function escapeXml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}