@tekyzinc/gsd-t 3.12.10 → 3.12.12

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.12.12] - 2026-04-17
+
+### Fixed — Token-Log Observability for Headless/Unattended Workers
+
+**Background**: M38 headless-by-default left `.gsd-t/token-log.md` blind to all supervisor and headless-exec worker activity. Rows were only written by interactive `T_START/T_END` bash blocks in command files. All event-stream `tool_call` entries from workers had `command: null`, `phase: null`, `trace_id: null`.
+
+#### Fix 1: headless worker spawns append to token-log.md
+
+Three spawn paths now write rows to `{projectDir}/.gsd-t/token-log.md`:
+
+- **`bin/headless-auto-spawn.cjs`** — `installCompletionWatcher` appends a row when the detached child exits (poll-based, graceful — never halts on write failure). Creates the file with the canonical header if it does not exist. Migrates files created before this fix (adds header if missing).
+- **`bin/gsd-t-unattended.cjs`** — supervisor worker loop appends a row after each `_spawnWorker` call completes, recording iteration number, duration, exit code. New `_appendTokenLog` helper follows the same schema as interactive command observability blocks.
+- **`bin/gsd-t.js` `doHeadlessExec`** — `gsd-t headless <command>` invocations append a row synchronously after the `claude -p` process exits.
+
+Row format matches the existing token-log schema:
+`| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |`
+Tokens are logged as `unknown` (no API access in worker contexts); duration is wall-clock.
+
+#### Fix 2: command/phase propagate to event-stream entries in worker contexts
+
+Env-var approach chosen (cleaner, no call-site changes needed):
+
+- **`scripts/gsd-t-event-writer.js` `buildEvent`** — reads `GSD_T_COMMAND` and `GSD_T_PHASE` env vars as defaults when `--command`/`--phase` flags are absent. Explicit flags always win.
+- **`bin/headless-auto-spawn.cjs`** — sets `GSD_T_COMMAND={command}` and `GSD_T_PHASE={phase}` on every detached child's env before spawn.
+- **`bin/gsd-t-unattended.cjs` `_spawnWorker`** — sets `GSD_T_COMMAND=gsd-t-resume` and `GSD_T_PHASE={state.phase||execute}` on each `claude -p` worker env.
+- **`bin/gsd-t.js` `doHeadlessExec`** — sets `GSD_T_COMMAND=gsd-t-{command}` on the `execFileSync` env.
+
+Result: all `tool_call` events in worker contexts are tagged with the originating command and phase instead of `null`.
+
+## [3.12.11] - 2026-04-17
+
+### Fixed
+- **Installer owns global PostToolUse context-meter hook** — the hook command now targets the globally-installed npm package (`$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-context-meter.js`) instead of `$CLAUDE_PROJECT_DIR/scripts/...`. The old path caused `Cannot find module` errors in every non-GSD-T project and when `CLAUDE_PROJECT_DIR` was unset.
+- **Auto-migration of stale hook entries** — `install`, `update`, `update-all`, and `init` now detect and replace any PostToolUse entry whose command matches the prior `$CLAUDE_PROJECT_DIR`-based pattern, upgrading it in-place to the canonical global form.
+- **Existence guard** — the hook command is wrapped in a `bash -c '[ -f ... ] && node ... || true'` guard so it silently exits 0 when the package is not present (non-GSD-T projects, uninstalled state).
+- **Uninstall removes the hook** — `gsd-t uninstall` now removes any PostToolUse hook containing `gsd-t-context-meter` from `~/.claude/settings.json`, leaving all other hooks intact.
+
 ## [3.12.10] - 2026-04-17
 
 ### M38: Headless-by-Default + Meter Reduction

package/bin/gsd-t-unattended.cjs

@@ -939,6 +939,17 @@ function runMainLoop(state, dir, opts, deps, ctx) {
     // Append the full worker output to run.log (never truncate).
     _appendRunLog(dir, state.iter, workerEnd, exitCode, stdout, stderr);
 
+    // Append to token-log.md (Fix 1, v3.12.12) — supervisor workers write rows
+    // so the log captures headless/unattended activity, not just interactive spawns.
+    _appendTokenLog(projectDir, {
+      dtStart: workerStart.toISOString().slice(0, 16).replace("T", " "),
+      dtEnd: workerEnd.toISOString().slice(0, 16).replace("T", " "),
+      command: "gsd-t-resume",
+      durationS: Math.round(elapsedMs / 1000),
+      exitCode,
+      iter: state.iter,
+    });
+
     // Post-spawn state update
     state.lastExit = exitCode;
     state.lastWorkerFinishedAt = workerEnd.toISOString();
@@ -1060,6 +1071,41 @@ function runMainLoop(state, dir, opts, deps, ctx) {
   return state;
 }
 
+// ── _appendTokenLog (Fix 1, v3.12.12) ───────────────────────────────────────
+
+const _TOKEN_LOG_HEADER =
+  "| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |\n" +
+  "|---|---|---|---|---|---|---|---|---|---|\n";
+
+/**
+ * Append one row to {projectDir}/.gsd-t/token-log.md for a supervisor worker
+ * iteration. Matches the schema used by interactive command-file observability.
+ */
+function _appendTokenLog(projectDir, entry) {
+  try {
+    const logPath = path.join(projectDir, ".gsd-t", "token-log.md");
+    const note = entry.exitCode === 0
+      ? `supervisor iter=${entry.iter}: ok`
+      : `supervisor iter=${entry.iter}: exit ${entry.exitCode}`;
+    const row =
+      `| ${entry.dtStart} | ${entry.dtEnd} | ${entry.command} | supervisor-iter-${entry.iter} | unknown | ${entry.durationS}s | ${note} | - | - | unknown |\n`;
+    const gsdtDir = path.join(projectDir, ".gsd-t");
+    if (!fs.existsSync(gsdtDir)) fs.mkdirSync(gsdtDir, { recursive: true });
+    if (!fs.existsSync(logPath)) {
+      fs.writeFileSync(logPath, `# GSD-T Token Log\n\n${_TOKEN_LOG_HEADER}${row}`);
+    } else {
+      const existing = fs.readFileSync(logPath, "utf8");
+      if (!existing.includes("| Datetime-start |")) {
+        fs.writeFileSync(logPath, `# GSD-T Token Log\n\n${_TOKEN_LOG_HEADER}${existing}${row}`);
+      } else {
+        fs.appendFileSync(logPath, row);
+      }
+    }
+  } catch (_) {
+    /* best-effort — never halt the supervisor loop */
+  }
+}
+
 // ── _spawnWorker ────────────────────────────────────────────────────────────
 
 /**
@@ -1073,7 +1119,15 @@ function runMainLoop(state, dir, opts, deps, ctx) {
  */
 function _spawnWorker(state, opts) {
   const bin = (state && state.claudeBin) || resolveClaudePath();
-  const workerEnv = { ...process.env, GSD_T_UNATTENDED_WORKER: "1" };
+  // Inject command/phase so event-stream tool_call entries are tagged in worker
+  // contexts (Fix 2, v3.12.12). Supervisor always runs gsd-t-resume workers;
+  // phase is inferred from state when available.
+  const workerEnv = {
+    ...process.env,
+    GSD_T_UNATTENDED_WORKER: "1",
+    GSD_T_COMMAND: "gsd-t-resume",
+    GSD_T_PHASE: (state && state.phase) || "execute",
+  };
   const res = platformSpawnWorker(opts.cwd, opts.timeout, {
     bin,
     args: [

package/bin/gsd-t.js

@@ -388,8 +388,14 @@ const CONTEXT_METER_GITIGNORE_ENTRIES = [
   ".gsd-t/context-meter.log",
 ];
 const CONTEXT_METER_HOOK_MARKER = "gsd-t-context-meter";
+// Canonical global hook — runs the script from the globally-installed npm package.
+// Guarded so it silently exits 0 if the package is not present (non-GSD-T projects).
 const CONTEXT_METER_HOOK_COMMAND =
-  'node "$CLAUDE_PROJECT_DIR/scripts/gsd-t-context-meter.js"';
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-context-meter.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-context-meter.js" || true\'';
+// Legacy command patterns that must be migrated on install/update/init.
+const CONTEXT_METER_STALE_PATTERNS = [
+  /node\s+"?\$CLAUDE_PROJECT_DIR\/scripts\/gsd-t-context-meter\.js"?/,
+];
 
 // Append entries to {projectDir}/.gitignore. Each entry added only if absent.
 // Idempotent. Returns true if any entries were added, false otherwise.
@@ -544,7 +550,9 @@ function installContextMeter(projectDir) {
 
 // Register the Context Meter PostToolUse hook in ~/.claude/settings.json.
 // Idempotent — if an existing hook references CONTEXT_METER_HOOK_MARKER the
-// command string is refreshed in-place. All other settings/hooks preserved.
+// command string is refreshed/migrated in-place to the canonical form.
+// Stale entries matching CONTEXT_METER_STALE_PATTERNS are migrated on the spot.
+// All other settings/hooks are preserved.
 // Returns { installed: bool, action: "added"|"updated"|"noop" }.
 function configureContextMeterHooks(settingsPath) {
   const targetPath = settingsPath || SETTINGS_JSON;
@@ -570,13 +578,17 @@ function configureContextMeterHooks(settingsPath) {
   for (const entry of settings.hooks.PostToolUse) {
     if (!entry || !Array.isArray(entry.hooks)) continue;
     for (const h of entry.hooks) {
-      if (h && typeof h.command === "string" && h.command.includes(CONTEXT_METER_HOOK_MARKER)) {
+      if (!h || typeof h.command !== "string") continue;
+      const isCurrentCanonical = h.command === cmd;
+      const isMarkerMatch = h.command.includes(CONTEXT_METER_HOOK_MARKER);
+      const isStaleMatch = !isCurrentCanonical &&
+        CONTEXT_METER_STALE_PATTERNS.some((re) => re.test(h.command));
+
+      if (isCurrentCanonical || isMarkerMatch || isStaleMatch) {
         found = true;
-        if (h.command !== cmd) {
+        if (!isCurrentCanonical) {
           h.command = cmd;
           action = "updated";
-        } else if (action === "noop") {
-          action = "noop";
         }
       }
     }
@@ -607,6 +619,46 @@ function configureContextMeterHooks(settingsPath) {
   return { installed: true, action };
 }
 
+// Remove any context meter PostToolUse hooks from settings.json.
+// Used during uninstall. Leaves all other hooks intact.
+function removeContextMeterHook(settingsPath) {
+  const targetPath = settingsPath || SETTINGS_JSON;
+  if (!fs.existsSync(targetPath)) return false;
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+    if (!settings || typeof settings !== "object") return false;
+  } catch {
+    warn("settings.json has invalid JSON — cannot remove context meter hook");
+    return false;
+  }
+
+  if (!settings.hooks || !Array.isArray(settings.hooks.PostToolUse)) return false;
+
+  const before = settings.hooks.PostToolUse.length;
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => {
+    if (!entry || !Array.isArray(entry.hooks)) return true;
+    // Keep the entry only if NONE of its hooks reference the context meter
+    return !entry.hooks.some(
+      (h) => h && typeof h.command === "string" && h.command.includes(CONTEXT_METER_HOOK_MARKER)
+    );
+  });
+  const removed = before - settings.hooks.PostToolUse.length;
+  if (removed === 0) return false;
+
+  if (isSymlink(targetPath)) {
+    warn("Skipping settings.json write — target is a symlink");
+    return false;
+  }
+  try {
+    fs.writeFileSync(targetPath, JSON.stringify(settings, null, 2));
+    return true;
+  } catch (e) {
+    warn(`Failed to write settings.json: ${e.message}`);
+    return false;
+  }
+}
+
 // Interactive prompt for the Anthropic API key env var.
 // Skips if not a TTY or if the env var is already set.
 // Never writes the key anywhere — just prints the export command for the user
@@ -1649,6 +1701,11 @@ function doUninstall() {
   removeInstalledCommands();
   removeVersionFile();
 
+  // Remove context meter PostToolUse hook from settings.json
+  if (removeContextMeterHook(SETTINGS_JSON)) {
+    success("Context meter PostToolUse hook removed from settings.json");
+  }
+
   warn("~/.claude/CLAUDE.md was NOT removed (may contain your customizations)");
   info("Remove manually if desired: delete the GSD-T section from ~/.claude/CLAUDE.md");
   info("Project files (.gsd-t/, docs/, CLAUDE.md) were NOT removed");
@@ -2600,6 +2657,39 @@ function doGraph(args) {
   }
 }
 
+// ─── Token-Log Writer (Fix 1, v3.12.12) ─────────────────────────────────────
+
+const _TL_HEADER =
+  "| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |\n" +
+  "|---|---|---|---|---|---|---|---|---|---|\n";
+
+/**
+ * Append one row to {projectDir}/.gsd-t/token-log.md for a headless exec
+ * invocation. Best-effort — never throws.
+ */
+function appendHeadlessTokenLog(projectDir, entry) {
+  try {
+    const logPath = path.join(projectDir, ".gsd-t", "token-log.md");
+    const note = entry.exitCode === 0 ? "headless exec: ok" : `headless exec: exit ${entry.exitCode}`;
+    const row =
+      `| ${entry.dtStart} | ${entry.dtEnd} | ${entry.command} | headless | unknown | ${entry.durationS}s | ${note} | - | - | unknown |\n`;
+    const gsdtDir = path.join(projectDir, ".gsd-t");
+    if (!fs.existsSync(gsdtDir)) fs.mkdirSync(gsdtDir, { recursive: true });
+    if (!fs.existsSync(logPath)) {
+      fs.writeFileSync(logPath, `# GSD-T Token Log\n\n${_TL_HEADER}${row}`);
+    } else {
+      const existing = fs.readFileSync(logPath, "utf8");
+      if (!existing.includes("| Datetime-start |")) {
+        fs.writeFileSync(logPath, `# GSD-T Token Log\n\n${_TL_HEADER}${existing}${row}`);
+      } else {
+        fs.appendFileSync(logPath, row);
+      }
+    }
+  } catch (_) {
+    /* best-effort */
+  }
+}
+
 // ─── Headless Mode ────────────────────────────────────────────────────────────
 
 /**
@@ -2717,12 +2807,20 @@ function doHeadlessExec(command, cmdArgs, flags) {
   let output = "";
   let processExitCode = 0;
 
+  // Inject command/phase env vars so worker event-stream entries are tagged
+  // (Fix 2, v3.12.12).
+  const workerEnv = Object.assign({}, process.env, {
+    GSD_T_COMMAND: `gsd-t-${command}`,
+    GSD_T_PHASE: process.env.GSD_T_PHASE || "execute",
+  });
+
   try {
     const result = execFileSync("claude", ["-p", "--dangerously-skip-permissions", prompt], {
       encoding: "utf8",
       timeout: timeoutMs,
       stdio: ["pipe", "pipe", "pipe"],
-      cwd: process.cwd()
+      cwd: process.cwd(),
+      env: workerEnv,
     });
     output = result;
   } catch (e) {
@@ -2738,6 +2836,16 @@ function doHeadlessExec(command, cmdArgs, flags) {
   const gsdtExitCode = mapHeadlessExitCode(processExitCode, output);
   const duration = Date.now() - startTime;
 
+  // Append to token-log.md (Fix 1, v3.12.12) — headless exec writes a row so
+  // `gsd-t headless <command>` spawns are visible in the log.
+  appendHeadlessTokenLog(process.cwd(), {
+    dtStart: new Date(startTime).toISOString().slice(0, 16).replace("T", " "),
+    dtEnd: new Date(startTime + duration).toISOString().slice(0, 16).replace("T", " "),
+    command: `gsd-t-${command}`,
+    durationS: Math.round(duration / 1000),
+    exitCode: gsdtExitCode,
+  });
+
   // Write log file if requested
   if (logMode && logFile) {
     try {
@@ -3360,6 +3468,7 @@ module.exports = {
   ensureGitignoreEntries,
   installContextMeter,
   configureContextMeterHooks,
+  removeContextMeterHook,
   promptForApiKeyIfMissing,
   resolveApiKeyEnvVar,
   runTaskCounterRetirementMigration,

package/bin/headless-auto-spawn.cjs

@@ -135,11 +135,18 @@ function autoSpawnHeadless(opts) {
     const gsdtCli = path.join(projectDir, "bin", "gsd-t.js");
     const childArgs = [gsdtCli, "headless", stripGsdtPrefix(command), ...args, "--log"];
 
+    // Inject command/phase into worker env so event-stream entries are tagged
+    // (Fix 2, v3.12.12). GSD_T_PHASE defaults to "execute" for primary spawns.
+    const workerEnv = Object.assign({}, process.env, {
+      GSD_T_COMMAND: command,
+      GSD_T_PHASE: process.env.GSD_T_PHASE || "execute",
+    });
+
     const child = spawn("node", childArgs, {
       cwd: projectDir,
       detached: true,
       stdio: ["ignore", logFd, logFd],
-      env: process.env,
+      env: workerEnv,
     });
 
     child.unref();
@@ -291,6 +298,7 @@ function installCompletionWatcher(opts) {
   const POLL_MS = 2000;
   const MAX_WAIT_MS = 60 * 60 * 1000; // 1 hour safety cap
   const startMs = Date.now();
+  const dtStart = new Date(startTimestamp).toLocaleString("sv-SE", { hour12: false }).slice(0, 16);
 
   const timer = setInterval(() => {
     let alive = false;
@@ -305,9 +313,20 @@ function installCompletionWatcher(opts) {
       // 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);
+      const endTimestamp = new Date().toISOString();
       markSessionCompleted(projectDir, id, {
         exitCode,
-        endTimestamp: new Date().toISOString(),
+        endTimestamp,
+      });
+      // Append token-log row (Fix 1, v3.12.12)
+      const dtEnd = new Date(endTimestamp).toLocaleString("sv-SE", { hour12: false }).slice(0, 16);
+      const durationS = Math.round((Date.now() - startMs) / 1000);
+      appendTokenLog(projectDir, {
+        dtStart,
+        dtEnd,
+        command: extractCommand(id),
+        durationS,
+        exitCode,
       });
       fireMacNotification({ id, command: extractCommand(id), startTimestamp });
     } else if (Date.now() - startMs > MAX_WAIT_MS) {
@@ -356,6 +375,43 @@ function fireMacNotification({ id, command }) {
   }
 }
 
+// ── Token-Log Writer (Fix 1, v3.12.12) ───────────────────────────────────────
+
+const TOKEN_LOG_HEADER =
+  "| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |\n" +
+  "|---|---|---|---|---|---|---|---|---|---|\n";
+
+/**
+ * Append one row to {projectDir}/.gsd-t/token-log.md matching the schema used
+ * by interactive command-file observability blocks.
+ *
+ * @param {string} projectDir
+ * @param {{ dtStart: string, dtEnd: string, command: string, durationS: number, exitCode: number }} entry
+ */
+function appendTokenLog(projectDir, entry) {
+  try {
+    const logPath = path.join(projectDir, ".gsd-t", "token-log.md");
+    const note = entry.exitCode === 0 ? "headless spawn: ok" : `headless spawn: exit ${entry.exitCode}`;
+    const row =
+      `| ${entry.dtStart} | ${entry.dtEnd} | ${entry.command} | headless | unknown | ${entry.durationS}s | ${note} | - | - | unknown |\n`;
+    if (!fs.existsSync(logPath)) {
+      // Create with header
+      ensureDir(path.dirname(logPath));
+      fs.writeFileSync(logPath, `# GSD-T Token Log\n\n${TOKEN_LOG_HEADER}${row}`);
+    } else {
+      // Check if header row exists; if not prepend it (migration for files created before this fix)
+      const existing = fs.readFileSync(logPath, "utf8");
+      if (!existing.includes("| Datetime-start |")) {
+        fs.writeFileSync(logPath, `# GSD-T Token Log\n\n${TOKEN_LOG_HEADER}${existing}${row}`);
+      } else {
+        fs.appendFileSync(logPath, row);
+      }
+    }
+  } catch (_) {
+    /* best-effort — never halt the completion watcher */
+  }
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 function ensureDir(d) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.12.10",
+  "version": "3.12.12",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-event-writer.js

@@ -71,11 +71,17 @@ function nullify(val) {
 }
 
 function buildEvent(args) {
+  // Env-var fallbacks: workers spawned by supervisor/headless-auto-spawn inherit
+  // GSD_T_COMMAND and GSD_T_PHASE so tool_call events are tagged even when the
+  // worker doesn't pass --command/--phase explicitly (Fix 2, v3.12.12).
+  const envCommand = process.env.GSD_T_COMMAND || null;
+  const envPhase = process.env.GSD_T_PHASE || null;
+
   return {
     ts: new Date().toISOString(),
     event_type: nullify(args["type"]),
-    command: nullify(args["command"]),
-    phase: nullify(args["phase"]),
+    command: nullify(args["command"]) || envCommand,
+    phase: nullify(args["phase"]) || envPhase,
     agent_id: nullify(args["agent-id"]),
     parent_agent_id: nullify(args["parent-id"]),
     trace_id: nullify(args["trace-id"]),