@tekyzinc/gsd-t 3.29.11 → 4.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +146 -0
  2. package/bin/gsd-t-parallel.cjs +64 -13
  3. package/bin/gsd-t.js +48 -376
  4. package/bin/journey-coverage.cjs +6 -3
  5. package/bin/parallel-cli.cjs +13 -1
  6. package/commands/gsd-t-debug.md +47 -533
  7. package/commands/gsd-t-design-decompose.md +24 -497
  8. package/commands/gsd-t-doc-ripple.md +23 -139
  9. package/commands/gsd-t-execute.md +41 -958
  10. package/commands/gsd-t-help.md +0 -2
  11. package/commands/gsd-t-impact.md +26 -295
  12. package/commands/gsd-t-integrate.md +44 -369
  13. package/commands/gsd-t-milestone.md +25 -124
  14. package/commands/gsd-t-partition.md +28 -539
  15. package/commands/gsd-t-plan.md +26 -472
  16. package/commands/gsd-t-prd.md +25 -311
  17. package/commands/gsd-t-quick.md +1 -1
  18. package/commands/gsd-t-resume.md +0 -33
  19. package/commands/gsd-t-verify.md +52 -569
  20. package/commands/gsd-t-wave.md +41 -430
  21. package/package.json +1 -1
  22. package/scripts/gsd-t-calibration-hook.js +3 -1
  23. package/scripts/hooks/pre-commit-journey-coverage +0 -2
  24. package/scripts/hooks/pre-commit-playwright-gate +0 -2
  25. package/templates/CLAUDE-global.md +43 -173
  26. package/templates/CLAUDE-project.md +118 -104
  27. package/templates/prompts/design-verify-subagent.md +3 -0
  28. package/templates/prompts/qa-subagent.md +3 -0
  29. package/templates/prompts/red-team-subagent.md +5 -2
  30. package/templates/workflows/_lib.js +176 -0
  31. package/templates/workflows/gsd-t-debug.workflow.js +86 -0
  32. package/templates/workflows/gsd-t-execute.workflow.js +206 -0
  33. package/templates/workflows/gsd-t-integrate.workflow.js +71 -0
  34. package/templates/workflows/gsd-t-phase.workflow.js +94 -0
  35. package/templates/workflows/gsd-t-quick.workflow.js +72 -0
  36. package/templates/workflows/gsd-t-verify.workflow.js +348 -0
  37. package/templates/workflows/gsd-t-wave.workflow.js +43 -0
  38. package/bin/check-headless-sessions.js +0 -140
  39. package/bin/context-budget-audit.cjs +0 -447
  40. package/bin/context-meter-config.cjs +0 -101
  41. package/bin/context-meter-config.test.cjs +0 -101
  42. package/bin/event-stream.cjs +0 -205
  43. package/bin/gsd-t-benchmark-orchestrator.js +0 -437
  44. package/bin/gsd-t-capture-lint.cjs +0 -440
  45. package/bin/gsd-t-economics.cjs +0 -315
  46. package/bin/gsd-t-in-session-usage.cjs +0 -213
  47. package/bin/gsd-t-orchestrator-config.cjs +0 -161
  48. package/bin/gsd-t-orchestrator-queue.cjs +0 -180
  49. package/bin/gsd-t-orchestrator-recover.cjs +0 -231
  50. package/bin/gsd-t-orchestrator-worker.cjs +0 -219
  51. package/bin/gsd-t-orchestrator.js +0 -535
  52. package/bin/gsd-t-parallel-probe.cjs +0 -132
  53. package/bin/gsd-t-ratelimit-probe-worker.cjs +0 -237
  54. package/bin/gsd-t-ratelimit-probe.cjs +0 -648
  55. package/bin/gsd-t-report-tokens.cjs +0 -549
  56. package/bin/gsd-t-stream-feed-client.cjs +0 -151
  57. package/bin/gsd-t-token-backfill.cjs +0 -366
  58. package/bin/gsd-t-token-capture.cjs +0 -321
  59. package/bin/gsd-t-token-dashboard.cjs +0 -353
  60. package/bin/gsd-t-token-regenerate-log.cjs +0 -129
  61. package/bin/gsd-t-tool-attribution.cjs +0 -377
  62. package/bin/gsd-t-tool-cost.cjs +0 -195
  63. package/bin/gsd-t-transcript-tee.cjs +0 -246
  64. package/bin/gsd-t-unattended-heartbeat.cjs +0 -188
  65. package/bin/gsd-t-unattended-platform.cjs +0 -551
  66. package/bin/gsd-t-unattended-platform.js +0 -381
  67. package/bin/gsd-t-unattended-safety.cjs +0 -773
  68. package/bin/gsd-t-unattended-safety.js +0 -788
  69. package/bin/gsd-t-unattended.cjs +0 -2109
  70. package/bin/gsd-t-unattended.js +0 -1367
  71. package/bin/gsd-t-worker-dispatch.cjs +0 -211
  72. package/bin/handoff-lock.cjs +0 -249
  73. package/bin/handoff-lock.js +0 -249
  74. package/bin/headless-auto-spawn.cjs +0 -711
  75. package/bin/headless-auto-spawn.js +0 -373
  76. package/bin/headless-exit-codes.cjs +0 -67
  77. package/bin/live-activity-report.cjs +0 -615
  78. package/bin/log-tail.cjs +0 -81
  79. package/bin/m44-proof-measure.cjs +0 -285
  80. package/bin/m46-iter-proof.cjs +0 -149
  81. package/bin/m46-worker-proof.cjs +0 -201
  82. package/bin/m55-substrate-proof.cjs +0 -134
  83. package/bin/metrics-rollup.js +0 -200
  84. package/bin/model-windows.cjs +0 -99
  85. package/bin/model-windows.test.cjs +0 -75
  86. package/bin/parallelism-report.cjs +0 -535
  87. package/bin/runway-estimator.cjs +0 -242
  88. package/bin/spawn-plan-derive.cjs +0 -163
  89. package/bin/spawn-plan-status-updater.cjs +0 -292
  90. package/bin/spawn-plan-writer.cjs +0 -204
  91. package/bin/supervisor-pid-fingerprint.cjs +0 -126
  92. package/bin/token-budget.cjs +0 -265
  93. package/bin/unattended-watch-format.cjs +0 -178
  94. package/bin/watch-progress.js +0 -155
  95. package/commands/gsd-t-unattended-stop.md +0 -85
  96. package/commands/gsd-t-unattended-watch.md +0 -465
  97. package/commands/gsd-t-unattended.md +0 -476
  98. package/commands/gsd-t-visualize.md +0 -116
  99. package/scripts/gsd-t-context-meter.e2e.test.js +0 -364
  100. package/scripts/gsd-t-context-meter.js +0 -341
  101. package/scripts/gsd-t-context-meter.test.js +0 -471
  102. package/scripts/gsd-t-dashboard-server.js +0 -1203
  103. package/scripts/gsd-t-post-commit-spawn-plan.sh +0 -86
  104. package/scripts/gsd-t-transcript.html +0 -1821
  105. package/scripts/hooks/gsd-t-conversation-capture.js +0 -439
  106. package/scripts/hooks/gsd-t-in-session-usage-hook.js +0 -84
  107. package/scripts/spawn-plan-fmt-tokens.cjs +0 -80
  108. package/templates/hooks/post-commit-spawn-plan.sh +0 -85
@@ -1,476 +0,0 @@
1
- # GSD-T: Unattended — Launch the Background Supervisor
2
-
3
- **Model**: sonnet (pre-flight reasoning + spawn coordination)
4
-
5
- You are launching the GSD-T unattended supervisor — a detached background process that drives the active milestone to completion by spawning `claude -p` worker iterations in a relay, without human intervention. The supervisor runs outside the interactive Claude session and survives `/clear`, terminal close, and session expiry.
6
-
7
- This command performs pre-flight checks, spawns the supervisor via the cross-platform helper, verifies liveness, displays the initial status block, and schedules the first watch tick. It then returns — the watch loop takes over.
8
-
9
- See `unattended-supervisor-contract.md` §7 (Launch Handshake), §4 (Status Enum), §3 (state.json schema).
10
-
11
- ## Step 1: Pre-Flight Checks
12
-
13
- ```bash
14
- node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-unattended --step 1 --step-label "Pre-Flight Checks" 2>/dev/null || true
15
- ```
16
-
17
- ### 1a: Verify GSD-T Project
18
-
19
- Run via Bash:
20
-
21
- ```bash
22
- if [ ! -f ".gsd-t/progress.md" ]; then
23
- echo "ERROR: .gsd-t/progress.md not found — not a GSD-T project. Run /gsd-t-init first."
24
- exit 1
25
- fi
26
- ```
27
-
28
- If the file is missing, stop immediately with the error above. Do NOT proceed.
29
-
30
- ### 1b: Check for an Already-Running Supervisor
31
-
32
- Run via Bash:
33
-
34
- ```bash
35
- node -e "
36
- const fs = require('fs');
37
- const PID_FILE = '.gsd-t/.unattended/supervisor.pid';
38
-
39
- if (!fs.existsSync(PID_FILE)) {
40
- console.log('PID_RUNNING=false');
41
- process.exit(0);
42
- }
43
-
44
- let pid = null;
45
- try {
46
- const { readPidFile } = require('./bin/supervisor-pid-fingerprint.cjs');
47
- const entry = readPidFile(process.cwd());
48
- pid = entry && Number.isInteger(entry.pid) ? entry.pid : null;
49
- } catch (_) {}
50
-
51
- if (!pid || !Number.isFinite(pid)) {
52
- console.log('PID_RUNNING=false');
53
- process.exit(0);
54
- }
55
-
56
- let alive = false;
57
- try { process.kill(pid, 0); alive = true; }
58
- catch (e) { alive = e.code === 'EPERM'; }
59
-
60
- console.log('PID_RUNNING=' + alive);
61
- console.log('PID=' + pid);
62
- "
63
- ```
64
-
65
- If `PID_RUNNING=true`, **STOP** and print:
66
-
67
- ```
68
- 🔴 Unattended supervisor is already running (PID {PID}).
69
-
70
- Use /gsd-t-unattended-stop to request a clean halt, then wait for the
71
- watch loop to confirm it has stopped before relaunching.
72
-
73
- To just watch the current run: /gsd-t-unattended-watch
74
- ```
75
-
76
- Do NOT spawn a second supervisor. End the turn.
77
-
78
- ### 1c: Parse Arguments and Resolve Milestone
79
-
80
- Parse `$ARGUMENTS` for:
81
- - `--hours=N` — wall-clock cap in hours (default: `24`)
82
- - `--milestone=LABEL` — milestone to drive (default: read from `.gsd-t/progress.md`)
83
- - `--max-iterations=N` — iteration cap (default: `200`)
84
- - `--dry-run` — preflight only; print what would be spawned, do NOT spawn
85
-
86
- **Persistent overrides**: create `.gsd-t/.unattended/config.json` to change
87
- defaults per-project (caps, protected branches, dirty-tree whitelist). CLI
88
- flags always win over the config file. See `docs/unattended-config.md` for
89
- the full schema and common recipes (e.g. `{"protectedBranches": []}` for
90
- solo projects that commit directly to main).
91
-
92
- Run via Bash to read the current milestone from progress.md:
93
-
94
- ```bash
95
- node -e "
96
- const fs = require('fs');
97
- let milestone = '';
98
- try {
99
- const text = fs.readFileSync('.gsd-t/progress.md', 'utf8');
100
- // Look for '## Current Milestone: M36' or 'Milestone: M36' patterns
101
- const m = text.match(/(?:##\s*)?(?:Current\s+)?Milestone[:\s]+(\S+)/i);
102
- if (m) milestone = m[1].replace(/[^A-Za-z0-9_.-]/g, '');
103
- } catch (_) {}
104
- console.log('MILESTONE=' + (milestone || 'unknown'));
105
- "
106
- ```
107
-
108
- Also read the project name from `package.json` (best-effort):
109
-
110
- ```bash
111
- node -e "
112
- try {
113
- const p = JSON.parse(require('fs').readFileSync('package.json', 'utf8'));
114
- console.log('PROJECT_NAME=' + (p.name || ''));
115
- } catch (_) {
116
- console.log('PROJECT_NAME=');
117
- }
118
- "
119
- ```
120
-
121
- ### 1c.1: Readiness Bootstrap (auto-complete pending state)
122
-
123
- **The unattended command must work from ANY workflow state.** If the user says "run unattended," that is an instruction to proceed — not an invitation to ask more questions. Regardless of where the project is in the GSD-T workflow (mid-discussion, pre-milestone, post-partition, between phases), the unattended supervisor should be able to pick up and continue.
124
-
125
- The `/gsd-t-resume` worker already knows how to chain through phases automatically. The only thing the unattended command needs is a milestone label in `progress.md` so the supervisor has a target.
126
-
127
- **If `MILESTONE=unknown`** (no active milestone found in progress.md):
128
-
129
- 1. **Look for a milestone** — check in priority order:
130
- a. `$ARGUMENTS` — if `--milestone=LABEL` was passed, use it.
131
- b. Conversation context — if the user discussed a milestone, feature, or work goal in this session, extract the milestone label from that discussion.
132
- c. `.gsd-t/progress.md` — check for any milestone mentioned anywhere (even if not in the standard "Current Milestone" format, e.g., a Decision Log entry like "created milestone M8").
133
- d. `.gsd-t/domains/` — if domains exist, infer the milestone from directory names or scope files.
134
-
135
- 2. **If a milestone is identifiable**:
136
- - Ensure `.gsd-t/progress.md` has a `## Current Milestone` section with the label and status `IN PROGRESS`. If missing, add it.
137
- - Run `gsd-t-init` silently to fill in any missing required files (it skips existing files).
138
- - Print: `ℹ️ Auto-bootstrapped milestone {LABEL} — supervisor workers will continue from current phase.`
139
- - Re-read the milestone label.
140
-
141
- 3. **If no milestone is identifiable at all**:
142
- - Print:
143
- ```
144
- ❌ No active milestone found and none identifiable from context.
145
-
146
- Specify one explicitly: /gsd-t-unattended --milestone=M1
147
- ```
148
- - **STOP.** Do NOT spawn.
149
-
150
- **If `MILESTONE` was found but progress.md shows a pre-execution phase** (e.g., milestone was just created, no partition/plan/domains yet): that's fine — proceed with the spawn. The `/gsd-t-resume` worker will read the current state and advance through partition → plan → execute → ... automatically. The unattended command should never second-guess the resume logic or add pre-conditions beyond "a milestone exists."
151
-
152
- ### 1d: Check for Stale Stop Sentinel
153
-
154
- If `.gsd-t/.unattended/stop` exists from a previous run, remove it before spawning (per contract §10 — the launch command cleans the stale sentinel):
155
-
156
- ```bash
157
- if [ -f ".gsd-t/.unattended/stop" ]; then
158
- rm ".gsd-t/.unattended/stop"
159
- echo "STALE_SENTINEL=removed"
160
- else
161
- echo "STALE_SENTINEL=none"
162
- fi
163
- ```
164
-
165
- If the sentinel was removed, print: `ℹ️ Removed stale stop sentinel from previous run.`
166
-
167
- ### 1e: Verify Required Software is Installed
168
-
169
- The unattended supervisor depends on platform-specific helpers. Check them up front and fail fast with clear install instructions rather than crashing mid-run.
170
-
171
- Run via Bash:
172
-
173
- ```bash
174
- node -e "
175
- const { execSync } = require('child_process');
176
- const os = require('os');
177
- const platform = os.platform();
178
-
179
- function has(cmd) {
180
- try {
181
- const which = platform === 'win32' ? 'where' : 'command -v';
182
- execSync(which + ' ' + cmd, { stdio: 'ignore' });
183
- return true;
184
- } catch (_) { return false; }
185
- }
186
-
187
- const missing = [];
188
- const warnings = [];
189
-
190
- // REQUIRED on all platforms
191
- if (!has('node')) missing.push({ name: 'node', install: 'https://nodejs.org (>= 16)' });
192
- if (!has('claude')) {
193
- missing.push({
194
- name: 'claude',
195
- install: platform === 'win32'
196
- ? 'npm install -g @anthropic-ai/claude-code (then ensure claude.cmd is on PATH)'
197
- : 'npm install -g @anthropic-ai/claude-code'
198
- });
199
- }
200
- if (!has('git')) missing.push({ name: 'git', install: 'https://git-scm.com/downloads' });
201
-
202
- // PLATFORM-SPECIFIC (warnings only — supervisor runs without them, just less resilient)
203
- if (platform === 'darwin') {
204
- if (!has('caffeinate')) warnings.push('caffeinate (macOS built-in) — missing means sleep may interrupt long runs');
205
- } else if (platform === 'linux') {
206
- if (!has('systemd-inhibit') && !has('caffeine')) {
207
- warnings.push('systemd-inhibit or caffeine — missing means sleep/screen-lock may interrupt long runs');
208
- }
209
- if (!has('notify-send')) {
210
- warnings.push('notify-send (libnotify-bin) — missing means no desktop notifications on milestone events');
211
- }
212
- } else if (platform === 'win32') {
213
- warnings.push('Windows: sleep prevention uses PowerShell SetThreadExecutionState — no external helper required');
214
- warnings.push('Windows: desktop notifications use BurntToast PowerShell module — install with: Install-Module BurntToast');
215
- }
216
-
217
- if (missing.length > 0) {
218
- console.log('PREFLIGHT=fail');
219
- console.log('MISSING=' + JSON.stringify(missing));
220
- } else {
221
- console.log('PREFLIGHT=ok');
222
- }
223
- if (warnings.length > 0) {
224
- console.log('WARNINGS=' + JSON.stringify(warnings));
225
- }
226
- "
227
- ```
228
-
229
- If `PREFLIGHT=fail`, **STOP** and print:
230
-
231
- ```
232
- ❌ Required software missing — cannot launch unattended supervisor.
233
-
234
- Missing:
235
- {for each item in MISSING:}
236
- • {name}
237
- Install: {install}
238
-
239
- Install the missing software and retry: /gsd-t-unattended
240
- ```
241
-
242
- End the turn. Do NOT spawn.
243
-
244
- If `WARNINGS` were emitted, print them as a non-blocking advisory before proceeding:
245
-
246
- ```
247
- ⚠️ Platform advisories (non-blocking):
248
- {for each warning:}
249
- • {warning}
250
-
251
- Supervisor will still launch, but consider installing these for best reliability.
252
- ```
253
-
254
- ## Step 2: Spawn the Detached Supervisor
255
-
256
- ```bash
257
- node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-unattended --step 2 --step-label "Spawn the Detached Supervisor" 2>/dev/null || true
258
- ```
259
-
260
- ⚙ [sonnet] gsd-t-unattended → spawning detached supervisor
261
-
262
- **Before spawn — capture start timestamp (observability bracket):**
263
-
264
- ```bash
265
- DT_START=$(date +"%Y-%m-%d %H:%M")
266
- ```
267
-
268
- The detached supervisor is a `node -e spawnSupervisor` fire-and-forget (no Claude result envelope). Timing is recorded via `recordSpawnRow` (Pattern B) after spawn returns.
269
-
270
- If `--dry-run` was specified, print:
271
-
272
- ```
273
- 🔎 Dry-run mode — would spawn:
274
- node bin/gsd-t-unattended.cjs --hours={hours} --milestone={milestone} --max-iterations={maxIterations}
275
- Project: {cwd}
276
-
277
- No supervisor launched. Remove --dry-run to proceed.
278
- ```
279
-
280
- Then end the turn.
281
-
282
- Otherwise, run the actual spawn:
283
-
284
- ```bash
285
- node -e "
286
- const path = require('path');
287
- const { spawnSupervisor } = require('./bin/gsd-t-unattended-platform.cjs');
288
-
289
- // Parse CLI args forwarded from the launch command
290
- const hours = parseInt(process.env.GSD_T_HOURS || '24', 10) || 24;
291
- const milestone = process.env.GSD_T_MILESTONE || '';
292
- const maxIterations = parseInt(process.env.GSD_T_MAX_ITERATIONS || '200', 10) || 200;
293
-
294
- const binPath = path.resolve(__dirname, 'bin', 'gsd-t-unattended.cjs');
295
- const cwd = process.cwd();
296
-
297
- const extraArgs = [];
298
- if (hours !== 24) extraArgs.push('--hours=' + hours);
299
- if (milestone) extraArgs.push('--milestone=' + milestone);
300
- if (maxIterations !== 200) extraArgs.push('--max-iterations=' + maxIterations);
301
-
302
- const result = spawnSupervisor({ binPath, args: extraArgs, cwd });
303
- console.log('SPAWNED_PID=' + result.pid);
304
- " \
305
- GSD_T_HOURS={hours} \
306
- GSD_T_MILESTONE={milestone} \
307
- GSD_T_MAX_ITERATIONS={maxIterations}
308
- ```
309
-
310
- Capture `SPAWNED_PID` from the output.
311
-
312
- **After spawn — record row via `recordSpawnRow` (Pattern B, no usage envelope):**
313
-
314
- ```bash
315
- DT_END=$(date +"%Y-%m-%d %H:%M")
316
- node -e "
317
- const { recordSpawnRow } = require('./bin/gsd-t-token-capture.cjs');
318
- recordSpawnRow({
319
- projectDir: '.',
320
- command: 'gsd-t-unattended',
321
- step: 'Step 2',
322
- model: 'sonnet',
323
- startedAt: process.env.DT_START,
324
- endedAt: process.env.DT_END,
325
- // usage omitted → Tokens cell renders as '—' (no envelope from a fire-and-forget node spawn)
326
- notes: 'supervisor spawned PID ' + (process.env.SPAWNED_PID || '?'),
327
- });
328
- "
329
- ```
330
-
331
- The row lands under the canonical `.gsd-t/token-log.md` header with Tokens = `—`, Ctx% pulled via `getSessionStatus()`. No usage envelope is available because the supervisor is a fire-and-forget `node -e spawnSupervisor` child, not a `claude -p` or Task subagent.
332
-
333
- ## Step 3: Verify Supervisor Liveness
334
-
335
- ```bash
336
- node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-unattended --step 3 --step-label "Verify Supervisor Liveness" 2>/dev/null || true
337
- ```
338
-
339
- Wait up to 2 seconds for the supervisor to write its PID file and transition out of `initializing`:
340
-
341
- ```bash
342
- node -e "
343
- const fs = require('fs');
344
- const path = require('path');
345
-
346
- const PID_FILE = '.gsd-t/.unattended/supervisor.pid';
347
- const STATE_FILE = '.gsd-t/.unattended/state.json';
348
- const LOG_FILE = '.gsd-t/.unattended/run.log';
349
- const SPAWNED_PID = parseInt(process.env.SPAWNED_PID || '0', 10);
350
- const WAIT_MS = 2000;
351
- const POLL_MS = 100;
352
-
353
- function sleep(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
354
-
355
- let alive = false;
356
- let pidFromFile = null;
357
- const deadline = Date.now() + WAIT_MS;
358
-
359
- while (Date.now() < deadline) {
360
- // Check process liveness via process.kill(pid, 0)
361
- if (SPAWNED_PID > 0) {
362
- try { process.kill(SPAWNED_PID, 0); alive = true; } catch (e) {
363
- alive = e.code === 'EPERM';
364
- }
365
- }
366
- // Also try reading the PID file the supervisor writes (JSON or legacy bare-integer)
367
- if (fs.existsSync(PID_FILE)) {
368
- try {
369
- const { readPidFile } = require('./bin/supervisor-pid-fingerprint.cjs');
370
- const entry = readPidFile(process.cwd());
371
- pidFromFile = entry && Number.isInteger(entry.pid) ? entry.pid : null;
372
- } catch (_) {}
373
- }
374
- if (alive || pidFromFile) break;
375
- sleep(POLL_MS);
376
- }
377
-
378
- if (!alive && !pidFromFile) {
379
- console.log('LIVENESS=dead');
380
- // Emit last few lines of run.log if it exists
381
- if (fs.existsSync(LOG_FILE)) {
382
- try {
383
- const txt = fs.readFileSync(LOG_FILE, 'utf8');
384
- const tail = txt.split('\n').filter(l => l.trim()).slice(-20).join('\n');
385
- console.log('LOG_TAIL=' + JSON.stringify(tail));
386
- } catch (_) { console.log('LOG_TAIL='); }
387
- } else {
388
- console.log('LOG_TAIL=');
389
- }
390
- } else {
391
- console.log('LIVENESS=ok');
392
- console.log('PID_FROM_FILE=' + (pidFromFile || SPAWNED_PID));
393
- }
394
- " SPAWNED_PID=${SPAWNED_PID}
395
- ```
396
-
397
- If `LIVENESS=dead`, the supervisor crashed at startup. Print diagnostics and **STOP**:
398
-
399
- ```
400
- 💥 Supervisor crashed at startup (PID {SPAWNED_PID} no longer alive after 2s).
401
-
402
- Startup diagnostics (run.log tail):
403
- ──────────────────────────────────────────────────────────────
404
- {LOG_TAIL}
405
- ──────────────────────────────────────────────────────────────
406
-
407
- Common causes:
408
- • Missing Node.js or claude binary on PATH
409
- • .gsd-t/progress.md has no active milestone
410
- • Protected branch or dirty worktree rejected by safety rails
411
- • Permissions error on .gsd-t/.unattended/ directory
412
-
413
- Fix the issue above and retry: /gsd-t-unattended
414
- ```
415
-
416
- End the turn without scheduling a watch tick.
417
-
418
- ## Step 4: Display Initial Status Block
419
-
420
- ```bash
421
- node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-unattended --step 4 --step-label "Display Initial Status Block" 2>/dev/null || true
422
- ```
423
-
424
- Print the launch confirmation block:
425
-
426
- ```
427
- 🟢 Unattended supervisor launched.
428
-
429
- PID: {PID_FROM_FILE}
430
- Project: {PROJECT_NAME}
431
- Milestone: {milestone}
432
- Max hours: {hours}
433
- Max iterations: {maxIterations}
434
- Log: .gsd-t/.unattended/run.log
435
- State: .gsd-t/.unattended/state.json
436
- Watch: ScheduleWakeup every 270s
437
-
438
- The supervisor is running detached — it survives /clear and terminal close.
439
- Stop gracefully: /gsd-t-unattended-stop
440
- Watch manually: /gsd-t-unattended-watch
441
- ```
442
-
443
- ## Step 5: Schedule the First Watch Tick
444
-
445
- ```bash
446
- node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-unattended --step 5 --step-label "Schedule the First Watch Tick" 2>/dev/null || true
447
- ```
448
-
449
- Call the harness `ScheduleWakeup` tool with these exact parameters:
450
-
451
- - `delaySeconds`: `270` (fixed — inside the 5-minute prompt-cache TTL)
452
- - `prompt`: `/gsd-t-unattended-watch`
453
- - `reason`: `first unattended tick`
454
-
455
- Tool invocation pattern (make this a real tool call, not a bash command):
456
-
457
- ```
458
- ScheduleWakeup(
459
- delaySeconds: 270,
460
- prompt: "/gsd-t-unattended-watch",
461
- reason: "first unattended tick"
462
- )
463
- ```
464
-
465
- After the tool call, end the turn. The in-session watch loop takes over from here. Do NOT output a "Next Up" block — this is a self-rescheduling loop, not a phase workflow.
466
-
467
- ## Notes
468
-
469
- - **Singleton**: only one supervisor per project at a time. PID collision → refuse with "already running" message.
470
- - **Stale stop sentinel**: if `.gsd-t/.unattended/stop` exists from a prior run, Step 1d removes it before spawning.
471
- - **Platform helper**: uses `spawnSupervisor` from `bin/gsd-t-unattended-platform.cjs` — never hand-rolls `child_process.spawn` directly. This handles macOS/Linux/Windows differences.
472
- - **Dry-run**: `--dry-run` prints the would-be invocation without spawning. Useful for validating flags before a long overnight run.
473
- - **No doc ripple, no pre-commit gate**: this command spawns a background process; it does not modify any source files or contracts.
474
- - **watch command is stateless**: after this command returns, every `/gsd-t-unattended-watch` tick re-reads state from disk. There is no in-memory state to preserve.
475
-
476
- $ARGUMENTS
@@ -1,116 +0,0 @@
1
- # GSD-T: Visualize — Launch Real-Time Agent Dashboard
2
-
3
- You are launching the GSD-T real-time agent dashboard — an SSE-backed browser visualization of agent activity.
4
-
5
- ## Step 0: Launch via Subagent
6
-
7
- When invoked directly by the user, spawn yourself as a Task subagent for a fresh context window.
8
-
9
- **OBSERVABILITY LOGGING (MANDATORY) — wrap the visualize subagent spawn with `captureSpawn`:**
10
-
11
- ```
12
- node -e "
13
- const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
14
- (async () => {
15
- await captureSpawn({
16
- command: 'gsd-t-visualize',
17
- step: 'Step 0',
18
- model: 'sonnet',
19
- description: 'dashboard launched',
20
- projectDir: '.',
21
- notes: 'dashboard launched',
22
- spawnFn: async () => { /* Task subagent (general-purpose, model: sonnet):
23
- 'Run the GSD-T visualize command. Read commands/gsd-t-visualize.md for your full instructions.
24
- Arguments: {\$ARGUMENTS}
25
- Skip Step 0 — you are already the subagent.' */ },
26
- });
27
- })();
28
- "
29
- ```
30
-
31
- `captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`. Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
32
-
33
- ## Step 1: Write command_invoked Event
34
-
35
- Run via Bash:
36
- ```bash
37
- node ~/.claude/scripts/gsd-t-event-writer.js --type command_invoked --command gsd-t-visualize --reasoning "Launching dashboard" || true
38
- ```
39
-
40
- ## Step 1.5: Context Metrics for Dashboard
41
-
42
- If `.gsd-t/token-log.md` exists, the dashboard server automatically reads it and provides context utilization metrics for visualization. These metrics are served from the `/api/token-breakdown` endpoint and rendered as:
43
-
44
- 1. **Context utilization timeline** — Ctx% over time, ordered by Datetime-start
45
- 2. **Token breakdown by domain** — bar chart grouping Tokens by Domain column (gracefully handles older rows without Domain column — they are grouped as "(untagged)")
46
- 3. **Compaction proximity warnings** — rows where Ctx% >= 70 are highlighted; rows where Ctx% >= 85 are marked critical (🔴)
47
-
48
- If `.gsd-t/token-log.md` does not exist, context metrics panels are hidden (not shown as errors).
49
-
50
- ## Step 1.6: Graph Data for Dashboard
51
-
52
- If `.gsd-t/graph/index.json` exists, the dashboard can render entity-relationship visualizations from the graph data. The dashboard server will detect and serve graph data automatically — no additional configuration needed.
53
-
54
- ## Step 2: Check $ARGUMENTS for "stop"
55
-
56
- If `$ARGUMENTS` contains "stop", skip to **Step 5**. Otherwise continue to Step 3.
57
-
58
- ## Step 3: Check if Server is Already Running
59
-
60
- Run via Bash:
61
- ```bash
62
- if [ -f .gsd-t/dashboard.pid ]; then
63
- PID=$(cat .gsd-t/dashboard.pid)
64
- curl -sf http://localhost:7433/ping 2>/dev/null | grep -q '"ok"' && echo "SERVER_RUNNING=true" || echo "SERVER_RUNNING=false"
65
- else
66
- echo "SERVER_RUNNING=false"
67
- fi
68
- ```
69
-
70
- If output is `SERVER_RUNNING=true`, skip Step 3a and go directly to Step 4.
71
-
72
- ### Step 3a: Start Server if Not Running
73
-
74
- Run via Bash:
75
- ```bash
76
- node ~/.claude/scripts/gsd-t-dashboard-server.js --detach || true
77
- for i in 1 2 3 4 5; do
78
- curl -sf http://localhost:7433/ping 2>/dev/null | grep -q '"ok"' && break
79
- sleep 1
80
- done
81
- ```
82
-
83
- ## Step 4: Open Browser
84
-
85
- Run via Bash:
86
- ```bash
87
- node -e "const {execFileSync}=require('child_process'); const url='http://localhost:7433'; try { if(process.platform==='win32'){execFileSync('cmd',['/c','start','',url],{stdio:'ignore'})}else{execFileSync(process.platform==='darwin'?'open':'xdg-open',[url],{stdio:'ignore'})} } catch(e) { console.error('Could not open browser:', e.message); }" || true
88
- ```
89
-
90
- Report to the user: "Dashboard is running at http://localhost:7433 — browser opened."
91
-
92
- ## Step 5: Stop Handler
93
-
94
- Run only when `$ARGUMENTS` contains "stop".
95
-
96
- Run via Bash:
97
- ```bash
98
- if [ -f .gsd-t/dashboard.pid ]; then
99
- PID=$(cat .gsd-t/dashboard.pid)
100
- curl -sf http://localhost:7433/stop 2>/dev/null || kill $PID 2>/dev/null || true
101
- rm -f .gsd-t/dashboard.pid
102
- echo "Dashboard server stopped"
103
- else
104
- echo "No dashboard server running (no .gsd-t/dashboard.pid found)"
105
- fi
106
- ```
107
-
108
- ## Document Ripple
109
-
110
- Note: All 4 reference files (README.md, docs/GSD-T-README.md, templates/CLAUDE-global.md, commands/gsd-t-help.md) are updated in Task 3 of Milestone 15, not here.
111
-
112
- $ARGUMENTS
113
-
114
- ## Auto-Clear
115
-
116
- All work is committed to project files. Execute `/clear` to free the context window for the next command.