@tekyzinc/gsd-t 3.16.12 → 3.18.12

package/bin/gsd-t-file-disjointness.cjs

@@ -0,0 +1,227 @@
+"use strict";
+
+/**
+ * gsd-t-file-disjointness — M44 D5 (T2: core implementation)
+ *
+ * Pre-spawn file-disjointness prover. Consumes the task-graph DAG from D1 and
+ * partitions a candidate parallel set into:
+ *   - parallel   — groups confirmed pairwise-disjoint (safe to spawn together)
+ *   - sequential — groups sharing ≥1 write target (must serialize)
+ *   - unprovable — tasks with no touch-list source (routed sequential; safe-default)
+ *
+ * Contract: .gsd-t/contracts/file-disjointness-contract.md (v1.0.0)
+ *
+ * Hard rules (from constraints.md):
+ *   - Unprovable is ALWAYS safe — never assume disjointness
+ *   - Zero external runtime deps (Node built-ins + git subprocess only)
+ *   - Never throws (returns result object)
+ *   - Read-only on all domain files; only writes to .gsd-t/events/YYYY-MM-DD.jsonl
+ *   - D5 checks WRITE targets only; reads never conflict
+ *   - Mode-agnostic
+ *   - Git-history heuristic bounded to 100 commits
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { execSync } = require("node:child_process");
+
+// ─── Event writer (append-only JSONL) ────────────────────────────────────
+
+/**
+ * Append a disjointness_fallback event for a task moved to sequential
+ * (including unprovable tasks).
+ *
+ * Event shape (per T2 spec):
+ *   { type: 'disjointness_fallback', task_id, reason, ts }
+ *
+ * Best-effort: filesystem errors are swallowed so the prover never throws.
+ */
+function appendFallbackEvent(projectDir, taskId, reason) {
+  try {
+    const eventsDir = path.join(projectDir, ".gsd-t", "events");
+    fs.mkdirSync(eventsDir, { recursive: true });
+    const now = new Date();
+    const day = now.toISOString().slice(0, 10); // YYYY-MM-DD (UTC)
+    const file = path.join(eventsDir, `${day}.jsonl`);
+    const entry = {
+      type: "disjointness_fallback",
+      task_id: taskId,
+      reason,
+      ts: now.toISOString(),
+    };
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {
+    // Swallow — observability only; never block the caller.
+  }
+}
+
+// ─── Git-history fallback (bounded) ──────────────────────────────────────
+
+/**
+ * Heuristic touch-list source: scan up to the last 100 commits that touched
+ * the domain's directory and collect file paths from commits whose subject
+ * mentions the task id. Bounded to prevent runaway I/O on large repos.
+ *
+ * Returns: string[] — file paths (may be empty). Never throws.
+ */
+function gitHistoryTouches(projectDir, domain, taskId) {
+  if (!domain || !taskId) return [];
+  const domainDir = path.join(".gsd-t", "domains", domain);
+  let raw;
+  try {
+    raw = execSync(
+      `git log --name-only --pretty=format:"COMMIT:%H %s" -n 100 -- "${domainDir}"`,
+      { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+  } catch {
+    return [];
+  }
+  if (!raw) return [];
+
+  const files = new Set();
+  let capturing = false;
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.startsWith("COMMIT:")) {
+      // Subject is everything after the sha
+      const sp = line.indexOf(" ");
+      const subject = sp >= 0 ? line.slice(sp + 1) : "";
+      capturing = subject.includes(taskId);
+      continue;
+    }
+    if (!capturing) continue;
+    const trimmed = line.trim();
+    if (trimmed) files.add(trimmed);
+  }
+  return Array.from(files);
+}
+
+// ─── Touch-list resolution ───────────────────────────────────────────────
+
+/**
+ * Resolve the effective touch list for a task by applying the fallback chain:
+ *   1. Explicit `touches` populated by D1 (from **Touches** field or scope.md Files Owned)
+ *   2. Git-history heuristic — only when touches is [] (D1 couldn't find anything)
+ *
+ * Returns: { touches: string[], source: 'declared' | 'git' | 'none' }
+ */
+function resolveTouches(task, projectDir) {
+  const declared = Array.isArray(task.touches) ? task.touches : [];
+  if (declared.length > 0) {
+    return { touches: declared.slice(), source: "declared" };
+  }
+  // D1 emitted an empty list → scope.md was also empty. Try git history.
+  const fromGit = gitHistoryTouches(projectDir, task.domain, task.id);
+  if (fromGit.length > 0) {
+    return { touches: fromGit, source: "git" };
+  }
+  return { touches: [], source: "none" };
+}
+
+// ─── Overlap grouping (union-find over the overlap relation) ─────────────
+
+function haveOverlap(a, b) {
+  if (!a.length || !b.length) return false;
+  const set = new Set(a);
+  for (const f of b) {
+    if (set.has(f)) return true;
+  }
+  return false;
+}
+
+/**
+ * Group provable tasks (those with a non-empty touch list from any source)
+ * into connected components over the overlap relation. A singleton component
+ * with no overlapping partner is safe to parallelize; a component of size ≥ 2
+ * must be serialized.
+ */
+function groupByOverlap(items) {
+  // items: [{ task, touches }]
+  const n = items.length;
+  const parent = Array.from({ length: n }, (_, i) => i);
+  const find = (i) => {
+    while (parent[i] !== i) {
+      parent[i] = parent[parent[i]];
+      i = parent[i];
+    }
+    return i;
+  };
+  const union = (i, j) => {
+    const a = find(i), b = find(j);
+    if (a !== b) parent[a] = b;
+  };
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      if (haveOverlap(items[i].touches, items[j].touches)) union(i, j);
+    }
+  }
+  const groups = new Map();
+  for (let i = 0; i < n; i++) {
+    const root = find(i);
+    if (!groups.has(root)) groups.set(root, []);
+    groups.get(root).push(items[i].task);
+  }
+  return Array.from(groups.values());
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Prove pairwise file-disjointness across a candidate parallel set.
+ *
+ * @param {{tasks: object[], projectDir: string}} opts
+ * @returns {{parallel: object[][], sequential: object[][], unprovable: object[]}}
+ *
+ * Never throws. Appends a `disjointness_fallback` event to
+ * `.gsd-t/events/YYYY-MM-DD.jsonl` for every task routed sequential
+ * (including unprovable tasks).
+ */
+function proveDisjointness(opts) {
+  const tasks = (opts && Array.isArray(opts.tasks)) ? opts.tasks : [];
+  const projectDir = (opts && opts.projectDir) || process.cwd();
+
+  const parallel = [];
+  const sequential = [];
+  const unprovable = [];
+
+  if (tasks.length === 0) {
+    return { parallel, sequential, unprovable };
+  }
+
+  // Resolve each task's effective touch list.
+  const provable = []; // [{ task, touches }]
+  for (const t of tasks) {
+    const { touches, source } = resolveTouches(t, projectDir);
+    if (source === "none") {
+      unprovable.push(t);
+      // Unprovable → always sequential (singleton group). Safe-default.
+      sequential.push([t]);
+      appendFallbackEvent(projectDir, t.id, "unprovable");
+    } else {
+      provable.push({ task: t, touches });
+    }
+  }
+
+  // Group provable tasks by overlap. Singletons → parallel. Multi → sequential.
+  const groups = groupByOverlap(provable);
+  for (const group of groups) {
+    if (group.length === 1) {
+      parallel.push(group);
+    } else {
+      sequential.push(group);
+      for (const t of group) {
+        appendFallbackEvent(projectDir, t.id, "write-target-overlap");
+      }
+    }
+  }
+
+  return { parallel, sequential, unprovable };
+}
+
+module.exports = {
+  proveDisjointness,
+  // Internals exposed for unit tests:
+  _haveOverlap: haveOverlap,
+  _groupByOverlap: groupByOverlap,
+  _resolveTouches: resolveTouches,
+  _gitHistoryTouches: gitHistoryTouches,
+};

package/bin/gsd-t-in-session-usage.cjs

@@ -0,0 +1,213 @@
+'use strict';
+/**
+ * GSD-T In-Session Usage Capture (M43 D1)
+ *
+ * Writes one schema-v2 row per **assistant turn** of an interactive Claude Code
+ * session to `.gsd-t/metrics/token-usage.jsonl`, so the dialog channel is
+ * observable alongside the headless spawns M41 already covers.
+ *
+ * Branch B (transcript-sourced). Claude Code hook payloads (Stop / SessionEnd /
+ * PostToolUse) do not carry `usage`, but every payload contains
+ * `transcript_path` — the on-disk jsonl Claude Code appends assistant turns to.
+ * This module reads the transcript, extracts `message.usage` envelopes per
+ * assistant turn (keyed by `message.id` for dedup), and hands each new envelope
+ * to `recordSpawnRow` from `bin/gsd-t-token-capture.cjs` with
+ * `sessionType: 'in-session'`.
+ *
+ * Dedup state lives per `session_id` in `.gsd-t/.in-session-cursor.json` —
+ * tracks the last-seen `message.id` so repeated Stop fires within the same
+ * session only append new rows.
+ *
+ * Zero external deps. `.cjs` for ESM/CJS compat.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const capture = require('./gsd-t-token-capture.cjs');
+
+const CURSOR_REL = path.join('.gsd-t', '.in-session-cursor.json');
+
+// ── Cursor state ─────────────────────────────────────────────────────
+
+function _loadCursor(projectDir) {
+  const p = path.join(projectDir, CURSOR_REL);
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function _saveCursor(projectDir, state) {
+  const p = path.join(projectDir, CURSOR_REL);
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(state, null, 2));
+}
+
+// ── Transcript parsing ───────────────────────────────────────────────
+
+function _parseJsonLineSafe(line) {
+  const s = String(line || '').trim();
+  if (!s || s[0] !== '{') return null;
+  try { return JSON.parse(s); } catch (_) { return null; }
+}
+
+/**
+ * Walk a Claude Code transcript jsonl and return assistant-turn usage entries.
+ *
+ * Each returned entry: { messageId, model, usage, timestamp, turnIndex }
+ * - `messageId` from `message.id` (stable per assistant turn)
+ * - `model` from `message.model`
+ * - `usage` from `message.usage` (the full envelope — schema lines up with
+ *   Anthropic API usage + Claude Code's additions like `cache_creation`,
+ *   `service_tier`, `iterations[]`).
+ * - `timestamp` from the transcript line's `timestamp` field (ISO-8601)
+ * - `turnIndex` 0-based position among usage-bearing lines in the transcript
+ */
+function extractTurns(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return [];
+  const text = fs.readFileSync(transcriptPath, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let turnIndex = 0;
+  for (const line of lines) {
+    const j = _parseJsonLineSafe(line);
+    if (!j) continue;
+    const msg = j.message;
+    if (!msg || typeof msg !== 'object') continue;
+    if (msg.role && msg.role !== 'assistant') continue;
+    const usage = msg.usage;
+    if (!usage || typeof usage !== 'object') continue;
+    out.push({
+      messageId: msg.id || j.uuid || null,
+      model: msg.model || null,
+      usage,
+      timestamp: j.timestamp || null,
+      turnIndex: turnIndex++,
+    });
+  }
+  return out;
+}
+
+// ── Row emission ─────────────────────────────────────────────────────
+
+function pad2(n) { return String(n).padStart(2, '0'); }
+function _fmtDateTime(iso) {
+  const d = iso ? new Date(iso) : new Date();
+  if (isNaN(d.getTime())) return _fmtDateTime(new Date().toISOString());
+  return `${d.getFullYear()}-${pad2(d.getMonth()+1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+
+/**
+ * Capture usage for one in-session turn.
+ *
+ * Low-level entry point: caller supplies the usage envelope directly. Used by
+ * unit tests and by the hook handler after extracting a turn from the
+ * transcript.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectDir
+ * @param {string} opts.sessionId
+ * @param {string|number} opts.turnId    unique-per-session identifier
+ * @param {object|null} opts.usage       Claude usage envelope (may be null)
+ * @param {string} [opts.model]
+ * @param {string} [opts.command]        e.g. 'in-session' or 'dialog'
+ * @param {string} [opts.ts]             ISO-8601; defaults to now
+ * @returns {{jsonlPath: string, tokenLogPath: string}}
+ */
+function captureInSessionUsage(opts) {
+  if (!opts || !opts.projectDir) throw new Error('captureInSessionUsage: projectDir required');
+  if (opts.sessionId == null) throw new Error('captureInSessionUsage: sessionId required');
+  if (opts.turnId == null) throw new Error('captureInSessionUsage: turnId required');
+
+  const stamp = _fmtDateTime(opts.ts);
+  return capture.recordSpawnRow({
+    projectDir: opts.projectDir,
+    command: opts.command || 'in-session',
+    step: 'turn',
+    model: opts.model || 'claude',
+    startedAt: stamp,
+    endedAt: stamp,
+    usage: opts.usage || undefined,
+    notes: 'in-session turn',
+    sessionId: opts.sessionId,
+    turnId: opts.turnId,
+    sessionType: 'in-session',
+    // Canonical sink is JSONL; token-log.md is regenerated via
+    // `gsd-t tokens --regenerate-log` (D3). Avoid polluting the markdown
+    // log with per-turn rows (one session can have hundreds of turns).
+    skipMarkdownLog: true,
+  });
+}
+
+/**
+ * Process a hook payload (Stop / SessionEnd) — read the transcript it points
+ * at, emit rows for every assistant turn we haven't seen yet.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectDir
+ * @param {object} opts.payload  raw hook payload as written by Claude Code
+ * @returns {{sessionId: string|null, emitted: number, skipped: number, reason?: string}}
+ */
+function processHookPayload(opts) {
+  const projectDir = (opts && opts.projectDir) || '.';
+  const payload = opts && opts.payload;
+  if (!payload || typeof payload !== 'object') {
+    return { sessionId: null, emitted: 0, skipped: 0, reason: 'no-payload' };
+  }
+  const sessionId = payload.session_id || payload.sessionId || null;
+  const transcriptPath = payload.transcript_path || payload.transcriptPath || null;
+  if (!sessionId || !transcriptPath) {
+    return { sessionId, emitted: 0, skipped: 0, reason: 'missing-session-or-transcript' };
+  }
+
+  const turns = extractTurns(transcriptPath);
+  if (!turns.length) {
+    return { sessionId, emitted: 0, skipped: 0, reason: 'no-turns' };
+  }
+
+  const cursor = _loadCursor(projectDir);
+  const lastSeen = cursor[sessionId] && cursor[sessionId].lastMessageId;
+
+  let startAt = 0;
+  if (lastSeen) {
+    const idx = turns.findIndex(t => t.messageId === lastSeen);
+    if (idx >= 0) startAt = idx + 1;
+  }
+
+  let emitted = 0;
+  let skipped = startAt;
+  for (let i = startAt; i < turns.length; i++) {
+    const turn = turns[i];
+    const turnId = turn.messageId || `idx-${turn.turnIndex}`;
+    captureInSessionUsage({
+      projectDir,
+      sessionId,
+      turnId,
+      usage: turn.usage,
+      model: turn.model,
+      command: 'in-session',
+      ts: turn.timestamp,
+    });
+    emitted++;
+  }
+
+  const newLast = turns[turns.length - 1];
+  cursor[sessionId] = {
+    lastMessageId: newLast ? newLast.messageId : null,
+    lastTurnIndex: newLast ? newLast.turnIndex : -1,
+    lastUpdatedAt: new Date().toISOString(),
+  };
+  _saveCursor(projectDir, cursor);
+
+  return { sessionId, emitted, skipped };
+}
+
+module.exports = {
+  captureInSessionUsage,
+  processHookPayload,
+  extractTurns,
+  _internal: { _loadCursor, _saveCursor },
+};

package/bin/gsd-t-orchestrator-config.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
 const DEFAULTS = Object.freeze({
@@ -11,6 +12,79 @@ const DEFAULTS = Object.freeze({
 });
 
 const MAX_PARALLEL_CEILING = 15;
+const WORKER_RAM_BUDGET_BYTES = 2 * 1024 * 1024 * 1024;
+const ADAPTIVE_FLOOR = 3;
+
+// ─── M44 D2 — mode-aware gating math ──────────────────────────────────────
+// Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0 §Mode-Aware Gating Math.
+
+const IN_SESSION_CW_CEILING_PCT = 85;
+const UNATTENDED_PER_WORKER_CW_PCT = 60;
+const DEFAULT_SUMMARY_SIZE_PCT = 4;
+
+/**
+ * [in-session] headroom gate.
+ *
+ * Returns `{ok, reducedCount}`.
+ *   ok=true iff `ctxPct + workerCount * summarySize ≤ IN_SESSION_CW_CEILING_PCT`.
+ *   Otherwise reduces N repeatedly; final floor is N=1. NEVER refuses
+ *   (constraints.md: never throw a pause/resume prompt under any condition).
+ *
+ *   - reducedCount = the largest N ≤ requested workerCount such that the
+ *     headroom inequality holds. If the inequality fails for every N ≥ 1
+ *     (e.g. ctxPct already > ceiling), returns { ok: true, reducedCount: 1 }
+ *     — sequential always remains feasible because the 4% summary is only
+ *     spent *post*-worker, and one worker is the irreducible floor.
+ */
+function computeInSessionHeadroom(opts) {
+  const o = opts || {};
+  const ctxPct = Number.isFinite(o.ctxPct) ? o.ctxPct : 0;
+  const requested = Number.isFinite(o.workerCount) ? Math.max(0, Math.floor(o.workerCount)) : 0;
+  const summarySize = Number.isFinite(o.summarySize) ? o.summarySize : DEFAULT_SUMMARY_SIZE_PCT;
+  const ceiling = IN_SESSION_CW_CEILING_PCT;
+
+  // Direct fit.
+  if (ctxPct + requested * summarySize <= ceiling) {
+    return { ok: true, reducedCount: requested };
+  }
+  // Reduce N until it fits or we hit the floor.
+  let n = requested - 1;
+  while (n > 1) {
+    if (ctxPct + n * summarySize <= ceiling) {
+      return { ok: true, reducedCount: n };
+    }
+    n -= 1;
+  }
+  // Floor: 1 worker (sequential). Never refuses.
+  return { ok: true, reducedCount: 1 };
+}
+
+/**
+ * [unattended] per-worker CW gate.
+ *
+ * Returns `{ok, split}`.
+ *   ok=true, split=false if `estimatedCwPct ≤ threshold` (default 60).
+ *   ok=false, split=true otherwise — caller MUST slice the task into
+ *   multiple `claude -p` iters (actual splitting is scheduled by the
+ *   caller; this function only signals the split requirement).
+ */
+function computeUnattendedGate(opts) {
+  const o = opts || {};
+  const estimatedCwPct = Number.isFinite(o.estimatedCwPct) ? o.estimatedCwPct : 0;
+  const threshold = Number.isFinite(o.threshold) ? o.threshold : UNATTENDED_PER_WORKER_CW_PCT;
+  if (estimatedCwPct > threshold) {
+    return { ok: false, split: true };
+  }
+  return { ok: true, split: false };
+}
+
+function computeAdaptiveMaxParallel(freeBytes) {
+  const free = typeof freeBytes === 'number' ? freeBytes : os.freemem();
+  if (!Number.isFinite(free) || free <= 0) return ADAPTIVE_FLOOR;
+  const byMemory = Math.floor(free / WORKER_RAM_BUDGET_BYTES);
+  const clamped = Math.max(ADAPTIVE_FLOOR, Math.min(MAX_PARALLEL_CEILING, byMemory));
+  return clamped;
+}
 
 function loadConfigFile(projectDir) {
   const p = path.join(projectDir, '.gsd-t', 'orchestrator.config.json');
@@ -29,19 +103,28 @@ function parseIntStrict(v, name) {
 }
 
 function loadConfig(opts) {
-  const { projectDir, cliFlags = {}, env = process.env } = opts || {};
+  const { projectDir, cliFlags = {}, env = process.env, freeMemBytes } = opts || {};
   if (!projectDir) throw new Error('loadConfig requires projectDir');
 
   const fileCfg = loadConfigFile(projectDir);
+  const fileSetMaxParallel = Object.prototype.hasOwnProperty.call(fileCfg, 'maxParallel');
   const merged = { ...DEFAULTS, ...fileCfg };
+  let maxParallelSource = fileSetMaxParallel ? 'config-file' : 'adaptive';
+  if (!fileSetMaxParallel) {
+    merged.maxParallel = computeAdaptiveMaxParallel(freeMemBytes);
+  }
 
-  if (cliFlags.maxParallel != null) merged.maxParallel = parseIntStrict(cliFlags.maxParallel, '--max-parallel');
+  if (cliFlags.maxParallel != null) {
+    merged.maxParallel = parseIntStrict(cliFlags.maxParallel, '--max-parallel');
+    maxParallelSource = 'cli';
+  }
   if (cliFlags.workerTimeoutMs != null) merged.workerTimeoutMs = parseIntStrict(cliFlags.workerTimeoutMs, '--worker-timeout');
   if (cliFlags.retryOnFail != null) merged.retryOnFail = !!cliFlags.retryOnFail;
   if (cliFlags.haltOnSecondFail != null) merged.haltOnSecondFail = !!cliFlags.haltOnSecondFail;
 
   if (env.GSD_T_MAX_PARALLEL != null && env.GSD_T_MAX_PARALLEL !== '') {
     merged.maxParallel = parseIntStrict(env.GSD_T_MAX_PARALLEL, 'GSD_T_MAX_PARALLEL');
+    maxParallelSource = 'env';
   }
   if (env.GSD_T_WORKER_TIMEOUT_MS != null && env.GSD_T_WORKER_TIMEOUT_MS !== '') {
     merged.workerTimeoutMs = parseIntStrict(env.GSD_T_WORKER_TIMEOUT_MS, 'GSD_T_WORKER_TIMEOUT_MS');
@@ -58,7 +141,21 @@ function loadConfig(opts) {
   }
 
   merged.projectDir = projectDir;
+  merged.maxParallelSource = maxParallelSource;
   return merged;
 }
 
-module.exports = { loadConfig, DEFAULTS, MAX_PARALLEL_CEILING };
+module.exports = {
+  loadConfig,
+  DEFAULTS,
+  MAX_PARALLEL_CEILING,
+  computeAdaptiveMaxParallel,
+  WORKER_RAM_BUDGET_BYTES,
+  ADAPTIVE_FLOOR,
+  // M44 D2 — mode-aware gating math
+  computeInSessionHeadroom,
+  computeUnattendedGate,
+  IN_SESSION_CW_CEILING_PCT,
+  UNATTENDED_PER_WORKER_CW_PCT,
+  DEFAULT_SUMMARY_SIZE_PCT,
+};

package/bin/gsd-t-orchestrator.js

@@ -51,7 +51,8 @@ function printHelp() {
     '',
     'Options:',
     '  --milestone <id>         Milestone id (e.g. M40). Required.',
-    '  --max-parallel <n>       Max concurrent workers (default 3, max 15).',
+    '  --max-parallel <n>       Max concurrent workers (default: adaptive by free RAM,',
+    '                            1 worker per 2GB, floor 3, ceiling 15).',
     '  --worker-timeout <ms>    Per-worker timeout in ms (default 270000).',
     '  --project-dir <path>     Project directory (default cwd).',
     '  --resume                 Resume from .gsd-t/orchestrator/state.json.',