The best way to control Claude Code, Codex and more from any computer or phone
fix(pi): fork historical turns from their original session (#38315)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Benjamin Nasse committed
Nov 17, 2026 at 15:48 UTC
2ebe7f8e22617d0eb8deb93ce4f458aba3e9a434
3 files changed
+252
-24
packages/contracts/src/orchestrationV2.ts
+2
@@ -1232,6 +1232,8 @@ export const OrchestrationV2ProviderTurn = Schema.Struct({
1232
nodeId: NodeId,
1233
runAttemptId: Schema.NullOr(RunAttemptId),
1234
nativeTurnRef: Schema.NullOr(OrchestrationV2ProviderRef),
1235
+ /** The native session that held this turn, when a provider can move a thread between sessions. */
1236
+ nativeThreadRef: Schema.optional(OrchestrationV2ProviderRef),
1237
ordinal: PositiveInt,
1238
status: Schema.Literals([
1239
"pending",
packages/provider-pi/src/server/adapter.test.ts
+104
-5
@@ -164,6 +164,7 @@ interface FakePi {
164
readonly queueEntries: (data: unknown) => void;
165
readonly queueMessages: (data: unknown) => void;
166
readonly vetoNextSwitch: () => void;
167
+ readonly failNextFork: () => void;
168
readonly queueState: (data: Record<string, unknown>) => void;
169
readonly setStreaming: (streaming: boolean) => void;
170
readonly setCompacting: (compacting: boolean) => void;
@@ -237,6 +238,7 @@ const makeFakePi: Effect.Effect<FakePi> = Effect.gen(function* () {
238
let failStateAfter: number | null = null;
239
let failThinking = false;
240
let vetoSwitch = false;
241
+ let failFork = false;
242
let vetoNewSession = false;
243
let deferredLifecycle: string | undefined;
244
let sessionFile = FAKE_SESSION_FILE;
@@ -354,6 +356,10 @@ const makeFakePi: Effect.Effect<FakePi> = Effect.gen(function* () {
356
case "get_session_stats":
357
return { ...base, data: statsQueue.shift() ?? {} };
358
case "fork":
359
+ if (failFork) {
360
+ failFork = false;
361
+ return { ...base, success: false, error: "Invalid entry ID for forking" };
362
+ }
363
serviceTier = null;
364
return { ...base, data: { text: "Hello pi", cancelled: false } };
365
case "clear_queue":
@@ -498,6 +504,9 @@ const makeFakePi: Effect.Effect<FakePi> = Effect.gen(function* () {
504
vetoNextSwitch: () => {
505
vetoSwitch = true;
506
},
507
+ failNextFork: () => {
508
+ failFork = true;
509
+ },
510
queueState: (data) => stateQueue.push(data),
511
setStreaming: (streaming) => {
512
isStreaming = streaming;
@@ -2806,6 +2815,16 @@ describe("PiAdapterV2", () => {
2815
yield* fake.emit({ type: "agent_start" });
2816
yield* fake.emit({ type: "agent_end", messages: [], willRetry: false });
2817
yield* fake.emit({ type: "agent_settled" });
2818
+ const completed = yield* takeEvent(
2819
+ (event) =>
2820
+ event.type === "provider_turn.updated" && event.providerTurn.status === "completed",
2821
+ );
2822
+ assert.equal(
2823
+ completed.type === "provider_turn.updated"
2824
+ ? completed.providerTurn.nativeThreadRef?.nativeId
2825
+ : undefined,
2826
+ childFile,
2827
+ );
2828
const idle = yield* takeEvent(
2829
(event) =>
2830
event.type === "provider_thread.updated" && event.providerThread.status === "idle",
@@ -2965,9 +2984,21 @@ describe("PiAdapterV2", () => {
2984
);
2985
2986
it.effect.each([
2968
- { historical: false, label: "the latest turn" },
2969
- { historical: true, label: "a historical turn" },
2970
- ])("natively forks $label into an independent session", ({ historical }) =>
2987
+ { historical: false, moved: false, split: false, label: "the latest turn" },
2988
+ { historical: true, moved: false, split: false, label: "a historical turn" },
2989
+ {
2990
+ historical: true,
2991
+ moved: true,
2992
+ split: false,
2993
+ label: "a historical turn after a session switch",
2994
+ },
2995
+ {
2996
+ historical: true,
2997
+ moved: true,
2998
+ split: true,
2999
+ label: "the last turn before a switch to a fresh session",
3000
+ },
3001
+ ])("natively forks $label into an independent session", ({ historical, moved, split }) =>
3002
Effect.gen(function* () {
3003
const fake = yield* makeFakePi;
3004
const forkFake = yield* makeFakePi;
@@ -2984,12 +3015,22 @@ describe("PiAdapterV2", () => {
3015
modelSelection: modelSelection("default"),
3016
runtimePolicy,
3017
});
3018
+ const freshSession = {
3019
+ driver: PI_PROVIDER,
3020
+ nativeId: "/fake/new-session.jsonl",
3021
+ strength: "strong",
3022
+ } as const;
3023
const turn = (ordinal: number): OrchestrationV2ProviderTurn => ({
3024
id: ProviderTurnId.make(`turn-${ordinal}`),
3025
providerThreadId: source.id,
3026
nodeId: NodeId.make(`node-${ordinal}`),
3027
runAttemptId: null,
3028
nativeTurnRef: { driver: PI_PROVIDER, nativeId: `u${ordinal}`, strength: "strong" },
3029
+ ...(split && ordinal === 2
3030
+ ? { nativeThreadRef: freshSession }
3031
+ : moved && source.nativeThreadRef !== null
3032
+ ? { nativeThreadRef: source.nativeThreadRef }
3033
+ : {}),
3034
ordinal,
3035
status: "completed",
3036
startedAt: null,
@@ -3005,7 +3046,7 @@ describe("PiAdapterV2", () => {
3046
fake.queueState({ sessionFile: forkFile });
3047
const target = ThreadId.make("fork-target");
3048
const forked = yield* runtime.forkThread({
3008
- sourceProviderThread: source,
3049
+ sourceProviderThread: moved ? { ...source, nativeThreadRef: freshSession } : source,
3050
sourceProviderTurns: historical ? [turn(1), turn(2)] : [turn(1)],
3051
providerTurnId: turn(1).id,
3052
targetThreadId: target,
@@ -3025,7 +3066,7 @@ describe("PiAdapterV2", () => {
3066
.allRequests()
3067
.filter((request) => request.type === "fork")
3068
.map((request) => request.entryId),
3028
- historical ? ["u2"] : [],
3069
+ historical && !split ? ["u2"] : [],
3070
);
3071
assert.isFalse(
3072
fake.allRequests().some((request) => request.type === "fork" || request.type === "clone"),
@@ -3061,6 +3102,64 @@ describe("PiAdapterV2", () => {
3102
}).pipe(Effect.scoped, Effect.provide(layerTest)),
3103
);
3104
3105
+ it.effect("recovers a historical Pi fork recorded before turns stored the session file", () =>
3106
+ Effect.gen(function* () {
3107
+ const fs = yield* FileSystem.FileSystem;
3108
+ const dir = yield* fs.makeTempDirectoryScoped();
3109
+ const oldFile = `${dir}/original.jsonl`;
3110
+ const unrelatedFile = `${dir}/unrelated.jsonl`;
3111
+ const currentFile = `${dir}/current.jsonl`;
3112
+ const header = { type: "session", version: 3 };
3113
+ const writeSession = (file: string, entries: ReadonlyArray<unknown>) =>
3114
+ fs.writeFileString(
3115
+ file,
3116
+ [header, ...entries].map((entry) => encodeJsonLine(entry)).join("\n") + "\n",
3117
+ );
3118
+ yield* writeSession(oldFile, UNCAPTURED_TURN_TREE.entries);
3119
+ yield* writeSession(unrelatedFile, [
3120
+ sessionMessage("u1", null, "user", 10),
3121
+ sessionMessage("u2", null, "user", 110),
3122
+ ]);
3123
+ yield* writeSession(currentFile, [sessionMessage("new", null, "user", 120)]);
3124
+
3125
+ const fake = yield* makeFakePi;
3126
+ const forkFake = yield* makeFakePi;
3127
+ const { runtime } = yield* openRuntime(fake, "default", THREAD_ID, SESSION_ID, forkFake);
3128
+ const source = yield* runtime.ensureThread({
3129
+ threadId: THREAD_ID,
3130
+ modelSelection: modelSelection("default"),
3131
+ runtimePolicy,
3132
+ });
3133
+ const forkFile = `${dir}/forked.jsonl`;
3134
+ forkFake.failNextFork();
3135
+ forkFake.queueState({ sessionFile: forkFile });
3136
+ fake.queueState({ sessionFile: forkFile });
3137
+ const [target, boundary] = uncapturedTurns(source.id, {
3138
+ startedAt: 100,
3139
+ completedAt: 145,
3140
+ });
3141
+ if (target === undefined || boundary === undefined) throw new Error("missing fork turns");
3142
+ const forked = yield* runtime.forkThread({
3143
+ sourceProviderThread: {
3144
+ ...source,
3145
+ nativeThreadRef: { driver: PI_PROVIDER, nativeId: currentFile, strength: "strong" },
3146
+ },
3147
+ sourceProviderTurns: [
3148
+ target,
3149
+ {
3150
+ ...boundary,
3151
+ nativeTurnRef: { driver: PI_PROVIDER, nativeId: "u2", strength: "strong" },
3152
+ },
3153
+ ],
3154
+ providerTurnId: target.id,
3155
+ targetThreadId: ThreadId.make("fork-target"),
3156
+ });
3157
+ const args = forkFake.lastSpawn().args;
3158
+ assert.equal(args[args.indexOf("--fork") + 1], oldFile);
3159
+ assert.equal(forked.nativeThreadRef?.nativeId, forkFile);
3160
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
3161
+ );
3162
+
3163
it.effect("natively forks before a turn whose start entry was never captured", () =>
3164
Effect.gen(function* () {
3165
const fake = yield* makeFakePi;
packages/provider-pi/src/server/adapter.ts
+146
-19
@@ -521,7 +521,7 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* (
521
Effect.orElseSucceed(() => undefined),
522
);
523
if (header === undefined) return true;
524
- const sessionCwd = recordString(Option.getOrUndefined(decodeSessionHeader(header)), "cwd");
524
+ const sessionCwd = recordString(Option.getOrUndefined(decodeSessionLine(header)), "cwd");
525
if (sessionCwd === undefined || sessionCwd === cwd) return true;
526
const realCwd = yield* fileSystem.realPath(cwd).pipe(Effect.orElseSucceed(() => cwd));
527
return sessionCwd === realCwd;
@@ -2076,6 +2076,9 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* (
2076
...(treeRefs === null || treeRefs.nativeTurnRef === undefined
2077
? {}
2078
: { nativeTurnRef: treeRefs.nativeTurnRef }),
2079
+ ...(state.providerThread.nativeThreadRef === null
2080
+ ? {}
2081
+ : { nativeThreadRef: state.providerThread.nativeThreadRef }),
2082
status: interrupted ? "interrupted" : failure !== null ? "failed" : "completed",
2083
completedAt,
2084
...(tokenUsage === undefined ? {} : { tokenUsage }),
@@ -2951,6 +2954,68 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* (
2954
).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner));
2955
});
2956
2957
+ // Old records hold entry IDs without a session file. Recover only when both
2958
+ // timestamped user entries are on the same branch in a sibling session.
2959
+ const findHistoricalForkSession = Effect.fnUntraced(function* (
2960
+ currentFile: string,
2961
+ boundary: Extract<PiForkBoundary, { type: "entry" }>,
2962
+ ) {
2963
+ const targetId = piTurnEntryId(boundary.target);
2964
+ const startedAt = boundary.target?.startedAt;
2965
+ const completedAt = boundary.target?.completedAt;
2966
+ const boundaryEnd = boundary.turn.completedAt;
2967
+ if (
2968
+ targetId === undefined ||
2969
+ startedAt == null ||
2970
+ completedAt == null ||
2971
+ boundaryEnd === null
2972
+ ) {
2973
+ return undefined;
2974
+ }
2975
+ const from = DateTime.toEpochMillis(startedAt);
2976
+ const between = DateTime.toEpochMillis(completedAt);
2977
+ const to = DateTime.toEpochMillis(boundaryEnd);
2978
+ const dir = path.dirname(currentFile);
2979
+ const siblings = yield* fileSystem
2980
+ .readDirectoryEntries(dir)
2981
+ .pipe(Effect.orElseSucceed(() => []));
2982
+ const files = siblings
2983
+ .filter((entry) => entry.type === "File" && entry.name.endsWith(".jsonl"))
2984
+ .map((entry) => path.join(dir, entry.name))
2985
+ .sort()
2986
+ .reverse();
2987
+ for (const file of files) {
2988
+ if (file === currentFile) continue;
2989
+ const entries = new Map<string, PiSessionEntry>();
2990
+ let leafId: string | null = null;
2991
+ const readable = yield* fileSystem.stream(file).pipe(
2992
+ Stream.decodeText(),
2993
+ Stream.splitLines,
2994
+ Stream.runForEach((line) =>
2995
+ Effect.sync(() => {
2996
+ const entry = readPiSessionEntry(Option.getOrUndefined(decodeSessionLine(line)));
2997
+ if (entry === null) return;
2998
+ const [id, value] = entry;
2999
+ entries.set(id, value);
3000
+ leafId = id;
3001
+ }),
3002
+ ),
3003
+ Effect.as(true),
3004
+ Effect.orElseSucceed(() => false),
3005
+ );
3006
+ if (
3007
+ readable &&
3008
+ piUserEntryInWindow(entries.get(targetId), from, between) &&
3009
+ piUserEntryInWindow(entries.get(boundary.entryId), between, to) &&
3010
+ walkPiBranch(entries, leafId, boundary.entryId)?.reachedStop === true &&
3011
+ walkPiBranch(entries, boundary.entryId, targetId)?.reachedStop === true
3012
+ ) {
3013
+ return file;
3014
+ }
3015
+ }
3016
+ return undefined;
3017
+ });
3018
+
3019
const sessionFileInCwd = Effect.fnUntraced(function* (
3020
sessionFile: string,
3021
providerThreadCreatedAt: DateTime.Utc,
@@ -3369,6 +3434,9 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* (
3434
nodeId: turnInput.rootNodeId,
3435
runAttemptId: turnInput.attemptId,
3436
nativeTurnRef: providerRef(syntheticNativeTurnId, "weak"),
3437
+ ...(state.providerThread.nativeThreadRef === null
3438
+ ? {}
3439
+ : { nativeThreadRef: state.providerThread.nativeThreadRef }),
3440
ordinal: turnInput.providerTurnOrdinal,
3441
status: "running",
3442
startedAt,
@@ -3927,8 +3995,8 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* (
3995
return yield* protocolError("Cannot fork while a Pi turn is active");
3996
}
3997
const source = forkInput.sourceProviderThread;
3930
- const sourceFile = source.nativeThreadRef?.nativeId;
3931
- if (sourceFile == null)
3998
+ const currentFile = source.nativeThreadRef?.nativeId;
3999
+ if (currentFile == null)
4000
return yield* protocolError("Pi fork source has no session file");
4001
const sourceTurns = (forkInput.sourceProviderTurns ?? []).filter(
4002
(turn) => turn.providerThreadId === source.id,
@@ -3937,14 +4005,39 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* (
4005
if (forkInput.providerTurnId !== undefined && target === undefined) {
4006
return yield* protocolError("Pi fork target turn is missing");
4007
}
4008
+ const targetFile = target?.nativeThreadRef?.nativeId ?? undefined;
4009
const boundary: PiForkBoundary =
4010
target === undefined
4011
? { type: "nothing" }
4012
: piForkBoundary({
4013
target: { type: "provider_turn", providerTurn: target },
4014
providerThreadTurns: sourceTurns,
4015
+ sessionFile: targetFile,
4016
});
3947
- const nativeId = yield* forkSessionIntoCwd(sourceFile, boundary, source.createdAt);
4017
+ const boundaryFile =
4018
+ boundary.type === "nothing" ? undefined : boundary.turn.nativeThreadRef?.nativeId;
4019
+ const sourceFile = targetFile ?? boundaryFile ?? currentFile;
4020
+ const nativeId = yield* forkSessionIntoCwd(sourceFile, boundary, source.createdAt).pipe(
4021
+ Effect.catchTags({
4022
+ PiRpcError: (error) => {
4023
+ if (
4024
+ boundary.type !== "entry" ||
4025
+ boundaryFile != null ||
4026
+ error.operation !== "fork" ||
4027
+ error.detail !== "Invalid entry ID for forking"
4028
+ ) {
4029
+ return Effect.fail(error);
4030
+ }
4031
+ return findHistoricalForkSession(currentFile, boundary).pipe(
4032
+ Effect.flatMap((file) =>
4033
+ file === undefined
4034
+ ? Effect.fail(error)
4035
+ : forkSessionIntoCwd(file, boundary, source.createdAt),
4036
+ ),
4037
+ );
4038
+ },
4039
+ }),
4040
+ );
4041
const now = yield* DateTime.now;
4042
return yield* registerThread(
4043
{
@@ -3998,7 +4091,7 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* (
4091
});
4092
});
4093
4001
-const decodeSessionHeader = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown));
4094
+const decodeSessionLine = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown));
4095
4096
interface PiSessionEntry {
4097
readonly parentId: string | null;
@@ -4021,15 +4114,24 @@ function piSessionListing(data: unknown): PiSessionListing | null {
4114
}
4115
4116
function piSessionEntries(entries: unknown): ReadonlyMap<string, PiSessionEntry> | null {
4024
- const byId = new Map<string, PiSessionEntry>();
4117
if (!Array.isArray(entries)) return null;
4026
- for (const entry of entries) {
4027
- const id = recordString(entry, "id");
4028
- const parentId = recordField(entry, "parentId");
4029
- if (id === undefined || byId.has(id) || (parentId !== null && typeof parentId !== "string"))
4030
- return null;
4031
- const timestamp = recordString(entry, "timestamp");
4032
- byId.set(id, {
4118
+ const byId = new Map<string, PiSessionEntry>();
4119
+ for (const raw of entries) {
4120
+ const entry = readPiSessionEntry(raw);
4121
+ if (entry === null || byId.has(entry[0])) return null;
4122
+ byId.set(...entry);
4123
+ }
4124
+ return byId;
4125
+}
4126
+
4127
+function readPiSessionEntry(entry: unknown): [string, PiSessionEntry] | null {
4128
+ const id = recordString(entry, "id");
4129
+ const parentId = recordField(entry, "parentId");
4130
+ if (id === undefined || (parentId !== null && typeof parentId !== "string")) return null;
4131
+ const timestamp = recordString(entry, "timestamp");
4132
+ return [
4133
+ id,
4134
+ {
4135
parentId,
4136
isUserMessage:
4137
recordField(entry, "type") === "message" &&
@@ -4038,9 +4140,22 @@ function piSessionEntries(entries: unknown): ReadonlyMap<string, PiSessionEntry>
4140
timestamp === undefined
4141
? null
4142
: Option.getOrNull(Option.map(DateTime.make(timestamp), DateTime.toEpochMillis)),
4041
- });
4042
- }
4043
- return byId;
4143
+ },
4144
+ ];
4145
+}
4146
+
4147
+function piUserEntryInWindow(entry: PiSessionEntry | undefined, from: number, to: number): boolean {
4148
+ return (
4149
+ entry?.isUserMessage === true &&
4150
+ entry.timestamp !== null &&
4151
+ entry.timestamp >= from &&
4152
+ entry.timestamp <= to
4153
+ );
4154
+}
4155
+
4156
+function piTurnEntryId(turn: OrchestrationV2ProviderTurn | null | undefined): string | undefined {
4157
+ const ref = turn?.nativeTurnRef;
4158
+ return ref?.strength === "strong" ? (ref.nativeId ?? undefined) : undefined;
4159
}
4160
4161
function walkPiBranch(
@@ -4067,7 +4182,12 @@ function walkPiBranch(
4182
}
4183
4184
type PiForkBoundary =
4070
- | { readonly type: "entry"; readonly entryId: string }
4185
+ | {
4186
+ readonly type: "entry";
4187
+ readonly entryId: string;
4188
+ readonly turn: OrchestrationV2ProviderTurn;
4189
+ readonly target: OrchestrationV2ProviderTurn | null;
4190
+ }
4191
| { readonly type: "nothing" }
4192
| {
4193
readonly type: "uncaptured";
@@ -4085,15 +4205,22 @@ function piForkBoundary(input: {
4205
| { readonly type: "thread_start" }
4206
| { readonly type: "provider_turn"; readonly providerTurn: OrchestrationV2ProviderTurn };
4207
readonly providerThreadTurns: ReadonlyArray<OrchestrationV2ProviderTurn>;
4208
+ /** Only turns recorded in this session can bound a fork from it. */
4209
+ readonly sessionFile?: string | undefined;
4210
}): PiForkBoundary {
4211
const target = input.target.type === "thread_start" ? null : input.target.providerTurn;
4212
const boundary = input.providerThreadTurns
4091
- .filter((turn) => turn.ordinal > (target?.ordinal ?? 0) && turn.nativeTurnRef !== null)
4213
+ .filter(
4214
+ (turn) =>
4215
+ turn.ordinal > (target?.ordinal ?? 0) &&
4216
+ turn.nativeTurnRef !== null &&
4217
+ (input.sessionFile === undefined || turn.nativeThreadRef?.nativeId === input.sessionFile),
4218
+ )
4219
.sort((a, b) => a.ordinal - b.ordinal)[0];
4220
const ref = boundary?.nativeTurnRef;
4221
if (boundary === undefined || ref == null) return { type: "nothing" };
4222
return ref.strength === "strong" && ref.nativeId !== null
4096
- ? { type: "entry", entryId: ref.nativeId }
4223
+ ? { type: "entry", entryId: ref.nativeId, turn: boundary, target }
4224
: { type: "uncaptured", turn: boundary, target };
4225
}
4226