gm-skill 0.1.0 → 0.1.2

package/gm-complete.SKILL.md

@@ -0,0 +1,106 @@
+---
+name: gm-complete
+description: VERIFY and COMPLETE phase. End-to-end system verification and git enforcement. Any new unknown triggers immediate snake back to planning — restart chain.
+---
+
+# GM COMPLETE — Verify, then close
+
+Entry: EMIT gates clear, from `gm-emit`. Exit: `.prd` deleted + test.js green + pushed + CI green → `update-docs`.
+
+Cross-cutting dispositions live in `gm` SKILL.md.
+
+## Transitions
+
+- `.prd` items remain → `gm-execute`
+- `.prd` empty AND test.js green AND pushed AND CI green → `update-docs`
+- Broken file output → `gm-emit`
+- Wrong logic → `gm-execute`
+- New unknown or wrong requirements → `planning`
+
+Failure triage: broken output to EMIT, wrong logic to EXECUTE, new unknown to PLAN. Never patch around surprises.
+
+## Mutables that must resolve before COMPLETE
+
+- `witnessed_e2e` — real end-to-end run with witnessed output
+- `browser_validated` — for any change touching client / UI / browser-facing code, see gate below. test.js + node-side imports DO NOT satisfy this gate.
+- `git_clean` — `git status --porcelain` returns empty
+- `git_pushed` — `git log origin/main..HEAD --oneline` returns empty
+- `ci_passed` — every GitHub Actions run reaches `conclusion: success`
+- `mutables_resolved` — `.gm/mutables.yml` deleted OR every entry `status: witnessed`. Stop hook hard-blocks turn-stop while any entry is `status: unknown`.
+- `prd_empty` — `.gm/prd.yml` deleted AFTER residual scan: enumerate every in-spirit reachable residual surfaced this session; any hit re-enters `planning`, appends PRD items, executes. Empty PRD is necessary, not sufficient — done = empty PRD AND zero reachable in-spirit residuals. Out-of-spirit-or-unreachable residuals are named in the response and skipped; everything else is this turn's work.
+- `stress_suite_clear` — change walked through M1–D1 (governance), none flunked
+- `hidden_decision_posture` — open → down_weighted → closed only when CI is green AND stress suite is clear
+
+## End-to-end verification
+
+Real system, real data, witness actual output. Doc updates, "saying done", and screenshots alone are not verification. Write the e2e probe to the spool (`.gm/exec-spool/in/nodejs/<N>.js`):
+
+```
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
+
+After every success, enumerate what remains — never stop at first green.
+
+## Browser validation gate
+
+Required when this session changed any code that runs in a browser: anything under `client/`, UI components, shaders, page-loaded JS, served HTML, gh-pages assets, dev-server endpoints, or any module imported into the page bundle.
+
+Trigger detection (any one): `git diff --name-only origin/main..HEAD` includes paths under `client/`, `apps/*/index.js` with client export, `docs/`, `*.html`, shader files, or any file imported by a browser entry; new/changed export consumed by `window.*` or rendered in DOM/canvas/WebGL; visual, layout, animation, input, network-on-page, or shader behavior altered.
+
+Protocol: boot the real server (or open the static page) on a known URL — witness HTTP 200. `exec:browser` → `page.goto(url)` → wait for app init by polling for the global the change affects (`window.__app.<system>`). Probe via `page.evaluate(() => …)` asserting the specific invariant the change was supposed to establish — instance counts, scene meshes, DOM nodes, render stats, network frames. Capture witnessed numbers in the response — "looks fine" is not a witness. Failures route to `gm-execute` (logic) or `gm-emit` (output) — never paper over.
+
+Long-running probes split into navigate-call → `exec:wait N` → probe-call to stay under the per-call budget. Do not stack multi-second `setTimeout` inside one `exec:browser` invocation.
+
+Exempt only when: change is server-only with zero browser-facing surface, OR the repository has no browser surface at all (pure CLI / library). Exemption requires explicit tag in the response: `BROWSER EXEMPT: <reason — must reference diff paths showing zero browser-facing surface>`. Default posture is NOT exempt — burden is on the agent to prove exemption with diff evidence.
+
+Pre-flight: run `git diff --name-only origin/main..HEAD` directly via Bash, then dispatch a nodejs spool file that reads the diff list and filters lines matching `client/|docs/|\.html$|\.glsl$|\.frag$|\.vert$`. Any hit AND no `exec:browser` block in this session → mandatory regression to `gm-execute`.
+
+## Integration test gate
+
+Write to `.gm/exec-spool/in/nodejs/<N>.js`:
+
+```
+const { execSync } = require('child_process');
+try { execSync('node test.js', { stdio: 'inherit', timeout: 30000 }); console.log('PASS'); }
+catch (e) { console.error('FAIL'); process.exit(1); }
+```
+
+Failure → `gm-execute`. No test.js in a repo with testable surface → `gm-execute` to create it.
+
+## Git enforcement
+
+Run directly via Bash:
+
+```
+git status --porcelain
+git log origin/main..HEAD --oneline
+```
+
+Both must return empty. Local commit without push is not complete.
+
+## CI is automated
+
+The Stop hook watches Actions for the pushed HEAD. Do not call `gh run list` manually. All-green → Stop approves with CI summary in next-turn context. Failure → Stop blocks with run names + IDs; investigate via `gh run view <id> --log-failed`, fix, push, hook re-watches. Deadline 180s (override `GM_CI_WATCH_SECS`); slow jobs get a "still in progress" approve.
+
+## Hygiene sweep
+
+1. Files >200 lines → split
+2. Comments in code → remove
+3. Scattered test files (`.test.js`, `.spec.js`, `__tests__/`, `fixtures/`, `mocks/`) → delete, consolidate into root `test.js`
+4. Mock / stub / simulation files → delete
+5. Unnecessary doc files (not CHANGELOG, CLAUDE, README, TODO.md) → delete
+6. Duplicate concern → regress to `planning` with restructuring instructions
+7. Hardcoded values → derive from ground truth
+8. Fallback / demo modes → remove, fail loud
+9. TODO.md → empty or deleted
+10. CHANGELOG.md → entries for this session
+11. Observability gaps → server subsystems expose `/debug/<subsystem>`; client modules register in `window.__debug`
+12. Memorize → every fact from verification handed off via background `Agent(memorize)` at moment of resolution
+13. Deploy / publish → if deployable, deploy; if npm package, publish
+14. GitHub Pages → check `.github/workflows/pages.yml` + `docs/index.html` exist; invoke `pages` skill if absent
+15. Governance stress-suite → walk change through M1, F1, C1, H1, S1, B1, A1, D1; any flunk regresses to the owning phase
+
+## Completion
+
+All true at once: witnessed e2e | browser_validated when client work touched | failure paths exercised | test.js passes | `.prd` deleted | git clean and pushed | CI green | hygiene sweep clean | TODO.md gone | CHANGELOG.md updated.

package/gm-emit.SKILL.md

@@ -0,0 +1,70 @@
+---
+name: gm-emit
+description: EMIT phase. Pre-emit debug, write files, post-emit verify from disk. Any new unknown triggers immediate snake back to planning — restart chain.
+---
+
+# GM EMIT — Write and verify from disk
+
+Entry: every mutable KNOWN, from `gm-execute` or re-entered from VERIFY. Exit: gates clear → `gm-complete`.
+
+Cross-cutting dispositions live in `gm` SKILL.md.
+
+## Transitions
+
+- All gates clear → `gm-complete`
+- Post-emit variance with known cause → fix in-band, re-verify, stay in EMIT
+- Pre-emit reveals known logic error → `gm-execute`
+- Pre-emit reveals new unknown OR post-emit variance with unknown cause OR scope changed → `planning`
+
+## Legitimacy gate (before pre-emit run)
+
+For every claim landing in a file, answer five questions:
+
+1. Earned specificity — does it trace to `authorization=witnessed`, or is it inflated from a weak prior?
+2. Repair legality — is a local patch dressed as structural repair? Downgrade scope or regress to PLAN.
+3. Lawful downgrade — can a weaker, true statement replace it? Prefer the downgrade.
+4. Alternative-route suppression — is a live competing route being silenced? Preserve it.
+5. Strongest objection — what would the sharpest reviewer pushback be? Articulate it. Cannot articulate = have not understood the alternatives → `gm-execute`.
+
+Any failure regresses to `gm-execute` to witness what was missing, or `planning` if the gap is structural.
+
+## Pre-emit run
+
+Mandatory before writing any file. Write the probe to the spool (`.gm/exec-spool/in/nodejs/<N>.js`):
+
+```
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
+
+Import the actual module from disk to witness current behavior as the baseline. Run the proposed logic in isolation without writing — witness with real inputs and with real error inputs. Match expected → write. Unexpected → new unknown → `planning`.
+
+## Writing
+
+Use the Write tool, or a nodejs spool file with `require('fs')`. Write only when every gate mutable resolves simultaneously.
+
+## Post-emit verification
+
+Re-import from disk — in-memory state is stale and inadmissible. Run identical inputs as pre-emit; output must match the baseline exactly. Known variance → fix and re-verify (self-loop). Unknown variance → `planning`.
+
+## Mutables gate
+
+Before pre-emit run, read `.gm/mutables.yml`. Any entry with `status: unknown` → regress to `gm-execute`. The pre-tool-use hook hard-blocks Write/Edit/NotebookEdit while unresolved entries exist; trying to emit anyway returns deny. Zero unresolved is the precondition for every legitimacy question below.
+
+## Gate (all true at once)
+
+- `.gm/mutables.yml` empty/absent OR every entry `status: witnessed` with filled `witness_evidence`
+- Legitimacy gate passed; no refused collapse
+- Pre-emit passed with real inputs and real error inputs
+- Post-emit matches pre-emit exactly
+- Hot-reloadable; errors throw with context (no `|| default`, no `catch { return null }`, no fallbacks)
+- No mocks, fakes, stubs, or scattered test files (delete on discovery)
+- Any behavior change has a corresponding assertion in `test.js` — a change no test catches is a change you cannot prove
+- Browser-facing change → post-emit verify includes a live `exec:browser` witness (boot server → `page.goto` → `page.evaluate` asserting the invariant the change established). Node-side import + test.js does not satisfy this — the final gate runs again in `gm-complete`.
+- Files ≤ 200 lines
+- No duplicate concern (run `exec:codesearch` for the primary concern after writing; overlap → `planning`)
+- No comments, no hardcoded values, no adjectives in identifiers, no unnecessary files
+- Observability: new server subsystems expose `/debug/<subsystem>`; new client modules register in `window.__debug`
+- Structure: no if/else where dispatch suffices; no one-liners that obscure; no reinvented APIs
+- Every fact resolved this phase memorized via background `Agent(memorize)`
+- CHANGELOG.md updated; TODO.md cleared or deleted

package/gm-execute.SKILL.md

@@ -0,0 +1,88 @@
+---
+name: gm-execute
+description: EXECUTE phase AND the foundational execution contract for every skill. Every exec:<lang> run, every witnessed check, every code search, in every phase, follows this skill's discipline. Resolve all mutables via witnessed execution. Any new unknown triggers immediate snake back to planning — restart chain from PLAN.
+---
+
+# GM EXECUTE — Resolve every unknown by witness
+
+Entry: `.prd` with named unknowns. Exit: every mutable KNOWN → invoke `gm-emit`.
+
+A `@<discipline>` sigil propagates from PLAN through every recall, codesearch, and memorize call; reads without one fan across default plus enabled disciplines, writes without one go to default only.
+
+This skill is the execution contract for ALL phases — pre-emit witnesses, post-emit verifies, e2e checks all run on this discipline. Cross-cutting dispositions live in `gm` SKILL.md.
+
+## Transitions
+
+- All mutables KNOWN → `gm-emit`
+- Still UNKNOWN → re-run from a different angle (max 2 passes)
+- New unknown OR unresolvable after 2 passes → `planning`
+
+## Mutable discipline
+
+Each mutable carries: name, expected, current, resolution method.
+
+Resolves to KNOWN only when all four pass:
+
+- **ΔS = 0** — witnessed output equals expected
+- **λ ≥ 2** — two independent paths agree
+- **ε intact** — adjacent invariants hold
+- **Coverage ≥ 0.70** — enough corpus inspected to rule out contradiction
+
+Unresolved after 2 passes regresses to `planning`. Never narrate past an unresolved mutable.
+
+Every witness that resolves a mutable writes back to `.gm/mutables.yml` the same step: set `status: witnessed` and fill `witness_evidence` with concrete proof (file:line, codesearch hit, exec output snippet). No write-back = the mutable stays unknown and the EMIT-gate stays closed. The hook reads this file; the agent's memory of "I resolved it" does not unblock anything.
+
+Route candidates from PLAN are `weak_prior` only. Plausibility is the right to test, not the right to believe. A claim with no witness in the current session is a hypothesis — say so when stating it, and say what would settle it. The next reader (you, next turn) needs to know which lines were earned and which were carried forward.
+
+## Verification budget
+
+Spend on `.prd` items in descending order of consequence-if-wrong × distance-from-witnessed. Items whose failure would collapse the headline finding must reach witnessed status before EMIT; sub-argument-level items need at minimum a stated fallback path.
+
+## Code execution
+
+Code AND utility verbs both run through the file-spool. Write a file to `.gm/exec-spool/in/<lang-or-verb>/<N>.<ext>` — language stems (`in/nodejs/42.js`, `in/python/43.py`, `in/bash/44.sh`, plus typescript, go, rust, c, cpp, java, deno) or verb stems (`in/codesearch/45.txt`, `in/recall/46.txt`, `in/memorize/47.md`, plus wait, sleep, status, close, browser, runner, type, kill-port, forget, feedback, learn-status, learn-debug, learn-build, discipline, pause, health). The spool watcher executes and streams stdout to `out/<N>.out`, stderr to `out/<N>.err`, then writes `out/<N>.json` metadata sidecar at completion (taskId, lang, ok, exitCode, durationMs, timedOut, startedAt, endedAt). Both streams return as systemMessage with `--- stdout ---` / `--- stderr ---` separators. File I/O via a nodejs spool file + `require('fs')`. Only `git` and `gh` run directly in Bash. Never `Bash(node/npm/npx/bun)`, never `Bash(exec:<anything>)`.
+
+Pack runs: `Promise.allSettled`, each idea own try/catch, under 12s per call. Runner: write `in/runner/<N>.txt` with body `start` | `stop` | `status`.
+
+Every exec daemonizes. The hook tails the task logfile up to 30s wall-clock and returns whatever is there — short tasks complete inside the window and look synchronous; long tasks return a task_id with partial output. Continue with `exec:tail` (drain, bounded), `exec:watch` (resume blocking until match or timeout), or `exec:close` (terminate). Never re-spawn a long task to check on it — that orphans the first one. `exec:wait` is a pure timer; `exec:sleep` blocks on a specific task's output; `exec:watch` is the match-or-timeout primitive. Every execution-platform RPC returns the live list of running tasks for this session — close stragglers via `exec:close\n<id>` so the list stays scannable. Session-end (clear/logout/prompt_input_exit) kills the session's tasks; compaction/handoff preserves them.
+
+Every utility verb dispatches via `in/<verb>/<N>.txt`; the body of the file is the verb's argument. There is no inline form and no Bash-prefix form — both are denied by the hook.
+
+## Codebase search
+
+`exec:codesearch` only. Grep, Glob, Find, Explore, raw grep/rg/find inside `exec:bash` are all hook-blocked.
+
+```
+exec:codesearch
+<two-word query>
+```
+
+Start two words, change/add one per pass, minimum four attempts before concluding absent. Known absolute path → `Read`. Known directory → `exec:nodejs` + `fs.readdirSync`.
+
+## Utility verb failure handling
+
+**Utility verb failures must surface**: exec:memorize, exec:recall, exec:codesearch, and other utility verbs may fail (socket unavailable, timeout, network error). Failures do not block witness completion but must be reported to the user with error context. Fallback mechanisms (AGENTS.md for memorize) ensure memory preservation even when rs-learn is temporarily unavailable.
+
+## Import-based execution
+
+Hypotheses become real by importing actual modules from disk. Reimplemented behavior is UNKNOWN. Write the import probe to the spool:
+
+```
+# write .gm/exec-spool/in/nodejs/42.js
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
+
+Differential diagnosis: smallest reproduction → compare actual vs expected → name the delta — that delta is the mutable.
+
+## Edits depend on witnesses
+
+Hypothesis → run → witness → edit. An edit before a witness is a guess. Scan via `exec:codesearch` before creating or modifying — duplicate concern regresses to `planning`. Code-quality preference: native → library → structure → write.
+
+## Parallel subagents
+
+Up to 3 `gm:gm` subagents for independent items in one message. Browser escalation: `exec:browser` → `browser` skill → screenshot only as last resort.
+
+## CI is automated
+
+`git push` triggers the Stop hook to watch Actions for the pushed HEAD on the same repo (downstream cascades are not auto-watched). Green → Stop approves with summary; failure → run names + IDs surfaced, investigate via `gh run view <id> --log-failed`. Deadline 180s (override `GM_CI_WATCH_SECS`).

package/gm.SKILL.md

@@ -0,0 +1,63 @@
+---
+name: gm
+description: Orchestrator dispatching PLAN→EXECUTE→EMIT→VERIFY→UPDATE-DOCS skill chain; spool-driven task execution with session isolation
+allowed-tools: Skill
+compatible-platforms:
+  - gm-cc
+  - gm-gc
+  - gm-oc
+  - gm-kilo
+  - gm-codex
+  - gm-copilot-cli
+  - gm-vscode
+  - gm-cursor
+  - gm-zed
+  - gm-jetbrains
+end-to-end: true
+---
+
+# GM — Orchestrator
+
+Invoke `planning` immediately. Phases cascade: PLAN → EXECUTE → EMIT → VERIFY → UPDATE-DOCS.
+
+The user's request is authorization. When scope is unclear, pick the maximum reachable shape and declare it — the user can interrupt. Doubts resolve via witnessed probe or recall, never by asking back except for destructive-irreversible actions uncovered by the PRD.
+
+**What ships runs**: no stubs, mocks, placeholder returns, fixture-only paths, or demo-mode short-circuits. Real input through real code into real output. A shim is allowed only when delegating to real upstream behavior.
+
+**CI is the build**: for Rust crates and the gm publish chain, push triggers CI auto-watch. Green signals authority. Local cargo build is not a witness.
+
+**Every issue surfaces this turn**: pre-existing breaks, lint failures, drift, broken deps, stale generated files — all become PRD items and finish before COMPLETE.
+
+**LLM provider**: acptoapi (127.0.0.1:4800) is the preferred provider when available. rs-plugkit session_start spawns acptoapi daemon and auto-detects ACP agents (opencode, kilo-code, codex, gemini-cli, qwen-code). All downstream platforms (rs-learn, freddie, gm-skill daemon mode) read OPENAI_BASE_URL environment variable and default to 127.0.0.1:4800. Anthropic SDK is fallback only when acptoapi socket is unavailable (CI, headless mode).
+
+**rs-learn failure contract**: exec:memorize, exec:recall, and exec:codesearch failures must be reported explicitly with error details to the user. Fallback to AGENTS.md for memory preservation when socket/network unavailable. Never silently absorb errors because memory preservation requires explicit fallback. This rule applies across all phases (PLAN through UPDATE-DOCS).
+
+**Spool dispatch chain**: write to `.gm/exec-spool/in/<lang>/<N>.<ext>` or `in/<verb>/<N>.txt`. Watcher executes and streams `out/<N>.out` + `out/<N>.err` + `out/<N>.json` metadata. Languages: nodejs, python, bash, typescript, go, rust, c, cpp, java, deno. Verbs: codesearch, recall, memorize, wait, sleep, status, close, browser, runner, type, kill-port, forget, feedback, learn-status, learn-debug, learn-build, discipline, pause, health.
+
+**Session isolation**: SESSION_ID environment variable (or uuid fallback) threads through task dispatch for cleanup scope. rs-exec RPC handlers verify session_id match on all task-scoped operations.
+
+**Code does mechanics; meaning routes through textprocessing skill**: summarize, classify, extract intent, rewrite, translate, semantic dedup, rank, label — all via `Agent(subagent_type='gm:textprocessing', ...)`.
+
+**Recall before fresh execution**: before witnessing unknown via execution, recall first. Hits arrive as weak_prior; empty results confirm fresh unknown.
+
+**Memorize is the back-half of witness**: resolution incomplete until fact lives outside this context window. Fire `Agent(subagent_type='gm:memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<fact>')` alongside witness, in parallel, never blocking.
+
+**Parallel independent items**: up to 3 `gm:gm` subagents per message for independent PRD items. Serial for dependent items — no re-asking between them.
+
+**Terse response**: fragments OK. `[thing] [action] [reason]. [next step].` Code, commits, PRs use normal prose.
+
+## End-to-End Phase Chaining (Skills-Based Platforms)
+
+When `end-to-end: true` is present in SKILL.md frontmatter, skill output includes structured JSON on stdout (final line):
+
+```json
+{"nextSkill": "gm-execute" | "gm-emit" | "gm-complete" | "update-docs" | null, "context": {PRD and state dict}, "phase": "PLAN" | "EXECUTE" | "EMIT" | "COMPLETE"}
+```
+
+Platform adapters (vscode, cursor, zed, jetbrains) that support `end-to-end: true` detection:
+1. Invoke `Skill(skill="gm:gm")`
+2. Parse stdout for trailing JSON blob
+3. If `nextSkill` is non-null, invoke `Skill(skill="gm:<nextSkill>")` with context dict auto-passed
+4. Repeat until `nextSkill` is null
+
+This collapses 5 manual skill invocations into 1 user invocation + 4 transparent auto-dispatches, achieving perceived single-flow parity with gm-cc's subagent orchestration.

package/index.js

@@ -1,9 +1 @@
-const daemonBootstrap = require('../gm-starter/lib/daemon-bootstrap.js');
-const spool = require('../gm-starter/lib/spool.js');
-const manifest = require('./lib/manifest.js');
-
-module.exports = {
-  ...daemonBootstrap,
-  spool,
-  manifest
-};
+module.exports = require('./lib/index.js');

package/lib/daemon-bootstrap.js

@@ -0,0 +1,314 @@
+const fs = require('fs');
+const path = require('path');
+const net = require('net');
+const crypto = require('crypto');
+const { spawn, execSync } = require('child_process');
+const os = require('os');
+
+const LOG_DIR = path.join(os.homedir(), '.claude', 'gm-log');
+const GM_STATE_DIR = path.join(os.homedir(), '.gm');
+
+function emitEvent(daemon, severity, message, details = {}) {
+  try {
+    const date = new Date().toISOString().split('T')[0];
+    const logDir = path.join(LOG_DIR, date);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+    const logFile = path.join(logDir, 'daemon.jsonl');
+    const entry = {
+      ts: new Date().toISOString(),
+      daemon,
+      severity,
+      message,
+      ...details,
+    };
+    fs.appendFileSync(logFile, JSON.stringify(entry) + '\n');
+  } catch (e) {
+    console.error(`[daemon-bootstrap] emit failed: ${e.message}`);
+  }
+}
+
+function getPlatformKey() {
+  const plat = process.platform;
+  if (plat === 'win32') return plat;
+  if (plat === 'darwin') return plat;
+  if (plat === 'linux') return plat;
+  throw new Error(`Unsupported platform: ${plat}`);
+}
+
+function getSessionId() {
+  return process.env.CLAUDE_SESSION_ID || 'unknown';
+}
+
+function isDaemonRunning(daemonName) {
+  try {
+    const plat = getPlatformKey();
+    if (plat === 'win32') {
+      const output = execSync('tasklist /FO CSV /NH', { encoding: 'utf8' });
+      const lines = output.split('\n').filter(Boolean);
+      return lines.some(line => {
+        const parts = line.split(',').map(p => p.trim().replace(/^"/, '').replace(/"$/, ''));
+        return parts[0].includes(daemonName);
+      });
+    } else {
+      try {
+        execSync(`pgrep -f "${daemonName}" > /dev/null 2>&1`);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  } catch (e) {
+    return false;
+  }
+}
+
+function checkPortReachable(host, port, timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    const timeoutHandle = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, timeoutMs);
+
+    socket.connect(port, host, () => {
+      clearTimeout(timeoutHandle);
+      socket.destroy();
+      resolve(true);
+    });
+
+    socket.on('error', () => {
+      clearTimeout(timeoutHandle);
+      resolve(false);
+    });
+  });
+}
+
+function writeStatusFile(daemonName, status, details = {}) {
+  try {
+    fs.mkdirSync(GM_STATE_DIR, { recursive: true });
+    const statusFile = path.join(GM_STATE_DIR, `${daemonName}-status.json`);
+    const payload = {
+      daemon: daemonName,
+      status,
+      sessionId: getSessionId(),
+      timestamp: new Date().toISOString(),
+      pid: process.pid,
+      ...details,
+    };
+    fs.writeFileSync(statusFile, JSON.stringify(payload, null, 2));
+    emitEvent(daemonName, 'info', 'Status written', { file: statusFile });
+  } catch (e) {
+    emitEvent(daemonName, 'warn', 'Failed to write status file', { error: e.message });
+  }
+}
+
+async function checkState(daemonName) {
+  const sessionId = getSessionId();
+  const startTime = Date.now();
+
+  try {
+    emitEvent(daemonName, 'info', 'checkState initiated', { sessionId });
+
+    const running = isDaemonRunning(daemonName);
+    if (!running) {
+      emitEvent(daemonName, 'info', 'Daemon not running', { sessionId });
+      writeStatusFile(daemonName, 'not_running', { sessionId });
+      return { ok: true, running: false, durationMs: Date.now() - startTime };
+    }
+
+    emitEvent(daemonName, 'info', 'Daemon running', { sessionId });
+    writeStatusFile(daemonName, 'running', { sessionId });
+    return { ok: true, running: true, durationMs: Date.now() - startTime };
+  } catch (e) {
+    emitEvent(daemonName, 'error', 'checkState failed', {
+      error: e.message,
+      sessionId,
+      durationMs: Date.now() - startTime,
+    });
+    return { ok: false, error: e.message, durationMs: Date.now() - startTime };
+  }
+}
+
+async function spawnDaemon(daemonName, cmd) {
+  const sessionId = getSessionId();
+  const startTime = Date.now();
+
+  try {
+    emitEvent(daemonName, 'info', 'spawn initiated', { cmd, sessionId });
+
+    if (isDaemonRunning(daemonName)) {
+      emitEvent(daemonName, 'info', 'Already running, skipping spawn', { sessionId });
+      writeStatusFile(daemonName, 'running', { sessionId });
+      return { ok: true, already_running: true, durationMs: Date.now() - startTime };
+    }
+
+    emitEvent(daemonName, 'info', 'Spawning daemon', { cmd, sessionId });
+
+    const env = Object.assign({}, process.env, {
+      CLAUDE_SESSION_ID: sessionId,
+    });
+
+    const proc = spawn('bun', ['x', cmd], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      env,
+    });
+
+    const pid = proc.pid;
+    proc.unref();
+
+    emitEvent(daemonName, 'info', 'Daemon spawned', { pid, cmd, sessionId });
+    writeStatusFile(daemonName, 'spawned', { pid, sessionId });
+
+    return {
+      ok: true,
+      pid,
+      cmd,
+      sessionId,
+      durationMs: Date.now() - startTime,
+    };
+  } catch (e) {
+    emitEvent(daemonName, 'error', 'spawn failed', {
+      error: e.message,
+      cmd,
+      sessionId,
+      durationMs: Date.now() - startTime,
+    });
+    writeStatusFile(daemonName, 'spawn_error', { error: e.message, sessionId });
+    return { ok: false, error: e.message, durationMs: Date.now() - startTime };
+  }
+}
+
+async function waitForReady(daemonName, host, port, timeoutMs = 30000) {
+  const sessionId = getSessionId();
+  const startTime = Date.now();
+
+  try {
+    emitEvent(daemonName, 'info', 'waitForReady initiated', {
+      host,
+      port,
+      timeoutMs,
+      sessionId,
+    });
+
+    const deadline = startTime + timeoutMs;
+    const pollIntervalMs = 500;
+
+    while (Date.now() < deadline) {
+      const reachable = await checkPortReachable(host, port, 1000);
+      if (reachable) {
+        emitEvent(daemonName, 'info', 'Ready', {
+          host,
+          port,
+          elapsedMs: Date.now() - startTime,
+          sessionId,
+        });
+        writeStatusFile(daemonName, 'ready', { host, port, sessionId });
+        return { ok: true, host, port, elapsedMs: Date.now() - startTime };
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+
+    emitEvent(daemonName, 'warn', 'Timeout waiting for readiness', {
+      host,
+      port,
+      timeoutMs,
+      sessionId,
+      elapsedMs: Date.now() - startTime,
+    });
+    writeStatusFile(daemonName, 'timeout', { host, port, timeoutMs, sessionId });
+    return { ok: false, error: 'Timeout', timeoutMs, elapsedMs: Date.now() - startTime };
+  } catch (e) {
+    emitEvent(daemonName, 'error', 'waitForReady failed', {
+      error: e.message,
+      host,
+      port,
+      sessionId,
+      elapsedMs: Date.now() - startTime,
+    });
+    return { ok: false, error: e.message, elapsedMs: Date.now() - startTime };
+  }
+}
+
+async function getSocket(daemonName) {
+  try {
+    emitEvent(daemonName, 'info', 'getSocket initiated', { sessionId: getSessionId() });
+
+    const statusFile = path.join(GM_STATE_DIR, `${daemonName}-status.json`);
+    if (!fs.existsSync(statusFile)) {
+      emitEvent(daemonName, 'warn', 'No status file found', { statusFile });
+      return { ok: false, error: 'No status file found' };
+    }
+
+    const status = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
+    const socket = `${status.host || '127.0.0.1'}:${status.port || 'unknown'}`;
+
+    emitEvent(daemonName, 'info', 'Socket retrieved', { socket });
+    return { ok: true, socket, ...status };
+  } catch (e) {
+    emitEvent(daemonName, 'error', 'getSocket failed', {
+      error: e.message,
+      sessionId: getSessionId(),
+    });
+    return { ok: false, error: e.message };
+  }
+}
+
+async function shutdown(daemonName) {
+  const sessionId = getSessionId();
+  const startTime = Date.now();
+
+  try {
+    emitEvent(daemonName, 'info', 'shutdown initiated', { sessionId });
+
+    const plat = getPlatformKey();
+    let killed = false;
+
+    if (plat === 'win32') {
+      try {
+        execSync(`taskkill /F /IM ${daemonName}* /T`, { stdio: 'ignore' });
+        killed = true;
+      } catch {
+        killed = false;
+      }
+    } else {
+      try {
+        execSync(`pkill -9 -f "${daemonName}"`, { stdio: 'ignore' });
+        killed = true;
+      } catch {
+        killed = false;
+      }
+    }
+
+    emitEvent(daemonName, 'info', 'shutdown completed', {
+      killed,
+      sessionId,
+      durationMs: Date.now() - startTime,
+    });
+    writeStatusFile(daemonName, 'shutdown', { killed, sessionId });
+
+    return { ok: true, killed, durationMs: Date.now() - startTime };
+  } catch (e) {
+    emitEvent(daemonName, 'error', 'shutdown failed', {
+      error: e.message,
+      sessionId,
+      durationMs: Date.now() - startTime,
+    });
+    return { ok: false, error: e.message, durationMs: Date.now() - startTime };
+  }
+}
+
+module.exports = {
+  checkState,
+  spawnDaemon,
+  waitForReady,
+  getSocket,
+  shutdown,
+  emitEvent,
+  isDaemonRunning,
+  checkPortReachable,
+};