Skip to content

Repository navigation

Vendor-pull slice 3a: recover client queries across reconnects #132

Closed
#135
Closed
Vendor-pull slice 3a: recover client queries across reconnects#132
#135
Labels
enhancementRequested improvement or new capability.kind:sub-specChild spec produced by decomposing an epic.status:verifiedAcceptance evidence accepted.

Description

@gannonh
gannonh
opened on Aug 26, 2026

Status

Verified

Verified: 2026-08-26T20:27:29Z. Maintainer accepted the recorded evidence after merge.

Goal

Web, desktop, and mobile clients recover shared environment queries after a remote connection is replaced. Users keep the last meaningful state during recovery instead of seeing an interruption-only failure.

Context

Parent: #124.

This child ports upstream #8117 at 589a9d0e2.

Kata currently keys shared environment queries from connected generations. If a Connect session is replaced while a query runs, an interruption-only failure can reach the caller before the replacement session retries the query.

The upstream patch applies cleanly to Kata origin/main at 84cf12c38. This issue has no dependency on #129 or another slice 3 child. Remote server-update recovery from transient credential rejection is a separate sibling spec.

Constraints and non-goals

  • Keep Kata package imports and product identity.
  • Do not change authorization storage, environment credential formats, Connect wire identifiers, or the supervisor state model.
  • Do not add client-specific recovery branches. The shared behavior stays in packages/client-runtime.
  • Do not port upstream #7953 or #7664 in this issue.
  • Do not change query refresh intervals, stale times, idle lifetimes, or individual query implementations.

Acceptance criteria

  • When a connected environment session is replaced during a query, the query remains pending or revalidating and does not publish an interruption-only failure.
  • When the replacement session becomes connected, the shared query runs again and settles with the replacement session's result.
  • During reconnect, stale-while-revalidate keeps the last successful value. A genuine query failure also remains available with waiting: true until the replacement attempt settles.
  • A manually disconnected, offline, or blocked environment settles without waiting forever. The result uses lastFailure when present and otherwise returns EnvironmentRpcUnavailableError.
  • The public environment-query atom boundary proves session replacement, terminal connection states, retained failures, and stale-while-revalidate values without sleeps or polling.
  • Focused client-runtime tests and the client-runtime typecheck pass.
  • The product diff contains no new @t3tools/, T3CODE_*, t3@, or pingdotgg/t3code product identity.

Architecture

createEnvironmentQueryAtomFamily observes the paired EnvironmentSupervisor.state and EnvironmentSupervisor.session streams. Connected state with a live session runs the query. Connecting and backoff state keep the query pending so stale-while-revalidate retains prior state. Available, offline, and blocked states settle with a typed failure.

No contract, server persistence, migration, web component, desktop IPC, or mobile component changes.

Delivery slices

  1. This issue is one slice. Recover shared environment-query atoms across session replacement and prove every connection phase at the atom boundary.

Demonstration

  • Consumer: a web, desktop, or mobile client that reads environment-backed state through packages/client-runtime.
  • Action or input: start a query, replace its connected session, enter reconnect, then connect a replacement session.
  • Observable result: the atom retains prior success or genuine failure while waiting, does not expose an interruption-only failure, and settles with the replacement session's result.
  • Evidence: deterministic public atom-boundary tests that drive the supervisor state and session streams. A bounded live Connect reconnection pass is useful supplementary evidence but is not a substitute for the deterministic lifecycle cases.

Verification

  • Run vp test run packages/client-runtime/src/state/runtime.test.ts.
  • Run vp run --filter @kata-sh/code-client-runtime typecheck.
  • Confirm the focused tests cover session replacement, available, offline, blocked, retained failure, and retained success cases through the exported environment-query atom family.
  • Make one bounded live Connect reconnection attempt when a disposable remote environment is available. Record it as supplementary Pass or Blocked evidence. A Blocked live attempt does not satisfy a failed deterministic criterion.
  • Run a diff-scoped identity search for @t3tools/, T3CODE_, t3@, and pingdotgg/t3code.

Risks and mitigations

  • A query can wait forever in the wrong phase. Lifecycle tests cover connected, connecting, backoff, available, offline, and blocked states.
  • A session and a connected state can arrive separately. The query runs only when both state and session say the connection is usable.
  • A reconnect can erase the last useful state. Separate tests cover retained successes and genuine failures while revalidation waits.

Build handoff

  • Approved scope: upstream #8117 in runtime.ts and runtime.test.ts at the shared client-runtime boundary.
  • Non-goals: #7953, #7664, authorization storage, credential formats, Connect wire changes, client-specific retry logic, or visual changes.
  • Ordered slices: one shared query-lifecycle change with deterministic atom-boundary proof.
  • Required verification commands: the focused vp test run, client-runtime typecheck, lifecycle coverage check, optional bounded live Connect attempt, and identity search above.
  • Fixtures or credentials needed: deterministic tests need none. A disposable remote environment is optional supplementary evidence.
  • Blocking open questions: None

Activity

  1. gannonh
    added
    enhancementRequested improvement or new capability.
    kind:sub-specChild spec produced by decomposing an epic.
    status:draftSpec is being written or revised. Do not build.
    phase:planCurrently in the Plan phase.
    on Aug 26, 2026
  2. gannonh
    added a parent issue on Aug 26, 2026
  3. gannonh
    added
    status:approvedSpec approved by the maintainer. Ready to build.
    phase:buildCurrently in the Build phase.
    and removed
    status:draftSpec is being written or revised. Do not build.
    phase:planCurrently in the Plan phase.
    on Aug 26, 2026

  4. gannonh commented on Aug 26, 2026

    @gannonh
    gannonh
    on Aug 26, 2026
    OwnerAuthor

    Build started on branch cursor/recover-env-queries-reconnect-498f at base SHA aedb43bd0df6aff52b1be30150602703541b6774.

  5. cursor
    added a commit that references this issue on Aug 26, 2026

    test(client-runtime): assert unavailable error on manual disconnect

    7f037f7

  6. gannonh commented on Aug 26, 2026

    @gannonh
    gannonh
    on Aug 26, 2026
    OwnerAuthor

    Build completion report

    Issue #132 (parent #124).

    Tasks completed

    Ported upstream t3code #8117 into createEnvironmentQueryAtomFamily. Queries follow paired supervisor state and session. Connecting and backoff stay pending. Available, offline, and blocked settle with lastFailure or EnvironmentRpcUnavailableError.

    Files changed

    • packages/client-runtime/src/state/runtime.ts
    • packages/client-runtime/src/state/runtime.test.ts

    Tests and verification

    • vp test run packages/client-runtime/src/state/runtime.test.ts: 25 passed. RED then GREEN for the six new lifecycle cases.
    • vp run --filter @kata-sh/code-client-runtime typecheck: exit 0. Pre-existing suggestion in src/relay/discovery.ts only.
    • Identity search on the product diff: no @t3tools/, T3CODE_, t3@, or pingdotgg/t3code.
    • Public atom-boundary tests cover session replacement, available, offline, blocked, retained failure, and retained success. No sleeps or polling.

    Demonstration

    Consumer is any client that reads environment-backed state through packages/client-runtime. Tests start a query, drop the session, reconnect, and assert no interruption-only failure, then settlement on "recovered". Terminal phases settle. SWR keeps last success or genuine failure with waiting: true.

    Review gates

    • Spec compliance: PASS.
    • Code quality: PASS. Ready to continue.
    • Independent subagent review: yes.
    • Approved deviations: none.

    Known follow-ups

    Bounded live Connect reconnection is supplementary and Blocked in this VM. No disposable remote environment. That does not fail a deterministic criterion.

  7. gannonh
    added
    status:implementedBuilt and reported. Ready to verify.
    phase:verifyCurrently in the Verify phase.
    and removed
    status:approvedSpec approved by the maintainer. Ready to build.
    phase:buildCurrently in the Build phase.
    on Aug 26, 2026

  8. gannonh commented on Aug 26, 2026

    @gannonh
    gannonh
    on Aug 26, 2026
    OwnerAuthor

    Verify: acceptance criteria matrix

    Scope: branch cursor/recover-env-queries-reconnect-498f, PR #135, HEAD 7f037f7b0b69eeb5399dc2716ae609159d277c02.

    Adversarial review asked for a recapture on this SHA after the EnvironmentRpcUnavailableError assertion. Tests, typecheck, and identity search were re-run at HEAD.

    Criterion Method Result Evidence
    Session replacement does not publish an interruption-only failure vp test run packages/client-runtime/src/state/runtime.test.ts (retries an interrupted query without exposing a failure during session replacement) Pass uat-evidence/sdk-132-query-reconnect/logs/runtime-query-lifecycle.log (25 passed). RED: /opt/cursor/artifacts/runtime_tests_red.log
    Replacement session re-runs and settles with its result Same test, getResult equals "recovered" after generation 2 Pass Same log. Production: createEnvironmentQueryAtomFamily runs only when phase === "connected" and session is Some
    SWR keeps last success. Genuine failure stays with waiting: true retains the last successful value while reconnecting and keeps a genuine query failure settled while reconnecting Pass Same test file and log
    Manual disconnect, offline, blocked settle. lastFailure or EnvironmentRpcUnavailableError settles as unavailable $condition (HEAD asserts tagged error when lastFailure is null) Pass runtime.test.ts plus HEAD recapture log
    Public atom-boundary proof, no sleeps or polling Lifecycle suite drives exported createEnvironmentQueryAtomFamily with latches and Effect.yieldNow Pass packages/client-runtime/src/state/runtime.test.ts
    Focused tests and client-runtime typecheck pass vp test run and vp run --filter @kata-sh/code-client-runtime typecheck Pass runtime-query-lifecycle.log exit 0. client-runtime-typecheck.log exit 0. Pre-existing suggestion in src/relay/discovery.ts only
    No new T3 product identity Diff-scoped rg for @t3tools/, T3CODE_, t3@, pingdotgg/t3code Pass /opt/cursor/artifacts/identity_search.log (IDENTITY_CLEAN)
    Bounded live Connect reconnection (supplementary) Manual Blocked No disposable remote Connect environment on this VM. Does not fail a deterministic criterion

    Totals: 7 Pass / 0 Fail / 1 Blocked (blocked item is supplementary only).

    Manual run

    vp test run packages/client-runtime/src/state/runtime.test.ts
vp run --filter @kata-sh/code-client-runtime typecheck
git diff main...HEAD | rg -n '@t3tools/|T3CODE_|t3@|pingdotgg/t3code'

    Expected: 25 tests pass, typecheck exit 0, identity search empty.

    Build report: #132 (comment)
    UAT pack: uat-evidence/sdk-132-query-reconnect/ (gitignored). Artifacts worth attaching by hand: /opt/cursor/artifacts/runtime_query_lifecycle.log, /opt/cursor/artifacts/runtime_tests_red.log, /opt/cursor/artifacts/runtime_tests_green.log.

    Recommendation: Pending user sign-off

  9. gannonh commented on Aug 26, 2026

    @gannonh
    gannonh
    on Aug 26, 2026
    OwnerAuthor

    Verify: convergence report

    Checks on this SHA

    Check Result
    Check success
    Test success
    Mobile Native Static Analysis success
    Release Smoke success
    CodeRabbit status success (review skipped: manual review required for this OSS repository)

    Review ledger

    id source ask classification disposition
    r3865786108 CodeRabbit, runtime.test.ts Assert EnvironmentRpcUnavailableError on manual disconnect already-addressed Replied [agent] pointing at 7f037f7. Thread resolved.

    Flaky retries used: 0.
    Commits during convergence: none after 7f037f7.

    Acceptance matrix: 7 Pass / 0 Fail / 1 Blocked (supplementary live Connect). #132 (comment)

  10. gannonh
    added a commit that references this issue on Aug 26, 2026

    fix(client-runtime): recover environment queries after session replac…

    23a9989
  11. gannonh
    closed this as completedin #135on Aug 26, 2026

  12. gannonh commented on Aug 26, 2026

    @gannonh
    gannonh
    on Aug 26, 2026
    OwnerAuthor

    Post-merge web verification on main at 10fd03965 (verify-katacode run web-20260826-195042-3137a9a2).

    Pass (live smoke, not Connect replacement)

    • After pairing, Usage settled with Totals (environment query completed).
    • Tokens metric showed a processed-token count, not a dollar amount.
    • Settings General loaded Project grouping on the same paired origin.

    Blocked

    Evidence: uat-evidence/web-20260826-195042-3137a9a2/screenshots/usage-cost.png, usage-tokens.png, settings-general.png.

  13. gannonh
    added
    status:verifiedAcceptance evidence accepted.
    and removed
    status:implementedBuilt and reported. Ready to verify.
    phase:verifyCurrently in the Verify phase.
    on Aug 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementRequested improvement or new capability.kind:sub-specChild spec produced by decomposing an epic.status:verifiedAcceptance evidence accepted.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions