gm-skill 2.0.1156 → 2.0.1158

package/README.md

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

package/gm-plugkit/bootstrap.js

@@ -777,14 +777,6 @@ function startSpoolDaemon() {
       return { ok: false, error: `wrapper not at ${wrapper} — ensureReady() must run first` };
     }
     const runtime = process.platform === 'win32' ? 'bun.exe' : 'bun';
-    let cmd = runtime;
-    let args = [wrapper, 'spool'];
-    try {
-      require('child_process').execFileSync(runtime, ['--version'], { stdio: 'ignore' });
-    } catch (_) {
-      cmd = process.execPath;
-      args = [wrapper, 'spool'];
-    }
     const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
     const spoolDir = path.join(projectDir, '.gm', 'exec-spool');
     fs.mkdirSync(spoolDir, { recursive: true });
@@ -796,18 +788,43 @@ function startSpoolDaemon() {
         fs.renameSync(logPath, path.join(spoolDir, '.watcher.log.1'));
       }
     } catch (_) {}
+
+    const supervisor = path.join(__dirname, 'supervisor.js');
+    if (process.env.PLUGKIT_SKIP_SUPERVISOR === '1' || !fs.existsSync(supervisor)) {
+      let cmd = runtime;
+      let args = [wrapper, 'spool'];
+      try {
+        require('child_process').execFileSync(runtime, ['--version'], { stdio: 'ignore' });
+      } catch (_) {
+        cmd = process.execPath;
+        args = [wrapper, 'spool'];
+      }
+      const logFd = fs.openSync(logPath, 'a');
+      try { fs.writeSync(logFd, `\n--- daemon spawn ${new Date().toISOString()} parent=${process.pid} (no supervisor) ---\n`); } catch (_) {}
+      const child = require('child_process').spawn(cmd, args, {
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+        windowsHide: true,
+        env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir, PLUGKIT_BOOT_REASON: 'direct-no-supervisor' },
+      });
+      try { fs.closeSync(logFd); } catch (_) {}
+      const pid = child.pid;
+      child.unref();
+      return { ok: true, pid, wrapper, runtime: cmd, logPath, supervised: false };
+    }
+
     const logFd = fs.openSync(logPath, 'a');
-    try { fs.writeSync(logFd, `\n--- daemon spawn ${new Date().toISOString()} parent=${process.pid} ---\n`); } catch (_) {}
-    const child = require('child_process').spawn(cmd, args, {
+    try { fs.writeSync(logFd, `\n--- supervisor spawn ${new Date().toISOString()} parent=${process.pid} ---\n`); } catch (_) {}
+    const child = require('child_process').spawn(process.execPath, [supervisor], {
       detached: true,
       stdio: ['ignore', logFd, logFd],
       windowsHide: true,
-      env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir },
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir, PLUGKIT_RUNTIME: runtime },
     });
     try { fs.closeSync(logFd); } catch (_) {}
     const pid = child.pid;
     child.unref();
-    return { ok: true, pid, wrapper, runtime: cmd, logPath };
+    return { ok: true, pid, wrapper, supervisor, runtime, logPath, supervised: true };
   } catch (e) {
     return { ok: false, error: e.message };
   }

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

@@ -123,8 +123,33 @@ function emitOrchestratorEvents(verb, taskBase, resultStr) {
 }
 
 const TMP_DIR = os.tmpdir();
-const BROWSER_PORTS_FILE = path.join(TMP_DIR, 'plugkit-browser-ports.json');
-const BROWSER_SESSIONS_FILE = path.join(TMP_DIR, 'plugkit-browser-sessions.json');
+const LEGACY_BROWSER_PORTS_FILE = path.join(TMP_DIR, 'plugkit-browser-ports.json');
+const LEGACY_BROWSER_SESSIONS_FILE = path.join(TMP_DIR, 'plugkit-browser-sessions.json');
+
+function browserStateDir(cwd) {
+  const dir = path.join(cwd || process.cwd(), '.gm', 'exec-spool');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (_) {}
+  return dir;
+}
+function browserPortsFile(cwd) { return path.join(browserStateDir(cwd), 'browser-ports.json'); }
+function browserSessionsFile(cwd) { return path.join(browserStateDir(cwd), 'browser-sessions.json'); }
+
+function migrateLegacyBrowserState(cwd) {
+  const dst1 = browserPortsFile(cwd);
+  const dst2 = browserSessionsFile(cwd);
+  try {
+    if (!fs.existsSync(dst1) && fs.existsSync(LEGACY_BROWSER_PORTS_FILE)) {
+      const legacy = JSON.parse(fs.readFileSync(LEGACY_BROWSER_PORTS_FILE, 'utf-8'));
+      if (legacy && typeof legacy === 'object') fs.writeFileSync(dst1, JSON.stringify(legacy, null, 2));
+    }
+  } catch (_) {}
+  try {
+    if (!fs.existsSync(dst2) && fs.existsSync(LEGACY_BROWSER_SESSIONS_FILE)) {
+      const legacy = JSON.parse(fs.readFileSync(LEGACY_BROWSER_SESSIONS_FILE, 'utf-8'));
+      if (legacy && typeof legacy === 'object') fs.writeFileSync(dst2, JSON.stringify(legacy, null, 2));
+    }
+  } catch (_) {}
+}
 
 function readJsonFile(fp, fallback) {
   try { return JSON.parse(fs.readFileSync(fp, 'utf-8')); } catch (_) { return fallback; }
@@ -246,8 +271,11 @@ function runPlaywriter(pw, args, timeoutMs) {
 }
 
 function getOrCreateBrowserSession(cwd, claudeSessionId, pw) {
-  const ports = readJsonFile(BROWSER_PORTS_FILE, {});
-  const sessions = readJsonFile(BROWSER_SESSIONS_FILE, {});
+  migrateLegacyBrowserState(cwd);
+  const portsFile = browserPortsFile(cwd);
+  const sessionsFile = browserSessionsFile(cwd);
+  const ports = readJsonFile(portsFile, {});
+  const sessions = readJsonFile(sessionsFile, {});
   const existing = ports[claudeSessionId];
   if (existing && existing.port && isPortAliveSync(existing.port)) {
     const pwIds = sessions[claudeSessionId] || [];
@@ -265,6 +293,7 @@ function getOrCreateBrowserSession(cwd, claudeSessionId, pw) {
     '--disable-features=Translate',
   ];
   const child = spawn(chrome, chromeArgs, { detached: true, stdio: 'ignore' });
+  const chromePid = child.pid;
   child.unref();
   const deadline = Date.now() + 10000;
   let alive = false;
@@ -288,10 +317,10 @@ function getOrCreateBrowserSession(cwd, claudeSessionId, pw) {
     try { const j = JSON.parse(out); pwSessionId = j.id || j.session_id || j.session; } catch (_) {}
   }
   if (!pwSessionId) throw new Error(`could not parse playwriter session id from: ${out}`);
-  ports[claudeSessionId] = { port, profileDir };
+  ports[claudeSessionId] = { port, profileDir, pid: chromePid };
   sessions[claudeSessionId] = [pwSessionId];
-  writeJsonFile(BROWSER_PORTS_FILE, ports);
-  writeJsonFile(BROWSER_SESSIONS_FILE, sessions);
+  writeJsonFile(portsFile, ports);
+  writeJsonFile(sessionsFile, sessions);
   return pwSessionId;
 }
 
@@ -406,6 +435,192 @@ function kvFilePath(ns, key) {
   return path.join(dir, safeKey + '.json');
 }
 
+const __tasks = new Map();
+
+function tasksDir(cwd) {
+  const d = path.join(cwd || process.cwd(), '.gm', 'exec-spool', 'tasks');
+  try { fs.mkdirSync(d, { recursive: true }); } catch (_) {}
+  return d;
+}
+
+function taskMetaPath(cwd, id) { return path.join(tasksDir(cwd), `${id}.json`); }
+function taskOutPath(cwd, id, which) { return path.join(tasksDir(cwd), `${id}.${which}.log`); }
+
+function writeTaskMeta(cwd, id, meta) {
+  try { fs.writeFileSync(taskMetaPath(cwd, id), JSON.stringify(meta, null, 2)); } catch (_) {}
+}
+
+function nextTaskId(cwd) {
+  const counterPath = path.join(tasksDir(cwd), '.counter');
+  let n = 0;
+  try { n = parseInt(fs.readFileSync(counterPath, 'utf-8'), 10) || 0; } catch (_) {}
+  n += 1;
+  try { fs.writeFileSync(counterPath, String(n)); } catch (_) {}
+  return `t${n}`;
+}
+
+function langToCmd(lang, code) {
+  if (lang === 'nodejs' || lang === 'js' || lang === 'javascript' || lang === 'node') return { cmd: process.execPath, args: ['-e', code], stdinCode: null };
+  if (lang === 'python' || lang === 'py') return { cmd: 'python', args: ['-c', code], stdinCode: null };
+  if (lang === 'bash' || lang === 'sh' || lang === 'shell' || lang === 'zsh') return { cmd: 'bash', args: ['-c', code], stdinCode: null };
+  if (lang === 'powershell' || lang === 'ps1') return { cmd: 'powershell', args: ['-NoProfile', '-NonInteractive', '-Command', code], stdinCode: null };
+  if (lang === 'deno') return { cmd: 'deno', args: ['eval', code], stdinCode: null };
+  return null;
+}
+
+function spawnTask({ cwd, lang, code, timeoutMs }) {
+  const id = nextTaskId(cwd);
+  const built = langToCmd(lang, code);
+  if (!built) return { ok: false, error: `unsupported lang: ${lang}` };
+  const outLog = taskOutPath(cwd, id, 'stdout');
+  const errLog = taskOutPath(cwd, id, 'stderr');
+  let outFd = null, errFd = null;
+  try { outFd = fs.openSync(outLog, 'a'); } catch (_) {}
+  try { errFd = fs.openSync(errLog, 'a'); } catch (_) {}
+  const startedMs = Date.now();
+  const isPosix = process.platform !== 'win32';
+  const child = spawn(built.cmd, built.args, {
+    cwd: cwd || process.cwd(),
+    detached: isPosix,
+    stdio: ['ignore', outFd || 'ignore', errFd || 'ignore'],
+    windowsHide: true,
+    env: process.env,
+  });
+  try { if (outFd !== null) fs.closeSync(outFd); } catch (_) {}
+  try { if (errFd !== null) fs.closeSync(errFd); } catch (_) {}
+  const meta = {
+    id,
+    pid: child.pid,
+    pgid: isPosix ? child.pid : null,
+    lang,
+    cmd: built.cmd,
+    cwd: cwd || process.cwd(),
+    started_ms: startedMs,
+    timeout_ms: timeoutMs,
+    deadline_ms: startedMs + timeoutMs,
+    status: 'running',
+    exit_code: null,
+    stdout_log: outLog,
+    stderr_log: errLog,
+  };
+  __tasks.set(id, { child, meta });
+  writeTaskMeta(cwd, id, meta);
+  child.on('exit', (code, signal) => {
+    meta.status = signal ? 'killed' : (code === 0 ? 'completed' : 'failed');
+    meta.exit_code = code;
+    meta.signal = signal;
+    meta.ended_ms = Date.now();
+    writeTaskMeta(meta.cwd, id, meta);
+  });
+  child.on('error', (err) => {
+    meta.status = 'error';
+    meta.error = err.message;
+    meta.ended_ms = Date.now();
+    writeTaskMeta(meta.cwd, id, meta);
+  });
+  logEvent('plugkit', 'task.spawn', { task_id: id, pid: child.pid, lang, timeout_ms: timeoutMs });
+  return { ok: true, task_id: id, pid: child.pid, started_ms: startedMs };
+}
+
+function stopTaskById(id) {
+  const entry = __tasks.get(id);
+  if (!entry) {
+    return { ok: false, error: 'unknown task_id', task_id: id };
+  }
+  const { child, meta } = entry;
+  if (meta.status !== 'running') return { ok: true, already: meta.status, task_id: id };
+  const pid = meta.pid;
+  const isPosix = process.platform !== 'win32';
+  try {
+    if (isPosix && meta.pgid) {
+      try { process.kill(-meta.pgid, 'SIGTERM'); } catch (_) {}
+    } else {
+      try { child.kill('SIGTERM'); } catch (_) {}
+    }
+  } catch (_) {}
+  const graceTimer = setTimeout(() => {
+    if (meta.status !== 'running') return;
+    if (isPosix && meta.pgid) {
+      try { process.kill(-meta.pgid, 'SIGKILL'); } catch (_) {}
+    } else if (process.platform === 'win32') {
+      try { spawnSync('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore', timeout: 3000 }); } catch (_) {}
+    } else {
+      try { child.kill('SIGKILL'); } catch (_) {}
+    }
+  }, 2000);
+  graceTimer.unref && graceTimer.unref();
+  logEvent('plugkit', 'task.stop', { task_id: id, pid });
+  return { ok: true, task_id: id, pid };
+}
+
+function tailFile(filePath, maxBytes) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size <= maxBytes) return fs.readFileSync(filePath, 'utf-8');
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const buf = Buffer.alloc(maxBytes);
+      fs.readSync(fd, buf, 0, maxBytes, stat.size - maxBytes);
+      return buf.toString('utf-8');
+    } finally { try { fs.closeSync(fd); } catch (_) {} }
+  } catch (_) { return ''; }
+}
+
+function listTasks(cwd) {
+  const d = tasksDir(cwd);
+  const out = [];
+  try {
+    for (const entry of fs.readdirSync(d)) {
+      if (!entry.endsWith('.json') || entry.startsWith('.')) continue;
+      try {
+        const meta = JSON.parse(fs.readFileSync(path.join(d, entry), 'utf-8'));
+        out.push(meta);
+      } catch (_) {}
+    }
+  } catch (_) {}
+  return out;
+}
+
+function reapTimedOutTasks() {
+  const now = Date.now();
+  for (const [id, entry] of __tasks) {
+    const m = entry.meta;
+    if (m.status === 'running' && m.deadline_ms && now > m.deadline_ms) {
+      logEvent('plugkit', 'task.timeout', { task_id: id, pid: m.pid, deadline_ms: m.deadline_ms, now_ms: now });
+      stopTaskById(id);
+    }
+  }
+}
+
+function killAllTasks(reason) {
+  let killed = 0;
+  for (const [id, entry] of __tasks) {
+    if (entry.meta.status === 'running') {
+      stopTaskById(id);
+      killed += 1;
+    }
+  }
+  if (killed > 0) logEvent('plugkit', 'task.killAll', { reason, count: killed });
+  return killed;
+}
+
+function hostTaskProc(action, params) {
+  switch (action) {
+    case 'spawn': return spawnTask(params);
+    case 'stop': return stopTaskById(params.id || params.task_id);
+    case 'list': return { ok: true, tasks: listTasks(params.cwd) };
+    case 'output': return {
+      ok: true,
+      task_id: params.id || params.task_id,
+      stdout: tailFile(taskOutPath(params.cwd, params.id || params.task_id, 'stdout'), params.max_bytes || 65536),
+      stderr: tailFile(taskOutPath(params.cwd, params.id || params.task_id, 'stderr'), params.max_bytes || 65536),
+    };
+    case 'reap': { reapTimedOutTasks(); return { ok: true }; }
+    case 'killAll': { const n = killAllTasks(params.reason || 'host_task_proc'); return { ok: true, killed: n }; }
+    default: return { ok: false, error: `unknown action: ${action}` };
+  }
+}
+
 function makeHostFunctions(instanceRef) {
   return {
     host_fs_read: (pathPtr, pathLen) => {
@@ -684,6 +899,19 @@ function makeHostFunctions(instanceRef) {
         return 0n;
       }
     },
+
+    host_task_proc: (actionPtr, actionLen, paramsPtr, paramsLen) => {
+      try {
+        const action = readWasmStr(instanceRef.value, actionPtr, actionLen);
+        const paramsStr = readWasmStr(instanceRef.value, paramsPtr, paramsLen);
+        const params = paramsStr ? JSON.parse(paramsStr) : {};
+        if (!params.cwd) params.cwd = process.cwd();
+        const result = hostTaskProc(action, params);
+        return writeWasmJson(instanceRef.value, result);
+      } catch (e) {
+        return writeWasmJson(instanceRef.value, { ok: false, error: e.message });
+      }
+    },
   };
 }
 
@@ -742,6 +970,96 @@ async function runSpoolWatcher(instance, spoolDir) {
   }
   acquireLock();
   setInterval(refreshLock, 5000);
+
+  const IDLE_LIMIT_MS = parseInt(process.env.PLUGKIT_IDLE_LIMIT_MS, 10) || 15 * 60 * 1000;
+  const IDLE_CHECK_MS = 60_000;
+  const SHUTDOWN_REASON_PATH = path.join(spoolDir, '.shutdown-reason.json');
+  const STATUS_PATH_FOR_TEARDOWN = path.join(spoolDir, '.status.json');
+  const ACPTOAPI_STATUS_PATH = path.join(process.cwd(), '.gm', 'acptoapi-status.json');
+  let lastActivityMs = Date.now();
+  function markActivity(source) {
+    lastActivityMs = Date.now();
+  }
+
+  function killPidQuiet(pid) {
+    if (!Number.isFinite(pid) || pid <= 0 || pid === process.pid) return false;
+    try { process.kill(pid, 'SIGTERM'); } catch (_) {}
+    if (process.platform === 'win32') {
+      try { spawnSync('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore', timeout: 3000 }); } catch (_) {}
+    }
+    return true;
+  }
+
+  function teardownAll(reason) {
+    try {
+      logEvent('plugkit', 'watcher.teardown', { reason, idle_ms: Date.now() - lastActivityMs });
+      console.log(`[plugkit-wasm] teardown reason=${reason}`);
+    } catch (_) {}
+
+    try { killAllTasks(`teardown:${reason}`); } catch (_) {}
+
+    try {
+      if (fs.existsSync(ACPTOAPI_STATUS_PATH)) {
+        const status = JSON.parse(fs.readFileSync(ACPTOAPI_STATUS_PATH, 'utf-8'));
+        if (status && Number.isFinite(status.pid)) killPidQuiet(status.pid);
+        try { fs.unlinkSync(ACPTOAPI_STATUS_PATH); } catch (_) {}
+      }
+    } catch (_) {}
+
+    try {
+      const portsFile = browserPortsFile(process.cwd());
+      const sessionsFile = browserSessionsFile(process.cwd());
+      const ports = readJsonFile(portsFile, {});
+      for (const [sid, entry] of Object.entries(ports)) {
+        if (entry && Number.isFinite(entry.pid)) killPidQuiet(entry.pid);
+      }
+      try { fs.unlinkSync(portsFile); } catch (_) {}
+      try { fs.unlinkSync(sessionsFile); } catch (_) {}
+    } catch (_) {}
+
+    try {
+      fs.writeFileSync(SHUTDOWN_REASON_PATH, JSON.stringify({
+        reason,
+        ts: Date.now(),
+        pid: process.pid,
+        idle_ms: Date.now() - lastActivityMs,
+      }));
+    } catch (_) {}
+
+    try { fs.unlinkSync(STATUS_PATH_FOR_TEARDOWN); } catch (_) {}
+    try { releaseLock(); } catch (_) {}
+    process.exit(0);
+  }
+
+  setInterval(() => {
+    try { reapTimedOutTasks(); } catch (_) {}
+  }, 5000);
+
+  setInterval(() => {
+    try {
+      const idleMs = Date.now() - lastActivityMs;
+      if (idleMs < IDLE_LIMIT_MS) return;
+      try {
+        const ports = readJsonFile(browserPortsFile(process.cwd()), {});
+        let browserAlive = false;
+        for (const entry of Object.values(ports)) {
+          if (entry && Number.isFinite(entry.port) && isPortAliveSync(entry.port)) { browserAlive = true; break; }
+        }
+        if (browserAlive) { markActivity('browser-port-alive'); return; }
+      } catch (_) {}
+      try {
+        let anyRunning = false;
+        for (const entry of __tasks.values()) {
+          if (entry.meta.status === 'running') { anyRunning = true; break; }
+        }
+        if (anyRunning) { markActivity('task-running'); return; }
+      } catch (_) {}
+      teardownAll('idle');
+    } catch (e) {
+      console.error(`[idle-check] error: ${e.message}`);
+    }
+  }, IDLE_CHECK_MS);
+
   process.on('SIGINT', () => { releaseLock(); process.exit(0); });
   process.on('SIGTERM', () => { releaseLock(); process.exit(0); });
   process.on('exit', releaseLock);
@@ -767,7 +1085,49 @@ async function runSpoolWatcher(instance, spoolDir) {
   const _bootVersion = resolveVersion(instance);
   console.log(`[plugkit-wasm] plugkit v${_bootVersion} (wasm)`);
   console.log(`[plugkit-wasm] watching ${inDir}`);
-  logEvent('plugkit', 'watcher.boot', { version: _bootVersion, in_dir: inDir, out_dir: outDir, spool_dir: spoolDir });
+
+  let _priorShutdown = null;
+  let _priorStatus = null;
+  try { _priorShutdown = JSON.parse(fs.readFileSync(SHUTDOWN_REASON_PATH, 'utf-8')); } catch (_) {}
+  try { _priorStatus = JSON.parse(fs.readFileSync(STATUS_PATH_FOR_TEARDOWN, 'utf-8')); } catch (_) {}
+  const _bootReason = process.env.PLUGKIT_BOOT_REASON || 'unknown';
+  const _supervisorPid = parseInt(process.env.PLUGKIT_SUPERVISOR_PID, 10) || null;
+  const restartContext = {
+    boot_reason: _bootReason,
+    supervisor_pid: _supervisorPid,
+    prior_shutdown: _priorShutdown,
+    prior_status: _priorStatus,
+    prior_status_age_ms: _priorStatus && Number.isFinite(_priorStatus.ts) ? Date.now() - _priorStatus.ts : null,
+  };
+  const _isPlannedBoot = _priorShutdown && (_priorShutdown.reason === 'idle' || _priorShutdown.reason === 'sigterm' || _priorShutdown.reason === 'version-change');
+  const _isFirstBoot = !_priorShutdown && !_priorStatus;
+  const UNPLANNED_RESTART_MARKER = path.join(spoolDir, '.unplanned-restart.json');
+  if (!_isPlannedBoot && !_isFirstBoot) {
+    const incidentPayload = {
+      ts: Date.now(),
+      version: _bootVersion,
+      severity: 'critical',
+      ...restartContext,
+      log_tail_path: path.join(spoolDir, '.watcher.log'),
+      gm_log_dir: GM_LOG_ROOT,
+      instruction: 'Prior watcher died without a planned shutdown. This is treated as a critical failure. Inspect .watcher.log and gm-log/<day>/plugkit.jsonl events supervisor.watcher-exited-unexpectedly + supervisor.heartbeat-stale around the prior_status.ts timestamp to diagnose root cause.',
+    };
+    logEvent('plugkit', 'watcher.unplanned-restart', incidentPayload);
+    try {
+      let history = [];
+      try { history = JSON.parse(fs.readFileSync(UNPLANNED_RESTART_MARKER, 'utf-8')).history || []; } catch (_) {}
+      history.push(incidentPayload);
+      if (history.length > 20) history = history.slice(-20);
+      fs.writeFileSync(UNPLANNED_RESTART_MARKER, JSON.stringify({
+        latest: incidentPayload,
+        count: history.length,
+        history,
+      }, null, 2));
+    } catch (_) {}
+    console.error(`[plugkit-wasm] UNPLANNED RESTART detected — prior watcher died without writing .shutdown-reason.json. prior_status_age_ms=${restartContext.prior_status_age_ms} boot_reason=${_bootReason}`);
+  }
+  try { fs.unlinkSync(SHUTDOWN_REASON_PATH); } catch (_) {}
+  logEvent('plugkit', 'watcher.boot', { version: _bootVersion, in_dir: inDir, out_dir: outDir, spool_dir: spoolDir, ...restartContext });
 
   const PROCESSED_MAX = 10000;
   const processed = new Map();
@@ -934,6 +1294,7 @@ async function runSpoolWatcher(instance, spoolDir) {
 
   const pollInterval = setInterval(async () => {
     const existing = walkDir(inDir);
+    if (existing.length > 0) markActivity('poll');
     for (const fullPath of existing) {
       await processFile(fullPath);
     }
@@ -1004,6 +1365,7 @@ async function runSpoolWatcher(instance, spoolDir) {
   watch(inDir, { recursive: true }, (eventType, filename) => {
     if (!filename) return;
     const fullPath = path.join(inDir, filename);
+    markActivity('watch');
 
     clearTimeout(debounce[fullPath]);
     debounce[fullPath] = setTimeout(async () => {

package/gm-plugkit/supervisor.js

@@ -0,0 +1,211 @@
+#!/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_PATH = path.join(spoolDir, '.supervisor.json');
+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 POLL_INTERVAL_MS = 10_000;
+const STATUS_STALE_MS = 30_000;
+const MAX_RESTART_BURST = 5;
+const RESTART_WINDOW_MS = 60_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: Date.now(),
+      sub: 'plugkit',
+      event,
+      pid: process.pid,
+      sess: process.env.CLAUDE_SESSION_ID || '',
+      cwd: process.cwd(),
+      role: 'supervisor',
+      ...fields,
+    }) + '\n';
+    fs.appendFileSync(path.join(dir, 'plugkit.jsonl'), line);
+  } catch (_) {}
+}
+
+function writeSupervisorStatus(state, extra) {
+  try {
+    fs.writeFileSync(SUPERVISOR_PATH, JSON.stringify({
+      pid: process.pid,
+      ts: Date.now(),
+      state,
+      ...(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 readShutdownReason() {
+  try { return JSON.parse(fs.readFileSync(SHUTDOWN_REASON_PATH, 'utf-8')); } catch (_) { return null; }
+}
+
+let lastSpawnedAt = 0;
+let restartTimestamps = [];
+let currentChildPid = null;
+let currentBootReason = 'initial';
+
+function spawnWatcher(bootReason) {
+  lastSpawnedAt = Date.now();
+  restartTimestamps.push(Date.now());
+  restartTimestamps = restartTimestamps.filter(t => Date.now() - t < RESTART_WINDOW_MS);
+  if (restartTimestamps.length > MAX_RESTART_BURST) {
+    logEvent('supervisor.giving-up', {
+      reason: 'restart-burst-exceeded',
+      restarts_in_window: restartTimestamps.length,
+      window_ms: RESTART_WINDOW_MS,
+      max: MAX_RESTART_BURST,
+      severity: 'critical',
+    });
+    writeSupervisorStatus('giving-up', { reason: 'restart-burst-exceeded' });
+    process.exit(2);
+  }
+
+  const wrapper = path.join(os.homedir(), '.claude', 'gm-tools', 'plugkit-wasm-wrapper.js');
+  if (!fs.existsSync(wrapper)) {
+    logEvent('supervisor.wrapper-missing', { wrapper, severity: 'critical' });
+    writeSupervisorStatus('error', { error: 'wrapper-missing' });
+    process.exit(3);
+  }
+
+  let runtime = process.env.PLUGKIT_RUNTIME || 'bun';
+  let cmd = runtime;
+  let args = [wrapper, 'spool'];
+  try {
+    spawnSync(runtime, ['--version'], { stdio: 'ignore', windowsHide: true });
+  } catch (_) {
+    cmd = process.execPath;
+    args = [wrapper, 'spool'];
+  }
+
+  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(cmd, args, {
+    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),
+    },
+  });
+
+  try { if (logFd !== null) fs.closeSync(logFd); } catch (_) {}
+  currentChildPid = child.pid;
+  currentBootReason = bootReason;
+  writeSupervisorStatus('watching', { watcher_pid: child.pid, boot_reason: bootReason });
+  logEvent('supervisor.spawned-watcher', { watcher_pid: child.pid, boot_reason: bootReason, runtime: cmd });
+
+  child.on('exit', (code, signal) => {
+    const shutdownReason = readShutdownReason();
+    const reason = shutdownReason && shutdownReason.reason;
+    const idleClean = reason === 'idle';
+    logEvent(idleClean ? 'supervisor.watcher-exited-idle' : 'supervisor.watcher-exited-unexpectedly', {
+      watcher_pid: currentChildPid,
+      exit_code: code,
+      signal,
+      shutdown_reason: reason || null,
+      had_shutdown_reason_file: shutdownReason !== null,
+      severity: idleClean ? 'info' : 'critical',
+      uptime_ms: Date.now() - lastSpawnedAt,
+    });
+    if (idleClean) {
+      writeSupervisorStatus('exited-idle', { watcher_pid: currentChildPid });
+      try { fs.unlinkSync(SUPERVISOR_PATH); } catch (_) {}
+      process.exit(0);
+    }
+    writeSupervisorStatus('restarting', {
+      prior_watcher_pid: currentChildPid,
+      prior_exit_code: code,
+      prior_signal: signal,
+      prior_shutdown_reason: reason || null,
+    });
+    setTimeout(() => spawnWatcher('unplanned-restart-after-exit'), 1500);
+  });
+
+  child.on('error', (err) => {
+    logEvent('supervisor.spawn-error', { error: err.message, severity: 'critical' });
+  });
+}
+
+function checkWatcherHealth() {
+  if (!currentChildPid) return;
+  if (!pidAlive(currentChildPid)) {
+    return;
+  }
+  const status = readStatus();
+  if (!status) {
+    logEvent('supervisor.status-missing', {
+      watcher_pid: currentChildPid,
+      severity: 'warn',
+    });
+    return;
+  }
+  const age = Date.now() - (status.ts || 0);
+  if (age > STATUS_STALE_MS) {
+    logEvent('supervisor.heartbeat-stale', {
+      watcher_pid: currentChildPid,
+      status_pid: status.pid,
+      status_age_ms: age,
+      stale_limit_ms: STATUS_STALE_MS,
+      severity: 'critical',
+    });
+    try { process.kill(currentChildPid, 'SIGTERM'); } catch (_) {}
+    if (process.platform === 'win32') {
+      try { spawnSync('taskkill', ['/F', '/T', '/PID', String(currentChildPid)], { stdio: 'ignore', windowsHide: true, timeout: 3000 }); } catch (_) {}
+    }
+  }
+}
+
+process.on('SIGINT', () => {
+  logEvent('supervisor.shutdown', { reason: 'sigint' });
+  writeSupervisorStatus('shutdown', { reason: 'sigint' });
+  if (currentChildPid && pidAlive(currentChildPid)) {
+    try { process.kill(currentChildPid, 'SIGTERM'); } catch (_) {}
+  }
+  process.exit(0);
+});
+process.on('SIGTERM', () => {
+  logEvent('supervisor.shutdown', { reason: 'sigterm' });
+  writeSupervisorStatus('shutdown', { reason: 'sigterm' });
+  if (currentChildPid && pidAlive(currentChildPid)) {
+    try { process.kill(currentChildPid, 'SIGTERM'); } catch (_) {}
+  }
+  process.exit(0);
+});
+
+writeSupervisorStatus('starting', {});
+logEvent('supervisor.starting', { spool_dir: spoolDir });
+spawnWatcher('initial');
+setInterval(checkWatcherHealth, POLL_INTERVAL_MS);
+setInterval(() => writeSupervisorStatus('watching', { watcher_pid: currentChildPid, boot_reason: currentBootReason }), 10_000);

package/gm.json

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

package/lib/daemon-bootstrap.js

@@ -120,7 +120,7 @@ function computeIndexDigest(cwd = process.cwd()) {
   }
 }
 
-function writeStatusFile(daemonName, status, sessionId) {
+function writeStatusFile(daemonName, status, sessionId, childPid) {
   try {
     fs.mkdirSync(GM_STATE_DIR, { recursive: true });
     const statusFile = path.join(GM_STATE_DIR, `${daemonName}-status.json`);
@@ -129,7 +129,8 @@ function writeStatusFile(daemonName, status, sessionId) {
       status,
       sessionId,
       timestamp: new Date().toISOString(),
-      pid: process.pid,
+      pid: Number.isFinite(childPid) ? childPid : process.pid,
+      parent_pid: process.pid,
     };
     fs.writeFileSync(statusFile, JSON.stringify(payload, null, 2));
     emitDaemonEvent(daemonName, 'info', 'Status written', { file: statusFile });
@@ -220,7 +221,7 @@ async function ensureAcptoapiRunning() {
       });
       child.unref();
       emitDaemonEvent('acptoapi', 'info', 'Daemon spawned', { pid: child.pid, port, sessionId });
-      writeStatusFile('acptoapi', 'spawned', sessionId);
+      writeStatusFile('acptoapi', 'spawned', sessionId, child.pid);
       return { ok: true, message: 'acptoapi spawned', pid: child.pid };
     } catch (spawnErr) {
       emitDaemonEvent('acptoapi', 'warn', 'Spawn failed, fallback to SDK', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1156",
+  "version": "2.0.1158",
   "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",
@@ -39,7 +39,7 @@
     "gm.json"
   ],
   "dependencies": {
-    "gm-plugkit": "^2.0.1156"
+    "gm-plugkit": "^2.0.1158"
   },
   "engines": {
     "node": ">=16.0.0"

package/skills/gm-skill/SKILL.md

@@ -20,6 +20,8 @@ If the `instruction` response carries a non-null `update_available`, plugkit dri
 
 The wasm artifact lives at `~/.claude/gm-tools/plugkit.wasm`; the spool watcher runs it. The watcher's own stdout/stderr is appended to `.gm/exec-spool/.watcher.log` — Read it to see plugkit's internal trace, dispatch timings, sweep actions, errors.
 
+The watcher self-shuts-down after 15 minutes idle (no spool I/O, no live browser session) and is restarted on next agent activity by a detached supervisor. `.gm/exec-spool/.unplanned-restart.json` is a critical-failure marker — present means a prior watcher died without a planned shutdown. Treat as a PRD-worthy incident on sight: diagnose via `.watcher.log` and `gm-log/<day>/plugkit.jsonl` events `supervisor.watcher-exited-unexpectedly` and `supervisor.heartbeat-stale` around the prior_status.ts timestamp, then delete the marker once root cause is named.
+
 ## Boot the spool watcher (first turn only)
 
 Check `.gm/exec-spool/.status.json`. If absent or `ts` > 15s old, boot via the npm package — `bun x gm-plugkit@latest spool` fetches the freshest plugkit (wasm + wrapper), copies them into `~/.claude/gm-tools/`, then enters spool mode: