The best way to control Claude Code, Codex and more from any computer or phone
perf(mobile): thread list resumes from the saved cache, and large gaps reload over gzip HTTP (#32287)
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Julius Marminge committed
Nov 8, 2026 at 16:04 UTC
9557ab46c5ebbc04d5307780b4397dfde952b196
11 files changed
+442
-126
apps/mobile/src/connection/environment-cache-store.test.ts
+10
-1
@@ -498,12 +498,21 @@ describe("mobile SQLite environment cache store", () => {
498
Effect.provideService(MobileDatabase.MobileDatabase, memory.database),
499
);
500
501
- yield* store.saveShell(ENVIRONMENT_ID, SHELL_SNAPSHOT);
501
+ const origin = {
502
+ serverVersion: "1.0.0",
503
+ databaseMigration: 70,
504
+ omitIdleSubagents: true,
505
+ omitOlderSettled: false,
506
+ snapshotAt: 1_800_000_000_000,
507
+ };
508
+ yield* store.saveShell(ENVIRONMENT_ID, SHELL_SNAPSHOT, origin);
509
yield* store.saveThread(ENVIRONMENT_ID, THREAD_SNAPSHOT);
510
511
const shell = Option.getOrThrow(yield* store.loadShell(ENVIRONMENT_ID));
512
const thread = Option.getOrThrow(yield* store.loadThread(ENVIRONMENT_ID, THREAD_ID));
513
514
+ expect(shell.origin).toEqual(origin);
515
+
516
expect(DateTime.formatIso(shell.threads[0]!.updatedAt)).toBe("2026-07-29T12:00:00.000Z");
517
expect(DateTime.formatIso(shell.threads[0]!.latestUserMessageAt!)).toBe(
518
"2026-07-29T12:00:00.000Z",
apps/mobile/src/connection/environment-cache-store.ts
+26
-11
@@ -106,7 +106,13 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
106
operation: "load-shell",
107
decode: decodeStoredShellSnapshot,
108
select: (stored) =>
109
- stored.environmentId === environmentId ? Option.some(stored.snapshot) : Option.none(),
109
+ stored.environmentId === environmentId
110
+ ? Option.some(
111
+ stored.origin === undefined
112
+ ? stored.snapshot
113
+ : { ...stored.snapshot, origin: stored.origin },
114
+ )
115
+ : Option.none(),
116
}).pipe(
117
Effect.zipWith(
118
Effect.promise(() => projectFaviconDatabaseCache.hydrate()),
@@ -115,16 +121,25 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
121
),
122
),
123
),
118
- saveShell: Effect.fn("MobileEnvironmentCache.saveShell")(function* (environmentId, snapshot) {
119
- const payload = yield* encodeStoredShellSnapshot({
120
- schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
121
- environmentId,
122
- snapshot,
123
- }).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
124
- yield* database
125
- .saveCache(environmentId, "shell", "snapshot", ORCHESTRATION_CACHE_SCHEMA_VERSION, payload)
126
- .pipe(Effect.mapError(mapDatabaseError("save-shell")));
127
- }),
124
+ saveShell: Effect.fn("MobileEnvironmentCache.saveShell")(
125
+ function* (environmentId, snapshot, origin) {
126
+ const payload = yield* encodeStoredShellSnapshot({
127
+ schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
128
+ environmentId,
129
+ snapshot,
130
+ ...(origin === undefined ? {} : { origin }),
131
+ }).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
132
+ yield* database
133
+ .saveCache(
134
+ environmentId,
135
+ "shell",
136
+ "snapshot",
137
+ ORCHESTRATION_CACHE_SCHEMA_VERSION,
138
+ payload,
139
+ )
140
+ .pipe(Effect.mapError(mapDatabaseError("save-shell")));
141
+ },
142
+ ),
143
loadThread: Effect.fn("MobileEnvironmentCache.loadThread")((environmentId, threadId) =>
144
loadDecodedCache({
145
database,
apps/server/src/ws.test.ts
+24
-9
@@ -1436,10 +1436,15 @@ it.effect("a publish whose push fails still refreshes the new remote", () =>
1436
),
1437
);
1438
1439
-// Pruned history cannot be replayed: a cursor below the boundary must resync from a snapshot.
1440
-it.effect.each(["thread", "shell"] as const)(
1441
- "%s resume from a cursor below the pruned boundary loads a snapshot",
1442
- (scope) =>
1439
+// Pruned history cannot be replayed: a cursor below the boundary must resync from a snapshot,
1440
+// or, for a shell client that loads it over HTTP, be told to without the server building one.
1441
+it.effect.each([
1442
+ { scope: "thread", httpSnapshotFallback: false },
1443
+ { scope: "shell", httpSnapshotFallback: false },
1444
+ { scope: "shell", httpSnapshotFallback: true },
1445
+] as const)(
1446
+ "$scope resume from a cursor below the pruned boundary (HTTP fallback: $httpSnapshotFallback)",
1447
+ ({ scope, httpSnapshotFallback }) =>
1448
Effect.gen(function* () {
1449
const sql = yield* SqlClient.SqlClient;
1450
const now = "2026-10-13T00:00:00.000Z";
@@ -1463,11 +1468,18 @@ it.effect.each(["thread", "shell"] as const)(
1468
) VALUES (${OrchestrationEventStore.EVENT_LOG_PRUNED_THROUGH}, 2, ${second!.sequence}, ${now})
1469
`;
1470
const subscription = Effect.gen(function* () {
1466
- const stream =
1471
+ const items: ReadonlyArray<unknown> =
1472
scope === "thread"
1468
- ? yield* subscribeOrchestrationV2Thread({ threadId, afterSequence: first!.sequence })
1469
- : yield* subscribeOrchestrationV2Shell({ afterSequence: first!.sequence });
1470
- return stream;
1473
+ ? yield* Stream.runCollect(
1474
+ yield* subscribeOrchestrationV2Thread({ threadId, afterSequence: first!.sequence }),
1475
+ )
1476
+ : yield* Stream.runCollect(
1477
+ yield* subscribeOrchestrationV2Shell({
1478
+ afterSequence: first!.sequence,
1479
+ ...(httpSnapshotFallback ? { httpSnapshotFallback: true as const } : {}),
1480
+ }),
1481
+ );
1482
+ return items;
1483
});
1484
const exit = yield* subscription.pipe(
1485
Effect.provideService(ThreadManagement.ThreadManagementService, {
@@ -1489,7 +1501,10 @@ it.effect.each(["thread", "shell"] as const)(
1501
} as ProjectEnrichment.ProjectEnrichmentService["Service"]),
1502
Effect.exit,
1503
);
1492
- assert.deepEqual(Exit.isFailure(exit) ? Cause.squash(exit.cause) : exit, "snapshot");
1504
+ assert.deepEqual(
1505
+ Exit.isFailure(exit) ? Cause.squash(exit.cause) : Array.from(exit.value),
1506
+ httpSnapshotFallback ? [{ kind: "snapshot-required" }] : "snapshot",
1507
+ );
1508
}).pipe(Effect.scoped, Effect.provide(ReplayTestLayer)),
1509
);
1510
apps/server/src/ws.ts
+15
-7
@@ -64,6 +64,7 @@ import {
64
OrchestrationV2ThreadLaunchError,
65
type OrchestrationProjectShell,
66
type OrchestrationV2ShellSnapshot,
67
+ type OrchestrationV2ShellStreamItem,
68
type OrchestrationV2ThreadStreamItem,
69
type ApplicationStoredEvent,
70
type ProjectEntriesFailure,
@@ -1115,6 +1116,7 @@ export const subscribeOrchestrationV2Thread = Effect.fn("ws.orchestrationV2.subs
1116
export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subscribeShell")(
1117
function* (input: {
1118
readonly afterSequence?: number;
1119
+ readonly httpSnapshotFallback?: true;
1120
readonly requestCompletionMarker?: boolean;
1121
readonly omitIdleSubagents?: boolean;
1122
readonly omitOlderSettled?: boolean;
@@ -1325,14 +1327,20 @@ export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subsc
1327
});
1328
}
1329
1328
- const fromSnapshot = Effect.gen(function* () {
1329
- const loaded = yield* loadSnapshot();
1330
- return composeShellStreamWithEnrichment({
1331
- initial: initialSnapshotItems(loaded),
1332
- tail: completionThenLive(loaded.snapshot.snapshotSequence),
1333
- enrichment: enrichmentRefreshes,
1334
- });
1330
+ const snapshotRequired: Stream.Stream<OrchestrationV2ShellStreamItem> = Stream.make({
1331
+ kind: "snapshot-required",
1332
});
1333
+ const fromSnapshot =
1334
+ input.httpSnapshotFallback === true
1335
+ ? Effect.succeed(snapshotRequired)
1336
+ : Effect.gen(function* () {
1337
+ const loaded = yield* loadSnapshot();
1338
+ return composeShellStreamWithEnrichment({
1339
+ initial: initialSnapshotItems(loaded),
1340
+ tail: completionThenLive(loaded.snapshot.snapshotSequence),
1341
+ enrichment: enrichmentRefreshes,
1342
+ });
1343
+ });
1344
const highWater = yield* applicationEvents.latestApplicationSequence;
1345
if (!(yield* canReplayPersistedRange(input.afterSequence, highWater, SHELL_RESUME_MAX_GAP))) {
1346
return yield* fromSnapshot;
apps/web/src/connection/storage.ts
+7
-2
@@ -846,7 +846,11 @@ export const layer = Layer.effectContext(
846
Effect.mapError((cause) => persistenceError("load-shell", cause)),
847
Effect.map((stored) =>
848
stored.environmentId === environmentId
849
- ? Option.some(stored.snapshot)
849
+ ? Option.some(
850
+ stored.origin === undefined
851
+ ? stored.snapshot
852
+ : { ...stored.snapshot, origin: stored.origin },
853
+ )
854
: Option.none(),
855
),
856
),
@@ -857,11 +861,12 @@ export const layer = Layer.effectContext(
861
);
862
}),
863
saveShell: Effect.fn("storage.saveShell")(
860
- function* (environmentId, snapshot) {
864
+ function* (environmentId, snapshot, origin) {
865
const encoded = yield* encodeStoredShellSnapshot({
866
schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
867
environmentId,
868
snapshot,
869
+ ...(origin === undefined ? {} : { origin }),
870
}).pipe(Effect.mapError((cause) => persistenceError("save-shell", cause)));
871
yield* writeDatabaseValue(database, SHELL_STORE_NAME, environmentId, encoded);
872
},
packages/client-runtime/src/platform/orchestrationCache.ts
+15
@@ -13,10 +13,25 @@ export const ORCHESTRATION_CACHE_SCHEMA_VERSION = 3 as const;
13
// Older caches may contain human turns that bypassed server history budgets.
14
export const ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION = 5 as const;
15
16
+/**
17
+ * The server snapshot the cached rows descend from. Written only for rows that have one, so a
18
+ * cache from before it existed decodes and never resumes.
19
+ */
20
+export const ShellCacheOrigin = Schema.Struct({
21
+ serverVersion: Schema.String,
22
+ databaseMigration: Schema.NullOr(Schema.Int),
23
+ omitIdleSubagents: Schema.Boolean,
24
+ omitOlderSettled: Schema.Boolean,
25
+ /** Epoch milliseconds of that snapshot; replay does not renew it. */
26
+ snapshotAt: Schema.Number,
27
+});
28
+export type ShellCacheOrigin = typeof ShellCacheOrigin.Type;
29
+
30
export const StoredOrchestrationShellSnapshot = Schema.Struct({
31
schemaVersion: Schema.Literal(ORCHESTRATION_CACHE_SCHEMA_VERSION),
32
environmentId: EnvironmentId,
33
snapshot: OrchestrationV2ShellSnapshotJson,
34
+ origin: Schema.optionalKey(ShellCacheOrigin),
35
});
36
37
export const StoredOrchestrationThreadSnapshot = Schema.Struct({
packages/client-runtime/src/platform/persistence.ts
+10
-1
@@ -14,6 +14,13 @@ import * as Schema from "effect/Schema";
14
import type { ConnectionRegistration } from "../connection/catalog.ts";
15
import type { DeferredShellSnapshot } from "../state/shellPullRequests.ts";
16
import type { ConnectionTarget, PersistedConnectionTarget } from "../connection/model.ts";
17
+import type { ShellCacheOrigin } from "./orchestrationCache.ts";
18
+
19
+export type { ShellCacheOrigin };
20
+
21
+export interface CachedShellSnapshot extends DeferredShellSnapshot {
22
+ readonly origin?: ShellCacheOrigin;
23
+}
24
25
export class ConnectionPersistenceError extends Schema.TaggedError<ConnectionPersistenceError>()(
26
"ConnectionPersistenceError",
@@ -82,10 +89,12 @@ export class EnvironmentCacheStore extends Context.Service<
89
{
90
readonly loadShell: (
91
environmentId: EnvironmentId,
85
- ) => Effect.Effect<Option.Option<DeferredShellSnapshot>, ConnectionPersistenceError>;
92
+ ) => Effect.Effect<Option.Option<CachedShellSnapshot>, ConnectionPersistenceError>;
93
+ /** `origin` only when the rows descend from a server snapshot. */
94
readonly saveShell: (
95
environmentId: EnvironmentId,
96
snapshot: OrchestrationV2ShellSnapshot,
97
+ origin?: ShellCacheOrigin,
98
) => Effect.Effect<void, ConnectionPersistenceError>;
99
readonly loadThread: (
100
environmentId: EnvironmentId,
packages/client-runtime/src/state/shell-sync.test.ts
+179
@@ -1136,3 +1136,182 @@ describe("environment shell synchronization", () => {
1136
}),
1137
);
1138
});
1139
+
1140
+describe("environment shell cold start", () => {
1141
+ const NOW = 1_800_000_000_000;
1142
+ const HOUR = 60 * 60 * 1000;
1143
+ const CACHED_SEQUENCE = 7;
1144
+ const HTTP_SEQUENCE = 9;
1145
+ // What `session()` advertises: server 1.0.0, no omissions, no migration.
1146
+ const CURRENT_ORIGIN = {
1147
+ serverVersion: "1.0.0",
1148
+ databaseMigration: null,
1149
+ omitIdleSubagents: false,
1150
+ omitOlderSettled: false,
1151
+ };
1152
+ const RECENT_ORIGIN = { ...CURRENT_ORIGIN, snapshotAt: NOW - HOUR };
1153
+
1154
+ const makeColdStart = Effect.fn("test.makeColdStartShell")(function* (
1155
+ origin: Persistence.ShellCacheOrigin | undefined,
1156
+ ) {
1157
+ yield* TestClock.setTime(NOW);
1158
+ const subscriptions = yield* Queue.unbounded<{
1159
+ readonly input: unknown;
1160
+ readonly events: Queue.Queue<OrchestrationV2ShellStreamItem>;
1161
+ }>();
1162
+ const saved = yield* Queue.unbounded<{
1163
+ readonly snapshot: OrchestrationV2ShellSnapshot;
1164
+ readonly origin: Persistence.ShellCacheOrigin | undefined;
1165
+ }>();
1166
+ const httpLoads = yield* Ref.make(0);
1167
+ const client = {
1168
+ [ORCHESTRATION_V2_WS_METHODS.subscribeShell]: (input: unknown) =>
1169
+ Stream.unwrap(
1170
+ Effect.gen(function* () {
1171
+ const events = yield* Queue.unbounded<OrchestrationV2ShellStreamItem>();
1172
+ yield* Queue.offer(subscriptions, { input, events });
1173
+ return Stream.fromQueue(events);
1174
+ }),
1175
+ ),
1176
+ } as unknown as WsRpcProtocolClient;
1177
+ const activeSession = yield* SubscriptionRef.make(Option.some(session(client)));
1178
+ const supervisor = EnvironmentSupervisor.EnvironmentSupervisor.of({
1179
+ target: TARGET,
1180
+ state: yield* SubscriptionRef.make(AVAILABLE_CONNECTION_STATE),
1181
+ session: activeSession,
1182
+ prepared: yield* SubscriptionRef.make(Option.some(PREPARED)),
1183
+ connect: Effect.void,
1184
+ disconnect: Effect.void,
1185
+ retryNow: Effect.void,
1186
+ } satisfies EnvironmentSupervisor.EnvironmentSupervisor["Service"]);
1187
+ const cache = Persistence.EnvironmentCacheStore.of({
1188
+ loadShell: () =>
1189
+ Effect.succeedSome({
1190
+ ...v2ShellSnapshot,
1191
+ snapshotSequence: CACHED_SEQUENCE,
1192
+ ...(origin === undefined ? {} : { origin }),
1193
+ }),
1194
+ saveShell: (_environmentId, snapshot, origin?: Persistence.ShellCacheOrigin) =>
1195
+ Queue.offer(saved, { snapshot, origin }).pipe(Effect.asVoid),
1196
+ loadThread: () => Effect.succeedNone,
1197
+ saveThread: () => Effect.void,
1198
+ removeThread: () => Effect.void,
1199
+ loadServerConfig: () => Effect.succeedNone,
1200
+ saveServerConfig: () => Effect.void,
1201
+ loadVcsRefs: () => Effect.succeedNone,
1202
+ saveVcsRefs: () => Effect.void,
1203
+ removeVcsRefs: () => Effect.void,
1204
+ clearVcsRefs: () => Effect.void,
1205
+ clear: () => Effect.void,
1206
+ });
1207
+ const snapshotLoader = ShellSnapshotLoader.ShellSnapshotLoader.of({
1208
+ load: () =>
1209
+ Ref.updateAndGet(httpLoads, (count) => count + 1).pipe(
1210
+ Effect.map((count) =>
1211
+ Option.some({ ...v2ShellSnapshot, snapshotSequence: HTTP_SEQUENCE + count - 1 }),
1212
+ ),
1213
+ ),
1214
+ });
1215
+ const shellState = yield* makeEnvironmentShellState().pipe(
1216
+ Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
1217
+ Effect.provideService(Persistence.EnvironmentCacheStore, cache),
1218
+ Effect.provideService(ShellSnapshotLoader.ShellSnapshotLoader, snapshotLoader),
1219
+ );
1220
+ return {
1221
+ subscriptions,
1222
+ saved,
1223
+ httpLoads,
1224
+ reconnect: SubscriptionRef.set(activeSession, Option.some(session(client))),
1225
+ liveAt: (sequence: number) =>
1226
+ SubscriptionRef.changes(shellState).pipe(
1227
+ Stream.filter(
1228
+ (state) =>
1229
+ state.status === "live" &&
1230
+ Option.exists(state.snapshot, (snapshot) => snapshot.snapshotSequence === sequence),
1231
+ ),
1232
+ Stream.runHead,
1233
+ Effect.map(Option.getOrThrow),
1234
+ ),
1235
+ };
1236
+ });
1237
+
1238
+ it.effect.each([
1239
+ { label: "a recent matching origin", origin: RECENT_ORIGIN, resumes: true },
1240
+ { label: "no origin", origin: undefined, resumes: false },
1241
+ {
1242
+ label: "other omissions",
1243
+ origin: { ...RECENT_ORIGIN, omitIdleSubagents: true },
1244
+ resumes: false,
1245
+ },
1246
+ {
1247
+ label: "another migration",
1248
+ origin: { ...RECENT_ORIGIN, databaseMigration: 70 },
1249
+ resumes: false,
1250
+ },
1251
+ {
1252
+ label: "another server version",
1253
+ origin: { ...RECENT_ORIGIN, serverVersion: "0.9.0" },
1254
+ resumes: false,
1255
+ },
1256
+ {
1257
+ label: "a 12 hour old origin",
1258
+ origin: { ...RECENT_ORIGIN, snapshotAt: NOW - 12 * HOUR },
1259
+ resumes: false,
1260
+ },
1261
+ ])("starts from a cache with $label (resumes: $resumes)", ({ origin, resumes }) =>
1262
+ Effect.gen(function* () {
1263
+ const h = yield* makeColdStart(origin);
1264
+ const first = yield* Queue.take(h.subscriptions);
1265
+ const sequence = resumes ? CACHED_SEQUENCE : HTTP_SEQUENCE;
1266
+ expect(first.input).toMatchObject({ afterSequence: sequence });
1267
+ // Only held rows may be refused; a fresh snapshot's cursor never loops back to HTTP.
1268
+ if (resumes) expect(first.input).toMatchObject({ httpSnapshotFallback: true });
1269
+ else expect(first.input).not.toHaveProperty("httpSnapshotFallback");
1270
+ expect(yield* Ref.get(h.httpLoads)).toBe(resumes ? 0 : 1);
1271
+
1272
+ // Thread families, older threads, and search wait for a nonzero generation.
1273
+ yield* Queue.offer(first.events, { kind: "synchronized" });
1274
+ expect((yield* h.liveAt(sequence)).generation).toBeGreaterThan(0);
1275
+
1276
+ if (!resumes) {
1277
+ // The next cold start may resume from this snapshot.
1278
+ yield* TestClock.adjust("500 millis");
1279
+ expect(yield* Queue.take(h.saved)).toMatchObject({
1280
+ snapshot: { snapshotSequence: HTTP_SEQUENCE },
1281
+ origin: { ...CURRENT_ORIGIN, snapshotAt: NOW },
1282
+ });
1283
+ }
1284
+ }),
1285
+ );
1286
+
1287
+ it.effect("reloads over HTTP when the server answers a resume with snapshot-required", () =>
1288
+ Effect.gen(function* () {
1289
+ const h = yield* makeColdStart(RECENT_ORIGIN);
1290
+
1291
+ const coldResume = yield* Queue.take(h.subscriptions);
1292
+ expect(coldResume.input).toMatchObject({ afterSequence: CACHED_SEQUENCE });
1293
+ yield* Queue.offer(coldResume.events, { kind: "snapshot-required" });
1294
+ const coldReload = yield* Queue.take(h.subscriptions);
1295
+ expect(coldReload.input).toMatchObject({ afterSequence: HTTP_SEQUENCE });
1296
+ expect(coldReload.input).not.toHaveProperty("httpSnapshotFallback");
1297
+ expect(yield* Ref.get(h.httpLoads)).toBe(1);
1298
+ yield* Queue.offer(coldReload.events, { kind: "synchronized" });
1299
+ expect((yield* h.liveAt(HTTP_SEQUENCE)).generation).toBeGreaterThan(0);
1300
+
1301
+ // A warm reconnect resumes the in-memory shell and falls back the same way.
1302
+ yield* h.reconnect;
1303
+ const warmResume = yield* Queue.take(h.subscriptions);
1304
+ expect(warmResume.input).toMatchObject({
1305
+ afterSequence: HTTP_SEQUENCE,
1306
+ httpSnapshotFallback: true,
1307
+ });
1308
+ expect(yield* Ref.get(h.httpLoads)).toBe(1);
1309
+ yield* Queue.offer(warmResume.events, { kind: "snapshot-required" });
1310
+ const warmReload = yield* Queue.take(h.subscriptions);
1311
+ expect(warmReload.input).toMatchObject({ afterSequence: HTTP_SEQUENCE + 1 });
1312
+ expect(yield* Ref.get(h.httpLoads)).toBe(2);
1313
+ yield* Queue.offer(warmReload.events, { kind: "synchronized" });
1314
+ yield* h.liveAt(HTTP_SEQUENCE + 1);
1315
+ }),
1316
+ );
1317
+});
packages/client-runtime/src/state/shell.ts
+141
-89
@@ -9,6 +9,7 @@ import {
9
type ThreadPullRequestLink,
10
} from "@t3tools/contracts";
11
import * as Cause from "effect/Cause";
12
+import * as Clock from "effect/Clock";
13
import * as Effect from "effect/Effect";
14
import * as Fiber from "effect/Fiber";
15
import * as Option from "effect/Option";
@@ -82,14 +83,41 @@ function withoutDeferredPullRequests(value: DeferredShellSnapshot): Orchestratio
83
84
const SHELL_SYNCHRONIZATION_ERROR_MESSAGE = "Could not synchronize environment data.";
85
85
-function groupBySession<A>(entries: ReadonlyArray<readonly [RpcSession, A]>) {
86
- const groups: Array<[RpcSession, Array<A>]> = [];
87
- for (const [session, value] of entries) {
88
- const last = groups.at(-1);
89
- if (last?.[0] === session) last[1].push(value);
90
- else groups.push([session, [value]]);
91
- }
92
- return groups;
86
+/**
87
+ * Replay does not refresh the older-settled cut, rows that left the newest window, or
88
+ * projections the server rebuilt, so drift grows with the age of the last server snapshot.
89
+ */
90
+const CACHE_RESUME_MAX_AGE_MILLIS = 12 * 60 * 60 * 1000;
91
+
92
+type ShellOriginIdentity = Omit<Persistence.ShellCacheOrigin, "snapshotAt">;
93
+
94
+interface ShellSubscription {
95
+ readonly session: RpcSession;
96
+ /** What a snapshot from this subscription descends from; null when the server did not say. */
97
+ readonly identity: ShellOriginIdentity | null;
98
+}
99
+
100
+function canResumeFrom(
101
+ origin: Persistence.ShellCacheOrigin | undefined,
102
+ identity: ShellOriginIdentity | null,
103
+ now: number,
104
+): boolean {
105
+ if (origin === undefined || identity === null) return false;
106
+ const age = now - origin.snapshotAt;
107
+ return (
108
+ origin.serverVersion === identity.serverVersion &&
109
+ origin.databaseMigration === identity.databaseMigration &&
110
+ origin.omitIdleSubagents === identity.omitIdleSubagents &&
111
+ origin.omitOlderSettled === identity.omitOlderSettled &&
112
+ age >= 0 &&
113
+ age < CACHE_RESUME_MAX_AGE_MILLIS
114
+ );
115
+}
116
+
117
+interface LiveShell {
118
+ readonly snapshot: OrchestrationV2ShellSnapshot;
119
+ // Read together with the rows, so a save never pairs them with another snapshot's origin.
120
+ readonly origin: Persistence.ShellCacheOrigin | undefined;
121
}
122
123
export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")(function* () {
@@ -105,29 +133,30 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
133
environmentId,
134
...safeErrorLogAttributes(error),
135
}),
108
- Effect.as(Option.none<DeferredShellSnapshot>()),
136
+ Effect.as(Option.none<Persistence.CachedShellSnapshot>()),
137
),
138
),
139
);
112
- const cachedSnapshot = Option.map(cached, withoutDeferredPullRequests);
140
+ const cachedOrigin = Option.isSome(cached) ? cached.value.origin : undefined;
141
+ const cachedSnapshot = Option.map(cached, ({ origin: _origin, ...rows }) =>
142
+ withoutDeferredPullRequests(rows),
143
+ );
144
const state = yield* SubscriptionRef.make<EnvironmentShellState>({
145
...EMPTY_SHELL_STATE,
146
snapshot: cachedSnapshot,
147
status: shellStatusForSnapshot(cachedSnapshot),
148
});
149
const awaitingCompletion = yield* Ref.make(false);
119
- // The omissions and server build of the subscription whose snapshot the
120
- // in-memory shell last came from; null while it holds only cached data.
121
- const authoritativeOmission = yield* Ref.make<string | null>(null);
122
- // Items buffered from a previous session keep that session's key.
123
- const sessionOmissions = new WeakMap<RpcSession, string | null>();
124
- const latestLiveSnapshot = yield* Ref.make<Option.Option<OrchestrationV2ShellSnapshot>>(
125
- Option.none(),
126
- );
150
+ const activeSubscription = yield* Ref.make<ShellSubscription | null>(null);
151
+ // The server snapshot the in-memory rows descend from, directly or through the cache.
152
+ // Only a server snapshot renews it; `snapshot-required` drops it.
153
+ const origin = yield* Ref.make(cachedOrigin);
154
+ const reloadRequests = yield* Queue.unbounded<void>();
155
+ const latestLive = yield* Ref.make<Option.Option<LiveShell>>(Option.none());
156
const persistence = yield* Queue.sliding<OrchestrationV2ShellSnapshot>(1);
157
158
const persistenceLock = yield* Semaphore.make(1);
130
- let lastPersisted: OrchestrationV2ShellSnapshot | undefined;
159
+ let lastPersisted: LiveShell | undefined;
160
// Rows still waiting for their deferred pull request links, which must not be saved:
161
// the cache would keep them without links until the next server refresh.
162
let pendingLinkRows: ReadonlySet<OrchestrationV2ThreadShell> = new Set();
@@ -135,24 +164,25 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
164
flush: boolean,
165
) {
166
while (true) {
138
- const latest = yield* Ref.get(latestLiveSnapshot);
167
+ const latest = yield* Ref.get(latestLive);
168
if (Option.isNone(latest) || latest.value === lastPersisted) return;
140
- if (latest.value.threads.some((thread) => pendingLinkRows.has(thread))) return;
141
- const snapshot = latest.value;
169
+ const { snapshot, origin } = latest.value;
170
+ if (snapshot.threads.some((thread) => pendingLinkRows.has(thread))) return;
171
if (
172
lastPersisted !== undefined &&
144
- snapshot.snapshotSequence >= lastPersisted.snapshotSequence &&
145
- snapshot.schemaVersion === lastPersisted.schemaVersion &&
146
- snapshot.projects === lastPersisted.projects &&
147
- snapshot.threads === lastPersisted.threads &&
148
- snapshot.archivedThreads === lastPersisted.archivedThreads
173
+ origin === lastPersisted.origin &&
174
+ snapshot.snapshotSequence >= lastPersisted.snapshot.snapshotSequence &&
175
+ snapshot.schemaVersion === lastPersisted.snapshot.schemaVersion &&
176
+ snapshot.projects === lastPersisted.snapshot.projects &&
177
+ snapshot.threads === lastPersisted.snapshot.threads &&
178
+ snapshot.archivedThreads === lastPersisted.snapshot.archivedThreads
179
) {
180
// Keep the live cursor without rewriting the rows. Remember it here too so a
181
// later authoritative reset to a lower sequence still reaches the cache.
152
- lastPersisted = snapshot;
182
+ lastPersisted = latest.value;
183
return;
184
}
155
- const saved = yield* cache.saveShell(environmentId, snapshot).pipe(
185
+ const saved = yield* cache.saveShell(environmentId, snapshot, origin).pipe(
186
Effect.as(true),
187
Effect.catch((error) =>
188
Effect.logWarning("Could not persist environment shell cache.").pipe(
@@ -162,7 +192,7 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
192
),
193
);
194
if (!saved) return;
165
- lastPersisted = snapshot;
195
+ lastPersisted = latest.value;
196
if (!flush) return;
197
}
198
}, persistenceLock.withPermit);
@@ -220,14 +250,20 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
250
const snapshotWriteLock = yield* Semaphore.make(1);
251
252
const applyItems = Effect.fn("EnvironmentShellState.applyItems")(function* (
223
- items: ReadonlyArray<OrchestrationV2ShellStreamItem>,
224
- omission: string | null,
253
+ entries: ReadonlyArray<readonly [RpcSession, OrchestrationV2ShellStreamItem]>,
254
pendingLinkIds?: ReadonlySet<ThreadId>,
255
) {
256
+ // Read under the lock: items buffered across a session change must not land on the
257
+ // rows the next session loaded.
258
+ const subscription = yield* Ref.get(activeSubscription);
259
+ const items = entries.flatMap(([session, item]) =>
260
+ session === subscription?.session ? [item] : [],
261
+ );
262
const initial = yield* SubscriptionRef.get(state);
263
let waiting = yield* Ref.get(awaitingCompletion);
264
let next = initial;
265
let receivedAuthoritativeSnapshot = false;
266
+ let snapshotRequired = false;
267
let deltas: Array<ShellStreamEvent> = [];
268
const flushDeltas = () => {
269
if (deltas.length > 0 && Option.isSome(next.snapshot)) {
@@ -260,6 +296,10 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
296
deltas = [];
297
};
298
for (const item of items) {
299
+ if (item.kind === "snapshot-required") {
300
+ snapshotRequired = true;
301
+ continue;
302
+ }
303
if (item.kind !== "snapshot" && item.kind !== "synchronized") {
304
deltas.push(item);
305
continue;
@@ -269,7 +309,13 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
309
if (item.kind === "synchronized") {
310
waiting = false;
311
if (Option.isSome(next.snapshot)) {
272
- next = { ...next, status: "live", error: Option.none() };
312
+ next = {
313
+ ...next,
314
+ status: "live",
315
+ error: Option.none(),
316
+ // A cache resume that caught up is as current as a snapshot for generation readers.
317
+ generation: next.generation === 0 ? ++lastShellGeneration : next.generation,
318
+ };
319
}
320
continue;
321
}
@@ -292,6 +338,20 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
338
}
339
flushDeltas();
340
yield* Ref.set(awaitingCompletion, waiting);
341
+ let nextOrigin = yield* Ref.get(origin);
342
+ if (snapshotRequired) {
343
+ // The rows stay on screen but reload before the next resume; the cache keeps the old
344
+ // origin until that reload saves, which costs at most one more refusal.
345
+ nextOrigin = undefined;
346
+ yield* Ref.set(origin, nextOrigin);
347
+ yield* Queue.offer(reloadRequests, undefined);
348
+ } else if (receivedAuthoritativeSnapshot) {
349
+ nextOrigin =
350
+ subscription?.identity == null
351
+ ? undefined
352
+ : { ...subscription.identity, snapshotAt: yield* Clock.currentTimeMillis };
353
+ yield* Ref.set(origin, nextOrigin);
354
+ }
355
if (next === initial) return;
356
if (pendingLinkIds !== undefined && Option.isSome(next.snapshot)) {
357
pendingLinkRows = new Set(
@@ -299,12 +359,12 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
359
);
360
}
361
if (Option.isSome(next.snapshot)) {
302
- yield* Ref.set(latestLiveSnapshot, next.snapshot);
362
+ yield* Ref.set(
363
+ latestLive,
364
+ Option.some({ snapshot: next.snapshot.value, origin: nextOrigin }),
365
+ );
366
}
367
yield* SubscriptionRef.set(state, next);
305
- if (receivedAuthoritativeSnapshot && omission !== null) {
306
- yield* Ref.set(authoritativeOmission, omission);
307
- }
368
if (next.snapshot !== initial.snapshot && Option.isSome(next.snapshot)) {
369
yield* Queue.offer(persistence, next.snapshot.value);
370
}
@@ -365,11 +425,11 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
425
},
426
);
427
pendingLinkRows = new Set();
368
- const live = yield* Ref.get(latestLiveSnapshot);
428
+ const live = yield* Ref.get(latestLive);
429
if (Option.isNone(live)) return;
370
- const latest = Option.isSome(filled) ? filled : live;
371
- yield* Ref.set(latestLiveSnapshot, latest);
372
- yield* Queue.offer(persistence, latest.value);
430
+ const latest = Option.isSome(filled) ? filled.value : live.value.snapshot;
431
+ yield* Ref.set(latestLive, Option.some({ snapshot: latest, origin: live.value.origin }));
432
+ yield* Queue.offer(persistence, latest);
433
},
434
(effect) => snapshotWriteLock.withPermit(effect),
435
);
@@ -377,53 +437,52 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
437
yield* fillDeferredPullRequests(cached.value, cachedSnapshot.value);
438
}
439
380
- const foregroundResubscriptions = Option.match(wakeups, {
381
- onNone: () => Stream.never,
382
- onSome: (service) =>
383
- service.changes.pipe(Stream.filter(ConnectionWakeups.shouldResubscribeAfterWakeup)),
384
- });
440
+ const resubscriptions = Stream.merge(
441
+ Stream.fromQueue(reloadRequests),
442
+ Option.match(wakeups, {
443
+ onNone: () => Stream.never,
444
+ onSome: (service) =>
445
+ service.changes.pipe(Stream.filter(ConnectionWakeups.shouldResubscribeAfterWakeup)),
446
+ }),
447
+ );
448
449
yield* setSynchronizing;
450
yield* Effect.forkScoped(
451
subscribeDynamicWithSession(
452
ORCHESTRATION_V2_WS_METHODS.subscribeShell,
453
Effect.fn("EnvironmentShellState.makeSubscribeInput")(function* (session) {
391
- const { omitIdleSubagents, omitOlderSettled, omissionKey } =
392
- yield* session.initialConfig.pipe(
393
- Effect.map((config) => {
394
- const omitIdleSubagents = config.shellThreadFamilies === true;
395
- const omitOlderSettled = config.shellOlderSettled === true && omitIdleSubagents;
396
- // Migrations rewrite projections without events, so an upgraded server reloads.
397
- const { serverVersion, databaseMigration } = config.environment;
398
- return {
399
- omitIdleSubagents,
400
- omitOlderSettled,
401
- omissionKey: JSON.stringify([
402
- omitIdleSubagents,
403
- omitOlderSettled,
404
- serverVersion,
405
- databaseMigration ?? null,
406
- ]),
407
- };
408
- }),
409
- Effect.orElseSucceed(() => ({
410
- omitIdleSubagents: false,
411
- omitOlderSettled: false,
412
- omissionKey: null,
413
- })),
414
- );
415
- sessionOmissions.set(session, omissionKey);
454
+ const identity = yield* session.initialConfig.pipe(
455
+ Effect.map((config): ShellOriginIdentity => {
456
+ const omitIdleSubagents = config.shellThreadFamilies === true;
457
+ return {
458
+ serverVersion: config.environment.serverVersion,
459
+ // Migrations rewrite projections without events, so a migrated server reloads.
460
+ databaseMigration: config.environment.databaseMigration ?? null,
461
+ omitIdleSubagents,
462
+ omitOlderSettled: config.shellOlderSettled === true && omitIdleSubagents,
463
+ };
464
+ }),
465
+ Effect.orElseSucceed(() => null),
466
+ );
467
+ const { omitIdleSubagents, omitOlderSettled } = identity ?? {
468
+ omitIdleSubagents: false,
469
+ omitOlderSettled: false,
470
+ };
471
+ yield* Ref.set(activeSubscription, { session, identity });
472
yield* Ref.set(awaitingCompletion, true);
473
yield* setSynchronizing;
474
419
- // A shell from a server snapshot resumes from its cursor, on this session or a
420
- // new one. Cached data, other omissions, or another server build reload the
421
- // authoritative HTTP snapshot so a valid cursor cannot preserve stale data.
422
- const hasAuthoritativeSnapshot =
423
- omissionKey !== null && (yield* Ref.get(authoritativeOmission)) === omissionKey;
424
- let canResume = hasAuthoritativeSnapshot;
475
+ // Rows from a recent server snapshot with the same omissions and server build resume
476
+ // from their cursor, in memory or from the cache. Anything else reloads the HTTP
477
+ // snapshot so a valid cursor cannot preserve stale or incomplete data.
478
let current = yield* SubscriptionRef.get(state);
426
- if (!hasAuthoritativeSnapshot || Option.isNone(current.snapshot)) {
479
+ let canResume =
480
+ Option.isSome(current.snapshot) &&
481
+ canResumeFrom(yield* Ref.get(origin), identity, yield* Clock.currentTimeMillis);
482
+ // Only rows the client already held may be refused; a cursor from the snapshot just
483
+ // loaded falls back to the socket snapshot, so a refusal cannot loop.
484
+ const resumingHeldRows = canResume;
485
+ if (!canResume) {
486
const prepared = yield* SubscriptionRef.get(supervisor.prepared).pipe(
487
Effect.flatMap(
488
Option.match({
@@ -455,7 +514,7 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
514
? []
515
: httpSnapshot.value.threads.map((thread) => thread.id),
516
);
458
- yield* applyItems([{ kind: "snapshot", snapshot }], omissionKey, pendingLinkIds);
517
+ yield* applyItems([[session, { kind: "snapshot", snapshot }]], pendingLinkIds);
518
canResume = true;
519
current = yield* SubscriptionRef.get(state);
520
if (Option.isSome(current.snapshot)) {
@@ -473,6 +532,7 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
532
}
533
return {
534
afterSequence: current.snapshot.value.snapshotSequence,
535
+ ...(resumingHeldRows ? { httpSnapshotFallback: true as const } : {}),
536
...omission,
537
requestCompletionMarker: true as const,
538
};
@@ -480,17 +540,9 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
540
{
541
onExpectedFailure: (cause) => setStreamError(Cause.squash(cause)),
542
retryExpectedFailureAfter: "250 millis",
483
- resubscribe: foregroundResubscriptions,
543
+ resubscribe: resubscriptions,
544
},
485
- ).pipe(
486
- Stream.runForEachArray((entries) =>
487
- Effect.forEach(
488
- groupBySession(entries),
489
- ([session, items]) => applyItems(items, sessionOmissions.get(session) ?? null),
490
- { discard: true },
491
- ),
492
- ),
493
- ),
545
+ ).pipe(Stream.runForEachArray((entries) => applyItems(entries))),
546
);
547
yield* SubscriptionRef.changes(supervisor.state).pipe(
548
Stream.runForEach((connectionState) => {
packages/client-runtime/src/state/shellReducer.ts
+3
-6
@@ -131,10 +131,7 @@ export function mergeShellSnapshotProjects(
131
132
export function applyShellStreamEvent(
133
snapshot: OrchestrationV2ShellSnapshot,
134
- event: Exclude<
135
- OrchestrationV2ShellStreamItem,
136
- { readonly kind: "snapshot" } | { readonly kind: "synchronized" }
137
- >,
134
+ event: ShellStreamEvent,
135
): OrchestrationV2ShellSnapshot {
136
if (event.sequence <= snapshot.snapshotSequence) return snapshot;
137
@@ -217,9 +214,9 @@ function batchRows<T extends { readonly id: unknown }>(rows: ReadonlyArray<T>) {
214
};
215
}
216
220
-export type ShellStreamEvent = Exclude<
217
+export type ShellStreamEvent = Extract<
218
OrchestrationV2ShellStreamItem,
222
- { readonly kind: "snapshot" } | { readonly kind: "synchronized" }
219
+ { readonly sequence: number }
220
>;
221
222
/** Apply ordered deltas with one index and at most one new array per collection. */
packages/contracts/src/orchestrationV2.ts
+12
@@ -2243,6 +2243,13 @@ export const OrchestrationV2ShellStreamItem = Schema.Union([
2243
Schema.Struct({
2244
kind: Schema.Literal("synchronized"),
2245
}),
2246
+ /**
2247
+ * The only item of a resume the server cannot replay when the client asked for
2248
+ * `httpSnapshotFallback`: load the HTTP snapshot and subscribe again from its cursor.
2249
+ */
2250
+ Schema.Struct({
2251
+ kind: Schema.Literal("snapshot-required"),
2252
+ }),
2253
Schema.Struct({
2254
kind: Schema.Literal("snapshot"),
2255
snapshot: OrchestrationV2ShellSnapshot,
@@ -3692,6 +3699,11 @@ export type OrchestrationV2GetThreadProjectionInput =
3699
3700
export const OrchestrationV2SubscribeShellInput = Schema.Struct({
3701
afterSequence: Schema.optionalKey(NonNegativeInt),
3702
+ /**
3703
+ * With `afterSequence`, a gap the server cannot replay answers `snapshot-required` instead of
3704
+ * a socket snapshot, which clients without transport compression download over gzip HTTP.
3705
+ */
3706
+ httpSnapshotFallback: Schema.optionalKey(Schema.Literal(true)),
3707
requestCompletionMarker: Schema.optionalKey(Schema.Boolean),
3708
/**
3709
* Snapshots leave out idle subagent children; read them with `getThreadFamily`. Send only to