gm-plugkit 2.0.2469 → 2.0.2471

package/SKILL.md

@@ -60,7 +60,7 @@ 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 check 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 check serving before dispatching (rare), read `.gm/exec-spool/.status.json` yourself and check `ts` freshness.
 
-**The boot line resolves to agentplug-runner, the sole spool loader; `bun x gm-plugkit@latest spool` is the thin launcher that re-execs into it.** `gm-plugkit/cli.js::tryDelegateToRunner` execs `~/.gm-tools/agentplug-runner` -- a native wasmtime binary that loads gm.wasm alongside shared `bert`/`libsql`/`treesitter` plugins (so gm runs `plugkit-slim.wasm`, browser via direct CDP, task via a native registry); `.status.json` `runtime` reads `agentplug` when it serves. The JS wasm-host (`plugkit-wasm-wrapper.js`) and the redundant `gm-runner` native host are retired -- there is no fallback loader. `bin/install.js` hard-requires agentplug-runner: it downloads the sha256-verified binary from `AnEntrypoint/agentplug-bin` for the host platform and fails loudly if none is published (or the download fails) rather than leaving no loader. agentplug-runner auto-updates both its served `plugkit.wasm` and its own executable fully autonomously (600s poll each): a newer runner build is staged to `.new` in the background, then swapped in via a self-triggered `takeover` handoff on the next idle tick -- no agent action, no `bin/install.js` re-run, no restart ever required.
+**The boot line resolves to agentplug-runner, the sole spool loader; `bun x gm-plugkit@latest spool` is the thin launcher that re-execs into it.** `gm-plugkit/cli.js::tryDelegateToRunner` execs `~/.gm-tools/agentplug-runner` -- a native wasmtime binary that loads gm.wasm alongside shared `bert`/`libsql`/`treesitter` plugins (so gm runs `plugkit-slim.wasm`, browser via direct CDP, task via a native registry); `.status.json` `runtime` reads `agentplug` when it serves. A missing runner binary is downloaded and sha256-verified automatically on the next boot attempt -- no separate install step. agentplug-runner auto-updates both its served `plugkit.wasm` and its own executable fully autonomously (600s poll each): a newer runner build is staged to `.new` in the background, then swapped in via a self-triggered `takeover` handoff on the next idle tick -- no agent action, no restart ever required.
 
 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.
 
@@ -74,7 +74,7 @@ Two more real, code-checked env toggles beyond `GM_PLUGKIT_SKIP_SELF_STALE_CHECK
 
 **Reboot-loop escape (watcher dies ~30-90s after every boot).** If a fresh `bun x gm-plugkit@latest spool` boots but the watcher dies again shortly after (heartbeat `ts` goes stale >30s with no future `busy_until`, then a new pid appears, repeatedly), the on-disk index has not finished embedding and each boot re-triggers the same synchronous code-index embed that can block the heartbeat past the supervisor's 30s stale limit (`STATUS_STALE_MS`). Confirm by reading `.gm/exec-spool/.watcher.log` for repeated `codeinsight_rebuild` + `partial pass (wall budget) ... deferred_files=N` lines whose `deferred_files` never reaches 0. The embed is genuinely converging in that case: do NOT immediately re-boot on the first stale reading -- read `.watcher.log`, and as long as `deferred_files` is strictly decreasing across `codeinsight_index_partial` events the index is converging (each accepted verb advances it one wall-budget); give it repeated single verbs until a `code_index: done` / `deferred_files=0` line appears, then normal dispatch resumes. Rebooting mid-convergence resets this progress -- the loop is the reboot, not the embed.
 
-**A self-update in progress or just-completed is visible directly in `.status.json`, no manual log-reading needed.** `runner_update_in_progress: true` (with `runner_update_waiting_ms`) means a newer runner build is staged and mid-handoff right now -- a dispatch that lands in this window can come back `dispatch_orphaned` (`"was claimed by a daemon that died before answering... a self-update handoff that exited while this dispatch was still running"`); this is expected, not a real failure, and the fix is a bare re-dispatch of the exact same verb once `.status.json`'s `ts` is fresh again, never a different recovery path. `last_completed_runner_swap: {version, swapped_at_ts}` is the durable "a swap just happened" record -- diff it against what you last saw this session to notice a version change mid-turn (served prose, gate behavior, or verb set can differ across a swap) without needing to poll continuously. `loaded_plugin_versions: {gm, bert, libsql, treesitter}` reports each currently-loaded plugin's version string, purely informational -- a plugin content-hash recompile evicts and rebuilds in-process without a process restart, so it never orphans a dispatch the way a runner takeover does, but the version is still worth diffing against a prior read to notice gm's own behavior changed mid-session. None of these three fields change what you dispatch next; they explain WHY a dispatch might have just failed or WHY served behavior just shifted, so it is recognized and handled immediately instead of investigated as a mystery.
+A `dispatch_orphaned` response ("claimed by a daemon that died before answering... a self-update handoff") is expected during a runner takeover, never a real failure -- bare re-dispatch the exact same verb once `.status.json`'s `ts` is fresh again. `.status.json`'s `last_completed_runner_swap`/`loaded_plugin_versions` are diagnostic-only, worth diffing against a prior read to notice served behavior changed mid-session; neither changes what to dispatch next.
 
 **Apparent tooling failure is never grounds to ask the user, never a blind restart.** "Spooler not working" / missing response / stale watcher / `gm_plugkit_stale` flagged in a response = your own mechanical self-recovery: honor a future `busy_until` (wait), else boot + re-dispatch. You have boot authority; asking the user to do what a verb can do is a deviation. Staleness of any kind (stale watcher version, stale served prose vs published source) is itself a deviation to resolve immediately, the same turn it's noticed -- `bun x gm-plugkit@latest spool` first, before any other work.
 

package/bootstrap.js

@@ -231,6 +231,24 @@ function httpGetBuffer(url, timeoutMs) {
   });
 }
 
+function httpHeadOk(url, timeoutMs) {
+  const https = require('https');
+  return new Promise((resolve, reject) => {
+    const req = https.request(url, { method: 'HEAD', timeout: timeoutMs || 3000, headers: { 'user-agent': 'gm-plugkit-bootstrap' } }, (res) => {
+      res.resume();
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        httpHeadOk(res.headers.location, timeoutMs).then(resolve, reject);
+        return;
+      }
+      if (res.statusCode === 200) resolve();
+      else reject(new Error(`HTTP ${res.statusCode} ${url}`));
+    });
+    req.on('timeout', () => { try { req.destroy(new Error(`idle-timeout ${timeoutMs || 3000}ms ${url}`)); } catch (_) {} });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
 async function downloadFromGithubReleases(destPath, version, artifactName) {
   const name = artifactName || 'plugkit.wasm';
   const base = `https://github.com/AnEntrypoint/plugkit-bin/releases/download/v${version}`;
@@ -546,12 +564,59 @@ function discoverBundledSkillsAndSourcesLocal() {
   return found;
 }
 
+// Walks a (decompressed) POSIX tar stream's fixed 512-byte headers, yielding
+// each entry's name. `git archive --remote` was tried first and does NOT
+// work against GitHub (its git server returns HTTP 422 for upload-archive,
+// a documented GitHub limitation) -- codeload.github.com's tarball endpoint
+// is the real plain-HTTPS, non-api.github.com path that actually serves
+// repo content.
+function* tarEntryNames(buf) {
+  let offset = 0;
+  while (offset + 512 <= buf.length) {
+    const header = buf.subarray(offset, offset + 512);
+    if (header.every(b => b === 0)) break;
+    const name = header.subarray(0, 100).toString('utf-8').replace(/\0.*$/s, '');
+    const sizeOctal = header.subarray(124, 136).toString('utf-8').replace(/\0.*$/s, '').trim();
+    const size = parseInt(sizeOctal, 8) || 0;
+    if (name) yield name;
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+}
+
+async function discoverRemoteSkillNamesViaCodeload(timeoutMs) {
+  const url = `https://codeload.github.com/${SKILL_MD_REMOTE_REPO}/tar.gz/refs/heads/${SKILL_MD_REMOTE_BRANCH}`;
+  const gz = await httpGetBuffer(url, timeoutMs || 15000);
+  const tar = require('zlib').gunzipSync(gz);
+  const names = new Set();
+  for (const name of tarEntryNames(tar)) {
+    const m = /^[^/]+\/skills\/([^/]+)\/$/.exec(name);
+    if (m) names.add(m[1]);
+  }
+  if (names.size === 0) throw new Error('codeload tarball listing produced zero skill directories');
+  return Array.from(names);
+}
+
+// The GitHub Contents API this normally uses already fails soft (caller
+// falls back to bundled local skills), but a fully API-scope-restricted
+// environment (a corporate proxy or org policy blocking api.github.com
+// specifically) loses fresh remote skill discovery entirely even though
+// the same repo is reachable over codeload.github.com's plain-HTTPS
+// tarball endpoint -- a different host, no API token or REST surface.
 async function discoverRemoteSkillNames(timeoutMs) {
   const url = `https://api.github.com/repos/${SKILL_MD_REMOTE_REPO}/contents/skills?ref=${SKILL_MD_REMOTE_BRANCH}`;
-  const buf = await httpGetBuffer(url, timeoutMs || 5000);
-  const entries = JSON.parse(buf.toString('utf-8'));
-  if (!Array.isArray(entries)) throw new Error('unexpected github contents API response shape');
-  return entries.filter(e => e && e.type === 'dir' && e.name).map(e => e.name);
+  try {
+    const buf = await httpGetBuffer(url, timeoutMs || 5000);
+    const entries = JSON.parse(buf.toString('utf-8'));
+    if (!Array.isArray(entries)) throw new Error('unexpected github contents API response shape');
+    return entries.filter(e => e && e.type === 'dir' && e.name).map(e => e.name);
+  } catch (apiErr) {
+    try {
+      return await discoverRemoteSkillNamesViaCodeload(timeoutMs);
+    } catch (fallbackErr) {
+      obsEvent('bootstrap', 'discover-remote-skill-names.codeload-fallback-failed', { error: fallbackErr.message });
+      throw apiErr;
+    }
+  }
 }
 
 async function fetchRemoteSkillMd(skillName, timeoutMs) {
@@ -659,6 +724,42 @@ function installedVersionAtTools() {
   } catch (_) { return null; }
 }
 
+function compareDottedSemverAscending(a, b) {
+  const pa = a.replace(/^v/, '').split('.').map(Number);
+  const pb = b.replace(/^v/, '').split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+// Fallback when the Releases-list API is unreachable: git ls-remote can
+// see every tag over plain git protocol without touching api.github.com,
+// but cannot see release ASSETS -- so a tag it finds is verified against
+// a HEAD probe on the raw release-download URL for plugkit.wasm before
+// being trusted, matching the API path's own hasPlugkitWasm check.
+async function resolveLatestRemoteVersionViaGit(timeoutMs) {
+  const { execFileSync } = require('child_process');
+  const out = execFileSync('git', ['ls-remote', '--tags', '--refs', 'https://github.com/AnEntrypoint/plugkit-bin.git'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const tags = out.split('\n')
+    .map(line => line.match(/refs\/tags\/v(\d+\.\d+\.\d+(?:-[A-Za-z0-9.]+)?)$/))
+    .filter(Boolean)
+    .map(m => m[1]);
+  tags.sort(compareDottedSemverAscending);
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const version = tags[i];
+    try {
+      await httpHeadOk(`https://github.com/AnEntrypoint/plugkit-bin/releases/download/v${version}/plugkit.wasm`, timeoutMs || 3000);
+      return version;
+    } catch (_) { /* asset missing for this tag, try the next-newest */ }
+  }
+  return null;
+}
+
 async function resolveLatestRemoteVersion(timeoutMs) {
   try {
     const buf = await httpGetBuffer('https://api.github.com/repos/AnEntrypoint/plugkit-bin/releases?per_page=50', timeoutMs || 3000);
@@ -674,6 +775,12 @@ async function resolveLatestRemoteVersion(timeoutMs) {
     }
   } catch (e) {
     obsEvent('bootstrap', 'resolve-latest-remote-version.failed', { error: e.message });
+    try {
+      const viaGit = await resolveLatestRemoteVersionViaGit(timeoutMs);
+      if (viaGit) return viaGit;
+    } catch (gitErr) {
+      obsEvent('bootstrap', 'resolve-latest-remote-version.git-fallback-failed', { error: gitErr.message });
+    }
   }
   return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.2469",
+  "version": "2.0.2471",
   "description": "Bootstrap and daemon-spawn tool for gm plugkit binary. Downloads the correct platform wasm, verifies SHA256, and launches agentplug-runner (the native wasm host) as the spool watcher daemon.",
   "main": "index.js",
   "bin": {

package/plugkit.version

@@ -1 +1 @@
-0.1.1182
+0.1.1183