instar 1.3.391 → 1.3.393

package/upgrades/1.3.393.md

@@ -0,0 +1,53 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Added `SubscriptionPool` — a new file-backed registry that records an operator's
+subscription accounts, the first building block of the Subscription & Auth
+Standard (multi-account quota-aware load balancing). Each account entry carries a
+nickname, its provider and framework, a lifecycle status, and — by design — only
+the LOCATION of its login (its config home, e.g. the per-account
+`CLAUDE_CONFIG_DIR`), never any tokens. A structural guard rejects any attempt to
+store a credential-bearing field, so "store the location, not the secret" is
+enforced in code rather than by convention.
+
+A CRUD API was added behind the new `/subscription-pool` route family
+(GET / POST / PATCH / DELETE), wired through the server, AgentServer, and route
+context. The registry is file-backed (atomic write, per-record version counter),
+mirroring the existing CommitmentTracker durable-registry pattern.
+
+This ships DARK and ADDITIVE: an empty pool is a pure no-op, so single-account
+agents are unaffected. The route is deliberately classified agent-internal for
+now (it does not appear in the capabilities self-discovery surface and is not yet
+mentioned in the agent template), because a bare registry with no enrollment
+wizard or quota-aware scheduler is not a finished capability to advertise. It
+graduates to a surfaced capability when those later phases land.
+
+Coverage: 27 tests across all three tiers — unit (both sides of every validation
+boundary, the credential-rejection guard, corruption resilience), integration
+(full CRUD over real HTTP), and an e2e feature-alive check (the route answers 200
+in the dark state and supports live enroll / read-back / persisted-to-disk).
+
+## What to Tell Your User
+
+I've started building the system that lets me manage several of your
+subscriptions at once. The first piece just remembers each account by a friendly
+nickname and where it logs in — never its passwords or tokens, which stay where
+your real login tool keeps them. Nothing changes for you yet: it's switched off
+until the later pieces (logging in from your phone, and automatically switching
+accounts before one hits its limit) are ready. When you ask me to set that up, I
+can walk you through it then.
+
+## Summary of New Capabilities
+
+- **Subscription account registry** — records each subscription account (nickname,
+  provider, framework, login location, status). Stores the login location only,
+  never credentials; a structural guard rejects credential-bearing fields.
+- **Account management API** — list, add, rename/re-status, and remove accounts
+  via the new `/subscription-pool` routes (operator/internal for now).
+- **Dark + additive** — an empty pool is a no-op; existing single-account agents
+  are unaffected, and the capability stays agent-invisible until the enrollment
+  wizard and quota-aware scheduler make it user-usable.

package/upgrades/side-effects/a2a-inbound-gate-observability.md

@@ -0,0 +1,60 @@
+# Side-Effects Review — A2A Inbound Gate Observability (PR4a)
+
+**Version / slug:** `a2a-inbound-gate-observability`
+**Date:** `2026-06-07`
+**Author:** `echo`
+**Tier:** `1` (small, low-risk, behavior-preserving — pure observability)
+**Second-pass reviewer:** `not-required (Tier-1 logging-only; correctness self-owned per Tier-1-no-review)`
+
+## Summary of the change
+
+Makes `InboundMessageGate` verdicts visible in `server.log`. Previously a blocked
+inbound A2A message was **silent** — the decision lived only in the returned
+`GateDecision` and in aggregate, restart-volatile metric counters, never the log.
+That silence is the exact mechanism by which the dawn→echo remote-relay leg went
+dark for ~1.5 days unnoticed (`/threadline/peers/health` showed Dawn's fp with
+zero recorded inbound; no block line anywhere in `server.log`).
+
+`evaluate()` now emits: one `[inbound-gate] eval from=<fp12> trust=<level>
+op=<type>` line per inbound; a `[inbound-gate] BLOCK <reason> from=<fp12> …` line
+on each of the five block paths (the `insufficient_trust` line carries the
+**resolved trust level + allowed-ops**, so a fingerprint/trust-key mismatch is
+diagnosable from the log alone); and a `PASS` line on success. A private
+`logBlock(reason, fingerprint, extra?)` helper centralizes the block lines.
+
+Files: `src/threadline/InboundMessageGate.ts` (logging only),
+`tests/unit/InboundMessageGate.test.ts` (+3 observability tests),
+`docs/specs/A2A-DURABLE-DELIVERY-SPEC.md` (§6 + Tier-1 note).
+
+## Decision-point inventory
+
+- **Does it change routing / trust / rate-limit / delivery behavior?** No. Every
+  `console.log` is additive and side-effect-free; the `evaluate()` return values,
+  metric increments, and control flow are byte-for-byte unchanged. A test run
+  shows all 37 pre-existing gate tests still GREEN alongside the 3 new ones.
+- **New dependency / state / route?** None. No injected dependency added (the gate
+  still takes `trustManager`, `router`, `config`), no SQLite store, no HTTP route,
+  no config key, no `migrateClaudeMd` section → trips none of the SqliteRegistry-
+  wiring / feature-delivery-completeness / docs-coverage guard classes.
+- **Silent fallbacks?** None added — no new `try/catch`; the change is pure logging
+  (no `@silent-fallback-ok` annotations needed).
+- **Log volume / PII?** A2A inbound is low-volume (peer messages, not user chat),
+  so per-message logging is not a flood risk. Fingerprints are truncated to 12
+  chars; **no payload content** is ever logged (only reason + resolved trust +
+  allowed-ops + byte size). No secrets, no message text.
+- **Migration parity?** Ships in code via npm; existing agents receive it on the
+  normal AutoUpdater path. No agent-installed file (settings/config/hook/skill)
+  changes → no PostUpdateMigrator step required. It is internal observability, not
+  a user-surfaced capability → no CLAUDE.md template (Agent Awareness) entry.
+- **Rollback?** Trivial — revert the single source file; logging vanishes, gate
+  behavior is identical (it never depended on the logs).
+
+## Why this is correct to ship before the fix (PR4b)
+
+The drop is silent on **both** remaining hypotheses (gate-blocks-her vs
+relay-client-never-emits-for-her), so a Dawn live re-test alone cannot
+disambiguate (her prior test left zero trace) and the fix cannot be written
+without guessing. PR4a converts the next live test into a self-diagnosing event:
+a gate block prints the exact reason + resolved trust (→ trust-resolution fix), or
+no `eval` line prints at all (→ upstream relay-client fix). Observability-first is
+the verify-claim-honest path to a targeted PR4b.

package/upgrades/side-effects/subscription-pool-registry.md

@@ -0,0 +1,43 @@
+# Side-Effects Review — SubscriptionPool Registry (P1.1)
+
+## Scope of change
+
+New self-contained registry + CRUD routes + wiring. Files:
+- `src/core/SubscriptionPool.ts` (new) — the registry class + types.
+- `src/server/routes.ts` — 5 new `/subscription-pool` routes + RouteContext field.
+- `src/server/AgentServer.ts` — threads `subscriptionPool` option → RouteContext.
+- `src/commands/server.ts` — instantiates the pool, passes it to AgentServer.
+- `src/server/CapabilityIndex.ts` — classifies the prefix as INTERNAL.
+- tests (unit/integration/e2e).
+
+## Mutability / authority analysis
+
+- **No new authority.** The registry is passive metadata. It does not gate, block, spawn, kill, message, or call any external service. It cannot influence routing, session lifecycle, or any existing behavior. Nothing reads the pool yet (the scheduler that will is P1.3).
+- **Filesystem writes** are confined to a single file, `<stateDir>/subscription-pool.json`, via atomic tmp+rename. No deletes of anything pre-existing; no writes outside the agent state dir.
+- **No network calls.** P1.1 does not poll the quota endpoint or contact any provider. (That is P1.2.)
+- **No process/session effects.** Does not touch tmux, sessions, the reaper, or spawning.
+
+## Credential-handling threat model (the load-bearing concern)
+
+- The registry **must never store tokens.** Enforced structurally: `add()` and `update()` scan input (including the raw request body) for credential-bearing field names (accessToken/refreshToken/token/apiKey/secret/password/oauth/credential[s]) and throw `ValidationError` → HTTP 400. Verified from both sides by unit + integration tests.
+- Only the login **location** (config home path) is persisted. A leaked `subscription-pool.json` therefore leaks nicknames + config-home paths, never a usable credential.
+- This aligns with Anthropic's enforced ToS position (Claude OAuth tokens may only be used by the official Claude Code client): instar will drive each account through its real client pointed at the config home — it never extracts a token. The registry storing only the location keeps that invariant structural.
+
+## Failure modes considered
+
+- **Corrupt store file** → `load()` starts fresh (no credentials are lost because none are stored). Covered by a test.
+- **Concurrent writes** → per-record `version` counter supports optimistic CAS for the later scheduler; P1.1 is single-writer (server process) so no contention today.
+- **Persist failure** (disk full / EPERM) → `@silent-fallback-ok`: in-memory store remains authoritative, next write retries. Matches the CommitmentTracker pattern.
+- **Unknown/duplicate/empty inputs** → rejected with 400 + a specific message; covered both sides.
+
+## Blast radius if this is wrong
+
+Minimal. Dark + additive + agent-invisible + no authority. Worst realistic case: a malformed account row in one JSON file, which the operator can delete; no live behavior depends on the pool until later phases wire a consumer.
+
+## Migration / parity
+
+None required. No config defaults, hooks, skills, or CLAUDE.md template changes. The route ships via dist on update. The capability is deliberately not surfaced to agents yet (graduates with P1.3/P2.1).
+
+## Tier rationale
+
+Declared Tier 1 despite the structural risk-floor signal (new route + new exported class). The signals are present but the *actual* risk is low: ships dark, adds no authority, mutates no existing behavior, single confined state file, full three-tier test coverage, and the design was reviewed + decided by the operator (topic 20905) before build. The below-floor declaration is recorded for audit per the gate's design (the mind holds authority).