@tekyzinc/gsd-t 3.29.11 → 4.0.14

package/bin/gsd-t-transcript-tee.cjs

@@ -1,246 +0,0 @@
-'use strict';
-/**
- * GSD-T Transcript Tee (M42 D1)
- *
- * Captures raw stream-json frames from every unattended spawn to
- * `.gsd-t/transcripts/{spawn-id}.ndjson` + maintains a registry at
- * `.gsd-t/transcripts/.index.json` used by the dashboard sidebar.
- *
- * Zero external deps. Append-only. Does not parse the frames — that's the
- * renderer's job. One frame per line; lines that fail JSON parse are still
- * tee'd so nothing is silently dropped.
- *
- * Contracts:
- *   - .gsd-t/contracts/stream-json-sink-contract.md v1.1.0 (frame shape)
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-const TRANSCRIPTS_DIRNAME = path.join('.gsd-t', 'transcripts');
-const INDEX_FILENAME = '.index.json';
-
-function _transcriptsDir(projectDir) {
-  return path.join(projectDir || '.', TRANSCRIPTS_DIRNAME);
-}
-
-function _indexPath(projectDir) {
-  return path.join(_transcriptsDir(projectDir), INDEX_FILENAME);
-}
-
-function _ensureDir(p) {
-  if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
-}
-
-/**
- * Allocate a hierarchical spawn-id. Shape: `{parent-prefix}-{short}` where
- * `short` is an 8-char hex from a random UUID. Root spawns get no prefix.
- *
- * @param {object} [opts]
- * @param {string|null} [opts.parentId]
- * @returns {string}
- */
-function allocateSpawnId(opts) {
-  const parentId = opts && opts.parentId ? String(opts.parentId) : null;
-  const short = crypto.randomBytes(4).toString('hex');
-  return parentId ? `${parentId}.${short}` : `s-${short}`;
-}
-
-function _readIndex(projectDir) {
-  const p = _indexPath(projectDir);
-  if (!fs.existsSync(p)) return { spawns: [] };
-  try {
-    const raw = fs.readFileSync(p, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.spawns)) return { spawns: [] };
-    return parsed;
-  } catch (_) {
-    return { spawns: [] };
-  }
-}
-
-function _writeIndex(projectDir, idx) {
-  const p = _indexPath(projectDir);
-  _ensureDir(path.dirname(p));
-  const tmp = p + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(idx, null, 2));
-  fs.renameSync(tmp, p);
-}
-
-/**
- * Register a new transcript + create the ndjson file.
- *
- * @param {object} opts
- * @param {string} opts.spawnId
- * @param {string} [opts.projectDir='.']
- * @param {object} [opts.meta]           { parentId?, command?, description?, workerPid?, model? }
- * @returns {{spawnId, transcriptPath, startedAt}}
- */
-function openTranscript(opts) {
-  if (!opts || !opts.spawnId) throw new Error('openTranscript: spawnId required');
-  const projectDir = opts.projectDir || '.';
-  const meta = opts.meta || {};
-  const dir = _transcriptsDir(projectDir);
-  _ensureDir(dir);
-
-  const transcriptPath = path.join(dir, `${opts.spawnId}.ndjson`);
-  if (!fs.existsSync(transcriptPath)) {
-    fs.writeFileSync(transcriptPath, '');
-  }
-
-  const startedAt = new Date().toISOString();
-  const entry = {
-    spawnId: opts.spawnId,
-    parentId: meta.parentId || null,
-    command: meta.command || null,
-    description: meta.description || null,
-    model: meta.model || null,
-    workerPid: meta.workerPid || null,
-    startedAt,
-    endedAt: null,
-    status: 'running',
-  };
-
-  const idx = _readIndex(projectDir);
-  const existing = idx.spawns.findIndex((s) => s.spawnId === opts.spawnId);
-  if (existing >= 0) {
-    idx.spawns[existing] = { ...idx.spawns[existing], ...entry };
-  } else {
-    idx.spawns.push(entry);
-  }
-  _writeIndex(projectDir, idx);
-
-  return { spawnId: opts.spawnId, transcriptPath, startedAt };
-}
-
-/**
- * Append a single frame (already JSON-serializable) to the transcript.
- * `frame` may be a parsed object OR a raw string line — strings are wrapped
- * as `{type:"raw",line}` so the ndjson shape stays uniform.
- *
- * @param {object} opts
- * @param {string} opts.spawnId
- * @param {string} [opts.projectDir='.']
- * @param {object|string} opts.frame
- */
-function appendFrame(opts) {
-  if (!opts || !opts.spawnId) throw new Error('appendFrame: spawnId required');
-  if (opts.frame === undefined || opts.frame === null) return;
-  const projectDir = opts.projectDir || '.';
-  const p = path.join(_transcriptsDir(projectDir), `${opts.spawnId}.ndjson`);
-  _ensureDir(path.dirname(p));
-
-  let line;
-  if (typeof opts.frame === 'string') {
-    const trimmed = opts.frame.trim();
-    if (!trimmed) return;
-    try {
-      JSON.parse(trimmed);
-      line = trimmed;
-    } catch (_) {
-      line = JSON.stringify({ type: 'raw', line: opts.frame });
-    }
-  } else {
-    try {
-      line = JSON.stringify(opts.frame);
-    } catch (_) {
-      line = JSON.stringify({ type: 'raw', line: String(opts.frame) });
-    }
-  }
-  fs.appendFileSync(p, line + '\n');
-}
-
-/**
- * Mark a transcript as ended. Idempotent — subsequent calls update endedAt.
- *
- * @param {object} opts
- * @param {string} opts.spawnId
- * @param {string} [opts.projectDir='.']
- * @param {'done'|'failed'|'stopped'|'ended'} [opts.status='ended']
- */
-function closeTranscript(opts) {
-  if (!opts || !opts.spawnId) throw new Error('closeTranscript: spawnId required');
-  const projectDir = opts.projectDir || '.';
-  const idx = _readIndex(projectDir);
-  const i = idx.spawns.findIndex((s) => s.spawnId === opts.spawnId);
-  if (i < 0) return false;
-  idx.spawns[i].endedAt = new Date().toISOString();
-  idx.spawns[i].status = opts.status || 'ended';
-  _writeIndex(projectDir, idx);
-  return true;
-}
-
-/**
- * List registered spawns (most recent first).
- *
- * @param {string} [projectDir='.']
- * @returns {Array<object>}
- */
-function listTranscripts(projectDir) {
-  const idx = _readIndex(projectDir || '.');
-  return idx.spawns.slice().sort((a, b) => {
-    const ta = Date.parse(a.startedAt) || 0;
-    const tb = Date.parse(b.startedAt) || 0;
-    return tb - ta;
-  });
-}
-
-function readTranscriptMeta(projectDir, spawnId) {
-  const idx = _readIndex(projectDir || '.');
-  return idx.spawns.find((s) => s.spawnId === spawnId) || null;
-}
-
-/**
- * Tee a stream-json stdout stream. Returns an `onChunk(buffer)` callback that
- * you feed chunks to (typed as Buffer or string). Frames are split at `\n`
- * and each complete line is written to the transcript ndjson. Incomplete
- * tails are buffered until the next chunk.
- *
- * Returns also a `flush()` to call on child exit — writes any stranded tail
- * as a single `{type:"raw"}` line so nothing is dropped.
- *
- * @param {object} opts
- * @param {string} opts.spawnId
- * @param {string} [opts.projectDir='.']
- * @returns {{onChunk: (chunk) => void, flush: () => void}}
- */
-function makeStreamTee(opts) {
-  if (!opts || !opts.spawnId) throw new Error('makeStreamTee: spawnId required');
-  const projectDir = opts.projectDir || '.';
-  const spawnId = opts.spawnId;
-  let buf = '';
-
-  return {
-    onChunk(chunk) {
-      if (chunk == null) return;
-      buf += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
-      let nl;
-      while ((nl = buf.indexOf('\n')) >= 0) {
-        const line = buf.slice(0, nl);
-        buf = buf.slice(nl + 1);
-        if (line.length > 0) appendFrame({ spawnId, projectDir, frame: line });
-      }
-    },
-    flush() {
-      if (buf.length > 0) {
-        appendFrame({ spawnId, projectDir, frame: buf });
-        buf = '';
-      }
-    },
-  };
-}
-
-module.exports = {
-  allocateSpawnId,
-  openTranscript,
-  appendFrame,
-  closeTranscript,
-  listTranscripts,
-  readTranscriptMeta,
-  makeStreamTee,
-  _readIndex,
-  _writeIndex,
-  TRANSCRIPTS_DIRNAME,
-  INDEX_FILENAME,
-};

package/bin/gsd-t-unattended-heartbeat.cjs

@@ -1,188 +0,0 @@
-/**
- * gsd-t-unattended-heartbeat.cjs
- *
- * Liveness heartbeat watchdog for the unattended supervisor.
- *
- * Supersedes the pre-M43 `workerTimeoutMs` wall-clock guillotine as the
- * PRIMARY stuck-worker detector. The guillotine remains as an absolute
- * backstop (raised to 1 hour by default) for pathological cases where a
- * child never writes a single event.
- *
- * How it works
- * ────────────
- * The supervisor polls `.gsd-t/events/YYYY-MM-DD.jsonl` mtime every 60 s
- * during a worker iteration. If the mtime has not advanced for at least
- * `staleHeartbeatMs` (default 300_000 = 5 min), the worker is considered
- * stuck and SIGTERM'd. Healthy workers producing events run indefinitely
- * under the 1-hour absolute cap.
- *
- * This module is pure and side-effect-free by default. `checkHeartbeat()`
- * accepts injected `now` and `fsShim` so the entire watchdog can be
- * unit-tested with a fake clock and fake filesystem.
- *
- * Zero external dependencies — Node built-ins only.
- *
- * Contract: .gsd-t/contracts/unattended-supervisor-contract.md v1.1.0
- *   §"Heartbeat Watchdog"
- */
-
-"use strict";
-
-const fs = require("node:fs");
-const path = require("node:path");
-
-/**
- * Build the events JSONL path for a given date.
- *
- * @param {string} projectDir
- * @param {Date|number} when  Date, or ms since epoch. Defaults to now when
- *   omitted at the call site.
- * @returns {string}
- */
-function eventsPathFor(projectDir, when) {
-  const d = when instanceof Date ? when : new Date(when || Date.now());
-  const y = d.getUTCFullYear();
-  const m = String(d.getUTCMonth() + 1).padStart(2, "0");
-  const day = String(d.getUTCDate()).padStart(2, "0");
-  return path.join(projectDir, ".gsd-t", "events", `${y}-${m}-${day}.jsonl`);
-}
-
-/**
- * Check whether the worker's event stream is stale.
- *
- * A worker is "stale" when the relevant events JSONL file's mtime has not
- * advanced within `staleHeartbeatMs` of the given `now`. The relevant file
- * is the one matching the date of `now` — if the loop crosses a UTC day
- * boundary mid-iteration, the new day's file is checked.
- *
- * Fresh worker grace: if the events file does not exist yet AND
- * `(now - workerStartedAt) < staleHeartbeatMs`, the worker is considered
- * healthy (still booting). After the grace window with no file, the worker
- * is stale.
- *
- * @param {object} params
- * @param {string} params.projectDir
- * @param {number} params.workerStartedAt  ms since epoch
- * @param {number} params.staleHeartbeatMs
- * @param {number} [params.now]            ms since epoch (defaults to Date.now())
- * @param {object} [params.fsShim]         { existsSync, statSync } — test hook
- * @returns {{stale: boolean, reason: string, lastEventMs: (number|null), ageMs: (number|null), eventsPath: string}}
- */
-function checkHeartbeat({
-  projectDir,
-  workerStartedAt,
-  staleHeartbeatMs,
-  now,
-  fsShim,
-}) {
-  if (typeof projectDir !== "string" || projectDir.length === 0) {
-    throw new Error("checkHeartbeat: projectDir is required");
-  }
-  if (typeof workerStartedAt !== "number" || !Number.isFinite(workerStartedAt)) {
-    throw new Error("checkHeartbeat: workerStartedAt must be a finite number");
-  }
-  if (
-    typeof staleHeartbeatMs !== "number" ||
-    !Number.isFinite(staleHeartbeatMs) ||
-    staleHeartbeatMs <= 0
-  ) {
-    throw new Error("checkHeartbeat: staleHeartbeatMs must be a positive number");
-  }
-  const nowMs = typeof now === "number" ? now : Date.now();
-  const shim = fsShim || fs;
-
-  const eventsPath = eventsPathFor(projectDir, nowMs);
-
-  let exists = false;
-  try {
-    exists = !!shim.existsSync(eventsPath);
-  } catch (_) {
-    exists = false;
-  }
-
-  if (!exists) {
-    const sinceStart = nowMs - workerStartedAt;
-    if (sinceStart < staleHeartbeatMs) {
-      return {
-        stale: false,
-        reason: `events file not yet created (grace: ${sinceStart}ms < ${staleHeartbeatMs}ms)`,
-        lastEventMs: null,
-        ageMs: null,
-        eventsPath,
-      };
-    }
-    return {
-      stale: true,
-      reason: `events file ${eventsPath} absent for ${sinceStart}ms since worker start (threshold ${staleHeartbeatMs}ms)`,
-      lastEventMs: null,
-      ageMs: sinceStart,
-      eventsPath,
-    };
-  }
-
-  let stat;
-  try {
-    stat = shim.statSync(eventsPath);
-  } catch (err) {
-    // File existed at existsSync but stat failed — treat as stale only if
-    // we are past the grace window. Under the grace window, assume transient.
-    const sinceStart = nowMs - workerStartedAt;
-    if (sinceStart < staleHeartbeatMs) {
-      return {
-        stale: false,
-        reason: `events stat transient failure (grace): ${err.message}`,
-        lastEventMs: null,
-        ageMs: null,
-        eventsPath,
-      };
-    }
-    return {
-      stale: true,
-      reason: `events stat failed past grace: ${err.message}`,
-      lastEventMs: null,
-      ageMs: sinceStart,
-      eventsPath,
-    };
-  }
-
-  const mtimeMs =
-    typeof stat.mtimeMs === "number"
-      ? stat.mtimeMs
-      : stat.mtime instanceof Date
-        ? stat.mtime.getTime()
-        : 0;
-
-  // Reference point for staleness: max(mtime, workerStartedAt). This handles
-  // the bootstrap case where the events file already existed from a prior
-  // iteration — we don't want to kill the worker on its first 60s poll just
-  // because it hasn't emitted yet. The worker gets at least staleHeartbeatMs
-  // from its own start to produce the first event.
-  const ref = Math.max(mtimeMs, workerStartedAt);
-  const ageMs = nowMs - ref;
-
-  if (ageMs >= staleHeartbeatMs) {
-    return {
-      stale: true,
-      reason: `last event ${ageMs}ms ago (threshold ${staleHeartbeatMs}ms)`,
-      lastEventMs: mtimeMs,
-      ageMs,
-      eventsPath,
-    };
-  }
-  return {
-    stale: false,
-    reason: `fresh — last event ${ageMs}ms ago`,
-    lastEventMs: mtimeMs,
-    ageMs,
-    eventsPath,
-  };
-}
-
-module.exports = {
-  checkHeartbeat,
-  eventsPathFor,
-  // Default heartbeat poll cadence — exported so tests and the supervisor
-  // can reference a single source of truth.
-  DEFAULT_HEARTBEAT_POLL_MS: 60 * 1000,
-  DEFAULT_STALE_HEARTBEAT_MS: 5 * 60 * 1000,
-};