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/gsd-mcp-server.test.cjs

@@ -54,6 +54,36 @@ test('tools/call gsd_invoke_command: dispatches to the command hub (point 1); un
   assert.strictEqual(res.jsonrpc, '2.0');
   const payload = JSON.parse(res.result.content[0].text);
   assert.strictEqual(payload.ok, false, 'an unknown command dispatches to the hub and returns ok:false');
+  assert.strictEqual(res.result.isError, true, 'unknown family surfaces as isError:true (#2102)');
+});
+
+// REGRESSION #2102: gsd_invoke_command previously called
+// `commandRoutingHub.createHub()` with NO arguments, which always hits
+// `if (!_cjsRegistry) return makeUnknownCommand()` — every dispatch, valid
+// family or not, returned UnknownCommand. The test above (family:
+// 'no-such-family') could not catch this: an UnknownCommand result is
+// EXACTLY what an unknown family is supposed to return, whether or not
+// dispatch actually worked — it is vacuous by construction. This test proves
+// the fix: a VALID read-only family/subcommand must reach gsd-tools.cjs for
+// real and come back with actual data (not a crash, not UnknownCommand).
+test('tools/call gsd_invoke_command: REGRESSION #2102 — a valid read-only family dispatches for real (not the createHub()-with-no-args UnknownCommand bug)', () => {
+  const dir = createTempDir();
+  try {
+    const res = handleMessage(
+      { jsonrpc: '2.0', id: 9, method: 'tools/call', params: { name: 'gsd_invoke_command', arguments: { family: 'progress', subcommand: 'json' } } },
+      { cwd: dir },
+    );
+    assert.strictEqual(res.jsonrpc, '2.0');
+    assert.notStrictEqual(res.result.isError, true, 'a valid family must not surface as an error');
+    const text = res.result.content[0].text;
+    const parsed = JSON.parse(text);
+    // Fail-first proof: under the bug, this would be
+    // { ok: false, kind: 'UnknownCommand', command: 'progress json' } instead
+    // of the real progress payload — `percent` would not exist.
+    assert.strictEqual(typeof parsed.percent, 'number', 'the real "progress json" command ran (the engine was reached)');
+  } finally {
+    cleanup(dir);
+  }
 });
 
 test('tools/call: unknown tool name surfaces a tool error (isError), not a JSON-RPC protocol error', () => {