@jaggerxtrm/specialists 3.17.0 → 3.18.0

package/docs/overrides-guide.md

@@ -0,0 +1,306 @@
+# Global user overrides guide
+
+This guide is the canonical reference for `~/.config/specialists/user.json`, created by `sp init --global`. The global user layer lets each user tune environment-specific fields without forking shipped specialists. Specialist identity and safety fields remain blocked.
+
+## Overview
+
+The global override surface includes:
+
+- KAN-91 allowlisted user-environment fields: `prompt.system_prompt_mode`, `execution.extensions.serena`, `execution.extensions.gitnexus`, `notes_mode`, `output_file`, `execution.prompt_limit_bytes`, and `execution.stdout_limit_bytes`.
+- Additional runtime-default knobs: `execution.interactive` (default keep-alive behavior) and `stall_detection.waiting_auto_close_ms` (opt-in waiting auto-close threshold).
+- Fallback chains via `execution.fallback_models` while keeping legacy `execution.fallback_model`.
+- Preset references like `@preset/cheap` for model and fallback entries.
+- A top-level `_doc` sentinel in generated `user.json` pointing back to this guide. Keys starting with `_` are metadata, not specialist names.
+
+The examples below are delta snippets to add inside an existing specialist entry from `sp init --global`; they are not complete standalone `user.json` files. Keep the surrounding generated entry shape, including its `execution`, `prompt`, `stall_detection`, `beads_write_notes`, and `skills` keys, and change only the highlighted field.
+
+## Per-field reference
+
+### `prompt.system_prompt_mode`
+
+- Type: `"append" | "replace" | null`
+- Default semantics: `null` inherits the shipped specialist value, normally `append`.
+- Example:
+
+```json
+{
+  "executor": {
+    "prompt": { "system_prompt_mode": "replace" }
+  }
+}
+```
+
+Pitfall: this controls composition mode only. It does not let `user.json` replace `prompt.system`; prompt content remains blocked.
+
+### `execution.interactive`
+
+- Type: `boolean | null`
+- Default semantics: `null` inherits the merged specialist default. This is the default keep-alive/resume behavior when the operator does **not** pass `--keep-alive` or `--no-keep-alive`.
+- Example:
+
+```json
+{
+  "reviewer": {
+    "execution": { "interactive": false }
+  }
+}
+```
+
+Pitfall: CLI flags still win. Effective precedence is `--no-keep-alive` > `--keep-alive` > merged `execution.interactive`.
+
+### `execution.extensions.serena`
+
+- Type: `boolean | null`
+- Default semantics: `null` inherits the shipped extension setting.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "extensions": { "serena": false } }
+  }
+}
+```
+
+Pitfall: extension overrides are per-key overlays. Setting `serena: false` does not change `gitnexus`.
+
+### `execution.extensions.gitnexus`
+
+- Type: `boolean | null`
+- Default semantics: `null` inherits the shipped extension setting.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "extensions": { "gitnexus": false } }
+  }
+}
+```
+
+Pitfall: disabling GitNexus removes graph tooling from that specialist run. Use only when project indexing is unavailable or too expensive.
+
+### `stall_detection.waiting_auto_close_ms`
+
+- Type: `number | null`
+- Default semantics: `null` inherits or disables the behavior. `0` also means disabled.
+- Example:
+
+```json
+{
+  "reviewer": {
+    "stall_detection": { "waiting_auto_close_ms": 3600000 }
+  }
+}
+```
+
+Pitfall: this is **opt-in** and applies only after a specialist is already in `waiting`. The runtime attempts graceful close first; forced termination is fallback-only if the session refuses to exit.
+
+### `notes_mode`
+
+- Type: `"full-trail" | "final-only" | null`
+- Default semantics: `null` inherits the specialist default. `full-trail` appends turn handoffs; `final-only` keeps final handoff only.
+- Example:
+
+```json
+{
+  "researcher": {
+    "notes_mode": "final-only"
+  }
+}
+```
+
+Pitfall: `final-only` is quieter but removes intermediate turn notes from bead history.
+
+### `output_file`
+
+- Type: `string | null`
+- Default semantics: `null` inherits the specialist default or no file mirror.
+- Example:
+
+```json
+{
+  "researcher": {
+    "output_file": "./.specialists/researcher-result.md"
+  }
+}
+```
+
+Pitfall: paths are not expanded by the loader. `~/result.md` stays literal and is not converted to your home directory.
+
+### `execution.prompt_limit_bytes`
+
+- Type: `number | null`
+- Default semantics: `null` inherits the shipped prompt input limit.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "prompt_limit_bytes": 8388608 }
+  }
+}
+```
+
+Pitfall: raising this limit can increase token spend or provider rejection risk.
+
+### `execution.stdout_limit_bytes`
+
+- Type: `number | null`
+- Default semantics: `null` inherits the shipped stdout capture limit.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "stdout_limit_bytes": 67108864 }
+  }
+}
+```
+
+Pitfall: raising this limit can produce very large logs and result files.
+
+### `execution.fallback_model`
+
+- Type: `string | null`
+- Default semantics: legacy single fallback. `null` means no singular fallback from this layer.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "fallback_model": "openai-codex/gpt-5.4-mini" }
+  }
+}
+```
+
+Pitfall: if `fallback_models` is also set, plural wins.
+
+### `execution.fallback_models`
+
+- Type: `string[] | null`
+- Default semantics: `null` inherits lower layers. Array values replace the singular fallback chain for that layer.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": {
+      "fallback_models": [
+        "openai-codex/gpt-5.4-mini",
+        "nano-gpt/moonshotai/kimi-k2.5"
+      ]
+    }
+  }
+}
+```
+
+Pitfall: fallback walk is transient-failure-only. Auth failures, prompt rejections, and other logical failures do not advance to the next provider.
+
+## Preset reference syntax
+
+Write a preset reference as an exact string inside the existing generated specialist entry:
+
+```json
+{
+  "executor": {
+    "execution": {
+      "model": "@preset/cheap",
+      "fallback_models": ["@preset/medium", "openai-codex/gpt-5.4-mini"]
+    }
+  }
+}
+```
+
+Package presets live in `config/presets.json`. Current shipped names are `cheap`, `medium`, and `power`. User-defined preset files and repo-level preset shadowing are not part of this global override surface.
+
+Preset references resolve transitively with depth cap 4. Cycles raise `SpecialistPresetCycleError` with the visited preset list. Unknown names raise `SpecialistPresetNotFoundError` and list known presets. Malformed preset payloads raise `SpecialistPresetTypeError` before the loader writes the resolved value into the merged specialist spec.
+
+Only allowlisted override fields accept preset references. A blocked field such as `prompt.system` cannot smuggle a preset reference through `user.json`.
+
+## Fallback chain semantics
+
+Runtime model order is:
+
+1. Primary `execution.model`.
+2. `execution.fallback_models` entries when plural is present.
+3. Legacy `execution.fallback_model` only when plural is absent.
+
+Plural wins over singular in the same layer. A plural override in a higher layer replaces the lower layer's singular fallback chain because mixing singular and plural fallbacks across layers is ambiguous.
+
+Each fallback step emits `fallback_step` telemetry with specialist, attempt number, tried model, error class, and whether the step was terminal. Chain walk only happens for transient failures such as rate limits, network errors, timeouts, and 5xx-class provider failures.
+
+## `auto_commit` is fork-only by design
+
+`auto_commit` is intentionally blocked from `user.json`. The package default is `checkpoint_on_waiting` for `executor` and `debugger`, which checkpoints work before these long-running specialists enter `waiting`. Silent loss is the failure mode this default prevents: a specialist can produce useful edits, pause for review, then be resumed or terminated before manual staging captures the work.
+
+Change `auto_commit` only by forking the specialist into `.specialists/user/<name>.specialist.json` and editing that fork:
+
+```bash
+mkdir -p .specialists/user
+cp config/specialists/executor.specialist.json .specialists/user/executor.specialist.json
+# edit .specialists/user/executor.specialist.json and set auto_commit intentionally
+```
+
+Repo/user forks are explicit because `auto_commit` changes repository-write behavior for everyone using that fork.
+
+## Initialization and strict JSON
+
+Existing `~/.config/specialists/user.json` files auto-extend on the next `sp init --global` run. Existing values are preserved. Missing fields are filled with `null` defaults, and `_doc` points at `./overrides-guide.md`.
+
+Generated files stay strict JSON. `sp init --global` does not write comments; it writes `_doc` as a top-level metadata key and writes this guide as `overrides-guide.md` next to `user.json`.
+
+## Complete example (validates against `GlobalUserConfigSchema`)
+
+This is a complete `user.json` shape, not a delta snippet. It keeps every required key from `sp init --global` and exercises `system_prompt_mode`, fallback chains, extension opt-out, and `@preset/<name>` references.
+
+```json
+{
+  "_doc": "./overrides-guide.md",
+  "executor": {
+    "execution": {
+      "model": "@preset/cheap",
+      "fallback_model": null,
+      "fallback_models": [
+        "@preset/medium",
+        "openai-codex/gpt-5.4-mini"
+      ],
+      "timeout_ms": null,
+      "stall_timeout_ms": null,
+      "interactive": true,
+      "thinking_level": null,
+      "max_retries": null,
+      "prompt_limit_bytes": 8388608,
+      "stdout_limit_bytes": null,
+      "extensions": {
+        "serena": false,
+        "gitnexus": null
+      }
+    },
+    "prompt": {
+      "system_prompt_mode": "replace"
+    },
+    "stall_detection": {
+      "waiting_auto_close_ms": 3600000
+    },
+    "beads_write_notes": null,
+    "notes_mode": "final-only",
+    "output_file": null,
+    "skills": {
+      "paths": []
+    }
+  }
+}
+```
+
+## Cross-references
+
+- Historical KAN-91 delta: `docs/upgrade-notes/kan-91-expanded-overrides.md`
+- Origin doc: `docs/upgrade-notes/kan-90-global-user-config.md`
+- KAN-91 epic: `unitAI-gp7nq`
+- Phase 0 override machinery: `unitAI-gp7nq.1`
+- Phase 1 user-environment fields: `unitAI-gp7nq.2`
+- Phase 2 fallback chains: `unitAI-gp7nq.3`
+- Phase 3 preset references: `unitAI-gp7nq.4`
+- Follow-up reference-doc update: `unitAI-aav4w`
+- Follow-up stale 4-layer wording fix: `unitAI-v4i0j`

package/docs/pi-rpc-boundary.md

@@ -0,0 +1,118 @@
+---
+title: pi/rpc Boundary
+description: Canonical ownership boundary between pi/rpc protocol surfaces and Specialists runtime adaptation.
+synced_at: 4e7a6b4a
+version: 3
+updated: 2026-05-15
+---
+
+# pi/rpc Boundary
+
+This document defines ownership boundaries so protocol changes stay in the right layer.
+
+References:
+- `pi/rpc/` — canonical protocol implementation and types
+- `docs/pi-rpc-boundary.md` — this ownership-boundary guide
+- `pi/rpc/rpc-types.ts`
+- `pi/rpc/rpc-client.ts`
+- `pi/rpc/rpc-mode.ts`
+- `pi/rpc/jsonl.ts`
+- `src/pi/session.ts`
+- `src/specialist/supervisor.ts`
+- `src/specialist/timeline-events.ts`
+
+## 1) Canonical pi/rpc (source of truth)
+
+Own this in `pi/rpc/*` and treat as canonical protocol contract:
+
+- Command/response/event schema and names (`prompt`, `steer`, `follow_up`, `agent_end`, `message_update`, `tool_execution_*`, etc.)
+- Wire-level command typing and response typing
+- Extension UI sub-protocol (`extension_ui_request` / `extension_ui_response`)
+- RPC mode command dispatch semantics (`rpc-mode.ts`)
+- JSONL framing semantics (`jsonl.ts`): LF-delimited records, strict line splitting behavior
+- Request/response correlation by `id`
+
+If a behavior is represented in `pi/rpc/*.ts`, Specialists should adapt to it, not redefine it. This document records the ownership boundary; the protocol implementation remains the source of truth.
+
+## 2) Specialists-owned boundary (adapter + orchestration)
+
+Own this in Specialists runtime code:
+
+- `src/pi/session.ts` as adapter from canonical pi/rpc events into Specialists callbacks and lifecycle hooks
+- Mapping raw pi event stream into Specialists event labels (`message_start_assistant`, `turn_start`, `tool_execution_start`, etc.)
+- Runtime liveness/operational policy: stall watchdog, process lifecycle, kill/abort behavior, **test-aware stall timeout extension**
+- Supervisor durability model (DB-first: `specialist_results` table, with file output env-gated since 3.9) and job lifecycle decisions
+- Specialists timeline abstraction in `src/specialist/timeline-events.ts`
+
+Specialists may transform/aggregate events for its own APIs, but must not invent conflicting meanings for existing pi/rpc event names.
+
+## 3) Transport-only concerns (non-semantic)
+
+Transport-only concerns are implementation mechanics, not business semantics:
+
+- stdin/stdout subprocess wiring
+- JSONL encode/decode and buffering across chunk boundaries
+- newline normalization (`\n`, optional trailing `\r` handling)
+- request timeout handling and pending request maps
+- low-level process termination mechanics
+
+Changes here must preserve canonical protocol meaning; they should not alter runtime semantics defined by pi/rpc.
+
+## 4) Practical decision rule
+
+When deciding where a change belongs:
+
+- **pi/rpc change** if it introduces/renames/removes protocol fields, commands, or event semantics.
+- **Specialists change** if it changes orchestration, persistence, timeline modeling, or job lifecycle policy while consuming the same pi/rpc contract.
+- **transport-only change** if it only affects framing, buffering, or subprocess I/O mechanics without semantic changes.
+
+## 5) Specialists-owned stall detection
+
+The stall timeout mechanism is entirely Specialists-owned:
+
+- **Base timeout**: configured via `execution.stall_timeout_ms` in specialist YAML, passed to PiAgentSession
+- **Test-aware extension**: PiAgentSession detects test command patterns (vitest, bun test, npm test, pnpm test, yarn test, jest, pytest) and extends the stall window to 300s during tool execution
+- **Session kills**: StallTimeoutError thrown by PiAgentSession when no activity is detected within the effective timeout
+- **Supervisor staleness**: Separate mechanism (running_silence_warn_ms, waiting_stale_ms) that emits timeline events but does not kill the session
+
+This distinction matters: pi/rpc provides the event stream, but Specialists determines when "no activity" becomes a timeout. The test-aware extension is a Specialists policy decision, not a protocol feature.
+
+---
+
+## 7) Specialists-owned Pi extensions
+
+Specialists can inject Pi extensions at session spawn time for policy enforcement. These extensions live in `$TMPDIR/specialists-pi-extensions/` and are passed to Pi via `-e <path>` arguments.
+
+**What's OK to inject:**
+
+- Pre-tool-call hooks (`pi.on('tool_call', ...)`) — for write-boundary enforcement, tool filtering, argument validation
+- Event listeners (`pi.on('message_update', ...)`, etc.) — for logging, metrics, custom event handling
+- Post-tool-call hooks — for result filtering, error handling wrappers
+
+**What's NOT OK:**
+
+- Pi protocol changes — extension cannot modify the command/event schema, add new RPC commands, or change wire-level semantics
+- Competing with Supervisor lifecycle — extension should not emit `run_complete` or alter job state
+- Cross-session state — extension is per-session, cannot persist state across Pi invocations
+
+The RPC boundary remains unchanged: Pi's command/response/event contract is identical whether or not extensions are injected. Extensions are a **policy layer**, not a protocol extension.
+
+**Example: worktree write-boundary enforcement**
+
+The primary use case is blocking write tools (`edit`, `write`, `multiEdit`, `notebookEdit`) from writing outside a declared worktree boundary. The extension:
+
+1. Hooks `tool_call` events
+2. Extracts `path`/`file_path` argument from tool input
+3. Validates against the boundary (via `SPECIALISTS_WORKTREE_BOUNDARY` env var)
+4. Returns `{ block: true, reason: '...' }` for out-of-bounds paths
+
+The boundary path is passed to the extension via `SPECIALISTS_WORKTREE_BOUNDARY` env var. This enforcement happens entirely inside the Pi process — the Specialists Supervisor does not need to intercept or validate tool calls itself.
+
+---
+
+## 6) Invariants
+
+- `pi/rpc/*.ts` remains the canonical protocol surface.
+- `src/pi/session.ts` remains an adapter, not a competing protocol definition.
+- Supervisor remains the durable source of run lifecycle state for Specialists.
+- Any divergence from `pi/rpc/*.ts` must be treated as a bug or an explicit upstream protocol update.

package/docs/pi-session.md

@@ -0,0 +1,195 @@
+---
+title: Pi Subprocess Isolation
+scope: pi-session
+category: reference
+version: 1.3.0
+updated: 2026-06-24
+synced_at: bf6baf7a
+description: Why specialists spawns Pi with isolation flags and which extensions are selectively re-enabled.
+source_of_truth_for:
+  - "src/pi/session.ts"
+domain:
+  - pi
+  - architecture
+---
+
+<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+| [Why `--no-extensions`](#why-no-extensions) | Pi auto-discovers xtrm extensions on startup from `~/ |
+| [Selective re-enable policy](#selective-re-enable-policy) | After disabling all extensions, `src/pi/session |
+| [How it maps from specialist YAML](#how-it-maps-from-specialist-yaml) | The specialist's `execution |
+| [Serena-pool integration](#serena-pool-integration) | Pre-spawn hook that starts/reuses a shared Serena daemon via `ensureSerenaForRootInSubprocess` |
+| [Telemetry bridging](#telemetry-bridging) | AgentOps-style metrics — token usage schema, `reasoning_tokens`, `tool_tokens`, `usage_source` |
+| [Code location](#code-location) | `src/pi/session.ts` — `start()` method, extension resolution section |
+| [Installing the selectively-loaded extensions](#installing-the-selectively-loaded-extensions) | Specialists does not install these — it only loads them if present |
+| [See also](#see-also) | - [pi-rpc |
+<!-- END INDEX -->
+
+# Pi Subprocess Isolation
+
+> **Alias:** `sp` is a shorter alias for `specialists` — `sp run`, `sp list`, `sp feed` etc. work identically.
+
+Specialists spawns Pi in `--rpc` mode as a subprocess. Every package-class specialist run starts Pi with `--no-extensions`, `--offline`, `--no-context-files`, `--no-prompt-templates`, and `--no-themes`, then selectively re-enables a small allowlist of extensions. This page explains why.
+
+## Why `--no-extensions`
+
+Pi auto-discovers xtrm extensions on startup from `~/.pi/agent/extensions/`. In an interactive session these extensions provide useful workflow enforcement — but in a specialist subprocess they cause silent failures.
+
+The critical case is the **beads** extension. It blocks file edits unless a `claimed:<sessionId>` KV entry exists for the active Pi session ID. The orchestrating Claude session holds the claim; the specialist subprocess has a different, unrelated session ID. Without `--no-extensions`, every file write the specialist attempts silently fails the beads edit gate.
+
+Other extensions (`session-flow`, `xt-end` reminder, UI/UX helpers) are similarly irrelevant or harmful in a headless subprocess context. The runner also disables Pi startup discovery surfaces with `--offline`, `--no-context-files`, `--no-prompt-templates`, and `--no-themes` so specialist subprocesses do not perform startup network checks or inherit human-session context files, prompt templates, or themes.
+
+## Selective re-enable policy
+
+After disabling all extensions, `src/pi/session.ts` re-enables a small allowlist using `-e <path>`:
+
+| Extension | Loaded in specialist Pi? | Condition | Reason |
+|-----------|--------------------------|-----------|--------|
+| `beads` | ❌ Never | — | Blocks edits — subprocess session ID has no claim |
+| `session-flow` | ❌ Never | — | Stop gate and xt-end reminder are irrelevant in subprocess |
+| `quality-gates` | ✅ If installed | `permission_required` ≠ `READ_ONLY` | Lint/typecheck enforcement on specialist edits |
+| `service-skills` | ✅ If installed | Always (if installed) | Territory-aware routing is useful in any session |
+| `caveman` | ✅ If installed | Always (if installed) | Terse output for agent-to-agent communication |
+| `pi-gitnexus` (npm) | ✅ If installed, unless opted out | Not in `excludeExtensions` | Code intelligence tools |
+| `pi-serena-tools` (npm) | ✅ If installed, unless opted out | Not in `excludeExtensions` | Serena integration tools |
+| All other extensions | ❌ Never | — | UI/UX only; not relevant headlessly |
+
+## How it maps from specialist YAML
+
+The specialist's `execution.permission_required` field controls whether `quality-gates` loads:
+
+```yaml
+execution:
+  permission_required: READ_ONLY   # → quality-gates NOT loaded (read-only; no edits to lint)
+  permission_required: LOW         # → quality-gates loaded if installed
+  permission_required: MEDIUM      # → quality-gates loaded if installed
+  permission_required: HIGH        # → quality-gates loaded if installed
+```
+
+`service-skills` loads regardless of permission level if the extension is installed.
+
+## Extension opt-out
+
+Specialists can opt out of specific npm extensions via `execution.extensions` in their config:
+
+```json
+{
+  "execution": {
+    "extensions": {
+      "serena": false,
+      "gitnexus": false
+    }
+  }
+}
+```
+
+When `false`, the extension is excluded from the `-e` args passed to Pi spawn. This is useful for specialists where Serena or GitNexus tools add overhead without value.
+
+## Caveman extension
+
+The caveman extension (`~/.pi/agent/extensions/caveman`) is loaded automatically when present. It enforces terse output style for agent-to-agent communication. The runner also sets `CAVEMAN_LEVEL=full` in the Pi process environment.
+
+## Code location
+
+`src/pi/session.ts` — `start()` method, extension resolution section:
+
+```typescript
+const args = [
+  '--mode', 'rpc',
+  '--no-extensions',
+  ...providerArgs,
+  '--no-session',
+  '--offline',
+  '--no-context-files',
+  '--no-prompt-templates',
+  '--no-themes',
+];
+
+// Selectively re-enable extensions
+const piExtDir = join(homedir(), '.pi', 'agent', 'extensions');
+const excludedExtensions = new Set(this.options.excludeExtensions ?? []);
+
+// Quality-gates (edit-capable only)
+const permLevel = (this.options.permissionLevel ?? '').toUpperCase();
+if (permLevel !== 'READ_ONLY') {
+  const qgPath = join(piExtDir, 'quality-gates');
+  if (existsSync(qgPath)) args.push('-e', qgPath);
+}
+
+// Service-skills (always)
+const ssPath = join(piExtDir, 'service-skills');
+if (existsSync(ssPath)) args.push('-e', ssPath);
+
+// Caveman (always)
+const cavemanPath = join(piExtDir, 'caveman');
+if (existsSync(cavemanPath)) args.push('-e', cavemanPath);
+
+// npm package extensions (with opt-out)
+const npmGlobalDir = resolveGlobalNodeModulesDir();
+if (npmGlobalDir) {
+  if (!excludedExtensions.has('pi-gitnexus')) {
+    const gitnexusPath = join(npmGlobalDir, 'pi-gitnexus');
+    if (existsSync(gitnexusPath)) args.push('-e', gitnexusPath);
+  }
+  if (!excludedExtensions.has('pi-serena-tools')) {
+    const serenaPath = join(npmGlobalDir, 'pi-serena-tools');
+    if (existsSync(serenaPath)) args.push('-e', serenaPath);
+  }
+}
+```
+
+### serena-pool
+
+When `pi-serena-tools` is enabled, `session.ts` runs a **pre-spawn hook** to start or reuse a shared Serena MCP daemon for the same repo root:
+
+1. It locates the globally-installed `serena-pool` extension at `@jaggerxtrm/pi-extensions/extensions/serena-pool/index.ts`.
+2. If found, it calls `ensureSerenaForRootInSubprocess` (a Bun/Node `execFileSync`-wrapped helper that dynamic-imports the pool module and returns a deterministic TCP port).
+3. The resulting port is injected into the Pi process environment as `SERENA_MCP_PORT`.
+
+Because `pi-serena-tools` reads `SERENA_MCP_PORT` at **extension construction time** (not at session-start), the env must be set **before** Pi spawns. This avoids duplicate Serena daemons on random ports.
+
+| Property | Value |
+|---|---|
+| Pool extension path | `<global_node_modules>/@jaggerxtrm/pi-extensions/extensions/serena-pool/index.ts` |
+| Port determinism | Hash-based on `projectRoot` |
+| State file | `~/.local/share/pi-serena-pool/<hash>.json` |
+| Fallback if pool fails | Pi falls back to spawning its own Serena (may incur per-worktree overhead) |
+
+If the pool extension is not installed, or the specialist opts out with `"extensions": { "serena": false }`, Pi spawns its own Serena directly (or skips it entirely for read-only specialists).
+
+### agentops telemetry bridge
+
+`session.ts` collates streaming RPC events into structured **session metrics** consumed by the AgentOps telemetry bridge:
+
+- **`SessionRunMetrics`** — `events`, `tokens`, `tool_calls`, `tool_tokens`, `stall_warnings`, `execution_time_ms`, `cost_usd`.
+- **`SessionTokenUsage`** — `input_tokens`, `output_tokens`, `cache_creation_tokens`, `cache_read_tokens`, **`reasoning_tokens`**, **`tool_tokens`**, `total_tokens`, `usage_source`.
+
+`usage_source` tells downstream dashboards how reliable the token numbers are:
+
+| Value | Meaning |
+|---|---|
+| `provider_usage` | Exact numbers from the LLM provider (OpenAI / Anthropic usage block) |
+| `runtime_estimate` | Approximated from streaming chunk sizes when no provider usage arrived |
+| `local_estimate` | Fallback heuristic (e.g. character-count ÷ 4) |
+| `unknown` | No data available |
+
+Cost is derived from the mapped `backend` + `model` in the telemetry layer, not inside `session.ts`.
+
+`onMeta` callback now also receives `sessionId` so the telemetry bridge can correlate the Pi session with the specialist run record.
+
+## Installing the selectively-loaded extensions
+
+Specialists does not install these — it only loads them if present. To enable them:
+
+```bash
+nextpi install quality-gates
+nextpi install service-skills
+```
+
+Both live at `~/.pi/agent/extensions/`. Run `specialists status` to see which extensions are active in a running job.
+
+## See also
+
+- [pi-rpc-boundary.md](pi-rpc-boundary.md) — RPC ownership boundary and lifecycle adaptation notes
+- [background-jobs.md](background-jobs.md) — Background job monitoring

package/docs/release.md

@@ -0,0 +1,22 @@
+# Release inputs
+
+`xt release` now reads two synthesis inputs:
+
+1. closed beads + git range signals
+2. xt session reports from `.xtrm/reports/` for same release window
+
+`sp release prepare` / `sp release publish` remain as deprecated aliases for backward compatibility. They proxy to the same release logic and print a deprecation notice on every invocation.
+
+The report layer is the higher-signal source. It captures intent, attempted approaches, discarded ideas, and post-mortem context. Use it to write WHY-grounded release bullets instead of file-diff summaries.
+
+## Report bundle cap
+
+Report injection is capped at about 50k bytes/tokens. If range is larger, oldest reports are dropped and a cap note is prepended. Release still runs.
+
+## Operator range
+
+Default range is previous tag..HEAD. Backfill runs may pass explicit `--from` / `--to` refs, and report selection follows that same range.
+
+## Result
+
+Keep-a-Changelog markdown still comes out unchanged. Only input quality changes.