instar 1.3.90 → 1.3.92

package/upgrades/side-effects/session-pool-track-e-router.md

@@ -0,0 +1,23 @@
+# Side effects — Track E part 2: SessionRouter dispatch engine + deliverMessage (§L4)
+
+## What this adds
+The L4 inbound-message dispatch engine, shipped DARK (constructed/activated only when `multiMachine.sessionPool.enabled` — boot wiring + the live-ingress interception land in Track E part 3 / Track H's staged rollout). No runtime behavior change for any deployed agent.
+
+- `src/core/SessionRouter.ts` — `route(InboundMessage): Promise<RouteOutcome>`. Resolves session ownership and dispatches per §L4:
+  - owned+alive+self → handle locally (no MeshRpc hop);
+  - owned+alive+remote → forward via `deliverMessage` over MeshRpc (idempotent on `messageId`; the router treats the platform offset as advanceable ONLY after the owner's `queued`/`duplicate` ACK — `RouteOutcome.acked`);
+  - owner dead / retries exhausted → owner-dead re-placement (mark suspect → re-place → claim);
+  - transient (placing/transferring) → queue (ownership-contention);
+  - unowned → `PlacementExecutor.decide()` → SYNCHRONOUS CAS-claim → spawn on the winner (CAS-loss → re-read → forward to confirmed owner / queue).
+  - Per-session ordering: strictly in-order, at-most-one-in-flight (a per-session promise chain); different sessions dispatch concurrently. All I/O is injected (deterministic, unit-testable); the `deliverMessage` dep owns its own per-attempt timeout (throws on timeout) and the router owns the retry/backoff/fallback loop.
+- `src/core/MeshRpc.ts` — added the `deliverMessage` command to the `MeshCommand` union (`{ session, messageId, payload, ownershipEpoch }`) and its RBAC (router-only, alongside place/transfer). This is the §L4 owner-forward command carried inside the §L0 signed, recipient-bound, replay-protected envelope.
+
+## Risk / blast radius
+None at runtime — `SessionRouter` is not yet imported by any boot path, and the new `deliverMessage` command type is inert until a handler is registered (part 3). The MeshRpc union/RBAC addition is additive; all 27 existing mesh tests still pass.
+
+## Tests
+- `tests/unit/SessionRouter.test.ts` — 15 tests: every dispatch branch (local, remote-forward, duplicate ACK, stale-ownership re-resolve, retry-then-owner-dead, owner-dead, transient-queue, unowned place→CAS won/self/blocked/queued, CAS-lost→forward/queue) + per-session in-order/one-in-flight serialization + cross-session concurrency.
+- `tests/integration/session-router-dispatch.test.ts` — 3 tests over the REAL MeshRpc transport (signed envelopes, POST /mesh/rpc) + a REAL SessionOwnershipRegistry: deliverMessage owner-forward with offset-advance-only-after-ACK, idempotent redelivery (duplicate ACK, not re-processed), and two-router concurrent CAS → exactly-one-owner.
+
+## Follow-ups (tracked in this same Track E / Track H)
+Part 3: register the `deliverMessage` receive handler (owner-side MessageProcessingLedger dedupe) on the boot mesh dispatcher, construct SessionRouter behind the dark flag, expose on RouteContext, add the Tier-3 "router alive when enabled" E2E + agent-awareness (nickname-transfer) blurb. Live-ingress interception ("consult placement instead of always spawning locally") is gated by Track H's StageAdvancer — the designed dark-ship rollout boundary, not a deferral.

package/upgrades/side-effects/session-pool-track-f-config.md

@@ -0,0 +1,12 @@
+# Side effects — Track F part 2: transfer integration + §L5 config tunables
+
+## What this adds
+- Tier-2 integration coverage (`tests/integration/transfer-orchestrator-ownership.test.ts`) of the TransferOrchestrator driving the REAL SessionOwnershipRegistry transfer FSM + REAL verifyLedgerSnapshot — no production code change there, it's test-only.
+- `src/config/ConfigDefaults.ts` + `src/core/types.ts` — the §L5 transfer/handoff tunables added to the dark `sessionPool` block: `transferDrainTimeoutMs` (30000), `transferOutputCutoffMs` (1000), `placementCooldownMs` (300000), `topicPlacementUpdateMinIntervalMs` (10000). Added via the add-missing `applyDefaults` path so existing agents backfill ONLY the new sub-fields on update (migration parity), never clobbering tuned values.
+
+## Risk / blast radius
+None — config additions are inert (the whole sessionPool block is enabled:false / stage:dark). No behavior change.
+
+## Tests
+- `tests/integration/transfer-orchestrator-ownership.test.ts` — 2: clean S→T transfer reaches active(T)@epoch4 through the real FSM + source teardown after claim; in_flight ledger snapshot → sync-corrupted, record stays transferring(S) (no no-owner gap), T never claims, source not torn down.
+- `tests/unit/ConfigDefaults.test.ts` — extended backfill assertion: the §L5 tunables backfill into a partial sessionPool block (add-missing, operator stage preserved).

package/upgrades/side-effects/session-pool-track-f-handoff-core.md

@@ -0,0 +1,17 @@
+# Side effects — Track F part 1: Transfer/Handoff core + transfer-by-nickname (§L3/§L5)
+
+## What this adds
+Two PURE, side-effect-free cores for the L5 Session Transfer / Handoff Orchestrator, shipped DARK (no boot wiring / no live transfer yet — Track-H stage-gated activation). No runtime behavior change.
+
+- `src/core/TransferByNickname.ts` — `planTransferByNickname(command, state, sessionKey)`: turns an already-recognized NicknameCommand into a gated, validated TransferPlan. Resolves nickname→machineId; REJECTS unknown nicknames (lists valid ones — never silent mis-route); rate-limits rapid-fire transfers per topic; no-ops when already on the target; and applies the §L4 confirmation gate (offline target, or a different owner while mid-reply). This is the brain behind the headline "move this to <nickname>" swap.
+- `src/core/TransferOrchestrator.ts` — `TransferOrchestrator.transfer(req)`: drives the §L3/§L5 ordered handoff `active(S) → transferring(e+1) → drain → flush ledger → target pulls+verifies → active(T, e+2) → S-release` (claim-before-release, fenced by status+epoch; no double-run, no no-owner gap). Enforces the two timing contracts: drain bound (`transferDrainTimeoutMs` — abandon partial output, never emit past the deadline) and output exclusion (`transferOutputCutoffMs` — T holds its CONTINUATION until the cutoff since `transferring`, so the emission windows are disjoint). Abort paths: CAS-lost, sync-corrupted (escalates, does NOT claim), target-claim-failed (no release). Plus `verifyLedgerSnapshot()` — the §L5 handoff verify (SHA256 match + every entry terminal, reject any in_flight). All I/O injected → deterministic.
+
+## Risk / blast radius
+None — neither module is imported by any boot path yet. Pure functions + new tests only.
+
+## Tests
+- `tests/unit/TransferByNickname.test.ts` — 8 tests: transfer/pin, unknown-nickname rejection, rate-limit (and post-window), already-there no-op, offline + mid-reply confirmation gates.
+- `tests/unit/TransferOrchestrator.test.ts` — 10 tests: full ordered sequence, output-cutoff hold (and skip when already elapsed), drain-abandon, CAS-lost abort, sync-corrupted escalation (no claim/release), target-claim-failed (no release); verifyLedgerSnapshot accept / sha-mismatch / in-flight-reject.
+
+## Follow-ups (this Track F)
+Part 2: Tier-2 integration over the REAL transfer MeshRpc command + real SessionOwnershipRegistry transfer FSM + real ledger-snapshot verify; config tunables (transferDrainTimeoutMs, transferOutputCutoffMs, placementCooldownMs, topicPlacementUpdateMinIntervalMs) with migration parity. Live drain (SessionMigrator) + real git ledger flush + outbound mesh client are Track-H activation (D11).

package/upgrades/side-effects/session-pool-track-g-load-broker.md

@@ -0,0 +1,16 @@
+# Side effects — Track G: Multi-Agent-Per-Machine load broker + isolation (§L6)
+
+## What this adds
+Pure cores for L6 (multiple agents sharing one machine), shipped DARK (no boot wiring — consumed by the registry/router when the pool activates in Track H).
+
+- `src/core/MachineLoadBroker.ts` — `computeMachineLoad(input)`: the machine-local shared-load accounting. Sums sessions across ALL resident agents (true machine load, not just one agent's view), and — critically — does NOT trust agent self-reports for the authoritative number. It cross-checks each agent's claimed footprint against the OS-measured footprint; an agent measured to use materially MORE than it claims (the lie-idle case) is flagged `suspect-overloaded`, its placement weight reduced, and `sessionCountTrustworthy` set false (the router leans on the authoritative OS `loadAvg`). A lying agent cannot make itself look idle. Plus `checkAgentIsolation(agents)`: the L6 isolation invariant — distinct ports/identities, no nested home dirs (which would let one agent read another's state).
+
+## Risk / blast radius
+None — pure functions, not imported by any boot path yet.
+
+## Tests
+- `tests/unit/MachineLoadBroker.test.ts` — 8: cross-agent session sum, under-report → suspect-overloaded (+ untrustworthy session count), over-report not flagged (conservative), custom tolerance; isolation pass + duplicate-port/duplicate-fingerprint/nested-home detection.
+- `tests/integration/machine-load-placement.test.ts` — 1 (§L6→§L4): a machine whose agent lies idle (high OS loadAvg) is flagged suspect AND NOT selected by PlacementExecutor — the OS truth overrides the faked self-report, so a lying agent cannot attract sessions.
+
+## Activation boundary (Track-H, D11)
+The live OS sampling (process RSS by port/cmdline) + feeding the broker's output into the live MachineCapacity heartbeat are the Track-H wiring; the accounting + verification + isolation logic is fully built + tested now.

package/upgrades/side-effects/session-pool-track-h-gate-wiring.md

@@ -0,0 +1,17 @@
+# Side effects — Track H part 2b: rollout-gate boot wiring + GET /session-pool/e2e-results (§Rollout)
+
+## What this adds
+Wires the rollout gate into the live server (still dark — inert until the pool activates).
+- `src/commands/server.ts` — constructs `SessionPoolE2EResultStore` (HMAC-signed over the agent authToken, file `state/session-pool-e2e-results.json`) + a `StageAdvancer` whose `writeStageConfig` routes through `liveConfig.set(STAGE_CONFIG_PATH, stage, { stageWriteToken })` — the sole stage write path. Passed to AgentServer.
+- `src/server/routes.ts` — `GET /session-pool/e2e-results` (Bearer-auth like all routes): latest result per stage + per-row verify + total history count; 503 when the gate is dark/absent. RouteContext gains `sessionPoolE2EResultStore?`.
+- `src/server/AgentServer.ts` — passthrough option → routeCtx.
+
+## Risk / blast radius
+None — the store is read-only over the route; StageAdvancer is constructed but not driven yet (the rollout job that calls advanceTo/reconcile is a later step). The stage-write path is guarded (Track H part 2a). No behavior change while dark.
+
+## Tests
+- `tests/integration/session-pool-e2e-results-route.test.ts` — 2: 503 when dark; 200 with latest-per-stage + verification + append-only total over a real store + real route.
+- (units from part 1/2a: StageAdvancer 9, E2EResultStore 5, stageWriteGuard 6 — all green.)
+
+## Follow-ups (Track H)
+The rollout job/tick that drives StageAdvancer.advanceTo/reconcile; the CI release-boundary check; rebalance; live-ingress interception + outbound mesh client (D11 activation); real-hardware + test-as-self proof.

package/upgrades/side-effects/session-pool-track-h-mesh-client.md

@@ -0,0 +1,15 @@
+# Side effects — Track H part 4: outbound MeshRpcClient (§L0 send side, dark)
+
+## What this adds
+`src/core/MeshRpcClient.ts` — the SEND side of MeshRpc, the outbound counterpart to MeshRpcDispatcher (receive). Builds a §L0 envelope (recipient-bound, Ed25519-signed, nonce + timestamp), POSTs to a peer's /mesh/rpc, returns the typed result (maps the dispatcher's reason/status on a non-200; throws only on transport error/timeout so the caller's retry loop catches it). Per-attempt timeout via AbortController; fully injected (fetch/sign/nonce/clock).
+
+This is the activation transport (D11): it's what makes the SessionRouter's deliverMessage/spawnOnMachine deps and the TransferOrchestrator's sendTransferRpc dep live ACROSS machines.
+
+## Risk / blast radius
+None — pure transport class, not wired into the router yet (the activation step wires it as the router's outbound deps). No behavior change.
+
+## Tests
+- `tests/integration/mesh-rpc-client-roundtrip.test.ts` — 4 over a real MeshRpcDispatcher + real Ed25519 keys + loopback /mesh/rpc: full router→owner deliverMessage round-trip (200 + result + handler ran); RBAC rejection mapped (non-router → 403 not-router); replayed-nonce → 409 on the second send; transport error throws.
+
+## Status — m2m transport COMPLETE
+Send (MeshRpcClient) + receive (MeshRpcDispatcher) are both built + round-trip-proven. The remaining Track-H work is the ACTIVATION (wire MeshRpcClient as the SessionRouter's outbound deps + flip live-ingress to route through the router) + the staged real-hardware (laptop+mini) + test-as-self nickname-swap proof.

package/upgrades/side-effects/session-pool-track-h-rebalance.md

@@ -0,0 +1,13 @@
+# Side effects — Track H part 3: load-rebalance planner (§L4 Stage-3, dark)
+
+## What this adds
+`src/core/RebalancePlanner.ts` — the pure Stage-3 load-rebalance decision. `planRebalance(input, placementExecutor)` proposes a BOUNDED set of transfers off over-saturated machines (session ratio > rebalanceThresholdPercent), only for non-pinned, low-priority, off-cooldown sessions; at most one move per source per cycle (cascade guard); the target is chosen by the same PlacementExecutor.decide(reason:'rebalance') the router uses; a working copy of capacities is updated as moves are proposed so it never piles onto one target. No qualifying session ⇒ no move.
+
+## Risk / blast radius
+None — pure function, not wired into a tick yet. The caller (a heartbeat-interval rebalance tick, post-activation) performs the actual transfers via TransferOrchestrator. Evaluated ONLY on the heartbeat interval by design, never per message.
+
+## Tests
+- `tests/unit/RebalancePlanner.test.ts` — 8: moves off-saturated→free; no-move-under-threshold; never moves pinned/hard-pinned; never moves within cooldown; never moves a non-low-priority/critical session; one-move-per-source cascade cap; distinct-sessions across sources; purity.
+
+## Follow-ups (Track H — the remaining frontier)
+The heartbeat rebalance tick that drives planRebalance → TransferOrchestrator; the live-ingress interception + outbound mesh client (D11 activation); real-hardware (laptop+mini) + test-as-self nickname-swap proof.

package/upgrades/side-effects/session-pool-track-h-rollout-gate.md

@@ -0,0 +1,17 @@
+# Side effects — Track H part 1: rollout gate (StageAdvancer + E2E result store) (§Rollout)
+
+## What this adds
+The mechanical rollout gate for the staged dark→shadow→live-transfer→rebalance ladder. Pure components, shipped DARK (constructed in boot when the pool is enabled; the stage stays 'dark' until a green prior-stage E2E exists).
+
+- `src/core/SessionPoolE2EResultStore.ts` — signed, append-only log of each stage's Tier-3 E2E outcome (`StageE2EResult`). recordResult (the E2E harness is the only writer) signs each row; getLatestForStage returns the most recent (a later red supersedes an earlier green); verify() is tamper-evidence; append-only history preserved.
+- `src/core/StageAdvancer.ts` — the SOLE stage-config writer + the gate. advanceTo(stage) REFUSES (e2e-gate-not-passed) unless the prior stage's E2E is green for the CURRENT commit (missing/red/stale-commit/tampered → refused). reconcile() mechanically REVERTS to the prior stage when a live stage records red. 'dark' is the floor.
+
+## Risk / blast radius
+None — pure components, not yet wired into boot (the Config.ts stage-write guard + boot construction + GET /session-pool/e2e-results route land in part 2). No runtime behavior change.
+
+## Tests
+- `tests/unit/SessionPoolE2EResultStore.test.ts` — 5: signed record/read, latest-per-stage (red supersedes green), stage independence, tamper-evidence, missing-file/torn-line tolerance.
+- `tests/unit/StageAdvancer.test.ts` — 9: refuse-no-result / advance-on-green / refuse stale-commit / refuse red / refuse bad-signature / refuse already-at-or-past; reconcile reverts-on-red / stays-on-green / dark-floor-noop.
+
+## Follow-ups (Track H)
+Part 2: Config.ts stage-write guard (stage-write-not-permitted for non-StageAdvancer writes) + boot wiring + GET /session-pool/e2e-results + the CI release-boundary check. The real-hardware + test-as-self proof (nickname-driven mid-conversation swap) is the culmination, which also needs the live-ingress interception + outbound mesh client (D11 activation).

package/upgrades/side-effects/session-pool-track-h-stage-guard.md

@@ -0,0 +1,16 @@
+# Side effects — Track H part 2a: stage-write guard (§Rollout, Structure > Willpower)
+
+## What this adds
+The structural enforcement that `multiMachine.sessionPool.stage` is StageAdvancer-write-only.
+
+- `src/config/stageWriteGuard.ts` (NEW) — `STAGE_CONFIG_PATH`, a module-private `STAGE_WRITE_TOKEN` capability symbol, `assertStageWriteAuthorized(dotPath, token)` (throws `StageWriteNotPermittedError` / code `stage-write-not-permitted` on a stage write without the token; no-op for any other path).
+- `src/config/LiveConfig.ts` — `set(dotPath, value, opts?)` now calls the guard first. A direct runtime write to the rollout stage without the token is refused; every other config write is unaffected (opts is optional, backward-compatible). StageAdvancer's boot wiring passes the token.
+
+## Risk / blast radius
+None for existing callers — the guard only fires for the exact stage path, and `opts` is optional so all current `set()` callsites are unchanged. The stage field is already only written by StageAdvancer; this makes that structural (a stray ad-hoc write now throws instead of silently flipping the rollout).
+
+## Tests
+- `tests/unit/stageWriteGuard.test.ts` — 6: assert throws without/with-forged token, allows with token, no-op for other paths; LiveConfig refuses a direct stage write (unchanged on disk), allows it with the token, and does not gate other writes.
+
+## Follow-ups (Track H)
+StageAdvancer + E2EResultStore boot construction + `GET /session-pool/e2e-results` route + the CI release-boundary check; rebalance; live-ingress interception + outbound mesh client (D11); real-hardware + test-as-self proof.

package/upgrades/side-effects/transient-api-error-recovery-generalization.md

@@ -0,0 +1,18 @@
+# Side effects — Generalize backoff recovery to the whole transient-API-error class
+
+## What this changes
+Extends the intelligent throttle-recovery lifecycle (RateLimitSentinel) to cover ALL transient API errors (500/502/503, overloaded, timeouts, connection drops), not just rate limits — the 2026-05-29 future-proofing ask (topic 13481). Builds on the per-episode nudge re-arm (same branch).
+
+- `src/monitoring/RateLimitSentinel.ts` — new `ApiErrorClass = 'throttle' | 'transient-api'`. `report(name, trigger, { errorClass })` (default 'throttle' → fully back-compatible). Per-class backoff schedule (`transientApiBackoffScheduleMs` = [5s,15s,30s,60s,2m,5m], fast first retry) + per-class user wording in every notice. Lifecycle (backoff→resume→verify→escalate→zombie-veto) unchanged.
+- `src/core/SessionManager.ts` — the generic `TERMINAL_ERROR_PATTERNS` idle path now hands off to the sentinel via a new `apiErrorAtIdle` event when a listener is wired (production), mirroring the existing `rateLimitedAtIdle` handoff; the re-armable immediate nudge remains the fallback when no sentinel is wired (bare/test).
+- `src/commands/server.ts` — wires `sessionManager.on('apiErrorAtIdle', name => rateLimitSentinel.report(name, 'idle-error', { errorClass: 'transient-api' }))`.
+
+## Why
+A generic `API Error: 500` previously only got SessionManager's immediate single nudge — no backoff, no verify, no escalate — while the intelligent RateLimitSentinel was scoped to rate-limit/throttle only. Now a 500 rides the same proven backoff→verify→escalate lifecycle. Spec: docs/specs/SESSION-ERROR-NUDGE-REARM-SPEC.md (Part 2).
+
+## Risk / blast radius
+Low + back-compatible. `errorClass` defaults to 'throttle' so all existing rate-limit behavior is byte-identical (14 existing RateLimitSentinel tests unchanged + green). The generic-error handoff only changes behavior when an `apiErrorAtIdle` listener is wired; otherwise the (now re-armable) immediate nudge fallback runs. Future-proof: driven by the existing TERMINAL_ERROR_PATTERNS list. Server-side → deploys fleet-wide via release.
+
+## Tests
+- `tests/unit/RateLimitSentinel.test.ts` — +4 transient-api tests (fast 5s first backoff vs 30s throttle; transient-API wording; full lifecycle→recovered; state errorClass + listActive short schedule). Throttle suite unchanged.
+- `tests/unit/session-error-nudge.test.ts` — +2: generic-error idle path defers to the sentinel via apiErrorAtIdle when wired; re-armable nudge is the fallback. Plus the Part-1 re-arm + cap behavioral tests.