gm-skill 2.0.1607 → 2.0.1609

package/AGENTS.md

@@ -156,6 +156,8 @@ Orchestration state is tracked via `.gm/` marker files, not hook events; the CLI
 
 **Dead-watcher recovery uses `bun x gm-plugkit@latest spool`, never direct-node boot** (mechanism in rs-learn: `recall: dead-watcher recovery bun x not direct-node`).
 
+**Apparent tooling failure is mechanical self-recovery, NEVER a question for the user and never an a/b-test/blind-restart.** "The spooler is not working" / a missing spool response / a stale watcher is the agent's own job to fix: honor a future `busy_until` (wait), else boot the watcher and re-dispatch; on a transient boot hiccup (`FailedToOpenSocket`) retry `@latest`, never the non-`@latest` cache (stale). The spooler is sound by construction -- `.status.json` is written atomically (temp+rename, `atomicWriteJson`) and every long verb advertises `busy_until` -- so a transient unreadable/stale read is a respawn/idle-teardown window to boot through, not a broken tool; asking the user to do what a verb can do is a paper-spirit violation. Debug the live page via `window.*` globals + the `browser` verb's `page.evaluate` as a process of elimination, never variant-after-variant a/b testing. This IS the core gm method on every surface including its own tooling: record all mutables, eliminate each by witness, discover more, keep going.
+
 **The first verb after a genuine multi-minute IDLE is `instruction`, to reset the long-gap clock**: gate fires when >300s since last instruction AND >300s since any SPOOL verb. Platform `Bash`/`Read`/`Edit`/`Grep` do NOT reset the clock -- a long investigation run in them trips a false stall; interleave `prd-add` or `instruction` to keep warm. For a predictable blocking wait (`TaskOutput`/`gh run watch`), dispatch `instruction` BEFORE entering the wait. Detail + platform-tool exception in rs-learn (`recall: first verb after multi-minute wait instruction long-gap`).
 
 **A stop-hook firing on a terminal chain does not authorize re-polling**: when a stop-hook fires while already at `phase=COMPLETE` AND `prd_pending_count=0`, re-dispatching `instruction`/`phase-status` to "re-confirm" is a deviation (`deviation.complete-chain-poll`, `instructions/mod.rs`). Two admissible responses: (a) a prose-only turn (COMPLETE is in hand), or (b) genuinely new planned work opened with a FRESH `{"prompt":...}` body (resets phase to PLAN, driven through the skill). Repeatedly answering the same hook is a loop; state the terminal facts once and stop, or open new work.

package/bin/gm-shell-validate.js

@@ -10,6 +10,18 @@ const { pathToFileURL } = require('url');
 const ROOT = process.cwd();
 const WITNESS_DIR = path.join(ROOT, '.gm', 'witness');
 
+function freePort() {
+  const net = require('net');
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.once('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const p = srv.address().port;
+      srv.close(() => resolve(p));
+    });
+  });
+}
+
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 function rmrf(p) { try { fs.rmSync(p, { recursive: true, force: true }); } catch (_) {} }
 function write(file, text) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, text); }
@@ -26,7 +38,7 @@ function which(cmds) {
 async function renderPreview() {
   const preview = fs.mkdtempSync(path.join(os.tmpdir(), 'gm-shell-preview-'));
   fs.mkdirSync(path.join(preview, 'vendor'), { recursive: true });
-  cp.execSync(`powershell.exe -NoProfile -NonInteractive -Command "Copy-Item -Recurse -Force '${path.join(ROOT, 'site', 'vendor', '*')}' '${path.join(preview, 'vendor')}'"`, { stdio: 'ignore', windowsHide: true });
+  fs.cpSync(path.join(ROOT, 'site', 'vendor'), path.join(preview, 'vendor'), { recursive: true });
 
   const renderScript = `
     import { writeFileSync } from 'fs';
@@ -44,17 +56,18 @@ async function renderPreview() {
       }
     };
     const out = await mod.default.render(ctx);
-    writeFileSync(resolve('${preview.replace(/\\/g, '\\\\')}', 'index.html'), out[0].html);
+    writeFileSync(resolve(process.env.GM_SHELL_PREVIEW, 'index.html'), out[0].html);
   `;
   const tmp = path.join(os.tmpdir(), `gm-shell-render-${Date.now()}.mjs`);
   fs.writeFileSync(tmp, renderScript);
-  cp.execFileSync('node', [tmp], { stdio: 'inherit', windowsHide: true });
+  cp.execFileSync('node', [tmp], { stdio: 'inherit', windowsHide: true, env: { ...process.env, GM_SHELL_PREVIEW: preview } });
   try { fs.unlinkSync(tmp); } catch (_) {}
 
-  const server = cp.spawn('python', ['-m', 'http.server', '4210', '--directory', preview], { cwd: ROOT, detached: true, stdio: 'ignore', windowsHide: true });
+  const port = await freePort();
+  const server = cp.spawn('python', ['-m', 'http.server', String(port), '--directory', preview], { cwd: ROOT, detached: true, stdio: 'ignore', windowsHide: true });
   server.unref();
   await sleep(1500);
-  return { preview, port: 4210, serverPid: server.pid };
+  return { preview, port, serverPid: server.pid };
 }
 
 function killServer(pid) {
@@ -96,7 +109,7 @@ return JSON.stringify(result);
   const response = await fetch(relayUrl, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ sessionId: '9', code: script, timeout: 60000, cwd: ROOT }),
+    body: JSON.stringify({ sessionId: `gm-shell-${process.pid}-${Date.now()}`, code: script, timeout: 60000, cwd: ROOT }),
   });
   const result = await response.json();
   const out = result.text || '';

package/gm-plugkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.1607",
+  "version": "2.0.1609",
   "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.version

@@ -1 +1 @@
-0.1.683
+0.1.684

package/gm.json

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

package/lib/spool.js

@@ -55,7 +55,13 @@ function writeSpool(body, lang = 'nodejs', options = {}) {
   fs.mkdirSync(inDir, { recursive: true });
 
   const sessionId = options.sessionId || process.env.CLAUDE_SESSION_ID;
-  const code = sessionId ? `const SESSION_ID = ${JSON.stringify(sessionId)};\n${body}` : body;
+  let code = body;
+  if (sessionId) {
+    const prelude = validLang === 'bash'
+      ? `SESSION_ID=${JSON.stringify(String(sessionId))}\n`
+      : `const SESSION_ID = ${JSON.stringify(sessionId)};\n`;
+    code = prelude + body;
+  }
 
   fs.writeFileSync(inFile, code, 'utf8');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-skill",
-  "version": "2.0.1607",
+  "version": "2.0.1609",
   "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",
@@ -38,7 +38,18 @@
     "bin/plugkit.sha256",
     "bin/plugkit.version",
     "bin/plugkit.wasm.sha256",
-    "gm-plugkit/",
+    "gm-plugkit/bootstrap.js",
+    "gm-plugkit/browser-idle.js",
+    "gm-plugkit/cli.js",
+    "gm-plugkit/index.js",
+    "gm-plugkit/lang-host-runner.js",
+    "gm-plugkit/package.json",
+    "gm-plugkit/plugkit-wasm-wrapper.js",
+    "gm-plugkit/supervisor.js",
+    "gm-plugkit/plugkit.version",
+    "gm-plugkit/plugkit.sha256",
+    "gm-plugkit/instructions/",
+    "gm-plugkit/scripts/",
     "AGENTS.md",
     "README.md",
     "gm.json"

package/skills/gm-skill/SKILL.md

@@ -48,6 +48,10 @@ bun x gm-plugkit@latest spool > /dev/null 2>&1 &
 
 **Dead-watcher recovery is mandatory.** Two consecutive missing re-Reads AND stale `ts` (>15s) AND no future `busy_until` = dead: `bun x gm-plugkit@latest spool` to boot a fresh watcher, then re-dispatch the original verb. Never substitute an alternative tool (puppeteer-core, WebFetch, raw chrome) for the `browser` verb -- reaching outside plugkit orphans state and bypasses the witness gates. Recovery is always notice-dead -> boot -> re-dispatch.
 
+**Apparent tooling failure is NEVER grounds to ask the user, and never a reason to a/b-test or blind-restart.** "The spooler is not working" / a missing spool response / a stale watcher is YOUR mechanical, self-service recovery, not a question for the user: honor a future `busy_until` (wait), else boot the watcher and re-dispatch -- you have the authority to boot, so asking the user to do it (or to do anything the verbs can do) is a paper-spirit violation. The spooler mechanics are sound by construction (`.status.json` is written atomically temp+rename, every long verb advertises `busy_until`), so a transient unreadable/stale read is a respawn/idle-teardown window to boot through, not a broken tool. When a transient boot hiccup occurs (e.g. `FailedToOpenSocket`), retry `bun x gm-plugkit@latest spool` -- blips resolve in seconds; never escalate to the user and never fall back to a non-`@latest` cache (it lands a stale watcher). This is the gm method applied to your own tooling: record each candidate cause as a mutable, eliminate it by witness, discover more, keep going.
+
+**Debug the live page via globals + process-of-elimination, never a/b testing.** When a browser/client issue is hard, the move is NOT to guess-and-restart or try variant after variant: surface the relevant state as a `window.*` global and read it live via the `browser` verb's `page.evaluate`, running experiments in the page to eliminate hypotheses one by one (record each as a mutable, witness its resolution, add the new mutables it reveals). A global plus one evaluate observes real runtime state in a single dispatch; the restart-and-eyeball / a/b loop observes almost nothing and burns turns. This process -- record all mutables, eliminate by witness, discover more, keep going -- is the core of gm and applies to every debugging surface, the browser most of all.
+
 From PowerShell, write spool input as UTF-8 no-BOM (`-Encoding utf8` or `[System.IO.File]::WriteAllText`); the 5.1 default UTF-16+BOM trips `spool.body-encoding-recoded`. Prefer the `Write` tool for JSON bodies. First-turn body is `{"prompt":"<user request>"}` (derives orient_nouns + recall_hits); later same-conversation turns may use `{}`. A `Write` to `in/<verb>/` that errors `ENOENT` (a fast watcher consumed and unlinked the file before the tool's post-write stat) has STILL dispatched -- confirm via the `out/` response, never blind-retry (a non-idempotent verb like `git_finalize` would double-fire); a Bash heredoc `cat > in/<verb>/<N>.txt` has no post-write stat and never surfaces this.
 
 **Batch writes and reads together.** Write request + Read response is one logical step -- issue both in one block, not three turns. Fan-out is the same: N independent verbs = N Writes in one block then N Reads in one block. Only a real data dependency (verb B needs A's response) forces separate turns.

package/gm-plugkit/browser-idle.test.js

@@ -1,46 +0,0 @@
-const assert = require('assert');
-const { selectIdleBrowserSessions } = require('./browser-idle.js');
-
-const NOW = 1_000_000;
-const LIMIT = 10 * 60 * 1000;
-
-(function onlyPastLimitSelected() {
-  const ports = {
-    active: { pid: 1, lastUse: NOW - 1000 },
-    idle: { pid: 2, lastUse: NOW - (LIMIT + 5000) },
-  };
-  const idle = selectIdleBrowserSessions(ports, NOW, LIMIT);
-  assert.strictEqual(idle.length, 1, 'exactly one idle session selected');
-  assert.strictEqual(idle[0].sid, 'idle', 'the idle session is selected, active untouched');
-})();
-
-(function boundaryIsInclusive() {
-  const ports = { edge: { pid: 1, lastUse: NOW - LIMIT } };
-  const idle = selectIdleBrowserSessions(ports, NOW, LIMIT);
-  assert.strictEqual(idle.length, 1, 'idleMs == limit closes (>=)');
-})();
-
-(function missingLastUseReapedAsStale() {
-  const ports = { orphan: { pid: 1 } };
-  const idle = selectIdleBrowserSessions(ports, NOW, LIMIT);
-  assert.strictEqual(idle.length, 1, 'entry with no lastUse is treated as stale (epoch 0) and reaped');
-  assert.strictEqual(idle[0].sid, 'orphan');
-})();
-
-(function concurrentIsolation() {
-  const ports = {
-    sessA: { pid: 1, lastUse: NOW - 2000 },
-    sessB: { pid: 2, lastUse: NOW - (LIMIT + 1) },
-    sessC: { pid: 3, lastUse: NOW - (LIMIT + 999999) },
-  };
-  const idle = selectIdleBrowserSessions(ports, NOW, LIMIT).map(x => x.sid).sort();
-  assert.deepStrictEqual(idle, ['sessB', 'sessC'], 'only the idle sessions, active sessA preserved');
-})();
-
-(function emptyAndMalformed() {
-  assert.deepStrictEqual(selectIdleBrowserSessions({}, NOW, LIMIT), [], 'empty ports');
-  assert.deepStrictEqual(selectIdleBrowserSessions(null, NOW, LIMIT), [], 'null ports');
-  assert.deepStrictEqual(selectIdleBrowserSessions({ bad: null, str: 'x' }, NOW, LIMIT), [], 'malformed entries skipped');
-})();
-
-console.log('browser-idle.test.js: all assertions passed');

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

@@ -1,25 +0,0 @@
-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');