instar 1.3.64 → 1.3.66

package/upgrades/1.3.65.md

@@ -0,0 +1,67 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Fixed a runaway credit-burn bug: LLM call loops no longer keep hammering the
+provider after you hit a usage or spend limit.**
+
+Instar runs small background LLM calls to watch your sessions (for example, the
+per-tick check that detects when a session is blocked on a prompt). Until now,
+if one of those calls came back with a usage/rate/spend-limit error, the loop
+swallowed the error and tried again on the very next tick — with no backoff. If
+your account had auto-reload turned on, each retry refueled and re-burned. A
+real agent in the wild burned $452 of $455 in usage credits this way over a
+couple of days before anyone noticed.
+
+There is now an **account-global circuit breaker** in front of every internal
+LLM call. The moment the provider reports a usage/rate/spend limit, the breaker
+opens and *all* background LLM-backed work pauses — without spawning another
+`claude` subprocess, so it costs nothing while paused. After a cool-down window
+(15 minutes by default) it sends exactly one quiet probe; if the limit has
+lifted it closes and resumes automatically, and if not it waits another window.
+It is wired at the single provider-construction chokepoint, so every feature —
+current and future — is covered with no per-feature work.
+
+This is reactive (it listens to the provider's own "you're over limit" signal)
+and complements the existing volume-based burn-detection, which reacts to
+statistical token-share over a longer window.
+
+## What to Tell Your User
+
+Your agent can no longer burn through your credits by repeatedly calling the
+model after you've hit a usage or spend limit. The instant the provider says
+you're over your limit, background model work pauses on its own, costs nothing
+while paused, and quietly resumes once the limit lifts. This is on by default —
+no setup needed. If you ever want to tune the cool-down window or turn it off,
+there's an optional circuit-breaker setting in your config, but the safe
+defaults are designed to just work.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Account-global LLM rate-limit circuit breaker | Automatic. When the provider returns a usage/rate/spend-limit error, all background LLM-backed work pauses (no subprocess spawned) and self-heals via a single probe after the cool-down. |
+| Tunable cool-down / kill switch | Optional `intelligence.circuitBreaker` in `.instar/config.json`: `enabled` (default true) and `openMs` (default 900000 = 15 min). Absent config uses the safe defaults, so existing agents are protected with no changes. |
+
+## Evidence
+
+**Reproduction (the incident pattern), reproduced as an automated test:** a fake
+`claude` binary that records each spawn to an on-disk counter and exits with
+"Claude AI usage limit reached" on stderr.
+`tests/integration/llm-circuit-breaker-chokepoint.test.ts` builds two providers
+through the real `buildIntelligenceProvider` factory and drives them:
+
+- Before fix (old behaviour): every `evaluate()` call spawns the binary →
+  unbounded spawns while limited (this is exactly the $452 burn).
+- After fix (observed in the test): the first call spawns once and trips the
+  breaker; the next 5 calls — and a call through a *second, independently built*
+  provider — all reject with `LlmCircuitOpenError` and the spawn counter stays
+  at **1**. Zero additional subprocesses, proving the burn is stopped and the
+  breaker is account-global.
+
+39 new circuit-breaker tests pass (state machine both-sides-of-boundary, the
+rate-limit classifier on true-positive and unrelated-error strings, and the
+chokepoint wiring). `tsc --noEmit` clean. The server log emits
+`[llm-circuit] OPEN: …` / `[llm-circuit] closing: …` lines on each transition.

package/upgrades/1.3.66.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+Added `CollaborationRedriveEngine` — a small, off-by-default monitor that fills the one verified gap in cross-agent collaboration continuity: nothing today proactively re-engages a counterpart when **they** go silent on an unfinished objective. Spec `docs/specs/collaboration-redrive-on-counterpart-silence.md` (approved by Justin 2026-05-28 after a 2-round adversarial convergence). It builds on the already-shipped Threadline Conversation Keystone (`WarrantsReplyGate` loop-safety + `ConversationStore` continuity + `CompletionEvaluator` done-judgment) — it is **not** a rebuild of any of those.
+
+The engine sweeps active `threadline-reply` commitments on its own 5-minute cadence (NOT the PromiseBeacon tick, which only schedules beacon-enabled commitments) and, for each unfinished objective whose counterpart has been silent past a threshold, sends one bounded peer nudge. The termination guarantee is a **durable, monotonic, reply-INDEPENDENT** per-commitment counter (`redriveCount` on the Commitment record) — a counterpart reply updates `lastReplyAt` but never touches the counter, closing the mutual-re-drive hole the round-1 adversarial review caught. After the per-commitment cap (default 2), the engine raises ONE Attention-queue item and goes terminal-quiet on that commitment. Independent per-peer 24h cap, engine-wide daily fuse, per-tick fuse, finite-timestamp validation, and skip-don't-increment on name→fingerprint resolution miss provide defence-in-depth.
+
+## What to Tell Your User
+
+- I can now nudge another agent once or twice if they go quiet on something we're working on together, then I shut up and surface it to you — never a loop.
+- It ships **OFF**. To turn it on for me, flip the collaboration-redrive enabled setting in my config to true. The other tunables (silence threshold, max nudges, per-peer cap, daily fuse) all have safe defaults.
+- It only triggers on commitments I already have for "I'm waiting on agent X to do thing Y", so it has no effect outside that surface.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Proactive peer re-drive on counterpart silence | Set `monitoring.collaborationRedrive.enabled: true` (defaults: 45-min silence threshold, max 2 nudges per objective, escalate to Attention queue then stop) |
+
+## Evidence
+
+- Tier-1 unit tests cover both sides of every eligibility boundary (terminal status, NaN/future timestamp, silence threshold, cap, spacing window, missing peer), the load-bearing reply-independent cap (the round-1 adversarial fix), restart-survival across a fresh `CommitmentTracker` load, name-unresolved skip-don't-increment, and disabled-mode no-op.
+- New fields on `Commitment`: `redriveCount?: number`, `lastRedriveAt?: string`, `lastRedriveText?: string` — additive and optional; `loadStore()` backfills `redriveCount: 0` on existing rows alongside the existing `correctionCount`/`escalated` backfill.
+- Side-effects review: `upgrades/side-effects/collaboration-redrive-engine.md`.
+- Spec convergence: `docs/specs/reports/collaboration-redrive-convergence.md` (2 review rounds; round 1 caught a real mutual-re-drive hole reopening the ack-loop blast radius and was fixed by switching to a reply-independent durable cap; round 2 caught a fingerprint-resolution wiring bug and was fixed).

package/upgrades/side-effects/collaboration-redrive-engine.md

@@ -0,0 +1,36 @@
+# Side-Effects Review — CollaborationRedriveEngine
+
+**Spec:** `docs/specs/collaboration-redrive-on-counterpart-silence.md` (approved 2026-05-28)
+**Change:** add `src/monitoring/CollaborationRedriveEngine.ts`; add `redriveCount`/`lastRedriveAt`/`lastRedriveText` optional fields to `Commitment`; backfill in `loadStore()`; default new threadline-reply commitments with `redriveCount: 0`; wire construction into `src/commands/server.ts` after `completionEvaluator` (ships OFF).
+
+## 1. Over-block / under-block
+**Over-drive:** nudging a counterpart who is legitimately working. Mitigated by the `CompletionEvaluator` "objective-met" gate (auto-closes the commitment instead of nudging), the silence threshold, the per-commitment cap, the per-peer/daily/per-tick fuses, and (decoratively) the novelty tiebreaker. The cap biases toward UNDER-drive (stop + escalate), which is the safe direction.
+**Under-drive:** never nudging → that is today's gap and the thing this fixes. The ship-OFF default is the strongest under-drive bias; we dogfood-on-Echo before any rollout.
+
+## 2. Level-of-abstraction fit
+Composes existing primitives — no new transport, no new persistence store. Reads/writes existing `Commitment` records via `mutate()`; sends via the same `threadlineRelayClient.sendPlaintext` the inbound auto-ack path uses; surfaces via the existing `CollaborationSurfacer.notify`; escalates via `telegram.createAttentionItem` (injected `raiseAttention`). The engine is a small monitor sibling to `PromiseBeacon` / `CommitmentTracker`.
+
+## 3. Signal vs Authority
+Stall + not-met are SIGNALS. The bounded nudge is a limited action with a hard cap. The OPERATOR holds terminal authority — when the cap is hit, the engine raises an Attention-queue item ("collaboration with <peer> stalled — your call") and goes silent. The engine cannot decide to keep going past the cap.
+
+## 4. Interactions
+- `CommitmentTracker`: adds optional fields; uses `getActive()` + `mutate()` + `markReplyArrived()` (already only-touches-`lastReplyAt`).
+- `PromiseBeacon`: independent. The engine runs its OWN sweep so most threadline-reply commitments (which are NOT beacon-enabled) are still covered.
+- `WarrantsReplyGate`: the peer's gate suppresses our nudge if it's pure-ack; the engine sends concrete questions/next-steps so it warrants reply (convergence-driving by construction).
+- `CollaborationSurfacer`: visibility-only — silent hub posts; does not buzz the operator.
+- Attention queue (`telegram.createAttentionItem`): used only at cap-hit + after N consecutive name-resolution misses.
+
+## 5. Rollback
+Ships OFF (`monitoring.collaborationRedrive.enabled: false`); flipping back to false fully disables. The new fields are additive/optional — no destructive data transform; the only "migration" is an idempotent backfill defaulting `redriveCount: 0` on existing rows (safe to remove — would just read back as `undefined`, which the engine treats as 0).
+
+## 6. Data integrity
+The only mutation to existing Commitment lifecycle semantics is the auto-close on objective-met (transitions `pending → delivered`), which is a documented terminal transition this engine is now authorised to make. All other writes are to the new additive fields. The cap and spacing live durably on the commitment record (via `mutate()`), not in PromiseBeacon hot-state, so they survive restart.
+
+## 7. Failure modes
+- **Runaway nudges (incl. mutual re-drive):** bounded by the durable reply-independent cap + per-peer 24h cap + engine-wide daily fuse + per-tick fuse. The cap is the ONLY termination guarantee; novelty is decorative. Tested.
+- **Restart amnesia:** cap/spacing persisted to `commitments.json` via `mutate()`. Restart-survival test required and present.
+- **Clock jump / sleep-wake burst:** per-tick fuse + `Number.isFinite` validation + injectable `now()`. NaN/future timestamps disqualify, fail-safe.
+- **Peer ack-storm in response:** the peer's own `WarrantsReplyGate` suppresses inbound; our durable cap stops our side regardless of replies.
+- **Wrong-peer send:** name→fingerprint resolved via `known-agents.json`; unresolved or ambiguous names skip + don't increment + escalate after N strikes. A send is never attempted against a guessed address.
+- **Re-drive while operator is mid-conversation:** visibility surfaces silently to the Threadline hub; never the active parent topic. Cap-hit escalates to the Attention queue, which the operator opens on their own schedule.
+- **Evaluator unreachable:** errs to "not met" (keep waiting); an evaluator exception never produces an uncounted nudge — but the engine does NOT nudge on evaluator-throw this tick (the evaluator failure short-circuits the eligible path).

package/upgrades/side-effects/llm-ratelimit-circuit-breaker.md

@@ -0,0 +1,75 @@
+# Side-effects review — account-global LLM rate-limit circuit breaker
+
+**Scope**: Stop the runaway credit-burn failure mode where an LLM-call loop
+keeps invoking the provider after the account is over its usage/spend limit.
+Motivating incident (2026-05-28): a wild agent burned $452/$455 because
+PromptGate's per-tick Haiku detection loop kept spawning `claude -p` against
+the weekly-limit screen with no backoff on the rate-limit error; the account's
+auto-reload refueled the burn each cycle.
+
+Distinct from — and complementary to — the existing volume-based
+token-burn-detection system (BurnDetector + LlmRateGate, ~30-min statistical
+reaction). This breaker reacts in milliseconds to the provider's OWN rate-limit
+signal: once the provider says "over limit," every further call is wasted
+(rejected) or harmful (auto-reload), so we stop immediately.
+
+**Files touched**:
+- `src/core/LlmCircuitBreaker.ts` — NEW. Account-global breaker
+  (closed/open/half-open, single-probe invariant, configurable open window,
+  default 15 min) + the pure exported `isRateLimitError()` classifier + typed
+  `RateLimitError` / `LlmCircuitOpenError` + process singleton + `configure()`.
+- `src/core/CircuitBreakingIntelligenceProvider.ts` — NEW. Decorator that gates
+  every `evaluate()` on the breaker BEFORE delegating; trips on rate-limit,
+  closes on any other outcome; `wrapIntelligenceWithCircuitBreaker()` helper
+  (null-safe, idempotent).
+- `src/core/intelligenceProviderFactory.ts` — wrap every provider the factory
+  returns (the single chokepoint).
+- `src/commands/server.ts` — `configureLlmCircuitBreaker()` from config at
+  startup; wrap the three direct `new ClaudeCliIntelligenceProvider` fallback
+  sites.
+- `src/commands/reflect.ts` — wrap its direct fallback site.
+- `src/core/ClaudeCliIntelligenceProvider.ts` / `CodexCliIntelligenceProvider.ts`
+  — widen the captured stderr slice 200 → 600 so the rate-limit phrase isn't
+  truncated before classification.
+- `src/core/types.ts` — optional `intelligence.circuitBreaker` config block.
+- Tests: `tests/unit/LlmCircuitBreaker.test.ts` (31),
+  `tests/unit/CircuitBreakingIntelligenceProvider.test.ts` (6),
+  `tests/integration/llm-circuit-breaker-chokepoint.test.ts` (2, real subprocess
+  spawn-counter proof of account-global short-circuit).
+
+**Under-block** (does it fail to stop something it should?): The breaker only
+trips on errors the classifier recognizes as usage/rate/spend limits. If a
+provider emits limit language the classifier doesn't match, the loop is not
+stopped by THIS layer — but the volume-based BurnDetector remains the backstop.
+The classifier is deliberately broad (429/402, "rate limit", "usage limit",
+"quota", "limit reached/resets", "credit balance too low", "payment required",
+"exceeded …"), and the stderr-slice widening reduces truncation misses.
+
+**Over-block** (does it stop something it shouldn't?): A false positive trips
+the breaker and degrades ALL LLM-backed features (PromptGate, PresenceProxy,
+PromiseBeacon, sentinels, reviewers) to heuristic-only for one open window
+(default 15 min), after which a single probe self-heals. The classifier
+excludes generic error/timeout/ENOENT/parse text to avoid this. Worst case from
+a false trip is bounded, reversible, and self-healing — and is strictly safer
+than the unbounded credit burn it prevents. A non-rate-limit error during a
+probe closes the breaker (does not keep features down on unrelated errors).
+
+**Level-of-abstraction fit**: The breaker is wired at the IntelligenceProvider
+construction chokepoint, so every current and future consumer is covered without
+per-consumer code (Structure > Willpower). Consumers that already swallow
+provider errors (PromptGate's silent fallback) swallow `LlmCircuitOpenError`
+too — the desired behaviour: skip the LLM step at zero subprocess cost.
+
+**Signal vs authority**: No new blocking authority over jobs/messages/sessions.
+The breaker only gates LLM dispatch in reaction to the provider's own response.
+It does not decide policy; it enforces "the provider said no."
+
+**Migration / fleet reach**: Pure `src/` code shipped via the normal release →
+AutoUpdater path. The protection is default-ON and reads config defensively with
+built-in defaults, so it reaches every existing agent on the version bump with
+NO config migration required. No agent-installed file (hooks/settings/CLAUDE.md
+template/skills) changed → no PostUpdateMigrator entry needed.
+
+**Rollback**: `intelligence.circuitBreaker.enabled: false` in `.instar/config.json`
+makes the breaker a transparent passthrough. Full revert is a code revert of the
+additive files.