instar 1.3.1237 → 1.3.1239

package/src/data/standards-registry.meta.json

@@ -1,6 +1,6 @@
 {
-  "sha256": "3b12afd2e8d1cf7e26246e69c0af49bf7012a18d3a8bd128fe2aafa332f625c3",
+  "sha256": "890eec3dcf80e4388c396f43001a0bd3fabc80c88f79aa9525885d6402a6dfdf",
   "articleCount": 91,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1237"
+  "packageVersion": "1.3.1239"
 }

package/upgrades/1.3.1238.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Claude sign-in repair now records an opaque, keyed revision of the account slot's auth material before a login starts. The automatic completion sweep only finishes the repair after that revision actually changes and the returned account identity matches. An existing `.claude.json` settings file is no longer treated as proof that a new login succeeded.
+
+If the dashboard's short-lived operator approval has expired, tapping a repair action now opens the PIN screen directly. The user is told to enter the dashboard PIN and retry, instead of being left with the unactionable instruction to “unlock the dashboard again.”
+
+The internal auth revision never contains credential bytes and is removed from local, pooled, reissue, start, reuse, completion, expired-login, and peer-facing HTTP responses. Concurrent completion sweeps are serialized by pending-row version, and a failed pool finalization stays pending for a safe retry rather than reporting success.
+
+## What to Tell Your User
+
+Sign-in repair now waits for a real credential change before reporting success. If dashboard approval has expired, the repair button reopens the PIN prompt so the user can continue in place.
+
+## Summary of New Capabilities
+
+- False completion is prevented even when an old Claude settings file already exists.
+- Locked repair controls can reopen the existing dashboard unlock flow.
+
+## Evidence
+
+- Unit, integration, and production-composition E2E coverage exercises changed, unchanged, missing, legacy, and unreadable auth revisions plus the locked dashboard action.
+- The focused regression suite passes 276 tests across 7 files and the TypeScript production build completes successfully.

package/upgrades/1.3.1239.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The Subscriptions dashboard now lets current account health outrank durable repair history. If a previously failed or suggested repair remains in the audit ledger after the account is already Active, the grid and account card no longer show that old episode as actionable or offer a retry the server must refuse.
+
+The click path also self-heals if account health changes between rendering and tapping: the dashboard refreshes current state instead of exposing the internal revalidation error. Point-of-use revalidation refusals are returned as conflicts rather than server errors.
+
+## What to Tell Your User
+
+If an account is already Active, an old failed repair will disappear automatically after the next dashboard refresh instead of asking for another retry.
+
+## Summary of New Capabilities
+
+- Current Active subscription health supersedes stale suggested and failed repair actions.
+- An already-active click race refreshes the dashboard without exposing internal error codes.

package/upgrades/side-effects/subscription-relogin-completion-witness.md

@@ -0,0 +1,125 @@
+# Side-Effects Review — Subscription re-login completion witness
+
+**Version / slug:** `subscription-relogin-completion-witness`
+**Date:** 2026-09-14
+**Author:** Echo
+**Second-pass reviewer:** Archimedes (`review_relogin_side_effects`)
+
+## Summary of the change
+
+This change removes file-existence as automatic completion proof for Claude follow-me sign-in. `PendingLoginStore` records an opaque pre-login auth revision, `EnrollmentWizard` advances only after that revision changes and then retains the existing exact-email oracle gate, `server.ts` derives the revision from the machine-local keychain without persisting credential bytes, and `routes.ts` strips the internal revision from every HTTP surface. The Subscriptions dashboard also reopens its existing PIN overlay when a repair action lacks current operator proof.
+
+## Decision-point inventory
+
+- `EnrollmentWizard.sweepFollowMeCompletions` — **modified** — automatic completion now requires a changed auth revision instead of an already-existing settings file.
+- `EnrollmentWizard.completeFollowMe` — **pass-through** — exact provider identity remains the authority that decides whether the account is selectable.
+- Subscriptions dashboard repair/profile controls — **modified** — missing or expired proof invokes the existing unlock surface; the server remains the authorization authority.
+- Pending-login API projection — **modified** — internal revision evidence is removed before serialization.
+
+---
+
+## 1. Over-block
+
+A legitimate already-authorized browser short-circuit will remain pending if the provider completes without changing the keychain credential blob. That is the intended fail-closed posture: unchanged credential material cannot prove that this exact attempt succeeded. The operator can still use the explicit paste-back path or reissue the artifact, which captures a fresh baseline. Legacy pending rows without a baseline also cannot auto-complete, but remain recoverable through those existing paths.
+
+---
+
+## 2. Under-block
+
+A credential blob changed by an unrelated process during the same pending window can satisfy the revision precondition. It cannot by itself activate the account: the existing identity oracle must still resolve the exact expected email. The broader assisted-repair orchestrator continues to require fresh authenticated use, active pool state, and closure of the exact incident before declaring repair success. This patch does not turn the revision into a success authority.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The revision comparison belongs in `EnrollmentWizard`, immediately before its existing follow-me completion authority. The server composition owns access to the machine-local keychain and supplies only an opaque witness function. `PendingLoginStore` durably binds the baseline to the exact artifact/reissue. HTTP routes own projection and strip the internal field at the boundary. The dashboard reuses the global PIN overlay instead of creating a second authorization mechanism.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context (LLM-backed with recent history or equivalent).
+- [ ] ⚠️ Yes, with brittle logic — STOP.
+
+The HMAC revision comparison is a deterministic evidence signal and a hard fail-closed precondition, not the authority that declares the identity or repair successful. Exact identity remains with the provider-backed identity oracle; the approved assisted-relogin state machine retains its independent authenticated-use and incident-closure requirements. Missing evidence means “keep waiting,” not rejection of a user or destructive action.
+
+---
+
+## 4b. Judgment-point check
+
+No new static heuristic is added at a competing-signals judgment point. Whether auth material changed is an enumerable invariant: absent, unreadable, or unchanged evidence cannot prove a new credential landed. No balancing of liveness, urgency, ownership, or conversational meaning is involved.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** revision evidence runs before `completeFollowMe`; it can delay that identity probe but cannot bypass or replace it.
+- **Double-fire:** a per-login single-flight guard and `PendingLoginStore.completeIfVersion()` version CAS ensure that concurrent sweeps run pool finalization and Claude readiness setup exactly once on the winning completion.
+- **Races:** each reissue records the current revision as its new baseline. A change from an older attempt therefore cannot satisfy a later artifact, and stale sweep versions cannot finalize a newer row.
+- **Feedback loops:** pool activation can trigger ordinary quota polling, but quota data does not feed the revision baseline and cannot retrigger completion.
+- **Recovery:** old durable rows fail closed; restart recovery/reissue supplies a baseline without migrating credential material. A thrown pool finalizer leaves the row pending, so a later sweep can retry instead of preserving a false terminal result.
+
+---
+
+## 6. External surfaces
+
+The visible dashboard text changes from the dead-end “unlock again” instruction to an in-place PIN prompt. Pending-login response shapes do not expose the new internal field. The store gains one optional HMAC string; it contains no credential bytes and is machine-local. Timing still depends on the existing periodic completion sweep. No new provider, browser, messaging, or external API action is introduced.
+
+Every touched operator action remains phone-completable: tapping Repair sign-in opens the existing six-digit PIN overlay, after which the same button can be tapped again. No raw token, JSON, ID, or command is requested.
+
+---
+
+## 6b. Operator-surface quality
+
+1. **Leads with the primary action:** Yes. The existing Repair sign-in action remains the visible cell action; an expired proof immediately opens the required PIN overlay.
+2. **Zero raw internals as primary content:** Yes. The operator sees only plain-language PIN and retry guidance; revisions, account ids, and credential locations remain hidden.
+3. **Destructive actions de-emphasized:** Yes. This change adds no destructive action and does not move cancel/revoke controls.
+4. **Plain language + phone width:** Yes. It reuses the existing mobile dashboard overlay and short status copy, introduces no new layout, table column, or horizontal content.
+
+---
+
+## 7. Multi-machine posture
+
+**Machine-local BY DESIGN**, with pool-wide visibility proxied on read. Each auth revision is derived from the credential slot physically held on that machine and must never replicate. `GET /subscription-pool?scope=pool` continues to merge redacted account state across peers; route projection strips the revision before local or peer responses. The dashboard action is routed to the machine holding the target cell. The change emits no user-facing notice, creates no transferable URL, and adds no topic-bound durable state that could strand on transfer.
+
+---
+
+## 8. Rollback cost
+
+- **Hot-fix release:** revert the code change and ship the next patch.
+- **Data migration:** none. The optional baseline may remain in pending rows and is ignored by old code.
+- **Agent state repair:** none. Existing pending rows remain valid; reissue is the ordinary recovery path.
+- **User visibility:** during rollback propagation, an old node could again show dead-end unlock copy or accept file existence as completion proof, so rollback should be fleet-wide and prompt.
+
+---
+
+## Conclusion
+
+The review confirms that the fix adds a narrowly scoped evidence precondition at the correct machine-local boundary. It removes the stale-file false-positive without weakening identity, authorization, or authenticated-use authorities. The material residual is deliberate fail-closed waiting when auth bytes do not change; existing paste-back and reissue paths keep that recoverable. The change is ready for independent review and shipment.
+
+---
+
+## Second-pass review
+
+**Reviewer:** Archimedes (`review_relogin_side_effects`)
+**Independent read of the artifact:** Concur. The reviewer verified signal-versus-authority separation; fail-closed absent/unreadable baselines; redaction across the identified HTTP paths; per-login single-flight plus version-CAS completion; retry after pool-finalization failure; exactly-once readiness setup for the winning sweep; and the dashboard 401-to-PIN recovery path.
+
+---
+
+## Evidence pointers
+
+- Focused unit/integration/AgentServer E2E suite: 276 tests passed across 7 files.
+- `corepack pnpm build`: passed.
+- Repository lint: passed after the operator-authorized countdown update.
+- `git diff --check`: passed.
+- A repository-wide test attempt reached an unrelated CPU-bound hang in `window-lifecycle-production-wiring.test.ts`; the affected subscription suites completed green independently.
+
+---
+
+## Class-Closure Declaration
+
+`defectClass: unbounded-self-action`, `closure: guard`, `guardEvidence: { enforcementType: ratchet, citation: tests/unit/enrollment-wizard.test.ts, howCaught: repeated completion sweeps with absent, unreadable, or unchanged revision evidence emit no completion; exact version CAS runs finalization once, a thrown finalizer remains pending, and terminal state is the settling brake }`.

package/upgrades/side-effects/subscription-relogin-stale-retry.md

@@ -0,0 +1,100 @@
+# Side-Effects Review — Subscription dashboard stale-retry correction
+
+**Version / slug:** `subscription-relogin-stale-retry`
+**Date:** `2026-09-14`
+**Author:** `Echo`
+**Second-pass reviewer:** `Archimedes`
+
+## Summary of the change
+
+The Subscriptions dashboard now reconciles durable assisted-relogin history against the current subscription-pool truth before rendering an action. A suggested or failed repair remains actionable only while the exact account×machine cell is currently `needs-reauth`; an in-flight repair remains visible until the controller closes it. If health changes between render and click, the dashboard converts the typed server conflict into a plain-language refresh instead of exposing an internal error. The two approval routes also consistently classify revalidation refusal as HTTP 409. The implementation touches `dashboard/subscriptions.js`, the assisted-relogin routes in `src/server/routes.ts`, and focused unit, integration, and E2E tests.
+
+## Decision-point inventory
+
+- `repairAppliesToCurrentState()` in `dashboard/subscriptions.js` — add — deterministically decides whether a durable repair episode still applies to current pool truth.
+- Account-card and matrix action rendering — modify — suppresses stale suggested/failed actions for cells that no longer need authentication.
+- Account-card and matrix click-race handling — modify — refreshes current truth after the server reports the account is already active.
+- Assisted-relogin approval HTTP classification — modify — maps typed revalidation refusals to 409 conflicts rather than 500 errors.
+
+---
+
+## 1. Over-block
+
+The main over-block risk is hiding a repair whose pool state is stale `active` even though authentication has actually failed. The existing candidate authority already requires the subscription-pool authority to say `needs-reauth`, and the server independently revalidates that fact at action time, so exposing a retry while current authority says Active would only offer an action guaranteed to be refused. In-flight states are deliberately retained even if the pool flips Active, preventing a legitimate running repair from disappearing before final verification.
+
+Unknown or malformed peer repair states are hidden. This is intentional fail-closed behavior: an unknown state has no defined action contract and cannot safely authorize a repair.
+
+## 2. Under-block
+
+The change does not erase stale terminal episodes from the durable audit ledger, so an API client that ignores current pool state could still display them incorrectly. The first-party dashboard is corrected and the server remains the final admission authority. A separate future repair state could also require explicit addition to the known-state allowlist before it appears; this is a conservative compatibility cost rather than unsafe action exposure.
+
+## 3. Level-of-abstraction fit
+
+This is at the presentation/reconciliation layer that combined the two authoritative reads incorrectly. The repair ledger remains authoritative for repair lifecycle and audit history; the subscription pool remains authoritative for whether a new suggested/failed repair is presently applicable. The server-side orchestrator remains the action authority and revalidates at point of use. No parallel repair authority is introduced.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context (LLM-backed with recent history or equivalent).
+- [x] This is a closed hard-invariant reconciliation, not a judgment heuristic.
+
+The UI rule is enumerable: `suggested` and `failed` are actionable only when current pool truth is exactly `needs-reauth`; known in-flight states remain visible; unknown states fail closed. This does not infer user intent or interpret ambiguous prose. The actual repair action is still authorized and revalidated by the existing deterministic orchestrator. The change therefore does not give a brittle detector independent judgment authority.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic is added at a competing-signals judgment point. The inputs are typed state-machine values owned by two existing authorities, and the precedence is a spec-defined invariant: current pool health governs new actionability while the repair ledger governs an already-running lifecycle.
+
+## 5. Interactions
+
+- **Shadowing:** the dashboard reconciliation runs after both pool and repair reads. It hides only terminal/suggested actions that the point-of-use server revalidation would reject.
+- **Double-fire:** no new actuator or request is added. A user click still sends one existing repair request.
+- **Races:** if the cell changes from `needs-reauth` to Active after render, the existing server revalidation wins. The client consumes the typed 409, refreshes both authorities, and removes the invalid action.
+- **Feedback loops:** terminal repair rows remain durable and continue to appear in the repair API. Rendering no longer feeds them back into another invalid retry when the pool is Active.
+
+## 6. External surfaces
+
+The visible dashboard changes from a raw `retry-revalidation-refused:account-not-needs-reauth` failure and retry invitation to the current Active state. API callers now receive 409 consistently for both direct and mandate-scoped approval revalidation conflicts. No persistent schema, credentials, provider data, or external service contract changes. The existing dashboard/PIN and phone-complete action surface is retained.
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+1. **Leads with the primary action:** yes. A legitimately eligible `needs-reauth` cell still presents its repair control directly; a healthy Active cell leads with its health and no invalid action.
+2. **Zero raw internals as primary content:** yes. The already-active race is translated to “This account is already active. Refreshing its status…” and then replaced by refreshed state; the internal refusal slug is not shown.
+3. **Destructive actions de-emphasized:** yes. This change adds no destructive control and does not promote cancel/delete behavior.
+4. **Plain language + phone width:** yes. Existing touch targets/layout are unchanged, and the new status copy is short, plain language that fits the existing responsive cell/card surfaces without adding horizontal content.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Proxied-on-read.** Subscription cells come from `GET /subscription-pool?scope=pool`, and repair episodes come from `GET /subscription-relogin?scope=pool`; the dashboard joins the exact account and machine identifiers from those merged reads. Point-of-use actions continue through the existing machine-targeted mandate route and are revalidated on the target machine. Peer read failure remains explicit and does not cause local data to authorize a remote repair.
+
+The change emits no user-facing notices, adds no durable state, and generates no URLs. Existing machine-local repair ledgers remain visible pool-wide through the proxied read and therefore do not strand the dashboard view when the topic is handled on another machine.
+
+## 8. Rollback cost
+
+Pure code rollback: revert the dashboard reconciliation and HTTP status mapping and ship a patch. No data migration or agent-state repair is required because durable repair episodes are neither mutated nor deleted. During rollback propagation, users could temporarily see the stale retry/raw conflict again, but no invalid server-side repair would be admitted because point-of-use revalidation remains intact.
+
+## Conclusion
+
+The review preserves the split between current-health authority and durable lifecycle history, keeps in-flight work visible, fails closed on unknown states, and makes the click race self-healing. The main compatibility tradeoff—new unknown repair states remain hidden until explicitly supported—is conservative and covered by boundary tests. The change is clear to ship through the normal release and live-browser verification gates.
+
+## Second-pass review (if required)
+
+**Reviewer:** Archimedes
+**Independent read of the artifact: concur**
+
+The reviewer found no remaining blocker after both account-card and matrix paths shared typed already-active handling, both approval routes returned 409 consistently, unknown states failed closed, and the focused race tests plus `git diff --check` passed.
+
+## Evidence pointers
+
+- `tests/unit/subscriptions-render.test.ts`
+- `tests/integration/subscriptions-tab.test.ts`
+- `tests/integration/subscription-relogin-routes.test.ts`
+- `tests/e2e/subscriptions-tab-lifecycle.test.ts`
+- Focused result: 127 tests passed across the four files.
+- Independent reviewer: concurred with no remaining blockers.
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect and no self-triggered controller change — not applicable.