gm-skill 2.0.1516 → 2.0.1518

package/AGENTS.md

@@ -32,6 +32,8 @@ The plugkit stack runs as a wasm cdylib loaded by `plugkit-wasm-wrapper.js` unde
 
 **`plugkit-wasm-wrapper.js` is ESM; never use inline `require()` for a node builtin — import it at module scope.** The wrapper runs under both node and bun, and the supervisor's `resolveRuntime()` prefers bun. Under bun's ESM, `require` is not a global, so an inline `const x = require('crypto'|'net'|'http'|'https'|'child_process')` throws `require is not defined` — and because those calls sit in `catch(_){}` blocks, the failure is silent: it broke `_ownWrapperSha12` (status.wrapper_sha stayed null, leaving the supervisor wrapper-sha-drift recycle inert), `_wrapperShaAtBoot` and its self-drift-restart, the synthetic-session cwd-hash, and the file-index sha — all only under the bun watcher, which is why it hid for so long (node-run watchers have `require` via CJS interop). Every node builtin is imported once at the top (`import crypto from 'crypto'`, etc.); inline `require` of a builtin is forbidden. Full incident in rs-learn (`recall: wrapper require not defined under bun`).
 
+**Every single-instance / lock guard is atomic, never check-then-act.** A guard that does `existsSync` -> read -> decide -> `writeFileSync` is TOCTOU: under a concurrent burst (the bootstrap spawns several supervisors in the same millisecond per skill-load) every caller passes the check before any writes, so all proceed and the duplicate it was meant to prevent happens anyway. The supervisor single-instance guard, the `.watcher.lock`, and any future pid/lock file all acquire via an atomic primitive — `fs.openSync(path, 'wx')` (O_EXCL exclusive-create, succeeds for exactly one racer) or atomic-rename — then on `EEXIST` read the holder and refuse-if-alive / take-over-if-stale. The trap: a check-then-write guard passes sequential testing (a later boot sees the prior holder) and silently fails only under concurrency, so when a guard is in place and the duplicate STILL occurs, suspect non-atomicity before suspecting absence. Full incident (three mis-diagnoses) in rs-learn (`recall: supervisor churn TOCTOU atomic guard`).
+
 ## Spool dispatch ABI
 
 Agents dispatch verbs by writing to `.gm/exec-spool/in/<verb>/<N>.txt` (request body) and reading the response from `.gm/exec-spool/out/<verb>-<N>.json` (nested verbs) or `.gm/exec-spool/out/<N>.json` (root verbs). The wasm orchestrator services every possible verb; the harness never executes side effects directly.

package/bin/plugkit-supervisor.js

@@ -90,22 +90,31 @@ function statusMtime() {
 }
 
 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;
+  // Atomic via O_EXCL ('wx'): exclusive-create fails if the file exists, so when N supervisors
+  // race to start in the same instant exactly one wins. A plain existsSync->write is TOCTOU and
+  // lets a concurrent burst all pass, which is the duplicate-supervisor churn this guards against.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(SUPERVISOR_PID_PATH, 'wx');
+      try { fs.writeSync(fd, String(process.pid)); } finally { fs.closeSync(fd); }
+      return true;
+    } catch (e) {
+      if (e && e.code === 'EEXIST') {
+        let other = NaN;
+        try { other = parseInt(fs.readFileSync(SUPERVISOR_PID_PATH, 'utf-8').trim(), 10); } catch (_) {}
+        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;
+        }
+        try { fs.unlinkSync(SUPERVISOR_PID_PATH); } catch (_) {}
+        continue;
       }
+      logEvent('supervisor.pid-write-failed', { error: e && e.message, severity: 'warn' });
+      return true;
     }
-    fs.writeFileSync(SUPERVISOR_PID_PATH, String(process.pid));
-    return true;
-  } catch (e) {
-    logEvent('supervisor.pid-write-failed', { error: e.message, severity: 'warn' });
-    return true;
   }
+  return true;
 }
 
 function releaseSingleInstance() {

package/gm-plugkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.1516",
+  "version": "2.0.1518",
   "description": "Bootstrap and daemon-spawn tool for gm plugkit binary. Downloads the correct platform binary, verifies SHA256, and starts the spool watcher daemon. Includes plugkit-wasm-wrapper for WASM-based spool watching.",
   "main": "index.js",
   "bin": {

package/gm-plugkit/supervisor.js

@@ -23,6 +23,7 @@ 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 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');
 
@@ -66,6 +67,47 @@ function pidAlive(pid) {
   try { process.kill(pid, 0); return true; } catch (_) { return false; }
 }
 
+// Single-instance guard. findSupervisorPid (skill-bootstrap.js) reads .supervisor.pid to early-return
+// when a supervisor is already running; without it every bootstrap spawns a duplicate supervisor,
+// and duplicates spawn duplicate watchers that lock-fight in an endless spawn-reject churn. Write the
+// pid file on startup and refuse to start if a live peer already holds it.
+function acquireSingleInstance() {
+  // Atomic via O_EXCL ('wx'): exclusive-create fails if the file exists, so when N supervisors
+  // race to start in the same instant exactly one wins. A plain existsSync->write is TOCTOU and
+  // lets a concurrent burst all pass, which is the duplicate-supervisor churn this guards against.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(SUPERVISOR_PID_PATH, 'wx');
+      try { fs.writeSync(fd, String(process.pid)); } finally { fs.closeSync(fd); }
+      return true;
+    } catch (e) {
+      if (e && e.code === 'EEXIST') {
+        let other = NaN;
+        try { other = parseInt(fs.readFileSync(SUPERVISOR_PID_PATH, 'utf-8').trim(), 10); } catch (_) {}
+        if (Number.isFinite(other) && other !== process.pid && pidAlive(other)) {
+          logEvent('supervisor.refused-duplicate', { existing_pid: other, severity: 'warn' });
+          return false;
+        }
+        // Holder is dead/stale: remove and retry the exclusive create once.
+        try { fs.unlinkSync(SUPERVISOR_PID_PATH); } catch (_) {}
+        continue;
+      }
+      logEvent('supervisor.pid-write-failed', { error: e && e.message, severity: 'warn' });
+      return true;
+    }
+  }
+  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 (_) {}
+}
+
 function readStatus() {
   try { return JSON.parse(fs.readFileSync(STATUS_PATH, 'utf-8')); } catch (_) { return null; }
 }
@@ -273,9 +315,15 @@ process.on('SIGTERM', () => {
   if (currentChildPid && pidAlive(currentChildPid)) {
     try { process.kill(currentChildPid, 'SIGTERM'); } catch (_) {}
   }
+  releaseSingleInstance();
   process.exit(0);
 });
+process.on('exit', () => { releaseSingleInstance(); });
 
+if (!acquireSingleInstance()) {
+  process.stderr.write('[plugkit-supervisor] another supervisor is alive; exiting\n');
+  process.exit(0);
+}
 writeSupervisorStatus('starting', {});
 logEvent('supervisor.starting', { spool_dir: spoolDir });
 try { fs.unlinkSync(path.join(spoolDir, '.pre-supervised-watcher.json')); } catch (_) {}

package/gm.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1516",
+  "version": "2.0.1518",
   "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",