feat(#2102): make pi a first-class installable runtime + fix its dispatch (ADR-1239)

Net-new EoS/pi installable runtime — purely additive (no prior runtime==='pi'
branches). pi is a bun-runtime programmatic-CLI whose /gsd command is registered
by a native ExtensionAPI extension and dispatches through the embedded engine.

Stage 1 (install plumbing):
- capabilities/pi/capability.json: full hostIntegration descriptor (imperative /
  slash-programmatic / active-model / native-extension / bun) + hostBehaviors
  {nativePlugin, pluginOnlyInstall}.
- --pi flag + interactive-menu renumber (All 17->18); pi added to RUNTIME_FLAG_IDS,
  RUNTIME_LABELS, RUNTIME_META, allRuntimes/runtimeMap, model-catalog defaults.
- Install mirrors OpenCode: pi installs the gsd.cjs extension + the shared engine
  payload (gsd-core + scripts + config markers) + the shared hooks bundle (spawned
  by the extension at lifecycle events, like OpenCode's plugin). pluginOnlyInstall
  EXCLUDES declarative command/agent/skill markdown, which pi has no host-read
  surface for (its /gsd is programmatic). _installNativePluginIfDeclared (extracted
  from the opencode-family path) copies pi/gsd.cjs -> ~/.pi/agent/extensions/gsd.cjs
  (global) / .pi/extensions/ (local). pi added to package.json files.
- Golden: new pi.json (320 files: extension + engine + 27-file hooks bundle, no
  markdown); the 16 other fixtures + claude-local change only by the shared
  model-catalog hash line.

Stage 2 (real dispatch + upgrades):
- Shared dispatchGsdCommand() (shell-command-projection): bounded, no-throw
  subprocess-shim to gsd-tools.cjs (the only full-surface dispatch path; no
  in-process full-hub factory exists). Fixes pi/gsd.cjs's createHub()-no-args bug
  (every dispatch was UnknownCommand) AND the identical bug in mcp-server.cts's
  gsd_invoke_command, which a vacuous unknown-family-only test had masked (now has
  a real dispatch regression test).
- pi/gsd.cjs: /gsd handler now (args, ctx) - tokenizes (quote-aware, via the
  shipped hooks/lib/git-cmd.js) + dispatches real family/subcommand (not hardcoded
  query/help); gsd_invoke gets a TypeBox (JSON-schema-fallback) parameters schema +
  consumes params; getArgumentCompletions; before_provider_request active-model
  steering (fail-open on null resolution); functional session_start /
  before_agent_start / session_before_compact hook bridges (spawn the shipped GSD
  hook scripts).
- EXTENSION_EVENT_SURFACES.pi expanded from ['tool_call'] to the full 30-event
  vocabulary.

Docs (host-integration matrix + how-to) + changeset (Added).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/shell-command-projection-dispatch.test.cjs

@@ -14,6 +14,8 @@ const {
   platformWriteSync,
   platformReadSync,
   platformEnsureDir,
+  dispatchGsdCommand,
+  resolveGsdToolsPath,
 } = require(path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'shell-command-projection.cjs'));
 
 const { createTempGitProject, createTempDir, cleanup } = require('./helpers.cjs');
@@ -99,6 +101,78 @@ describe('execTool', () => {
   });
 });
 
+// ─── dispatchGsdCommand (#2102 Stage 2 — subprocess-shim dispatch to gsd-tools.cjs) ──
+//
+// The command-routing hub (`createHub()`) has no fully-populated factory
+// anywhere in the tree — every caller builds a single-family hub — so the
+// only dispatch path covering the FULL family/subcommand surface is the
+// gsd-tools.cjs CLI itself. This is the shared helper pi/gsd.cjs and the
+// companion MCP server both dispatch through.
+
+describe('dispatchGsdCommand', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanup(tmpDir); });
+
+  test('resolveGsdToolsPath resolves to the real gsd-tools.cjs on disk', () => {
+    const toolsPath = resolveGsdToolsPath();
+    assert.ok(fs.existsSync(toolsPath), `expected gsd-tools.cjs to exist at ${toolsPath}`);
+    assert.equal(path.basename(toolsPath), 'gsd-tools.cjs');
+  });
+
+  test('a valid read-only family/subcommand dispatches for real and returns ok:true + non-empty stdout', () => {
+    const result = dispatchGsdCommand({ family: 'progress', subcommand: 'json', cwd: tmpDir });
+    assert.equal(result.ok, true, `expected ok:true, got: ${JSON.stringify(result)}`);
+    assert.equal(typeof result.stdout, 'string');
+    assert.ok(result.stdout.length > 0, 'stdout must be non-empty');
+    const parsed = JSON.parse(result.stdout);
+    assert.equal(typeof parsed.percent, 'number', 'the real progress command ran (proves the engine was reached)');
+    assert.equal(result.code, 0);
+    assert.equal(result.timedOut, false);
+  });
+
+  test('an unknown family returns ok:false without throwing', () => {
+    assert.doesNotThrow(() => {
+      const result = dispatchGsdCommand({ family: 'no-such-family-8675309', cwd: tmpDir });
+      assert.equal(result.ok, false);
+      assert.notEqual(result.code, 0);
+      assert.equal(typeof result.stderr, 'string');
+      assert.ok(result.stderr.length > 0);
+      // --json-errors gives a structured, parseable error envelope.
+      const parsedErr = JSON.parse(result.stderr);
+      assert.equal(parsedErr.ok, false);
+    });
+  });
+
+  test('a missing/bogus gsd-tools.cjs path degrades to ok:false without throwing', () => {
+    assert.doesNotThrow(() => {
+      const result = dispatchGsdCommand({
+        family: 'progress',
+        cwd: tmpDir,
+        gsdToolsPath: path.join(tmpDir, 'definitely-not-a-real-gsd-tools-8675309.cjs'),
+      });
+      assert.equal(result.ok, false);
+      assert.equal(result.timedOut, false);
+    });
+  });
+
+  test('a missing/empty "family" is rejected locally without spawning a subprocess', () => {
+    const result = dispatchGsdCommand({ cwd: tmpDir });
+    assert.equal(result.ok, false);
+    assert.equal(result.code, null);
+    assert.match(result.stderr, /requires a non-empty string "family"/);
+  });
+
+  test('a wall-clock timeout is reported via timedOut:true, ok:false — never throws', () => {
+    assert.doesNotThrow(() => {
+      const result = dispatchGsdCommand({ family: 'progress', subcommand: 'json', cwd: tmpDir, timeout: 1 });
+      assert.equal(result.ok, false);
+      assert.equal(result.timedOut, true);
+    });
+  });
+});
+
 // ─── probeTty ────────────────────────────────────────────────────────────────
 
 describe('probeTty', () => {