instar 1.3.590 → 1.3.592

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-16T06:03:16.573Z",
-  "instarVersion": "1.3.590",
+  "generatedAt": "2026-06-16T08:21:53.499Z",
+  "instarVersion": "1.3.592",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/src/scaffold/templates.ts

@@ -802,8 +802,9 @@ I declare owner/blockedOn at commitment creation; a later state change goes thro
 - **Continuity guarantee** — a long session that hits its account's quota resumes on another eligible account (conversation preserved via \`--resume\`), never dies. Manual lever: \`POST /subscription-pool/swap\` \`{"sessionName":"...","exhaustedAccountId":"..."}\`. Auto-swap on rate-limit ships OFF (opt-in via \`subscriptionPool.autoSwapOnRateLimit\` — it moves a live session, real authority).
 - **Pre-limit (proactive) swap** — beyond the reactive swap above, I can move a session OFF an account BEFORE it walls, at a lag-aware measured threshold (default 80% — the polled reading trails real usage, so the swap completes with margin). It also covers the UNTAGGED interactive session (resolves its account from the default login), so the session you talk to doesn't wedge at the wall. Opt-in via \`subscriptionPool.proactiveSwap.enabled\` (same authority as auto-swap, earlier trigger). Status: \`GET /subscription-pool/proactive-swap\`; run a pass now: \`POST /subscription-pool/proactive-swap/check\`.
 - **Enroll a new account from your phone** — \`POST /subscription-pool/enroll\` \`{"id","label","provider","framework","configHome"}\` starts a login and returns a public code/URL (never a token); \`GET /subscription-pool/pending-logins\` is the surface; expired codes are auto-reissued. Mark done with \`POST /subscription-pool/enroll/:id/complete\`.
+- **Pool-aware quota brake (the global load-shed is NOT account-blind)** — the global quota throttle (\`QuotaTracker.shouldSpawnSession\`) that decides "can I run work right now?" gates on the **best-available account's headroom across the whole pool**, NOT a single account. So one maxed account can NEVER stop the whole agent while another account still has room — the subscription pool just places the work on the account with the most headroom. A non-authoritative/implausible usage reading (a JSONL token-estimate, or any value >100%) **fails open** rather than slamming the brake on a guess. (A solo, single-account agent keeps the exact legacy single-account gating.) The collector folds every account's live usage into \`quota-state.json\` → \`accounts[]\` so the brake can see the whole pool.
 - **Dashboard**: the **Subscriptions tab** shows live quota bars (5h + weekly + reset countdown), status, and the Pending Logins panel — share the dashboard URL + PIN.
-- **When to use** (PROACTIVE): "how much quota is left across my accounts?" / "am I about to hit a limit?" → \`GET /subscription-pool\`; the user wants to add another subscription → drive the enrollment wizard (never ask them to paste a token); a long job is at risk of a quota wall → the continuity guarantee + \`/swap\` keep it alive. Single-account pools are a no-op.
+- **When to use** (PROACTIVE): "how much quota is left across my accounts?" / "am I about to hit a limit?" → \`GET /subscription-pool\`; the user wants to add another subscription → drive the enrollment wizard (never ask them to paste a token); a long job is at risk of a quota wall → the continuity guarantee + \`/swap\` keep it alive. **"Why didn't the agent stall / get stuck with one account maxed out?"** → the pool-aware quota brake above: it only stops work when EVERY account in the pool is at capacity, so idle accounts get used instead of the agent halting. Single-account pools are a no-op.
 
 **Live Credential Re-pointing (move a pool account's login between config-home "slots" without restarting — WS5.2)** — Beyond the subscription pool's session-MOVING, this MOVES the credential itself: it exchanges which pool account's OAuth login sits in which config-home "slot" via a staged keychain swap, so the sessions already reading that slot pick up the new account on their NEXT API call — no restart, no re-login, nothing on your screen. The unit shuffled is the CREDENTIAL (always a clean SWAP between two slots, never a copy — one home per credential), verified by identity after every move (quarantine-never-repair when the identity oracle can't confirm). **On a development agent it runs LIVE in dry-run** (the developmentAgent gate, \`subscriptionPool.credentialRepointing.enabled\` omitted → resolves live-on-dev / dark-fleet) — the \`/credentials/*\` levers return real data and the balancer runs its full decision loop, but the executor performs ZERO credential writes while \`dryRun\` holds (the write-safety canary; on the fleet every lever 503s). Actually MOVING a credential needs a deliberate \`dryRun:false\` — that decision is yours (gated behind running the §5 livetest battery first).
 - **Which account is in which slot?** (Registry First — read it, never guess) \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/credentials/locations\` → the ledger census (slot ↔ account, since, lastVerifiedAt, quarantine state, journal tail, mode).

package/upgrades/1.3.591.md

@@ -0,0 +1,34 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed a boot-ordering bug that left the cross-machine `OwnershipApplier` permanently
+un-wired: a topic moved between machines was reported moved but the destination never took
+ownership, so the conversation went silent on arrival. The applier's on-switch now depends on
+the durable ownership store alone (extracted into a testable `wireOwnershipApplier` factory),
+and the machine id it uses for logging is late-bound, so the wiring can't be broken by code
+reordering. Caught by applying the Live-User-Channel Proof gold standard to a real
+Laptop→Mini transfer (the second, deeper bug after the dev-gate-darkness fix in v1.3.590).
+
+## What to Tell Your User
+
+If you move a conversation between your machines, the destination now genuinely takes over and
+answers there. Before this, a moved conversation could report success but then go quiet on the
+new machine, because the new machine never realized it owned the conversation. Single-machine
+setups are unaffected.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Moving a conversation between machines actually lands it on the destination | Move a topic to another machine as usual; the destination now takes ownership and serves it |
+
+## Evidence
+
+- 6 new unit/wiring tests (`tests/unit/ownershipApplierWiring.test.ts`) + 7 existing applier
+  tests stay green; tsc clean.
+- Release gate: a live two-machine re-run asserts the destination materializes the seat and a
+  reply serves from it (Telegram + Slack).

package/upgrades/1.3.592.md

@@ -0,0 +1,40 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The global quota brake (`QuotaTracker.shouldSpawnSession`) was account-blind: it stopped the WHOLE agent
+on a single account's usage, so when one Claude account hit its weekly limit the agent froze even though
+other pooled accounts sat at 0% (the 2026-06-15 "two accounts untouched while work stalls" incident; a
+degraded JSONL estimate reading 186% jammed it harder). It now reasons over the whole pool by asking the
+placement layer's OWN `selectAccount` predicate (via a provider wired in `server.ts`): the brake never
+halts the agent while a placeable account has headroom, and never allows work placement can't land — the
+90–95% "allowed-but-unplaceable" respawn-loop band is closed by construction (`allowed ⟹ placeable`).
+Missing/implausible/degraded readings trigger a BOUNDED mode (shed low priority, allow medium+, honor an
+authoritative 5-hour wall) instead of a stall or unbounded fail-open.
+
+## What to Tell Your User
+
+If you run several Claude accounts pooled together, the agent no longer freezes when one account hits its
+weekly limit — it keeps working on the accounts that still have room, and it won't get stuck in the
+"session respawned" restart loop. Single-account agents are completely unaffected (byte-identical
+behavior). Nothing to configure; it's on by default because it removes a bug.
+
+## Summary of New Capabilities
+
+- `QuotaTracker.setPoolQuotaProvider()` — the brake shares placement's exact eligibility predicate, so a
+  maxed account can never stop the whole agent while a placeable account exists.
+- Bounded degraded-data handling (shared by the pool and single-account paths): non-authoritative /
+  out-of-range / missing readings shed low priority and allow medium+, instead of stalling or running blind.
+- The "use-it-or-lose-it" optimizations (drain near-reset accounts first, burn-rate balancing) are the
+  tracked SECOND PR — this one is the robust+safe foundation.
+
+## Evidence
+
+Converged over 3 `/spec-converge` rounds (6 internal reviewers + codex GPT-5.5); the first two designs were
+rejected by review (one dead in production, one with a staleness/loop gap) and redesigned. 253 quota tests
+pass with no regressions, including a test proving `allowed ⟹ placeable` across a 0→100 usage sweep and the
+90–95% band → stop. Spec: `docs/specs/POOL-AWARE-QUOTA-THROTTLE-SPEC.md`. Acceptance: the two previously-idle
+accounts demonstrably carry load after the fix (live proof).

package/upgrades/side-effects/ownership-applier-meshself-ordering-fix.md

@@ -0,0 +1,52 @@
+# Side-Effects Review — OwnershipApplier mesh-self ordering fix
+
+**Slug:** ownership-applier-meshself-ordering-fix
+**Spec:** docs/specs/ownership-applier-meshself-ordering-fix.md
+**Parent principle:** Wiring Integrity — a dependency-injected component must actually run, not be a silently-skipped no-op.
+
+## What changed
+
+A boot-ordering bug in `src/commands/server.ts` meant the transfer-fix §7.2 `OwnershipApplier`
+was never constructed or ticked at runtime (its guard read `_meshSelfId` ~650 lines before
+the boot sequence assigns it, so the guard was always false). Result: a topic transferred
+between machines was recorded on the SOURCE and replicated to the DESTINATION's journal, but
+the destination never materialized ownership → it never knew it owned the session → the seat
+died on arrival. Caught by applying the Live-User-Channel Proof gold standard to a real
+Laptop→Mini transfer.
+
+Fix (order-independent — Structure > Willpower):
+- `src/core/OwnershipApplier.ts` — `selfMachineId` accepts a late-bound getter (label-only;
+  materialization never needs it); resolved per-tick instead of captured stale at construction.
+- `src/core/ownershipApplierWiring.ts` (new) — `wireOwnershipApplier()` factory gates
+  construction on the durable store ALONE (the correct condition), extracted so the invariant
+  is unit-testable (the inline condition was untestable, which is how the bug shipped).
+- `src/commands/server.ts` — calls the factory in place of the inline guard.
+
+## Blast radius
+
+- **Multi-machine destinations (the target):** a transferred seat now materializes durable
+  ownership on the destination and is served there. This was BROKEN before — net improvement.
+- **Single machine:** the durable store may be active but there are no peer placements; the
+  applier ticks and finds nothing — a harmless no-op. No behavior change.
+- **Transfer SOURCE:** unchanged (it writes ownership directly via the tclaim path).
+- **No new route, config flag, state schema, URL, or migration.** Pure internal wiring +
+  one new internal module (no agent-facing surface → no CLAUDE.md template change required).
+- **Backward compatibility:** `OwnershipApplier`'s `selfMachineId` still accepts a plain
+  string; all existing callers/tests are unaffected (7 existing applier tests stay green).
+
+## Reversibility
+
+No flag (it only activates the durable-ownership path that already ships pool-consistent for
+replication-on pools / dark for single-machine). Revertable by reverting the three-file diff;
+no durable state is written that would outlive a revert (ownership records are re-derived from
+the replicated journal on the next tick).
+
+## Risk / monitoring
+
+Low. The applier is off the hot path (boot tick + 15s interval), never throws (degrades to
+"materialized fewer this tick"), and fast-forward-CAS guards against clobbering a fresher
+local decision. Observable via `[ownership-applier] materialized …` / `[OwnershipApplier]
+materialized N/M …` in `logs/server.log` — their appearance is itself the proof the wiring is
+now alive (the bug's signature was their total absence). Release gate: the live two-machine
+re-run (deploy both → transfer → assert destination materializes + a reply serves from the
+destination).

package/upgrades/side-effects/pool-aware-quota-throttle.md

@@ -0,0 +1,123 @@
+# Side-Effects Review — Pool-Aware Quota Throttle
+
+**Version / slug:** `pool-aware-quota-throttle`
+**Date:** `2026-06-16`
+**Author:** `echo`
+**Second-pass reviewer:** spec-converge multi-reviewer panel (6 internal + codex GPT-5.5), 3 rounds — see docs/specs/reports/POOL-AWARE-QUOTA-THROTTLE-convergence.md
+
+## Summary of the change
+
+Makes the global quota brake (`QuotaTracker.shouldSpawnSession`) pool-aware. Instead of stopping the
+whole agent when ONE account's usage is high, it consults a new `poolHeadroom` helper in the placement
+module (via an injected provider wired in `server.ts`). `poolHeadroom` shares `selectAccount`'s EXACT
+eligibility predicate — so `placeable ⟺ selectAccount() !== null` (the never-loop invariant) — but
+gates on the MOST-HEADROOM eligible account, so non-critical work runs whenever ANY account has room
+(the 2026-06-16 live-proof fix: gating on `selectAccount`'s use-it-or-lose-it drain-first winner
+wrongly shed medium/autonomous work even with a fresh 0% reserve). Placement (`selectAccount`) still
+drains the soonest-to-reset account. A non-authoritative/implausible/missing reading triggers a
+BOUNDED degraded mode (shed low priority, allow medium+, honor an authoritative 5h wall) rather than
+an unbounded fail-open or a whole-agent stall. Files: `src/monitoring/QuotaTracker.ts` (provider +
+bounded helper + data-quality guard), `src/core/QuotaAwareScheduler.ts` (the shared `poolHeadroom`
+helper), `src/commands/server.ts` (wiring), `src/scaffold/templates.ts` (CLAUDE.md awareness).
+Decision point: the spawn/job quota gate.
+
+## Decision-point inventory
+
+- `QuotaTracker.shouldSpawnSession` (the spawn/job quota brake) — **modify** — now reasons over pool
+  placeability (shared with placement's `selectAccount`) instead of a single account's usage; adds a
+  bounded degraded mode. This is the only decision surface touched.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The change REDUCES over-block — its whole purpose is to stop the brake from falsely halting the agent
+when fresh accounts exist. New possible over-block: if EVERY account is status `rate-limited` (not
+just high-usage), `selectAccount` returns null → STOP. This is correct (placement genuinely can't
+land), and it is NOT latched — it re-evaluates every call and self-clears when a window resets. The
+bounded degraded mode sheds `low` priority during untrustworthy readings — intended, conservative.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+A throttle "allow" guarantees placeability AT DECISION TIME; a concurrent spawn could consume the last
+account before placement runs — placement then returns null, which the caller handles as a normal
+back-off (NOT the old respawn loop, which came from throttle/placement disagreeing — now impossible).
+The provider trusts the pool's own quota-poll freshness (same data placement already relies on); a
+genuinely stale-but-present reading is the pool layer's concern, not newly introduced here.
+
+## 3. Level-of-abstraction fit
+
+The fix lives in the existing quota-gating module (`QuotaTracker`) and the existing server wiring —
+the correct layer. It reuses placement's `selectAccount`/`bindingUtilization` rather than duplicating
+eligibility logic, so there is one source of truth for "is this account placeable."
+
+## 4. Signal vs authority compliance
+
+`QuotaTracker` is an EXISTING authority (it gates real spawns). The change does not add a new brittle
+blocking check — it makes the existing authority's decision pool-aware and adds fail-open/bounded
+behavior in the safe direction. Fail-open on degraded data is exactly the Signal-vs-Authority guidance
+(don't let an expensive false-positive stop everything). Lessons-aware reviewer confirmed PASS across 3
+rounds.
+
+## 5. Interactions
+
+- **Placement (`QuotaAwareScheduler.selectAccount`):** now shared by the throttle — by construction
+  they cannot diverge (closes the respawn-loop band). No change to selectAccount itself.
+- **SubscriptionPool:** read-only (`list()`); no mutation.
+- **QuotaCollector / QuotaManager:** unchanged (the earlier collector edit was reverted). The file
+  path (single-account / legacy) is byte-identical except the bounded degraded mode.
+- **Scheduler / can-start / spawn gates:** all consume `shouldSpawnSession`/`canRunJob` and benefit
+  automatically; no signature change.
+
+## 6. External surfaces
+
+No new routes, no new config keys, no new dashboard surface. The only user-facing surface is the
+CLAUDE.md template awareness blurb (additive). No external network calls added (the provider reads the
+in-memory pool synchronously).
+
+## 6b. Operator-surface quality
+
+No operator-facing UI/route changes. The behavior the operator observes ("the agent no longer freezes
+when one account maxes out; idle accounts get used") is the intended improvement, documented in the
+CLAUDE.md awareness section so an agent can explain it conversationally.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** `quota-state.json` and the SubscriptionPool the throttle reads are
+per-machine: each host polls its own account credentials and places sessions locally. Replicating
+would be wrong (machine A's stale view would gate machine B's spawns). The existing
+`GET /subscription-pool?scope=pool` is the unchanged cross-machine quota surface. No durable state is
+introduced that could strand on a topic transfer. Documented in the spec's "Multi-machine posture"
+section.
+
+## 8. Rollback cost
+
+Low. Pure code change, no persisted-state migration. Disable per-agent by leaving the provider unset
+(or `setPoolQuotaProvider(undefined)`) → file-based gating returns. Full revert = revert the commit +
+rebuild + restart sessions. Solo (single-account) agents are unaffected (no provider wired). No
+dark-gate flag (this is a correctness fix, default-on, fail-safe — the prior behavior was the bug).
+
+## Conclusion
+
+The change removes a false-positive whole-agent halt, shares placement's exact eligibility so the
+throttle and placer can't diverge (no respawn loop), and bounds degraded-data behavior in the safe
+direction. Reviewed to convergence over 3 rounds (the first two designs were rejected and redesigned).
+All three test tiers green; 253 quota tests pass with no regressions.
+
+## Second-pass review (if required)
+
+Done — the spec-converge panel (6 internal reviewers + codex GPT-5.5 external) served as the
+multi-reviewer second pass across 3 rounds; both high-signal reviewers returned "CONVERGED — no
+material findings" in the final round. Concurred: true.
+
+## Evidence pointers
+
+- Spec: `docs/specs/POOL-AWARE-QUOTA-THROTTLE-SPEC.md` (review-convergence + approved)
+- ELI16: `docs/specs/POOL-AWARE-QUOTA-THROTTLE-SPEC.eli16.md`
+- Convergence report: `docs/specs/reports/POOL-AWARE-QUOTA-THROTTLE-convergence.md`
+- Round-1 findings: `docs/specs/reports/POOL-AWARE-QUOTA-THROTTLE-round1-findings.md`
+- Tests: `tests/unit/quota-tracker-pool-aware.test.ts`, `tests/unit/quota-tracker-invalid-input.test.ts`, `tests/integration/pool-aware-quota-canstart.test.ts`