@tekyzinc/gsd-t 2.74.13 → 3.10.10

package/docs/unattended-windows-caveats.md

@@ -0,0 +1,245 @@
+# Unattended Supervisor — Windows Caveats (v1.0.0)
+
+**Status**: Windows support is **shipping but caveated** in v1.0.0.
+
+**Contract reference**: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0
+**Platform module**: `bin/gsd-t-unattended-platform.js`
+
+---
+
+## 0. Required Software (All Platforms)
+
+The launch command (`/user:gsd-t-unattended`) pre-flights required software in
+Step 1e and refuses to spawn if anything is missing. Install these before
+launching:
+
+**Required everywhere (hard-fail):**
+
+| Tool    | Install                                                       |
+|---------|---------------------------------------------------------------|
+| node    | https://nodejs.org (>= 16)                                    |
+| claude  | `npm install -g @anthropic-ai/claude-code`                    |
+| git     | https://git-scm.com/downloads                                 |
+
+**macOS — soft warnings (install for best reliability):**
+
+| Tool        | Purpose                  | Install             |
+|-------------|--------------------------|---------------------|
+| caffeinate  | sleep prevention          | built-in (Apple)    |
+
+**Linux — soft warnings:**
+
+| Tool                      | Purpose                     | Install                                    |
+|---------------------------|-----------------------------|--------------------------------------------|
+| systemd-inhibit OR caffeine | sleep/screen-lock prevention | usually preinstalled; else `sudo apt install caffeine` |
+| notify-send               | desktop notifications        | `sudo apt install libnotify-bin`           |
+
+**Windows — soft warnings:**
+
+| Tool               | Purpose                      | Install                                |
+|--------------------|------------------------------|----------------------------------------|
+| PowerShell         | sleep prevention (built-in)  | ships with Windows                     |
+| BurntToast         | real toast notifications     | `Install-Module BurntToast` (PowerShell) |
+
+If the pre-flight fails, the launcher prints each missing tool with its
+install instructions and refuses to spawn. Soft warnings are advisory only —
+the supervisor still launches without them, but with degraded resilience.
+
+---
+
+## 1. Overview
+
+The GSD-T unattended supervisor (M36) ships cross-platform. All core supervisor
+mechanics — the watch loop, state-file lifecycle, worker spawning, stop
+sentinel, and safety rails — run unchanged on Windows. The darwin and linux
+code paths are runtime-tested; the win32 code paths are
+**implementation-complete but not runtime-tested on the dev host (macOS)**.
+
+Three OS-integration surfaces have known limitations on Windows:
+
+1. **Sleep prevention** — no stock `caffeinate` equivalent ships with Windows.
+2. **Notifications** — `msg.exe` is a minimal fire-and-forget shim with real
+   delivery restrictions.
+3. **Process detach** — `spawn(..., { detached: true })` behaves differently
+   from POSIX and is not a true daemonization primitive.
+
+This document covers what works, what doesn't, the Spike C disposition, and
+the recommended usage pattern. Everything below applies to `win32` only;
+darwin and linux are unaffected.
+
+---
+
+## 2. Known Gaps
+
+### 2.1 Sleep prevention (no-op on win32)
+
+`preventSleep(reason)` in `bin/gsd-t-unattended-platform.js` explicitly
+**returns `null` on win32** and writes a one-line notice to stderr:
+
+```
+[platform] sleep prevention not implemented on win32 (see docs/unattended-windows-caveats.md)
+```
+
+Windows has no stock command-line equivalent of macOS `caffeinate`. The
+native API (`SetThreadExecutionState`) requires a C binding, which violates
+the GSD-T zero-external-dependency constraint for `bin/`. `releaseSleep(null)`
+is a safe no-op, so the supervisor still shuts down cleanly.
+
+**Consequence**: if a Windows machine is configured to sleep on its default
+power schedule, a long unattended run will pause (or outright fail) when the
+machine sleeps. The supervisor has no way to prevent this.
+
+**Workaround (v1)**: the user must configure Windows power settings manually
+to keep the machine awake for the duration of the run. Microsoft's official
+guidance covers both GUI and command-line approaches:
+
+- [powercfg command-line options](https://learn.microsoft.com/en-us/windows-hardware/design/device-experiences/powercfg-command-line-options)
+- [Change power plan settings](https://support.microsoft.com/en-us/windows/change-power-mode-for-your-windows-pc-c2aff038-22f9-f46a-8ca1-ba5be2b6a7b9)
+
+Useful examples:
+
+```powershell
+# Disable sleep while on AC power (requires admin)
+powercfg /change standby-timeout-ac 0
+
+# Disable sleep while on battery (requires admin)
+powercfg /change standby-timeout-dc 0
+```
+
+### 2.2 Notifications (`msg.exe`, interactive-session only)
+
+`notify(title, message, level)` in `bin/gsd-t-unattended-platform.js` uses
+`msg.exe * "title: message"` on win32 with `windowsHide: true`. This is a
+deliberate minimal fire-and-forget dependency: `msg.exe` ships with Windows
+and has zero install cost.
+
+**Restrictions**:
+
+- `msg.exe` only delivers to **interactive Windows sessions**. If the
+  supervisor is launched under a Windows Service, a non-interactive ssh
+  session, or any other session without a desktop attached, `msg.exe` will
+  silently drop the notification (or fail with an access error). The
+  supervisor core is unaffected — the `child.on('error', ...)` handler logs
+  the failure to stderr and the relay loop continues.
+- `msg.exe` is not a true toast / Action Center notification. It pops a
+  blocking message-box dialog into the active session. This is visible and
+  audible but is not the modern Windows notification experience.
+
+**Recommended v2 enhancement**: integrate a real toast API such as
+[`BurntToast`](https://github.com/Windos/BurntToast) (a PowerShell module).
+`BurntToast` requires an opt-in install, so it will remain behind a capability
+check; stock installs will fall back to `msg.exe`.
+
+### 2.3 Process detach (`detached: true` is not full daemonization)
+
+`spawnSupervisor({ binPath, args, cwd })` uses
+`spawn('node', [...], { detached: true, stdio: 'ignore', windowsHide: true })`
+followed by `child.unref()`. On **POSIX** (darwin / linux) this makes the
+child a new process-group leader and the supervisor survives the parent
+terminal closing. On **win32** the same options produce a separate process
+tree but do **not** fully detach the child from the launching console:
+
+- Closing the launching terminal window may still deliver a console
+  `CTRL_CLOSE_EVENT` to the child and terminate the supervisor.
+- Signing out of the user session will terminate the child along with every
+  other user process.
+- There is no equivalent of POSIX `setsid()` purely from Node's `spawn`
+  options.
+
+**Workarounds**:
+
+- Use `start /B` via a shell wrapper to launch the supervisor in a fully
+  background-detached process on the current session.
+- For truly-outlive-the-session runs, register the supervisor as a **Windows
+  Task Scheduler** task. Task Scheduler manages its own process lifetime
+  independent of the interactive session.
+- Run inside **WSL2** (see §5) to get POSIX detach semantics end-to-end.
+
+---
+
+## 3. Spike C Disposition — Sleep Prevention Alternatives
+
+Spike C was an exploratory investigation of Windows-native alternatives to
+`caffeinate`. The question: can we keep the zero-dependency constraint and
+still prevent sleep?
+
+Three candidates were evaluated:
+
+| Option | Mechanism | Verdict |
+|--------|-----------|---------|
+| `SetThreadExecutionState` Win32 API via `ffi` | Native API, exactly what caffeinate maps to. | **Reject.** Requires `ffi-napi` or equivalent — a C binding and a compiled native dep. Violates the zero-external-dependency constraint for `bin/`. |
+| `powercfg` toggle | CLI that ships with Windows. `powercfg /change standby-timeout-ac 0` before run, restore after. | **Reject.** Requires administrator privileges. Persists across runs if the supervisor crashes mid-run, leaving the machine in a modified power state. Hard to guarantee restoration. |
+| Task Scheduler "wake to run" / wake events | Scheduled task can force the machine to wake at interval. | **Defer.** Best user-space path but adds non-trivial scheduler management code (create task, tear down on exit, handle orphaned tasks). |
+
+**Verdict**: **defer to v2.** v1.0.0 ships with the `null`-handle + documentation
+approach described in §2.1. v2 will consider Task Scheduler integration as the
+primary path, since it is the only candidate that is both user-space and
+compatible with the zero-dependency constraint.
+
+---
+
+## 4. What Works Today on Windows
+
+All of the following run on Windows with no caveats (pending runtime testing
+on a real Windows host; implementation is complete):
+
+- **Core supervisor process** — runs to completion, observes the state file,
+  dispatches workers, honours the watch-loop cadence, and exits cleanly.
+- **State file lifecycle** — atomic write, lockfile, heartbeat updates, and
+  teardown all use Node built-ins and behave identically on win32.
+- **Worker spawning** — `spawnWorker(projectDir, timeoutMs)` uses `claude.cmd`
+  via `resolveClaudePath()` with `shell: false` and `windowsHide: true`, which
+  avoids the Spike C PowerShell quoting hazard.
+- **Stop sentinel** — sentinel-file detection is filesystem-based and is
+  cross-platform by construction.
+- **Safety rails** — `isAlive(pid)` uses Node's `process.kill(pid, 0)`, which
+  implements POSIX signal-0 semantics on Windows. Liveness checks, watchdog
+  timers, and stuck-worker detection all work unchanged.
+
+Exit code table (contract §5), heartbeat contract, and the launch-handshake
+file contract are all platform-agnostic and fully honoured on win32.
+
+---
+
+## 5. Recommended Usage Pattern on Windows
+
+Given the gaps above, the recommended way to run the unattended supervisor on
+Windows for v1.0.0 is:
+
+1. **Run on a desktop that never sleeps.** Configure Windows power settings so
+   the machine will not sleep, hibernate, or turn off the display for the
+   expected duration of the run. Use `powercfg` or the Settings UI (see §2.1).
+2. **Launch from an interactive PowerShell session** (not a Windows Service,
+   not a non-interactive ssh session). This ensures `msg.exe` notifications
+   can be delivered and that the supervisor's stderr diagnostics are visible.
+3. **Monitor via the watch-tick command from the same interactive session.**
+   Do not close the launching terminal until the supervisor exits — see §2.3
+   for why.
+4. **Consider running inside WSL2** instead of native Windows. WSL2 provides a
+   full Linux userland where `bin/gsd-t-unattended-platform.js` takes the
+   `linux` branch everywhere: `isAlive`, `spawnWorker`, `spawnSupervisor`, and
+   `notify` all behave with POSIX semantics end-to-end. The only remaining gap
+   in WSL2 is sleep prevention (linux also returns `null` from `preventSleep`
+   in v1.0.0), which is still governed by the host Windows machine's power
+   settings. WSL2 is currently the closest thing to the full darwin / linux
+   feature set on a Windows box.
+
+---
+
+## 6. Summary Matrix
+
+| Feature                  | darwin    | linux     | win32                                          |
+|--------------------------|-----------|-----------|------------------------------------------------|
+| `resolveClaudePath`      | `claude`  | `claude`  | `claude.cmd`                                   |
+| `isAlive(pid)`           | works     | works     | works (POSIX signal-0 semantics)               |
+| `spawnWorker`            | works     | works     | implementation-complete, untested on real host |
+| `spawnSupervisor` detach | full      | full      | partial — console-close may kill child         |
+| `preventSleep`           | works     | null (v1) | null (v1) — see §2.1 and §3                    |
+| `releaseSleep`           | works     | no-op     | no-op                                          |
+| `notify`                 | works     | works     | works only in interactive sessions (§2.2)      |
+
+**v2 roadmap (non-binding)**:
+- Linux: opt-in `systemd-inhibit` for sleep prevention.
+- Windows: Task Scheduler integration for sleep prevention; `BurntToast`
+  capability check for real toast notifications; optional Task-Scheduler-based
+  daemonization path for true detachment.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.74.13",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 56 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
+  "version": "3.10.10",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 61 slash commands with unattended supervisor relay, headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {

package/scripts/context-meter/count-tokens-client.js

@@ -0,0 +1,221 @@
+/**
+ * count-tokens-client.js
+ *
+ * Zero-dependency Node.js client for Anthropic's `POST /v1/messages/count_tokens`
+ * endpoint. Built on the built-in `https` / `http` modules so the Context Meter
+ * hook ships with no runtime dependencies.
+ *
+ * Contract: `.gsd-t/contracts/context-meter-contract.md` — "count_tokens API usage"
+ *
+ * Design notes:
+ *
+ *   - Every failure mode returns `null`. The caller (the hook in Task 4) treats
+ *     `null` as "fail open" — it simply emits `{}` on stdout and Claude is never
+ *     blocked. This function NEVER throws.
+ *
+ *   - The `system` field on the Messages API rejects an empty string
+ *     (`system: ""` → 400). The `{ system, messages }` shape produced by
+ *     `transcript-parser.js` starts with an empty system string when the
+ *     transcript has no system blocks, so this client DROPS the `system` key
+ *     from the request body when the input is an empty string. Any non-empty
+ *     system is forwarded as-is.
+ *
+ *   - The hard timeout uses `req.setTimeout(ms)`; on fire we `req.destroy()` to
+ *     release the socket and return `null`. Without the explicit destroy the
+ *     socket can linger for the OS-level keep-alive window, which matters when
+ *     the hook is already at its ~200ms latency budget.
+ *
+ *   - We NEVER log the request body. The only diagnostic signal this module
+ *     produces is the returned value itself (`null` on failure). Any logging
+ *     is the caller's responsibility — the hook writes to `logPath` per config.
+ *
+ *   - A hidden `_baseUrl` option lets the tests point the client at a local
+ *     stub HTTP server bound to `127.0.0.1:0`. Production callers never pass
+ *     `_baseUrl`. Parsing uses `URL` so either http or https works transparently.
+ *
+ * @module scripts/context-meter/count-tokens-client
+ */
+
+"use strict";
+
+const https = require("https");
+const http = require("http");
+const { URL } = require("url");
+
+const DEFAULT_BASE_URL = "https://api.anthropic.com";
+const COUNT_TOKENS_PATH = "/v1/messages/count_tokens";
+const ANTHROPIC_VERSION = "2023-06-01";
+
+/**
+ * Call Anthropic count_tokens.
+ *
+ * @param {object} opts
+ * @param {string} opts.apiKey - Anthropic API key (from env var named in config)
+ * @param {string} opts.model - model id, e.g. "claude-opus-4-6"
+ * @param {string} opts.system - system prompt text; dropped from body if ""
+ * @param {Array}  opts.messages - messages array from transcript-parser.js
+ * @param {number} opts.timeoutMs - hard timeout for the whole request
+ * @param {string} [opts._baseUrl] - TEST ONLY: override the base URL
+ * @returns {Promise<{inputTokens: number} | null>} tokens on success, null on any failure
+ */
+function countTokens(opts) {
+  return new Promise((resolve) => {
+    // Single outer try/catch — any synchronous throw below becomes `null`.
+    try {
+      if (!opts || typeof opts !== "object") {
+        resolve(null);
+        return;
+      }
+
+      const {
+        apiKey,
+        model,
+        system,
+        messages,
+        timeoutMs,
+        _baseUrl,
+      } = opts;
+
+      if (typeof apiKey !== "string" || apiKey.length === 0) {
+        resolve(null);
+        return;
+      }
+      if (typeof model !== "string" || model.length === 0) {
+        resolve(null);
+        return;
+      }
+      if (!Array.isArray(messages)) {
+        resolve(null);
+        return;
+      }
+      if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        resolve(null);
+        return;
+      }
+
+      // Build request body. Drop `system` when it's an empty string —
+      // the endpoint rejects `system: ""` with a 400.
+      const body = { model, messages };
+      if (typeof system === "string" && system.length > 0) {
+        body.system = system;
+      } else if (system != null && typeof system !== "string") {
+        // Unusual shape — do not forward.
+        resolve(null);
+        return;
+      }
+
+      let payload;
+      try {
+        payload = JSON.stringify(body);
+      } catch (_) {
+        resolve(null);
+        return;
+      }
+
+      // Parse base URL — test code passes http://127.0.0.1:<port>, prod uses https.
+      let parsed;
+      try {
+        parsed = new URL(COUNT_TOKENS_PATH, _baseUrl || DEFAULT_BASE_URL);
+      } catch (_) {
+        resolve(null);
+        return;
+      }
+
+      const isHttps = parsed.protocol === "https:";
+      const transport = isHttps ? https : http;
+
+      const reqOptions = {
+        method: "POST",
+        hostname: parsed.hostname,
+        port: parsed.port || (isHttps ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        headers: {
+          "x-api-key": apiKey,
+          "anthropic-version": ANTHROPIC_VERSION,
+          "content-type": "application/json",
+          "content-length": Buffer.byteLength(payload),
+        },
+      };
+
+      let settled = false;
+      const settle = (value) => {
+        if (settled) return;
+        settled = true;
+        resolve(value);
+      };
+
+      let req;
+      try {
+        req = transport.request(reqOptions, (res) => {
+          const status = res.statusCode || 0;
+          const chunks = [];
+          res.on("data", (chunk) => {
+            chunks.push(chunk);
+          });
+          res.on("end", () => {
+            if (status !== 200) {
+              // 401 / 403 / 429 / 5xx — fail open silently.
+              settle(null);
+              return;
+            }
+            let text;
+            try {
+              text = Buffer.concat(chunks).toString("utf8");
+            } catch (_) {
+              settle(null);
+              return;
+            }
+            let parsedBody;
+            try {
+              parsedBody = JSON.parse(text);
+            } catch (_) {
+              settle(null);
+              return;
+            }
+            if (!parsedBody || typeof parsedBody !== "object") {
+              settle(null);
+              return;
+            }
+            const n = Number(parsedBody.input_tokens);
+            if (!Number.isFinite(n)) {
+              settle(null);
+              return;
+            }
+            settle({ inputTokens: n });
+          });
+          res.on("error", () => {
+            settle(null);
+          });
+        });
+      } catch (_) {
+        settle(null);
+        return;
+      }
+
+      req.on("error", () => {
+        settle(null);
+      });
+
+      req.setTimeout(timeoutMs, () => {
+        // Destroy the socket so it doesn't linger beyond the hook's latency budget.
+        try {
+          req.destroy();
+        } catch (_) {
+          /* ignore */
+        }
+        settle(null);
+      });
+
+      try {
+        req.write(payload);
+        req.end();
+      } catch (_) {
+        settle(null);
+      }
+    } catch (_) {
+      resolve(null);
+    }
+  });
+}
+
+module.exports = { countTokens };