@tekyzinc/gsd-t 3.11.11 → 3.12.12

package/bin/gsd-t-unattended.js

@@ -56,6 +56,13 @@ const {
   notify,
 } = require("./gsd-t-unattended-platform.js");
 
+// Event stream (M38 ES) — additive, non-blocking. `_emit` swallows its own
+// errors per unattended-event-stream-contract.md §6.
+const { appendEvent: _esAppendEvent } = require("./event-stream.cjs");
+function _emit(projectDir, ev) {
+  try { _esAppendEvent(projectDir, ev); } catch (_) { /* never halt the loop */ }
+}
+
 // ── Constants ───────────────────────────────────────────────────────────────
 
 const CONTRACT_VERSION = "1.0.0";
@@ -477,7 +484,32 @@ function finalizeState(state, dir, terminalStatus) {
  */
 function doUnattended(argv, deps) {
   deps = deps || {};
-  const opts = parseArgs(argv || []);
+  const rawArgv = argv || [];
+
+  // --watch rejection (headless-default-contract §2) — unattended is detached
+  // by definition; passing --watch is a category error. Refuse fast so the
+  // user sees a clear message before any state.json / PID work happens.
+  if (
+    Array.isArray(rawArgv) &&
+    rawArgv.some(
+      (a) => typeof a === "string" && (a === "--watch" || a.startsWith("--watch=")),
+    )
+  ) {
+    // eslint-disable-next-line no-console
+    console.error(
+      "[gsd-t-unattended] --watch is incompatible with unattended.\n" +
+        "Unattended supervisor is detached by definition.\n" +
+        "Run /user:gsd-t-unattended-watch from your interactive session to see live activity.",
+    );
+    return {
+      ok: false,
+      dryRun: false,
+      exitCode: 2,
+      reason: "--watch is incompatible with unattended",
+    };
+  }
+
+  const opts = parseArgs(rawArgv);
   const projectDir = path.resolve(opts.project || ".");
 
   // ── Resolve injection points (real impls by default) ─────────────────────
@@ -884,6 +916,16 @@ function runMainLoop(state, dir, opts, deps, ctx) {
     state.lastWorkerStartedAt = workerStart.toISOString();
     writeState(state, dir);
 
+    _emit(projectDir, {
+      ts: workerStart.toISOString(),
+      iter: state.iter,
+      type: "task_start",
+      source: "supervisor",
+      milestone: state.milestone || "",
+      wave: state.wave || "",
+      task: state.nextTask || "",
+    });
+
     let res;
     try {
       res = spawnWorker(state, {
@@ -921,6 +963,29 @@ function runMainLoop(state, dir, opts, deps, ctx) {
     state.lastElapsedMs = elapsedMs;
     writeState(state, dir);
 
+    // Event-stream: task_complete on success, error on non-zero.
+    const durationS = Math.round(elapsedMs / 1000);
+    if (exitCode === 0) {
+      _emit(projectDir, {
+        ts: workerEnd.toISOString(),
+        iter: state.iter,
+        type: "task_complete",
+        source: "supervisor",
+        task: state.nextTask || "",
+        verdict: "pass",
+        duration_s: durationS,
+      });
+    } else {
+      _emit(projectDir, {
+        ts: workerEnd.toISOString(),
+        iter: state.iter,
+        type: "error",
+        source: "supervisor",
+        error: `worker exit ${exitCode}`,
+        recoverable: exitCode !== 4 && exitCode !== 5,
+      });
+    }
+
     // ── POST-WORKER HOOK (contract §12) ────────────────────────────────────
     // Read the tail of run.log for pattern detection. ~200 lines is enough
     // to span the last several iteration blocks for the gutter detector.
@@ -959,6 +1024,13 @@ function runMainLoop(state, dir, opts, deps, ctx) {
         break;
       }
       // Not yet done — continue relay.
+      _emit(projectDir, {
+        iter: state.iter,
+        type: "retry",
+        source: "supervisor",
+        attempt: state.iter,
+        reason: "milestone_incomplete",
+      });
       continue;
     }
     if (exitCode === 4) {
@@ -975,9 +1047,23 @@ function runMainLoop(state, dir, opts, deps, ctx) {
     }
     if (exitCode === 124) {
       // Timeout — continue unless the iter cap is hit on the next check.
+      _emit(projectDir, {
+        iter: state.iter,
+        type: "retry",
+        source: "supervisor",
+        attempt: state.iter,
+        reason: "timeout",
+      });
       continue;
     }
     // Non-terminal (1/2/3) — continue the relay.
+    _emit(projectDir, {
+      iter: state.iter,
+      type: "retry",
+      source: "supervisor",
+      attempt: state.iter,
+      reason: `exit_${exitCode}`,
+    });
   }
 
   // If we exited because the user dropped a stop sentinel and no terminal

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.
@@ -433,8 +439,8 @@ function ensureGitignoreEntries(projectDir, entries) {
 
 // Install the Context Meter into a project directory.
 // Copies scripts/gsd-t-context-meter.js, scripts/context-meter/*.js (runtime
-// only — skips .test.js and test-injector.js), and the config template (if
-// missing). Also appends entries to .gitignore.
+// only — skips .test.js), and the config template (if missing). Also appends
+// entries to .gitignore.
 function installContextMeter(projectDir) {
   try {
     // 1. Copy gsd-t-context-meter.js → {projectDir}/scripts/
@@ -486,9 +492,7 @@ function installContextMeter(projectDir) {
         return false;
       }
       for (const fname of depFiles) {
-        // Skip test files and test-only infrastructure
         if (fname.includes(".test.")) continue;
-        if (fname === "test-injector.js") continue;
         const fsrc = path.join(depsSrcDir, fname);
         const fdest = path.join(depsDestDir, fname);
         try {
@@ -546,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;
@@ -572,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";
         }
       }
     }
@@ -609,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
@@ -1651,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");
@@ -1970,8 +2025,7 @@ const PROJECT_BIN_TOOLS = [
   "archive-progress.cjs", "log-tail.cjs", "context-budget-audit.cjs",
   "context-meter-config.cjs", "token-budget.cjs",
   "gsd-t-unattended.cjs", "gsd-t-unattended-platform.cjs", "gsd-t-unattended-safety.cjs",
-  "handoff-lock.cjs", "headless-auto-spawn.cjs", "runway-estimator.cjs",
-  "token-telemetry.cjs", "token-optimizer.cjs",
+  "handoff-lock.cjs", "headless-auto-spawn.cjs",
 ];
 
 function copyBinToolsToProject(projectDir, projectName) {
@@ -2603,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 ────────────────────────────────────────────────────────────
 
 /**
@@ -2720,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", prompt], {
+    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) {
@@ -2741,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 {
@@ -3245,117 +3350,10 @@ function showHeadlessHelp() {
   log(`  ${DIM}$${RESET} gsd-t headless query domains\n`);
 }
 
-// ─── Metrics (M35 token telemetry CLI) ────────────────────────────────────────
-
-function parseMetricsByFlag(args) {
-  const byArg = args.find(a => a.startsWith("--by="));
-  if (!byArg) return [];
-  const raw = byArg.slice(5).trim();
-  if (!raw) return [];
-  return raw.split(",").map(s => s.trim()).filter(Boolean);
-}
-
-function formatPct(v) {
-  if (v === null || v === undefined || Number.isNaN(v)) return "—";
-  return `${Number(v).toFixed(1)}%`;
-}
+// ─── Metrics (removed in v3.12 — M38 meter reduction) ─────────────────────────
 
-function formatInt(v) {
-  if (v === null || v === undefined || Number.isNaN(v)) return "—";
-  return String(Math.round(Number(v)));
-}
-
-function doMetrics(args) {
-  const projectDir = process.cwd();
-  let tt;
-  try {
-    tt = require(path.join(projectDir, "bin", "token-telemetry.js"));
-  } catch (e) {
-    error(`bin/token-telemetry.js not found in ${projectDir} — run gsd-t install first.`);
-    process.exit(1);
-  }
-
-  const records = tt.readAll(projectDir);
-  if (records.length === 0) {
-    log(`${DIM}No telemetry records yet — .gsd-t/token-metrics.jsonl is empty or missing.${RESET}`);
-    return;
-  }
-
-  const isTokens = args.includes("--tokens");
-  const isHalts = args.includes("--halts");
-  const isContextWindow = args.includes("--context-window");
-
-  if (!isTokens && !isHalts && !isContextWindow) {
-    log(`${YELLOW}Specify at least one of: --tokens, --halts, --context-window${RESET}`);
-    return;
-  }
-
-  if (isHalts) {
-    const halts = records.filter(r => r.halt_type);
-    log(`\n${BOLD}Halts — ${halts.length} record(s)${RESET}`);
-    if (halts.length === 0) {
-      log(`${DIM}  (no halts recorded — all spawns completed normally)${RESET}\n`);
-    } else {
-      const byType = {};
-      for (const r of halts) {
-        const key = String(r.halt_type);
-        byType[key] = (byType[key] || 0) + 1;
-      }
-      for (const [type, count] of Object.entries(byType).sort()) {
-        log(`  ${CYAN}${type.padEnd(24)}${RESET} ${count}`);
-      }
-      log("");
-    }
-  }
-
-  if (isTokens) {
-    const by = parseMetricsByFlag(args);
-    if (by.length === 0) {
-      const totalConsumed = records.reduce((a, r) => a + (Number(r.tokens_consumed) || 0), 0);
-      const totalDuration = records.reduce((a, r) => a + (Number(r.duration_s) || 0), 0);
-      log(`\n${BOLD}Tokens — ${records.length} spawn(s)${RESET}`);
-      log(`  total tokens consumed:  ${formatInt(totalConsumed)}`);
-      log(`  total duration (s):     ${formatInt(totalDuration)}`);
-      if (records.length > 0) {
-        log(`  mean tokens/spawn:      ${formatInt(totalConsumed / records.length)}`);
-      }
-      log("");
-    } else {
-      const groups = tt.aggregate(records, { by });
-      log(`\n${BOLD}Tokens by ${by.join(",")} — ${groups.length} group(s)${RESET}`);
-      const keyHeader = by.join("/");
-      log(`  ${keyHeader.padEnd(36)}  ${"count".padStart(7)}  ${"total".padStart(12)}  ${"mean".padStart(10)}  ${"median".padStart(10)}  ${"p95".padStart(10)}`);
-      log(`  ${"-".repeat(36)}  ${"-".repeat(7)}  ${"-".repeat(12)}  ${"-".repeat(10)}  ${"-".repeat(10)}  ${"-".repeat(10)}`);
-      for (const g of groups) {
-        const label = by.map(k => g.key[k] == null ? "—" : String(g.key[k])).join("/");
-        log(`  ${label.padEnd(36)}  ${formatInt(g.count).padStart(7)}  ${formatInt(g.total_tokens).padStart(12)}  ${formatInt(g.mean).padStart(10)}  ${formatInt(g.median).padStart(10)}  ${formatInt(g.p95).padStart(10)}`);
-      }
-      log("");
-    }
-  }
-
-  if (isContextWindow) {
-    log(`\n${BOLD}Context window trend — ${records.length} record(s)${RESET}`);
-    const withPct = records.filter(r => r.context_window_pct_after != null && !Number.isNaN(Number(r.context_window_pct_after)));
-    if (withPct.length === 0) {
-      log(`${DIM}  (no context-window measurements in records)${RESET}\n`);
-    } else {
-      const sorted = [...withPct].map(r => Number(r.context_window_pct_after)).sort((a, b) => a - b);
-      const min = sorted[0];
-      const max = sorted[sorted.length - 1];
-      const mean = sorted.reduce((a, b) => a + b, 0) / sorted.length;
-      const p95 = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))];
-      log(`  min:   ${formatPct(min)}`);
-      log(`  mean:  ${formatPct(mean)}`);
-      log(`  p95:   ${formatPct(p95)}`);
-      log(`  max:   ${formatPct(max)}`);
-      const atWarn = withPct.filter(r => Number(r.context_window_pct_after) >= 70).length;
-      const atStop = withPct.filter(r => Number(r.context_window_pct_after) >= 85).length;
-      log(`  spawns at warn band (≥70%):  ${atWarn}`);
-      log(`  spawns at stop band (≥85%):  ${atStop}`);
-      log("");
-    }
-  }
+function doMetrics(_args) {
+  log(`${DIM}metrics removed in v3.12 — context meter is no longer telemetry-instrumented${RESET}`);
 }
 
 function showHelp() {
@@ -3470,6 +3468,7 @@ module.exports = {
   ensureGitignoreEntries,
   installContextMeter,
   configureContextMeterHooks,
+  removeContextMeterHook,
   promptForApiKeyIfMissing,
   resolveApiKeyEnvVar,
   runTaskCounterRetirementMigration,
@@ -3515,6 +3514,14 @@ if (require.main === module) {
     case "headless":
       doHeadless(args.slice(1));
       break;
+    case "unattended": {
+      const { spawnSync } = require("child_process");
+      const cjs = path.join(__dirname, "gsd-t-unattended.cjs");
+      const res = spawnSync(process.execPath, [cjs, ...args.slice(1)], {
+        stdio: "inherit",
+      });
+      process.exit(res.status == null ? 1 : res.status);
+    }
     case "metrics":
       doMetrics(args.slice(1));
       break;

package/bin/headless-auto-spawn.cjs

@@ -53,20 +53,54 @@ module.exports = {
  *   args?: string[],
  *   continue_from?: string,
  *   projectDir?: string,
- *   context?: object
+ *   context?: object,
+ *   sessionContext?: object,
+ *   sessionId?: string,
+ *   watch?: boolean,
+ *   spawnType?: 'primary' | 'validation'
  * }} opts
- * @returns {{ id: string, pid: number, logPath: string, timestamp: string }}
+ * @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 || null;
+  const context = opts.context || opts.sessionContext || null;
+  const watch = opts.watch === true;
+  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)})`,
+    );
+  }
+
+  // Propagation rules (headless-default-contract §2):
+  //   watch=true + primary    → signal in-context fallback (caller uses Task)
+  //   watch=true + validation → warn on stderr; proceed headless
+  //   watch=false             → headless (default behavior)
+  if (watch && spawnType === "primary") {
+    return {
+      id: null,
+      pid: null,
+      logPath: null,
+      timestamp: new Date().toISOString(),
+      mode: "in-context",
+    };
+  }
+  if (watch && spawnType === "validation") {
+    try {
+      process.stderr.write(
+        `[headless-default] --watch ignored for validation spawn type: ${spawnType}\n`,
+      );
+    } catch (_) {
+      /* best effort */
+    }
+  }
 
   const timestamp = new Date().toISOString();
   const id = makeSessionId(command, new Date());
@@ -101,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();
@@ -145,7 +186,13 @@ function autoSpawnHeadless(opts) {
   // 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 };
+  return {
+    id,
+    pid,
+    logPath: path.relative(projectDir, logPath),
+    timestamp,
+    mode: "headless",
+  };
 }
 
 // ── makeSessionId ────────────────────────────────────────────────────────────
@@ -251,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;
@@ -265,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) {
@@ -316,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) {