instar 1.3.343 → 1.3.345

package/upgrades/1.3.345.md

@@ -0,0 +1,154 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+The apprenticeship program can now SEE when its deepest layer is starving.
+`GET /apprenticeship/instances/:id/role-coverage` gains an observe-only
+`keystoneBalance` block:
+
+```
+keystoneBalance: {
+  keystoneAxis: 'mentor-mentee-differential',
+  keystoneCycleCount, lastKeystoneAt,
+  oversightCycleCount, oversightSinceKeystone,
+  starved: boolean, starvationThreshold, reason
+}
+```
+
+`starved:true` means the deepest layer (the real mentor→mentee drive) is
+under-firing relative to ongoing activity — the silent "mentor-heavy /
+mentee-light" drift. It generalizes the old narrow `driftWarning` to catch the
+common "keystone fired once long ago, then drifted into pure review" case, not
+just "never fired." Tune the threshold per call with
+`?oversightStarvationThreshold=N` (default 3).
+
+Why: a 2026-06-06 holistic check found the program lopsided — the mentor layer
+had run 13 cycles while the mentee layer ran 3, and nothing surfaced it. By
+"Observation Needs Structure," a duty to notice is a wish unless the structure
+makes it visible.
+
+PR 2 of the June-15 interactive-only readiness arc (PR 1 = #873). The
+provider substrate could route INTERNAL intelligence calls onto the
+subscription lane, but Instar's other headless surface — full agentic
+`claude -p` one-shots for scheduled jobs, mentor loops, dispatch actions,
+`POST /sessions/spawn`, and Threadline A2A cold replies — still billed the
+Agent SDK pot with no reroute. This PR adds the reroute at the single funnel
+those spawns share (`SessionManager.spawnSession`'s headless branch,
+claude-code only): under `intelligence.subscriptionPath.mode` `force` (or
+`auto` when the shared credit decision says subscription), the spawn
+launches an INTERACTIVE claude session instead — same tmux session, same
+watchdogs/reaper semantics, same `--allowedTools`/`--strict-mcp-config`
+flags (spliced for parity), wide-pane geometry, with the prompt delivered
+via the existing ready-wait + guarded-inject machinery. Because an
+interactive REPL never exits, each rerouted task carries a deterministic
+completion sentinel (`INSTAR_JOB_COMPLETE_<id>`) the monitor reaps as
+SUCCESS (job history records success, not timeout), plus a hard
+`maxLifetimeMinutes` backstop (default 45). Safety gates from the 5-reviewer
+convergence: a rerouted-session concurrency cap (`maxRerouted`, default 3) +
+memory-pressure pre-spawn gate (auto → degradation-reported headless
+fallback; force → loud refusal); subscription-quota backpressure on the A2A
+(`SpawnRequestManager`) and pipe (`PipeSessionSpawner`) surfaces so peer
+traffic cannot rate-limit the operator's own account; force-mode pipe
+refusal that falls through to the rerouted A2A path; a paste-escape
+sanitizer in the tmux inject path; per-slug double-run guard + boot-time
+reconciliation so a restart can't double-execute a mid-flight job; an F6
+recurrence cap so a silently-dead reroute escalates instead of hiding behind
+its own fallback; a persisted `Session.launchLane` field surfaced in
+`GET /sessions` and the reap-log (the soak's machine-checkable criterion);
+a new CI lint (`lint-no-unfunneled-headless-launch`) that fails any future
+direct `buildHeadlessLaunch` callsite outside the funnel; three
+factory-bypass intelligence fallbacks in server.ts routed through the
+factory (carrying breaker + router); and the CLAUDE.md awareness block
+corrected (+ a new migration that reaches already-deployed agents).
+Everything ships dark: mode `off` (the fleet default) is pinned
+byte-for-byte to today's argv by test at every touched callsite.
+
+## What to Tell Your User
+
+Your agent can now answer "is my apprenticeship loop actually exercising its
+deepest layer, or has it drifted into just reviewing?" — and flag when the
+mentee side is starving, so the imbalance can't silently persist.
+
+After June 15, the one-shot commands I use for background jobs and
+agent-to-agent replies start drawing from a prepaid credit pot — and when it
+empties, they'd just fail. I already have a switch (from the last release)
+that can move my internal thinking onto normal interactive sessions; this
+release teaches that SAME switch to also cover my scheduled jobs and
+agent-to-agent replies. It also adds the guardrails that make flipping it
+safe: caps so rerouted work can't overload the machine or eat your
+subscription's rate window (other agents messaging me can never crowd out
+YOUR conversations), a marker system so finished jobs are recorded as
+successes, restart protection so a job can't accidentally run twice, and a
+visible label on every session showing which billing lane it used — so when
+we run the full-day proof, "everything ran on the subscription lane" is
+something you can check, not something you have to take my word for.
+Nothing changes at this release — the switch is still OFF everywhere.
+
+## Summary of New Capabilities
+
+- `keystoneBalance` on the role-coverage response — observe-only deepest-layer
+  health, with a plain-English `reason`. Tunable via
+  `?oversightStarvationThreshold=N`. Never gates.
+
+- `intelligence.subscriptionPath.mode` now governs headless job/A2A/dispatch
+  spawns too (claude-code only): `force` → interactive sessions with a
+  completion sentinel + lifetime backstop; `auto` → credit-driven, with
+  loud, capped fallback.
+- New config knobs: `subscriptionPath.maxRerouted` (concurrent rerouted
+  sessions, default 3), `subscriptionPath.maxReroutedLifetimeMinutes`
+  (default 45).
+- `Session.launchLane` (`headless` | `rerouted-interactive`) in
+  `GET /sessions` and the reap-log — machine-checkable billing-lane audit.
+- Quota backpressure on A2A + pipe spawn admission when the reroute is
+  active (wired to the same QuotaTracker gate jobs already use).
+- Per-slug job double-run guard + boot reconciliation of rerouted job
+  sessions.
+- CI funnel lint: direct `buildHeadlessLaunch` use outside the allowlist
+  fails the build.
+
+## Evidence
+
+Computed from existing cycle rows (no new storage, no migration). Three test
+tiers green: unit (both sides of every boundary incl. shortcut-still-un-driven
+and exactly-at-threshold), integration (route surfaces it + honors the tuning
+query), e2e (alive through the real AgentServer). Migration-parity + agent-
+awareness covered (template line + idempotent PostUpdateMigrator backfill, 4
+tests). `tsc --noEmit` clean.
+
+5-reviewer adversarial convergence (correctness/wiring, security/cost,
+ops/scale, standards/lessons, spec-vs-reality — ALL initially BLOCK; every
+finding folded into the spec, `docs/specs/june15-headless-spawn-reroute.md`
++ `.eli16.md`). 56+ new tests across all three tiers: 43 unit
+(`headless-spawn-reroute` 23 incl. argv pins both sides / completionMode
+both sides / cap + lifetime + sanitizer + reconciliation;
+`subscription-quota-gates` 8; `lint-no-unfunneled-headless-launch` 4;
+`PostUpdateMigrator-subscriptionPathScope` 5; `job-scheduler-double-run-
+guard` 3), 1 integration (`sessions-launch-lane` — launchLane through the
+real route pipeline), 4 e2e (`june15-headless-spawn-reroute` — production-
+mirroring construction: force spawn has no `-p` + wide pane, sentinel
+completes as success through the real monitor, launchLane via real HTTP,
+default-off invariance). Funnel lint clean on the tree + self-tested both
+ways. Silent-fallback ratchet held at 458.
+
+## Scope (honest)
+
+Observe-only this slice. It surfaces the imbalance; it does NOT yet
+auto-correct. The natural phase-2 (a cadence rule that drives the mentee layer
+at least once per K mentor cycles) is deliberately deferred so the signal
+proves out first — the same ship-the-observation-before-the-law order used for
+#856/#864 ahead of the #861 constitution article.
+
+## Incidental fix surfaced by the merge (Zero-Failure Standard)
+
+Merging current `main` in surfaced a pre-existing route-completeness ratchet
+break introduced by #884 (P1 Coherence Journal): the new `/coherence/journal`
+route's catch handled `InvalidCursorError` then `throw err` for everything
+else — leaving the routes.ts catch/instanceof count at 225/224 and producing an
+unhandled Express 500 (HTML stack leak) on any non-cursor error. Fixed in this
+PR by returning a proper JSON 500 (`err instanceof Error ? err.message :
+String(err)`) instead of re-throwing — strictly better behavior, and it
+rebalances the ratchet (225/225). Owned per the Zero-Failure Standard ("there
+is no such thing as a pre-existing failure").

package/upgrades/side-effects/apprenticeship-layer-balance.md

@@ -0,0 +1,50 @@
+# Side-Effects Review - apprenticeship layer-balance signal
+
+**Version / slug:** `apprenticeship-layer-balance`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (Tier 1)`
+
+## Summary of the change
+
+Adds an observe-only `keystoneBalance` block to `ApprenticeshipCycleStore.roleCoverage()` (surfaced via `GET /apprenticeship/instances/:id/role-coverage`). It makes the deepest-layer (mentor→mentee keystone) health a queryable fact: starved when the keystone never fired while oversight did, or enough oversight accrued since the last drive (default 3, tunable via `?oversightStarvationThreshold`). Generalizes the existing narrow `driftWarning`.
+
+## Decision-point inventory
+
+- `computeKeystoneBalance` (new, private) - pure function over the already-tallied axes + oversight timestamps; no I/O.
+- `roleCoverage(instanceId, opts?)` - modify - gains an optional opts param (back-compat: existing single-arg callers unchanged) and returns the new `keystoneBalance` field.
+- role-coverage route - modify - parses optional `?oversightStarvationThreshold` and passes it through.
+
+## 1. Behavior change / gating
+
+NONE. This is observe-only. It adds a computed read-only field; it never blocks a cycle record, never gates a transition, never alters the loop. The existing `driftWarning` is untouched (kept for back-compat). No new failure modes.
+
+## 2. Over/under-signal
+
+- Over-signal (false "starved"): a long-idle instance whose keystone fired once then sat through 3+ reviews reads starved even if that's intended. Acceptable — it's a surfaced signal a human/loop reads, not an action; and "intended long review phase" is exactly the thing worth surfacing.
+- Under-signal: an instance with keystone fired recently + <threshold oversight reads healthy even if the mentee is actually stuck. Acceptable for this slice — the signal is about cadence/balance, not per-drive quality (that's operatorSeatUx + the transcript auditor's job).
+
+## 3. Blast radius
+
+`roleCoverage()` callers: the one route + tests. The added param is optional, so every existing call compiles and behaves identically (just gains the extra field). No persistent-state change (computed from existing rows), so NO migration and NO data backfill. The field appears automatically for all instances, including legacy/grandfathered ones (their keystone history is read as-is).
+
+## 4. Failure modes
+
+`computeKeystoneBalance` is pure and total — no throw paths, no I/O. A malformed threshold from the query string falls back to the default (parsed-int guard). ISO string timestamp comparison is safe (createdAt is always normalized ISO).
+
+## 5. Migration parity
+
+No agent-installed files change. The signal is a new read-only API field, so Agent Awareness gets a one-line mention in the CLAUDE.md template + a PostUpdateMigrator backfill so deployed agents learn the state question ("is my mentee layer starving?"). No config, hooks, or skills touched.
+
+## 6. Scope honesty (what this is NOT)
+
+Observe-only by design. It does NOT auto-correct the imbalance — the natural phase-2 (a cadence rule that makes the autonomous loop drive the mentee layer at least once per K mentor cycles) is deliberately deferred so the signal proves out first (Graduated-Feature-Rollout discipline; ship the observation structure before the enforcement law — the same order as #856/#864 before the #861 constitution article).
+
+## 7. Incidental fix carried by this PR (`src/server/routes.ts`)
+
+Merging current `main` surfaced a pre-existing route-completeness ratchet break introduced by #884 (P1 Coherence Journal): the new `/coherence/journal` route caught `InvalidCursorError` then `throw err` for everything else. That left routes.ts at 225 `catch (err)` / 224 `err instanceof Error` (ratchet red) and leaked an unhandled Express HTML 500 on any non-cursor error.
+
+- **Decision point:** the journal route's catch block — `modify`. Behavior change: a non-cursor error now returns a clean JSON `{ error }` 500 instead of propagating to Express's default HTML error handler. Strictly better (no stack-trace leak), no new failure mode.
+- **Causal autopsy:** balance was even (224/224) at `6c2af5a6a`, went to 225/224 at `7afa768f5` (#884). Confirmed via per-commit catch/instanceof bisect.
+- **Blast radius:** one route's error path. No state, no migration, no gating. Rebalances the ratchet to 225/225 (route-completeness green).
+- **Why carried here vs separate PR:** the merge made this PR's CI red and #893 can't go green without it; owned per the Zero-Failure Standard ("there is no such thing as a pre-existing failure"). Documented loudly rather than silently bundled.

package/upgrades/side-effects/june15-headless-spawn-reroute.md

@@ -0,0 +1,105 @@
+# Side-Effects Review — june15-headless-spawn-reroute (PR 2)
+
+Spec: `docs/specs/june15-headless-spawn-reroute.md` (converged, 5-reviewer
+panel, approved by Justin in topic 9984 2026-06-05: "you have my approval if
+needed. please continue!").
+
+## Behavior changes when `mode` is `off`/unset (the fleet default)
+
+NONE intended, and pinned: V1/V5 argv pin tests assert the headless launch
+argv is byte-for-byte unchanged at every touched callsite for claude-code,
+codex-cli, and gemini-cli. Admission behavior of SpawnRequestManager and
+PipeSessionSpawner is unchanged (the quota/mode seams are absent unless the
+server wires them, and the server only wires them when mode is auto/force).
+Two deliberate always-on deltas, both additive:
+
+1. **`Session.launchLane` is now always stamped** (`'headless'` on the
+   default lane) and serialized via the existing `{ ...s }` spreads in
+   `GET /sessions` + the reap-log. Consumers that enumerate fields see one
+   more key. No existing field changes meaning.
+2. **`rawInject` strips bracketed-paste boundary sequences**
+   (`\x1b[200~` / `\x1b[201~`) from injected text (finding S2). Legitimate
+   prompts never contain raw paste-boundary bytes; anything that did was a
+   forged-submit vector, not a feature.
+3. **Three server.ts intelligence FALLBACK sites** (shared, relationships,
+   topic-summarizer) now construct via `buildIntelligenceProvider` instead
+   of `new ClaudeCliIntelligenceProvider` directly. When the factory returns
+   null (no claude binary), the fallback is now an honest absence instead of
+   a provider with an undefined binary path that fails at call time — a
+   strict improvement on an already-degraded path.
+
+## New failure modes introduced (and their bounds)
+
+- **Rerouted session never prints the sentinel** → reaped at
+  `maxLifetimeMinutes` (default 45) as timeout + DegradationReporter event.
+  Bound: the lifetime cap; tested.
+- **Reroute silently dead under `auto`** (cap stuck / pressure stuck /
+  continuity gap) → every spawn falls back headless; the F6 recurrence cap
+  raises ONE escalated degradation event per 30-min window instead of
+  letting the self-heal hide it.
+- **Restart with a rerouted job mid-flight** → boot reconciliation kills the
+  surviving REPL (job reruns cleanly); per-slug guard prevents concurrent
+  double-execution. Tested both.
+- **Force-mode refusal paths** (cap/memory/pipe) are loud: throw or
+  `{spawned:false}` + degradation event — never a silent drop. The pipe
+  refusal shape (`{spawned:false}` from inside `spawn()`) is pinned by test
+  because only that shape falls through to the rerouted A2A path.
+
+## Quota / cost surface
+
+- Rerouted spawns bill the subscription 5h window. Bounds: `maxRerouted`
+  (default 3) + memory-pressure pre-spawn gate + QuotaTracker backpressure
+  on A2A/pipe admission (the same gate scheduled jobs already use). The
+  worst case (window already ≥95%) denies non-critical spawns BEFORE they
+  land on the window.
+- The `auto` decision reuses PR 1's TTL-cached credit reader via
+  `setSdkCreditReader` — one credit source for both routing layers, no
+  drift.
+
+## Framework generality (launch/inject surface)
+
+The reroute is **claude-code-only by design** — it exists to dodge
+Anthropic's June-15 SDK-pot billing; codex-cli and gemini-cli headless
+spawns are untouched on every mode (V5 pin test). The launch builders are
+not modified; the reroute composes `buildInteractiveLaunch` +
+`claudeHeadlessExtraFlags`, both existing per-framework abstractions. Works
+for codex-cli/gemini-cli: yes — by explicit non-interference, pinned by
+test. The funnel lint allowlist names the two legitimate
+`buildHeadlessLaunch` callsites; a future framework adding a third must
+justify it at review.
+
+## Migration / fleet rollout
+
+- New config keys are optional with safe defaults; `migrateConfig` additions
+  are not needed (absence = off).
+- CLAUDE.md template block corrected + a NEW idempotent migration
+  (`headless job / agent-to-agent / dispatch spawns` sniff) patches the
+  already-deployed PR-1 wording on update — both PR-1 wordings ("routes
+  them" / "can route them") handled; hand-edited sections left untouched.
+  Tested (5 cases incl. idempotency).
+
+## Evidence pointers
+
+- Unit: `tests/unit/headless-spawn-reroute.test.ts` (23),
+  `tests/unit/subscription-quota-gates.test.ts` (8),
+  `tests/unit/lint-no-unfunneled-headless-launch.test.ts` (4),
+  `tests/unit/PostUpdateMigrator-subscriptionPathScope.test.ts` (5),
+  `tests/unit/job-scheduler-double-run-guard.test.ts` (3)
+- Integration: `tests/integration/sessions-launch-lane.test.ts` (1)
+- E2E: `tests/e2e/june15-headless-spawn-reroute.test.ts` (4 —
+  production-mirroring construction, the spawn-path "200 not 503")
+- Spec + ELI16: `docs/specs/june15-headless-spawn-reroute.md` / `.eli16.md`
+- Lint: `scripts/lint-no-unfunneled-headless-launch.js` (chained in
+  `pnpm lint`)
+
+## CI-green follow-up #2 (Zero-Failure Standard)
+
+A main-drift imbalance surfaced by this PR's CI (route-completeness:
+225 `catch (err)` vs 224 `err instanceof Error` in routes.ts — landed on
+main via a [skip ci] merge that never ran this shard). Per the Zero-Failure
+Standard ("no pre-existing failures — if you see it you own it"), fixed by
+converting one `/providers/...` route's `(err as Error).message` cast to the
+safe `err instanceof Error ? err.message : String(err)` guard — balances the
+count AND is strictly safer (an `as Error` cast lies if err isn't an Error).
+Also: the codex-model-swap structure-pin window widened past the reroute
+branch (test-only — invariant unchanged).

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.