@tekyzinc/gsd-t 3.29.11 → 4.0.12

package/bin/headless-auto-spawn.js

@@ -1,373 +0,0 @@
-#!/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,
-  // M43 D4 — channel-separation invariant; see .cjs twin.
-  shouldSpawnHeadless: () => true,
-};
-
-// M43 D4 — one-shot deprecation banner (legacy `.js` copy mirrors `.cjs`).
-let _deprecatedWatchWarned = false;
-
-// ── autoSpawnHeadless ────────────────────────────────────────────────────────
-
-/**
- * @param {{
- *   command: string,
- *   args?: string[],
- *   continue_from?: string,
- *   projectDir?: string,
- *   context?: object,
- *   sessionContext?: object,
- *   sessionId?: string,
- *   watch?: boolean,
- *   spawnType?: 'primary' | 'validation'
- * }} opts
- * @returns {{ id: string | null, pid: number | null, logPath: string | null, timestamp: string, mode: 'headless' | 'in-context' }}
- */
-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 || opts.sessionContext || null;
-  // M43 D4 — `watch`/`inSession` ignored under v2.0.0 channel-separation.
-  const legacyWatch = opts.watch === true;
-  const legacyInSession = opts.inSession === true;
-  if ((legacyWatch || legacyInSession) && !_deprecatedWatchWarned) {
-    _deprecatedWatchWarned = true;
-    try {
-      process.stderr.write(
-        "[headless-default] `watch`/`inSession` flag is deprecated under headless-default-contract v2.0.0 — every spawn is headless; caller hint ignored.\n",
-      );
-    } catch (_) {
-      /* best-effort */
-    }
-  }
-  const spawnType = opts.spawnType || "primary";
-
-  if (!command || typeof command !== "string") {
-    throw new Error("autoSpawnHeadless: `command` is required");
-  }
-  if (spawnType !== "primary" && spawnType !== "validation") {
-    throw new Error(
-      `autoSpawnHeadless: \`spawnType\` must be 'primary' or 'validation' (got ${JSON.stringify(spawnType)})`,
-    );
-  }
-
-  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"];
-
-    // v3.12.14 — env-var propagation for telemetry tagging (mirror of the
-    // authoritative .cjs variant). PRODUCTION consumers import the .cjs; this
-    // .js copy is retained only to keep the legacy test green.
-    const workerEnv = Object.assign({}, process.env, {
-      GSD_T_COMMAND: command,
-      GSD_T_PHASE: process.env.GSD_T_PHASE || "execute",
-      GSD_T_PROJECT_DIR: process.env.GSD_T_PROJECT_DIR || projectDir,
-    });
-    if (process.env.GSD_T_TRACE_ID) workerEnv.GSD_T_TRACE_ID = process.env.GSD_T_TRACE_ID;
-    if (process.env.GSD_T_MODEL) workerEnv.GSD_T_MODEL = process.env.GSD_T_MODEL;
-
-    const child = spawn("node", childArgs, {
-      cwd: projectDir,
-      detached: true,
-      stdio: ["ignore", logFd, logFd],
-      env: workerEnv,
-    });
-
-    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,
-    mode: "headless",
-  };
-}
-
-// ── 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-/, "");
-}

package/bin/headless-exit-codes.cjs

@@ -1,67 +0,0 @@
-/**
- * Shared helper: map a `claude -p` process exit code + output to the
- * GSD-T headless exit-code contract.
- *
- * Lives in its own file so non-entry modules (e.g. gsd-t-unattended.cjs)
- * can require it without pulling in the full CLI at bin/gsd-t.js. That
- * decoupling lets PROJECT_BIN_TOOLS ship the supervisor without also
- * vendoring the CLI itself — projects resolve `gsd-t` from the global
- * install, not from a project-local copy.
- *
- * Exit codes (contract):
- *   0 — success
- *   1 — verification/test failure
- *   2 — context budget exceeded
- *   3 — non-zero process exit (other)
- *   4 — blocked / needs human
- *   5 — unknown slash command (claude -p exited 0 but rejected the prompt)
- */
-
-"use strict";
-
-// Match terminal markers, not narration. A bare "tests failed" substring will
-// appear in healthy output ("0 tests failed", "no tests failed", quoted as an
-// example in prose). Require either a non-zero count prefix or a structured
-// terminal marker (start of line, uppercase-FAIL prefix, Jest-style summary).
-// Bug history: M45 worker output contained "tests failed" 6× in narration,
-// causing the supervisor to map exit 0 → exit 1 and halt a successful run.
-
-const NONZERO_FAILURE_COUNT_RE =
-  /(?:^|\b)([1-9]\d*)\s+(?:tests?|specs?|assertions?|examples?|suites?)\s+failed\b/i;
-const STRUCTURED_FAIL_RE = /^FAIL[:\s]/m;
-const JEST_SUMMARY_FAIL_RE = /^Tests:\s+\d+\s+failed/im;
-
-// Verification-phrase matchers: require the phrase at a line boundary or
-// preceded by a sentence-start punctuation — not mid-prose. Each phrase is
-// distinctive enough that start-of-line / post-punctuation is a reliable
-// terminal-marker signal.
-const VERIFICATION_FAILED_RE =
-  /(?:^|[.!?]\s+)(?:verification|verify|quality gate)\s+failed\b/im;
-
-// Context-budget phrases — same polarity discipline. Tolerant of surrounding
-// punctuation (— / :) but requires the phrase at a line boundary.
-const CONTEXT_BUDGET_RE =
-  /(?:^|[.!?]\s+)(?:context budget exceeded|context window exceeded|budget exceeded|token limit)\b/im;
-
-// Blocker compound: "blocked" within 80 chars of a human-gate phrase, both
-// anchored to recognizable boundaries. The 80-char proximity keeps unrelated
-// mentions from compounding.
-const BLOCKED_HUMAN_RE =
-  /\bblocked\b[\s\S]{0,80}?\b(?:needs? human|human input|human approval)\b/i;
-
-function mapHeadlessExitCode(processExitCode, output) {
-  if (processExitCode !== 0 && processExitCode !== null) return 3;
-  const raw = output || "";
-  if (/^unknown command:/im.test(raw)) return 5;
-  if (CONTEXT_BUDGET_RE.test(raw)) return 2;
-  if (BLOCKED_HUMAN_RE.test(raw)) return 4;
-  if (
-    VERIFICATION_FAILED_RE.test(raw) ||
-    NONZERO_FAILURE_COUNT_RE.test(raw) ||
-    STRUCTURED_FAIL_RE.test(raw) ||
-    JEST_SUMMARY_FAIL_RE.test(raw)
-  ) return 1;
-  return 0;
-}
-
-module.exports = { mapHeadlessExitCode };