@tekyzinc/gsd-t 2.74.13 → 3.10.10

package/bin/handoff-lock.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Handoff Lock — Fail-safe sentinel preventing parent/child race
+ * conditions in `autoSpawnHeadless()`.
+ *
+ * Problem: when the interactive parent spawns a detached headless child to
+ * resume a session, both processes may briefly contend for the continue-here
+ * file and session JSON. If the child wakes and reads before the parent has
+ * finished writing, it sees stale or partial state.
+ *
+ * Solution: the parent acquires a short-lived lock on
+ * `.gsd-t/.handoff/lock-{sessionId}` BEFORE writing handoff artifacts and
+ * releases it AFTER `child.unref()` returns. The child waits on the same
+ * lock path before reading the continue-here file.
+ *
+ * Locks are TTL-bounded (default 30s) so a crashed parent can never wedge
+ * a future spawn — `cleanStaleLocks()` swept by housekeeping or by the next
+ * acquire attempt against an expired record reclaims the slot.
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ *
+ * Contract: .gsd-t/contracts/headless-auto-spawn-contract.md v1.0.0
+ *           (implementation-detail primitive; no contract bump)
+ * Consumers: bin/headless-auto-spawn.js (Task 2 — wires this in),
+ *            commands/gsd-t-resume.md (child-side wait).
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const HANDOFF_DIR_REL = path.join(".gsd-t", ".handoff");
+const LOCK_FILE_PREFIX = "lock-";
+const DEFAULT_TTL_MS = 30000;
+const DEFAULT_WAIT_TIMEOUT_MS = 30000;
+const DEFAULT_STALE_AGE_MS = 60000;
+const POLL_INTERVAL_MS = 100;
+const GRACE_MS = 500;
+
+// ── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  acquireHandoffLock,
+  releaseHandoffLock,
+  waitForLockRelease,
+  cleanStaleLocks,
+  // Exported for tests / consumer wiring:
+  lockPathFor,
+  HANDOFF_DIR_REL,
+};
+
+// ── acquireHandoffLock ───────────────────────────────────────────────────────
+
+/**
+ * Acquire an exclusive handoff lock for the given sessionId.
+ *
+ * @param {string} projectDir
+ * @param {string} sessionId
+ * @param {{ ttlMs?: number }} [opts]
+ * @returns {{ lockPath: string, sessionId: string }} release handle
+ * @throws {Error} if an unexpired lock already exists
+ */
+function acquireHandoffLock(projectDir, sessionId, opts) {
+  if (!projectDir || typeof projectDir !== "string") {
+    throw new Error("acquireHandoffLock: `projectDir` is required");
+  }
+  if (!sessionId || typeof sessionId !== "string") {
+    throw new Error("acquireHandoffLock: `sessionId` is required");
+  }
+  const ttlMs = (opts && opts.ttlMs) || DEFAULT_TTL_MS;
+
+  const dir = path.join(projectDir, HANDOFF_DIR_REL);
+  ensureDir(dir);
+
+  const lockPath = lockPathFor(projectDir, sessionId);
+
+  // If a lock file already exists, decide whether it is still binding.
+  if (fs.existsSync(lockPath)) {
+    const existing = readLockSafe(lockPath);
+    const now = Date.now();
+    if (existing && now < existing.releaseBy + GRACE_MS) {
+      throw new Error(
+        `handoff lock held by PID ${existing.parentPid} until ${new Date(
+          existing.releaseBy,
+        ).toISOString()}`,
+      );
+    }
+    // Expired or unparseable — reclaim it.
+    try {
+      fs.unlinkSync(lockPath);
+    } catch (_) {
+      /* race: someone else cleaned it; fall through */
+    }
+  }
+
+  const acquiredAt = Date.now();
+  const record = {
+    sessionId,
+    parentPid: process.pid,
+    acquiredAt,
+    releaseBy: acquiredAt + ttlMs,
+  };
+
+  // Write atomically: O_EXCL ensures we lose if a concurrent acquirer beats
+  // us between the existsSync check above and this write.
+  let fd;
+  try {
+    fd = fs.openSync(lockPath, "wx");
+  } catch (e) {
+    if (e && e.code === "EEXIST") {
+      // Another acquirer raced ahead; surface a uniform error.
+      const existing = readLockSafe(lockPath);
+      const pid = existing ? existing.parentPid : "unknown";
+      const until = existing
+        ? new Date(existing.releaseBy).toISOString()
+        : "unknown";
+      throw new Error(`handoff lock held by PID ${pid} until ${until}`);
+    }
+    throw e;
+  }
+  try {
+    fs.writeSync(fd, JSON.stringify(record, null, 2) + "\n");
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return { lockPath, sessionId };
+}
+
+// ── releaseHandoffLock ───────────────────────────────────────────────────────
+
+/**
+ * Release a previously acquired handoff lock. Idempotent — tolerates a
+ * missing file (already released or never existed).
+ *
+ * @param {{ lockPath: string, sessionId: string }} handle
+ */
+function releaseHandoffLock(handle) {
+  if (!handle || !handle.lockPath) return;
+  try {
+    fs.unlinkSync(handle.lockPath);
+  } catch (e) {
+    if (e && e.code === "ENOENT") return; // already released
+    throw e;
+  }
+}
+
+// ── waitForLockRelease ───────────────────────────────────────────────────────
+
+/**
+ * Poll until the lock file for {sessionId} no longer exists, OR until
+ * timeoutMs elapses. Throws on timeout.
+ *
+ * @param {string} projectDir
+ * @param {string} sessionId
+ * @param {number} [timeoutMs]
+ * @returns {Promise<true>}
+ */
+function waitForLockRelease(projectDir, sessionId, timeoutMs) {
+  const limit = typeof timeoutMs === "number" ? timeoutMs : DEFAULT_WAIT_TIMEOUT_MS;
+  const lockPath = lockPathFor(projectDir, sessionId);
+  const start = Date.now();
+
+  return new Promise((resolve, reject) => {
+    const check = () => {
+      if (!fs.existsSync(lockPath)) {
+        resolve(true);
+        return;
+      }
+      if (Date.now() - start >= limit) {
+        reject(new Error(`waitForLockRelease timeout after ${limit}ms`));
+        return;
+      }
+      setTimeout(check, POLL_INTERVAL_MS);
+    };
+    check();
+  });
+}
+
+// ── cleanStaleLocks ──────────────────────────────────────────────────────────
+
+/**
+ * Sweep `.gsd-t/.handoff/` and remove any `lock-*` file whose `acquiredAt`
+ * is older than `maxAgeMs`. Returns the count of files removed.
+ *
+ * @param {string} projectDir
+ * @param {number} [maxAgeMs]
+ * @returns {number}
+ */
+function cleanStaleLocks(projectDir, maxAgeMs) {
+  const limit = typeof maxAgeMs === "number" ? maxAgeMs : DEFAULT_STALE_AGE_MS;
+  const dir = path.join(projectDir, HANDOFF_DIR_REL);
+  if (!fs.existsSync(dir)) return 0;
+
+  let removed = 0;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (_) {
+    return 0;
+  }
+  const now = Date.now();
+  for (const name of entries) {
+    if (!name.startsWith(LOCK_FILE_PREFIX)) continue;
+    const fp = path.join(dir, name);
+    const rec = readLockSafe(fp);
+    // Unparseable lock files are treated as stale — they're not protecting
+    // anything, and leaving them around defeats the cleaner.
+    if (!rec || now - rec.acquiredAt > limit) {
+      try {
+        fs.unlinkSync(fp);
+        removed++;
+      } catch (_) {
+        /* ignore */
+      }
+    }
+  }
+  return removed;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function lockPathFor(projectDir, sessionId) {
+  return path.join(projectDir, HANDOFF_DIR_REL, `${LOCK_FILE_PREFIX}${sessionId}`);
+}
+
+function readLockSafe(fp) {
+  try {
+    const raw = fs.readFileSync(fp, "utf8");
+    const j = JSON.parse(raw);
+    if (
+      typeof j === "object" &&
+      j &&
+      typeof j.acquiredAt === "number" &&
+      typeof j.releaseBy === "number"
+    ) {
+      return j;
+    }
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function ensureDir(d) {
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}

package/bin/headless-auto-spawn.js

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Headless Auto-Spawn — Detached headless continuation
+ *
+ * When the runway estimator refuses a run (projected context ≥ stop band),
+ * the caller invokes `autoSpawnHeadless()` to hand off to a detached child
+ * process running `gsd-t headless {command} --log`. The interactive session
+ * never blocks on the child (`child.unref()`), so the user retains their
+ * terminal and can work on unrelated tasks. On child completion, a macOS
+ * notification fires (T2). The interactive session surfaces the result via
+ * a read-back banner on the next `gsd-t-resume` or `gsd-t-status` call (T4).
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ *
+ * Contract: .gsd-t/contracts/headless-auto-spawn-contract.md v1.0.0
+ * Consumers: commands/gsd-t-execute|wave|integrate|quick|debug.md (via runway
+ *            estimator handoff), bin/runway-estimator.js (conceptual target).
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+const {
+  acquireHandoffLock,
+  releaseHandoffLock,
+  // waitForLockRelease — NOT consumed here. The child-side wait is
+  // performed by `commands/gsd-t-resume.md` Step 0 (wired in m36
+  // watch-loop Task 4); it calls waitForLockRelease(projectDir,
+  // sessionId) before reading the continue-here file.
+} = require("./handoff-lock.js");
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const SESSIONS_DIR_REL = path.join(".gsd-t", "headless-sessions");
+const LOG_DIR_REL = ".gsd-t"; // headless-{id}.log lives directly in .gsd-t
+
+// ── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  autoSpawnHeadless,
+  makeSessionId,
+  writeSessionFile,
+  writeContinueHereFile,
+  markSessionCompleted,
+};
+
+// ── autoSpawnHeadless ────────────────────────────────────────────────────────
+
+/**
+ * @param {{
+ *   command: string,
+ *   args?: string[],
+ *   continue_from?: string,
+ *   projectDir?: string,
+ *   context?: object
+ * }} opts
+ * @returns {{ id: string, pid: number, logPath: string, timestamp: string }}
+ */
+function autoSpawnHeadless(opts) {
+  const command = opts.command;
+  const args = opts.args || [];
+  const continue_from = opts.continue_from || ".";
+  const projectDir = opts.projectDir || process.cwd();
+  const context = opts.context || null;
+
+  if (!command || typeof command !== "string") {
+    throw new Error("autoSpawnHeadless: `command` is required");
+  }
+
+  const timestamp = new Date().toISOString();
+  const id = makeSessionId(command, new Date());
+  const logPath = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);
+
+  ensureDir(path.join(projectDir, LOG_DIR_REL));
+  ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
+
+  // Handoff-lock gate (m36 gap-fix T2). Only engaged when the caller
+  // supplies a `sessionId` — existing callers that do not pass one keep
+  // the pre-m36 behavior unchanged. When engaged, the lock is held
+  // across writeContinueHereFile + spawn so a child that is already
+  // waiting via `waitForLockRelease()` (see commands/gsd-t-resume.md
+  // Step 0, wired by m36 watch-loop T4) cannot read a half-written
+  // continue-here file. See .gsd-t/contracts/headless-auto-spawn-contract.md
+  // v1.0.0 (implementation-detail primitive; no contract bump).
+  const lockSessionId = typeof opts.sessionId === "string" && opts.sessionId
+    ? opts.sessionId
+    : null;
+  let lockHandle = null;
+  if (lockSessionId) {
+    lockHandle = acquireHandoffLock(projectDir, lockSessionId);
+  }
+
+  let pid = 0;
+  try {
+    // Open log file descriptor before spawning — child writes directly.
+    const logFd = fs.openSync(logPath, "a");
+
+    // Headless invocation: `node bin/gsd-t.js headless <command> [args] --log`
+    // The `gsd-t` CLI entry point is bin/gsd-t.js relative to projectDir.
+    const gsdtCli = path.join(projectDir, "bin", "gsd-t.js");
+    const childArgs = [gsdtCli, "headless", stripGsdtPrefix(command), ...args, "--log"];
+
+    const child = spawn("node", childArgs, {
+      cwd: projectDir,
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: process.env,
+    });
+
+    child.unref();
+    fs.closeSync(logFd);
+
+    pid = child.pid || 0;
+
+    writeSessionFile(projectDir, {
+      id,
+      pid,
+      logPath: path.relative(projectDir, logPath),
+      startTimestamp: timestamp,
+      command,
+      args,
+      status: "running",
+      continueFromPath: continue_from,
+      surfaced: false,
+    });
+
+    writeContinueHereFile(projectDir, id, context);
+  } finally {
+    // Release the lock AFTER the child is confirmed started and
+    // handoff artifacts are on disk. The finally ensures a spawn
+    // failure still frees the slot for a retry.
+    if (lockHandle) {
+      try {
+        releaseHandoffLock(lockHandle);
+      } catch (_) {
+        /* idempotent best-effort */
+      }
+    }
+  }
+
+  // T2 — install completion watcher. Non-blocking (setImmediate) so the
+  // caller's return is not delayed. The watcher uses `child.on('exit')` on
+  // a separately-spawned bridge process; here we defer to fs.watchFile for
+  // a detached approach that survives even after the parent's `unref()`.
+  installCompletionWatcher({ projectDir, id, logPath, pid, startTimestamp: timestamp });
+
+  return { id, pid, logPath: path.relative(projectDir, logPath), timestamp };
+}
+
+// ── makeSessionId ────────────────────────────────────────────────────────────
+
+/**
+ * @param {string} command
+ * @param {Date} [now]
+ * @returns {string} e.g., "gsd-t-execute-2026-04-15-01-23-45"
+ */
+function makeSessionId(command, now) {
+  const d = now || new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+  const time = `${pad(d.getHours())}-${pad(d.getMinutes())}-${pad(d.getSeconds())}`;
+  const base = stripGsdtPrefix(command) || command;
+  return `gsd-t-${base}-${date}-${time}`;
+}
+
+// ── writeSessionFile ─────────────────────────────────────────────────────────
+
+function writeSessionFile(projectDir, session) {
+  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${session.id}.json`);
+  ensureDir(path.dirname(fp));
+  fs.writeFileSync(fp, JSON.stringify(session, null, 2) + "\n");
+  return fp;
+}
+
+// ── writeContinueHereFile ────────────────────────────────────────────────────
+
+function writeContinueHereFile(projectDir, id, context) {
+  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${id}-context.json`);
+  const payload = context || buildContextSnapshot(projectDir);
+  fs.writeFileSync(fp, JSON.stringify(payload, null, 2) + "\n");
+  return fp;
+}
+
+function buildContextSnapshot(projectDir) {
+  // Best-effort snapshot of current GSD-T state at handoff time.
+  const snap = {
+    capturedAt: new Date().toISOString(),
+    progress: null,
+    currentDomain: null,
+    pendingTasks: [],
+    lastDecisionLogEntry: null,
+    currentWave: null,
+  };
+  try {
+    const progressFp = path.join(projectDir, ".gsd-t", "progress.md");
+    if (fs.existsSync(progressFp)) {
+      const raw = fs.readFileSync(progressFp, "utf8");
+      snap.progress = firstNLines(raw, 20);
+      // Pull the last Decision Log entry (last non-empty bullet line).
+      const lines = raw.split("\n");
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const ln = lines[i].trim();
+        if (ln.startsWith("- ")) {
+          snap.lastDecisionLogEntry = ln;
+          break;
+        }
+      }
+    }
+  } catch (_) {
+    /* best-effort */
+  }
+  return snap;
+}
+
+function firstNLines(s, n) {
+  return s.split("\n").slice(0, n).join("\n");
+}
+
+// ── markSessionCompleted ─────────────────────────────────────────────────────
+
+/**
+ * T2 completion hook — updates the session file in place.
+ * @param {string} projectDir
+ * @param {string} id
+ * @param {{ exitCode: number, endTimestamp?: string }} result
+ */
+function markSessionCompleted(projectDir, id, result) {
+  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${id}.json`);
+  if (!fs.existsSync(fp)) return;
+  try {
+    const s = JSON.parse(fs.readFileSync(fp, "utf8"));
+    s.status = "completed";
+    s.exitCode = result.exitCode;
+    s.endTimestamp = result.endTimestamp || new Date().toISOString();
+    fs.writeFileSync(fp, JSON.stringify(s, null, 2) + "\n");
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+// ── Completion watcher (T2) — macOS notification on exit ─────────────────────
+
+function installCompletionWatcher(opts) {
+  const { projectDir, id, pid, startTimestamp } = opts;
+  if (!pid || pid <= 0) return;
+
+  // Poll-based watcher. We can't hold a reference to the child (it's unref'd
+  // and detached), so we poll `process.kill(pid, 0)` which throws if the
+  // process is gone. This is cheap and survives across detachment.
+  const POLL_MS = 2000;
+  const MAX_WAIT_MS = 60 * 60 * 1000; // 1 hour safety cap
+  const startMs = Date.now();
+
+  const timer = setInterval(() => {
+    let alive = false;
+    try {
+      process.kill(pid, 0);
+      alive = true;
+    } catch (_) {
+      alive = false;
+    }
+    if (!alive) {
+      clearInterval(timer);
+      // Exit code is unknown from a signal-based probe. Best-effort: read
+      // the log's last lines to guess, otherwise default to 0.
+      const exitCode = guessExitCodeFromLog(projectDir, id);
+      markSessionCompleted(projectDir, id, {
+        exitCode,
+        endTimestamp: new Date().toISOString(),
+      });
+      fireMacNotification({ id, command: extractCommand(id), startTimestamp });
+    } else if (Date.now() - startMs > MAX_WAIT_MS) {
+      clearInterval(timer);
+    }
+  }, POLL_MS);
+
+  // Let the timer not block the parent's exit.
+  if (typeof timer.unref === "function") timer.unref();
+}
+
+function guessExitCodeFromLog(projectDir, id) {
+  try {
+    const fp = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);
+    if (!fs.existsSync(fp)) return 0;
+    const raw = fs.readFileSync(fp, "utf8");
+    if (/exit code[: ]+(\d+)/i.test(raw)) {
+      const m = raw.match(/exit code[: ]+(\d+)/i);
+      return parseInt(m[1], 10);
+    }
+    return 0;
+  } catch (_) {
+    return 0;
+  }
+}
+
+function extractCommand(id) {
+  // id format: gsd-t-{command}-{date}-{time}
+  const m = id.match(/^gsd-t-(.+?)-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}$/);
+  return m ? m[1] : id;
+}
+
+function fireMacNotification({ id, command }) {
+  if (process.platform !== "darwin") return;
+  try {
+    const { spawn } = require("child_process");
+    const msg = `GSD-T headless run complete: ${id}`;
+    const script = `display notification "${msg}" with title "GSD-T" subtitle "${command}"`;
+    const child = spawn("osascript", ["-e", script], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+  } catch (_) {
+    /* graceful degradation */
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function ensureDir(d) {
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}
+
+function stripGsdtPrefix(command) {
+  if (typeof command !== "string") return "";
+  return command.replace(/^gsd-t-/, "");
+}