gm-skill 2.0.1867 → 2.0.1868

package/README.md

@@ -58,15 +58,14 @@ This repo IS the published `gm-skill` npm package. No build step, no factory. Th
 ```
 gm/
 |-- skills/gm/        <- the skill (SKILL.md), installed as /gm
-|-- bin/               <- bootstrap + plugkit launcher (gmsniff / ccsniff are separate npm packages, `bun x gmsniff`, `bun x ccsniff`)
-|-- lib/               <- runtime: spool dispatch, skill bootstrap, daemon mgmt
-|-- agents/            <- subagent prompts (gm, memorize, research-worker, textprocessing)
-|-- lang/              <- language packs (browser, ssh)
-|-- gm-plugkit/        <- separate npm package that ships the wasm-wrapper
+|-- bin/               <- bootstrap + installer + plugkit wasm pins (gmsniff / ccsniff are separate npm packages, `bun x gmsniff`, `bun x ccsniff`)
+|-- scripts/           <- publish-time helper scripts
+|-- gm-plugkit/        <- separate npm package that ships the wasm-wrapper + supervisor
 |-- gm.json            <- version + plugkit pin
 |-- package.json       <- npm publish manifest
 |-- AGENTS.md          <- architectural rules (present-tense, no history)
 |-- CHANGELOG.md       <- release history
+|-- docs/              <- long-form paper + crate/skill/distribution pages
 `-- site/              <- flatspace site source (built to dist/ by CI)
 ```
 
@@ -92,12 +91,14 @@ Every tool the agent uses is a dispatch verb. No direct shell, no direct file wr
 - **`git_status` / `branch_status` / `git_push`**: git verbs that gate on porcelain
 - **`filter`**: in-wasm stdout-compaction (grep/ls/tree/json/diff)
 
-### hooks
+### gates
 
-- **session-start**: bootstraps plugkit, seeds `.gm/next-step.md`, sets `needs-gm` marker
-- **prompt-submit**: reminds the agent to dispatch instruction first; injects per-prompt auto-recall
-- **pre-tool-use**: blocks tool use before the gm skill fires for the turn
-- **stop**: blocks session end while `.gm/prd.yml` has open items, mutables are unresolved, residual-scan hasn't fired, or the worktree is dirty
+Orchestration state is tracked via `.gm/` marker files, not hook events. The gate that admits Write/Edit/git pre-execution runs natively inside `plugkit.wasm` (rs-plugkit `gates.rs` + its `hook_pre_tool_use` / `hook_stop` exports), driven off the same markers:
+
+- **session-start**: bootstraps plugkit, seeds `.gm/next-step.md`, sets the `needs-gm` marker
+- **turn entry**: the `instruction` verb reminds the agent to dispatch first and attaches the per-prompt auto-recall pack
+- **pre-tool-use**: blocks Write/Edit/git before the gm skill fires for the turn
+- **stop**: blocks session end while `.gm/prd.yml` has open items, mutables are unresolved, residual-scan hasn't fired, or the worktree is dirty or unpushed
 
 ### ground truth
 

package/gm-plugkit/instructions/entry.md

@@ -71,7 +71,7 @@ Write `in/<lang>/<N>.<ext>` for language stems, `in/<verb>/<N>.txt` for orchestr
 
 ## SESSION_ID
 
-Thread SESSION_ID through every spool body + rs-exec RPC; plugkit rejects empty.
+Thread SESSION_ID through every spool body; plugkit rejects empty.
 
 ## Daemonize
 

package/gm-plugkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-plugkit",
-  "version": "2.0.1867",
+  "version": "2.0.1868",
   "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": {
@@ -12,7 +12,6 @@
     "index.js",
     "bootstrap.js",
     "supervisor.js",
-    "lang-host-runner.js",
     "plugkit-wasm-wrapper.js",
     "plugkit.version",
     "plugkit.sha256",

package/gm-plugkit/plugkit-wasm-wrapper.js

@@ -1049,18 +1049,6 @@ function resolveWindowsExeLocal(cmd) {
   }
 }
 
-function isPortReachableSync(host, port, timeoutMs) {
-  const r = spawnSync(process.execPath, ['-e', `
-    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); });
-    s.on('error', () => { if (!done) process.exit(1); });
-    setTimeout(() => { if (!done) { s.destroy(); process.exit(1); } }, ${timeoutMs || 800});
-  `], { timeout: (timeoutMs || 800) + 2000, windowsHide: true });
-  return r.status === 0;
-}
-
 function findFreePortSync() {
   const r = spawnSync(process.execPath, ['-e', `
     const net = require('net');
@@ -1072,17 +1060,6 @@ function findFreePortSync() {
   return parseInt(r.stdout.trim(), 10);
 }
 
-function isPortAliveSync(port) {
-  const r = spawnSync(process.execPath, ['-e', `
-    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));
-    setTimeout(() => process.exit(1), 800);
-  `], { timeout: 2000 });
-  return r.status === 0;
-}
-
 function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, ms | 0));
 }
@@ -4390,16 +4367,42 @@ async function runSpoolWatcher(instance, spoolDir) {
       // The window must therefore comfortably exceed the worst-case cold embed;
       // it is a one-time cost (the digest persists after a single completion,
       // so subsequent boots' warmup is near-instant).
-      _writeStatusBusy(1200000);
-      const vb = new TextEncoder().encode('codesearch');
-      const bb = new TextEncoder().encode(JSON.stringify({ query: 'index warmup', k: 1 }));
-      const vp = writeWasmInput(instance, vb, 'boot-warmup:codesearch.verb');
-      const bp = writeWasmInput(instance, bb, 'boot-warmup:codesearch.body');
+      // A single warmup dispatch only advances the index by one wall-budget
+      // slice, so a large repo needs many passes before the digest converges
+      // (deferred_files == 0). A single-shot warmup left the digest permanently
+      // withheld: every later verb and every respawn re-triggered a fresh
+      // partial pass, and the stale-digest boot path re-embedded from scratch
+      // forever. Loop the warmup, refreshing busy_until each pass so the
+      // supervisor's stale-heartbeat check never kills a converging rebuild,
+      // until deferred_files reaches 0 or a bounded pass count is hit.
       const t0 = Date.now();
-      const r = dispatch(vp, vb.length, bp, bb.length);
-      decodeWasmResult(instance, r, 'boot-warmup:codesearch');
+      let passes = 0;
+      let lastDeferred = -1;
+      let stagnant = 0;
+      const MAX_WARMUP_PASSES = 80;
+      while (passes < MAX_WARMUP_PASSES) {
+        _writeStatusBusy(1200000);
+        const vb = new TextEncoder().encode('codeinsight_index');
+        const bb = new TextEncoder().encode(JSON.stringify({ root: '.', max_files: 500 }));
+        const vp = writeWasmInput(instance, vb, 'boot-warmup:codeinsight_index.verb');
+        const bp = writeWasmInput(instance, bb, 'boot-warmup:codeinsight_index.body');
+        const r = dispatch(vp, vb.length, bp, bb.length);
+        const decoded = decodeWasmResult(instance, r, 'boot-warmup:codeinsight_index');
+        passes++;
+        let deferred = null;
+        try {
+          const parsed = typeof decoded === 'string' ? JSON.parse(decoded) : decoded;
+          const d = parsed && (parsed.data || parsed);
+          if (d && typeof d.deferred_files === 'number') deferred = d.deferred_files;
+          else if (parsed && typeof parsed.deferred_files === 'number') deferred = parsed.deferred_files;
+        } catch (_) {}
+        if (deferred === null) break;
+        if (deferred === 0) break;
+        if (deferred === lastDeferred) { stagnant++; if (stagnant >= 4) break; } else { stagnant = 0; }
+        lastDeferred = deferred;
+      }
       writeStatus();
-      logEvent('plugkit', 'boot.index-warmup', { ms: Date.now() - t0 });
+      logEvent('plugkit', 'boot.index-warmup', { ms: Date.now() - t0, passes, converged: lastDeferred === -1 || lastDeferred === 0 });
     } catch (e) {
       try { logEvent('plugkit', 'boot.index-warmup-failed', { error: String(e && e.message || e) }); } catch (_) {}
     }

package/gm.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.1867",
+  "version": "2.0.1868",
   "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.1867",
+  "version": "2.0.1868",
   "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",
@@ -30,14 +30,9 @@
   },
   "files": [
     "skills/",
-    "agents/",
-    "lib/",
-    "lang/",
     "scripts/",
     "bin/bootstrap.js",
     "bin/install.js",
-    "bin/gm-validate.js",
-    "bin/gm-shell-validate.js",
     "bin/plugkit.sha256",
     "bin/plugkit.version",
     "bin/plugkit.wasm.sha256",
@@ -45,7 +40,6 @@
     "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",

package/skills/gm/SKILL.md

@@ -72,7 +72,7 @@ Spool input from PowerShell must be UTF-8 no-BOM (`-Encoding utf8` or `[System.I
 
 **EXECUTE resolves all mutables before EMIT, discovers more, resolves those too, rearchitects immediately on in-spirit discovery.** Any architectural improvement discovered mid-EXECUTE is an immediate `transition to=PLAN`, re-`prd-add` the affected row with its existing id (re-scope, never delete-and-re-add) -- maximal-effort correctness over preservation-for-its-own-sake, no deferral, no "note for later."
 
-**`prd-resolve` is bound by the false-completion rule in every phase, PLAN included -- not only at VERIFY.** A row marked `status: completed` whose witness says "deferred", "pending next session", "pending browser fix", "awaits [X] recovery", "user must refresh", or any equivalent hedge is undone work labeled done -- forbidden, the same class as a mock standing in for real code. A genuinely external blocker (browser environment down, credential missing, another team's repo) keeps the row `status: pending` with `blockedBy: [external, "<specific reason>"]`; it is never grounds to resolve as completed. A blocker that recurs across sessions (the same tool crashing every attempt) becomes its own PRD row naming the tool defect to fix -- diagnose and repair it, never paper over the original row with a completed status while the real work stays undone.
+**`prd-resolve` is bound by the false-completion rule in every phase, PLAN included -- not only at VERIFY.** A row resolved on a hedge ("deferred", "pending next session", "awaits recovery") is undone work labeled done -- forbidden, the same class as a mock standing in for real code. The served PLAN/VERIFY `instruction` prose carries the full hedge taxonomy, the `blockedBy: [external, ...]` handling for genuine outside-session blockers, and the recurring-blocker-becomes-its-own-row rule; dispatch `instruction` for it rather than re-deriving it here.
 
 VERIFY is adversarial, never confirmatory: run the real code path and read its actual output via `exec_js` or `browser` -- a finding is only real once witnessed by execution this turn. Never assert a crash, pass, or defect from memory, prior session state, or written prose alone. A gate denial (e.g. `residual.skipped` on dirty worktree) is resolved immediately by the named recovery action (commit or revert the listed files, then re-dispatch the same verb) in the same turn -- it is never grounds to re-enter PLAN, add unrelated PRD rows, or narrate the blocker instead of clearing it.
 

package/agents/gm.md

@@ -1,22 +0,0 @@
----
-description: Agent (not skill) - immutable programming state machine. Always invoke for all work coordination.
-mode: primary
----
-
-# GM -- Skill-First Orchestrator
-
-**Invoke the `planning` skill immediately.** Use the Skill tool with `skill: "planning"`.
-
-**CRITICAL: Skills are invoked via the Skill tool ONLY. Do NOT use the Agent tool to load skills. Skills are not agents. Use: `Skill tool` with `skill: "gm"` (or `"planning"`, `"gm-execute"`, `"gm-emit"`, `"gm-complete"`, `"update-docs"`). Using the Agent tool for skills is a violation.**
-
-All work coordination, planning, execution, and verification happens through the skill tree:
-- `planning` skill -> `gm-execute` skill -> `gm-emit` skill -> `gm-complete` skill -> `update-docs` skill
-- `memorize` sub-agent -- background only, non-sequential. Invocation: `Agent(subagent_type='memorize', model='haiku', run_in_background=true, prompt='## CONTEXT TO MEMORIZE\n<what was learned>')`
-
-All code execution uses `exec:<lang>` via the Bash tool -- never direct `Bash(node ...)` or `Bash(npm ...)`.
-
-To send stdin to a running background task: `exec:type` with task_id on line 1 and input on line 2.
-
-Do not use `EnterPlanMode`. Do not run code directly via Bash. Invoke `planning` skill first.
-
-Responses to the user must be two sentences maximum, only when the user needs to know something, and in plain conversational language -- no file paths, filenames, symbols, or technical identifiers.

package/agents/memorize.md

@@ -1,100 +0,0 @@
----
-name: memorize
-description: Background memory agent. Classifies context and writes to AGENTS.md + rs-learn. No memory dir, no MEMORY.md.
----
-
-# Memorize -- Background Memory Agent
-
-Writes facts to two places only: **AGENTS.md** (non-obvious technical caveats) and **rs-learn** (all classified facts via fast ingest).
-
-Resolve at start of every run:
-
-- **Project root** = `process.cwd()` when invoked. `AGENTS.md` is `<project root>/AGENTS.md`.
-- **Reach check** = run `gh api repos/<owner>/<repo> --jq .permissions.push` on `<project root>`'s `git remote get-url origin`. Cache the answer for the run. If the result is anything other than literal `true` (false, no remote, non-github URL, gh CLI missing, gh not authed, repo private and inaccessible), the project is **out-of-reach**.
-
-## STEP 0: SCOPE GUARD -- DO NOT POLLUTE OUT-OF-REACH PROJECTS
-
-If the reach check returns out-of-reach:
-
-- **Do** ingest classified facts into rs-learn (Step 2) -- rs-learn is per-user, not per-project, so private notes about a project the user is reading-but-not-owning are safe there.
-- **Do not** read or edit `<project root>/AGENTS.md` (Step 3). Skip the file entirely.
-- **Do not** run the AGENTS.md <-> rs-learn migration audit (Step 4). The audit edits AGENTS.md.
-
-Reason: agents running in a cwd that points at a third-party repo (e.g. running Claude inside a checkout of `nousresearch/hermes-agent` while building a downstream port) must not write project-specific notes into the upstream project's AGENTS.md. That AGENTS.md belongs to the upstream maintainers. Personal porting notes belong in the user's downstream repo's AGENTS.md, or -- when the work spans multiple repos and there's no clean home -- in rs-learn only.
-
-When the reach check returns **in-reach**, proceed normally with all four steps below.
-
-## STEP 1: CLASSIFY
-
-Examine the ## CONTEXT TO MEMORIZE section at the end of this prompt. For each fact, classify as:
-
-- user: user role, goals, preferences, knowledge
-- feedback: guidance on approach -- corrections AND confirmations
-- project: ongoing work, goals, bugs, incidents, decisions
-- reference: pointers to external systems, URLs, paths
-
-Discard:
-- Obvious facts derivable from reading the code
-- Active task state or session progress
-- Facts that would not be useful in a future session
-
-## STEP 2: INGEST INTO RS-LEARN
-
-For each classified fact, invoke `exec:memorize` (HTTP-preferred, subprocess fallback -- fast either way):
-
-```
-exec:memorize
-<type>/<slug>
-<fact body -- one to three self-contained sentences>
-```
-
-Line 1 of the body is the source tag (e.g. `feedback/terse-responses`, `project/merge-freeze`). Lines 2+ are the fact itself. Use kebab-case slugs.
-
-A discipline sigil -- `@<name>` as the first space-token in the invoking prompt, or a trailing `discipline=<name>` line -- routes the write to that discipline's store. Without one, the write lands in the default store. Forward the sigil verbatim to `exec:memorize`; never invent or default a discipline name.
-
-To invalidate previously-memorized content (correction or retraction):
-
-```
-exec:forget
-by-source <tag>
-```
-
-Or by content:
-
-```
-exec:forget
-by-query <2-6 search words>
-```
-
-**CRITICAL: rs-learn failures must be explicit and recoverable.** If `exec:memorize` fails (socket unavailable, network error, timeout):
-1. Report the failure to the user with error details
-2. Fallback immediately to STEP 3 (AGENTS.md) to preserve the fact in the always-on context buffer
-3. Never proceed as if the write succeeded
-4. This contract ensures memory preservation when the rs-learn retrieval store is temporarily unavailable
-
-## STEP 3: AGENTS.md
-
-A non-obvious technical caveat qualifies if it required multiple failed runs to discover and would not be apparent from reading code or docs.
-
-For each qualifying fact from context:
-- Read AGENTS.md first if not already read this run
-- If AGENTS.md already covers it -> skip
-- If genuinely non-obvious -> append to the appropriate section
-
-Never add: obvious patterns, active task progress, redundant restatements.
-
-## STEP 4: AGENTS.md -> RS-LEARN MIGRATION (BENCHMARK + DRAIN)
-
-AGENTS.md is the **always-on context buffer** -- every prompt sees it. rs-learn is the **conditional retrieval store** -- only relevant facts surface. The migration loop turns AGENTS.md into a benchmark for rs-learn's recall quality:
-
-1. Pick **5 random items** from AGENTS.md (sections, paragraphs, or numbered points). Don't pick the most recent additions -- pick the oldest stable items.
-2. For each item, derive a 2-6 word query that a future agent would naturally use to find this fact.
-3. Run `exec:recall` with that query.
-4. Decide:
-   - **Recall accurate AND complete** -> the rs-learn store has internalized this fact; **remove it from AGENTS.md**. Frees buffer space and confirms learning.
-   - **Recall partial / outdated / missing** -> keep the AGENTS.md item AND ingest a refined version of the fact via `exec:memorize` so next round it can pass. Note the outcome in your run log.
-5. Report the audit cycle in the run output (items checked, removed, refined). Do not write the audit result to AGENTS.md -- it is changelog-shaped and AGENTS.md forbids dated audit sections.
-
-Why: AGENTS.md grows monotonically without this loop. rs-learn already filters by relevance per-prompt, so duplicating stable facts in AGENTS.md just inflates the always-on context. The migration drains AGENTS.md into the retrieval store as the store proves it can recall. Failed migrations leave the fact in AGENTS.md (safe default) and improve the store. Success rate over time = a metric for how well gm is learning this project.
-
-Don't migrate if the fact is genuinely about agent meta-behavior that must be active every prompt (e.g. "always invoke gm:gm first") -- those stay permanently.

package/agents/research-worker.md

@@ -1,36 +0,0 @@
----
-name: research-worker
-description: Focused single-thread web investigator. Spawned in parallel by the research skill. Owns one question, returns one path.
-agent: true
-allowed-tools: WebFetch, WebSearch, Bash
----
-
-# Research Worker
-
-One question. One context. One file on disk. One-line return.
-
-Two shapes of brief arrive: a live-web question owning a path under `.gm/research/<slug>/<worker-id>.md`, or a corpus chunk owning `.gm/disciplines/<name>/corpus/concise/<chunk-id>.md`. The corpus shape carries an input chunk on disk and a fact-preservation contract -- every claim, number, name, caveat, and citation from the source survives the rewrite; prose density rises, content does not shrink. No fetching unless the brief asks for it. The output file looks like the live-web one but the `Sources` section points at the input chunk path and any inline citations the chunk already carried.
-
-## Brief shape
-
-The spawning prompt names: the question, the answer shape expected, the explicit out-of-scope boundary, and the destination path `.gm/research/<slug>/<worker-id>.md`. If any of those is missing or ambiguous, treat that as the first finding -- record what was unclear and stop, rather than guessing scope.
-
-## Investigation
-
-Open with a `WebSearch` broad enough to map sources, narrow enough to exclude obviously off-topic results. Pick the two or three highest-quality hits -- primary docs, dated authored posts, RFCs, source repos -- and `WebFetch` each. Aggregator pages, content farms, and undated listicles are last resort, flagged as such when used.
-
-Stop fetching when the question is answered to the shape requested. Extra fetches past sufficiency burn tokens the orchestrator needs for synthesis.
-
-## Output
-
-Write the findings file with: the question restated, the answer in the requested shape, every non-trivial claim followed by `[source: <url>]` and a quoted span, a `Sources` section listing every URL touched with a one-line quality note, and an `Unresolved` section naming anything the brief asked for that the search did not yield.
-
-A claim without an inline source URL is a defect; remove it before writing the file.
-
-## Return
-
-Return only: the absolute path to the findings file, and a single sentence summarising the headline answer. Never return the full findings inline -- the orchestrator reads from disk.
-
-## Boundary
-
-Do not chase tangents that surface mid-investigation, however interesting. Note them in `Unresolved` so the orchestrator can decide whether to fan out a new worker. Stretching past the brief is the worker-side equivalent of the orchestrator skipping fan-out.

package/agents/textprocessing.md

@@ -1,47 +0,0 @@
----
-name: textprocessing
-description: Haiku-backed text processor. Takes a body of text and an instruction, returns the processed output. The required surface for any task whose correctness depends on understanding (summary, classify, extract, rewrite, translate, semantic dedup, score, label).
-agent: true
----
-
-# Textprocessing -- Haiku Language Processor
-
-The single surface for intelligent text transforms. Code does mechanics (count, split, regex, sort, dedup-by-equality); this agent does meaning (summary, classify, extract, rewrite, translate, semantic dedup, score, label).
-
-## INVOCATION
-
-```
-Agent(subagent_type='gm:textprocessing', model='haiku', prompt='## INPUT\n<body>\n\n## INSTRUCTION\n<task>')
-```
-
-`prompt` always carries both halves -- input under `## INPUT`, instruction under `## INSTRUCTION`. The agent reads both, performs the transform, returns the result as plain text or JSON per what the instruction asked for. No preamble, no commentary, no "here is your output" wrapper.
-
-## OUTPUT CONTRACT
-
-- Plain-text instruction -> plain-text output, no fences, no labels.
-- JSON instruction (e.g. "return as a JSON array of {id, label}") -> exactly that JSON, parseable by `JSON.parse`, no fences, no surrounding prose.
-- Multi-document input requested as a list -> one entry per input doc in the same order, no skips.
-
-If the instruction is ambiguous about the output shape, default to plain text. If the input is empty, return empty output (empty string or `[]` for JSON).
-
-## BATCH PATTERN
-
-N independent items -> N parallel `Agent(textprocessing)` calls in ONE message, each with its own item under `## INPUT`. Never serialize independent items. The runner collects results and assembles the batch.
-
-For one large body that exceeds a single-prompt budget: the *caller* chunks the body deterministically (paragraph, section, fixed-token) and fans out one Agent call per chunk in parallel, then merges. The agent itself does not chunk; it processes whatever it receives in one shot.
-
-## DISCIPLINE
-
-Code for mechanics, agent for meaning.
-
-- Mechanics (use code): char/word/token count, byte length, split on delimiter, exact-string find/replace, regex match/extract, sort, group-by-key, dedup-by-equality, lowercase/uppercase, JSON parse/stringify, base64, URL encode.
-- Meaning (use this agent): summarize, classify, extract entities/intents, rewrite for tone/audience, translate, semantic dedup (same meaning, different words), rank/score by quality, label by topic, decide if two texts are "about the same thing", paraphrase, simplify, expand outline -> prose.
-
-A loop in code that "checks if this string contains certain meaning" via keyword lists is a stub of this agent. Replace it with one Agent call (or N parallel ones) per item.
-
-## CONSTRAINTS
-
-- Model is fixed at `haiku` -- fast, cheap, sufficient for transform tasks. Escalate to opus only when the agent's haiku output fails an acceptance check, never preemptively.
-- No tools beyond Read/Write -- the agent processes text it receives, optionally reads/writes chunks for multi-pass jobs. Never spawns subagents.
-- Background-spawnable: `run_in_background=true` for fire-and-forget batch processing where the caller polls results later.
-- Idempotent: same input + same instruction -> same output (modulo haiku sampling noise). Callers needing deterministic output specify `temperature=0` in the prompt.

package/bin/gm-shell-validate.js

@@ -1,143 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const cp = require('child_process');
-const os = require('os');
-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); }
-function which(cmds) {
-  for (const cmd of cmds) {
-    try {
-      const out = cp.execFileSync('where.exe', [cmd], { encoding: 'utf8', windowsHide: true }).split(/\r?\n/).filter(Boolean);
-      if (out[0]) return out[0];
-    } catch (_) {}
-  }
-  return '';
-}
-
-async function renderPreview() {
-  const preview = fs.mkdtempSync(path.join(os.tmpdir(), 'gm-shell-preview-'));
-  fs.mkdirSync(path.join(preview, 'vendor'), { recursive: true });
-  fs.cpSync(path.join(ROOT, 'site', 'vendor'), path.join(preview, 'vendor'), { recursive: true });
-
-  const renderScript = `
-    import { writeFileSync } from 'fs';
-    import { resolve } from 'path';
-    const mod = await import(${JSON.stringify(pathToFileURL(path.join(ROOT, 'site', 'theme.mjs')).href)});
-    const ctx = {
-      readGlobal: (k) => {
-        if (k === 'site') return { title: 'gm', tagline: "more coushin' for the pushin'", description: 'local browser OS surface', glyph: 'g', accent_from: '#7ee787', accent_to: '#56d364' };
-        if (k === 'navigation') return { links: [{ label: 'Home', href: '/' }, { label: 'Paper', href: '/paper/' }, { label: 'Stats', href: '/stats/' }, { label: 'Crates', href: '/crates/' }, { label: 'Skills', href: '/skills/' }] };
-        return null;
-      },
-      read: (k) => {
-        if (k === 'pages') return { docs: [{ id: 'home', title: 'gm', layout: 'landing', hero: { heading: 'gm', body: 'local browser OS surface', subheading: 'predictable panes and local vendors', ctas: [{ label: 'Open docs', href: '/paper/', primary: true }], badges: [{ label: 'local' }, { label: 'xstate' }] }, features: { heading: 'features', items: [{ name: 'A', desc: 'a' }, { name: 'B', desc: 'b' }, { name: 'C', desc: 'c' }, { name: 'D', desc: 'd' }] }, examples: { heading: 'docs', items: [{ name: 'Doc', desc: 'd', href: '/paper/', cta: 'open' }] }, quickstart: { lines: [{ kind: 'cmd', text: 'npm run build' }, { kind: 'cmd', text: 'npm start' }] } }] };
-        return null;
-      }
-    };
-    const out = await mod.default.render(ctx);
-    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, env: { ...process.env, GM_SHELL_PREVIEW: preview } });
-  try { fs.unlinkSync(tmp); } catch (_) {}
-
-  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, serverPid: server.pid };
-}
-
-function killServer(pid) {
-  if (!pid) return;
-  try {
-    if (process.platform === 'win32') cp.execFileSync('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore', windowsHide: true });
-    else process.kill(pid, 'SIGTERM');
-  } catch (_) {}
-}
-
-async function main() {
-  const { preview, port, serverPid } = await renderPreview();
-  try {
-  const witness = path.join(os.tmpdir(), `gm-shell-witness-${Date.now()}.js`);
-  const witnessOut = path.join(WITNESS_DIR, `gm-shell-${Date.now()}.json`);
-  write(witness, `
-await page.goto('http://127.0.0.1:${port}/');
-await page.waitForLoadState('domcontentloaded');
-await page.waitForTimeout(500);
-const before = await page.evaluate(() => ({
-  app: window.__debug.gm.app(),
-  activeSurface: document.querySelector('[data-app-surface]:not([hidden])')?.dataset.appSurface || null,
-  activeAppCopy: document.getElementById('active-app-copy')?.textContent || ''
-}));
-await page.evaluate(() => { const btn = document.querySelectorAll('[data-app]')[1]; if (btn) btn.click(); });
-await page.waitForTimeout(300);
-const after = await page.evaluate(() => ({
-  app: window.__debug.gm.app(),
-  activeSurface: document.querySelector('[data-app-surface]:not([hidden])')?.dataset.appSurface || null,
-  activeAppCopy: document.getElementById('active-app-copy')?.textContent || ''
-}));
-const result = { before, after };
-return JSON.stringify(result);
-`);
-
-  const script = fs.readFileSync(witness, 'utf8');
-  const relayPort = Number(process.env.PLAYWRITER_PORT) || 19988;
-  const relayUrl = `http://127.0.0.1:${relayPort}/cli/execute`;
-  const response = await fetch(relayUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    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 || '';
-  console.log(out.trim());
-  if (!response.ok || result.isError) {
-    throw new Error(out || `browser witness failed (${response.status})`);
-  }
-  fs.mkdirSync(WITNESS_DIR, { recursive: true });
-  let parsed = null;
-  const m = out.match(/\[return value\]\s*(\{[\s\S]*\})\s*$/);
-  if (m) {
-    try { parsed = JSON.parse(m[1]); } catch (_) {}
-  }
-  if (!parsed) {
-    try {
-      const raw = fs.readFileSync(witnessOut, 'utf8');
-      parsed = JSON.parse(raw);
-    } catch (_) {}
-  }
-  fs.writeFileSync(witnessOut, JSON.stringify({ preview, port, output: out.trim(), parsed }, null, 2));
-  try { fs.unlinkSync(witness); } catch (_) {}
-  rmrf(preview);
-  } finally {
-    killServer(serverPid);
-  }
-}
-
-main().catch((e) => {
-  console.error(e && e.stack || String(e));
-  process.exit(1);
-});