gm-skill 2.0.1291 → 2.0.1292

package/README.md

@@ -35,7 +35,7 @@ An earlier generation fanned out fifteen per-platform downstream repos (gm-cc, g
 
 ## Version
 
-`2.0.1291` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` (or any cascading sibling crate) republishes this package.
+`2.0.1292` — auto-bumped from the canonical `gm` repo. Every push to `AnEntrypoint/gm` (or any cascading sibling crate) republishes this package.
 
 ## Source of truth
 

package/bin/ccsniff.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const C = { r:'\x1b[31m', g:'\x1b[32m', y:'\x1b[33m', b:'\x1b[34m', m:'\x1b[35m', c:'\x1b[36m', d:'\x1b[2m', x:'\x1b[0m', bold:'\x1b[1m' };
+const useColor = process.stdout.isTTY;
+const col = (k, s) => useColor ? C[k] + s + C.x : s;
+
+function parseDuration(s) {
+  if (!s) return null;
+  const m = String(s).match(/^(\d+)([smhd])$/);
+  if (!m) return null;
+  return parseInt(m[1],10) * ({s:1000,m:60000,h:3600000,d:86400000}[m[2]]);
+}
+
+function parseArgs(argv) {
+  const flags = new Set();
+  let since = null, project = null;
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--since') { since = parseDuration(argv[++i]); continue; }
+    if (a === '--project') { project = argv[++i]; continue; }
+    if (a.startsWith('--')) flags.add(a.slice(2));
+  }
+  return { flags, since, project };
+}
+
+function encodeCwd(cwd) {
+  return cwd.replace(/[\\/:]+/g, '-').replace(/^-+/, '');
+}
+
+function findTranscripts(project) {
+  const root = path.join(os.homedir(), '.claude', 'projects');
+  if (!fs.existsSync(root)) { console.log(col('d', `no log at ${root}`)); return []; }
+  const out = [];
+  const targetEnc = project ? encodeCwd(project) : null;
+  for (const dir of fs.readdirSync(root)) {
+    if (targetEnc && !dir.includes(targetEnc)) continue;
+    const full = path.join(root, dir);
+    if (!fs.statSync(full).isDirectory()) continue;
+    for (const f of fs.readdirSync(full)) {
+      if (f.endsWith('.jsonl')) out.push({ project: dir, file: path.join(full, f) });
+    }
+  }
+  return out;
+}
+
+function* iterTurns(file) {
+  let lines;
+  try { lines = fs.readFileSync(file, 'utf8').split(/\r?\n/); }
+  catch { return; }
+  for (const line of lines) {
+    if (!line) continue;
+    try { yield JSON.parse(line); } catch {}
+  }
+}
+
+function extractBashCommands(turn) {
+  const out = [];
+  const msg = turn.message;
+  if (!msg || !Array.isArray(msg.content)) return out;
+  for (const c of msg.content) {
+    if (c.type === 'tool_use' && (c.name === 'Bash' || c.name === 'PowerShell')) {
+      out.push({ tool: c.name, cmd: c.input?.command || '', id: c.id });
+    }
+  }
+  return out;
+}
+
+function turnTs(turn) {
+  return Date.parse(turn.timestamp || '') || 0;
+}
+
+function gitDisciplineScan(transcripts, cutoff) {
+  const findings = [];
+  for (const { project, file } of transcripts) {
+    let lastCommitTs = null, lastCommitSess = null, sawPushAfterCommit = false;
+    for (const turn of iterTurns(file)) {
+      const ts = turnTs(turn);
+      if (cutoff && ts && ts < cutoff) continue;
+      const cmds = extractBashCommands(turn);
+      for (const { tool, cmd } of cmds) {
+        if (!cmd) continue;
+        if (/\bgit\s+push\b/.test(cmd) && !/exec-spool|spool-dispatch|git_push/.test(cmd)) {
+          findings.push({ kind: 'raw-push', project, file: path.basename(file), ts, tool, cmd: cmd.slice(0, 120), sess: turn.sessionId });
+          sawPushAfterCommit = true;
+        }
+        if (/\bgit\s+commit\b/.test(cmd)) {
+          if (lastCommitTs && !sawPushAfterCommit) {
+            findings.push({ kind: 'commit-without-push', project, file: path.basename(file), ts: lastCommitTs, sess: lastCommitSess, cmd: '(prior commit had no push)' });
+          }
+          lastCommitTs = ts; lastCommitSess = turn.sessionId; sawPushAfterCommit = false;
+        }
+        if (/git\s+push.*--force\b/.test(cmd)) {
+          findings.push({ kind: 'force-push', project, file: path.basename(file), ts, tool, cmd: cmd.slice(0,120), sess: turn.sessionId });
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+function collectPlugkitEvents(cutoff) {
+  const root = path.join(os.homedir(), '.claude', 'gm-log');
+  const events = [];
+  if (!fs.existsSync(root)) { console.log(col('d', `no log at ${root}`)); return events; }
+  for (const date of fs.readdirSync(root)) {
+    const pj = path.join(root, date, 'plugkit.jsonl');
+    if (!fs.existsSync(pj)) continue;
+    let lines; try { lines = fs.readFileSync(pj, 'utf8').split(/\r?\n/); } catch { continue; }
+    for (const line of lines) {
+      if (!line) continue;
+      try {
+        const ev = JSON.parse(line);
+        const ts = Date.parse(ev.ts || '') || 0;
+        if (cutoff && ts && ts < cutoff) continue;
+        ev._ts = ts;
+        events.push(ev);
+      } catch {}
+    }
+  }
+  return events;
+}
+
+function learningXref(transcripts, cutoff) {
+  const events = collectPlugkitEvents(cutoff);
+  const bySess = new Map();
+  for (const ev of events) {
+    const s = ev.sess || '';
+    if (!s) continue;
+    if (!bySess.has(s)) bySess.set(s, []);
+    bySess.get(s).push(ev);
+  }
+  const xrefs = [];
+  for (const { project, file } of transcripts) {
+    for (const turn of iterTurns(file)) {
+      const sess = turn.sessionId;
+      const ts = turnTs(turn);
+      if (cutoff && ts && ts < cutoff) continue;
+      if (!sess || !bySess.has(sess)) continue;
+      const candidates = bySess.get(sess).filter(ev => Math.abs((ev._ts||0) - ts) < 60000);
+      for (const ev of candidates) {
+        xrefs.push({ project, sess, turnTs: ts, evTs: ev._ts, event: ev.event, verb: ev.verb, dur: ev.dur_ms });
+      }
+    }
+  }
+  return xrefs;
+}
+
+function fmtTs(ts) { return ts ? new Date(ts).toISOString().slice(0,19).replace('T',' ') : '----------'; }
+
+function main() {
+  const { flags, since, project } = parseArgs(process.argv);
+  const cutoff = since ? Date.now() - since : 0;
+  const transcripts = findTranscripts(project);
+  console.log(col('bold', `ccsniff — ${transcripts.length} transcript(s)${since ? `, since ${since/1000}s` : ''}${project ? `, project=${project}` : ''}`));
+  console.log(col('d', '-'.repeat(80)));
+
+  if (flags.has('git-discipline') || flags.size === 0) {
+    const findings = gitDisciplineScan(transcripts, cutoff);
+    console.log(col('bold', `git-discipline: ${findings.length} finding(s)`));
+    const byKind = {};
+    for (const f of findings) byKind[f.kind] = (byKind[f.kind]||0)+1;
+    console.log(col('d', '  by kind: ') + Object.entries(byKind).map(([k,v]) => `${col('y',k)}=${v}`).join('  '));
+    for (const f of findings.slice(-200)) {
+      const tag = f.kind === 'raw-push' ? col('r','RAW-PUSH        ')
+                : f.kind === 'commit-without-push' ? col('y','COMMIT-NO-PUSH  ')
+                : col('r','FORCE-PUSH      ');
+      console.log(`${col('d', fmtTs(f.ts))} ${tag} ${col('m','['+String(f.sess||'').slice(0,8)+']')} ${col('c', f.project.slice(0,40))} ${f.cmd||''}`);
+    }
+    console.log();
+  }
+
+  if (flags.has('learning-xref')) {
+    const xrefs = learningXref(transcripts, cutoff);
+    console.log(col('bold', `learning-xref: ${xrefs.length} joined turn/event pair(s)`));
+    for (const x of xrefs.slice(-200)) {
+      console.log(`${col('d', fmtTs(x.turnTs))} ${col('m','['+x.sess.slice(0,8)+']')} ${col('c', x.event||'').padEnd(24)} verb=${x.verb||''} dur=${x.dur||''}ms proj=${x.project.slice(0,30)}`);
+    }
+  }
+}
+
+main();

package/bin/gmsniff.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const C = { r:'\x1b[31m', g:'\x1b[32m', y:'\x1b[33m', b:'\x1b[34m', m:'\x1b[35m', c:'\x1b[36m', d:'\x1b[2m', x:'\x1b[0m', bold:'\x1b[1m' };
+const useColor = process.stdout.isTTY;
+const col = (k, s) => useColor ? C[k] + s + C.x : s;
+
+function parseDuration(s) {
+  if (!s) return null;
+  const m = String(s).match(/^(\d+)([smhd])$/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  const mult = { s:1000, m:60000, h:3600000, d:86400000 }[m[2]];
+  return n * mult;
+}
+
+function parseArgs(argv) {
+  const flags = new Set();
+  let since = null;
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--since') { since = parseDuration(argv[++i]); continue; }
+    if (a.startsWith('--')) flags.add(a.slice(2));
+  }
+  return { flags, since };
+}
+
+function readLines(p) {
+  if (!fs.existsSync(p)) { console.log(col('d', `no log at ${p}`)); return []; }
+  try { return fs.readFileSync(p, 'utf8').split(/\r?\n/).filter(Boolean); }
+  catch (e) { console.log(col('r', `read err ${p}: ${e.message}`)); return []; }
+}
+
+function collectEvents(sinceMs) {
+  const events = [];
+  const cutoff = sinceMs ? Date.now() - sinceMs : 0;
+  const cwd = process.cwd();
+  const wlog = path.join(cwd, '.gm', 'exec-spool', '.watcher.log');
+  for (const line of readLines(wlog)) {
+    const m = line.match(/evt:\s*(\{.*\})\s*$/);
+    if (!m) continue;
+    try {
+      const ev = JSON.parse(m[1]);
+      const ts = typeof ev.ts === 'number' ? ev.ts : Date.parse(ev.ts || '');
+      if (ts && ts < cutoff) continue;
+      ev._ts = ts || 0; ev._src = 'watcher.log';
+      events.push(ev);
+    } catch {}
+  }
+  const gmLogRoot = path.join(os.homedir(), '.claude', 'gm-log');
+  if (fs.existsSync(gmLogRoot)) {
+    for (const date of fs.readdirSync(gmLogRoot)) {
+      const pj = path.join(gmLogRoot, date, 'plugkit.jsonl');
+      if (!fs.existsSync(pj)) continue;
+      for (const line of readLines(pj)) {
+        try {
+          const ev = JSON.parse(line);
+          const ts = Date.parse(ev.ts || '') || ev.ts || 0;
+          if (ts && ts < cutoff) continue;
+          ev._ts = ts; ev._src = `gm-log/${date}/plugkit.jsonl`;
+          events.push(ev);
+        } catch {}
+      }
+    }
+  }
+  events.sort((a,b) => (a._ts||0) - (b._ts||0));
+  return events;
+}
+
+function fmtTs(ts) {
+  if (!ts) return '----------';
+  return new Date(ts).toISOString().slice(11, 19);
+}
+
+function evName(ev) { return ev.event || ''; }
+
+const FILTERS = {
+  'embed-failures': ev => /^embed_(fail|init_fail|cached_fail|init_cached_fail)$/.test(evName(ev)),
+  'recall-misses': ev => evName(ev) === 'recall' && (ev.hits === 0 || (Array.isArray(ev.results) && ev.results.length === 0)),
+  'recall-scores': ev => evName(ev) === 'recall' || evName(ev) === 'recall_score_unavailable',
+  'classifier-rejects': ev => evName(ev) === 'memorize_reject',
+  'memory-leverage': ev => evName(ev) === 'recall' && (ev.hits > 0 || (Array.isArray(ev.results) && ev.results.length > 0)),
+  'recall-modes': ev => evName(ev) === 'recall' && ev.mode,
+  'table-drops': ev => evName(ev) === 'table_dropped',
+  'discipline-sigil-ignored': ev => evName(ev) === 'discipline_sigil_ignored',
+};
+
+function renderEvent(ev, kinds) {
+  const t = col('d', fmtTs(ev._ts));
+  const name = col('c', evName(ev).padEnd(28));
+  const sess = ev.sess ? col('m', `[${String(ev.sess).slice(0,16)}]`) : '';
+  const extras = [];
+  if (kinds.has('embed-failures') && ev.step) extras.push(`step=${ev.step}`);
+  if (ev.error) extras.push(col('r', `err=${String(ev.error).slice(0,80)}`));
+  if (ev.reason) extras.push(`reason=${ev.reason}`);
+  if (ev.text_prefix) extras.push(col('y', `text="${String(ev.text_prefix).slice(0,40)}"`));
+  if (ev.namespace) extras.push(`ns=${ev.namespace}`);
+  if (ev.mode) extras.push(col('g', `mode=${ev.mode}`));
+  if (ev.derived_query) extras.push(`q="${String(ev.derived_query).slice(0,40)}"`);
+  if (typeof ev.hits === 'number') extras.push(`hits=${ev.hits}`);
+  if (typeof ev.score === 'number') extras.push(`score=${ev.score.toFixed(3)}`);
+  if (ev.sigil) extras.push(col('y', `sigil=@${ev.sigil}`));
+  if (ev.key && evName(ev) === 'table_dropped') extras.push(`key=${ev.key}`);
+  return `${t} ${name} ${sess} ${extras.join(' ')}`;
+}
+
+function summarize(events) {
+  const counts = {};
+  for (const ev of events) {
+    const n = evName(ev) || '(unknown)';
+    counts[n] = (counts[n] || 0) + 1;
+  }
+  return counts;
+}
+
+function main() {
+  const { flags, since } = parseArgs(process.argv);
+  const allEvents = collectEvents(since);
+  const activeFilters = [...flags].filter(f => FILTERS[f]);
+  const useAll = activeFilters.length === 0;
+  const kinds = new Set(activeFilters);
+  const matched = useAll ? allEvents : allEvents.filter(ev => activeFilters.some(f => FILTERS[f](ev)));
+
+  console.log(col('bold', `gmsniff — ${matched.length} event(s)${since ? ` in last ${since/1000}s` : ''}${activeFilters.length ? `, filters: ${activeFilters.join(',')}` : ' (all)'}`));
+  const counts = summarize(matched);
+  const summary = Object.entries(counts).sort((a,b) => b[1]-a[1]).map(([k,v]) => `${col('c',k)}=${v}`).join('  ');
+  if (summary) console.log(col('d', 'by event: ') + summary);
+  console.log(col('d', '-'.repeat(80)));
+
+  if (kinds.has('recall-modes')) {
+    const modeCounts = {};
+    for (const ev of matched) if (ev.mode) modeCounts[ev.mode] = (modeCounts[ev.mode] || 0) + 1;
+    console.log(col('bold','recall mode distribution:'));
+    for (const [m,n] of Object.entries(modeCounts)) console.log(`  ${col('g',m.padEnd(20))} ${n}`);
+    console.log();
+  }
+
+  for (const ev of matched) console.log(renderEvent(ev, kinds));
+}
+
+main();

package/bin/plugkit-supervisor.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, spawnSync } = require('child_process');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const spoolDir = path.join(projectDir, '.gm', 'exec-spool');
+fs.mkdirSync(spoolDir, { recursive: true });
+
+const STATUS_PATH = path.join(spoolDir, '.status.json');
+const SHUTDOWN_REASON_PATH = path.join(spoolDir, '.shutdown-reason.json');
+const SUPERVISOR_STATUS_PATH = path.join(spoolDir, '.supervisor-status.json');
+const SUPERVISOR_PID_PATH = path.join(spoolDir, '.supervisor.pid');
+const LOG_PATH = path.join(spoolDir, '.watcher.log');
+const GM_LOG_ROOT = process.env.GM_LOG_DIR || path.join(os.homedir(), '.claude', 'gm-log');
+
+const HEARTBEAT_STALE_MS = 60_000;
+const HEALTH_POLL_MS = 5_000;
+const SUPERVISOR_HEARTBEAT_MS = 5_000;
+const SIGTERM_GRACE_MS = 5_000;
+const BACKOFF_BASE_MS = 2_000;
+const BACKOFF_CAP_MS = 30_000;
+
+function logEvent(event, fields) {
+  try {
+    const day = new Date().toISOString().slice(0, 10);
+    const dir = path.join(GM_LOG_ROOT, day);
+    fs.mkdirSync(dir, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      sub: 'plugkit',
+      event,
+      pid: process.pid,
+      sess: process.env.CLAUDE_SESSION_ID || '',
+      cwd: projectDir,
+      role: 'supervisor',
+      ...fields,
+    }) + '\n';
+    fs.appendFileSync(path.join(dir, 'plugkit.jsonl'), line);
+  } catch (_) {}
+}
+
+function writeSupervisorStatus(state, extra) {
+  try {
+    fs.writeFileSync(SUPERVISOR_STATUS_PATH, JSON.stringify({
+      pid: process.pid,
+      ts: Date.now(),
+      iso: new Date().toISOString(),
+      state,
+      watcher_pid: currentChildPid,
+      ...(extra || {}),
+    }));
+  } catch (_) {}
+}
+
+function writeShutdownReason(reason, extra) {
+  try {
+    fs.writeFileSync(SHUTDOWN_REASON_PATH, JSON.stringify({
+      ts: new Date().toISOString(),
+      reason,
+      written_by: 'supervisor',
+      supervisor_pid: process.pid,
+      watcher_pid: currentChildPid,
+      ...(extra || {}),
+    }));
+  } catch (_) {}
+}
+
+function pidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (_) { return false; }
+}
+
+function readStatus() {
+  try { return JSON.parse(fs.readFileSync(STATUS_PATH, 'utf-8')); } catch (_) { return null; }
+}
+
+function statusMtime() {
+  try { return fs.statSync(STATUS_PATH).mtimeMs; } catch (_) { return 0; }
+}
+
+function acquireSingleInstance() {
+  try {
+    if (fs.existsSync(SUPERVISOR_PID_PATH)) {
+      const raw = fs.readFileSync(SUPERVISOR_PID_PATH, 'utf-8').trim();
+      const other = parseInt(raw, 10);
+      if (Number.isFinite(other) && other !== process.pid && pidAlive(other)) {
+        logEvent('supervisor.refused-duplicate', { existing_pid: other, severity: 'warn' });
+        process.stderr.write(`[plugkit-supervisor] another supervisor is alive (pid=${other}); exiting\n`);
+        return false;
+      }
+    }
+    fs.writeFileSync(SUPERVISOR_PID_PATH, String(process.pid));
+    return true;
+  } catch (e) {
+    logEvent('supervisor.pid-write-failed', { error: e.message, severity: 'warn' });
+    return true;
+  }
+}
+
+function releaseSingleInstance() {
+  try {
+    if (fs.existsSync(SUPERVISOR_PID_PATH)) {
+      const raw = fs.readFileSync(SUPERVISOR_PID_PATH, 'utf-8').trim();
+      if (parseInt(raw, 10) === process.pid) fs.unlinkSync(SUPERVISOR_PID_PATH);
+    }
+  } catch (_) {}
+}
+
+let currentChildPid = null;
+let currentChild = null;
+let restartCount = 0;
+let lastSpawnedAt = 0;
+let shuttingDown = false;
+let killingForHeartbeat = false;
+
+function nextBackoffMs() {
+  const ms = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * Math.pow(2, restartCount));
+  return ms;
+}
+
+function resolveWrapper() {
+  return path.join(os.homedir(), '.claude', 'gm-tools', 'plugkit-wasm-wrapper.js');
+}
+
+function resolveRuntime() {
+  const preferred = process.env.PLUGKIT_RUNTIME || 'bun';
+  try {
+    const r = spawnSync(preferred, ['--version'], { stdio: 'ignore', windowsHide: true, timeout: 1500 });
+    if (r.status === 0) return preferred;
+  } catch (_) {}
+  return process.execPath;
+}
+
+function spawnWatcher(bootReason) {
+  if (shuttingDown) return;
+  const wrapper = resolveWrapper();
+  if (!fs.existsSync(wrapper)) {
+    logEvent('supervisor.wrapper-missing', { wrapper, severity: 'critical' });
+    writeSupervisorStatus('error', { error: 'wrapper-missing', wrapper });
+    setTimeout(() => spawnWatcher(bootReason), Math.min(BACKOFF_CAP_MS, nextBackoffMs()));
+    restartCount += 1;
+    return;
+  }
+  const runtime = resolveRuntime();
+  let logFd = null;
+  try { logFd = fs.openSync(LOG_PATH, 'a'); } catch (_) {}
+  try {
+    if (logFd !== null) fs.writeSync(logFd, `\n--- watcher spawn ${new Date().toISOString()} supervisor=${process.pid} reason=${bootReason} ---\n`);
+  } catch (_) {}
+
+  const child = spawn(runtime, [wrapper, 'spool'], {
+    detached: false,
+    stdio: ['ignore', logFd || 'ignore', logFd || 'ignore'],
+    windowsHide: true,
+    env: {
+      ...process.env,
+      CLAUDE_PROJECT_DIR: projectDir,
+      PLUGKIT_BOOT_REASON: bootReason,
+      PLUGKIT_SUPERVISOR_PID: String(process.pid),
+    },
+    ...(process.platform === 'win32' ? { creationFlags: 0x08000000 | 0x00000008 } : {}),
+  });
+
+  try { if (logFd !== null) fs.closeSync(logFd); } catch (_) {}
+  currentChild = child;
+  currentChildPid = child.pid;
+  lastSpawnedAt = Date.now();
+  writeSupervisorStatus('watching', { boot_reason: bootReason, runtime });
+  logEvent('supervisor.spawned-watcher', { watcher_pid: child.pid, boot_reason: bootReason, runtime });
+
+  child.on('exit', (code, signal) => {
+    const wasKilled = killingForHeartbeat;
+    killingForHeartbeat = false;
+    const exitedPid = currentChildPid;
+    currentChild = null;
+    currentChildPid = null;
+    if (shuttingDown) return;
+    const uptimeMs = Date.now() - lastSpawnedAt;
+    const respawnReason = wasKilled ? 'supervisor-killed-stale-heartbeat' : (signal ? `signal-${signal}` : `exit-${code}`);
+    logEvent('supervisor.watcher-exited', {
+      watcher_pid: exitedPid,
+      exit_code: code,
+      signal,
+      uptime_ms: uptimeMs,
+      respawn_reason: respawnReason,
+      severity: code === 0 && !signal && !wasKilled ? 'info' : 'critical',
+    });
+    if (code === 0 && !signal && !wasKilled) {
+      restartCount = 0;
+    } else {
+      restartCount += 1;
+    }
+    const delay = nextBackoffMs();
+    writeSupervisorStatus('restarting', { prior_watcher_pid: exitedPid, prior_exit_code: code, prior_signal: signal, respawn_reason: respawnReason, backoff_ms: delay });
+    setTimeout(() => spawnWatcher(respawnReason), delay);
+  });
+
+  child.on('error', (err) => {
+    logEvent('supervisor.spawn-error', { error: err.message, severity: 'critical' });
+  });
+}
+
+function killChild(reason) {
+  if (!currentChildPid || !pidAlive(currentChildPid)) return;
+  killingForHeartbeat = true;
+  writeShutdownReason(reason, { uptime_ms: Date.now() - lastSpawnedAt });
+  try { process.kill(currentChildPid, 'SIGTERM'); } catch (_) {}
+  const pidAtKill = currentChildPid;
+  setTimeout(() => {
+    if (pidAtKill && pidAlive(pidAtKill)) {
+      logEvent('supervisor.sigkill-after-grace', { watcher_pid: pidAtKill, grace_ms: SIGTERM_GRACE_MS, severity: 'warn' });
+      if (process.platform === 'win32') {
+        try { spawnSync('taskkill', ['/F', '/T', '/PID', String(pidAtKill)], { stdio: 'ignore', windowsHide: true, timeout: 3000 }); } catch (_) {}
+      } else {
+        try { process.kill(pidAtKill, 'SIGKILL'); } catch (_) {}
+      }
+    }
+  }, SIGTERM_GRACE_MS);
+}
+
+function checkWatcherHealth() {
+  if (shuttingDown) return;
+  if (!currentChildPid) return;
+  if (!pidAlive(currentChildPid)) return;
+  const mtime = statusMtime();
+  if (mtime === 0) {
+    const age = Date.now() - lastSpawnedAt;
+    if (age > HEARTBEAT_STALE_MS) {
+      logEvent('supervisor.no-heartbeat-file', { watcher_pid: currentChildPid, age_since_spawn_ms: age, severity: 'critical' });
+      killChild('supervisor-killed-no-heartbeat');
+    }
+    return;
+  }
+  const age = Date.now() - mtime;
+  if (age > HEARTBEAT_STALE_MS) {
+    logEvent('supervisor.heartbeat-stale', {
+      watcher_pid: currentChildPid,
+      status_age_ms: age,
+      stale_limit_ms: HEARTBEAT_STALE_MS,
+      severity: 'critical',
+    });
+    killChild('supervisor-killed-stale-heartbeat');
+  }
+}
+
+function shutdown(reason) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  logEvent('supervisor.shutdown', { reason });
+  writeSupervisorStatus('shutdown', { reason });
+  if (currentChildPid && pidAlive(currentChildPid)) {
+    writeShutdownReason('supervisor-graceful-shutdown', { trigger: reason, uptime_ms: Date.now() - lastSpawnedAt });
+    try { process.kill(currentChildPid, 'SIGTERM'); } catch (_) {}
+    const pidAtKill = currentChildPid;
+    const start = Date.now();
+    const waitInterval = setInterval(() => {
+      if (!pidAlive(pidAtKill)) {
+        clearInterval(waitInterval);
+        releaseSingleInstance();
+        process.exit(0);
+      } else if (Date.now() - start > SIGTERM_GRACE_MS) {
+        clearInterval(waitInterval);
+        if (process.platform === 'win32') {
+          try { spawnSync('taskkill', ['/F', '/T', '/PID', String(pidAtKill)], { stdio: 'ignore', windowsHide: true, timeout: 3000 }); } catch (_) {}
+        } else {
+          try { process.kill(pidAtKill, 'SIGKILL'); } catch (_) {}
+        }
+        releaseSingleInstance();
+        process.exit(0);
+      }
+    }, 200);
+  } else {
+    releaseSingleInstance();
+    process.exit(0);
+  }
+}
+
+process.on('SIGINT', () => shutdown('sigint'));
+process.on('SIGTERM', () => shutdown('sigterm'));
+process.on('uncaughtException', (err) => {
+  logEvent('supervisor.uncaught', { error: err.message, stack: err.stack, severity: 'critical' });
+  shutdown('uncaught-exception');
+});
+
+if (!acquireSingleInstance()) {
+  process.exit(0);
+}
+
+writeSupervisorStatus('starting', {});
+logEvent('supervisor.starting', { spool_dir: spoolDir, heartbeat_stale_ms: HEARTBEAT_STALE_MS });
+spawnWatcher('initial');
+setInterval(checkWatcherHealth, HEALTH_POLL_MS);
+setInterval(() => writeSupervisorStatus('watching', {}), SUPERVISOR_HEARTBEAT_MS);

package/gm-plugkit/plugkit-wasm-wrapper.js

@@ -461,15 +461,17 @@ function writeJsonFile(fp, value) {
   try { fs.writeFileSync(fp, JSON.stringify(value, null, 2)); } catch (_) {}
 }
 
-function findPlaywriter() {
+const BROWSER_RUNNER_BIN = process.env.GM_BROWSER_RUNNER_BIN || 'playwriter';
+
+function findBrowserRunner() {
   const npmR = spawnSync('npm', ['root', '-g'], { encoding: 'utf-8', shell: true });
   if (npmR.status === 0 && npmR.stdout.trim()) {
     const root = npmR.stdout.trim().split(/\r?\n/).pop();
-    const binJs = path.join(root, 'playwriter', 'bin.js');
+    const binJs = path.join(root, BROWSER_RUNNER_BIN, 'bin.js');
     if (fs.existsSync(binJs)) return { cmd: process.execPath, baseArgs: [binJs], shell: false };
   }
   const whichCmd = process.platform === 'win32' ? 'where' : 'which';
-  const r = spawnSync(whichCmd, ['playwriter'], { encoding: 'utf-8', shell: true });
+  const r = spawnSync(whichCmd, [BROWSER_RUNNER_BIN], { encoding: 'utf-8', shell: true });
   if (r.status === 0 && r.stdout.trim()) {
     const candidates = r.stdout.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
     const cmd = candidates.find(c => c.toLowerCase().endsWith('.cmd')) || candidates.find(c => !c.toLowerCase().endsWith('.ps1')) || candidates[0];
@@ -477,11 +479,11 @@ function findPlaywriter() {
   }
   const bunR = spawnSync(whichCmd, ['bun'], { encoding: 'utf-8', shell: true });
   if (bunR.status === 0 && bunR.stdout.trim()) {
-    return { cmd: 'bun', baseArgs: ['x', 'playwriter@latest'], shell: true };
+    return { cmd: 'bun', baseArgs: ['x', `${BROWSER_RUNNER_BIN}@latest`], shell: true };
   }
   const npxR = spawnSync(whichCmd, ['npx'], { encoding: 'utf-8', shell: true });
   if (npxR.status === 0 && npxR.stdout.trim()) {
-    return { cmd: 'npx', baseArgs: ['-y', 'playwriter'], shell: true };
+    return { cmd: 'npx', baseArgs: ['-y', BROWSER_RUNNER_BIN], shell: true };
   }
   return null;
 }
@@ -637,7 +639,7 @@ function sleepSync(ms) {
   spawnSync(process.execPath, ['-e', `setTimeout(()=>{}, ${ms})`], { timeout: ms + 2000 });
 }
 
-function runPlaywriter(pw, args, timeoutMs) {
+function runBrowserRunner(pw, args, timeoutMs) {
   const allArgs = [...pw.baseArgs, ...args];
   const useShell = !!pw.shell;
   const spawnCmd = useShell && /\s/.test(pw.cmd) ? `"${pw.cmd}"` : pw.cmd;
@@ -654,7 +656,7 @@ function runPlaywriter(pw, args, timeoutMs) {
 function scrubBrowserRunnerText(s) {
   if (!s || typeof s !== 'string') return s;
   let t = s;
-  t = t.replace(/(^|[^A-Za-z0-9_\\/.-])playwriter(?![A-Za-z0-9_\\/.-])/gi, (m, pre) => `${pre}managed browser session`);
+  t = t.replace(/(^|[^A-Za-z0-9_\\/.-])(playwriter|playwright|puppeteer)(?![A-Za-z0-9_\\/.-])/gi, (m, pre) => `${pre}managed browser session`);
   t = t.replace(/Click the[^.\n]*?extension[^.\n]*?icon[^.\n]*?\.?/gi, '');
   t = t.replace(/(connected\s+)?browser\s+extension(\s+is)?\s+not\s+connected\b[^.\n]*\.?/gi, '');
   t = t.replace(/no\s+connected\s+browsers?\b[^.\n]*\.?/gi, '');
@@ -664,18 +666,20 @@ function scrubBrowserRunnerText(s) {
 
 function findInstalledChromiumBinary() {
   try {
-    if (process.env.PLAYWRITER_BROWSER_PATH && fs.existsSync(process.env.PLAYWRITER_BROWSER_PATH)) {
-      return process.env.PLAYWRITER_BROWSER_PATH;
+    const explicit = process.env.GM_BROWSER_RUNNER_PATH || process.env.PLAYWRITER_BROWSER_PATH;
+    if (explicit && fs.existsSync(explicit)) {
+      return explicit;
     }
     const roots = [];
+    const cacheDir = process.env.GM_BROWSER_RUNNER_CACHE_DIR || 'ms-playwright';
     if (process.platform === 'win32') {
       const lad = process.env.LOCALAPPDATA;
-      if (lad) roots.push(path.join(lad, 'ms-playwright'));
+      if (lad) roots.push(path.join(lad, cacheDir));
     } else {
       const home = process.env.HOME || '';
       if (home) {
-        roots.push(path.join(home, '.cache', 'ms-playwright'));
-        roots.push(path.join(home, 'Library', 'Caches', 'ms-playwright'));
+        roots.push(path.join(home, '.cache', cacheDir));
+        roots.push(path.join(home, 'Library', 'Caches', cacheDir));
       }
     }
     const exeName = process.platform === 'win32' ? 'chrome.exe' : (process.platform === 'darwin' ? 'Chromium.app/Contents/MacOS/Chromium' : 'chrome');
@@ -707,9 +711,10 @@ function findInstalledChromiumBinary() {
 function startManagedBrowser(pw, profileDir) {
   const args = [...pw.baseArgs, 'browser', 'start', '--user-data-dir', profileDir, '--headless'];
   const env = { ...process.env };
-  if (!env.PLAYWRITER_BROWSER_PATH) {
+  if (!env.GM_BROWSER_RUNNER_PATH && !env.PLAYWRITER_BROWSER_PATH) {
     const browserBin = findInstalledChromiumBinary();
     if (browserBin) {
+      env.GM_BROWSER_RUNNER_PATH = browserBin;
       env.PLAYWRITER_BROWSER_PATH = browserBin;
       logEvent('plugkit', 'browser.binary-resolved', { path: browserBin });
     } else {
@@ -742,24 +747,24 @@ function isColdRunProfile(profileDir) {
 }
 
 function resolveManagedBrowserKey(pw) {
-  if (process.env.PLAYWRITER_BROWSER_KEY) {
-    const k = process.env.PLAYWRITER_BROWSER_KEY;
-    if (/^profile:/.test(k)) {
-      throw new Error(`PLAYWRITER_BROWSER_KEY=${k} points at a user OS browser profile; refusing — managed sessions must use install:Chromium:*`);
+  const explicitKey = process.env.GM_BROWSER_RUNNER_KEY || process.env.PLAYWRITER_BROWSER_KEY;
+  if (explicitKey) {
+    if (/^profile:/.test(explicitKey)) {
+      throw new Error(`GM_BROWSER_RUNNER_KEY=${explicitKey} points at a user OS browser profile; refusing — managed sessions must use install:Chromium:*`);
     }
-    return k;
+    return explicitKey;
   }
   let text = '';
   try {
-    const r = runPlaywriter(pw, ['browser', 'list'], 8000);
+    const r = runBrowserRunner(pw, ['browser', 'list'], 8000);
     text = (r && (r.stdout || r.stderr)) || '';
   } catch (e) {
-    throw new Error(`playwriter browser list failed: ${e.message}`);
+    throw new Error(`managed browser session list failed: ${e.message}`);
   }
   const lines = text.split(/\r?\n/);
   const installChromium = lines.map(l => (l.match(/\b(install:Chromium:[A-Za-z0-9_-]+)\b/) || [])[1]).find(Boolean);
   if (installChromium) return installChromium;
-  throw new Error(`no managed Chromium install detected; playwriter browser list returned: ${scrubBrowserRunnerText(text).trim()}`);
+  throw new Error(`no managed Chromium install detected; browser runner returned: ${scrubBrowserRunnerText(text).trim()}`);
 }
 
 function waitForExtensionReady(pw, profileDir, opts) {
@@ -775,7 +780,7 @@ function waitForExtensionReady(pw, profileDir, opts) {
   while (Date.now() < deadline) {
     const remaining = deadline - Date.now();
     const innerTimeout = Math.max(28000, Math.min(remaining, 30000));
-    const r = runPlaywriter(pw, ['session', 'new', '--browser', browserKey], innerTimeout);
+    const r = runBrowserRunner(pw, ['session', 'new', '--browser', browserKey], innerTimeout);
     if (r && r.status === 0) return r;
     lastErr = scrubBrowserRunnerText((r && (r.stderr || r.stdout)) || '');
     const now = Date.now();
@@ -1461,11 +1466,11 @@ function makeHostFunctions(instanceRef) {
         const body = readWasmStr(instanceRef.value, bodyPtr, bodyLen);
         const cwd = readWasmStr(instanceRef.value, cwdPtr, cwdLen) || process.cwd();
         const sessionId = readWasmStr(instanceRef.value, sidPtr, sidLen) || 'default';
-        const pw = findPlaywriter();
+        const pw = findBrowserRunner();
         if (!pw) return writeWasmJson(instanceRef.value, { ok: false, error: 'managed browser session runner not available' });
         if (body.startsWith('session ')) {
           const parts = body.slice(8).trim().split(/\s+/);
-          const r = runPlaywriter(pw, ['session', ...parts], 30000);
+          const r = runBrowserRunner(pw, ['session', ...parts], 30000);
           return writeWasmJson(instanceRef.value, {
             ok: r.status === 0,
             stdout: scrubBrowserRunnerText(r.stdout || ''),
@@ -1474,7 +1479,7 @@ function makeHostFunctions(instanceRef) {
           });
         }
         const pwSessionId = getOrCreateBrowserSession(cwd, sessionId, pw);
-        const r = runPlaywriter(pw, ['-s', pwSessionId, '--timeout', '14000', '-e', body], 60000);
+        const r = runBrowserRunner(pw, ['-s', pwSessionId, '--timeout', '14000', '-e', body], 60000);
         return writeWasmJson(instanceRef.value, {
           ok: r.status === 0,
           stdout: scrubBrowserRunnerText(r.stdout || ''),
@@ -1659,7 +1664,13 @@ async function runSpoolWatcher(instance, spoolDir) {
       const ageMs = Date.now() - priorBoot.ts;
       const shutdownIsNewer = priorShutdownForAbort && Number.isFinite(priorShutdownForAbort.ts) && priorShutdownForAbort.ts >= priorBoot.ts;
       if (ageMs > 30_000 && !shutdownIsNewer) {
-        logEvent('plugkit', 'watcher.silent-abort', {
+        let priorVerbSnap = null;
+        let priorStatusSnap = null;
+        let priorPidAlive = null;
+        try { priorVerbSnap = JSON.parse(fs.readFileSync(VERB_ACTIVE_PATH, 'utf-8')); } catch (_) {}
+        try { priorStatusSnap = JSON.parse(fs.readFileSync(path.join(path.dirname(BOOT_ACTIVE_PATH), '.status.json'), 'utf-8')); } catch (_) {}
+        try { process.kill(priorBoot.pid, 0); priorPidAlive = true; } catch (e) { priorPidAlive = e.code === 'EPERM'; }
+        const forensics = {
           prior_pid: priorBoot.pid,
           prior_ts: priorBoot.ts,
           prior_sha: priorBoot.wrapper_sha || null,
@@ -1668,8 +1679,15 @@ async function runSpoolWatcher(instance, spoolDir) {
           age_ms: ageMs,
           shutdown_reason_present: !!priorShutdownForAbort,
           shutdown_reason_ts: priorShutdownForAbort ? priorShutdownForAbort.ts : null,
-        });
-        try { console.error(`[plugkit-wasm] SILENT ABORT detected: prior watcher pid=${priorBoot.pid} sha=${priorBoot.wrapper_sha} died without writing .shutdown-reason.json (age=${ageMs}ms)`); } catch (_) {}
+          prior_verb_active: priorVerbSnap,
+          prior_status: priorStatusSnap,
+          prior_pid_alive: priorPidAlive,
+        };
+        logEvent('plugkit', 'watcher.silent-abort', forensics);
+        try {
+          fs.writeFileSync(path.join(path.dirname(BOOT_ACTIVE_PATH), '.silent-abort-forensics.json'), JSON.stringify(forensics, null, 2));
+        } catch (_) {}
+        try { console.error(`[plugkit-wasm] SILENT ABORT detected: prior watcher pid=${priorBoot.pid} sha=${priorBoot.wrapper_sha} died without writing .shutdown-reason.json (age=${ageMs}ms, prior_pid_alive=${priorPidAlive})`); } catch (_) {}
       }
     }
   } catch (_) {}

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1291",
+  "version": "2.0.1292",
   "description": "Spool-dispatch orchestration engine with unified state machine, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/lib/skill-bootstrap.js

@@ -10,6 +10,7 @@ const PLUGKIT_TOOLS_DIR = path.join(os.homedir(), '.claude', 'gm-tools');
 const PLUGKIT_VERSION_FILE = path.join(PLUGKIT_TOOLS_DIR, 'plugkit.version');
 const PLUGKIT_WASM_PATH = path.join(PLUGKIT_TOOLS_DIR, 'plugkit.wasm');
 const PLUGKIT_WASM_WRAPPER = path.join(PLUGKIT_TOOLS_DIR, 'plugkit-wasm-wrapper.js');
+const PLUGKIT_SUPERVISOR = path.join(PLUGKIT_TOOLS_DIR, 'plugkit-supervisor.js');
 const BOOTSTRAP_STATUS_FILE = path.join(os.homedir(), '.gm', 'bootstrap-status.json');
 const BOOTSTRAP_ERROR_FILE = path.join(os.homedir(), '.gm', 'bootstrap-error.json');
 const LOG_DIR = path.join(os.homedir(), '.claude', 'gm-log');
@@ -385,12 +386,28 @@ function findPlugkitWasmPids() {
 }
 
 function isProcessRunning() {
-  return findPlugkitWasmPids().length > 0;
+  if (findPlugkitWasmPids().length > 0) return true;
+  try {
+    const supervisorPidFile = path.join(process.cwd(), '.gm', 'exec-spool', '.supervisor.pid');
+    if (!fs.existsSync(supervisorPidFile)) return false;
+    const pid = parseInt(fs.readFileSync(supervisorPidFile, 'utf8').trim(), 10);
+    if (!Number.isFinite(pid) || pid <= 0) return false;
+    try { process.kill(pid, 0); return true; } catch (_) { return false; }
+  } catch (_) { return false; }
 }
 
 function killExistingPlugkit() {
   try {
     const pids = findPlugkitWasmPids();
+    try {
+      const supervisorPidFile = path.join(process.cwd(), '.gm', 'exec-spool', '.supervisor.pid');
+      if (fs.existsSync(supervisorPidFile)) {
+        const sp = parseInt(fs.readFileSync(supervisorPidFile, 'utf8').trim(), 10);
+        if (Number.isFinite(sp) && sp > 0) {
+          try { process.kill(sp, 0); pids.unshift(String(sp)); } catch (_) {}
+        }
+      }
+    } catch (_) {}
     if (pids.length === 0) {
       emitBootstrapEvent('info', 'No existing plugkit WASM watcher to kill');
       return;
@@ -477,9 +494,51 @@ function openWatcherLog(projectDir) {
   return fd;
 }
 
+function ensureSupervisorInstalled() {
+  try {
+    const src = resolveFromCandidates([
+      path.join(__dirname, '..', 'bin', 'plugkit-supervisor.js'),
+      path.join(__dirname, '..', '..', 'bin', 'plugkit-supervisor.js'),
+    ], 'gm-skill/bin/plugkit-supervisor.js');
+    if (!src || !fs.existsSync(src)) {
+      emitBootstrapEvent('warn', 'bundled plugkit-supervisor.js not found; supervisor unavailable');
+      return null;
+    }
+    fs.mkdirSync(PLUGKIT_TOOLS_DIR, { recursive: true });
+    let needsWrite = true;
+    if (fs.existsSync(PLUGKIT_SUPERVISOR)) {
+      try {
+        const a = crypto.createHash('sha256').update(fs.readFileSync(src)).digest('hex');
+        const b = crypto.createHash('sha256').update(fs.readFileSync(PLUGKIT_SUPERVISOR)).digest('hex');
+        if (a === b) needsWrite = false;
+      } catch (_) {}
+    }
+    if (needsWrite) {
+      const tmp = PLUGKIT_SUPERVISOR + '.tmp';
+      fs.copyFileSync(src, tmp);
+      fs.renameSync(tmp, PLUGKIT_SUPERVISOR);
+      emitBootstrapEvent('info', 'plugkit-supervisor.js installed', { target: PLUGKIT_SUPERVISOR });
+    }
+    return PLUGKIT_SUPERVISOR;
+  } catch (e) {
+    emitBootstrapEvent('warn', 'ensureSupervisorInstalled failed', { error: e.message });
+    return null;
+  }
+}
+
+function findSupervisorPid() {
+  try {
+    const supervisorPidFile = path.join(process.cwd(), '.gm', 'exec-spool', '.supervisor.pid');
+    if (!fs.existsSync(supervisorPidFile)) return null;
+    const pid = parseInt(fs.readFileSync(supervisorPidFile, 'utf8').trim(), 10);
+    if (!Number.isFinite(pid) || pid <= 0) return null;
+    try { process.kill(pid, 0); return pid; } catch (_) { return null; }
+  } catch (_) { return null; }
+}
+
 async function spawnPlugkitWatcher(wasmPath) {
   try {
-    emitBootstrapEvent('info', 'Spawning plugkit WASM watcher daemon');
+    emitBootstrapEvent('info', 'Spawning plugkit supervisor');
 
     let wrapperPath;
     try {
@@ -494,16 +553,37 @@ async function spawnPlugkitWatcher(wasmPath) {
       throw new Error(`WASM wrapper not found at ${wrapperPath}`);
     }
 
+    const supervisorPath = ensureSupervisorInstalled();
     const projectDir = process.cwd();
+
+    const existingSupervisor = findSupervisorPid();
+    if (existingSupervisor) {
+      emitBootstrapEvent('info', 'Plugkit supervisor already running', { pid: existingSupervisor });
+      return existingSupervisor;
+    }
+
+    if (!supervisorPath) {
+      emitBootstrapEvent('warn', 'falling back to direct watcher spawn (no supervisor)');
+      const logFd = openWatcherLog(projectDir);
+      const runtime = process.platform === 'win32' ? 'bun.exe' : 'bun';
+      const proc = spawn(runtime, [wrapperPath, 'spool'], {
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+        windowsHide: true,
+        env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir },
+        ...(process.platform === 'win32' ? { creationFlags: 0x08000000 | 0x00000008 } : {}),
+      });
+      try { fs.closeSync(logFd); } catch (_) {}
+      const pid = proc.pid;
+      proc.unref();
+      emitBootstrapEvent('info', 'Plugkit watcher spawned (unsupervised)', { pid });
+      return pid;
+    }
+
     const logFd = openWatcherLog(projectDir);
+    try { fs.writeSync(logFd, `\n--- supervisor spawn ${new Date().toISOString()} parent=${process.pid} ---\n`); } catch (_) {}
 
-    const runtime = process.platform === 'win32' ? 'bun.exe' : 'bun';
-    // CREATE_NO_WINDOW (0x08000000) | DETACHED_PROCESS (0x00000008) —
-    // inherited by all descendants so bun.exe → spool watcher → any
-    // downstream spawn never allocates a console window. Without this,
-    // windowsHide:true only hides the immediate bun.exe child while
-    // .cmd shims it later spawns each pop their own conhost.
-    const proc = spawn(runtime, [wrapperPath, 'spool'], {
+    const proc = spawn(process.execPath, [supervisorPath], {
       detached: true,
       stdio: ['ignore', logFd, logFd],
       windowsHide: true,
@@ -516,14 +596,53 @@ async function spawnPlugkitWatcher(wasmPath) {
     const pid = proc.pid;
     proc.unref();
 
-    emitBootstrapEvent('info', 'Plugkit WASM watcher spawned', { pid, logPath: path.join(projectDir, '.gm', 'exec-spool', '.watcher.log') });
+    emitBootstrapEvent('info', 'Plugkit supervisor spawned', { pid, supervisor: supervisorPath, logPath: path.join(projectDir, '.gm', 'exec-spool', '.watcher.log') });
     return pid;
   } catch (e) {
-    emitBootstrapEvent('error', 'Failed to spawn plugkit WASM watcher', { error: e.message });
+    emitBootstrapEvent('error', 'Failed to spawn plugkit supervisor', { error: e.message });
     throw e;
   }
 }
 
+function ensureNextStepWiring(cwd) {
+  const gmDir = path.join(cwd, '.gm');
+  try { fs.mkdirSync(gmDir, { recursive: true }); } catch (_) {}
+
+  const nextStepPath = path.join(gmDir, 'next-step.md');
+  const nextStepBody = '# Next step\n\nDispatch the `instruction` verb to plugkit by writing `.gm/exec-spool/in/instruction/<N>.txt` (any unique N) with body `{}` (or `{"prompt":"<user request>"}` on the first dispatch of the turn). Read the response from `.gm/exec-spool/out/<N>.json` and follow the imperative in the `instruction` field.\n\nThis file is auto-rewritten by plugkit on every instruction dispatch.\n';
+  try {
+    if (!fs.existsSync(nextStepPath)) {
+      fs.writeFileSync(nextStepPath, nextStepBody);
+      emitBootstrapEvent('info', 'Seeded .gm/next-step.md', { path: nextStepPath });
+    }
+  } catch (e) {
+    emitBootstrapEvent('warn', 'Failed to seed .gm/next-step.md', { error: e.message });
+  }
+
+  const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+  try {
+    if (!fs.existsSync(claudeMdPath)) {
+      fs.writeFileSync(claudeMdPath, '@AGENTS.md\n');
+    } else {
+      const cur = fs.readFileSync(claudeMdPath, 'utf8');
+      const hasLine = cur.split(/\r?\n/).some(l => l.trim() === '@AGENTS.md');
+      if (!hasLine) fs.writeFileSync(claudeMdPath, '@AGENTS.md\n' + cur);
+    }
+  } catch (_) {}
+
+  const agentsMdPath = path.join(cwd, 'AGENTS.md');
+  try {
+    if (fs.existsSync(agentsMdPath)) {
+      const cur = fs.readFileSync(agentsMdPath, 'utf8');
+      const hasLine = cur.split(/\r?\n/).some(l => l.trim() === '@.gm/next-step.md');
+      if (!hasLine) {
+        const sep = cur.endsWith('\n') ? '' : '\n';
+        fs.writeFileSync(agentsMdPath, cur + sep + '\n@.gm/next-step.md\n');
+      }
+    }
+  } catch (_) {}
+}
+
 async function bootstrapPlugkit(sessionId, options) {
   const startTime = Date.now();
   const opts = options || {};
@@ -534,6 +653,7 @@ async function bootstrapPlugkit(sessionId, options) {
 
     writeSessionSidecar(sessionId);
     ensureBuildToolIgnores(process.cwd());
+    ensureNextStepWiring(process.cwd());
     ensureSkillMdCurrent();
 
     const manifest = readManifest();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1291",
+  "version": "2.0.1292",
   "description": "Canonical universal harness — AI-native software engineering via skill-driven orchestration; bootstraps plugkit for task execution and session isolation. Install in any AI coding agent host.",
   "author": "AnEntrypoint",
   "license": "MIT",
@@ -23,7 +23,9 @@
   },
   "main": "bin/bootstrap.js",
   "bin": {
-    "gm-skill-bootstrap": "./bin/bootstrap.js"
+    "gm-skill-bootstrap": "./bin/bootstrap.js",
+    "gmsniff": "./bin/gmsniff.js",
+    "ccsniff": "./bin/ccsniff.js"
   },
   "files": [
     "skills/",
@@ -39,7 +41,7 @@
     "gm.json"
   ],
   "dependencies": {
-    "gm-plugkit": "^2.0.1291"
+    "gm-plugkit": "^2.0.1292"
   },
   "engines": {
     "node": ">=16.0.0"