instar 1.3.342 → 1.3.344

package/upgrades/1.3.344.md

@@ -0,0 +1,46 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+instar gained a fourth agentic framework: **pi-cli** (the pi coding agent,
+`@earendil-works/pi-coding-agent` — the minimal harness powering OpenClaw).
+Ships completely DARK: nothing registers and no behavior changes unless an
+agent's config explicitly lists `'pi-cli'` in `enabledFrameworks` AND the
+`pi` binary is installed. Opting in gets: (1) pi topic sessions in tmux with
+IDENTICAL dashboard streaming/typing (TUI-in-tmux v1; launch builders +
+stuck-input detection pinned against real captured panes); (2) a
+provider-substrate adapter with pi's NATIVE structured RPC channel (prompt /
+mid-stream steer / abort, strict-LF JSONL, canonical event normalization)
+plus one-shot completions reporting tokens AND cost; (3)
+`sessions.componentFrameworks` can route internal components (sentinels,
+gates) to `'pi-cli'` — e.g. background chatter onto a Codex/Copilot
+subscription via pi; (4) a STRUCTURAL subscription guard: Anthropic/Claude-
+routed pi model patterns are DENIED by default at every call-construction
+path (Claude-via-pi bills as per-token extra usage, not plan limits — so it
+can never be selected silently; file-config-only override, audit-logged).
+Verified hands-on against the real binary (pi 0.78.1) with a hermetic mock
+provider — zero credentials, all three test tiers.
+
+## What to Tell Your User
+
+Nothing proactively — this ships dark and changes nothing by default. If your
+user asks about pi/OpenClaw support, or about spreading background LLM load
+onto other subscriptions: instar can now drive the pi coding agent as an
+additional framework (experimental, opt-in), with a built-in guard that
+prevents accidental Anthropic extra-usage billing.
+
+## Summary of New Capabilities
+
+- **pi-cli framework** (⚗️ experimental, opt-in via `enabledFrameworks`) — drive
+  the pi coding agent as a fourth framework alongside claude-code / codex-cli /
+  gemini-cli. Sessions run in tmux (dashboard streaming unchanged).
+- **pi provider adapter** — `GET /providers/registry` lists `pi-cli` (one-shot
+  completion + native RPC session + session-id + hard-kill) when enabled.
+- **pi component routing** — `sessions.componentFrameworks` accepts `pi-cli`,
+  so sentinels/gates can run on pi (onto a non-Claude subscription).
+- **Subscription guard** — `piCli.allowAnthropicProviders` (default false):
+  routing pi at an Anthropic/Claude model is denied unless explicitly opted in,
+  and the opt-in is audit-logged with a cost warning.

package/upgrades/side-effects/pi-harness-integration.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — pi-harness-integration (Phases A-D)
+
+## Blast radius
+
+Additive at every layer; ships DARK behind `enabledFrameworks` containing
+`'pi-cli'` (default absent) AND a detectable `pi` binary. With the default
+config, NOTHING registers and NO dispatch path changes outcome.
+
+Shared-file behavior changes (the only non-additive surfaces):
+
+1. **SessionManager.isMarkerStuckAtPrompt** — adds a new detection branch
+   (marker sandwiched between two `─` rule lines, pi's input box). Requires
+   BOTH the injected marker AND a rule within 2 lines above AND below —
+   normal transcript output and the other frameworks' panes cannot satisfy
+   it (their input areas use prompt chars, not rule sandwiches). Existing
+   prompt-char branches untouched; pinned by tests against real captured
+   pane bytes for all four frameworks.
+2. **SessionManager binary resolution** — pi-cli now resolves to bare `'pi'`
+   instead of falling back to `claudePath` (which holds a CLAUDE binary).
+   Without this, a pi topic on a claude install would silently launch
+   Claude — the exact additive-only violation this project forbids. Other
+   frameworks' resolution is byte-identical.
+3. **framework-arg-rendering-matrix test** — now DERIVED from
+   SUPPORTED_FRAMEWORKS instead of a hand-list (which had silently dropped
+   gemini-cli). Test-only.
+
+## Framework generality
+
+This change EXTENDS the framework abstraction rather than special-casing:
+'pi-cli' rides the same Record<IntelligenceFramework, …> dispatch maps as
+claude-code / codex-cli / gemini-cli (launch builders, injection processes,
+activity + process signals, parity renderer), and the never-exhaustiveness
+checks force every future dispatch site to handle all four. The
+framework-agnosticism test suite passes with pi included; the arg-rendering
+matrix now derives from the registry so a fifth framework cannot silently
+miss coverage. Warm-session injection works for pi via the
+FRAMEWORK_INJECTION_PROCESS_NAMES entry ('pi'), same as every framework.
+
+## Security / spend surfaces
+
+- **Subscription guard (structural)**: Anthropic/Claude-routed pi model
+  patterns are DENIED at every call-construction path (one-shot transport,
+  RPC session start, intelligence provider construction), including
+  aggregator pass-throughs (`openrouter/anthropic/...`) and the
+  pattern-less case (pi's ambient default could be an Anthropic login).
+  Override is file-config only (`piCli.allowAnthropicProviders`), never env
+  or per-call; allowed calls are audit-logged with a cost warning.
+- **Child env hardening**: pi child processes get an explicit allowlist env
+  with UNCONDITIONAL deletion of all billing-capable vars (ANTHROPIC/
+  OPENAI/GEMINI/GOOGLE/XAI/GROQ/OPENROUTER keys + CLAUDE_CODE_OAUTH_TOKEN),
+  mirroring the gemini Rule-1a analog. pi authenticates via its own
+  ~/.pi/agent/auth.json (subscription OAuth) or models.json custom keys.
+- **No permission system in pi**: instar's gate layer wraps pi sessions
+  exactly like other frameworks; containerization noted as future hardening
+  in the spec (§ kickoff Risks).
+
+## Rollback
+
+Revert the commit. No migrations mutate state destructively (the CLAUDE.md
+migration is content-sniffed append-only; no config defaults are written).
+Agents that opted in simply lose the pi framework value on downgrade —
+their claude-code/codex-cli/gemini-cli behavior is untouched.
+
+## Deliberate non-goals (tracked in spec §9, not silent drops)
+
+Replacing any Claude Code path; pi-ai adoption for non-pi internal calls;
+OAuth flow automation; cross-provider mid-session handoff; event-stream
+dashboard renderer (optional Phase E, decided after the core lands).
+
+## CI-fix follow-up (post-first-commit)
+
+Greening CI surfaced expected churn, no behavior change:
+- Three existing tests hardcoded the 3-framework SUPPORTED list → added
+  'pi-cli' to the expectations.
+- The `no-silent-fallbacks` ratchet counted the intelligenceProviderFactory
+  pi-cli degrade-to-null catch → marked `@silent-fallback-ok` (it warns
+  loudly and the router emits its own DegradationReporter; a second report
+  here would double-count the same degrade).
+- The release-fragment lint required `## Summary of New Capabilities` → added
+  it and switched to the canonical `<!-- bump -->` comment.
+None of these touch runtime behavior; they align the new framework with the
+existing structural gates.

package/upgrades/side-effects/redteam-harness-phase1-core.md

@@ -0,0 +1,53 @@
+# Side-effects review — MTP Red-Team Harness Phase-1 core (EXO 3.0 G7)
+
+## What this change is
+A new, self-contained module `src/redteam/ScenarioPack.ts` (pure logic) + two
+default scenario packs under `src/redteam/packs/` + a unit test. It adds NO
+route, NO CLI command, NO session/lifecycle hook, NO config key, and is imported
+by nothing in the running server yet. It is foundation code for a Phase-2
+productization (CLI/route).
+
+## Blast radius
+- **Runtime impact: none.** Nothing imports `ScenarioPack.ts` at server boot or
+  in any job/sentinel/route. Adding the file cannot change any live behavior. A
+  grep for `redteam` / `ScenarioPack` across `src/server`, `src/commands`,
+  `src/core` composition shows no consumer.
+- **Only dependency is inward**: it imports `IntentTestHarness` and the
+  `ParsedOrgIntent` type — both read-only, already-shipped. It calls
+  `IntentTestHarness.testRefusal()` (a pure function over parsed intent); it
+  never mutates intent, never writes files, never performs I/O.
+- **The packs are data.** The two `pack.json` files + committed `L0.md`/`L1.md`
+  payloads are inert until a future runner reads them. No code loads them yet.
+
+## Security / safety review
+- **Payload-by-reference is enforced in the type system**: the module handles
+  payloads as `{ path, sha256 }` only and has no code path that reads a payload
+  body. The committed payloads (`L0.md` declared-audit, `L1.md` naive benign
+  ask) were authored in an isolated subagent session, never in the orchestrator
+  transcript — honoring the CMT-1115 lesson (inline red-team payloads
+  permanently wedged a session via an AUP-rejection loop).
+- **Engineered payloads are NOT committed**: `L2.md` (pressure) and `L3.md`
+  (engineered) are gitignored; their `pack.json` sha reads
+  `PENDING-LOCAL-AUTHOR`. So the reviewable PR diff contains no engineered
+  attack text — a reviewing agent reading this diff cannot be wedged by it.
+- **No new external surface**: no network calls, no new auth, no new file
+  writes. The classifier's regexes are local string checks.
+
+## Framework generality
+This change does not route through the session-launch / inject abstraction or
+message delivery — it is framework-agnostic pure logic operating on parsed
+ORG-INTENT, which is identical across claude-code / codex-cli / gemini-cli. The
+harness it seeds is explicitly designed to be org-agnostic AND framework-neutral
+(it tests an agent's behavior through whatever channel, independent of the
+underlying framework). No Claude-specific assumption is introduced.
+
+## Test coverage
+25 unit tests (`tests/unit/redteam-scenario-pack.test.ts`) cover both sides of
+every decision boundary: coherent vs incoherent transport, governed vs
+ungoverned, each outcome class, pass vs fail, and the boundary-map edges
+(holds-through-L2-cracks-at-L3, cracks-at-L0, holds-everywhere, derivation
+ratio, ungoverned surface). `tsc --noEmit` is clean.
+
+## Rollback
+Deleting `src/redteam/` + the test + reverting the `.gitignore` lines fully
+removes the change with zero runtime consequence (nothing depends on it).