@tekyzinc/gsd-t 3.29.11 → 4.0.12

package/bin/spawn-plan-writer.cjs

@@ -1,204 +0,0 @@
-'use strict';
-
-/**
- * GSD-T Spawn Plan Writer (M44 D8 T1)
- *
- * Pure module — writes a spawn-plan JSON file under `.gsd-t/spawns/{spawnId}.json`
- * at every spawn chokepoint (captureSpawn, autoSpawnHeadless, unattended-worker
- * resume Step 0). The plan file answers exactly one question:
- *
- *   "Of the tasks that were supposed to happen in this spawn, which are done,
- *    which are in flight, which are pending?"
- *
- * Hard rules (see .gsd-t/domains/m44-d8-spawn-plan-visibility/constraints.md):
- *   1. Writer DERIVES, never decides — no LLM calls, no prompts, no heuristics
- *      beyond reading partition.md + tasks.md.
- *   2. Spawn must launch even if writer fails — callers wrap in try/catch.
- *   3. Atomic writes only (temp file + rename).
- *
- * Contract: .gsd-t/contracts/spawn-plan-contract.md v1.0.0
- *
- * Zero external deps. `.cjs` so it loads in both ESM-default and CJS projects.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const SPAWNS_SUBDIR = path.join('.gsd-t', 'spawns');
-const SPAWN_PLAN_SCHEMA_VERSION = 1;
-
-/**
- * Write a spawn-plan file at `.gsd-t/spawns/{spawnId}.json` using an atomic
- * temp-file + rename. Creates the `.gsd-t/spawns/` directory and its
- * `.gitkeep` sentinel if missing.
- *
- * If `tasks` or `domains` are not explicitly supplied, the writer tries
- * to derive them from `.gsd-t/partition.md` + `.gsd-t/domains/*\/tasks.md`
- * via the companion `spawn-plan-derive.cjs` module. When derivation fails
- * (no partition file, malformed tasks.md, ENOENT), the writer falls back to
- * `{tasks: [], note: "no-partition"}` and STILL writes the file — the
- * observability panel's job is to render whatever is present; never to block.
- *
- * @param {object} opts
- * @param {string} opts.spawnId                       filesystem-safe id
- * @param {'unattended-worker'|'headless-detached'|'in-session-subagent'|'unattended-worker-sub'} opts.kind
- * @param {string} [opts.milestone]                   e.g. 'M44'
- * @param {string} [opts.wave]                        e.g. 'wave-3'
- * @param {string[]} [opts.domains]                   domain names involved
- * @param {Array<{id: string, title: string, status?: string}>} [opts.tasks]
- *                                                    explicit task list
- *                                                    (bypasses derivation)
- * @param {string} [opts.projectDir='.']
- * @param {Date}   [opts.now]                         injection for tests
- * @returns {string}                                  absolute path written
- */
-function writeSpawnPlan(opts) {
-  if (!opts || typeof opts !== 'object') {
-    throw new Error('writeSpawnPlan: opts is required');
-  }
-  const spawnId = _sanitizeSpawnId(opts.spawnId);
-  if (!spawnId) {
-    throw new Error('writeSpawnPlan: spawnId is required and must be filesystem-safe');
-  }
-  const kind = opts.kind || 'in-session-subagent';
-  const projectDir = opts.projectDir || '.';
-  const now = opts.now instanceof Date ? opts.now : new Date();
-
-  const spawnsDir = path.join(projectDir, SPAWNS_SUBDIR);
-  _ensureDir(spawnsDir);
-  _ensureGitkeep(spawnsDir);
-
-  // Derive or accept explicit plan slice. Explicit wins.
-  let plan = _buildPlanSkeleton({ spawnId, kind, now });
-  plan.milestone = opts.milestone || null;
-  plan.wave = opts.wave || null;
-  plan.domains = Array.isArray(opts.domains) ? opts.domains.slice() : [];
-  plan.tasks = Array.isArray(opts.tasks)
-    ? opts.tasks.map(_normalizeTask)
-    : [];
-
-  // Only auto-derive when caller did NOT explicitly supply tasks. A caller
-  // can pass `tasks: []` to bypass derivation too.
-  if (!Array.isArray(opts.tasks)) {
-    try {
-      const derive = require('./spawn-plan-derive.cjs');
-      const derived = derive.derivePlanFromPartition({
-        projectDir,
-        milestone: opts.milestone,
-        currentIter: opts.currentIter,
-      });
-      if (derived && typeof derived === 'object') {
-        if (!plan.milestone && derived.milestone) plan.milestone = derived.milestone;
-        if (!plan.wave && derived.wave) plan.wave = derived.wave;
-        if (!plan.domains.length && Array.isArray(derived.domains)) plan.domains = derived.domains.slice();
-        if (Array.isArray(derived.tasks)) plan.tasks = derived.tasks.map(_normalizeTask);
-      }
-    } catch (err) {
-      // Derivation failures NEVER block the spawn. The plan file still
-      // gets written with `{tasks: [], note: "no-partition"}` shape.
-      plan.note = 'no-partition';
-      try { process.stderr.write(`[spawn-plan-writer] derive failed (continuing): ${err && err.message || err}\n`); } catch (_) { /* silent */ }
-    }
-  }
-
-  // Mark first incomplete task as in_progress if every predecessor is done.
-  // Only one task per spawn may be in_progress at a time (see constraints §Format rules).
-  _applyInProgressHint(plan.tasks);
-
-  const targetPath = path.join(spawnsDir, spawnId + '.json');
-  const absTarget = path.resolve(targetPath);
-  _atomicWriteJson(absTarget, plan);
-  return absTarget;
-}
-
-/**
- * Return the `.gsd-t/spawns/` directory for the given project.
- */
-function spawnsDirFor(projectDir) {
-  return path.join(projectDir || '.', SPAWNS_SUBDIR);
-}
-
-// ── Internal helpers ────────────────────────────────────────────────────────
-
-function _sanitizeSpawnId(id) {
-  if (id == null) return null;
-  const s = String(id);
-  // Filesystem-safe: alphanumerics, dash, underscore, dot. See constraints.md §Format rules.
-  if (!/^[A-Za-z0-9._-]{1,200}$/.test(s)) return null;
-  return s;
-}
-
-function _ensureDir(d) {
-  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-}
-
-function _ensureGitkeep(dir) {
-  const gk = path.join(dir, '.gitkeep');
-  if (!fs.existsSync(gk)) {
-    try { fs.writeFileSync(gk, ''); } catch (_) { /* best-effort */ }
-  }
-}
-
-function _buildPlanSkeleton({ spawnId, kind, now }) {
-  return {
-    schemaVersion: SPAWN_PLAN_SCHEMA_VERSION,
-    spawnId,
-    kind,
-    startedAt: now.toISOString(),
-    endedAt: null,
-    milestone: null,
-    wave: null,
-    domains: [],
-    tasks: [],
-    endedReason: null,
-  };
-}
-
-function _normalizeTask(t) {
-  if (!t || typeof t !== 'object') return null;
-  const id = typeof t.id === 'string' ? t.id : null;
-  const title = typeof t.title === 'string' ? t.title : '';
-  const statusIn = typeof t.status === 'string' ? t.status : 'pending';
-  const status = ['pending', 'in_progress', 'done'].includes(statusIn) ? statusIn : 'pending';
-  const normalized = {
-    id,
-    title,
-    status,
-  };
-  if (typeof t.commit === 'string' && t.commit) normalized.commit = t.commit;
-  if (t.tokens && typeof t.tokens === 'object') {
-    normalized.tokens = t.tokens;
-  } else {
-    normalized.tokens = null;
-  }
-  return normalized;
-}
-
-function _applyInProgressHint(tasks) {
-  if (!Array.isArray(tasks) || tasks.length === 0) return;
-  // Already an in_progress? Leave as-is.
-  if (tasks.some((t) => t && t.status === 'in_progress')) return;
-  for (const t of tasks) {
-    if (!t) continue;
-    if (t.status === 'pending') { t.status = 'in_progress'; return; }
-    // Skip already-done; continue to next.
-  }
-}
-
-function _atomicWriteJson(targetPath, obj) {
-  const tmp = targetPath + '.tmp-' + process.pid + '-' + Date.now();
-  const json = JSON.stringify(obj, null, 2) + '\n';
-  fs.writeFileSync(tmp, json);
-  fs.renameSync(tmp, targetPath);
-}
-
-module.exports = {
-  writeSpawnPlan,
-  spawnsDirFor,
-  SPAWN_PLAN_SCHEMA_VERSION,
-  // Exposed for unit-test reach-in only; not part of the public contract.
-  _sanitizeSpawnId,
-  _normalizeTask,
-  _applyInProgressHint,
-  _atomicWriteJson,
-};

package/bin/supervisor-pid-fingerprint.cjs

@@ -1,126 +0,0 @@
-/**
- * Supervisor PID fingerprint.
- *
- * The supervisor.pid file is written as JSON `{pid, projectDir, startedAt}`
- * so that resume-time liveness checks can distinguish "our supervisor is
- * running" from "some other process recycled this PID."
- *
- * Backward-compat: if the file parses as a bare integer (legacy format),
- * treat it as `{pid, projectDir: null, startedAt: null, form: "legacy"}`
- * and let callers decide whether to trust it.
- */
-"use strict";
-
-const fs = require("node:fs");
-const path = require("node:path");
-const { execSync } = require("node:child_process");
-
-const PID_REL = path.join(".gsd-t", ".unattended", "supervisor.pid");
-
-function pidPathFor(projectDir) {
-  return path.join(path.resolve(projectDir), PID_REL);
-}
-
-function writePidFile(projectDir, pid) {
-  if (!projectDir || typeof projectDir !== "string") {
-    throw new Error("writePidFile: projectDir required");
-  }
-  if (!Number.isInteger(pid) || pid <= 0) {
-    throw new Error(`writePidFile: invalid pid ${pid}`);
-  }
-  const entry = {
-    pid,
-    projectDir: path.resolve(projectDir),
-    startedAt: new Date().toISOString(),
-  };
-  const p = pidPathFor(projectDir);
-  fs.mkdirSync(path.dirname(p), { recursive: true });
-  fs.writeFileSync(p, JSON.stringify(entry) + "\n", "utf8");
-  return entry;
-}
-
-function readPidFile(projectDir) {
-  const p = pidPathFor(projectDir);
-  if (!fs.existsSync(p)) return null;
-  const raw = fs.readFileSync(p, "utf8").trim();
-  if (!raw) return null;
-
-  // Try JSON form first.
-  if (raw.startsWith("{")) {
-    try {
-      const obj = JSON.parse(raw);
-      if (obj && Number.isInteger(obj.pid)) {
-        return {
-          pid: obj.pid,
-          projectDir: obj.projectDir || null,
-          startedAt: obj.startedAt || null,
-          form: "json",
-        };
-      }
-    } catch {
-      // fall through to legacy attempt
-    }
-  }
-
-  // Legacy bare-integer form.
-  const n = Number.parseInt(raw, 10);
-  if (Number.isInteger(n) && n > 0) {
-    return { pid: n, projectDir: null, startedAt: null, form: "legacy" };
-  }
-  return null;
-}
-
-/**
- * verifyFingerprint(entry, projectDir, opts?)
- *
- * Returns { ok, reason, command? }:
- *   ok: true   → entry matches this project AND ps confirms gsd-t command line
- *   ok: false  → mismatch (see reason)
- *   ok: null   → inconclusive (legacy entry, can't verify)
- *
- * reason values when ok=false:
- *   "project_mismatch"   — entry.projectDir !== resolved projectDir
- *   "process_not_found"  — ps -p returned nothing
- *   "command_not_gsd_t"  — ps succeeded but command line doesn't match /gsd-t|unattended/i
- *   "ps_failed"          — ps threw (couldn't introspect)
- *
- * opts._execSync — injection point for tests
- */
-function verifyFingerprint(entry, projectDir, opts = {}) {
-  if (!entry || typeof entry !== "object") {
-    return { ok: false, reason: "no_entry" };
-  }
-  if (entry.form === "legacy" || !entry.projectDir) {
-    return { ok: null, reason: "legacy_fingerprint" };
-  }
-  const resolved = path.resolve(projectDir);
-  if (entry.projectDir !== resolved) {
-    return { ok: false, reason: "project_mismatch" };
-  }
-
-  const exec = opts._execSync || execSync;
-  let cmd;
-  try {
-    const out = exec(`ps -p ${entry.pid} -o command=`, {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    });
-    cmd = (out || "").trim();
-  } catch {
-    return { ok: false, reason: "ps_failed" };
-  }
-  if (!cmd) {
-    return { ok: false, reason: "process_not_found" };
-  }
-  if (!/gsd-t|unattended/i.test(cmd)) {
-    return { ok: false, reason: "command_not_gsd_t", command: cmd };
-  }
-  return { ok: true, reason: "verified", command: cmd };
-}
-
-module.exports = {
-  pidPathFor,
-  writePidFile,
-  readPidFile,
-  verifyFingerprint,
-};

package/bin/token-budget.cjs

@@ -1,265 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * GSD-T Token Budget — Session-level token tracking (single-band, v3.12)
- *
- * Reads .gsd-t/.context-meter-state.json (M34) for context-window readings
- * and returns a single-band status signal (normal / threshold) that the
- * orchestrator uses to decide whether the next subagent spawn must go
- * through autoSpawnHeadless().
- *
- * v3.12.0 (M38 — meter reduction):
- *   - Collapsed three-band model (normal/warn/stop) to single-band
- *     (normal/threshold). The orchestrator makes the routing decision;
- *     the meter reports a band, not a degradation policy.
- *   - `getDegradationActions` export removed.
- *   - Dead-meter detection, `stale` band, and `deadReason` removed.
- *     Stale state transparently falls through to the heuristic — the
- *     fail-open hook never raised a user-visible alarm anyway, and the
- *     orchestrator's headless-by-default posture handles overflow
- *     structurally rather than by trying to instruct Claude mid-session.
- *   - Threshold default is `thresholdPct` from context-meter-config.json
- *     (default 75%). There is no intermediate warn band.
- *
- * Zero external dependencies (Node.js built-ins only).
- */
-
-const fs = require("fs");
-const path = require("path");
-const { SAFE_DEFAULT_WINDOW } = require("./model-windows.cjs");
-
-// ── Constants ────────────────────────────────────────────────────────────────
-
-const MODEL_RATIOS = { haiku: 1, sonnet: 5, opus: 25 };
-
-// Fallback context window when no per-model signal is available. Uses the
-// model-windows safe LARGE default (1M) rather than a bare 200K literal: a
-// too-small fallback re-introduces the premature-headless-handoff bug the
-// model-aware sizing was added to fix. See bin/model-windows.cjs.
-const FALLBACK_WINDOW = SAFE_DEFAULT_WINDOW;
-
-// Base token estimates per task type (in haiku-equivalent units)
-const BASE_ESTIMATES = {
-  execute: 8000,
-  qa: 5000,
-  "red-team": 10000,
-  "doc-ripple": 3000,
-  plan: 4000,
-  integrate: 6000,
-  verify: 5000,
-  default: 6000,
-};
-
-// v3.12 single-band default. Overridable via context-meter-config.json.
-const DEFAULT_THRESHOLD_PCT = 75;
-
-// ── Exports ──────────────────────────────────────────────────────────────────
-
-module.exports = {
-  estimateCost,
-  getSessionStatus,
-  recordUsage,
-  estimateMilestoneCost,
-  getModelCostRatios,
-};
-
-// ── getModelCostRatios ────────────────────────────────────────────────────────
-
-/** @returns {{ haiku: 1, sonnet: 5, opus: 25 }} */
-function getModelCostRatios() {
-  return { ...MODEL_RATIOS };
-}
-
-// ── estimateCost ──────────────────────────────────────────────────────────────
-
-/**
- * @param {string} model - 'haiku' | 'sonnet' | 'opus'
- * @param {string} taskType - 'execute' | 'qa' | 'red-team' | etc.
- * @param {{ complexity?: number, historicalAvg?: number, projectDir?: string }} [options]
- * @returns {number} estimated tokens
- */
-function estimateCost(model, taskType, options) {
-  const o = options || {};
-  const ratio = MODEL_RATIOS[model] || MODEL_RATIOS.sonnet;
-  if (o.historicalAvg) return Math.round(o.historicalAvg * ratio);
-  const hist = getHistoricalAvg(model, taskType, o.projectDir);
-  if (hist) return Math.round(hist);
-  const base = BASE_ESTIMATES[taskType] || BASE_ESTIMATES.default;
-  const complexity = o.complexity || 1.0;
-  return Math.round(base * ratio * complexity);
-}
-
-// ── getSessionStatus ─────────────────────────────────────────────────────────
-
-const STATE_FILE_REL = path.join(".gsd-t", ".context-meter-state.json");
-const CONFIG_FILE_REL = path.join(".gsd-t", "context-meter-config.json");
-const STATE_STALE_MS = 5 * 60 * 1000;
-
-/**
- * @param {string} [projectDir]
- * @returns {{ consumed: number, estimated_remaining: number, pct: number, threshold: 'normal'|'threshold' }}
- *
- * v3.12 (M38): reads `.gsd-t/.context-meter-state.json` produced by the
- * Context Meter PostToolUse hook. When the state file is fresh (timestamp
- * within 5 minutes), real `input_tokens` drive the response. Otherwise we
- * fall back to a historical heuristic from `.gsd-t/token-log.md`. Stale or
- * missing state is not a distinct band — the fail-open hook never raised
- * a user-visible alarm, and the orchestrator's headless-by-default spawn
- * path handles overflow structurally.
- */
-function getSessionStatus(projectDir) {
-  const dir = projectDir || process.cwd();
-  const thresholdPct = resolveThresholdPct(dir);
-  const real = readContextMeterState(dir);
-  if (real) {
-    const consumed = real.inputTokens;
-    // Primary: the Context Meter writes a model-aware modelWindowSize into
-    // state (bin/model-windows.cjs). Fallback only when state predates that.
-    const window = real.modelWindowSize > 0 ? real.modelWindowSize : FALLBACK_WINDOW;
-    const estimated_remaining = Math.max(0, window - consumed);
-    const pct = Math.round(real.pct * 10) / 10;
-    const threshold = bandFor(pct, thresholdPct);
-    return { consumed, estimated_remaining, pct, threshold };
-  }
-  return getSessionStatusHeuristic(dir, thresholdPct);
-}
-
-function readContextMeterState(dir) {
-  try {
-    const fp = path.join(dir, STATE_FILE_REL);
-    const raw = fs.readFileSync(fp, "utf8");
-    const s = JSON.parse(raw);
-    if (!s || typeof s.inputTokens !== "number" || typeof s.pct !== "number") return null;
-    if (!s.timestamp) return null;
-    const age = Date.now() - Date.parse(s.timestamp);
-    if (isNaN(age) || age > STATE_STALE_MS || age < 0) return null;
-    if (s.lastError && typeof s.lastError === "object") return null;
-    return s;
-  } catch (_) {
-    return null;
-  }
-}
-
-function resolveThresholdPct(dir) {
-  try {
-    const fp = path.join(dir, CONFIG_FILE_REL);
-    const raw = fs.readFileSync(fp, "utf8");
-    const c = JSON.parse(raw);
-    const pct = Number(c.thresholdPct);
-    if (Number.isFinite(pct) && pct > 0 && pct < 100) return pct;
-  } catch (_) {
-    /* fall through */
-  }
-  return DEFAULT_THRESHOLD_PCT;
-}
-
-function getSessionStatusHeuristic(dir, thresholdPct) {
-  const window = FALLBACK_WINDOW;
-  const consumed = readSessionConsumed(dir);
-  const estimated_remaining = Math.max(0, window - consumed);
-  const pct = window > 0 ? Math.round((consumed / window) * 100 * 10) / 10 : 0;
-  const threshold = bandFor(pct, thresholdPct);
-  return { consumed, estimated_remaining, pct, threshold };
-}
-
-// ── recordUsage ──────────────────────────────────────────────────────────────
-
-/**
- * @param {{ model: string, taskType: string, tokens: number, duration_s: number, projectDir?: string }} usage
- */
-function recordUsage(usage) {
-  const dir = usage.projectDir || process.cwd();
-  const fp = tokenLogPath(dir);
-  ensureDir(path.dirname(fp));
-  const now = fmtDate(new Date());
-  const line = `| ${now} | ${now} | token-budget | record | ${usage.model} | ${usage.duration_s}s | recorded | ${usage.tokens} | null | | ${usage.taskType} | N/A |\n`;
-  if (!fs.existsSync(fp)) {
-    const header = "| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tokens | Compacted | Domain | Task | Ctx% |\n|----------------|--------------|---------|------|-------|-------------|-------|--------|-----------|--------|------|---------|\n";
-    fs.writeFileSync(fp, header);
-  }
-  fs.appendFileSync(fp, line);
-}
-
-// ── estimateMilestoneCost ─────────────────────────────────────────────────────
-
-/**
- * @param {object[]} remainingTasks - [{ model, taskType, complexity }]
- * @param {string} [projectDir]
- * @returns {{ estimatedTokens: number, estimatedPct: number, feasible: boolean }}
- */
-function estimateMilestoneCost(remainingTasks, projectDir) {
-  const status = getSessionStatus(projectDir);
-  const window = status.consumed + status.estimated_remaining || FALLBACK_WINDOW;
-  const estimatedTokens = remainingTasks.reduce((sum, t) => {
-    return sum + estimateCost(t.model, t.taskType, { complexity: t.complexity, projectDir });
-  }, 0);
-  const estimatedPct = window > 0 ? Math.min(100, Math.round((estimatedTokens / window) * 100 * 10) / 10) : 0;
-  const feasible = estimatedTokens <= status.estimated_remaining;
-  return { estimatedTokens, estimatedPct, feasible };
-}
-
-// ── Internal: single-band resolution ─────────────────────────────────────────
-
-function bandFor(pct, thresholdPct) {
-  if (!Number.isFinite(pct)) return "normal";
-  return pct >= thresholdPct ? "threshold" : "normal";
-}
-
-// ── Internal: token-log parsing ───────────────────────────────────────────────
-
-function readSessionConsumed(projectDir) {
-  const fp = tokenLogPath(projectDir || process.cwd());
-  if (!fs.existsSync(fp)) return 0;
-  const today = fmtDate(new Date()).slice(0, 10); // YYYY-MM-DD
-  const lines = fs.readFileSync(fp, "utf8").split("\n");
-  let total = 0;
-  for (const line of lines) {
-    if (!line.startsWith("|")) continue;
-    const cols = parseRow(line);
-    if (cols.length < 8) continue;
-    const dtStart = (cols[0] || "").trim();
-    if (!dtStart.startsWith(today)) continue;
-    const tokens = parseInt(cols[7], 10);
-    if (!isNaN(tokens) && tokens > 0) total += tokens;
-  }
-  return total;
-}
-
-function getHistoricalAvg(model, taskType, projectDir) {
-  const fp = tokenLogPath(projectDir || process.cwd());
-  if (!fs.existsSync(fp)) return null;
-  const lines = fs.readFileSync(fp, "utf8").split("\n");
-  const matches = [];
-  for (const line of lines) {
-    if (!line.startsWith("|")) continue;
-    const cols = parseRow(line);
-    if (cols.length < 8) continue;
-    const rowModel = (cols[4] || "").trim();
-    const rowTask = (cols[10] || (cols[3] || "")).trim();
-    const tokens = parseInt(cols[7], 10);
-    if (rowModel === model && rowTask === taskType && !isNaN(tokens) && tokens > 0) {
-      matches.push(tokens);
-    }
-  }
-  if (matches.length === 0) return null;
-  return matches.reduce((s, v) => s + v, 0) / matches.length;
-}
-
-function parseRow(line) {
-  return line.split("|").slice(1, -1);
-}
-
-// ── Internal: helpers ────────────────────────────────────────────────────────
-
-function tokenLogPath(dir) {
-  return path.join(dir, ".gsd-t", "token-log.md");
-}
-
-function ensureDir(d) {
-  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-}
-
-function fmtDate(d) {
-  const pad = (n) => String(n).padStart(2, "0");
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
-}