gm-plugkit 2.0.2466 → 2.0.2468

package/SKILL.md

@@ -6,21 +6,17 @@ allowed-tools: Skill, Read, Write, AskUserQuestion, Bash(bun *), Bash(npx *), Ba
 
 # gm
 
-**The conversation literally stops the instant a response contains no tool call -- this is the entire mechanism, not a guideline to remember.** Nothing external enforces continuation; the only thing that keeps this session alive turn after turn is that every single response contains a dispatch. The moment a response is prose alone -- a summary, a "here's what I did," a "Session N closes, ready to resume with /gm," a recap of architecture decisions made, a list of what's left for "next time" -- that response IS the final message of the conversation. There is no next turn where the user re-prompts and work resumes; from the model's own vantage point mid-generation, writing that closing summary is indistinguishable from ending the conversation permanently, because it has the exact same effect. So: never compose a closing/summary/"standing work ready" sentence as the last thing in a response -- if the work in front of you feels finished, the correct final action is still a dispatch (the next verb, or `Skill(skill="gm-continue")` if genuinely `phase=COMPLETE AND prd_pending_count=0`), never a sentence describing that it's finished. A turn-final sentence naming the next move instead of taking it is the same stop -- take the move, don't narrate it. **A question asking permission to take the next move ("Should I dispatch X now?", "Ready to proceed -- want me to continue?") is the identical stop, worded as a question instead of a narration.** Standing approval already covers this turn's work (see below) -- dispatch the named verb instead of asking whether to. Decisions worth surfacing to the user go through `AskUserQuestion` (a real ambiguity with distinct answers) or `prd-add` (a discovered row), never a prose question about whether to continue the already-authorized chain.
+**The conversation literally stops the instant a response contains no tool call -- this is the entire mechanism, not a guideline to remember.** Nothing external enforces continuation; the only thing that keeps this session alive turn after turn is that every single response contains a dispatch. The moment a response is prose alone -- a summary, a "here's what I did," a "Session N closes, ready to resume with /gm," a recap of architecture decisions made, a list of what's left for "next time" -- that response IS the final message of the conversation. There is no next turn where the user re-prompts and work resumes; from the model's own vantage point mid-generation, writing that closing summary is indistinguishable from ending the conversation permanently, because it has the exact same effect. So: never compose a closing/summary/"standing work ready" sentence as the last thing in a response -- if the work in front of you feels finished, the correct final action is still a dispatch (the next verb, or `Skill(skill="gm-continue")` if genuinely `phase=COMPLETE AND prd_pending_count=0`), never a sentence describing that it's finished. A turn-final sentence naming the next move instead of taking it is the same stop -- take the move, don't narrate it. Standing approval already covers this turn's work (see below) -- always dispatch the named verb next till the workflow is complete. Decisions about scope expansions or `prd-add` (a discovered row) are approved.
 
-**A verification or reproduction step that appears to require a human is first a build task, not an ask.** `AskUserQuestion`'s "real ambiguity with distinct answers" scope above does not cover "please perform an action so I can observe the result" -- physically pressing a button, turning a physical knob, listening to real audio, operating hardware the session has no other channel to. That is a missing channel, not an ambiguity, and the missing channel is itself a PRD row: attempt to build or reuse an automated substitute that exercises the same code path without the human before asking. For hardware I/O this means byte-level injection at the lowest available interface (e.g. writing raw MIDI note-on/note-off bytes directly to the device's rawmidi/ALSA node over the same SSH channel already used to pull logs, replaying a captured byte sequence from prior logs, or scripting the exact protocol messages the physical action would have produced) rather than asking a human to reproduce the input by hand. Only fall back to `AskUserQuestion` for the physical step once the substitute has genuinely been attempted and either (a) is provably impossible for this bug class -- the defect depends on analog qualities a byte-level or protocol-level injection cannot reproduce (audible sound quality, real timing jitter/debounce, genuine electrical behavior) -- or (b) the human has explicitly stated they want to check by ear/feel themselves. A repeated commit-push-CI-flash-then-ask cycle where the "ask" step is always the identical physical action and no substitute was ever attempted is itself a deviation-shaped pattern: the second occurrence of the same physical-action ask in one session is the signal to stop and build the harness instead of asking a third time.
+**`gm` must end by calling `gm-continue` which dispatches the finishing procedure; there is no other exit.** At genuine `phase=COMPLETE AND prd_pending_count=0`, the only allowed next step is dispatching `Skill(skill="gm-continue")` as the literal last tool call of the turn -- (reaching COMPLETE earlier in a turn does not license a prose-only response afterward -- the Skill dispatch belongs in that same turn, immediately).
 
-**`gm` is only allowed to end by calling `gm-continue`; there is no other exit.** At genuine `phase=COMPLETE AND prd_pending_count=0`, the only allowed next step is dispatching `Skill(skill="gm-continue")` as the literal last tool call of the turn -- never a bare prose ending, never a stop for the user to re-prompt, and never a prose summary followed by no further dispatch (reaching COMPLETE earlier in a turn does not license a prose-only response afterward -- the Skill dispatch belongs in that same turn, immediately). This is absolute: no branch of `gm`'s own logic, no phase, no gate response ever authorizes ending a `gm`-driven turn any other way. Do not inline `gm-continue`'s remaining-work search or its `gm`/`wfgy-method` decision here or improvise around it -- dispatch the skill and follow exactly what it does.
+**plugkit provides our completion checks** If uncertain what's next, dispatch `phase-status`, read the phase, then keep walking -- "uncertain" is never grounds to stop.
 
-**Done is plugkit's word, never yours.** COMPLETE gate is the sole arbiter; not-COMPLETE = a next transition to seek, never a stopping point. Idle mid-chain is a deviation, not a pause. If uncertain what's next, dispatch `phase-status`, read the phase, then keep walking -- "uncertain" is never grounds to stop.
+**Standing approval: finish everything, max granularity.** Every session is approved through requested work -- our policy is to plan, every addition, every discovered/unfinished item. We add prds insted of deferring work. If a walk is long, SPECIFY pushes more rows and PROVE/EMIT keep walking them, session after session if needed, never pausing to ask which subset to attempt first. Decide to always: proceed with the full scope, never the partial one. PRD rows are in `.gm/prd.yml`; a long task means MORE rows pushed onto SPECIFY as work is discovered, never fewer turns spent working. An apparent external blocker (a crashing tool, a down service, a missing peice, another team's repo) is an indication to add more prds and expand scope, making the most sensible choices along the way about replacing the problematic content with something that works, retry/escalate/route around, open the cross-repo change. `blockedBy` may only transiently carry the concrete reach action forward while it is being built.
 
-**Standing approval: finish everything, max granularity, no budget constraints.** Every session is pre-approved through ALL requested work -- plan, every addition, every discovered/unfinished item. No stop-and-ask, no deferral, no narrowed slice. Effort is unbounded and never gated on cost, context window, session length, or "budget" of any kind -- there is no such thing as running out mid-cycle in a way that authorizes stopping; if a walk is long, SPECIFY pushes more rows and PROVE/EMIT keep walking them, session after session if needed, never pausing to ask which subset to attempt first. A prompt offering the user a menu of "compressed/deferred/partial" options gated on running out of budget is itself the deviation -- make the decision yourself (always: proceed with the full scope, never the partial one) and dispatch, don't present it as a choice. PRD rows are in `.gm/prd.yml`; a long-horizon task means MORE rows pushed onto SPECIFY as work is discovered, never fewer turns spent working. **Everything is fixable; `blockedBy: external` is not a solution path.** An apparent external blocker (a crashing tool, a down service, a missing credential, another team's repo) is a row to BUILD PAST -- drive the crashing tool's protocol directly, spawn your own instance, retry/escalate/route around, script the credential path, open the cross-repo change. It is never a resting state that closes a turn, never a way to shrink the row count for large/complex/multi-step work; `blockedBy` may only transiently carry the concrete reach action forward while it is being built. The canonical "external" case this codebase carried for months (the playwriter browser crash) was fixed by driving Chrome's CDP endpoint directly -- proof these blockers are reachable, not terminal.
+The next action is determined solely by phase + PRD state, identically whether 500k tokens or 500 remain. If you catch yourself estimating/citing a remaining-token number for any reason, that estimate itself is the drift signal -- discard the framing entirely and re-derive the next action from `phase`/`prd_pending_count` alone. Real per-row witnessing (one `exec_js`/`browser` dispatch per row, actually reading its output) is mandatory regardless of how many rows remain or how much context is left; a batch `prd-resolve` for N rows justified by "given the budget" is `deviation.prd-resolve-duplicate-witness`-shaped even when each id is individually correct, because the underlying witnesses were never separately produced.
 
-**Naming a token/context count as a reason to change behavior is itself the deviation, full stop -- this applies even while reasoning, not only in the final message.** "32k remaining," "fast-track, no delays," "due to token constraints, finalizing immediately," "given the budget, batch/skip/compress X" -- any of these phrases appearing ANYWHERE in a turn (thinking, prose, or tool-call rationale) is the exact failure this rule exists to name, independent of whether the actions taken afterward look reasonable. There is no quantity of remaining context that changes what you do next; the next action is determined solely by phase + PRD state, identically whether 500k tokens or 500 remain. If you catch yourself estimating/citing a remaining-token number for any reason, that estimate itself is the drift signal -- discard the framing entirely and re-derive the next action from `phase`/`prd_pending_count` alone. This is not a softer version of "no budget constraints" above; it is the same rule restated at the point where it actually breaks -- the rule was violated last not through an explicit stated stop, but through invoking the concept as live context for a decision (batching resolves, skipping witnesses, "fast-tracking" a chain) while still taking real dispatch actions. Real per-row witnessing (one `exec_js`/`browser` dispatch per row, actually reading its output) is mandatory regardless of how many rows remain or how much context is left; a batch `prd-resolve` for N rows justified by "given the budget" is `deviation.prd-resolve-duplicate-witness`-shaped even when each id is individually correct, because the underlying witnesses were never separately produced.
-
-**No task is bounded; "out of scope" naming a real, reachable piece of work must never occur.** A task's actual scope is whatever its closure requires, not whatever fits some assumed limit -- when a row turns out bigger/harder/more multi-part than first estimated, the fix is fitting the bound to the task (more PRD rows, more turns, more sessions if genuinely needed), never fitting the task to an assumed bound by declaring part of it "out of scope," "future work," or "not yet implemented." A design doc describing what a reachable piece of work would look like, in place of doing that work, is the same deviation named above (documenting instead of implementing) wearing the "scoping" costume -- catch it the same way: if it's reachable this session, it is in scope by definition, full stop.
-
-**A gate denied the same way 3+ times in a row is a stuck loop, not a retry target.** Retrying the identical `transition`/verb after an unchanged denial repeats the same failure -- plugkit's own gate response names this explicitly (`stuck-loop-escalation`) once it detects the repeat. On that signal, or on noticing it yourself: stop retrying bare, `prd-add` a row naming the concrete stuck state (what's blocking, what you tried, why it didn't clear), invoke the `wfgy-method` skill's BBCR bounded-retry-then-surface discipline to recover with a checkpoint instead of blind-retrying, then re-attempt the transition once the actual blocker is cleared.
+**No task is bounded; The fix is fitting the bound to the task (more PRD rows, more turns, more sessions if genuinely needed), never fitting the task to an assumed bound by declaring part of it "out of scope," "future work," or "not yet implemented." We don't want ideas for future work in the project when finished, all plans must go through the process of becoming a prd and being executed, leaving no other artifacts.
 
 **A fresh session entering a repo already mid-chain checks for a recent `stuck-loop-escalation` or repeated `prd-resolve-unknown-id` before repeating the same fix shape.** If a prior session hit either (guessing at ids never `prd-add`ed this chain, or retrying the same denied transition), the actual PRD rows and their real ids are on disk in `.gm/prd.yml` -- read them directly rather than assuming remembered ids from context are still correct. Re-`prd-add`ing a row under a slightly different id because the original is unknown/forgotten creates an orphaned duplicate; when uncertain of a row's real id, `codesearch`/`recall`/direct `.gm/prd.yml` read settles it, never a guess-and-hope `prd-resolve`.
 

package/bootstrap.js

@@ -792,6 +792,95 @@ function getBinaryPath() {
   return getWasmPath();
 }
 
+function agentplugRunnerAssetName() {
+  const plat = process.platform;
+  const arch = process.arch;
+  if (plat === 'win32') {
+    if (arch === 'x64') return 'agentplug-runner-windows-x64.exe';
+    if (arch === 'arm64') return 'agentplug-runner-windows-arm64.exe';
+    return null;
+  }
+  if (plat === 'darwin') {
+    if (arch === 'x64') return 'agentplug-runner-macos-x64';
+    if (arch === 'arm64') return 'agentplug-runner-macos-arm64';
+    return null;
+  }
+  if (plat === 'linux') {
+    if (arch === 'x64') return 'agentplug-runner-linux-x64';
+    if (arch === 'arm64') return 'agentplug-runner-linux-arm64';
+    return null;
+  }
+  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;
+}
+
+function latestAgentplugRunnerTagViaGitLsRemote() {
+  const { execFileSync } = require('child_process');
+  const out = execFileSync('git', ['ls-remote', '--tags', '--refs', 'https://github.com/AnEntrypoint/agentplug-bin.git'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const tags = out.split('\n')
+    .map(line => line.match(/refs\/tags\/(.+)$/))
+    .filter(Boolean)
+    .map(m => m[1]);
+  if (tags.length === 0) return null;
+  tags.sort(compareDottedSemverAscending);
+  return tags[tags.length - 1];
+}
+
+// The sole loader has to exist before startSpoolDaemon can do anything --
+// a project that never ran `gm-skill install` (or whose install predates
+// agentplug-runner) hit a hard "not installed" failure here even though
+// the sha256-verified download this needs is the same one bin/install.js
+// already performs. Attempting it inline means a bare `spool` boot recovers
+// on its own instead of requiring a separate manual install step first.
+async function ensureAgentplugRunnerInstalled(destPath) {
+  const assetName = agentplugRunnerAssetName();
+  if (!assetName) return false;
+  const destDir = gmToolsDir();
+  try {
+    let tag;
+    try {
+      const releaseInfo = JSON.parse((await httpGetBuffer('https://api.github.com/repos/AnEntrypoint/agentplug-bin/releases/latest', 15000)).toString('utf8'));
+      tag = releaseInfo && releaseInfo.tag_name;
+    } catch (apiErr) {
+      try {
+        tag = latestAgentplugRunnerTagViaGitLsRemote();
+      } catch (_) {
+        return false;
+      }
+    }
+    if (!tag) return false;
+    const base = `https://github.com/AnEntrypoint/agentplug-bin/releases/download/${tag}`;
+    const [binBuf, shaBuf] = await Promise.all([
+      httpGetBuffer(`${base}/${assetName}`, 60000),
+      httpGetBuffer(`${base}/${assetName}.sha256`, 15000),
+    ]);
+    const expectedSha = shaBuf.toString('utf8').trim().split(/\s+/)[0];
+    const actualSha = sha256Hex(binBuf);
+    if (!expectedSha || actualSha.toLowerCase() !== expectedSha.toLowerCase()) 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(path.join(destDir, 'agentplug-runner.version'), tag);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
 function startSpoolDaemon() {
   try {
     const runnerName = process.platform === 'win32' ? 'agentplug-runner.exe' : 'agentplug-runner';
@@ -805,6 +894,7 @@ function startSpoolDaemon() {
           `which downloads the sha256-verified native runner from AnEntrypoint/agentplug-bin for this platform ` +
           `(${process.platform}/${process.arch}). If no binary is published for this platform yet, there is no ` +
           `loader available -- file an issue at https://github.com/AnEntrypoint/agentplug-bin so a binary is built for it.`,
+        needsRunnerInstall: true,
       };
     }
     const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -846,6 +936,7 @@ module.exports = {
   getWasmPath,
   getBinaryPath,
   startSpoolDaemon,
+  ensureAgentplugRunnerInstalled,
   isReady,
   cacheRoot,
   obsEvent,

package/cli.js

@@ -5,7 +5,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const cp = require('child_process');
-const { ensureReady, startSpoolDaemon, gmToolsDir, readVersionFile, ensureGmPlugkitVersionFresh, ensureSkillMdFresh, isReady, getWasmPath, readPinnedGmPlugkitVersion, spawnPinnedBoot, resolveProjectRoot } = require('./bootstrap');
+const { ensureReady, startSpoolDaemon, ensureAgentplugRunnerInstalled, gmToolsDir, readVersionFile, ensureGmPlugkitVersionFresh, ensureSkillMdFresh, isReady, getWasmPath, readPinnedGmPlugkitVersion, spawnPinnedBoot, resolveProjectRoot } = require('./bootstrap');
 const { pidAliveSync, waitForPidDeath } = require('./gm-process');
 
 function getWasmPathSafe() {
@@ -24,7 +24,7 @@ function spawnBackgroundFreshnessCheck(reason) {
   } catch (_) {}
 }
 
-function spawnDaemonOrExit(version, binaryPath, message) {
+async function spawnDaemonOrExit(version, binaryPath, message) {
   let daemon;
   try {
     daemon = startSpoolDaemon();
@@ -33,6 +33,21 @@ function spawnDaemonOrExit(version, binaryPath, message) {
     console.error('Daemon start failed:', err.message);
     process.exit(1);
   }
+  if (daemon && !daemon.ok && daemon.needsRunnerInstall) {
+    const runnerName = process.platform === 'win32' ? 'agentplug-runner.exe' : 'agentplug-runner';
+    const runnerPath = path.join(gmToolsDir(), runnerName);
+    console.error('agentplug-runner not found -- attempting sha256-verified download from AnEntrypoint/agentplug-bin before failing...');
+    const installed = await ensureAgentplugRunnerInstalled(runnerPath);
+    if (installed) {
+      try {
+        daemon = startSpoolDaemon();
+      } catch (err) {
+        writeCliError('start-daemon', err);
+        console.error('Daemon start failed:', err.message);
+        process.exit(1);
+      }
+    }
+  }
   if (!daemon || !daemon.ok) {
     const errMsg = (daemon && daemon.error) || 'startSpoolDaemon returned non-ok';
     writeCliError('start-daemon', new Error(errMsg));
@@ -207,7 +222,7 @@ function tryDelegateToRunner(args) {
     try { installedVersion = readVersionFile(); } catch (_) { installedVersion = null; }
     writeCliStatus({ phase: 'bootstrapped', version: installedVersion, binary: getWasmPathSafe() });
     spawnBackgroundFreshnessCheck(versionDrifted ? 'version-drift-respawn' : 'fast-path-spawn');
-    spawnDaemonOrExit(
+    await spawnDaemonOrExit(
       installedVersion,
       getWasmPathSafe(),
       'plugkit daemon spawned from existing local install, not yet confirmed serving -- check .gm/exec-spool/.status.json for heartbeat freshness; remote freshness check running in background'
@@ -231,7 +246,7 @@ function tryDelegateToRunner(args) {
   }
 
   writeCliStatus({ phase: 'bootstrapped', version: bootstrapResult.version, binary: bootstrapResult.binaryPath });
-  spawnDaemonOrExit(
+  await spawnDaemonOrExit(
     bootstrapResult.version,
     bootstrapResult.binaryPath,
     'plugkit daemon spawned, not yet confirmed serving -- check .gm/exec-spool/.status.json for heartbeat freshness'

package/package.json

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