@tekyzinc/gsd-t 3.11.11 → 3.12.10

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.12.10] - 2026-04-17
+
+### M38: Headless-by-Default + Meter Reduction
+
+**Background**: M37 was right that the context meter needed to do more — but escalating to a MANDATORY STOP banner in the interactive session was the wrong fix. M38 removes the cause instead of bandaging the symptom: headless spawning is now the default for all primary workflow subagents, so the parent context grows much slower and the single-band meter threshold is sufficient. Seven commands removed. Five contracts folded. Net result: same "work never stops" UX achieved by structure instead of instrumentation.
+
+### Added
+- **`bin/event-stream.cjs`** — new module for structured JSONL event emission to `.gsd-t/events/YYYY-MM-DD.jsonl`. Emits `task_start`, `task_complete`, `subagent_verdict`, `file_changed`, `test_result`, `error`, `retry` event types. Used by unattended supervisor and watch tick.
+- **`bin/headless-auto-spawn.cjs`** `watch` + `spawnType` parameters — propagation rules: `spawnType:'validation'` always headless regardless of `--watch`; `spawnType:'primary'` + `watch:true` returns `{mode:'in-context'}` for live streaming.
+- **`.gsd-t/contracts/headless-default-contract.md`** v1.0.0 — defines the headless spawn primitive, Conversion Map (7 primary commands converted), `--watch` flag spec, validation-spawn enforcement, and migration path. Folds headless-auto-spawn-contract v1.0.0.
+- **`.gsd-t/contracts/unattended-event-stream-contract.md`** v1.0.0 — JSONL event schema, watch tick activity log format, supervisor emission requirements.
+- **`test/headless-default.test.js`** — 11 tests covering the 4-cell propagation matrix (primary/validation × watch/no-watch) + regression coverage.
+- **`test/event-stream.test.js`**, **`test/unattended-watch.test.js`**, **`test/router-intent.test.js`** — new test files for M38 components.
+- **`commands/gsd.md`** intent classifier — handles conversational requests directly (workflow → existing command; conversational → respond; ambiguous → default to conversation).
+
+### Changed
+- **7 command files** (`gsd-t-execute`, `gsd-t-wave`, `gsd-t-integrate`, `gsd-t-quick`, `gsd-t-debug`, `gsd-t-scan`, `gsd-t-verify`) — converted to `autoSpawnHeadless({spawnType:'primary', watch:$WATCH_FLAG})` pattern. Validation spawns (QA, Red Team, Design Verification) always headless.
+- **`bin/gsd-t-unattended.{cjs,js}`** — rejects `--watch` flag with clear error. Emits structured JSONL events at every phase boundary.
+- **`.gsd-t/contracts/context-meter-contract.md`** v1.3.0 — drops three-band model, dead-meter detection, stale-band logic, Universal Auto-Pause elevation. Single-band model: one threshold (default 85%), one action (silent headless handoff). Replaces v1.2.0.
+- **`.gsd-t/contracts/unattended-supervisor-contract.md`** v1.1.0 — adds §9 Event Stream Emission requirement: supervisor MUST emit structured events; watch tick MUST read events and format activity log.
+- **`templates/CLAUDE-global.md`** — Universal Auto-Pause Rule section removed; Context Meter section updated to single-band description.
+- **5 loop commands** (`gsd-t-execute`, `gsd-t-wave`, `gsd-t-integrate`, `gsd-t-quick`, `gsd-t-debug`) — Step 0.2 Universal Auto-Pause enforcement stripped.
+- **`scripts/gsd-t-context-meter.test.js`** — rewritten for single-band model.
+- **`test/filesystem.test.js`** — command count updated from 61 to 54.
+- **`docs/requirements.md`** — REQ-073..078 updated to `SUPERSEDED by REQ-08X (M38)` with replacement pointers. REQ-088..093 added (M38 requirements).
+- **`docs/methodology.md`** §3–§5 — historical framing added; deleted machinery marked as superseded by M38.
+- **`docs/prd-harness-evolution.md`** — Status updated to `HISTORICAL — M31 shipped; M32/M33 SUPERSEDED by M38`.
+- **`docs/architecture.md`**, **`docs/workflows.md`**, **`docs/infrastructure.md`**, **`GSD-T-README.md`** — updated to reflect headless-by-default spawn path, event stream, simplified meter.
+
+### Removed
+- **7 commands deleted**: `gsd-t-optimization-apply`, `gsd-t-optimization-reject`, `gsd-t-reflect`, `gsd-t-audit` (self-improvement loop), `gsd-t-prompt`, `gsd-t-brainstorm`, `gsd-t-discuss` (conversational — router intent classifier handles these)
+- **`bin/runway-estimator.cjs`** + **`bin/token-telemetry.cjs`** — deleted; replaced by headless-by-default approach
+- **`bin/qa-calibrator.js`** + **`bin/token-optimizer.js`** — deleted with self-improvement loop
+- **5 contracts folded/deleted**: `runway-estimator-contract.md`, `token-telemetry-contract.md`, `headless-auto-spawn-contract.md`, `qa-calibration-contract.md`, `harness-audit-contract.md`
+- **`test/runway-estimator.test.js`**, **`test/token-telemetry.test.js`**, **`test/qa-calibrator.test.js`**, **`test/token-optimizer.test.js`** — deleted with removed modules
+
+### Migration Notes
+- **Spawn pattern**: replace `autoSpawnHeadless()` (no args) with `autoSpawnHeadless({spawnType:'primary', watch:$WATCH_FLAG})` in any downstream command files that call the spawn primitive directly.
+- **Context meter**: if you depend on the three-band model (`normal`/`warn`/`stop`) or dead-meter detection in `token-budget.cjs`, those fields are removed. `getSessionStatus()` returns `{pct, threshold}` only.
+- **Deleted contracts**: any downstream references to `runway-estimator-contract.md`, `token-telemetry-contract.md`, or `headless-auto-spawn-contract.md` should point to `headless-default-contract.md` v1.0.0 instead.
+- **Deleted commands**: `gsd-t-prompt`, `gsd-t-brainstorm`, `gsd-t-discuss` — use plain text messages to Claude instead; the router classifier handles conversational requests. `gsd-t-optimization-apply/reject`, `gsd-t-reflect`, `gsd-t-audit` — removed; the self-improvement backlog is no longer maintained.
+
+### Testing
+- 1176/1177 tests pass. 1 pre-existing failure (`scan.test.js:287`) carried forward — scan-data-collector regex drift vs current prose format, unrelated to M38 scope.
+
+## [3.11.12] - 2026-04-16
+
+### Added — M38 Partition + Plan + Domain H1 Progress
+
+**Background**: M38 (Headless-by-Default + Meter Reduction) partitioned into 5 domains across 2 waves. Domain H1 (headless-spawn-default) executed through T6 by unattended supervisor Iter 2 but did not commit. This checkin captures all M38 setup work + H1 in-flight progress + Scan #11 regeneration.
+
+### Added
+- **5 M38 domain directories** under `.gsd-t/domains/` (m38-headless-spawn-default, m38-meter-reduction, m38-unattended-event-stream, m38-router-conversational, m38-cleanup-and-docs) with scope.md, constraints.md, tasks.md each — 35 atomic tasks total
+- **2 new contracts**: `.gsd-t/contracts/headless-default-contract.md` (v1.0.0 DRAFT, folds 3 M35 contracts), `.gsd-t/contracts/unattended-event-stream-contract.md` (v1.0.0 DRAFT)
+- **`test/headless-default.test.js`** — 11 tests covering the 4-cell propagation matrix (primary/validation × watch/no-watch) + existing regression coverage
+- **`bin/gsd-t.js`** `unattended` passthrough subcommand — dispatches to `bin/gsd-t-unattended.cjs` so defense-in-depth `--watch` rejection reaches the supervisor rejection logic
+- **M38 Scan #11** artifacts under `.gsd-t/scan/` (architecture, business-rules, contract-drift, quality, security, test-baseline + scan-report.html)
+
+### Changed
+- **`bin/headless-auto-spawn.{cjs,js}`** — added `watch` + `spawnType` parameters; propagation rules implemented (validation spawns always headless, primary+watch returns `{mode: 'in-context'}`)
+- **7 command files** converted to `autoSpawnHeadless({...spawnType: 'primary', watch: $WATCH_FLAG})` pattern: `gsd-t-execute`, `gsd-t-wave`, `gsd-t-integrate`, `gsd-t-quick`, `gsd-t-debug`, `gsd-t-scan`, `gsd-t-verify`
+- **`bin/gsd-t-unattended.{cjs,js}`** — rejects `--watch` flag with clear error (validation-spawn enforcement in unattended context)
+- **`bin/gsd-t.js`** `installContextMeter()` — removed `test-injector.js` skip (file deleted; no longer needed)
+- **`.gsd-t/contracts/integration-points.md`** — M38 dependency graph + 5 checkpoints (M38-CP1 → M38-CP5) + file ownership map
+- **`.gsd-t/progress.md`** — M38 partition + plan entries added to Decision Log
+- **`docs/architecture.md` + `docs/infrastructure.md`** — Scan #11 staleness callouts added (TD-103 doc-ripple candidate noted)
+
+### Removed
+- **`scripts/context-meter/count-tokens-client.{js,test.js}`** — retired with v3.11.11 local-estimator switch (count_tokens API no longer called)
+- **`scripts/context-meter/test-injector.js`** — test-only infrastructure, no longer referenced
+
+### Testing
+- 1234/1242 tests pass. 8 pre-existing failures carried forward: 7 stranded context-meter tests (TD-102, owned by M38-MR) + 1 scan.test.js live-state test (unrelated). No regressions from H1 work.
+
 ## [3.11.10] - 2026-04-16
 
 ### Added — Universal Context Auto-Pause (M37)

package/README.md

@@ -14,14 +14,10 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Self-learning rule engine** — declarative rules in rules.jsonl detect failure patterns from task metrics. Candidate patches progress through a 5-stage lifecycle (candidate, applied, measured, promoted, graduated) with >55% improvement gates before becoming permanent methodology artifacts.
 **Cross-project learning** — proven rules propagate to `~/.claude/metrics/` and sync across all registered projects via `update-all`. Rules validated in 3+ projects become universal; 5+ projects qualify for npm distribution. Cross-project signal comparison and global ELO rankings available via `gsd-t-metrics --cross-project` and `gsd-t-status`.
 **Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Includes **design-to-code** rules for pixel-perfect frontend implementation from Figma, screenshots, or design images — with Figma MCP integration, design token extraction, stack capability evaluation, and mandatory visual verification: every screen is rendered in a real browser, screenshotted at mobile/tablet/desktop, and compared pixel-by-pixel against the Figma design. Auto-bootstraps during partition when design references are detected. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
-**Self-Calibrating QA** — `qa-calibrator.js` tracks QA miss-rates across milestones, detects weak-spot categories (error paths, boundaries, state transitions), and automatically injects targeted guidance into QA subagent prompts. Projects on the same stack share miss-rate data for faster calibration.
-**Runway-Protected Execution (M35, v2.76.10)** — three-band token budget (`normal` < 70%, `warn` 70–85%, `stop` ≥ 85%) with **zero silent quality degradation**. No model downgrades, no phase skips under pressure. Instead:
+**Headless-by-Default Spawn (M38, v3.12.10)** — long-running workflow commands (execute, wave, integrate, debug repair loops) spawn detached by default via the unattended supervisor. The interactive session prints a launch banner, logs the event-stream path, and exits. Pass `--watch` to keep a live status block in the session (270s `ScheduleWakeup` ticks, cache-window-safe). The supervisor emits JSONL events to `.gsd-t/events/YYYY-MM-DD.jsonl` at every phase boundary — shared by watch command and dashboard. See `.gsd-t/contracts/headless-default-contract.md` v1.0.0 and `unattended-event-stream-contract.md` v1.0.0.
 - **Surgical model selection** — `bin/model-selector.js` assigns haiku/sonnet/opus per phase via a declarative rules table; `/advisor` escalation path with convention-based fallback.
-- **Pre-flight runway estimator** — `bin/runway-estimator.js` reads per-spawn token telemetry and projects whether a long-running command would cross 85%. If yes, the run is refused *before burning any tokens*.
-- **Headless auto-spawn on refusal** — `bin/headless-auto-spawn.js` detaches a child process to continue the work in a fresh context. The interactive session never sees a `/clear` prompt.
-- **Per-spawn token telemetry** — `.gsd-t/token-metrics.jsonl` records one 18-field row per Task subagent spawn. Feeds the runway estimator and the retrospective optimization backlog.
-- **Optimization backlog** — `bin/token-optimizer.js` runs at `complete-milestone` and appends model-tier recalibration recommendations (`demote`, `escalate`, `runway-tune`, `investigate`) to `.gsd-t/optimization-backlog.md`. **Never auto-applies.** User promotes via `/user:gsd-t-optimization-apply {ID}` or dismisses via `/user:gsd-t-optimization-reject {ID} [--reason "..."]` with a 5-milestone cooldown.
-**Context Meter (M34)** — real-time context window measurement via the Anthropic `count_tokens` API. A PostToolUse hook streams the current transcript to `count_tokens`, writes the exact input-token count and threshold band to `.gsd-t/.context-meter-state.json`, and `token-budget.getSessionStatus()` reads that state file as the authoritative context-burn signal. Replaces the v2.74.12 task-counter proxy. Requires an `ANTHROPIC_API_KEY` — `gsd-t doctor` hard-gates on it. See the Context Meter Setup section below.
+- **Per-spawn token telemetry** — `.gsd-t/token-metrics.jsonl` records one 18-field row per Task subagent spawn.
+**Context Meter (M34/M38)** — PostToolUse hook writes `.gsd-t/.context-meter-state.json` via local token estimation. Single-band model (`context-meter-contract.md` v1.3.0): one threshold (default 85%), one action — hand off to a detached headless spawn. The meter informs spawn-time routing, not in-flight pauses.
 **Quality North Star** — projects define a `## Quality North Star` section in CLAUDE.md (1–3 sentences, e.g., "This is a published npm library. Every public API must be intuitive and backward-compatible."). `gsd-t-init` auto-detects preset (library/web-app/cli) from package.json signals; `gsd-t-setup` configures it for existing projects. Subagents read it as a quality lens; absent = silent skip (backward compatible).
 **Design Brief Artifact** — during partition, UI/frontend projects (React, Vue, Svelte, Flutter, Tailwind) automatically get `.gsd-t/contracts/design-brief.md` with color palette, typography, spacing system, component patterns, and tone/voice. Non-UI projects skip silently. User-customized briefs are preserved. Referenced in plan phase for visual consistency.
 **Design Verification Agent** — after QA passes on design-to-code projects, a dedicated verification agent opens a browser with both the built frontend AND the original design (Figma page, design image, or MCP screenshot) side-by-side for direct visual comparison. Produces a structured element-by-element comparison table (30+ rows) with specific design values vs. implementation values and MATCH/DEVIATION verdicts. An artifact gate enforces that the comparison table exists — missing it blocks completion. Separation of concerns: coding agents code, verification agents verify. Wired into execute (Step 5.25) and quick (Step 5.25). Only fires when `.gsd-t/contracts/design-contract.md` exists — non-design projects are unaffected.
@@ -37,7 +33,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 51 GSD-T commands + 5 utility commands (56 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 49 GSD-T commands + 5 utility commands (54 total) to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -192,7 +188,6 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-status` | Cross-domain progress view with token breakdown by domain/task/phase | Manual |
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
 | `/user:gsd-t-quick` | Fast task with GSD-T guarantees | Manual |
-| `/user:gsd-t-reflect` | Generate retrospective from event stream, propose memory updates | Manual |
 | `/user:gsd-t-visualize` | Launch browser dashboard — SSE server + React Flow agent visualization | Manual |
 | `/user:gsd-t-debug` | Systematic debugging with state | Manual |
 | `/user:gsd-t-metrics` | View task telemetry, process ELO, signal distribution, domain health, and cross-project comparison (`--cross-project`) | Manual |
@@ -202,7 +197,6 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-version-update` | Update GSD-T to latest version | Manual |
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
 | `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches | Manual |
-| `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components | Manual |
 | `/user:gsd-t-design-audit` | Compare built screen against Figma design — structured deviation report | Manual |
 | `/user:gsd-t-design-build` | Build from design contracts with two-terminal review (Term 1 builder) | Manual |
 | `/user:gsd-t-design-review` | Independent review agent for design build (Term 2 reviewer) | Auto |

package/bin/event-stream.cjs

@@ -0,0 +1,205 @@
+/**
+ * bin/event-stream.cjs
+ *
+ * Structured event stream for the unattended supervisor watch-tick (M38 ES).
+ * Workers append events to `.gsd-t/events/YYYY-MM-DD.jsonl`; watch tick reads
+ * new events since the persisted cursor.
+ *
+ * Contract: `.gsd-t/contracts/unattended-event-stream-contract.md` v1.0.0.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const EVENTS_DIR_REL = path.join(".gsd-t", "events");
+const CURSOR_PATH_REL = path.join(".gsd-t", ".unattended", "event-cursor");
+
+function eventsDir(projectDir) {
+  return path.join(projectDir, EVENTS_DIR_REL);
+}
+
+function cursorPath(projectDir) {
+  return path.join(projectDir, CURSOR_PATH_REL);
+}
+
+function todayFileDate(now) {
+  const d = now || new Date();
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+function eventFileFor(projectDir, fileDate) {
+  return path.join(eventsDir(projectDir), `${fileDate}.jsonl`);
+}
+
+/**
+ * Append one event to today's jsonl file. Atomic via append-only write with
+ * a newline-terminated record. Never throws — failures are logged to stderr.
+ *
+ * @param {string} projectDir
+ * @param {object} eventObj  — `type`, `iter`, `source`, plus type-specific fields
+ * @returns {boolean} true on success, false on failure
+ */
+function appendEvent(projectDir, eventObj) {
+  try {
+    if (!eventObj || typeof eventObj !== "object") return false;
+    const ev = Object.assign({}, eventObj);
+    if (typeof ev.ts !== "string" || !ev.ts) {
+      ev.ts = new Date().toISOString();
+    }
+    const dir = eventsDir(projectDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const fileDate = todayFileDate(new Date(ev.ts));
+    const file = eventFileFor(projectDir, fileDate);
+    const line = JSON.stringify(ev) + "\n";
+    fs.appendFileSync(file, line, "utf8");
+    return true;
+  } catch (err) {
+    try {
+      process.stderr.write(`[event-stream] appendEvent failed: ${err.message}\n`);
+    } catch (_) { /* ignore */ }
+    return false;
+  }
+}
+
+function readCursor(projectDir) {
+  try {
+    const raw = fs.readFileSync(cursorPath(projectDir), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.fileDate === "string" && Number.isFinite(parsed.offset)) {
+      return parsed;
+    }
+  } catch (_) { /* missing or malformed → treated as uninitialized */ }
+  return null;
+}
+
+function writeCursor(projectDir, cursor) {
+  try {
+    const p = cursorPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(cursor), "utf8");
+    fs.renameSync(tmp, p);
+    return true;
+  } catch (err) {
+    try {
+      process.stderr.write(`[event-stream] writeCursor failed: ${err.message}\n`);
+    } catch (_) { /* ignore */ }
+    return false;
+  }
+}
+
+function fileSize(p) {
+  try {
+    return fs.statSync(p).size;
+  } catch (_) {
+    return 0;
+  }
+}
+
+function parseJsonlSlice(buf) {
+  const text = buf.toString("utf8");
+  const lines = text.split("\n");
+  const hasPartialTail = text.length > 0 && !text.endsWith("\n");
+  const consumable = hasPartialTail ? lines.slice(0, -1) : lines;
+  const events = [];
+  for (const line of consumable) {
+    if (!line) continue;
+    try {
+      events.push(JSON.parse(line));
+    } catch (_) {
+      try {
+        process.stderr.write(`[event-stream] skipping malformed line\n`);
+      } catch (__) { /* ignore */ }
+    }
+  }
+  const consumedBytes = hasPartialTail
+    ? Buffer.byteLength(consumable.join("\n") + (consumable.length ? "\n" : ""), "utf8")
+    : buf.length;
+  return { events, consumedBytes };
+}
+
+function readSlice(filePath, startOffset) {
+  const size = fileSize(filePath);
+  if (size <= startOffset) return { events: [], consumedBytes: 0, fileSize: size };
+  const fd = fs.openSync(filePath, "r");
+  try {
+    const length = size - startOffset;
+    const buf = Buffer.alloc(length);
+    fs.readSync(fd, buf, 0, length, startOffset);
+    const { events, consumedBytes } = parseJsonlSlice(buf);
+    return { events, consumedBytes, fileSize: size };
+  } finally {
+    try { fs.closeSync(fd); } catch (_) { /* ignore */ }
+  }
+}
+
+/**
+ * Read all events from cursor to EOF. Handles day-boundary per contract §3:
+ * if cursor points to a past file date, read remaining events from that file,
+ * then read today's file from byte 0; advance cursor to today's EOF.
+ *
+ * If cursor is missing, initialize to today's file at current EOF (no backlog
+ * surfaced on first read — matches contract §3 initial-cursor behavior).
+ *
+ * @param {string} projectDir
+ * @returns {{events: object[], newCursor: {fileDate: string, offset: number}}}
+ */
+function readSinceCursor(projectDir) {
+  const today = todayFileDate(new Date());
+  let cursor = readCursor(projectDir);
+  if (!cursor) {
+    const todayFile = eventFileFor(projectDir, today);
+    const size = fileSize(todayFile);
+    const newCursor = { fileDate: today, offset: size };
+    writeCursor(projectDir, newCursor);
+    return { events: [], newCursor };
+  }
+
+  const result = [];
+  let { fileDate, offset } = cursor;
+
+  if (fileDate !== today) {
+    const prev = eventFileFor(projectDir, fileDate);
+    if (fs.existsSync(prev)) {
+      const slice = readSlice(prev, offset);
+      result.push(...slice.events);
+    }
+    fileDate = today;
+    offset = 0;
+  }
+
+  const todayFile = eventFileFor(projectDir, today);
+  if (fs.existsSync(todayFile)) {
+    const slice = readSlice(todayFile, offset);
+    result.push(...slice.events);
+    offset = offset + slice.consumedBytes;
+  } else {
+    return { events: result, newCursor: { fileDate, offset } };
+  }
+
+  return { events: result, newCursor: { fileDate, offset } };
+}
+
+/**
+ * Persist the cursor returned by readSinceCursor.
+ * @param {string} projectDir
+ * @param {{fileDate: string, offset: number}} newCursor
+ */
+function advanceCursor(projectDir, newCursor) {
+  if (!newCursor || typeof newCursor.fileDate !== "string" || !Number.isFinite(newCursor.offset)) {
+    return false;
+  }
+  return writeCursor(projectDir, newCursor);
+}
+
+module.exports = {
+  appendEvent,
+  readSinceCursor,
+  advanceCursor,
+  _internal: { todayFileDate, eventsDir, cursorPath, readCursor, writeCursor },
+};

package/bin/gsd-t-unattended.cjs

@@ -55,6 +55,13 @@ const {
   notify,
 } = require("./gsd-t-unattended-platform.cjs");
 
+// 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";
@@ -476,7 +483,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) ─────────────────────
@@ -866,6 +898,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, {
@@ -903,6 +945,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.
@@ -941,6 +1006,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) {
@@ -957,9 +1029,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-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