gm-skill 2.0.1911 → 2.0.1913

package/AGENTS.md

@@ -24,9 +24,11 @@ Skills encode environment-specific constraints that override general knowledge.
 
 Repo root = package root = published `gm-skill` npm package; no factory, no separate build-output dir. Entry: `skills/gm/SKILL.md`. Orchestration lives in rs-plugkit, served on-demand via `instruction`. Agent-facing prose (phase instruction, gate/residual text) externalizes to editable `gm-plugkit/instructions/`: prose edits = gm-plugkit republish, zero Rust rebuild. Mechanism (prose.rs per-key fallback to compiled const; sync-instruction-consts.mjs byte-aligns .md<->rs-plugkit consts) in the recall store (`recall: string-externalization project`).
 
-## WASM-only
+## WASM-only, now with an optional native runner
 
-Plugkit = wasm cdylib, loaded by `plugkit-wasm-wrapper.js` under Node/bun; zero native binaries built/downloaded/published. `plugkit.wasm` fetched at bootstrap from `plugkit-wasm` npm / `plugkit-bin` gh-releases, sha256-pinned. Size + embedded-model (offline in-wasm embeddings) mechanics: the recall store (`recall: WASM-only plugkit size mechanics`).
+Plugkit = wasm cdylib. Two host loaders exist and coexist: `plugkit-wasm-wrapper.js` under Node/bun (original, still the default) and `gm-runner` (rs-plugkit `crates/gm-runner/`, a real native cross-platform binary built by CI and published to `AnEntrypoint/gm-runner-bin` releases) -- gm-runner links `wasmtime` and hosts the same wasm module directly, no Node/bun dependency for the boot step. Both loaders serve the byte-identical spool ABI (`in/`/`out/` layout, verb names), so a gm-driven session works the same regardless of which loader booted it. `bin/install.js` best-effort-downloads gm-runner (sha256-verified against its release's `.sha256` sidecar) but never hard-requires it -- a platform with no published gm-runner binary, or a failed download, silently falls back to bun/npx exactly as before. `plugkit.wasm` itself is fetched at bootstrap from `plugkit-wasm` npm / `plugkit-bin` gh-releases, sha256-pinned, by whichever loader is running (gm-runner's own `download.rs::bootstrap_plugkit_wasm` mirrors the JS wrapper's fetch+verify). Size + embedded-model (offline in-wasm embeddings) mechanics: the recall store (`recall: WASM-only plugkit size mechanics`).
+
+**gm-runner auto-updates the wasm it serves, not itself.** `spool.rs::run_spool_watcher` polls `plugkit-bin`'s GitHub Releases API every 600s for a newer tag (`download.rs::fetch_latest_plugkit_version`); on a mismatch it downloads+verifies the new wasm and the existing 30s local-version-skew check picks up the on-disk change and triggers a clean in-process reload (`StopReason::Reload`). The gm-runner *executable* itself has no such remote self-update loop yet -- a stale installed gm-runner binary keeps running until the next `bin/install.js` re-run re-checks `gm-runner-bin`'s latest release tag.
 
 Wasm host-import link-module rule (`#[link(wasm_import_module="env")]` on every host-import extern block, every dep crate): the recall store (`recall: wasm host-import link-module trap`).
 
@@ -152,6 +154,8 @@ A task that reduces to read/investigate/report, or a change confined to files th
 
 Push to any rs-* sibling -> `cascade.yml` -> rs-plugkit `release.yml` -> single `plugkit.wasm` (npm `plugkit-wasm` + `plugkit-bin` Releases) -> auto-bump `gm.json::plugkitVersion` -> `publish.yml` ships gm-skill+gm-plugkit+SKILL.md mirror. Step sequence + PUBLISHER_TOKEN: the recall store (`recall: cascade pipeline`).
 
+A push touching `rs-plugkit/crates/gm-runner/**` additionally triggers its own `gm-runner.yml` workflow (separate from `release.yml`, matrix-builds all 6 platform targets, publishes to `AnEntrypoint/gm-runner-bin` Releases) -- a stuck/unschedulable single matrix leg (observed: `macos-13` queued 18h+ with zero GH-assigned runner) must never block the `release` job from shipping the other 5 platforms; that job runs `if: always()` and tolerates partial artifacts rather than a blanket `needs: build` hard-gate.
+
 **Repos involved (push to any triggers cascade):** `AnEntrypoint/{rs-codeinsight, rs-search, rs-plugkit, gm}`. rs-learn and rs-exec are retired (crates removed from / never depended on by rs-plugkit; their spool-dispatch and memory surfaces reimplemented natively in rs-plugkit wasm_dispatch; repos archived as tombstones, README points at rs-plugkit). Roles, npm package names, legacy-retirement detail: the recall store (`recall: cascade repos involved roles`, `recall: legacy gm-skill variants retired`).
 
 **To update every possible thing**: push to the relevant repo. No manual version bumps, no local `cargo update`/`cargo build` -- push, let CI build.

package/bin/install.js

@@ -4,6 +4,8 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
+const https = require('https');
 const readline = require('readline');
 
 function out(msg) { process.stdout.write(msg + '\n'); }
@@ -170,6 +172,119 @@ function runPlugkitBootstrap() {
   return Promise.resolve(false);
 }
 
+// Maps process.platform/process.arch to the exact release-asset basename
+// gm-runner's CI (rs-plugkit/.github/workflows/gm-runner.yml) publishes to
+// AnEntrypoint/gm-runner-bin -- must stay byte-identical to that workflow's
+// `artifact:` matrix values, this is the only other place that name is
+// spelled. Returns null for a host combination CI does not build (no crash,
+// caller falls back to the existing bun/npx path).
+function gmRunnerAssetName() {
+  const plat = process.platform;
+  const arch = process.arch;
+  if (plat === 'win32') {
+    if (arch === 'x64') return 'gm-runner-windows-x64.exe';
+    if (arch === 'arm64') return 'gm-runner-windows-arm64.exe';
+    return null;
+  }
+  if (plat === 'darwin') {
+    if (arch === 'x64') return 'gm-runner-macos-x64';
+    if (arch === 'arm64') return 'gm-runner-macos-arm64';
+    return null;
+  }
+  if (plat === 'linux') {
+    if (arch === 'x64') return 'gm-runner-linux-x64';
+    if (arch === 'arm64') return 'gm-runner-linux-arm64';
+    return null;
+  }
+  return null;
+}
+
+function httpsGetBuffer(url, redirectsLeft) {
+  if (redirectsLeft === undefined) redirectsLeft = 5;
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { 'User-Agent': 'gm-skill-installer' } }, res => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        if (redirectsLeft <= 0) { reject(new Error('too many redirects fetching ' + url)); return; }
+        httpsGetBuffer(res.headers.location, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`GET ${url} -> HTTP ${res.statusCode}`));
+        return;
+      }
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+      res.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+function sha256Hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function gmToolsDir() {
+  const home = homeDir();
+  return path.join(home, '.gm-tools');
+}
+
+// Downloads the platform-matched gm-runner binary from gm-runner-bin's
+// GitHub Releases (native runner replacing the bun/node spool-boot path),
+// verified against the release's own .sha256 sidecar before the atomic
+// rename lands -- same trust model as gm-runner's own
+// download::download_and_verify for plugkit.wasm, so a corrupt/partial
+// download is never silently accepted. Best-effort: any failure (offline,
+// asset missing for this host, network error) resolves false rather than
+// throwing, so install never hard-fails over a runner-binary fetch -- the
+// bun/npx spool path remains the fallback until remove-node-bun-from-native-path
+// lands.
+async function downloadGmRunner({ silent } = {}) {
+  const assetName = gmRunnerAssetName();
+  if (!assetName) {
+    if (!silent) err(`gm-runner: no published binary for platform=${process.platform} arch=${process.arch}, skipping native runner install`);
+    return false;
+  }
+  const destDir = gmToolsDir();
+  const destPath = path.join(destDir, assetName.endsWith('.exe') ? 'gm-runner.exe' : 'gm-runner');
+  try {
+    const releaseInfo = JSON.parse((await httpsGetBuffer('https://api.github.com/repos/AnEntrypoint/gm-runner-bin/releases/latest')).toString('utf8'));
+    const tag = releaseInfo && releaseInfo.tag_name;
+    if (!tag) { if (!silent) err('gm-runner: no releases published yet at AnEntrypoint/gm-runner-bin, skipping'); return false; }
+    const base = `https://github.com/AnEntrypoint/gm-runner-bin/releases/download/${tag}`;
+    const binUrl = `${base}/${assetName}`;
+    const shaUrl = `${binUrl}.sha256`;
+
+    const versionFile = path.join(destDir, 'gm-runner.version');
+    if (fs.existsSync(destPath) && fs.existsSync(versionFile)) {
+      const installed = fs.readFileSync(versionFile, 'utf8').trim();
+      if (installed === tag) { if (!silent) out(`gm-runner ${tag} already installed at ${destPath}`); return true; }
+    }
+
+    const [binBuf, shaBuf] = await Promise.all([httpsGetBuffer(binUrl), httpsGetBuffer(shaUrl)]);
+    const expectedSha = shaBuf.toString('utf8').trim().split(/\s+/)[0];
+    const actualSha = sha256Hex(binBuf);
+    if (!expectedSha || actualSha.toLowerCase() !== expectedSha.toLowerCase()) {
+      if (!silent) err(`gm-runner: sha256 mismatch downloading ${binUrl} (expected ${expectedSha}, got ${actualSha}), not installing`);
+      return false;
+    }
+
+    fs.mkdirSync(destDir, { recursive: true });
+    const tmp = destPath + '.tmp' + process.pid;
+    fs.writeFileSync(tmp, binBuf);
+    if (process.platform !== 'win32') { try { fs.chmodSync(tmp, 0o755); } catch (_) {} }
+    fs.renameSync(tmp, destPath);
+    fs.writeFileSync(versionFile, tag);
+    if (!silent) out(`Installed gm-runner ${tag} to ${destPath}`);
+    return true;
+  } catch (e) {
+    if (!silent) err(`gm-runner download skipped: ${e && e.message || e}`);
+    return false;
+  }
+}
+
 function printHelp() {
   out('gm installer');
   out('');
@@ -220,6 +335,7 @@ async function main() {
   }
 
   await runPlugkitBootstrap();
+  await downloadGmRunner({ silent: false });
 
   out('');
   out('Done. Open Claude Code and run /gm. New top-level skill dirs may need one restart to register.');

package/gm-plugkit/package.json

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

@@ -758,6 +758,29 @@ function findCachedBunRunnerBin() {
   return null;
 }
 
+// Cache dir entries are named `<pkg>@<version>[@@@N]` (the `@@@N` suffix is bun's own
+// disambiguator for multiple cache slots of the same resolved version, not part of the semver).
+// Picks the highest semver-looking version present so a stale older cache entry left over from
+// a prior gm-plugkit run doesn't win over a newer one that's also cached.
+function findCachedBunRunnerVersion() {
+  try {
+    const cacheDir = path.join(os.homedir(), '.bun', 'install', 'cache');
+    const entries = fs.readdirSync(cacheDir).filter(n => n.startsWith(`${BROWSER_RUNNER_BIN}@`));
+    const versions = entries
+      .map(n => n.slice(BROWSER_RUNNER_BIN.length + 1).split('@@@')[0])
+      .filter(v => /^\d+\.\d+\.\d+/.test(v));
+    if (!versions.length) return null;
+    versions.sort((a, b) => {
+      const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
+      for (let i = 0; i < 3; i++) { if (pa[i] !== pb[i]) return pb[i] - pa[i]; }
+      return 0;
+    });
+    return versions[0];
+  } catch (_) {
+    return null;
+  }
+}
+
 // playwriter's CLI `--timeout` option is parsed as a raw string (its own arg parser does not
 // coerce it despite the zod schema declaring z.number()), and that string is forwarded verbatim
 // into `vm.runInContext(..., { timeout })`, which throws
@@ -826,7 +849,19 @@ function findBrowserRunner() {
   const whichCmd = process.platform === 'win32' ? 'where' : 'which';
   const bunR = spawnSync(whichCmd, ['bun'], { encoding: 'utf-8', shell: true });
   if (bunR.status === 0 && bunR.stdout.trim()) {
-    return { cmd: 'bun', baseArgs: ['x', `${BROWSER_RUNNER_BIN}@latest`], shell: true };
+    // `bun x <pkg>@latest` re-resolves the `@latest` tag against the npm registry on every
+    // single invocation, even when a resolved copy already sits in bun's own content-addressed
+    // cache (~/.bun/install/cache/<pkg>@<version>) from a prior run -- a redundant network
+    // round-trip per browser-verb dispatch. Observed on Windows to occasionally never return
+    // (hangs past "Resolved, downloaded and extracted" with no further output or error), which
+    // wedges every subsequent browser dispatch behind a 30s+ spawnSync timeout for no benefit,
+    // since the pinned exact version was already available locally. Prefer `bun x <pkg>@<exact
+    // cached version>` when a cached copy exists -- this still goes through `bun x`'s real
+    // dependency-tree resolution (the reason `bun x` is preferred over the raw cached bin.js
+    // above), it just skips the registry round-trip for the tag lookup itself.
+    const cachedVersion = findCachedBunRunnerVersion();
+    const pkgSpec = cachedVersion ? `${BROWSER_RUNNER_BIN}@${cachedVersion}` : `${BROWSER_RUNNER_BIN}@latest`;
+    return { cmd: 'bun', baseArgs: ['x', pkgSpec], shell: true };
   }
   const cachedBin = findCachedBunRunnerBin();
   if (cachedBin) return { cmd: process.execPath, baseArgs: [cachedBin], shell: false };

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1911",
+  "version": "2.0.1913",
   "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.1911",
+  "version": "2.0.1913",
   "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",

package/skills/gm/SKILL.md

@@ -60,6 +60,8 @@ bun x gm-plugkit@latest spool
 
 (`npx -y gm-plugkit@latest spool` if no `bun`.) Fire-and-forget: spawns the detached daemon and returns immediately (already-alive watcher also returns at once, unchanged) -- it does NOT wait for the watcher to confirm serving. No `&`, no `sleep`, no re-`cat`; write your first verb to `in/` right after it returns. A first-read "file does not exist" on that verb is normal (the just-spawned watcher hasn't noticed the file yet) -- re-Read next message, same as any dead-watcher-adjacent recheck. If you need to actively confirm serving before dispatching (rare), read `.gm/exec-spool/.status.json` yourself and check `ts` freshness.
 
+**A native `gm-runner` binary at `~/.gm-tools/gm-runner` (`gm-runner.exe` on Windows) is a drop-in replacement for the bun/npx boot line above, when present** -- `gm-runner spool` serves the identical spool ABI (same `in/`/`out/` layout, same verb names) directly from a compiled binary, no bun/npx/node_modules dependency for the boot step. It is optional and additive right now, not a required cutover: `bin/install.js`'s installer best-effort-downloads it (sha256-verified, from `AnEntrypoint/gm-runner-bin` releases) but silently no-ops if the platform has no published binary yet or the download fails, and gm-runner itself only auto-updates its own served `plugkit.wasm` (a background 600s remote-version poll), not its own executable. If `~/.gm-tools/gm-runner` (or `.exe`) exists, prefer it for the boot line; otherwise fall back to `bun x gm-plugkit@latest spool` exactly as before -- both are equally valid, check-for-binary-then-fallback, never a hard requirement on one or the other.
+
 The `Resolving dependencies` / `Saved lockfile` chatter before the JSON payload is `bunx` re-resolving the `@latest` tag against the registry, not gm-plugkit hanging -- the daemon already spawns detached+unref'd and the CLI itself exits the instant that happens; the visible delay is entirely bunx's own network round-trip, unavoidable on `@latest` (a pinned exact version, once bunx-cached, skips it). `GM_PLUGKIT_SKIP_SELF_STALE_CHECK=1` skips the CLI's own redundant npm-registry version probe (already covered by `@latest`'s resolution) for a faster boot on repeat same-session invocations. In PowerShell 5.1, never `2>&1`-redirect this command into another cmdlet (e.g. `| Select-Object`) -- PowerShell wraps every stderr line from a native exe in a `NativeCommandError` record and reports failure even on exit 0, turning bun's routine stderr progress output into a misleading red error block; run it bare or capture stdout only.
 
 **Dispatch shape: Write request + Read response, SAME tool-call block.** Never proceed/narrate/begin work before reading the response and following its `instruction` field. First-read "file does not exist" mid-verb = normal, re-Read next message. Never poll with `sleep && ls` -- plugkit is synchronous; missing response = dead watcher (recheck `ts`) or slow verb, never "still processing."