gm-skill 2.0.1517 → 2.0.1519

package/AGENTS.md

@@ -32,6 +32,10 @@ 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`).
+
+**Count plugkit processes by executable Name, never by command-line substring.** A `Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '*plugkit-wasm-wrapper*' }` (or `-match 'plugkit-supervisor'`) also matches the bash/powershell command running the query itself — its eval string contains those literals — so it fabricates phantom processes and inflates the count (it reported `8 watchers + 4 supervisors` when the truth was `4 watchers, 0 supervisors`). Always constrain to the real runtime: `Where-Object { ($_.Name -eq 'node.exe' -or $_.Name -eq 'bun.exe') -and $_.CommandLine -match 'plugkit-wasm-wrapper\.js' }`. The phantom count made a working atomic-guard fix look unconverged across two fires; a wrong measurement is as costly as a wrong diagnosis. Full incident 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/bootstrap.js

@@ -665,6 +665,20 @@ function ensureWrapperFresh() {
   } catch (_) { return false; }
 }
 
+function ensureGmPlugkitVersionFresh() {
+  try {
+    const ownPkg = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf-8'));
+    if (!ownPkg || !ownPkg.version) return false;
+    const dst = path.join(gmToolsDir(), 'gm-plugkit.version');
+    let cur = null;
+    try { cur = fs.readFileSync(dst, 'utf-8').trim(); } catch (_) {}
+    if (cur === ownPkg.version) return false;
+    fs.mkdirSync(gmToolsDir(), { recursive: true });
+    fs.writeFileSync(dst, ownPkg.version);
+    return true;
+  } catch (_) { return false; }
+}
+
 function ensureSkillMdFresh() {
   try {
     const candidates = [
@@ -820,8 +834,9 @@ async function ensureReady(opts) {
   if (isReady() && !versionDrift) {
     const wasmPath = getWasmPath();
     const wrapperUpdated = ensureWrapperFresh();
+    const versionMarkerUpdated = ensureGmPlugkitVersionFresh();
     ensureSkillMdFresh();
-    return { ok: true, wasmPath, binaryPath: wasmPath, status: wrapperUpdated ? 'wrapper-refreshed' : 'already-ready', version: installed };
+    return { ok: true, wasmPath, binaryPath: wasmPath, status: (wrapperUpdated || versionMarkerUpdated) ? 'wrapper-refreshed' : 'already-ready', version: installed };
   }
   if (versionDrift) {
     try { killRunningDaemons(`version_drift:${installed}->${targetVersion}`); } catch (_) {}

package/gm-plugkit/child-script-alias.test.js

@@ -0,0 +1,25 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const wrapper = fs.readFileSync(path.join(__dirname, 'plugkit-wasm-wrapper.js'), 'utf-8');
+
+const aliasInChildScript = /\bspawnSync\s*\(\s*process\.execPath\s*,\s*\[\s*['"]-e['"]\s*,\s*`[^`]*\b_(?:net|http|https|crypto|childProcess)Module\b[^`]*`/;
+
+(function noParentAliasInChildEvalTemplates() {
+  assert.strictEqual(
+    aliasInChildScript.test(wrapper),
+    false,
+    'no spawnSync(process.execPath, ["-e", `...`]) child-script template may reference a parent-scope _*Module alias; the spawned child has no such binding (use require() inside the template). This regression broke findFreePortSync/isPort*/fetchJsonSync and surfaced only as "could not allocate free port" at browser-spawn time.'
+  );
+})();
+
+(function childTemplatesUseRequire() {
+  const childEvalBlocks = wrapper.match(/spawnSync\s*\(\s*process\.execPath\s*,\s*\[\s*['"]-e['"]\s*,\s*`[^`]*`/g) || [];
+  for (const block of childEvalBlocks) {
+    if (/\brequire\s*\(\s*['"](?:net|http|https)['"]\s*\)/.test(block) || !/\b(?:net|http|https)\b/.test(block)) continue;
+    assert.fail(`child -e template uses a node builtin without require(): ${block.slice(0, 80)}...`);
+  }
+})();
+
+console.log('child-script-alias.test.js: all assertions passed');

package/gm-plugkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.1517",
+  "version": "2.0.1519",
   "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/plugkit-wasm-wrapper.js

@@ -828,7 +828,7 @@ function resolveWindowsExeLocal(cmd) {
 
 function isPortReachableSync(host, port, timeoutMs) {
   const r = spawnSync(process.execPath, ['-e', `
-    const net = _netModule;
+    const net = require('net');
     const s = net.connect({ port: ${port}, host: ${JSON.stringify(host)} });
     let done = false;
     s.on('connect', () => { done = true; s.destroy(); process.exit(0); });
@@ -840,7 +840,7 @@ function isPortReachableSync(host, port, timeoutMs) {
 
 function findFreePortSync() {
   const r = spawnSync(process.execPath, ['-e', `
-    const net = _netModule;
+    const net = require('net');
     const srv = net.createServer();
     srv.listen(0, '127.0.0.1', () => { const p = srv.address().port; srv.close(() => { process.stdout.write(String(p)); }); });
     srv.on('error', e => { process.stderr.write(e.message); process.exit(1); });
@@ -851,7 +851,7 @@ function findFreePortSync() {
 
 function isPortAliveSync(port) {
   const r = spawnSync(process.execPath, ['-e', `
-    const net = _netModule;
+    const net = require('net');
     const s = net.connect({ port: ${port}, host: '127.0.0.1' });
     s.on('connect', () => { s.destroy(); process.exit(0); });
     s.on('error', () => process.exit(1));
@@ -949,7 +949,7 @@ function findInstalledChromiumBinary() {
 
 function fetchJsonSync(url, timeoutMs) {
   const r = spawnSync(process.execPath, ['-e', `
-    const http = _httpModule;
+    const http = require('http');
     const req = http.get(${JSON.stringify(url)}, (res) => {
       let buf = '';
       res.on('data', d => buf += d);
@@ -1057,7 +1057,7 @@ function gracefulCloseBrowser(entry, reason) {
       const info = fetchJsonSync(`http://127.0.0.1:${port}/json/version`, 600);
       if (info && info.webSocketDebuggerUrl) {
         spawnSync(process.execPath, ['-e', `
-          const http = _httpModule;
+          const http = require('http');
           const req = http.request({host:'127.0.0.1',port:${port},path:'/json/close/browser',method:'GET',timeout:1500},
             res => { res.resume(); res.on('end', () => process.exit(0)); });
           req.on('error', () => process.exit(1));
@@ -2369,8 +2369,33 @@ async function runSpoolWatcher(instance, spoolDir) {
             }
             const latest = JSON.parse(body).version;
             const stalePath = path.join(spoolDir, '.gm-plugkit-stale.json');
+            const respawnGuardPath = path.join(spoolDir, '.gm-plugkit-respawn-guard.json');
             if (!latest || latest === own) {
               if (fs.existsSync(stalePath)) { try { fs.unlinkSync(stalePath); } catch (_) {} }
+              if (fs.existsSync(respawnGuardPath)) { try { fs.unlinkSync(respawnGuardPath); } catch (_) {} }
+              return;
+            }
+            let respawnGuard = { attempts: 0, last_own: null, last_latest: null, first_ts: Date.now() };
+            try {
+              if (fs.existsSync(respawnGuardPath)) respawnGuard = JSON.parse(fs.readFileSync(respawnGuardPath, 'utf8'));
+            } catch (_) {}
+            const sameStaleAsBefore = respawnGuard.last_own === own && respawnGuard.last_latest === latest;
+            const cameFromSelfRespawn = process.env.PLUGKIT_BOOT_REASON === 'self-respawn-from-self-stale';
+            if (sameStaleAsBefore && respawnGuard.attempts >= 3) {
+              try { fs.writeFileSync(stalePath, JSON.stringify({
+                ts: new Date().toISOString(),
+                reason: 'gm-plugkit-self-stale-respawn-exhausted',
+                running_version: own,
+                latest_version: latest,
+                respawn_attempts: respawnGuard.attempts,
+                instruction: `gm-plugkit ${own} cannot self-upgrade to ${latest}: ${respawnGuard.attempts} respawns all came up ${own} (bun/npx cache is serving the stale tarball). Respawn loop halted to keep this watcher alive and serving verbs. Fix manually: bun pm cache rm; npm cache clean --force; rm -rf ~/AppData/Local/npm-cache/_npx ~/.bun/install/cache; then bun x gm-plugkit@latest --kill-stale-watchers; bun x gm-plugkit@latest spool`,
+                detected_by: 'watcher-periodic-probe',
+              }, null, 2)); } catch (_) {}
+              if (!_selfStaleLoggedOnce) {
+                _selfStaleLoggedOnce = true;
+                try { logEvent('plugkit', 'gm-plugkit.self-stale-respawn-exhausted', { running_version: own, latest_version: latest, attempts: respawnGuard.attempts }); } catch (_) {}
+                console.error(`[plugkit-wasm] gm-plugkit self-stale respawn EXHAUSTED after ${respawnGuard.attempts} attempts (cache serving stale ${own} for latest ${latest}); halting respawn loop and staying alive to serve verbs`);
+              }
               return;
             }
             const marker = {
@@ -2389,6 +2414,25 @@ async function runSpoolWatcher(instance, spoolDir) {
               try {
                 const cp = _childProcess;
                 const bunPath = process.env.GM_BUN_PATH || 'bun';
+                const bustCache = sameStaleAsBefore || cameFromSelfRespawn;
+                if (bustCache) {
+                  try { cp.execFileSync(bunPath, ['pm', 'cache', 'rm'], { stdio: 'ignore', timeout: 30000, windowsHide: true }); } catch (_) {}
+                  try {
+                    const home = process.env.USERPROFILE || process.env.HOME || '';
+                    for (const rel of ['AppData/Local/npm-cache/_npx', '.npm/_npx', '.bun/install/cache']) {
+                      try { fs.rmSync(path.join(home, rel), { recursive: true, force: true }); } catch (_) {}
+                    }
+                  } catch (_) {}
+                  try { logEvent('plugkit', 'gm-plugkit.self-stale-cache-busted', { running_version: own, latest_version: latest, attempt: (respawnGuard.attempts || 0) + 1 }); } catch (_) {}
+                }
+                try { fs.writeFileSync(respawnGuardPath, JSON.stringify({
+                  attempts: (sameStaleAsBefore ? (respawnGuard.attempts || 0) : 0) + 1,
+                  last_own: own,
+                  last_latest: latest,
+                  first_ts: respawnGuard.first_ts || Date.now(),
+                  last_ts: Date.now(),
+                  cache_busted: bustCache,
+                }, null, 2)); } catch (_) {}
                 const child = cp.spawn(bunPath, ['x', `gm-plugkit@${latest}`, 'spool'], {
                   cwd: process.cwd(),
                   detached: true,
@@ -2397,7 +2441,7 @@ async function runSpoolWatcher(instance, spoolDir) {
                   env: { ...process.env, PLUGKIT_BOOT_REASON: 'self-respawn-from-self-stale' },
                 });
                 child.unref();
-                try { logEvent('plugkit', 'gm-plugkit.self-stale-respawn', { running_version: own, latest_version: latest }); } catch (_) {}
+                try { logEvent('plugkit', 'gm-plugkit.self-stale-respawn', { running_version: own, latest_version: latest, cache_busted: bustCache, attempt: (respawnGuard.attempts || 0) + 1 }); } catch (_) {}
                 try { fs.writeFileSync(path.join(spoolDir, '.shutdown-reason.json'), JSON.stringify({ reason: 'gm-plugkit-self-stale', ts: Date.now(), pid: process.pid, running_version: own, latest_version: latest })); } catch (_) {}
                 // Wait for the replacement's fresh heartbeat before exiting (mirror the
                 // version-drift path) instead of a blind 2s exit: the gm-plugkit download can
@@ -2406,13 +2450,17 @@ async function runSpoolWatcher(instance, spoolDir) {
                 const myPid = process.pid;
                 const respawnDeadline = Date.now() + 90000;
                 const exitSelfStale = () => { try { process.exit(0); } catch (_) {} };
+                const ownVersionFile = path.join(GM_TOOLS_ROOT, 'gm-plugkit.version');
                 const pollSelfStaleReplacement = () => {
                   try {
                     const st = JSON.parse(fs.readFileSync(STATUS_PATH_FOR_TEARDOWN, 'utf8'));
                     const freshHeartbeat = st && st.ts && (Date.now() - st.ts) < 15000;
                     const differentProc = st && st.pid && st.pid !== myPid;
-                    if (freshHeartbeat && differentProc) {
-                      try { logEvent('plugkit', 'gm-plugkit.self-stale-respawn-confirmed', { old_pid: myPid, new_pid: st.pid, new_version: st.version, latest_version: latest }); } catch (_) {}
+                    let replacementOnLatest = false;
+                    try { replacementOnLatest = fs.readFileSync(ownVersionFile, 'utf-8').trim() === latest; } catch (_) {}
+                    if (freshHeartbeat && differentProc && replacementOnLatest) {
+                      try { fs.unlinkSync(respawnGuardPath); } catch (_) {}
+                      try { logEvent('plugkit', 'gm-plugkit.self-stale-respawn-confirmed', { old_pid: myPid, new_pid: st.pid, new_version: st.version, latest_version: latest, replacement_gm_plugkit: latest }); } catch (_) {}
                       return exitSelfStale();
                     }
                   } catch (_) {}

package/gm-plugkit/supervisor.js

@@ -72,20 +72,31 @@ function pidAlive(pid) {
 // 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() {
-  try {
-    if (fs.existsSync(SUPERVISOR_PID_PATH)) {
-      const other = parseInt(fs.readFileSync(SUPERVISOR_PID_PATH, 'utf-8').trim(), 10);
-      if (Number.isFinite(other) && other !== process.pid && pidAlive(other)) {
-        logEvent('supervisor.refused-duplicate', { existing_pid: other, severity: 'warn' });
-        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' });
+          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;
     }
-    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.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1517",
+  "version": "2.0.1519",
   "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.1517",
+  "version": "2.0.1519",
   "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",