instar 1.3.1235 → 1.3.1237

package/upgrades/1.3.1236.md

@@ -0,0 +1,35 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+When a pinned dashboard-link edit is held or its delivery is uncertain, Instar now
+keeps the original message ID and reports the failed refresh. It no longer turns
+that failure into a brand-new dashboard post. This reduces the extra sends that
+can accumulate during repeated tunnel restarts.
+
+A confirmed missing pinned message can still be replaced, and an unchanged link
+remains a quiet no-op. Origin recording, ownership, capacity limits and recovery
+budgets remain in force. This patch does not fix false wake detection or guarantee
+delivery of a held message.
+
+## What to Tell Your User
+
+A held or uncertain pinned-link edit no longer falls back to creating a new
+dashboard post. A held refresh can still leave the existing pinned link stale
+until delivery recovers.
+
+Existing agents receive the correction through their normal update and server
+restart. No configuration change or queue reset is required.
+
+## Summary of New Capabilities
+
+- Dashboard edits preserve the existing message on held or uncertain outcomes.
+- A confirmed missing message can still be replaced; unchanged content stays quiet.
+
+## Evidence
+
+The focused unit, HTTP integration, production-Boot lifecycle and migration tests
+pass. Full-suite validation and CI are required before release.

package/upgrades/1.3.1237.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+- The Subscriptions grid now loads assisted re-login episodes from every reachable machine and binds each repair to the exact account×machine cell.
+- One **Repair sign-in** click after dashboard unlock issues a signed, exact-bounds re-mint mandate and starts the autonomous flow on the machine that owns the broken credential.
+- The target machine independently re-verifies the account, machine, episode, and mandate before acting. Ordinary API access remains insufficient.
+
+## What to Tell Your User
+
+When a Claude account needs authentication on a machine, unlock the dashboard and click **Repair sign-in** on that exact grid cell. Instar handles the routine login autonomously on the target machine. It asks for help only when the provider presents a genuine security challenge it is not allowed to bypass.
+
+## Summary of New Capabilities
+
+- Central, phone-friendly one-click repair across the machine fleet.
+- Machine-tagged repair progress and typed peer failures in one dashboard.
+- Signed cross-machine authorization with target-local point-of-use verification.
+- Single-use, 15-minute repair permissions with durable replay refusal.
+
+## Evidence
+
+- Focused dashboard, route, rendering, authority, and write-domain tests cover the one-click request, exact binding, remote episode aggregation, and deny/allow boundaries.
+- Target-side tests cover expiry, first-use consumption, replay refusal, and redelivery tombstones.
+- TypeScript build passes; full repository and remote CI remain release gates.

package/upgrades/relogin-pool-one-click.eli16.md

@@ -0,0 +1,9 @@
+# One-click Claude sign-in repair across your machines
+
+Today, a Claude account can be signed out on the Laptop while the dashboard you opened lives on the Mac Studio. The old repair feature could do the hard login work, but its approval lived on the machine with the broken account. That left an awkward gap: you could see the problem centrally without being able to fix that exact machine centrally.
+
+This change closes that gap. In the Subscriptions grid, the broken account's exact machine cell shows **Repair sign-in**. Once you have unlocked the dashboard, one click sends a short-lived, signed permission slip to that machine and starts the existing bounded repair flow there. The permission slip names the exact account, machine, repair episode, evidence snapshot, and action, so it cannot be reused for another account or for ordinary account setup.
+
+The cell continues to be useful after the first click. A safely failed repair offers **Try repair again**. Work in progress offers **Cancel repair**. If the repair feature is intentionally unavailable, or if a repair is refused for safety, the normal manual sign-in option remains available. If the machine's status cannot be trusted because it is offline or unreachable, competing actions are hidden until the dashboard can see the truth again.
+
+The target machine still owns all credentials and browser state. The central dashboard never receives passwords, cookies, codes, or login profiles. CAPTCHA, phone verification, unexpected sites, identity ambiguity, permission changes, and billing/security changes continue to stop safely for operator help instead of being bypassed.

package/upgrades/side-effects/relogin-pool-one-click.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — one-click fleet re-login
+
+**Version / slug:** `relogin-pool-one-click`
+**Date:** `2026-08-29`
+**Author:** Echo
+**Second-pass reviewer:** `/root/relogin_side_effects_review`
+**ELI16:** `upgrades/relogin-pool-one-click.eli16.md`
+
+## Summary of the change
+
+Closes the fleet seam in assisted re-login. The central dashboard reads machine-tagged episodes, renders the state-appropriate action on the exact account×machine cell, and converts one recent dashboard unlock into an exact, signed re-mint mandate. The target machine re-verifies the account, machine, episode, input digest, and requested approve/retry/cancel action at point of use.
+
+## Decision-point inventory
+
+- Pool episode aggregation — add — read-only, bounded peer fan-out with typed failures.
+- Fronting repair authorization — add — recent operator-session proof plus exact account, machine, and episode.
+- Target execution — add — local or asymmetrically verified delivered mandate must match account, target machine, episode, input digest, and action.
+
+## 1. Over-block
+
+An unreachable peer, expired dashboard session, missing mesh-delivery seam, stale episode, or mismatched identity refuses the click. The operator can retry after reachability or dashboard unlock is restored; no account state is changed by the refusal.
+
+## 2. Under-block
+
+Bearer-only callers cannot use the fronting route. The target does not trust the fronting request alone: it re-evaluates a local mandate or re-verifies the delivered asymmetric mandate and exact bounds. Residual risk is compromise of the trusted operator machine or its signing key, already inside the coordination-mandate threat boundary.
+
+## 3. Level-of-abstraction fit
+
+The dashboard selects no identity and grants no authority. It carries server-issued episode/account/machine identifiers. Deterministic route gates bind recent human proof to the existing signed re-mint authority; provider decisions remain inside the existing bounded repair worker.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No brittle signal becomes authority.
+
+Peer episode rows are status signals. Recent dashboard proof plus an exact signed mandate is the authority. The target's independent point-of-use verification remains the final gate.
+
+## 4b. Judgment-point check
+
+No semantic judgment is added. Account id, machine id, episode id, signature validity, expiry, and mandate bounds are enumerable invariants.
+
+## 5. Interactions
+
+- **Shadowing:** remote episodes are filtered out of machine-local account cards and rendered only on their exact matrix cells.
+- **Double-fire:** the durable episode state rejects an action once it is no longer valid; mandates are exact, action-bound, single-use, and expire after 15 minutes.
+- **Races:** peer disappearance yields a typed retryable failure. Target state is re-read before approval.
+- **Feedback loops:** the route starts one existing bounded repair episode; it creates no new poller or retry loop.
+
+## 6. External surfaces
+
+`GET /subscription-relogin?scope=pool` adds machine-tagged rows, typed truth failures, and separately typed feature-dark machines. `POST /subscription-relogin/repair-cell` is the dashboard entry point. `approve-with-mandate` is target-local service plumbing. The visible action is **Repair sign-in**, **Try repair again**, or **Cancel repair** according to durable state. A peer truth failure suppresses unsafe competing flows; an explicitly feature-dark target and a safely refused episode retain the manual sign-in fallback.
+
+## 6b. Operator-surface quality
+
+The primary action is one plain-language button on the exact cell. It exposes no paths, hashes, mandates, tokens, or JSON and requires no host access. A stale dashboard unlock produces one direct instruction to unlock and tap again.
+
+## 7. Multi-machine posture
+
+Status is aggregated, authority is delivered, but execution and credentials remain target-local. The fronting machine never receives provider secrets or browser state. The target accepts episode-bound mandates under the assisted-relogin rollout gate (independent of generic Account Follow-Me) and only when signed by its registered operator machine and pinned to itself.
+
+## 8. Rollback cost
+
+Pure route/dashboard change. Revert and publish; no migration or data repair. Existing local assisted repair and the older manual sign-in path remain intact.
+
+## Conclusion
+
+The change closes the phone-to-target seam without broadening ordinary API authority or moving credential state across machines. Ship requires focused three-tier evidence, independent review concurrence, full CI, deployment, and the two real canaries.
+
+## Second-pass review (required)
+
+The reviewer found three material gaps on the first pass: manual fallback was incorrectly suppressed for explicitly feature-dark machines, failed/waiting episodes had no recovery actions, and cross-machine delivery depended on the generic Account Follow-Me rollout gate. The implementation now separates `failed` from `unavailable`, exposes signed approve/retry/cancel actions, restores safe manual fallback after refusal or feature-dark status, and accepts only fully episode-bound mandates under the assisted-relogin gate. A later pass found and closed cross-surface authority bleed: repair-only mandates are refused by generic Account Follow-Me enrollment. The post-rebase pass then found that repair mandates were issued for an hour and not consumed. The correction clamps them to 15 minutes, rejects expiry at delivery and use, revokes local mandates before action, and durably tombstones delivered mandates before action so replay or redelivery cannot revive them. Replay, redelivery, and expiry regressions are test-pinned. The independent post-fix re-review concurred: exact bounds remain ahead of consumption, the two-server replay test passes, and no release blocker remains.
+
+## Evidence pointers
+
+- `tests/integration/subscription-relogin-routes.test.ts`
+- `tests/integration/subscriptions-tab.test.ts`
+- `tests/unit/subscriptions-render.test.ts`
+- `tests/unit/account-follow-me-mandate-delivery.test.ts`
+- `tests/e2e/subscription-relogin-lifecycle.test.ts`
+
+## Class-Closure Declaration (display-only mirror)
+
+**Defect class:** `unbounded-self-action`
+**Closure:** `n/a`
+**Reason:** this adds a one-shot operator-triggered dispatch into the already-registered, already-bounded subscription re-login controller; it adds no self-triggered loop.

package/upgrades/side-effects/telegram-dashboard-edit-rejection.md

@@ -0,0 +1,192 @@
+# Side-effects review: dashboard edit rejection
+
+**Author:** Echo
+**Independent reviewer:** Hooke; design, implementation and corrected boundaries concurred.
+
+## Scope and governing contract
+
+Justin's report from Scout identifies a dashboard amplifier still present in
+v1.3.1235. A rejected pinned-message edit fell through to a new send regardless
+of whether Telegram had received the edit. This repair preserves the approved
+[Telegram message-origin contract](../../docs/specs/telegram-message-origin.md):
+a hold or uncertain outcome does not authorize a new operation.
+
+The report's false-wake and daily-send counts were supplied by Justin, not
+independently verified on b2lead-insights. Echo's own log contains repeated wake,
+tunnel restart and edit-fallback entries; that confirms the path exists locally,
+not that every wake is false or that this explains every capacity refusal.
+
+## Decision-point inventory
+
+- TelegramAdapter.broadcastDashboardUrl: replace catch-all fresh sends and error
+  substring no-ops with narrow evidence from the platform response boundary.
+- TelegramAdapter.apiCall: bind parsed Telegram rejection evidence to the original
+  error and the actual edit target; preserve typed holds through existing catches.
+- TelegramOriginService.executePreparedBot: retain the same known-failed hold and
+  bind edit evidence only after recordOutcome reports recorded:true.
+- TelegramEditRejection: private, one-use error-object evidence for matching bot
+  account, chat, message and method. No serialized error field grants authority.
+
+## 1. Over-block
+
+Only HTTP400 with ok:false, error_code:400 and the exact Telegram missing-edit
+description permits replacement. A future changed description, cannot-edit,
+authorization rejection, malformed response or lost evidence remains an explicit
+refresh failure, preserving the pinned ID. This may leave a stale dashboard link
+until the underlying fault is resolved. It never invents a successful refresh.
+Exact authoritative unchanged content remains a no-op. First-run sends remain.
+
+## 2. Under-block
+
+Corrupt or unreadable saved-ID state is still treated as absent by the existing
+loader. Existing save failures and simultaneous legitimate missing-message
+refreshes are separate adjacent risks, not repaired here. If a genuinely missing
+message's replacement is held or unknown, a later broadcast against the still-saved
+old ID can receive another genuine missing-message rejection and prepare another
+replacement. This repair fences held edits within a broadcast; it does not add
+durable replacement custody across distinct broadcast calls. That boundary is
+tracked for the subsequent delivery work in topic69507. The broader false-wake
+classifier, unconditional tunnel recovery and opaque admission errors remain
+follow-ups in topic69507. No generic class-convergence claim is made.
+<!-- tracked: topic-69507 -->
+
+## 3. Level-of-abstraction fit
+
+The replacement decision belongs inside broadcastDashboardUrl, before sendToTopic,
+so it covers startup, wake and HTTP callers even when an outer caller catches the
+failure. Managed Telegram4xx responses are consumed inside the origin service;
+evidence must therefore be carried through its original typed hold rather than
+reconstructed from adapter error text. Legacy library use classifies the actual
+raw response at apiCall. These are the only production evidence producers.
+
+## 4. Signal versus authority
+
+This is a constrained transport-outcome invariant, not a semantic message filter.
+HTTP status alone and exception substrings cannot choose a new send. The narrowly
+enumerated platform error, actual target and successful durable outcome write
+provide the required evidence. Existing ownership, content and send-policy
+authorities still decide every replacement. See
+[signal versus authority](../../docs/signal-vs-authority.md).
+
+## 4b. Judgment points
+
+No new static heuristic at a competing-signals decision point, LLM call, timer,
+recovery budget or policy bypass. Wake classification is deliberately separate.
+
+## 5. Interactions
+
+Held/unknown edits never reach replacement, unpin or pin calls. Their original
+operation IDs and saved ID bytes remain intact. A successful missing-message
+replacement saves its new ID and the next refresh edits it. Failed replacement
+sends also preserve their original error identity. Managed outcome-write failure
+cannot mint evidence, even when Telegram's raw response says the message is gone.
+Known-failed edit operations retain the existing recovery rules; this repair does
+not reset attempts, deadlines, content reservations or the fifteen-minute brake.
+No additional retry loop is introduced. Existing raw429 retry behavior remains.
+
+## 6. External surfaces and migration
+
+No new API, config or durable schema. The existing dashboard-refresh route returns
+502 when refresh fails. New-install awareness and idempotent PostUpdateMigrator
+guidance explain original-operation custody and the remaining wake limitation.
+The explicit shadow migration updates AGENTS.md and GEMINI.md even when the new
+paragraph already exists in CLAUDE.md; custom framework text remains.
+Normal package update and server activation install the runtime correction.
+
+## 6b. Operator surface
+
+No new control or approval. A held update is a failure to refresh the pinned link;
+it must not be reported as delivered or worked around by deleting the saved ID.
+
+## 7. Multi-machine posture
+
+Evidence is process-local and target-bound. A serialized remote error cannot
+authorize replacement. Standby and revoked lease refusals remain fenced; no
+session credential is forwarded and no peer is granted a new send budget.
+This repair precedes the pending standby-routing release to stop its relay from
+carrying catch-all fallback dashboard posts.
+
+## 8. Rollback
+
+Revert the repair and publish a patch; no queue clearing or data migration needed.
+Rollback restores the reproduced dashboard amplification defect.
+
+## Evidence
+
+Nine regression tests failed against the released code for the intended reasons.
+The correction passed twenty-two unit cases, three actual HTTP route cases, seven
+production-Boot lifecycle cases and three awareness migration cases. E2E fixture
+repairs used a short Unix-socket path and the actual audit record/outer-service
+error contract. They did not change production to accommodate the fixture.
+Initial build and lint passed; the reviewed build passed. Independent review
+required preserving original errors on null/undefined-token adapters, managed
+unchanged-response coverage and explicit documentation of repeated replacement
+custody. These corrections passed their focused tests. Expanded shadow tests
+exposed missing standalone guidance on existing framework files; the explicit
+migration tuple corrected it and all three migration cases passed. Final commit
+checks, full test:all and CI remain required before release.
+
+The first full run on 9ffb202636d7 found two release-completeness failures:
+the new awareness marker was absent from the feature-addenda parity registry,
+and the release fragment lacked the required sections. The parent deliberately
+cancelled its own run after confirming these failures; all 5,579 frozen inputs
+were unchanged. That run is incomplete, not passing. The correction adds the
+marker to the existing real parity assertions and organizes the release note
+under the required headings. It changes no production behavior and removes no
+assertion or release requirement. A fresh full run is required on the correction.
+The corrected completeness suite and dashboard unit/migration tests passed all
+179 cases across three files.
+Independent correction review confirmed the added assertions preserve the gate;
+its wording concern narrowed the user-facing claim to held or uncertain pinned
+edits, preserving the documented cross-invocation replacement limitation.
+
+Class closure: unbounded-self-action is n/a for this bounded change. It removes
+an exception-driven extra send from one invocation and adds no autonomous retry
+controller. It does not claim to close the broader wake loop or cross-invocation
+replacement-custody class.
+
+The full run on d9d9dfa92a65 completed with exit 1: 3 failed and 51,883 passed tests (3
+failed/3,349 passed files); subsequent standalone integration and E2E stages did not
+run. All 5,579 frozen inputs were unchanged. Two token-redaction tests depended on the
+source spelling `throw new Error`; the runtime now assigns that error before attaching
+private rejection evidence. Replacements exercise actual JSON and non-JSON rejection
+paths, assert the sanitized request URL and absent fixture token, and independently
+verify one wire request carries the correct token URL. This covers request-URL
+redaction, not arbitrary response-body redaction.
+
+The third failure's final stack identifies prepareBot at production-Boot test 104,
+inside runWithSessionToken after its awaited observer refresh. The two recovery fixtures
+previously checked authorization earlier, before issuing the token. They now also
+observe the actual display authority immediately before their first preparation using
+the existing bounded helper. No preparation, admission, review, or delivery is retried;
+no production permission, timeout, or budget changes. The specific source of
+configuration invalidation remains unproved, and the fixture does not claim atomic
+readiness.
+
+Independent Boot reviews concurred with this exact setup correction conditional on the
+final preparation stack, now confirmed. Hooke concurred with both runtime-redaction
+replacements and recommended always restoring global stubs/temp files even if
+adapter.stop throws; that cleanup improvement is included. Focused validation and a
+fresh complete full run remain required on the correction.
+
+The corrected three-file run passed all 24 tests on the dashboard worktree, including
+the real production-Boot restart cases. Runtime source is unchanged from its passing
+build; full-suite validation and CI are still required.
+
+The fresh full run on 1523f656a99c completed normally with exit 1: exactly two
+failed and 51,886 passed tests (one failed/3,351 passed files). The only failing
+file was guards-route.test.ts. Standalone integration/E2E stages did not run
+after the aggregate failure. All 5,579 frozen source/test/config inputs were
+verified unchanged after completion.
+
+The receiver fixture used 1781300000000 (2026-06-12T21:33:20Z), which crossed the
+durable store's real-clock 90-day retention threshold at 2026-09-10T21:33:20Z.
+The preceding full run exercised that fixture before the threshold. Three
+receiver-clock initializations now start at Date.now(), retaining their existing
+relative advances and every persistence/age assertion. The sender timestamp
+remains fixed, so receiver-versus-sender semantics are still tested. Production
+retention policy and dashboard runtime behavior are unchanged.
+
+Hooke independently concurred with this exact clock correction. All 20 tests
+passed in both the isolated preparation and the dashboard candidate after the
+patch was applied. The next full run must validate the resulting commit.