Commit c2b9680a5efc0855d24fb5a4bdcf9320469354d4 | the-knife

apps/server/integration/OrchestrationEngineHarness.integration.ts-6

 @@ -6,7 +6,6 @@ import { execFileSync } from "node:child_process";
 import { NodeServices } from "@effect/platform-node";
 import {
   ApprovalRequestId,
-  CheckpointRef,
   type OrchestrationEvent,
   type OrchestrationThread,
 } from "@t3tools/contracts";
 @@ -63,11 +62,6 @@ function initializeGitWorkspace(cwd: string) {
   runGit(cwd, ["commit", "-m", "Initial"]);
 }
-export function checkpointRefForTurn(threadId: string, turnCount: number): CheckpointRef {
-  const encodedThreadId = Buffer.from(threadId, "utf8").toString("base64url");
-  return CheckpointRef.makeUnsafe(`refs/t3/checkpoints/${encodedThreadId}/turn/${turnCount}`);
-}
 export function gitRefExists(cwd: string, ref: string): boolean {
   try {
     runGit(cwd, ["show-ref", "--verify", "--quiet", ref]);

apps/server/integration/orchestrationEngine.integration.test.ts+32-20

 @@ -17,17 +17,15 @@ import { Effect, Option } from "effect";
 import type { TestTurnResponse } from "./TestProviderAdapter.integration.ts";
 import {
-  checkpointRefForTurn,
   gitRefExists,
   gitShowFileAtRef,
   makeOrchestrationIntegrationHarness,
   type OrchestrationIntegrationHarness,
 } from "./OrchestrationEngineHarness.integration.ts";
+import { checkpointRefForThreadTurn } from "../src/checkpointing/Refs.ts";
-const asCommandId = (value: string): CommandId => CommandId.makeUnsafe(value);
 const asMessageId = (value: string): MessageId => MessageId.makeUnsafe(value);
 const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
-const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
 const asEventId = (value: string): EventId => EventId.makeUnsafe(value);
 const asProviderSessionId = (value: string): ProviderSessionId =>
   ProviderSessionId.makeUnsafe(value);
 @@ -37,7 +35,7 @@ const asApprovalRequestId = (value: string): ApprovalRequestId =>
   ApprovalRequestId.makeUnsafe(value);
 const PROJECT_ID = asProjectId("project-1");
-const THREAD_ID = asThreadId("thread-1");
+const THREAD_ID = ThreadId.makeUnsafe("thread-1");
 const FIXTURE_SESSION_ID = asProviderSessionId("fixture-session");
 const FIXTURE_THREAD_ID = asProviderThreadId("fixture-thread");
 const FIXTURE_TURN_ID = asProviderTurnId("fixture-turn");
 @@ -95,7 +93,7 @@ const seedProjectAndThread = (harness: OrchestrationIntegrationHarness) =>
     yield* harness.engine.dispatch({
       type: "project.create",
-      commandId: asCommandId("cmd-project-create"),
+      commandId: CommandId.makeUnsafe("cmd-project-create"),
       projectId: PROJECT_ID,
       title: "Integration Project",
       workspaceRoot: harness.workspaceDir,
 @@ -105,7 +103,7 @@ const seedProjectAndThread = (harness: OrchestrationIntegrationHarness) =>
     yield* harness.engine.dispatch({
       type: "thread.create",
-      commandId: asCommandId("cmd-thread-create"),
+      commandId: CommandId.makeUnsafe("cmd-thread-create"),
       threadId: THREAD_ID,
       projectId: PROJECT_ID,
       title: "Integration Thread",
 @@ -124,7 +122,7 @@ const startTurn = (input: {
 }) =>
   input.harness.engine.dispatch({
     type: "thread.turn.start",
-    commandId: asCommandId(input.commandId),
+    commandId: CommandId.makeUnsafe(input.commandId),
     threadId: THREAD_ID,
     message: {
       messageId: asMessageId(input.messageId),
 @@ -195,8 +193,8 @@ it.live("runs a single turn end-to-end and persists checkpoint state in sqlite +
       yield* harness.waitForDomainEvent((event) => event.type === "thread.turn-diff-completed");
-      const ref0 = checkpointRefForTurn(THREAD_ID, 0);
+      const ref0 = checkpointRefForThreadTurn(THREAD_ID, 0);
-      const ref1 = checkpointRefForTurn(THREAD_ID, 1);
+      const ref1 = checkpointRefForThreadTurn(THREAD_ID, 1);
       assert.equal(gitRefExists(harness.workspaceDir, ref0), true);
       assert.equal(gitRefExists(harness.workspaceDir, ref1), true);
       assert.equal(gitShowFileAtRef(harness.workspaceDir, ref0, "README.md"), "v1\n");
 @@ -335,26 +333,34 @@ it.live("runs multi-turn file edits and persists checkpoint diffs", () =>
       const incrementalDiff = yield* harness.checkpointStore.diffCheckpoints({
         cwd: harness.workspaceDir,
-        fromCheckpointRef: checkpointRefForTurn(THREAD_ID, 1),
+        fromCheckpointRef: checkpointRefForThreadTurn(THREAD_ID, 1),
-        toCheckpointRef: checkpointRefForTurn(THREAD_ID, 2),
+        toCheckpointRef: checkpointRefForThreadTurn(THREAD_ID, 2),
         fallbackFromToHead: false,
       });
       assert.equal(incrementalDiff.includes("README.md"), true);
       const fullDiff = yield* harness.checkpointStore.diffCheckpoints({
         cwd: harness.workspaceDir,
-        fromCheckpointRef: checkpointRefForTurn(THREAD_ID, 0),
+        fromCheckpointRef: checkpointRefForThreadTurn(THREAD_ID, 0),
-        toCheckpointRef: checkpointRefForTurn(THREAD_ID, 2),
+        toCheckpointRef: checkpointRefForThreadTurn(THREAD_ID, 2),
         fallbackFromToHead: false,
       });
       assert.equal(fullDiff.includes("README.md"), true);
       assert.equal(
-        gitShowFileAtRef(harness.workspaceDir, checkpointRefForTurn(THREAD_ID, 1), "README.md"),
+        gitShowFileAtRef(
+          harness.workspaceDir,
+          checkpointRefForThreadTurn(THREAD_ID, 1),
+          "README.md",
+        ),
         "v2\n",
       );
       assert.equal(
-        gitShowFileAtRef(harness.workspaceDir, checkpointRefForTurn(THREAD_ID, 2), "README.md"),
+        gitShowFileAtRef(
+          harness.workspaceDir,
+          checkpointRefForThreadTurn(THREAD_ID, 2),
+          "README.md",
+        ),
         "v3\n",
       );
     }),
 @@ -416,7 +422,7 @@ it.live("tracks approval requests and resolves pending approvals on user respons
       yield* harness.engine.dispatch({
         type: "thread.approval.respond",
-        commandId: asCommandId("cmd-approval-respond"),
+        commandId: CommandId.makeUnsafe("cmd-approval-respond"),
         threadId: THREAD_ID,
         requestId: APPROVAL_REQUEST_ID,
         decision: "accept",
 @@ -507,7 +513,10 @@ it.live("records failed turn runtime state and checkpoint status as error", () =
       if (Option.isSome(checkpointRow)) {
         assert.equal(checkpointRow.value.status, "error");
       }
-      assert.equal(gitRefExists(harness.workspaceDir, checkpointRefForTurn(THREAD_ID, 1)), true);
+      assert.equal(
+        gitRefExists(harness.workspaceDir, checkpointRefForThreadTurn(THREAD_ID, 1)),
+        true,
+      );
     }),
   ),
 );
 @@ -644,7 +653,7 @@ it.live("reverts to an earlier checkpoint and trims checkpoint projections + git
       yield* harness.engine.dispatch({
         type: "thread.checkpoint.revert",
-        commandId: asCommandId("cmd-checkpoint-revert"),
+        commandId: CommandId.makeUnsafe("cmd-checkpoint-revert"),
         threadId: THREAD_ID,
         turnCount: 1,
         createdAt: nowIso(),
 @@ -681,7 +690,10 @@ it.live("reverts to an earlier checkpoint and trims checkpoint projections + git
         true,
       );
       assert.equal(fs.readFileSync(path.join(harness.workspaceDir, "README.md"), "utf8"), "v2\n");
-      assert.equal(gitRefExists(harness.workspaceDir, checkpointRefForTurn(THREAD_ID, 2)), false);
+      assert.equal(
+        gitRefExists(harness.workspaceDir, checkpointRefForThreadTurn(THREAD_ID, 2)),
+        false,
+      );
       assert.deepEqual(harness.adapterHarness.getRollbackCalls(sessionId), [1]);
       const checkpointRows = yield* harness.checkpointRepository.listByThreadId({
 @@ -701,7 +713,7 @@ it.live(
         yield* harness.engine.dispatch({
           type: "thread.checkpoint.revert",
-          commandId: asCommandId("cmd-checkpoint-revert-no-session"),
+          commandId: CommandId.makeUnsafe("cmd-checkpoint-revert-no-session"),
           threadId: THREAD_ID,
           turnCount: 0,
           createdAt: nowIso(),

apps/server/src/checkpointing/Layers/CheckpointDiffQuery.test.ts created+190

...	@@ -0,0 +1,190 @@
1	import {
2	CheckpointRef,
3	ProjectId,
4	ThreadId,
5	TurnId,
6	type OrchestrationReadModel,
7	} from "@t3tools/contracts";
8	import { Effect, Layer } from "effect";
9	import { describe, expect, it } from "vitest";
10
11	import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
12	import { checkpointRefForThreadTurn } from "../Refs.ts";
13	import { CheckpointDiffQueryLive } from "./CheckpointDiffQuery.ts";
14	import { CheckpointStore, type CheckpointStoreShape } from "../Services/CheckpointStore.ts";
15	import { CheckpointDiffQuery } from "../Services/CheckpointDiffQuery.ts";
16
17	const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
18	const asTurnId = (value: string): TurnId => TurnId.makeUnsafe(value);
19	const asCheckpointRef = (value: string): CheckpointRef => CheckpointRef.makeUnsafe(value);
20
21	function makeSnapshot(input: {
22	readonly projectId: ProjectId;
23	readonly threadId: ThreadId;
24	readonly workspaceRoot: string;
25	readonly worktreePath: string \| null;
26	readonly checkpointTurnCount: number;
27	readonly checkpointRef: CheckpointRef;
28	}): OrchestrationReadModel {
29	return {
30	snapshotSequence: 0,
31	updatedAt: "2026-01-01T00:00:00.000Z",
32	projects: [
33	{
34	id: input.projectId,
35	title: "Project",
36	workspaceRoot: input.workspaceRoot,
37	defaultModel: null,
38	scripts: [],
39	createdAt: "2026-01-01T00:00:00.000Z",
40	updatedAt: "2026-01-01T00:00:00.000Z",
41	deletedAt: null,
42	},
43	],
44	threads: [
45	{
46	id: input.threadId,
47	projectId: input.projectId,
48	title: "Thread",
49	model: "gpt-5-codex",
50	branch: null,
51	worktreePath: input.worktreePath,
52	latestTurnId: asTurnId("turn-1"),
53	createdAt: "2026-01-01T00:00:00.000Z",
54	updatedAt: "2026-01-01T00:00:00.000Z",
55	deletedAt: null,
56	messages: [],
57	activities: [],
58	checkpoints: [
59	{
60	turnId: asTurnId("turn-1"),
61	checkpointTurnCount: input.checkpointTurnCount,
62	checkpointRef: input.checkpointRef,
63	status: "ready",
64	files: [],
65	assistantMessageId: null,
66	completedAt: "2026-01-01T00:00:00.000Z",
67	},
68	],
69	session: null,
70	},
71	],
72	};
73	}
74
75	describe("CheckpointDiffQueryLive", () => {
76	it("computes diffs using canonical turn-0 checkpoint refs", async () => {
77	const projectId = asProjectId("project-1");
78	const threadId = ThreadId.makeUnsafe("thread-1");
79	const toCheckpointRef = asCheckpointRef("refs/t3/checkpoints/thread-1/turn/1");
80	const hasCheckpointRefCalls: Array<CheckpointRef> = [];
81	const diffCheckpointsCalls: Array<{
82	readonly fromCheckpointRef: CheckpointRef;
83	readonly toCheckpointRef: CheckpointRef;
84	readonly cwd: string;
85	}> = [];
86
87	const snapshot = makeSnapshot({
88	projectId,
89	threadId,
90	workspaceRoot: "/tmp/workspace",
91	worktreePath: null,
92	checkpointTurnCount: 1,
93	checkpointRef: toCheckpointRef,
94	});
95
96	const checkpointStore: CheckpointStoreShape = {
97	isGitRepository: () => Effect.succeed(true),
98	captureCheckpoint: () => Effect.void,
99	hasCheckpointRef: ({ checkpointRef }) =>
100	Effect.sync(() => {
101	hasCheckpointRefCalls.push(checkpointRef);
102	return true;
103	}),
104	restoreCheckpoint: () => Effect.succeed(true),
105	diffCheckpoints: ({ fromCheckpointRef, toCheckpointRef, cwd }) =>
106	Effect.sync(() => {
107	diffCheckpointsCalls.push({ fromCheckpointRef, toCheckpointRef, cwd });
108	return "diff patch";
109	}),
110	deleteCheckpointRefs: () => Effect.void,
111	};
112
113	const layer = CheckpointDiffQueryLive.pipe(
114	Layer.provideMerge(Layer.succeed(CheckpointStore, checkpointStore)),
115	Layer.provideMerge(
116	Layer.succeed(ProjectionSnapshotQuery, {
117	getSnapshot: () => Effect.succeed(snapshot),
118	}),
119	),
120	);
121
122	const result = await Effect.runPromise(
123	Effect.gen(function* () {
124	const query = yield* CheckpointDiffQuery;
125	return yield* query.getTurnDiff({
126	threadId,
127	fromTurnCount: 0,
128	toTurnCount: 1,
129	});
130	}).pipe(Effect.provide(layer)),
131	);
132
133	const expectedFromRef = checkpointRefForThreadTurn(threadId, 0);
134	expect(hasCheckpointRefCalls).toEqual([expectedFromRef, toCheckpointRef]);
135	expect(diffCheckpointsCalls).toEqual([
136	{
137	cwd: "/tmp/workspace",
138	fromCheckpointRef: expectedFromRef,
139	toCheckpointRef,
140	},
141	]);
142	expect(result).toEqual({
143	threadId,
144	fromTurnCount: 0,
145	toTurnCount: 1,
146	diff: "diff patch",
147	});
148	});
149
150	it("fails when the thread is missing from the snapshot", async () => {
151	const threadId = ThreadId.makeUnsafe("thread-missing");
152
153	const checkpointStore: CheckpointStoreShape = {
154	isGitRepository: () => Effect.succeed(true),
155	captureCheckpoint: () => Effect.void,
156	hasCheckpointRef: () => Effect.succeed(true),
157	restoreCheckpoint: () => Effect.succeed(true),
158	diffCheckpoints: () => Effect.succeed(""),
159	deleteCheckpointRefs: () => Effect.void,
160	};
161
162	const layer = CheckpointDiffQueryLive.pipe(
163	Layer.provideMerge(Layer.succeed(CheckpointStore, checkpointStore)),
164	Layer.provideMerge(
165	Layer.succeed(ProjectionSnapshotQuery, {
166	getSnapshot: () =>
167	Effect.succeed({
168	snapshotSequence: 0,
169	projects: [],
170	threads: [],
171	updatedAt: "2026-01-01T00:00:00.000Z",
172	} satisfies OrchestrationReadModel),
173	}),
174	),
175	);
176
177	await expect(
178	Effect.runPromise(
179	Effect.gen(function* () {
180	const query = yield* CheckpointDiffQuery;
181	return yield* query.getTurnDiff({
182	threadId,
183	fromTurnCount: 0,
184	toTurnCount: 1,
185	});
186	}).pipe(Effect.provide(layer)),
187	),
188	).rejects.toThrow("Thread 'thread-missing' not found.");
189	});
190	});

apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts created+193

...	@@ -0,0 +1,193 @@
1	import {
2	OrchestrationGetTurnDiffResult,
3	type ProjectId,
4	type OrchestrationGetFullThreadDiffInput,
5	type OrchestrationGetFullThreadDiffResult,
6	type OrchestrationGetTurnDiffResult as OrchestrationGetTurnDiffResultType,
7	} from "@t3tools/contracts";
8	import { Effect, Layer, Schema } from "effect";
9
10	import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
11	import { CheckpointInvariantError, CheckpointUnavailableError } from "../Errors.ts";
12	import { checkpointRefForThreadTurn } from "../Refs.ts";
13	import { CheckpointStore } from "../Services/CheckpointStore.ts";
14	import { CheckpointDiffQuery, type CheckpointDiffQueryShape } from "../Services/CheckpointDiffQuery.ts";
15
16	function trimToNonEmpty(value: string \| null \| undefined): string \| undefined {
17	const normalized = value?.trim();
18	return normalized && normalized.length > 0 ? normalized : undefined;
19	}
20
21	function resolveThreadWorkspaceCwd(input: {
22	readonly thread: {
23	readonly projectId: ProjectId;
24	readonly worktreePath: string \| null;
25	};
26	readonly projects: ReadonlyArray<{
27	readonly id: ProjectId;
28	readonly workspaceRoot: string;
29	}>;
30	}): string \| undefined {
31	const worktreeCwd = trimToNonEmpty(input.thread.worktreePath);
32	if (worktreeCwd) {
33	return worktreeCwd;
34	}
35
36	const workspaceRoot = input.projects.find(
37	(project) => project.id === input.thread.projectId,
38	)?.workspaceRoot;
39	return trimToNonEmpty(workspaceRoot);
40	}
41
42	const isTurnDiffResult = Schema.is(OrchestrationGetTurnDiffResult);
43
44	const make = Effect.gen(function* () {
45	const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
46	const checkpointStore = yield* CheckpointStore;
47
48	const getTurnDiff: CheckpointDiffQueryShape["getTurnDiff"] = (input) =>
49	Effect.gen(function* () {
50	const operation = "CheckpointDiffQuery.getTurnDiff";
51
52	if (input.fromTurnCount === input.toTurnCount) {
53	const emptyDiff: OrchestrationGetTurnDiffResultType = {
54	threadId: input.threadId,
55	fromTurnCount: input.fromTurnCount,
56	toTurnCount: input.toTurnCount,
57	diff: "",
58	};
59	if (!isTurnDiffResult(emptyDiff)) {
60	return yield* new CheckpointInvariantError({
61	operation,
62	detail: "Computed turn diff result does not satisfy contract schema.",
63	});
64	}
65	return emptyDiff;
66	}
67
68	const snapshot = yield* projectionSnapshotQuery.getSnapshot();
69	const thread = snapshot.threads.find((entry) => entry.id === input.threadId);
70	if (!thread) {
71	return yield* new CheckpointInvariantError({
72	operation,
73	detail: `Thread '${input.threadId}' not found.`,
74	});
75	}
76
77	const maxTurnCount = thread.checkpoints.reduce(
78	(max, checkpoint) => Math.max(max, checkpoint.checkpointTurnCount),
79	0,
80	);
81	if (input.toTurnCount > maxTurnCount) {
82	return yield* new CheckpointUnavailableError({
83	threadId: input.threadId,
84	turnCount: input.toTurnCount,
85	detail: `Turn diff range exceeds current turn count: requested ${input.toTurnCount}, current ${maxTurnCount}.`,
86	});
87	}
88
89	const workspaceCwd = resolveThreadWorkspaceCwd({
90	thread,
91	projects: snapshot.projects,
92	});
93	if (!workspaceCwd) {
94	return yield* new CheckpointInvariantError({
95	operation,
96	detail: `Workspace path missing for thread '${input.threadId}' when computing turn diff.`,
97	});
98	}
99
100	const fromCheckpointRef =
101	input.fromTurnCount === 0
102	? checkpointRefForThreadTurn(input.threadId, 0)
103	: thread.checkpoints.find(
104	(checkpoint) => checkpoint.checkpointTurnCount === input.fromTurnCount,
105	)?.checkpointRef;
106	if (!fromCheckpointRef) {
107	return yield* new CheckpointUnavailableError({
108	threadId: input.threadId,
109	turnCount: input.fromTurnCount,
110	detail: `Checkpoint ref is unavailable for turn ${input.fromTurnCount}.`,
111	});
112	}
113
114	const toCheckpointRef = thread.checkpoints.find(
115	(checkpoint) => checkpoint.checkpointTurnCount === input.toTurnCount,
116	)?.checkpointRef;
117	if (!toCheckpointRef) {
118	return yield* new CheckpointUnavailableError({
119	threadId: input.threadId,
120	turnCount: input.toTurnCount,
121	detail: `Checkpoint ref is unavailable for turn ${input.toTurnCount}.`,
122	});
123	}
124
125	const [fromExists, toExists] = yield* Effect.all(
126	[
127	checkpointStore.hasCheckpointRef({
128	cwd: workspaceCwd,
129	checkpointRef: fromCheckpointRef,
130	}),
131	checkpointStore.hasCheckpointRef({
132	cwd: workspaceCwd,
133	checkpointRef: toCheckpointRef,
134	}),
135	],
136	{ concurrency: "unbounded" },
137	);
138
139	if (!fromExists) {
140	return yield* new CheckpointUnavailableError({
141	threadId: input.threadId,
142	turnCount: input.fromTurnCount,
143	detail: `Filesystem checkpoint is unavailable for turn ${input.fromTurnCount}.`,
144	});
145	}
146
147	if (!toExists) {
148	return yield* new CheckpointUnavailableError({
149	threadId: input.threadId,
150	turnCount: input.toTurnCount,
151	detail: `Filesystem checkpoint is unavailable for turn ${input.toTurnCount}.`,
152	});
153	}
154
155	const diff = yield* checkpointStore.diffCheckpoints({
156	cwd: workspaceCwd,
157	fromCheckpointRef,
158	toCheckpointRef,
159	fallbackFromToHead: false,
160	});
161
162	const turnDiff: OrchestrationGetTurnDiffResultType = {
163	threadId: input.threadId,
164	fromTurnCount: input.fromTurnCount,
165	toTurnCount: input.toTurnCount,
166	diff,
167	};
168	if (!isTurnDiffResult(turnDiff)) {
169	return yield* new CheckpointInvariantError({
170	operation,
171	detail: "Computed turn diff result does not satisfy contract schema.",
172	});
173	}
174
175	return turnDiff;
176	});
177
178	const getFullThreadDiff: CheckpointDiffQueryShape["getFullThreadDiff"] = (
179	input: OrchestrationGetFullThreadDiffInput,
180	) =>
181	getTurnDiff({
182	threadId: input.threadId,
183	fromTurnCount: 0,
184	toTurnCount: input.toTurnCount,
185	}).pipe(Effect.map((result): OrchestrationGetFullThreadDiffResult => result));
186
187	return {
188	getTurnDiff,
189	getFullThreadDiff,
190	} satisfies CheckpointDiffQueryShape;
191	});
192
193	export const CheckpointDiffQueryLive = Layer.effect(CheckpointDiffQuery, make);

apps/server/src/checkpointing/Refs.ts created+10

...	@@ -0,0 +1,10 @@
1	import { Encoding } from "effect";
2	import { CheckpointRef, type ThreadId } from "@t3tools/contracts";
3
4	export const CHECKPOINT_REFS_PREFIX = "refs/t3/checkpoints";
5
6	export function checkpointRefForThreadTurn(threadId: ThreadId, turnCount: number): CheckpointRef {
7	return CheckpointRef.makeUnsafe(
8	`${CHECKPOINT_REFS_PREFIX}/${Encoding.encodeBase64Url(threadId)}/turn/${turnCount}`,
9	);
10	}

apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts created+24

...	@@ -0,0 +1,24 @@
1	import type {
2	OrchestrationGetFullThreadDiffInput,
3	OrchestrationGetFullThreadDiffResult,
4	OrchestrationGetTurnDiffInput,
5	OrchestrationGetTurnDiffResult,
6	} from "@t3tools/contracts";
7	import { ServiceMap } from "effect";
8	import type { Effect } from "effect";
9
10	import type { CheckpointServiceError } from "../Errors.ts";
11
12	export interface CheckpointDiffQueryShape {
13	readonly getTurnDiff: (
14	input: OrchestrationGetTurnDiffInput,
15	) => Effect.Effect<OrchestrationGetTurnDiffResult, CheckpointServiceError>;
16	readonly getFullThreadDiff: (
17	input: OrchestrationGetFullThreadDiffInput,
18	) => Effect.Effect<OrchestrationGetFullThreadDiffResult, CheckpointServiceError>;
19	}
20
21	export class CheckpointDiffQuery extends ServiceMap.Service<
22	CheckpointDiffQuery,
23	CheckpointDiffQueryShape
24	>()("checkpointing/CheckpointDiffQuery") {}

apps/server/src/git.ts+4-4

apps/server/src/keybindings.test.ts+1-1

...	@@ -40,7 +40,7 @@ const writeKeybindingsConfig = (configPath: string, rules: readonly KeybindingRu	...	@@ -40,7 +40,7 @@ const writeKeybindingsConfig = (configPath: string, rules: readonly KeybindingRu
40	Effect.gen(function* () {	40	Effect.gen(function* () {
41	const fileSystem = yield* FileSystem.FileSystem;	41	const fileSystem = yield* FileSystem.FileSystem;
42	const encoded = yield* Schema.encodeEffect(KeybindingsConfigJson)(	42	const encoded = yield* Schema.encodeEffect(KeybindingsConfigJson)(
43	rules.map((rule) => KeybindingRule.makeUnsafe(rule)),	43	rules,
44	);	44	);
45	yield* fileSystem.writeFileString(configPath, encoded);	45	yield* fileSystem.writeFileString(configPath, encoded);
46	});	46	});

apps/server/src/keybindings.ts+2-2

...	@@ -313,7 +313,7 @@ export const ResolvedKeybindingFromConfig = KeybindingRule.pipe(	...	@@ -313,7 +313,7 @@ export const ResolvedKeybindingFromConfig = KeybindingRule.pipe(
313	title: "Invalid keybinding rule",	313	title: "Invalid keybinding rule",
314	}),	314	}),
315	),	315	),
316	Effect.map((resolved) => ResolvedKeybindingRule.makeUnsafe(resolved)),	316	Effect.map((resolved) => resolved),
317	),	317	),
318		318
319	encode: (resolved) =>	319	encode: (resolved) =>
...	@@ -456,7 +456,7 @@ const makeKeybindings = Effect.gen(function* () {	...	@@ -456,7 +456,7 @@ const makeKeybindings = Effect.gen(function* () {
456	const tempPath = `${keybindingsConfigPath}.${process.pid}.${Date.now()}.tmp`;	456	const tempPath = `${keybindingsConfigPath}.${process.pid}.${Date.now()}.tmp`;
457		457
458	return Schema.encodeEffect(KeybindingsConfigJson)(	458	return Schema.encodeEffect(KeybindingsConfigJson)(
459	rules.map((rule) => KeybindingRule.makeUnsafe(rule)),	459	rules,
460	).pipe(	460	).pipe(
461	Effect.tap(() => fs.makeDirectory(path.dirname(keybindingsConfigPath), { recursive: true })),	461	Effect.tap(() => fs.makeDirectory(path.dirname(keybindingsConfigPath), { recursive: true })),
462	Effect.tap((encoded) => fs.writeFileString(tempPath, encoded)),	462	Effect.tap((encoded) => fs.writeFileString(tempPath, encoded)),

apps/server/src/orchestration/Layer.test.ts+33-35

...	@@ -22,9 +22,7 @@ import { OrchestrationEngineLive } from "./Layers/OrchestrationEngine.ts";	...	@@ -22,9 +22,7 @@ import { OrchestrationEngineLive } from "./Layers/OrchestrationEngine.ts";
22	import { OrchestrationProjectionPipelineLive } from "./Layers/ProjectionPipeline.ts";	22	import { OrchestrationProjectionPipelineLive } from "./Layers/ProjectionPipeline.ts";
23	import { OrchestrationEngineService } from "./Services/OrchestrationEngine.ts";	23	import { OrchestrationEngineService } from "./Services/OrchestrationEngine.ts";
24		24
25	const asCommandId = (value: string): CommandId => CommandId.makeUnsafe(value);
26	const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);	25	const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
27	const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
28	const asMessageId = (value: string): MessageId => MessageId.makeUnsafe(value);	26	const asMessageId = (value: string): MessageId => MessageId.makeUnsafe(value);
29	const asTurnId = (value: string): TurnId => TurnId.makeUnsafe(value);	27	const asTurnId = (value: string): TurnId => TurnId.makeUnsafe(value);
30	const asCheckpointRef = (value: string): CheckpointRef => CheckpointRef.makeUnsafe(value);	28	const asCheckpointRef = (value: string): CheckpointRef => CheckpointRef.makeUnsafe(value);
...	@@ -58,7 +56,7 @@ describe("OrchestrationEngine", () => {	...	@@ -58,7 +56,7 @@ describe("OrchestrationEngine", () => {
58	await system.run(	56	await system.run(
59	engine.dispatch({	57	engine.dispatch({
60	type: "project.create",	58	type: "project.create",
61	commandId: asCommandId("cmd-project-1-create"),	59	commandId: CommandId.makeUnsafe("cmd-project-1-create"),
62	projectId: asProjectId("project-1"),	60	projectId: asProjectId("project-1"),
63	title: "Project 1",	61	title: "Project 1",
64	workspaceRoot: "/tmp/project-1",	62	workspaceRoot: "/tmp/project-1",
...	@@ -69,8 +67,8 @@ describe("OrchestrationEngine", () => {	...	@@ -69,8 +67,8 @@ describe("OrchestrationEngine", () => {
69	await system.run(	67	await system.run(
70	engine.dispatch({	68	engine.dispatch({
71	type: "thread.create",	69	type: "thread.create",
72	commandId: asCommandId("cmd-thread-1-create"),	70	commandId: CommandId.makeUnsafe("cmd-thread-1-create"),
73	threadId: asThreadId("thread-1"),	71	threadId: ThreadId.makeUnsafe("thread-1"),
74	projectId: asProjectId("project-1"),	72	projectId: asProjectId("project-1"),
75	title: "Thread",	73	title: "Thread",
76	model: "gpt-5-codex",	74	model: "gpt-5-codex",
...	@@ -82,8 +80,8 @@ describe("OrchestrationEngine", () => {	...	@@ -82,8 +80,8 @@ describe("OrchestrationEngine", () => {
82	await system.run(	80	await system.run(
83	engine.dispatch({	81	engine.dispatch({
84	type: "thread.turn.start",	82	type: "thread.turn.start",
85	commandId: asCommandId("cmd-turn-start-1"),	83	commandId: CommandId.makeUnsafe("cmd-turn-start-1"),
86	threadId: asThreadId("thread-1"),	84	threadId: ThreadId.makeUnsafe("thread-1"),
87	message: {	85	message: {
88	messageId: asMessageId("msg-1"),	86	messageId: asMessageId("msg-1"),
89	role: "user",	87	role: "user",
...	@@ -108,7 +106,7 @@ describe("OrchestrationEngine", () => {	...	@@ -108,7 +106,7 @@ describe("OrchestrationEngine", () => {
108	await system.run(	106	await system.run(
109	engine.dispatch({	107	engine.dispatch({
110	type: "project.create",	108	type: "project.create",
111	commandId: asCommandId("cmd-project-replay-create"),	109	commandId: CommandId.makeUnsafe("cmd-project-replay-create"),
112	projectId: asProjectId("project-replay"),	110	projectId: asProjectId("project-replay"),
113	title: "Replay Project",	111	title: "Replay Project",
114	workspaceRoot: "/tmp/project-replay",	112	workspaceRoot: "/tmp/project-replay",
...	@@ -119,8 +117,8 @@ describe("OrchestrationEngine", () => {	...	@@ -119,8 +117,8 @@ describe("OrchestrationEngine", () => {
119	await system.run(	117	await system.run(
120	engine.dispatch({	118	engine.dispatch({
121	type: "thread.create",	119	type: "thread.create",
122	commandId: asCommandId("cmd-thread-replay-create"),	120	commandId: CommandId.makeUnsafe("cmd-thread-replay-create"),
123	threadId: asThreadId("thread-replay"),	121	threadId: ThreadId.makeUnsafe("thread-replay"),
124	projectId: asProjectId("project-replay"),	122	projectId: asProjectId("project-replay"),
125	title: "replay",	123	title: "replay",
126	model: "gpt-5-codex",	124	model: "gpt-5-codex",
...	@@ -132,8 +130,8 @@ describe("OrchestrationEngine", () => {	...	@@ -132,8 +130,8 @@ describe("OrchestrationEngine", () => {
132	await system.run(	130	await system.run(
133	engine.dispatch({	131	engine.dispatch({
134	type: "thread.delete",	132	type: "thread.delete",
135	commandId: asCommandId("cmd-thread-replay-delete"),	133	commandId: CommandId.makeUnsafe("cmd-thread-replay-delete"),
136	threadId: asThreadId("thread-replay"),	134	threadId: ThreadId.makeUnsafe("thread-replay"),
137	}),	135	}),
138	);	136	);
139		137
...	@@ -158,7 +156,7 @@ describe("OrchestrationEngine", () => {	...	@@ -158,7 +156,7 @@ describe("OrchestrationEngine", () => {
158	await system.run(	156	await system.run(
159	engine.dispatch({	157	engine.dispatch({
160	type: "project.create",	158	type: "project.create",
161	commandId: asCommandId("cmd-project-stream-create"),	159	commandId: CommandId.makeUnsafe("cmd-project-stream-create"),
162	projectId: asProjectId("project-stream"),	160	projectId: asProjectId("project-stream"),
163	title: "Stream Project",	161	title: "Stream Project",
164	workspaceRoot: "/tmp/project-stream",	162	workspaceRoot: "/tmp/project-stream",
...	@@ -179,8 +177,8 @@ describe("OrchestrationEngine", () => {	...	@@ -179,8 +177,8 @@ describe("OrchestrationEngine", () => {
179	yield* Effect.sleep("10 millis");	177	yield* Effect.sleep("10 millis");
180	yield* engine.dispatch({	178	yield* engine.dispatch({
181	type: "thread.create",	179	type: "thread.create",
182	commandId: asCommandId("cmd-stream-thread-create"),	180	commandId: CommandId.makeUnsafe("cmd-stream-thread-create"),
183	threadId: asThreadId("thread-stream"),	181	threadId: ThreadId.makeUnsafe("thread-stream"),
184	projectId: asProjectId("project-stream"),	182	projectId: asProjectId("project-stream"),
185	title: "domain-stream",	183	title: "domain-stream",
186	model: "gpt-5-codex",	184	model: "gpt-5-codex",
...	@@ -190,8 +188,8 @@ describe("OrchestrationEngine", () => {	...	@@ -190,8 +188,8 @@ describe("OrchestrationEngine", () => {
190	});	188	});
191	yield* engine.dispatch({	189	yield* engine.dispatch({
192	type: "thread.meta.update",	190	type: "thread.meta.update",
193	commandId: asCommandId("cmd-stream-thread-update"),	191	commandId: CommandId.makeUnsafe("cmd-stream-thread-update"),
194	threadId: asThreadId("thread-stream"),	192	threadId: ThreadId.makeUnsafe("thread-stream"),
195	title: "domain-stream-updated",	193	title: "domain-stream-updated",
196	});	194	});
197	eventTypes.push((yield* Queue.take(eventQueue)).type);	195	eventTypes.push((yield* Queue.take(eventQueue)).type);
...	@@ -211,7 +209,7 @@ describe("OrchestrationEngine", () => {	...	@@ -211,7 +209,7 @@ describe("OrchestrationEngine", () => {
211	await system.run(	209	await system.run(
212	engine.dispatch({	210	engine.dispatch({
213	type: "project.create",	211	type: "project.create",
214	commandId: asCommandId("cmd-project-turn-diff-create"),	212	commandId: CommandId.makeUnsafe("cmd-project-turn-diff-create"),
215	projectId: asProjectId("project-turn-diff"),	213	projectId: asProjectId("project-turn-diff"),
216	title: "Turn Diff Project",	214	title: "Turn Diff Project",
217	workspaceRoot: "/tmp/project-turn-diff",	215	workspaceRoot: "/tmp/project-turn-diff",
...	@@ -222,8 +220,8 @@ describe("OrchestrationEngine", () => {	...	@@ -222,8 +220,8 @@ describe("OrchestrationEngine", () => {
222	await system.run(	220	await system.run(
223	engine.dispatch({	221	engine.dispatch({
224	type: "thread.create",	222	type: "thread.create",
225	commandId: asCommandId("cmd-thread-turn-diff-create"),	223	commandId: CommandId.makeUnsafe("cmd-thread-turn-diff-create"),
226	threadId: asThreadId("thread-turn-diff"),	224	threadId: ThreadId.makeUnsafe("thread-turn-diff"),
227	projectId: asProjectId("project-turn-diff"),	225	projectId: asProjectId("project-turn-diff"),
228	title: "Turn diff thread",	226	title: "Turn diff thread",
229	model: "gpt-5-codex",	227	model: "gpt-5-codex",
...	@@ -235,8 +233,8 @@ describe("OrchestrationEngine", () => {	...	@@ -235,8 +233,8 @@ describe("OrchestrationEngine", () => {
235	await system.run(	233	await system.run(
236	engine.dispatch({	234	engine.dispatch({
237	type: "thread.turn.diff.complete",	235	type: "thread.turn.diff.complete",
238	commandId: asCommandId("cmd-turn-diff-complete"),	236	commandId: CommandId.makeUnsafe("cmd-turn-diff-complete"),
239	threadId: asThreadId("thread-turn-diff"),	237	threadId: ThreadId.makeUnsafe("thread-turn-diff"),
240	turnId: asTurnId("turn-1"),	238	turnId: asTurnId("turn-1"),
241	completedAt: createdAt,	239	completedAt: createdAt,
242	checkpointRef: asCheckpointRef("refs/t3/checkpoints/thread-turn-diff/turn/1"),	240	checkpointRef: asCheckpointRef("refs/t3/checkpoints/thread-turn-diff/turn/1"),
...	@@ -275,7 +273,7 @@ describe("OrchestrationEngine", () => {	...	@@ -275,7 +273,7 @@ describe("OrchestrationEngine", () => {
275		273
276	const flakyStore: OrchestrationEventStoreShape = {	274	const flakyStore: OrchestrationEventStoreShape = {
277	append(event) {	275	append(event) {
278	if (shouldFailFirstAppend && event.commandId === asCommandId("cmd-flaky-1")) {	276	if (shouldFailFirstAppend && event.commandId === CommandId.makeUnsafe("cmd-flaky-1")) {
279	shouldFailFirstAppend = false;	277	shouldFailFirstAppend = false;
280	return Effect.fail(	278	return Effect.fail(
281	new PersistenceSqlError({	279	new PersistenceSqlError({
...	@@ -314,7 +312,7 @@ describe("OrchestrationEngine", () => {	...	@@ -314,7 +312,7 @@ describe("OrchestrationEngine", () => {
314	await runtime.runPromise(	312	await runtime.runPromise(
315	engine.dispatch({	313	engine.dispatch({
316	type: "project.create",	314	type: "project.create",
317	commandId: asCommandId("cmd-project-flaky-create"),	315	commandId: CommandId.makeUnsafe("cmd-project-flaky-create"),
318	projectId: asProjectId("project-flaky"),	316	projectId: asProjectId("project-flaky"),
319	title: "Flaky Project",	317	title: "Flaky Project",
320	workspaceRoot: "/tmp/project-flaky",	318	workspaceRoot: "/tmp/project-flaky",
...	@@ -327,8 +325,8 @@ describe("OrchestrationEngine", () => {	...	@@ -327,8 +325,8 @@ describe("OrchestrationEngine", () => {
327	runtime.runPromise(	325	runtime.runPromise(
328	engine.dispatch({	326	engine.dispatch({
329	type: "thread.create",	327	type: "thread.create",
330	commandId: asCommandId("cmd-flaky-1"),	328	commandId: CommandId.makeUnsafe("cmd-flaky-1"),
331	threadId: asThreadId("thread-flaky-fail"),	329	threadId: ThreadId.makeUnsafe("thread-flaky-fail"),
332	projectId: asProjectId("project-flaky"),	330	projectId: asProjectId("project-flaky"),
333	title: "flaky-fail",	331	title: "flaky-fail",
334	model: "gpt-5-codex",	332	model: "gpt-5-codex",
...	@@ -342,8 +340,8 @@ describe("OrchestrationEngine", () => {	...	@@ -342,8 +340,8 @@ describe("OrchestrationEngine", () => {
342	const result = await runtime.runPromise(	340	const result = await runtime.runPromise(
343	engine.dispatch({	341	engine.dispatch({
344	type: "thread.create",	342	type: "thread.create",
345	commandId: asCommandId("cmd-flaky-2"),	343	commandId: CommandId.makeUnsafe("cmd-flaky-2"),
346	threadId: asThreadId("thread-flaky-ok"),	344	threadId: ThreadId.makeUnsafe("thread-flaky-ok"),
347	projectId: asProjectId("project-flaky"),	345	projectId: asProjectId("project-flaky"),
348	title: "flaky-ok",	346	title: "flaky-ok",
349	model: "gpt-5-codex",	347	model: "gpt-5-codex",
...	@@ -366,8 +364,8 @@ describe("OrchestrationEngine", () => {	...	@@ -366,8 +364,8 @@ describe("OrchestrationEngine", () => {
366	system.run(	364	system.run(
367	engine.dispatch({	365	engine.dispatch({
368	type: "thread.turn.start",	366	type: "thread.turn.start",
369	commandId: asCommandId("cmd-invariant-missing-thread"),	367	commandId: CommandId.makeUnsafe("cmd-invariant-missing-thread"),
370	threadId: asThreadId("thread-missing"),	368	threadId: ThreadId.makeUnsafe("thread-missing"),
371	message: {	369	message: {
372	messageId: asMessageId("msg-missing"),	370	messageId: asMessageId("msg-missing"),
373	role: "user",	371	role: "user",
...	@@ -390,7 +388,7 @@ describe("OrchestrationEngine", () => {	...	@@ -390,7 +388,7 @@ describe("OrchestrationEngine", () => {
390	await system.run(	388	await system.run(
391	engine.dispatch({	389	engine.dispatch({
392	type: "project.create",	390	type: "project.create",
393	commandId: asCommandId("cmd-project-duplicate-create"),	391	commandId: CommandId.makeUnsafe("cmd-project-duplicate-create"),
394	projectId: asProjectId("project-duplicate"),	392	projectId: asProjectId("project-duplicate"),
395	title: "Duplicate Project",	393	title: "Duplicate Project",
396	workspaceRoot: "/tmp/project-duplicate",	394	workspaceRoot: "/tmp/project-duplicate",
...	@@ -402,8 +400,8 @@ describe("OrchestrationEngine", () => {	...	@@ -402,8 +400,8 @@ describe("OrchestrationEngine", () => {
402	await system.run(	400	await system.run(
403	engine.dispatch({	401	engine.dispatch({
404	type: "thread.create",	402	type: "thread.create",
405	commandId: asCommandId("cmd-thread-duplicate-1"),	403	commandId: CommandId.makeUnsafe("cmd-thread-duplicate-1"),
406	threadId: asThreadId("thread-duplicate"),	404	threadId: ThreadId.makeUnsafe("thread-duplicate"),
407	projectId: asProjectId("project-duplicate"),	405	projectId: asProjectId("project-duplicate"),
408	title: "duplicate",	406	title: "duplicate",
409	model: "gpt-5-codex",	407	model: "gpt-5-codex",
...	@@ -417,8 +415,8 @@ describe("OrchestrationEngine", () => {	...	@@ -417,8 +415,8 @@ describe("OrchestrationEngine", () => {
417	system.run(	415	system.run(
418	engine.dispatch({	416	engine.dispatch({
419	type: "thread.create",	417	type: "thread.create",
420	commandId: asCommandId("cmd-thread-duplicate-2"),	418	commandId: CommandId.makeUnsafe("cmd-thread-duplicate-2"),
421	threadId: asThreadId("thread-duplicate"),	419	threadId: ThreadId.makeUnsafe("thread-duplicate"),
422	projectId: asProjectId("project-duplicate"),	420	projectId: asProjectId("project-duplicate"),
423	title: "duplicate",	421	title: "duplicate",
424	model: "gpt-5-codex",	422	model: "gpt-5-codex",

apps/server/src/orchestration/Layers/CheckpointReactor.test.ts+66-49

 @@ -5,7 +5,6 @@ import { execFileSync } from "node:child_process";
 import type { ProviderRuntimeEvent, ProviderSession } from "@t3tools/contracts";
 import {
-  CheckpointRef,
   CommandId,
   EventId,
   MessageId,
 @@ -36,19 +35,13 @@ import {
   ProviderService,
   type ProviderServiceShape,
 } from "../../provider/Services/ProviderService.ts";
+import { checkpointRefForThreadTurn } from "../../checkpointing/Refs.ts";
-const asCommandId = (value: string): CommandId => CommandId.makeUnsafe(value);
 const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
-const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
 const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);
 const asProviderThreadId = (value: string): ProviderThreadId => ProviderThreadId.makeUnsafe(value);
 const asTurnId = (value: string): TurnId => TurnId.makeUnsafe(value);
-function checkpointRefForTurn(threadId: ThreadId, turnCount: number): CheckpointRef {
-  const encodedThreadId = Buffer.from(threadId, "utf8").toString("base64url");
-  return CheckpointRef.makeUnsafe(`refs/t3/checkpoints/${encodedThreadId}/turn/${turnCount}`);
-}
 function createProviderServiceHarness(cwd: string, hasSession = true) {
   const now = new Date().toISOString();
   const runtimeEventPubSub = Effect.runSync(PubSub.unbounded<ProviderRuntimeEvent>());
 @@ -109,7 +102,7 @@ async function waitForThread(
     activities: ReadonlyArray<{ kind: string }>;
   }> => {
     const readModel = await Effect.runPromise(engine.getReadModel());
-    const thread = readModel.threads.find((entry) => entry.id === asThreadId("thread-1"));
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.makeUnsafe("thread-1"));
     if (thread && predicate(thread)) {
       return thread;
     }
 @@ -250,7 +243,7 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       engine.dispatch({
         type: "project.create",
-        commandId: asCommandId("cmd-project-create"),
+        commandId: CommandId.makeUnsafe("cmd-project-create"),
         projectId: asProjectId("project-1"),
         title: "Test Project",
         workspaceRoot: options?.projectWorkspaceRoot ?? cwd,
 @@ -261,8 +254,8 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       engine.dispatch({
         type: "thread.create",
-        commandId: asCommandId("cmd-thread-create"),
+        commandId: CommandId.makeUnsafe("cmd-thread-create"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         projectId: asProjectId("project-1"),
         title: "Thread",
         model: "gpt-5-codex",
 @@ -276,21 +269,21 @@ describe("CheckpointReactor", () => {
       await runtime.runPromise(
         checkpointStore.captureCheckpoint({
           cwd,
-          checkpointRef: checkpointRefForTurn(asThreadId("thread-1"), 0),
+          checkpointRef: checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 0),
         }),
       );
       fs.writeFileSync(path.join(cwd, "README.md"), "v2\n", "utf8");
       await runtime.runPromise(
         checkpointStore.captureCheckpoint({
           cwd,
-          checkpointRef: checkpointRefForTurn(asThreadId("thread-1"), 1),
+          checkpointRef: checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 1),
         }),
       );
       fs.writeFileSync(path.join(cwd, "README.md"), "v3\n", "utf8");
       await runtime.runPromise(
         checkpointStore.captureCheckpoint({
           cwd,
-          checkpointRef: checkpointRefForTurn(asThreadId("thread-1"), 2),
+          checkpointRef: checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 2),
         }),
       );
     }
 @@ -309,10 +302,10 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.session.set",
-        commandId: asCommandId("cmd-session-set-capture"),
+        commandId: CommandId.makeUnsafe("cmd-session-set-capture"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         session: {
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           status: "ready",
           providerName: "codex",
           providerSessionId: asSessionId("sess-1"),
 @@ -334,7 +327,7 @@ describe("CheckpointReactor", () => {
       threadId: ProviderThreadId.makeUnsafe("provider-thread-1"),
       turnId: asTurnId("turn-1"),
     });
-    await waitForGitRefExists(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 0));
+    await waitForGitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 0));
     fs.writeFileSync(path.join(harness.cwd, "README.md"), "v2\n", "utf8");
     harness.provider.emit({
 @@ -354,13 +347,25 @@ describe("CheckpointReactor", () => {
       (entry) => entry.latestTurnId === "turn-1" && entry.checkpoints.length === 1,
     );
     expect(thread.checkpoints[0]?.checkpointTurnCount).toBe(1);
-    expect(gitRefExists(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 0))).toBe(true);
+    expect(gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 0))).toBe(
-    expect(gitRefExists(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 1))).toBe(true);
+      true,
+    );
+    expect(gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 1))).toBe(
+      true,
+    );
     expect(
-      gitShowFileAtRef(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 0), "README.md"),
+      gitShowFileAtRef(
+        harness.cwd,
+        checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 0),
+        "README.md",
+      ),
     ).toBe("v1\n");
     expect(
-      gitShowFileAtRef(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 1), "README.md"),
+      gitShowFileAtRef(
+        harness.cwd,
+        checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 1),
+        "README.md",
+      ),
     ).toBe("v2\n");
   });
 @@ -374,8 +379,8 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.start",
-        commandId: asCommandId("cmd-turn-start-for-baseline"),
+        commandId: CommandId.makeUnsafe("cmd-turn-start-for-baseline"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         message: {
           messageId: MessageId.makeUnsafe("message-user-1"),
           role: "user",
 @@ -386,9 +391,13 @@ describe("CheckpointReactor", () => {
       }),
     );
-    await waitForGitRefExists(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 0));
+    await waitForGitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 0));
     expect(
-      gitShowFileAtRef(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 0), "README.md"),
+      gitShowFileAtRef(
+        harness.cwd,
+        checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 0),
+        "README.md",
+      ),
     ).toBe("v1\n");
   });
 @@ -403,10 +412,10 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.session.set",
-        commandId: asCommandId("cmd-session-set-missing-provider-cwd"),
+        commandId: CommandId.makeUnsafe("cmd-session-set-missing-provider-cwd"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         session: {
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           status: "running",
           providerName: "codex",
           providerSessionId: asSessionId("sess-missing"),
 @@ -432,9 +441,15 @@ describe("CheckpointReactor", () => {
     });
     await waitForEvent(harness.engine, (event) => event.type === "thread.turn-diff-completed");
-    expect(gitRefExists(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 1))).toBe(true);
+    expect(gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 1))).toBe(
+      true,
+    );
     expect(
-      gitShowFileAtRef(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 1), "README.md"),
+      gitShowFileAtRef(
+        harness.cwd,
+        checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 1),
+        "README.md",
+      ),
     ).toBe("v2\n");
   });
 @@ -445,10 +460,10 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.session.set",
-        commandId: asCommandId("cmd-session-set-checkpoint-captured"),
+        commandId: CommandId.makeUnsafe("cmd-session-set-checkpoint-captured"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         session: {
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           status: "ready",
           providerName: "codex",
           providerSessionId: asSessionId("sess-1"),
 @@ -488,10 +503,10 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.session.set",
-        commandId: asCommandId("cmd-session-set"),
+        commandId: CommandId.makeUnsafe("cmd-session-set"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         session: {
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           status: "ready",
           providerName: "codex",
           providerSessionId: asSessionId("sess-1"),
 @@ -507,11 +522,11 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.diff.complete",
-        commandId: asCommandId("cmd-diff-1"),
+        commandId: CommandId.makeUnsafe("cmd-diff-1"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         turnId: asTurnId("turn-1"),
         completedAt: createdAt,
-        checkpointRef: checkpointRefForTurn(asThreadId("thread-1"), 1),
+        checkpointRef: checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 1),
         status: "ready",
         files: [],
         checkpointTurnCount: 1,
 @@ -521,11 +536,11 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.diff.complete",
-        commandId: asCommandId("cmd-diff-2"),
+        commandId: CommandId.makeUnsafe("cmd-diff-2"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         turnId: asTurnId("turn-2"),
         completedAt: createdAt,
-        checkpointRef: checkpointRefForTurn(asThreadId("thread-1"), 2),
+        checkpointRef: checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 2),
         status: "ready",
         files: [],
         checkpointTurnCount: 2,
 @@ -536,8 +551,8 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.checkpoint.revert",
-        commandId: asCommandId("cmd-revert-request"),
+        commandId: CommandId.makeUnsafe("cmd-revert-request"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         turnCount: 1,
         createdAt,
       }),
 @@ -555,7 +570,9 @@ describe("CheckpointReactor", () => {
       numTurns: 1,
     });
     expect(fs.readFileSync(path.join(harness.cwd, "README.md"), "utf8")).toBe("v2\n");
-    expect(gitRefExists(harness.cwd, checkpointRefForTurn(asThreadId("thread-1"), 2))).toBe(false);
+    expect(gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.makeUnsafe("thread-1"), 2))).toBe(
+      false,
+    );
   });
   it("appends an error activity when revert is requested without an active session", async () => {
 @@ -565,8 +582,8 @@ describe("CheckpointReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.checkpoint.revert",
-        commandId: asCommandId("cmd-revert-no-session"),
+        commandId: CommandId.makeUnsafe("cmd-revert-no-session"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         turnCount: 1,
         createdAt,
       }),

apps/server/src/orchestration/Layers/CheckpointReactor.ts+4-10

 @@ -1,17 +1,18 @@
 import {
-  CheckpointRef,
   CommandId,
   EventId,
   MessageId,
   ProviderSessionId,
   ThreadId,
   TurnId,
+  type ProjectId,
   type OrchestrationEvent,
   type ProviderRuntimeEvent,
 } from "@t3tools/contracts";
 import { Effect, Layer, Option, Queue, Stream } from "effect";
 import { parseTurnDiffFilesFromUnifiedDiff } from "../../checkpointing/Diffs.ts";
+import { checkpointRefForThreadTurn } from "../../checkpointing/Refs.ts";
 import { CheckpointStore } from "../../checkpointing/Services/CheckpointStore.ts";
 import { ProviderService } from "../../provider/Services/ProviderService.ts";
 import { CheckpointReactor, type CheckpointReactorShape } from "../Services/CheckpointReactor.ts";
 @@ -19,8 +20,6 @@ import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
 import { CheckpointStoreError } from "../../checkpointing/Errors.ts";
 import { OrchestrationDispatchError } from "../Errors.ts";
-const CHECKPOINT_REFS_PREFIX = "refs/t3/checkpoints";
 type ReactorInput =
   | {
       readonly source: "runtime";
 @@ -31,11 +30,6 @@ type ReactorInput =
       readonly event: OrchestrationEvent;
     };
-function checkpointRefForThreadTurn(threadId: ThreadId, turnCount: number): CheckpointRef {
-  const encodedThreadId = Buffer.from(threadId, "utf8").toString("base64url");
-  return CheckpointRef.makeUnsafe(`${CHECKPOINT_REFS_PREFIX}/${encodedThreadId}/turn/${turnCount}`);
-}
 function toTurnId(value: string | undefined): TurnId | null {
   const normalized = value?.trim();
   return normalized && normalized.length > 0 ? TurnId.makeUnsafe(normalized) : null;
 @@ -48,11 +42,11 @@ function trimToNonEmpty(value: string | null | undefined): string | undefined {
 function resolveThreadWorkspaceCwd(input: {
   readonly thread: {
-    readonly projectId: string;
+    readonly projectId: ProjectId;
     readonly worktreePath: string | null;
   };
   readonly projects: ReadonlyArray<{
-    readonly id: string;
+    readonly id: ProjectId;
     readonly workspaceRoot: string;
   }>;
 }): string | undefined {

apps/server/src/orchestration/Layers/OrchestrationEngine.ts+1-23

 @@ -5,13 +5,11 @@ import type {
   ThreadId,
 } from "@t3tools/contracts";
 import { OrchestrationCommand } from "@t3tools/contracts";
-import { Deferred, Effect, Layer, Option, PubSub, Queue, Schema, Stream } from "effect";
+import { Deferred, Effect, Layer, Option, PubSub, Queue, Stream } from "effect";
 import { OrchestrationEventStore } from "../../persistence/Services/OrchestrationEventStore.ts";
 import { OrchestrationCommandReceiptRepository } from "../../persistence/Services/OrchestrationCommandReceipts.ts";
 import {
-  toOrchestrationCommandDecodeError,
-  toOrchestrationJsonParseError,
   OrchestrationCommandInvariantError,
   OrchestrationCommandPreviouslyRejectedError,
   type OrchestrationDispatchError,
 @@ -29,8 +27,6 @@ interface CommandEnvelope {
   result: Deferred.Deferred<{ sequence: number }, OrchestrationDispatchError>;
 }
-const decodeUnknownCommand = Schema.decodeUnknownEffect(OrchestrationCommand);
 function commandToAggregateRef(command: OrchestrationCommand): {
   readonly aggregateKind: "project" | "thread";
   readonly aggregateId: ProjectId | ThreadId;
 @@ -175,30 +171,12 @@ const makeOrchestrationEngine = Effect.gen(function* () {
       return yield* Deferred.await(result);
     });
-  const dispatchUnknownCommand: OrchestrationEngineShape["dispatchUnknownCommand"] = (command) =>
-    Effect.gen(function* () {
-      const payload =
-        typeof command === "string"
-          ? yield* Effect.try({
-              try: () => JSON.parse(command) as unknown,
-              catch: toOrchestrationJsonParseError,
-            })
-          : command;
-      const decoded = yield* decodeUnknownCommand(payload).pipe(
-        Effect.mapError(toOrchestrationCommandDecodeError),
-      );
-      return yield* dispatch(decoded);
-    });
   const streamDomainEvents: OrchestrationEngineShape["streamDomainEvents"] =
     Stream.fromPubSub(eventPubSub);
   return {
     getReadModel,
     readEvents,
-    dispatchUnknownCommand,
     dispatch,
     streamDomainEvents,
   } satisfies OrchestrationEngineShape;

apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts+2-3

...	@@ -18,7 +18,6 @@ import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQu	...	@@ -18,7 +18,6 @@ import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQu
18	import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";	18	import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
19		19
20	const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);	20	const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
21	const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
22	const asTurnId = (value: string): TurnId => TurnId.makeUnsafe(value);	21	const asTurnId = (value: string): TurnId => TurnId.makeUnsafe(value);
23	const asMessageId = (value: string): MessageId => MessageId.makeUnsafe(value);	22	const asMessageId = (value: string): MessageId => MessageId.makeUnsafe(value);
24	const asEventId = (value: string): EventId => EventId.makeUnsafe(value);	23	const asEventId = (value: string): EventId => EventId.makeUnsafe(value);
...	@@ -225,7 +224,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {	...	@@ -225,7 +224,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
225	]);	224	]);
226	assert.deepEqual(snapshot.threads, [	225	assert.deepEqual(snapshot.threads, [
227	{	226	{
228	id: asThreadId("thread-1"),	227	id: ThreadId.makeUnsafe("thread-1"),
229	projectId: asProjectId("project-1"),	228	projectId: asProjectId("project-1"),
230	title: "Thread 1",	229	title: "Thread 1",
231	model: "gpt-5-codex",	230	model: "gpt-5-codex",
...	@@ -269,7 +268,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {	...	@@ -269,7 +268,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
269	},	268	},
270	],	269	],
271	session: {	270	session: {
272	threadId: asThreadId("thread-1"),	271	threadId: ThreadId.makeUnsafe("thread-1"),
273	status: "running",	272	status: "running",
274	providerName: "codex",	273	providerName: "codex",
275	providerSessionId: asProviderSessionId("provider-session-1"),	274	providerSessionId: asProviderSessionId("provider-session-1"),

apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts+22-24

 @@ -26,9 +26,7 @@ import { ProviderCommandReactorLive } from "./ProviderCommandReactor.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
 import { ProviderCommandReactor } from "../Services/ProviderCommandReactor.ts";
-const asCommandId = (value: string): CommandId => CommandId.makeUnsafe(value);
 const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
-const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
 const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);
 const asProviderTurnId = (value: string): ProviderTurnId => ProviderTurnId.makeUnsafe(value);
 const asApprovalRequestId = (value: string): ApprovalRequestId =>
 @@ -126,7 +124,7 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       engine.dispatch({
         type: "project.create",
-        commandId: asCommandId("cmd-project-create"),
+        commandId: CommandId.makeUnsafe("cmd-project-create"),
         projectId: asProjectId("project-1"),
         title: "Provider Project",
         workspaceRoot: "/tmp/provider-project",
 @@ -137,8 +135,8 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       engine.dispatch({
         type: "thread.create",
-        commandId: asCommandId("cmd-thread-create"),
+        commandId: CommandId.makeUnsafe("cmd-thread-create"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         projectId: asProjectId("project-1"),
         title: "Thread",
         model: "gpt-5-codex",
 @@ -165,8 +163,8 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.start",
-        commandId: asCommandId("cmd-turn-start-1"),
+        commandId: CommandId.makeUnsafe("cmd-turn-start-1"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         message: {
           messageId: asMessageId("user-message-1"),
           role: "user",
 @@ -185,7 +183,7 @@ describe("ProviderCommandReactor", () => {
     });
     const readModel = await Effect.runPromise(harness.engine.getReadModel());
-    const thread = readModel.threads.find((entry) => entry.id === asThreadId("thread-1"));
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.makeUnsafe("thread-1"));
     expect(thread?.session?.providerSessionId).toBe("sess-1");
   });
 @@ -196,10 +194,10 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.session.set",
-        commandId: asCommandId("cmd-session-set"),
+        commandId: CommandId.makeUnsafe("cmd-session-set"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         session: {
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           status: "running",
           providerName: "codex",
           providerSessionId: asSessionId("sess-1"),
 @@ -215,8 +213,8 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.interrupt",
-        commandId: asCommandId("cmd-turn-interrupt"),
+        commandId: CommandId.makeUnsafe("cmd-turn-interrupt"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         turnId: asTurnId("turn-1"),
         createdAt: now,
       }),
 @@ -235,10 +233,10 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.session.set",
-        commandId: asCommandId("cmd-session-set-for-approval"),
+        commandId: CommandId.makeUnsafe("cmd-session-set-for-approval"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         session: {
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           status: "running",
           providerName: "codex",
           providerSessionId: asSessionId("sess-1"),
 @@ -254,8 +252,8 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.approval.respond",
-        commandId: asCommandId("cmd-approval-respond"),
+        commandId: CommandId.makeUnsafe("cmd-approval-respond"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         requestId: asApprovalRequestId("approval-request-1"),
         decision: "accept",
         createdAt: now,
 @@ -277,10 +275,10 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.session.set",
-        commandId: asCommandId("cmd-session-set-for-stop"),
+        commandId: CommandId.makeUnsafe("cmd-session-set-for-stop"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         session: {
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           status: "ready",
           providerName: "codex",
           providerSessionId: asSessionId("sess-1"),
 @@ -296,15 +294,15 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.session.stop",
-        commandId: asCommandId("cmd-session-stop"),
+        commandId: CommandId.makeUnsafe("cmd-session-stop"),
-        threadId: asThreadId("thread-1"),
+        threadId: ThreadId.makeUnsafe("thread-1"),
         createdAt: now,
       }),
     );
     await waitFor(() => harness.stopSession.mock.calls.length === 1);
     const readModel = await Effect.runPromise(harness.engine.getReadModel());
-    const thread = readModel.threads.find((entry) => entry.id === asThreadId("thread-1"));
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.makeUnsafe("thread-1"));
     expect(thread?.session).not.toBeNull();
     expect(thread?.session?.status).toBe("stopped");
     expect(thread?.session?.providerSessionId).toBeNull();

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts+7-9

...	@@ -28,9 +28,7 @@ import {	...	@@ -28,9 +28,7 @@ import {
28	} from "../Services/OrchestrationEngine.ts";	28	} from "../Services/OrchestrationEngine.ts";
29	import { ProviderRuntimeIngestionService } from "../Services/ProviderRuntimeIngestion.ts";	29	import { ProviderRuntimeIngestionService } from "../Services/ProviderRuntimeIngestion.ts";
30		30
31	const asCommandId = (value: string): CommandId => CommandId.makeUnsafe(value);
32	const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);	31	const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
33	const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
34	const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);	32	const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);
35	const asProviderTurnId = (value: string): ProviderTurnId => ProviderTurnId.makeUnsafe(value);	33	const asProviderTurnId = (value: string): ProviderTurnId => ProviderTurnId.makeUnsafe(value);
36	const asItemId = (value: string): ProviderItemId => ProviderItemId.makeUnsafe(value);	34	const asItemId = (value: string): ProviderItemId => ProviderItemId.makeUnsafe(value);
...	@@ -78,7 +76,7 @@ async function waitForThread(	...	@@ -78,7 +76,7 @@ async function waitForThread(
78	activities: ReadonlyArray<{ kind: string }>;	76	activities: ReadonlyArray<{ kind: string }>;
79	}> => {	77	}> => {
80	const readModel = await Effect.runPromise(engine.getReadModel());	78	const readModel = await Effect.runPromise(engine.getReadModel());
81	const thread = readModel.threads.find((entry) => entry.id === asThreadId("thread-1"));	79	const thread = readModel.threads.find((entry) => entry.id === ThreadId.makeUnsafe("thread-1"));
82	if (thread && predicate(thread)) {	80	if (thread && predicate(thread)) {
83	return thread;	81	return thread;
84	}	82	}
...	@@ -132,7 +130,7 @@ describe("ProviderRuntimeIngestion", () => {	...	@@ -132,7 +130,7 @@ describe("ProviderRuntimeIngestion", () => {
132	await Effect.runPromise(	130	await Effect.runPromise(
133	engine.dispatch({	131	engine.dispatch({
134	type: "project.create",	132	type: "project.create",
135	commandId: asCommandId("cmd-provider-project-create"),	133	commandId: CommandId.makeUnsafe("cmd-provider-project-create"),
136	projectId: asProjectId("project-1"),	134	projectId: asProjectId("project-1"),
137	title: "Provider Project",	135	title: "Provider Project",
138	workspaceRoot: "/tmp/provider-project",	136	workspaceRoot: "/tmp/provider-project",
...	@@ -143,8 +141,8 @@ describe("ProviderRuntimeIngestion", () => {	...	@@ -143,8 +141,8 @@ describe("ProviderRuntimeIngestion", () => {
143	await Effect.runPromise(	141	await Effect.runPromise(
144	engine.dispatch({	142	engine.dispatch({
145	type: "thread.create",	143	type: "thread.create",
146	commandId: asCommandId("cmd-thread-create"),	144	commandId: CommandId.makeUnsafe("cmd-thread-create"),
147	threadId: asThreadId("thread-1"),	145	threadId: ThreadId.makeUnsafe("thread-1"),
148	projectId: asProjectId("project-1"),	146	projectId: asProjectId("project-1"),
149	title: "Thread",	147	title: "Thread",
150	model: "gpt-5-codex",	148	model: "gpt-5-codex",
...	@@ -156,10 +154,10 @@ describe("ProviderRuntimeIngestion", () => {	...	@@ -156,10 +154,10 @@ describe("ProviderRuntimeIngestion", () => {
156	await Effect.runPromise(	154	await Effect.runPromise(
157	engine.dispatch({	155	engine.dispatch({
158	type: "thread.session.set",	156	type: "thread.session.set",
159	commandId: asCommandId("cmd-session-seed"),	157	commandId: CommandId.makeUnsafe("cmd-session-seed"),
160	threadId: asThreadId("thread-1"),	158	threadId: ThreadId.makeUnsafe("thread-1"),
161	session: {	159	session: {
162	threadId: asThreadId("thread-1"),	160	threadId: ThreadId.makeUnsafe("thread-1"),
163	status: "ready",	161	status: "ready",
164	providerName: "codex",	162	providerName: "codex",
165	providerSessionId: asSessionId("sess-1"),	163	providerSessionId: asSessionId("sess-1"),

apps/server/src/orchestration/Services/OrchestrationEngine.ts+1-13

...	@@ -18,7 +18,7 @@ import type {	...	@@ -18,7 +18,7 @@ import type {
18	import { ServiceMap } from "effect";	18	import { ServiceMap } from "effect";
19	import type { Effect, Stream } from "effect";	19	import type { Effect, Stream } from "effect";
20		20
21	import type { OrchestrationDispatchError, OrchestrationEngineError } from "../Errors.ts";	21	import type { OrchestrationDispatchError } from "../Errors.ts";
22	import type { OrchestrationEventStoreError } from "../../persistence/Errors.ts";	22	import type { OrchestrationEventStoreError } from "../../persistence/Errors.ts";
23		23
24	export interface OrchestrationEngineShape {	24	export interface OrchestrationEngineShape {
...	@@ -39,18 +39,6 @@ export interface OrchestrationEngineShape {	...	@@ -39,18 +39,6 @@ export interface OrchestrationEngineShape {
39	fromSequenceExclusive: number,	39	fromSequenceExclusive: number,
40	) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError, never>;	40	) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError, never>;
41		41
42	/**
43	* Validate and dispatch an unknown command payload.
44	*
45	* Accepts either parsed values or raw JSON strings.
46	*
47	* @param command - Unknown command payload.
48	* @returns Effect containing the sequence of the persisted event.
49	*/
50	readonly dispatchUnknownCommand: (
51	command: unknown,
52	) => Effect.Effect<{ sequence: number }, OrchestrationEngineError, never>;
53
54	/**	42	/**
55	* Dispatch a validated orchestration command.	43	* Dispatch a validated orchestration command.
56	*	44	*

apps/server/src/orchestration/decider.projectScripts.test.ts+12-14

 @@ -5,10 +5,8 @@ import { Effect } from "effect";
 import { decideOrchestrationCommand } from "./decider.ts";
 import { createEmptyReadModel, projectEvent } from "./projector.ts";
-const asCommandId = (value: string): CommandId => CommandId.makeUnsafe(value);
 const asEventId = (value: string): EventId => EventId.makeUnsafe(value);
 const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
-const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
 const asMessageId = (value: string): MessageId => MessageId.makeUnsafe(value);
 describe("decider project scripts", () => {
 @@ -20,7 +18,7 @@ describe("decider project scripts", () => {
       decideOrchestrationCommand({
         command: {
           type: "project.create",
-          commandId: asCommandId("cmd-project-create-scripts"),
+          commandId: CommandId.makeUnsafe("cmd-project-create-scripts"),
           projectId: asProjectId("project-scripts"),
           title: "Scripts",
           workspaceRoot: "/tmp/scripts",
 @@ -46,9 +44,9 @@ describe("decider project scripts", () => {
         aggregateId: asProjectId("project-scripts"),
         type: "project.created",
         occurredAt: now,
-        commandId: asCommandId("cmd-project-create-scripts"),
+        commandId: CommandId.makeUnsafe("cmd-project-create-scripts"),
         causationEventId: null,
-        correlationId: asCommandId("cmd-project-create-scripts"),
+        correlationId: CommandId.makeUnsafe("cmd-project-create-scripts"),
         metadata: {},
         payload: {
           projectId: asProjectId("project-scripts"),
 @@ -76,7 +74,7 @@ describe("decider project scripts", () => {
       decideOrchestrationCommand({
         command: {
           type: "project.meta.update",
-          commandId: asCommandId("cmd-project-update-scripts"),
+          commandId: CommandId.makeUnsafe("cmd-project-update-scripts"),
           projectId: asProjectId("project-scripts"),
           scripts: Array.from(scripts),
         },
 @@ -100,9 +98,9 @@ describe("decider project scripts", () => {
         aggregateId: asProjectId("project-1"),
         type: "project.created",
         occurredAt: now,
-        commandId: asCommandId("cmd-project-create"),
+        commandId: CommandId.makeUnsafe("cmd-project-create"),
         causationEventId: null,
-        correlationId: asCommandId("cmd-project-create"),
+        correlationId: CommandId.makeUnsafe("cmd-project-create"),
         metadata: {},
         payload: {
           projectId: asProjectId("project-1"),
 @@ -120,15 +118,15 @@ describe("decider project scripts", () => {
         sequence: 2,
         eventId: asEventId("evt-thread-create"),
         aggregateKind: "thread",
-        aggregateId: asThreadId("thread-1"),
+        aggregateId: ThreadId.makeUnsafe("thread-1"),
         type: "thread.created",
         occurredAt: now,
-        commandId: asCommandId("cmd-thread-create"),
+        commandId: CommandId.makeUnsafe("cmd-thread-create"),
         causationEventId: null,
-        correlationId: asCommandId("cmd-thread-create"),
+        correlationId: CommandId.makeUnsafe("cmd-thread-create"),
         metadata: {},
         payload: {
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           projectId: asProjectId("project-1"),
           title: "Thread",
           model: "gpt-5-codex",
 @@ -144,8 +142,8 @@ describe("decider project scripts", () => {
       decideOrchestrationCommand({
         command: {
           type: "thread.turn.start",
-          commandId: asCommandId("cmd-turn-start"),
+          commandId: CommandId.makeUnsafe("cmd-turn-start"),
-          threadId: asThreadId("thread-1"),
+          threadId: ThreadId.makeUnsafe("thread-1"),
           message: {
             messageId: asMessageId("message-user-1"),
             role: "user",

apps/server/src/provider/Layers/CodexAdapter.test.ts+5-6

...	@@ -23,7 +23,6 @@ import { CodexAdapter } from "../Services/CodexAdapter.ts";	...	@@ -23,7 +23,6 @@ import { CodexAdapter } from "../Services/CodexAdapter.ts";
23	import { makeCodexAdapterLive } from "./CodexAdapter.ts";	23	import { makeCodexAdapterLive } from "./CodexAdapter.ts";
24		24
25	const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);	25	const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);
26	const asThreadId = (value: string): ProviderThreadId => ProviderThreadId.makeUnsafe(value);
27	const asTurnId = (value: string): ProviderTurnId => ProviderTurnId.makeUnsafe(value);	26	const asTurnId = (value: string): ProviderTurnId => ProviderTurnId.makeUnsafe(value);
28	const asEventId = (value: string): EventId => EventId.makeUnsafe(value);	27	const asEventId = (value: string): EventId => EventId.makeUnsafe(value);
29	const asItemId = (value: string): ProviderItemId => ProviderItemId.makeUnsafe(value);	28	const asItemId = (value: string): ProviderItemId => ProviderItemId.makeUnsafe(value);
...	@@ -36,7 +35,7 @@ class FakeCodexManager extends CodexAppServerManager {	...	@@ -36,7 +35,7 @@ class FakeCodexManager extends CodexAppServerManager {
36	sessionId: asSessionId("sess-1"),	35	sessionId: asSessionId("sess-1"),
37	provider: "codex",	36	provider: "codex",
38	status: "ready",	37	status: "ready",
39	threadId: asThreadId("thread-1"),	38	threadId: ProviderThreadId.makeUnsafe("thread-1"),
40	cwd: input.cwd,	39	cwd: input.cwd,
41	createdAt: now,	40	createdAt: now,
42	updatedAt: now,	41	updatedAt: now,
...	@@ -46,7 +45,7 @@ class FakeCodexManager extends CodexAppServerManager {	...	@@ -46,7 +45,7 @@ class FakeCodexManager extends CodexAppServerManager {
46		45
47	public sendTurnImpl = vi.fn(	46	public sendTurnImpl = vi.fn(
48	async (_input: ProviderSendTurnInput): Promise<ProviderTurnStartResult> => ({	47	async (_input: ProviderSendTurnInput): Promise<ProviderTurnStartResult> => ({
49	threadId: asThreadId("thread-1"),	48	threadId: ProviderThreadId.makeUnsafe("thread-1"),
50	turnId: asTurnId("turn-1"),	49	turnId: asTurnId("turn-1"),
51	}),	50	}),
52	);	51	);
...	@@ -56,12 +55,12 @@ class FakeCodexManager extends CodexAppServerManager {	...	@@ -56,12 +55,12 @@ class FakeCodexManager extends CodexAppServerManager {
56	);	55	);
57		56
58	public readThreadImpl = vi.fn(async (_sessionId: ProviderSessionId) => ({	57	public readThreadImpl = vi.fn(async (_sessionId: ProviderSessionId) => ({
59	threadId: asThreadId("thread-1"),	58	threadId: ProviderThreadId.makeUnsafe("thread-1"),
60	turns: [],	59	turns: [],
61	}));	60	}));
62		61
63	public rollbackThreadImpl = vi.fn(async (_sessionId: ProviderSessionId, _numTurns: number) => ({	62	public rollbackThreadImpl = vi.fn(async (_sessionId: ProviderSessionId, _numTurns: number) => ({
64	threadId: asThreadId("thread-1"),	63	threadId: ProviderThreadId.makeUnsafe("thread-1"),
65	turns: [],	64	turns: [],
66	}));	65	}));
67		66
...	@@ -194,7 +193,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {	...	@@ -194,7 +193,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
194	sessionId: asSessionId("sess-1"),	193	sessionId: asSessionId("sess-1"),
195	createdAt: new Date().toISOString(),	194	createdAt: new Date().toISOString(),
196	method: "item/completed",	195	method: "item/completed",
197	threadId: asThreadId("thread-1"),	196	threadId: ProviderThreadId.makeUnsafe("thread-1"),
198	turnId: asTurnId("turn-1"),	197	turnId: asTurnId("turn-1"),
199	itemId: asItemId("msg_1"),	198	itemId: asItemId("msg_1"),
200	payload: {	199	payload: {

apps/server/src/provider/Layers/ProviderService.test.ts+5-6

...	@@ -21,7 +21,7 @@ import {	...	@@ -21,7 +21,7 @@ import {
21	import { it, assert, vi } from "@effect/vitest";	21	import { it, assert, vi } from "@effect/vitest";
22	import { assertFailure } from "@effect/vitest/utils";	22	import { assertFailure } from "@effect/vitest/utils";
23		23
24	import { Effect, Fiber, Layer, Option, PubSub, Ref, Schema, Stream } from "effect";	24	import { Effect, Fiber, Layer, Option, PubSub, Ref, Stream } from "effect";
25	import * as SqlClient from "effect/unstable/sql/SqlClient";	25	import * as SqlClient from "effect/unstable/sql/SqlClient";
26		26
27	import {	27	import {
...	@@ -46,7 +46,6 @@ import {	...	@@ -46,7 +46,6 @@ import {
46	} from "../../persistence/Layers/Sqlite.ts";	46	} from "../../persistence/Layers/Sqlite.ts";
47		47
48	const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);	48	const asSessionId = (value: string): ProviderSessionId => ProviderSessionId.makeUnsafe(value);
49	const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
50	const asTurnId = (value: string): ProviderTurnId => ProviderTurnId.makeUnsafe(value);	49	const asTurnId = (value: string): ProviderTurnId => ProviderTurnId.makeUnsafe(value);
51	const asRequestId = (value: string): ApprovalRequestId => ApprovalRequestId.makeUnsafe(value);	50	const asRequestId = (value: string): ApprovalRequestId => ApprovalRequestId.makeUnsafe(value);
52	const asEventId = (value: string): EventId => EventId.makeUnsafe(value);	51	const asEventId = (value: string): EventId => EventId.makeUnsafe(value);
...	@@ -568,7 +567,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {	...	@@ -568,7 +567,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
568	provider: "codex",	567	provider: "codex",
569	sessionId: session.sessionId,	568	sessionId: session.sessionId,
570	createdAt: new Date().toISOString(),	569	createdAt: new Date().toISOString(),
571	threadId: asThreadId("thread-1"),	570	threadId: ThreadId.makeUnsafe("thread-1"),
572	turnId: asTurnId("turn-1"),	571	turnId: asTurnId("turn-1"),
573	status: "completed",	572	status: "completed",
574	};	573	};
...	@@ -616,7 +615,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {	...	@@ -616,7 +615,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
616	provider: "codex",	615	provider: "codex",
617	sessionId: session.sessionId,	616	sessionId: session.sessionId,
618	createdAt: new Date().toISOString(),	617	createdAt: new Date().toISOString(),
619	threadId: asThreadId("thread-1"),	618	threadId: ThreadId.makeUnsafe("thread-1"),
620	turnId: asTurnId("turn-1"),	619	turnId: asTurnId("turn-1"),
621	toolKind: "command",	620	toolKind: "command",
622	title: "Command run",	621	title: "Command run",
...	@@ -628,7 +627,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {	...	@@ -628,7 +627,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
628	provider: "codex",	627	provider: "codex",
629	sessionId: session.sessionId,	628	sessionId: session.sessionId,
630	createdAt: new Date().toISOString(),	629	createdAt: new Date().toISOString(),
631	threadId: asThreadId("thread-1"),	630	threadId: ThreadId.makeUnsafe("thread-1"),
632	turnId: asTurnId("turn-1"),	631	turnId: asTurnId("turn-1"),
633	delta: "hello",	632	delta: "hello",
634	},	633	},
...	@@ -638,7 +637,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {	...	@@ -638,7 +637,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
638	provider: "codex",	637	provider: "codex",
639	sessionId: session.sessionId,	638	sessionId: session.sessionId,
640	createdAt: new Date().toISOString(),	639	createdAt: new Date().toISOString(),
641	threadId: asThreadId("thread-1"),	640	threadId: ThreadId.makeUnsafe("thread-1"),
642	turnId: asTurnId("turn-1"),	641	turnId: asTurnId("turn-1"),
643	status: "completed",	642	status: "completed",
644	},	643	},

apps/server/src/serverLayers.ts+8

 @@ -4,8 +4,10 @@ import { NodeServices } from "@effect/platform-node";
 import { Effect, Layer } from "effect";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
+import { CheckpointDiffQueryLive } from "./checkpointing/Layers/CheckpointDiffQuery";
 import { CheckpointStoreLive } from "./checkpointing/Layers/CheckpointStore";
 import { ServerConfig } from "./config";
+import { CheckpointDiffQuery } from "./checkpointing/Services/CheckpointDiffQuery";
 import { CheckpointStore } from "./checkpointing/Services/CheckpointStore";
 import { OrchestrationCommandReceiptRepositoryLive } from "./persistence/Layers/OrchestrationCommandReceipts";
 import { OrchestrationEventStoreLive } from "./persistence/Layers/OrchestrationEventStore";
 @@ -55,6 +57,7 @@ export function makeServerRuntimeServicesLayer(): Layer.Layer<
   | OrchestrationEngineService
   | ProjectionSnapshotQuery
   | CheckpointStore
+  | CheckpointDiffQuery
   | OrchestrationReactor
   | TerminalManager
   | Keybindings,
 @@ -67,11 +70,16 @@ export function makeServerRuntimeServicesLayer(): Layer.Layer<
     Layer.provide(OrchestrationCommandReceiptRepositoryLive),
   );
   const checkpointStoreLayer = CheckpointStoreLive.pipe(Layer.provide(NodeServices.layer));
+  const checkpointDiffQueryLayer = CheckpointDiffQueryLive.pipe(
+    Layer.provideMerge(OrchestrationProjectionSnapshotQueryLive),
+    Layer.provideMerge(checkpointStoreLayer),
+  );
   const runtimeServicesLayer = Layer.mergeAll(
     orchestrationLayer,
     OrchestrationProjectionSnapshotQueryLive,
     checkpointStoreLayer,
+    checkpointDiffQueryLayer,
   );
   const runtimeIngestionLayer = ProviderRuntimeIngestionLive.pipe(
     Layer.provideMerge(runtimeServicesLayer),

apps/server/src/terminalManager.test.ts+4-3

 @@ -11,6 +11,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import type { PtyAdapterShape, PtyExitEvent, PtyProcess, PtySpawnInput } from "./ptyAdapter";
 import { TerminalManagerRuntime } from "./terminalManager";
+import { Encoding } from "effect";
 class FakePtyProcess implements PtyProcess {
   readonly writes: string[] = [];
 @@ -107,15 +108,15 @@ function openInput(overrides: Partial<TerminalOpenInput> = {}): TerminalOpenInpu
 }
 function historyLogName(threadId: string): string {
-  return `terminal_${Buffer.from(threadId, "utf8").toString("base64url")}.log`;
+  return `terminal_${Encoding.encodeBase64Url(threadId)}.log`;
 }
 function multiTerminalHistoryLogName(threadId: string, terminalId: string): string {
-  const threadPart = `terminal_${Buffer.from(threadId, "utf8").toString("base64url")}`;
+  const threadPart = `terminal_${Encoding.encodeBase64Url(threadId)}`;
   if (terminalId === DEFAULT_TERMINAL_ID) {
     return `${threadPart}.log`;
   }
-  return `${threadPart}_${Buffer.from(terminalId, "utf8").toString("base64url")}.log`;
+  return `${threadPart}_${Encoding.encodeBase64Url(terminalId)}.log`;
 }
 function historyLogPath(logsDir: string, threadId = "thread-1"): string {

apps/server/src/terminalManager.ts+3-3

...	@@ -13,7 +13,7 @@ import {	...	@@ -13,7 +13,7 @@ import {
13	type TerminalSessionSnapshot,	13	type TerminalSessionSnapshot,
14	type TerminalSessionStatus,	14	type TerminalSessionStatus,
15	} from "@t3tools/contracts";	15	} from "@t3tools/contracts";
16	import { Effect, Layer, Schema, ServiceMap } from "effect";	16	import { Effect, Encoding, Layer, Schema, ServiceMap } from "effect";
17		17
18	import { createLogger } from "./logger";	18	import { createLogger } from "./logger";
19	import { PtyAdapter, PtyAdapterShape, type PtyExitEvent, type PtyProcess } from "./ptyAdapter";	19	import { PtyAdapter, PtyAdapterShape, type PtyExitEvent, type PtyProcess } from "./ptyAdapter";
...	@@ -269,11 +269,11 @@ function legacySafeThreadId(threadId: string): string {	...	@@ -269,11 +269,11 @@ function legacySafeThreadId(threadId: string): string {
269	}	269	}
270		270
271	function toSafeThreadId(threadId: string): string {	271	function toSafeThreadId(threadId: string): string {
272	return `terminal_${Buffer.from(threadId, "utf8").toString("base64url")}`;	272	return `terminal_${Encoding.encodeBase64Url(threadId)}`;
273	}	273	}
274		274
275	function toSafeTerminalId(terminalId: string): string {	275	function toSafeTerminalId(terminalId: string): string {
276	return Buffer.from(terminalId, "utf8").toString("base64url");	276	return Encoding.encodeBase64Url(terminalId);
277	}	277	}
278		278
279	function toSessionKey(threadId: string, terminalId: string): string {	279	function toSessionKey(threadId: string, terminalId: string): string {

apps/server/src/wsServer.test.ts+21-1

...	@@ -175,7 +175,7 @@ class MockTerminalManager implements TerminalManagerShape {	...	@@ -175,7 +175,7 @@ class MockTerminalManager implements TerminalManagerShape {
175	this.sessions.delete(this.key(input.threadId, input.terminalId));	175	this.sessions.delete(this.key(input.threadId, input.terminalId));
176	return;	176	return;
177	}	177	}
178	for (const key of [...this.sessions.keys()]) {	178	for (const key of this.sessions.keys()) {
179	if (key.startsWith(`${input.threadId}\u0000`)) {	179	if (key.startsWith(`${input.threadId}\u0000`)) {
180	this.sessions.delete(key);	180	this.sessions.delete(key);
181	}	181	}
...	@@ -837,6 +837,26 @@ describe("WebSocket Server", () => {	...	@@ -837,6 +837,26 @@ describe("WebSocket Server", () => {
837	expect(response.error?.message).toContain("Thread 'thread-missing' not found.");	837	expect(response.error?.message).toContain("Thread 'thread-missing' not found.");
838	});	838	});
839		839
		840	it("returns error when requesting turn diff with an inverted range", async () => {
		841	server = await createTestServer({ cwd: "/test" });
		842	const addr = server.address();
		843	const port = typeof addr === "object" && addr !== null ? addr.port : 0;
		844
		845	const ws = await connectWs(port);
		846	connections.push(ws);
		847	await waitForMessage(ws);
		848
		849	const response = await sendRequest(ws, ORCHESTRATION_WS_METHODS.getTurnDiff, {
		850	threadId: "thread-any",
		851	fromTurnCount: 2,
		852	toTurnCount: 1,
		853	});
		854	expect(response.result).toBeUndefined();
		855	expect(response.error?.message).toContain(
		856	"fromTurnCount must be less than or equal to toTurnCount",
		857	);
		858	});
		859
840	it("returns error when requesting full thread diff for unknown thread", async () => {	860	it("returns error when requesting full thread diff for unknown thread", async () => {
841	server = await createTestServer({ cwd: "/test" });	861	server = await createTestServer({ cwd: "/test" });
842	const addr = server.address();	862	const addr = server.address();

apps/server/src/wsServer.ts+29-153

...	@@ -4,19 +4,19 @@ import path from "node:path";	...	@@ -4,19 +4,19 @@ import path from "node:path";
4	import type { Duplex } from "node:stream";	4	import type { Duplex } from "node:stream";
5		5
6	import {	6	import {
7	CheckpointRef,	7	CommandId,
8	ORCHESTRATION_WS_CHANNELS,	8	ORCHESTRATION_WS_CHANNELS,
9	ORCHESTRATION_WS_METHODS,	9	ORCHESTRATION_WS_METHODS,
		10	ProjectId,
10	TerminalEvent,	11	TerminalEvent,
11	WS_CHANNELS,	12	WS_CHANNELS,
12	WS_METHODS,	13	WS_METHODS,
13	WebSocketRequest,	14	WebSocketRequest,
14	WebSocketResponse,
15	WsPush,	15	WsPush,
16	WsResponse,	16	WsResponse,
17	} from "@t3tools/contracts";	17	} from "@t3tools/contracts";
18	import { NodeHttpServer } from "@effect/platform-node";	18	import { NodeHttpServer } from "@effect/platform-node";
19	import { Cause, Effect, Exit, Layer, Schema, Scope, ServiceMap, Stream } from "effect";	19	import { Cause, Effect, Exit, Layer, Schema, Scope, ServiceMap, Stream, Struct } from "effect";
20	import { WebSocketServer, type WebSocket } from "ws";	20	import { WebSocketServer, type WebSocket } from "ws";
21		21
22	import { createLogger } from "./logger";	22	import { createLogger } from "./logger";
...	@@ -37,7 +37,7 @@ import { OrchestrationEngineService } from "./orchestration/Services/Orchestrati	...	@@ -37,7 +37,7 @@ import { OrchestrationEngineService } from "./orchestration/Services/Orchestrati
37	import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery";	37	import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery";
38	import { OrchestrationReactor } from "./orchestration/Services/OrchestrationReactor";	38	import { OrchestrationReactor } from "./orchestration/Services/OrchestrationReactor";
39	import { ProviderService } from "./provider/Services/ProviderService";	39	import { ProviderService } from "./provider/Services/ProviderService";
40	import { CheckpointStore } from "./checkpointing/Services/CheckpointStore";	40	import { CheckpointDiffQuery } from "./checkpointing/Services/CheckpointDiffQuery";
41	import { clamp } from "effect/Number";	41	import { clamp } from "effect/Number";
42	import { Open } from "./open";	42	import { Open } from "./open";
43	import { ServerConfig } from "./config";	43	import { ServerConfig } from "./config";
...	@@ -133,22 +133,14 @@ function websocketRawToString(raw: unknown): string \| null {	...	@@ -133,22 +133,14 @@ function websocketRawToString(raw: unknown): string \| null {
133	return null;	133	return null;
134	}	134	}
135		135
136	function stripRequestTag<T extends { _tag: string }>(body: T): Omit<T, "_tag"> {	136	function stripRequestTag<T extends { _tag: string }>(body: T) {
137	const { _tag: _ignoredTag, ...rest } = body;	137	return Struct.omit(body, ["_tag"]);
138	return rest;
139	}
140
141	const CHECKPOINT_REFS_PREFIX = "refs/t3/checkpoints";
142
143	function checkpointRefForThreadTurn(threadId: string, turnCount: number): CheckpointRef {
144	const encodedThreadId = Buffer.from(threadId, "utf8").toString("base64url");
145	return CheckpointRef.makeUnsafe(`${CHECKPOINT_REFS_PREFIX}/${encodedThreadId}/turn/${turnCount}`);
146	}	138	}
147		139
148	export type ServerCoreRuntimeServices =	140	export type ServerCoreRuntimeServices =
149	\| OrchestrationEngineService	141	\| OrchestrationEngineService
150	\| ProjectionSnapshotQuery	142	\| ProjectionSnapshotQuery
151	\| CheckpointStore	143	\| CheckpointDiffQuery
152	\| OrchestrationReactor	144	\| OrchestrationReactor
153	\| ProviderService;	145	\| ProviderService;
154		146
...	@@ -301,7 +293,7 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E	...	@@ -301,7 +293,7 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E
301		293
302	const orchestrationEngine = yield* OrchestrationEngineService;	294	const orchestrationEngine = yield* OrchestrationEngineService;
303	const projectionReadModelQuery = yield* ProjectionSnapshotQuery;	295	const projectionReadModelQuery = yield* ProjectionSnapshotQuery;
304	const liveCheckpointStore = yield* CheckpointStore;	296	const checkpointDiffQuery = yield* CheckpointDiffQuery;
305	const liveProviderService = yield* ProviderService;	297	const liveProviderService = yield* ProviderService;
306	const orchestrationReactor = yield* OrchestrationReactor;	298	const orchestrationReactor = yield* OrchestrationReactor;
307	const { openInEditor } = yield* Open;	299	const { openInEditor } = yield* Open;
...	@@ -338,10 +330,10 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E	...	@@ -338,10 +330,10 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E
338	if (!existing) {	330	if (!existing) {
339	const createdAt = new Date().toISOString();	331	const createdAt = new Date().toISOString();
340	const projectName = path.basename(cwd) \|\| "project";	332	const projectName = path.basename(cwd) \|\| "project";
341	yield* orchestrationEngine.dispatchUnknownCommand({	333	yield* orchestrationEngine.dispatch({
342	type: "project.create",	334	type: "project.create",
343	commandId: crypto.randomUUID(),	335	commandId: CommandId.makeUnsafe(crypto.randomUUID()),
344	projectId: crypto.randomUUID(),	336	projectId: ProjectId.makeUnsafe(crypto.randomUUID()),
345	title: projectName,	337	title: projectName,
346	workspaceRoot: cwd,	338	workspaceRoot: cwd,
347	defaultModel: "gpt-5-codex",	339	defaultModel: "gpt-5-codex",
...	@@ -351,110 +343,6 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E	...	@@ -351,110 +343,6 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E
351	}	343	}
352		344
353	const routeRequest = Effect.fn(function* (request: WebSocketRequest) {	345	const routeRequest = Effect.fn(function* (request: WebSocketRequest) {
354	const computeTurnDiff = Effect.fn(function* (input: {
355	readonly threadId: string;
356	readonly fromTurnCount: number;
357	readonly toTurnCount: number;
358	}) {
359	if (input.fromTurnCount > input.toTurnCount) {
360	throw new Error(
361	`Invalid turn diff range for thread '${input.threadId}': from ${input.fromTurnCount} exceeds to ${input.toTurnCount}.`,
362	);
363	}
364
365	if (input.fromTurnCount === input.toTurnCount) {
366	return {
367	threadId: input.threadId,
368	fromTurnCount: input.fromTurnCount,
369	toTurnCount: input.toTurnCount,
370	diff: "",
371	};
372	}
373
374	const snapshot = yield* projectionReadModelQuery.getSnapshot();
375	const thread = snapshot.threads.find((entry) => entry.id === input.threadId);
376	if (!thread) {
377	throw new Error(`Thread '${input.threadId}' not found.`);
378	}
379
380	const maxTurnCount = thread.checkpoints.reduce(
381	(max, checkpoint) => Math.max(max, checkpoint.checkpointTurnCount),
382	0,
383	);
384	if (input.toTurnCount > maxTurnCount) {
385	throw new Error(
386	`Turn diff range exceeds current turn count for thread '${input.threadId}': requested ${input.toTurnCount}, current ${maxTurnCount}.`,
387	);
388	}
389
390	const workspaceCwd =
391	thread.worktreePath?.trim() \|\|
392	snapshot.projects.find((project) => project.id === thread.projectId)?.workspaceRoot?.trim();
393	if (!workspaceCwd) {
394	throw new Error(
395	`Invariant violation: workspace path missing for thread '${input.threadId}' when computing turn diff.`,
396	);
397	}
398
399	const fromCheckpointRef =
400	input.fromTurnCount === 0
401	? checkpointRefForThreadTurn(input.threadId, 0)
402	: thread.checkpoints.find(
403	(checkpoint) => checkpoint.checkpointTurnCount === input.fromTurnCount,
404	)?.checkpointRef;
405	if (!fromCheckpointRef) {
406	throw new Error(
407	`Checkpoint is unavailable for turn ${input.fromTurnCount} in thread ${input.threadId}.`,
408	);
409	}
410
411	const toCheckpointRef = thread.checkpoints.find(
412	(checkpoint) => checkpoint.checkpointTurnCount === input.toTurnCount,
413	)?.checkpointRef;
414	if (!toCheckpointRef) {
415	throw new Error(
416	`Checkpoint is unavailable for turn ${input.toTurnCount} in thread ${input.threadId}.`,
417	);
418	}
419
420	const [fromExists, toExists] = yield* Effect.all(
421	[
422	liveCheckpointStore.hasCheckpointRef({
423	cwd: workspaceCwd,
424	checkpointRef: fromCheckpointRef,
425	}),
426	liveCheckpointStore.hasCheckpointRef({
427	cwd: workspaceCwd,
428	checkpointRef: toCheckpointRef,
429	}),
430	],
431	{ concurrency: "unbounded" },
432	);
433	if (!fromExists) {
434	throw new Error(
435	`Filesystem checkpoint is unavailable for turn ${input.fromTurnCount} in thread ${input.threadId}.`,
436	);
437	}
438	if (!toExists) {
439	throw new Error(
440	`Filesystem checkpoint is unavailable for turn ${input.toTurnCount} in thread ${input.threadId}.`,
441	);
442	}
443
444	const diff = yield* liveCheckpointStore.diffCheckpoints({
445	cwd: workspaceCwd,
446	fromCheckpointRef,
447	toCheckpointRef,
448	fallbackFromToHead: false,
449	});
450	return {
451	threadId: input.threadId,
452	fromTurnCount: input.fromTurnCount,
453	toTurnCount: input.toTurnCount,
454	diff,
455	};
456	});
457
458	switch (request.body._tag) {	346	switch (request.body._tag) {
459	case ORCHESTRATION_WS_METHODS.getSnapshot:	347	case ORCHESTRATION_WS_METHODS.getSnapshot:
460	return yield* projectionReadModelQuery.getSnapshot();	348	return yield* projectionReadModelQuery.getSnapshot();
...	@@ -466,16 +354,12 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E	...	@@ -466,16 +354,12 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E
466		354
467	case ORCHESTRATION_WS_METHODS.getTurnDiff: {	355	case ORCHESTRATION_WS_METHODS.getTurnDiff: {
468	const body = stripRequestTag(request.body);	356	const body = stripRequestTag(request.body);
469	return yield* computeTurnDiff(body);	357	return yield* checkpointDiffQuery.getTurnDiff(body);
470	}	358	}
471		359
472	case ORCHESTRATION_WS_METHODS.getFullThreadDiff: {	360	case ORCHESTRATION_WS_METHODS.getFullThreadDiff: {
473	const body = stripRequestTag(request.body);	361	const body = stripRequestTag(request.body);
474	return yield* computeTurnDiff({	362	return yield* checkpointDiffQuery.getFullThreadDiff(body);
475	threadId: body.threadId,
476	fromTurnCount: 0,
477	toTurnCount: body.toTurnCount,
478	});
479	}	363	}
480		364
481	case ORCHESTRATION_WS_METHODS.replayEvents: {	365	case ORCHESTRATION_WS_METHODS.replayEvents: {
...	@@ -599,46 +483,38 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E	...	@@ -599,46 +483,38 @@ export const createServer = Effect.fn(function* (options: ServerOptions = {}): E
599		483
600	const messageText = websocketRawToString(raw);	484	const messageText = websocketRawToString(raw);
601	if (messageText === null) {	485	if (messageText === null) {
602	const errorResponse = yield* encodeResponse(	486	const errorResponse = yield* encodeResponse({
603	new WebSocketResponse({	487	id: "unknown",
604	id: "unknown",	488	error: { message: "Invalid request format: Failed to read message" },
605	error: { message: "Invalid request format: Failed to read message" },	489	});
606	}),
607	);
608	ws.send(errorResponse);	490	ws.send(errorResponse);
609	return;	491	return;
610	}	492	}
611		493
612	const request = Schema.decodeExit(Schema.fromJsonString(WebSocketRequest))(messageText);	494	const request = Schema.decodeExit(Schema.fromJsonString(WebSocketRequest))(messageText);
613	if (request._tag === "Failure") {	495	if (request._tag === "Failure") {
614	const errorResponse = yield* encodeResponse(	496	const errorResponse = yield* encodeResponse({
615	new WebSocketResponse({	497	id: "unknown",
616	id: "unknown",	498	error: { message: `Invalid request format: ${Cause.pretty(request.cause)}` },
617	error: { message: `Invalid request format: ${Cause.pretty(request.cause)}` },	499	});
618	}),
619	);
620	ws.send(errorResponse);	500	ws.send(errorResponse);
621	return;	501	return;
622	}	502	}
623		503
624	const result = yield* Effect.exit(routeRequest(request.value));	504	const result = yield* Effect.exit(routeRequest(request.value));
625	if (result._tag === "Failure") {	505	if (result._tag === "Failure") {
626	const errorResponse = yield* encodeResponse(	506	const errorResponse = yield* encodeResponse({
627	new WebSocketResponse({	507	id: request.value.id,
628	id: request.value.id,	508	error: { message: Cause.pretty(result.cause) },
629	error: { message: Cause.pretty(result.cause) },	509	});
630	}),
631	);
632	ws.send(errorResponse);	510	ws.send(errorResponse);
633	return;	511	return;
634	}	512	}
635		513
636	const response = yield* encodeResponse(	514	const response = yield* encodeResponse({
637	new WebSocketResponse({	515	id: request.value.id,
638	id: request.value.id,	516	result: result.value,
639	result: result.value,	517	});
640	}),
641	);
642	ws.send(response);	518	ws.send(response);
643	});	519	});
644		520

apps/web/src/components/BranchToolbar.logic.test.ts+7-4

...	@@ -1,4 +1,4 @@	...	@@ -1,4 +1,4 @@
1	import type { GitBranch } from "@t3tools/contracts";	1	import { ThreadId, type GitBranch } from "@t3tools/contracts";
2	import { describe, expect, it } from "vitest";	2	import { describe, expect, it } from "vitest";
3	import { deriveSyncedLocalBranch } from "./BranchToolbar.logic";	3	import { deriveSyncedLocalBranch } from "./BranchToolbar.logic";
4		4
...	@@ -19,8 +19,9 @@ const branches: GitBranch[] = [	...	@@ -19,8 +19,9 @@ const branches: GitBranch[] = [
19		19
20	describe("deriveSyncedLocalBranch", () => {	20	describe("deriveSyncedLocalBranch", () => {
21	it("syncs to git current branch in local mode", () => {	21	it("syncs to git current branch in local mode", () => {
		22	const threadId = ThreadId.makeUnsafe("thread-1");
22	const result = deriveSyncedLocalBranch({	23	const result = deriveSyncedLocalBranch({
23	activeThreadId: "thread-1",	24	activeThreadId: threadId,
24	activeWorktreePath: null,	25	activeWorktreePath: null,
25	envMode: "local",	26	envMode: "local",
26	activeThreadBranch: "feature/demo",	27	activeThreadBranch: "feature/demo",
...	@@ -31,8 +32,9 @@ describe("deriveSyncedLocalBranch", () => {	...	@@ -31,8 +32,9 @@ describe("deriveSyncedLocalBranch", () => {
31	});	32	});
32		33
33	it("does not sync when creating a new worktree", () => {	34	it("does not sync when creating a new worktree", () => {
		35	const threadId = ThreadId.makeUnsafe("thread-1");
34	const result = deriveSyncedLocalBranch({	36	const result = deriveSyncedLocalBranch({
35	activeThreadId: "thread-1",	37	activeThreadId: threadId,
36	activeWorktreePath: null,	38	activeWorktreePath: null,
37	envMode: "worktree",	39	envMode: "worktree",
38	activeThreadBranch: "feature/demo",	40	activeThreadBranch: "feature/demo",
...	@@ -43,8 +45,9 @@ describe("deriveSyncedLocalBranch", () => {	...	@@ -43,8 +45,9 @@ describe("deriveSyncedLocalBranch", () => {
43	});	45	});
44		46
45	it("does not sync when thread already targets a worktree path", () => {	47	it("does not sync when thread already targets a worktree path", () => {
		48	const threadId = ThreadId.makeUnsafe("thread-1");
46	const result = deriveSyncedLocalBranch({	49	const result = deriveSyncedLocalBranch({
47	activeThreadId: "thread-1",	50	activeThreadId: threadId,
48	activeWorktreePath: "/tmp/repo/worktrees/feature-demo",	51	activeWorktreePath: "/tmp/repo/worktrees/feature-demo",
49	envMode: "local",	52	envMode: "local",
50	activeThreadBranch: "feature/demo",	53	activeThreadBranch: "feature/demo",

apps/web/src/components/BranchToolbar.logic.ts+2-2

...	@@ -1,7 +1,7 @@	...	@@ -1,7 +1,7 @@
1	import type { GitBranch } from "@t3tools/contracts";	1	import type { GitBranch, ThreadId } from "@t3tools/contracts";
2		2
3	interface DeriveSyncedLocalBranchInput {	3	interface DeriveSyncedLocalBranchInput {
4	activeThreadId: string \| undefined;	4	activeThreadId: ThreadId \| undefined;
5	activeWorktreePath: string \| null;	5	activeWorktreePath: string \| null;
6	envMode: "local" \| "worktree";	6	envMode: "local" \| "worktree";
7	activeThreadBranch: string \| null;	7	activeThreadBranch: string \| null;

apps/web/src/components/BranchToolbar.tsx+14-12

...	@@ -1,14 +1,14 @@	...	@@ -1,14 +1,14 @@
1	import type { GitBranch } from "@t3tools/contracts";	1	import type { GitBranch, ThreadId } from "@t3tools/contracts";
2	import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";	2	import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
3	import { useEffect, useState } from "react";	3	import { useEffect, useState } from "react";
4		4
5	import { useNativeApi } from "../hooks/useNativeApi";	5	import { newCommandId } from "../lib/orchestrationIds";
6	import { asThreadId, newCommandId } from "../lib/orchestrationIds";
7	import {	6	import {
8	gitBranchesQueryOptions,	7	gitBranchesQueryOptions,
9	gitCheckoutMutationOptions,	8	gitCheckoutMutationOptions,
10	gitCreateBranchAndCheckoutMutationOptions,	9	gitCreateBranchAndCheckoutMutationOptions,
11	} from "../lib/gitReactQuery";	10	} from "../lib/gitReactQuery";
		11	import { readNativeApi } from "../nativeApi";
12	import { useStore } from "../store";	12	import { useStore } from "../store";
13	import { deriveSyncedLocalBranch } from "./BranchToolbar.logic";	13	import { deriveSyncedLocalBranch } from "./BranchToolbar.logic";
14	import { Button } from "./ui/button";	14	import { Button } from "./ui/button";
...	@@ -24,7 +24,7 @@ import {	...	@@ -24,7 +24,7 @@ import {
24	import { ChevronDownIcon } from "lucide-react";	24	import { ChevronDownIcon } from "lucide-react";
25		25
26	interface BranchToolbarProps {	26	interface BranchToolbarProps {
27	threadId: string;	27	threadId: ThreadId;
28	envMode: "local" \| "worktree";	28	envMode: "local" \| "worktree";
29	onEnvModeChange: (mode: "local" \| "worktree") => void;	29	onEnvModeChange: (mode: "local" \| "worktree") => void;
30	envLocked: boolean;	30	envLocked: boolean;
...	@@ -39,7 +39,6 @@ export default function BranchToolbar({	...	@@ -39,7 +39,6 @@ export default function BranchToolbar({
39	onComposerFocusRequest,	39	onComposerFocusRequest,
40	}: BranchToolbarProps) {	40	}: BranchToolbarProps) {
41	const { state, dispatch } = useStore();	41	const { state, dispatch } = useStore();
42	const api = useNativeApi();
43	const queryClient = useQueryClient();	42	const queryClient = useQueryClient();
44		43
45	const [isBranchMenuOpen, setIsBranchMenuOpen] = useState(false);	44	const [isBranchMenuOpen, setIsBranchMenuOpen] = useState(false);
...	@@ -54,7 +53,7 @@ export default function BranchToolbar({	...	@@ -54,7 +53,7 @@ export default function BranchToolbar({
54		53
55	// ── Queries ───────────────────────────────────────────────────────────	54	// ── Queries ───────────────────────────────────────────────────────────
56		55
57	const branchesQuery = useQuery(gitBranchesQueryOptions(api, branchCwd));	56	const branchesQuery = useQuery(gitBranchesQueryOptions(branchCwd));
58		57
59	const branches = branchesQuery.data?.branches ?? [];	58	const branches = branchesQuery.data?.branches ?? [];
60	const branchNames = branches.map((branch) => branch.name);	59	const branchNames = branches.map((branch) => branch.name);
...	@@ -72,11 +71,11 @@ export default function BranchToolbar({	...	@@ -72,11 +71,11 @@ export default function BranchToolbar({
72	// ── Mutations ─────────────────────────────────────────────────────────	71	// ── Mutations ─────────────────────────────────────────────────────────
73		72
74	const checkoutMutation = useMutation(	73	const checkoutMutation = useMutation(
75	gitCheckoutMutationOptions({ api, cwd: branchCwd, queryClient }),	74	gitCheckoutMutationOptions({ cwd: branchCwd, queryClient }),
76	);	75	);
77		76
78	const createBranchMutation = useMutation(	77	const createBranchMutation = useMutation(
79	gitCreateBranchAndCheckoutMutationOptions({ api, cwd: branchCwd, queryClient }),	78	gitCreateBranchAndCheckoutMutationOptions({ cwd: branchCwd, queryClient }),
80	);	79	);
81		80
82	// ── Effects ───────────────────────────────────────────────────────────	81	// ── Effects ───────────────────────────────────────────────────────────
...	@@ -92,12 +91,13 @@ export default function BranchToolbar({	...	@@ -92,12 +91,13 @@ export default function BranchToolbar({
92	queryBranches,	91	queryBranches,
93	});	92	});
94	if (!activeThreadId \|\| !syncedBranch) return;	93	if (!activeThreadId \|\| !syncedBranch) return;
		94	const api = readNativeApi();
95		95
96	if (api) {	96	if (api) {
97	void api.orchestration.dispatchCommand({	97	void api.orchestration.dispatchCommand({
98	type: "thread.meta.update",	98	type: "thread.meta.update",
99	commandId: newCommandId(),	99	commandId: newCommandId(),
100	threadId: asThreadId(activeThreadId),	100	threadId: activeThreadId,
101	branch: syncedBranch,	101	branch: syncedBranch,
102	worktreePath: null,	102	worktreePath: null,
103	});	103	});
...	@@ -115,7 +115,6 @@ export default function BranchToolbar({	...	@@ -115,7 +115,6 @@ export default function BranchToolbar({
115	queryBranches,	115	queryBranches,
116	envMode,	116	envMode,
117	dispatch,	117	dispatch,
118	api,
119	]);	118	]);
120		119
121	useEffect(() => {	120	useEffect(() => {
...	@@ -132,6 +131,7 @@ export default function BranchToolbar({	...	@@ -132,6 +131,7 @@ export default function BranchToolbar({
132		131
133	const setThreadBranch = (branch: string \| null, worktreePath: string \| null) => {	132	const setThreadBranch = (branch: string \| null, worktreePath: string \| null) => {
134	if (!activeThreadId) return;	133	if (!activeThreadId) return;
		134	const api = readNativeApi();
135	// If the effective cwd is about to change, stop the running session so the	135	// If the effective cwd is about to change, stop the running session so the
136	// next message creates a new one with the correct cwd.	136	// next message creates a new one with the correct cwd.
137	const sessionId = activeThread?.session?.sessionId;	137	const sessionId = activeThread?.session?.sessionId;
...	@@ -140,7 +140,7 @@ export default function BranchToolbar({	...	@@ -140,7 +140,7 @@ export default function BranchToolbar({
140	.dispatchCommand({	140	.dispatchCommand({
141	type: "thread.session.stop",	141	type: "thread.session.stop",
142	commandId: newCommandId(),	142	commandId: newCommandId(),
143	threadId: asThreadId(activeThreadId),	143	threadId: activeThreadId,
144	createdAt: new Date().toISOString(),	144	createdAt: new Date().toISOString(),
145	})	145	})
146	.catch(() => undefined);	146	.catch(() => undefined);
...	@@ -149,7 +149,7 @@ export default function BranchToolbar({	...	@@ -149,7 +149,7 @@ export default function BranchToolbar({
149	void api.orchestration.dispatchCommand({	149	void api.orchestration.dispatchCommand({
150	type: "thread.meta.update",	150	type: "thread.meta.update",
151	commandId: newCommandId(),	151	commandId: newCommandId(),
152	threadId: asThreadId(activeThreadId),	152	threadId: activeThreadId,
153	branch,	153	branch,
154	worktreePath,	154	worktreePath,
155	});	155	});
...	@@ -158,6 +158,7 @@ export default function BranchToolbar({	...	@@ -158,6 +158,7 @@ export default function BranchToolbar({
158	};	158	};
159		159
160	const selectBranch = (branch: GitBranch) => {	160	const selectBranch = (branch: GitBranch) => {
		161	const api = readNativeApi();
161	if (!api \|\| !activeThreadId \|\| !branchCwd) return;	162	if (!api \|\| !activeThreadId \|\| !branchCwd) return;
162		163
163	// For new worktree mode, selecting a branch picks the base branch.	164	// For new worktree mode, selecting a branch picks the base branch.
...	@@ -198,6 +199,7 @@ export default function BranchToolbar({	...	@@ -198,6 +199,7 @@ export default function BranchToolbar({
198		199
199	const createBranch = (rawName: string) => {	200	const createBranch = (rawName: string) => {
200	const name = rawName.trim();	201	const name = rawName.trim();
		202	const api = readNativeApi();
201	if (!api \|\| !activeThreadId \|\| !branchCwd \|\| !name \|\| createBranchMutation.isPending) return;	203	if (!api \|\| !activeThreadId \|\| !branchCwd \|\| !name \|\| createBranchMutation.isPending) return;
202	createBranchMutation.mutate(name, {	204	createBranchMutation.mutate(name, {
203	onSuccess: () => {	205	onSuccess: () => {

apps/web/src/components/ChatMarkdown.tsx+9-5

 @@ -3,7 +3,7 @@ import type { Components } from "react-markdown";
 import ReactMarkdown from "react-markdown";
 import rehypeHighlight from "rehype-highlight";
 import remarkGfm from "remark-gfm";
-import { useNativeApi } from "../hooks/useNativeApi";
+import { readNativeApi } from "../nativeApi";
 import { resolveMarkdownFileLinkTarget } from "../markdown-links";
 import { preferredTerminalEditor } from "../terminal-links";
 @@ -13,12 +13,11 @@ interface ChatMarkdownProps {
 }
 function ChatMarkdown({ text, cwd }: ChatMarkdownProps) {
-  const api = useNativeApi();
   const markdownComponents = useMemo<Components>(
     () => ({
       a({ node: _node, href, ...props }) {
         const targetPath = resolveMarkdownFileLinkTarget(href, cwd);
-        if (!targetPath || !api) {
+        if (!targetPath) {
           return <a {...props} href={href} target="_blank" rel="noreferrer" />;
         }
 @@ -29,13 +28,18 @@ function ChatMarkdown({ text, cwd }: ChatMarkdownProps) {
             onClick={(event) => {
               event.preventDefault();
               event.stopPropagation();
-              void api.shell.openInEditor(targetPath, preferredTerminalEditor());
+              const api = readNativeApi();
+              if (api) {
+                void api.shell.openInEditor(targetPath, preferredTerminalEditor());
+              } else {
+                console.warn("Native API not found. Unable to open file in editor.");
+              }
             }}
           />
         );
       },
     }),
-    [api, cwd],
+    [cwd],
   );
   return (

apps/web/src/components/ChatView.tsx+101-98

...	@@ -1,15 +1,25 @@	...	@@ -1,15 +1,25 @@
1	import {	1	import {
		2	type ApprovalRequestId,
		3	DEFAULT_MODEL,
		4	DEFAULT_REASONING,
2	EDITORS,	5	EDITORS,
3	type EditorId,	6	type EditorId,
4	type KeybindingCommand,	7	type KeybindingCommand,
5	type NativeApi,	8	type MessageId,
		9	MODEL_OPTIONS,
		10	type ProjectId,
6	type ProjectEntry,	11	type ProjectEntry,
7	type ProjectScript,	12	type ProjectScript,
8	ModelSlug,	13	ModelSlug,
9	PROVIDER_SEND_TURN_MAX_ATTACHMENTS,	14	PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
10	PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,	15	PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,
		16	REASONING_OPTIONS,
		17	type ReasoningEffort,
11	type ResolvedKeybindingsConfig,	18	type ResolvedKeybindingsConfig,
12	type ProviderApprovalDecision,	19	type ProviderApprovalDecision,
		20	type ThreadId,
		21	type TurnId,
		22	resolveModelSlug,
13	} from "@t3tools/contracts";	23	} from "@t3tools/contracts";
14	import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";	24	import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
15	import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";	25	import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
...	@@ -27,14 +37,6 @@ import {	...	@@ -27,14 +37,6 @@ import {
27	detectComposerTrigger,	37	detectComposerTrigger,
28	replaceTextRange,	38	replaceTextRange,
29	} from "../composer-logic";	39	} from "../composer-logic";
30	import {
31	DEFAULT_MODEL,
32	DEFAULT_REASONING,
33	MODEL_OPTIONS,
34	REASONING_OPTIONS,
35	ReasoningEffort,
36	resolveModelSlug,
37	} from "../model-logic";
38	import {	40	import {
39	derivePendingApprovals,	41	derivePendingApprovals,
40	derivePhase,	42	derivePhase,
...	@@ -66,7 +68,6 @@ import {	...	@@ -66,7 +68,6 @@ import {
66	} from "../keybindings";	68	} from "../keybindings";
67	import ChatMarkdown from "./ChatMarkdown";	69	import ChatMarkdown from "./ChatMarkdown";
68	import ThreadTerminalDrawer from "./ThreadTerminalDrawer";	70	import ThreadTerminalDrawer from "./ThreadTerminalDrawer";
69	import { useNativeApi } from "../hooks/useNativeApi";
70	import { Alert, AlertAction, AlertDescription, AlertTitle } from "./ui/alert";	71	import { Alert, AlertAction, AlertDescription, AlertTitle } from "./ui/alert";
71	import {	72	import {
72	BotIcon,	73	BotIcon,
...	@@ -101,13 +102,8 @@ import {	...	@@ -101,13 +102,8 @@ import {
101	} from "~/projectScripts";	102	} from "~/projectScripts";
102	import { Toggle } from "./ui/toggle";	103	import { Toggle } from "./ui/toggle";
103	import { SidebarTrigger } from "./ui/sidebar";	104	import { SidebarTrigger } from "./ui/sidebar";
104	import {	105	import { newCommandId, newMessageId } from "~/lib/orchestrationIds";
105	asApprovalRequestId,	106	import { readNativeApi } from "~/nativeApi";
106	asProjectId,
107	asThreadId,
108	newCommandId,
109	newMessageId,
110	} from "~/lib/orchestrationIds";
111		107
112	function formatMessageMeta(createdAt: string, duration: string \| null): string {	108	function formatMessageMeta(createdAt: string, duration: string \| null): string {
113	if (!duration) return formatTimestamp(createdAt);	109	if (!duration) return formatTimestamp(createdAt);
...	@@ -326,7 +322,7 @@ const ComposerCommandMenu = memo(function ComposerCommandMenu(props: {	...	@@ -326,7 +322,7 @@ const ComposerCommandMenu = memo(function ComposerCommandMenu(props: {
326	});	322	});
327		323
328	interface ChatViewProps {	324	interface ChatViewProps {
329	threadId: string;	325	threadId: ThreadId;
330	}	326	}
331		327
332	export default function ChatView({ threadId }: ChatViewProps) {	328	export default function ChatView({ threadId }: ChatViewProps) {
...	@@ -336,12 +332,9 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -336,12 +332,9 @@ export default function ChatView({ threadId }: ChatViewProps) {
336	strict: false,	332	strict: false,
337	select: (params) => parseDiffRouteSearch(params),	333	select: (params) => parseDiffRouteSearch(params),
338	});	334	});
339	const api = useNativeApi();
340	const { resolvedTheme } = useTheme();	335	const { resolvedTheme } = useTheme();
341	const queryClient = useQueryClient();	336	const queryClient = useQueryClient();
342	const createWorktreeMutation = useMutation(	337	const createWorktreeMutation = useMutation(gitCreateWorktreeMutationOptions({ queryClient }));
343	gitCreateWorktreeMutationOptions({ api, queryClient }),
344	);
345	const [prompt, setPrompt] = useState("");	338	const [prompt, setPrompt] = useState("");
346	const promptRef = useRef(prompt);	339	const promptRef = useRef(prompt);
347	const [composerImages, setComposerImages] = useState<ComposerImageAttachment[]>([]);	340	const [composerImages, setComposerImages] = useState<ComposerImageAttachment[]>([]);
...	@@ -353,7 +346,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -353,7 +346,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
353	const [selectedEffort, setSelectedEffort] = useState(DEFAULT_REASONING);	346	const [selectedEffort, setSelectedEffort] = useState(DEFAULT_REASONING);
354	const [envMode, setEnvMode] = useState<"local" \| "worktree">("local");	347	const [envMode, setEnvMode] = useState<"local" \| "worktree">("local");
355	const [isSwitchingRuntimeMode, setIsSwitchingRuntimeMode] = useState(false);	348	const [isSwitchingRuntimeMode, setIsSwitchingRuntimeMode] = useState(false);
356	const [respondingRequestIds, setRespondingRequestIds] = useState<string[]>([]);	349	const [respondingRequestIds, setRespondingRequestIds] = useState<ApprovalRequestId[]>([]);
357	const [expandedWorkGroups, setExpandedWorkGroups] = useState<Record<string, boolean>>({});	350	const [expandedWorkGroups, setExpandedWorkGroups] = useState<Record<string, boolean>>({});
358	const [nowTick, setNowTick] = useState(() => Date.now());	351	const [nowTick, setNowTick] = useState(() => Date.now());
359	const [terminalFocusRequestId, setTerminalFocusRequestId] = useState(0);	352	const [terminalFocusRequestId, setTerminalFocusRequestId] = useState(0);
...	@@ -429,7 +422,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -429,7 +422,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
429	const { turnDiffSummaries, inferredCheckpointTurnCountByTurnId } =	422	const { turnDiffSummaries, inferredCheckpointTurnCountByTurnId } =
430	useTurnDiffSummaries(activeThread);	423	useTurnDiffSummaries(activeThread);
431	const turnDiffSummaryByAssistantMessageId = useMemo(() => {	424	const turnDiffSummaryByAssistantMessageId = useMemo(() => {
432	const byMessageId = new Map<string, TurnDiffSummary>();	425	const byMessageId = new Map<MessageId, TurnDiffSummary>();
433	for (const summary of turnDiffSummaries) {	426	for (const summary of turnDiffSummaries) {
434	if (!summary.assistantMessageId) continue;	427	if (!summary.assistantMessageId) continue;
435	byMessageId.set(summary.assistantMessageId, summary);	428	byMessageId.set(summary.assistantMessageId, summary);
...	@@ -437,7 +430,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -437,7 +430,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
437	return byMessageId;	430	return byMessageId;
438	}, [turnDiffSummaries]);	431	}, [turnDiffSummaries]);
439	const revertTurnCountByUserMessageId = useMemo(() => {	432	const revertTurnCountByUserMessageId = useMemo(() => {
440	const byUserMessageId = new Map<string, number>();	433	const byUserMessageId = new Map<MessageId, number>();
441	for (let index = 0; index < timelineEntries.length; index += 1) {	434	for (let index = 0; index < timelineEntries.length; index += 1) {
442	const entry = timelineEntries[index];	435	const entry = timelineEntries[index];
443	if (!entry \|\| entry.kind !== "message" \|\| entry.message.role !== "user") {	436	if (!entry \|\| entry.kind !== "message" \|\| entry.message.role !== "user") {
...	@@ -536,14 +529,13 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -536,14 +529,13 @@ export default function ChatView({ threadId }: ChatViewProps) {
536	(debouncerState) => ({ isPending: debouncerState.isPending }),	529	(debouncerState) => ({ isPending: debouncerState.isPending }),
537	);	530	);
538	const effectivePathQuery = pathTriggerQuery.length > 0 ? debouncedPathQuery : "";	531	const effectivePathQuery = pathTriggerQuery.length > 0 ? debouncedPathQuery : "";
539	const branchesQuery = useQuery(gitBranchesQueryOptions(api, gitCwd));	532	const branchesQuery = useQuery(gitBranchesQueryOptions(gitCwd));
540	const keybindingsQuery = useQuery({	533	const keybindingsQuery = useQuery({
541	...serverConfigQueryOptions(api),	534	...serverConfigQueryOptions(),
542	select: (config) => config.keybindings,	535	select: (config) => config.keybindings,
543	});	536	});
544	const workspaceEntriesQuery = useQuery(	537	const workspaceEntriesQuery = useQuery(
545	projectSearchEntriesQueryOptions({	538	projectSearchEntriesQueryOptions({
546	api,
547	cwd: gitCwd,	539	cwd: gitCwd,
548	query: effectivePathQuery,	540	query: effectivePathQuery,
549	enabled: isPathTrigger,	541	enabled: isPathTrigger,
...	@@ -689,6 +681,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -689,6 +681,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
689	);	681	);
690	const closeTerminal = useCallback(	682	const closeTerminal = useCallback(
691	(terminalId: string) => {	683	(terminalId: string) => {
		684	const api = readNativeApi();
692	if (!activeThreadId \|\| !api) return;	685	if (!activeThreadId \|\| !api) return;
693	const isFinalTerminal = (activeThread?.terminalIds.length ?? 0) <= 1;	686	const isFinalTerminal = (activeThread?.terminalIds.length ?? 0) <= 1;
694	const fallbackExitWrite = () =>	687	const fallbackExitWrite = () =>
...	@@ -714,7 +707,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -714,7 +707,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
714	});	707	});
715	setTerminalFocusRequestId((value) => value + 1);	708	setTerminalFocusRequestId((value) => value + 1);
716	},	709	},
717	[activeThread?.terminalIds.length, activeThreadId, api, dispatch],	710	[activeThread?.terminalIds.length, activeThreadId, dispatch],
718	);	711	);
719	const runProjectScript = useCallback(	712	const runProjectScript = useCallback(
720	async (	713	async (
...	@@ -727,6 +720,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -727,6 +720,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
727	rememberAsLastInvoked?: boolean;	720	rememberAsLastInvoked?: boolean;
728	},	721	},
729	) => {	722	) => {
		723	const api = readNativeApi();
730	if (!api \|\| !activeThreadId \|\| !activeProject \|\| !activeThread) return;	724	if (!api \|\| !activeThreadId \|\| !activeProject \|\| !activeThread) return;
731	if (options?.rememberAsLastInvoked !== false) {	725	if (options?.rememberAsLastInvoked !== false) {
732	setLastInvokedScriptByProjectId((current) => {	726	setLastInvokedScriptByProjectId((current) => {
...	@@ -799,23 +793,24 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -799,23 +793,24 @@ export default function ChatView({ threadId }: ChatViewProps) {
799	});	793	});
800	}	794	}
801	},	795	},
802	[activeProject, activeThread, activeThreadId, api, dispatch, gitCwd],	796	[activeProject, activeThread, activeThreadId, dispatch, gitCwd],
803	);	797	);
804	const persistProjectScripts = useCallback(	798	const persistProjectScripts = useCallback(
805	async (input: {	799	async (input: {
806	projectId: string;	800	projectId: ProjectId;
807	projectCwd: string;	801	projectCwd: string;
808	previousScripts: ProjectScript[];	802	previousScripts: ProjectScript[];
809	nextScripts: ProjectScript[];	803	nextScripts: ProjectScript[];
810	keybinding?: string \| null;	804	keybinding?: string \| null;
811	keybindingCommand: KeybindingCommand;	805	keybindingCommand: KeybindingCommand;
812	}) => {	806	}) => {
		807	const api = readNativeApi();
813	if (!api) return;	808	if (!api) return;
814		809
815	await api.orchestration.dispatchCommand({	810	await api.orchestration.dispatchCommand({
816	type: "project.meta.update",	811	type: "project.meta.update",
817	commandId: newCommandId(),	812	commandId: newCommandId(),
818	projectId: asProjectId(input.projectId),	813	projectId: input.projectId,
819	scripts: input.nextScripts,	814	scripts: input.nextScripts,
820	});	815	});
821		816
...	@@ -836,7 +831,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -836,7 +831,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
836	);	831	);
837	}	832	}
838	},	833	},
839	[api, queryClient],	834	[queryClient],
840	);	835	);
841	const saveProjectScript = useCallback(	836	const saveProjectScript = useCallback(
842	async (input: NewProjectScriptInput) => {	837	async (input: NewProjectScriptInput) => {
...	@@ -911,6 +906,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -911,6 +906,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
911	if (mode === state.runtimeMode) return;	906	if (mode === state.runtimeMode) return;
912	dispatch({ type: "SET_RUNTIME_MODE", mode });	907	dispatch({ type: "SET_RUNTIME_MODE", mode });
913	scheduleComposerFocus();	908	scheduleComposerFocus();
		909	const api = readNativeApi();
914	if (!api) return;	910	if (!api) return;
915		911
916	const runningThreadIds = state.threads	912	const runningThreadIds = state.threads
...	@@ -927,7 +923,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -927,7 +923,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
927	.dispatchCommand({	923	.dispatchCommand({
928	type: "thread.session.stop",	924	type: "thread.session.stop",
929	commandId: newCommandId(),	925	commandId: newCommandId(),
930	threadId: asThreadId(threadId),	926	threadId,
931	createdAt: new Date().toISOString(),	927	createdAt: new Date().toISOString(),
932	})	928	})
933	.catch(() => undefined),	929	.catch(() => undefined),
...	@@ -1182,7 +1178,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1182,7 +1178,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
1182	]);	1178	]);
1183		1179
1184	const setThreadError = useCallback(	1180	const setThreadError = useCallback(
1185	(threadId: string \| null, error: string \| null) => {	1181	(threadId: ThreadId \| null, error: string \| null) => {
1186	if (!threadId) return;	1182	if (!threadId) return;
1187	dispatch({	1183	dispatch({
1188	type: "SET_ERROR",	1184	type: "SET_ERROR",
...	@@ -1298,9 +1294,9 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1298,9 +1294,9 @@ export default function ChatView({ threadId }: ChatViewProps) {
1298		1294
1299	const onRevertToTurnCount = useCallback(	1295	const onRevertToTurnCount = useCallback(
1300	async (turnCount: number) => {	1296	async (turnCount: number) => {
1301	if (!api \|\| !activeThread \|\| isRevertingCheckpoint) {	1297	const api = readNativeApi();
1302	return;	1298	if (!api \|\| !activeThread \|\| isRevertingCheckpoint) return;
1303	}	1299
1304	if (phase === "running" \|\| isSending \|\| isConnecting) {	1300	if (phase === "running" \|\| isSending \|\| isConnecting) {
1305	setThreadError(activeThread.id, "Interrupt the current turn before reverting checkpoints.");	1301	setThreadError(activeThread.id, "Interrupt the current turn before reverting checkpoints.");
1306	return;	1302	return;
...	@@ -1322,7 +1318,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1322,7 +1318,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
1322	await api.orchestration.dispatchCommand({	1318	await api.orchestration.dispatchCommand({
1323	type: "thread.checkpoint.revert",	1319	type: "thread.checkpoint.revert",
1324	commandId: newCommandId(),	1320	commandId: newCommandId(),
1325	threadId: asThreadId(activeThread.id),	1321	threadId: activeThread.id,
1326	turnCount,	1322	turnCount,
1327	createdAt: new Date().toISOString(),	1323	createdAt: new Date().toISOString(),
1328	});	1324	});
...	@@ -1335,11 +1331,12 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1335,11 +1331,12 @@ export default function ChatView({ threadId }: ChatViewProps) {
1335	setIsRevertingCheckpoint(false);	1331	setIsRevertingCheckpoint(false);
1336	}	1332	}
1337	},	1333	},
1338	[activeThread, api, isConnecting, isRevertingCheckpoint, isSending, phase, setThreadError],	1334	[activeThread, isConnecting, isRevertingCheckpoint, isSending, phase, setThreadError],
1339	);	1335	);
1340		1336
1341	const onSend = async (e: React.SubmitEvent \| React.KeyboardEvent) => {	1337	const onSend = async (e: React.SubmitEvent \| React.KeyboardEvent) => {
1342	e.preventDefault();	1338	e.preventDefault();
		1339	const api = readNativeApi();
1343	if (!api \|\| !activeThread \|\| isSending \|\| isConnecting) return;	1340	if (!api \|\| !activeThread \|\| isSending \|\| isConnecting) return;
1344	const trimmed = prompt.trim();	1341	const trimmed = prompt.trim();
1345	if (!trimmed && composerImages.length === 0) return;	1342	if (!trimmed && composerImages.length === 0) return;
...	@@ -1363,7 +1360,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1363,7 +1360,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
1363	await api.orchestration.dispatchCommand({	1360	await api.orchestration.dispatchCommand({
1364	type: "thread.meta.update",	1361	type: "thread.meta.update",
1365	commandId: newCommandId(),	1362	commandId: newCommandId(),
1366	threadId: asThreadId(activeThread.id),	1363	threadId: activeThread.id,
1367	branch: result.worktree.branch,	1364	branch: result.worktree.branch,
1368	worktreePath: result.worktree.path,	1365	worktreePath: result.worktree.path,
1369	});	1366	});
...	@@ -1397,7 +1394,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1397,7 +1394,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
1397	await api.orchestration.dispatchCommand({	1394	await api.orchestration.dispatchCommand({
1398	type: "thread.meta.update",	1395	type: "thread.meta.update",
1399	commandId: newCommandId(),	1396	commandId: newCommandId(),
1400	threadId: asThreadId(activeThread.id),	1397	threadId: activeThread.id,
1401	title,	1398	title,
1402	});	1399	});
1403	}	1400	}
...	@@ -1434,7 +1431,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1434,7 +1431,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
1434	await api.orchestration.dispatchCommand({	1431	await api.orchestration.dispatchCommand({
1435	type: "thread.turn.start",	1432	type: "thread.turn.start",
1436	commandId: newCommandId(),	1433	commandId: newCommandId(),
1437	threadId: asThreadId(activeThread.id),	1434	threadId: activeThread.id,
1438	message: {	1435	message: {
1439	messageId: newMessageId(),	1436	messageId: newMessageId(),
1440	role: "user",	1437	role: "user",
...	@@ -1456,17 +1453,19 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1456,17 +1453,19 @@ export default function ChatView({ threadId }: ChatViewProps) {
1456	};	1453	};
1457		1454
1458	const onInterrupt = async () => {	1455	const onInterrupt = async () => {
		1456	const api = readNativeApi();
1459	if (!api \|\| !activeThread) return;	1457	if (!api \|\| !activeThread) return;
1460	await api.orchestration.dispatchCommand({	1458	await api.orchestration.dispatchCommand({
1461	type: "thread.turn.interrupt",	1459	type: "thread.turn.interrupt",
1462	commandId: newCommandId(),	1460	commandId: newCommandId(),
1463	threadId: asThreadId(activeThread.id),	1461	threadId: activeThread.id,
1464	createdAt: new Date().toISOString(),	1462	createdAt: new Date().toISOString(),
1465	});	1463	});
1466	};	1464	};
1467		1465
1468	const onRespondToApproval = useCallback(	1466	const onRespondToApproval = useCallback(
1469	async (requestId: string, decision: ProviderApprovalDecision) => {	1467	async (requestId: ApprovalRequestId, decision: ProviderApprovalDecision) => {
		1468	const api = readNativeApi();
1470	if (!api \|\| !activeThreadId) return;	1469	if (!api \|\| !activeThreadId) return;
1471		1470
1472	setRespondingRequestIds((existing) =>	1471	setRespondingRequestIds((existing) =>
...	@@ -1476,8 +1475,8 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1476,8 +1475,8 @@ export default function ChatView({ threadId }: ChatViewProps) {
1476	await api.orchestration.dispatchCommand({	1475	await api.orchestration.dispatchCommand({
1477	type: "thread.approval.respond",	1476	type: "thread.approval.respond",
1478	commandId: newCommandId(),	1477	commandId: newCommandId(),
1479	threadId: asThreadId(activeThreadId),	1478	threadId: activeThreadId,
1480	requestId: asApprovalRequestId(requestId),	1479	requestId,
1481	decision,	1480	decision,
1482	createdAt: new Date().toISOString(),	1481	createdAt: new Date().toISOString(),
1483	});	1482	});
...	@@ -1491,23 +1490,24 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1491,23 +1490,24 @@ export default function ChatView({ threadId }: ChatViewProps) {
1491	setRespondingRequestIds((existing) => existing.filter((id) => id !== requestId));	1490	setRespondingRequestIds((existing) => existing.filter((id) => id !== requestId));
1492	}	1491	}
1493	},	1492	},
1494	[activeThreadId, api, dispatch],	1493	[activeThreadId, dispatch],
1495	);	1494	);
1496		1495
1497	const onModelSelect = useCallback(	1496	const onModelSelect = useCallback(
1498	(model: ModelSlug) => {	1497	(model: ModelSlug) => {
		1498	const api = readNativeApi();
1499	if (!activeThread) return;	1499	if (!activeThread) return;
1500	if (api) {	1500	if (api) {
1501	void api.orchestration.dispatchCommand({	1501	void api.orchestration.dispatchCommand({
1502	type: "thread.meta.update",	1502	type: "thread.meta.update",
1503	commandId: newCommandId(),	1503	commandId: newCommandId(),
1504	threadId: asThreadId(activeThread.id),	1504	threadId: activeThread.id,
1505	model: resolveModelSlug(model),	1505	model: resolveModelSlug(model),
1506	});	1506	});
1507	}	1507	}
1508	scheduleComposerFocus();	1508	scheduleComposerFocus();
1509	},	1509	},
1510	[activeThread, api, scheduleComposerFocus],	1510	[activeThread, scheduleComposerFocus],
1511	);	1511	);
1512	const onEffortSelect = useCallback(	1512	const onEffortSelect = useCallback(
1513	(effort: ReasoningEffort) => {	1513	(effort: ReasoningEffort) => {
...	@@ -1629,7 +1629,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1629,7 +1629,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
1629	});	1629	});
1630	}, [diffOpen, navigate, threadId]);	1630	}, [diffOpen, navigate, threadId]);
1631	const onOpenTurnDiff = useCallback(	1631	const onOpenTurnDiff = useCallback(
1632	(turnId: string, filePath?: string) => {	1632	(turnId: TurnId, filePath?: string) => {
1633	void navigate({	1633	void navigate({
1634	to: "/$threadId",	1634	to: "/$threadId",
1635	params: { threadId },	1635	params: { threadId },
...	@@ -1644,7 +1644,7 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1644,7 +1644,7 @@ export default function ChatView({ threadId }: ChatViewProps) {
1644	[navigate, threadId],	1644	[navigate, threadId],
1645	);	1645	);
1646	const onRevertUserMessage = useCallback(	1646	const onRevertUserMessage = useCallback(
1647	(messageId: string) => {	1647	(messageId: MessageId) => {
1648	const targetTurnCount = revertTurnCountByUserMessageId.get(messageId);	1648	const targetTurnCount = revertTurnCountByUserMessageId.get(messageId);
1649	if (typeof targetTurnCount !== "number") {	1649	if (typeof targetTurnCount !== "number") {
1650	return;	1650	return;
...	@@ -1698,7 +1698,6 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1698,7 +1698,6 @@ export default function ChatView({ threadId }: ChatViewProps) {
1698	activeProject ? (lastInvokedScriptByProjectId[activeProject.id] ?? null) : null	1698	activeProject ? (lastInvokedScriptByProjectId[activeProject.id] ?? null) : null
1699	}	1699	}
1700	keybindings={keybindings}	1700	keybindings={keybindings}
1701	api={api}
1702	gitCwd={gitCwd}	1701	gitCwd={gitCwd}
1703	diffOpen={diffOpen}	1702	diffOpen={diffOpen}
1704	onRunProjectScript={(script) => {	1703	onRunProjectScript={(script) => {
...	@@ -1971,35 +1970,39 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -1971,35 +1970,39 @@ export default function ChatView({ threadId }: ChatViewProps) {
1971	/>	1970	/>
1972	)}	1971	)}
1973		1972
1974	{activeThread.terminalOpen && api && activeProject && (	1973	{(() => {
1975	<ThreadTerminalDrawer	1974	if (!activeThread.terminalOpen \|\| !activeProject) {
1976	key={activeThread.id}	1975	return null;
1977	api={api}	1976	}
1978	threadId={activeThread.id}	1977	return (
1979	cwd={gitCwd ?? activeProject.cwd}	1978	<ThreadTerminalDrawer
1980	runtimeEnv={threadTerminalRuntimeEnv}	1979	key={activeThread.id}
1981	height={activeThread.terminalHeight}	1980	threadId={activeThread.id}
1982	terminalIds={activeThread.terminalIds}	1981	cwd={gitCwd ?? activeProject.cwd}
1983	activeTerminalId={activeThread.activeTerminalId}	1982	runtimeEnv={threadTerminalRuntimeEnv}
1984	terminalGroups={activeThread.terminalGroups}	1983	height={activeThread.terminalHeight}
1985	activeTerminalGroupId={activeThread.activeTerminalGroupId}	1984	terminalIds={activeThread.terminalIds}
1986	focusRequestId={terminalFocusRequestId}	1985	activeTerminalId={activeThread.activeTerminalId}
1987	onSplitTerminal={splitTerminal}	1986	terminalGroups={activeThread.terminalGroups}
1988	onNewTerminal={createNewTerminal}	1987	activeTerminalGroupId={activeThread.activeTerminalGroupId}
1989	splitShortcutLabel={splitTerminalShortcutLabel ?? undefined}	1988	focusRequestId={terminalFocusRequestId}
1990	newShortcutLabel={newTerminalShortcutLabel ?? undefined}	1989	onSplitTerminal={splitTerminal}
1991	closeShortcutLabel={closeTerminalShortcutLabel ?? undefined}	1990	onNewTerminal={createNewTerminal}
1992	onActiveTerminalChange={activateTerminal}	1991	splitShortcutLabel={splitTerminalShortcutLabel ?? undefined}
1993	onCloseTerminal={closeTerminal}	1992	newShortcutLabel={newTerminalShortcutLabel ?? undefined}
1994	onHeightChange={(height) =>	1993	closeShortcutLabel={closeTerminalShortcutLabel ?? undefined}
1995	dispatch({	1994	onActiveTerminalChange={activateTerminal}
1996	type: "SET_THREAD_TERMINAL_HEIGHT",	1995	onCloseTerminal={closeTerminal}
1997	threadId: activeThread.id,	1996	onHeightChange={(height) =>
1998	height,	1997	dispatch({
1999	})	1998	type: "SET_THREAD_TERMINAL_HEIGHT",
2000	}	1999	threadId: activeThread.id,
2001	/>	2000	height,
2002	)}	2001	})
		2002	}
		2003	/>
		2004	);
		2005	})()}
2003		2006
2004	{expandedImage && (	2007	{expandedImage && (
2005	<div	2008	<div
...	@@ -2040,13 +2043,12 @@ export default function ChatView({ threadId }: ChatViewProps) {	...	@@ -2040,13 +2043,12 @@ export default function ChatView({ threadId }: ChatViewProps) {
2040	}	2043	}
2041		2044
2042	interface ChatHeaderProps {	2045	interface ChatHeaderProps {
2043	activeThreadId: string;	2046	activeThreadId: ThreadId;
2044	activeThreadTitle: string;	2047	activeThreadTitle: string;
2045	activeProjectName: string \| undefined;	2048	activeProjectName: string \| undefined;
2046	activeProjectScripts: ProjectScript[] \| undefined;	2049	activeProjectScripts: ProjectScript[] \| undefined;
2047	preferredScriptId: string \| null;	2050	preferredScriptId: string \| null;
2048	keybindings: ResolvedKeybindingsConfig;	2051	keybindings: ResolvedKeybindingsConfig;
2049	api: NativeApi \| undefined;
2050	gitCwd: string \| null;	2052	gitCwd: string \| null;
2051	diffOpen: boolean;	2053	diffOpen: boolean;
2052	onRunProjectScript: (script: ProjectScript) => void;	2054	onRunProjectScript: (script: ProjectScript) => void;
...	@@ -2062,7 +2064,6 @@ const ChatHeader = memo(function ChatHeader({	...	@@ -2062,7 +2064,6 @@ const ChatHeader = memo(function ChatHeader({
2062	activeProjectScripts,	2064	activeProjectScripts,
2063	preferredScriptId,	2065	preferredScriptId,
2064	keybindings,	2066	keybindings,
2065	api,
2066	gitCwd,	2067	gitCwd,
2067	diffOpen,	2068	diffOpen,
2068	onRunProjectScript,	2069	onRunProjectScript,
...	@@ -2100,9 +2101,7 @@ const ChatHeader = memo(function ChatHeader({	...	@@ -2100,9 +2101,7 @@ const ChatHeader = memo(function ChatHeader({
2100	{activeProjectName && (	2101	{activeProjectName && (
2101	<OpenInPicker keybindings={keybindings} activeThreadId={activeThreadId} />	2102	<OpenInPicker keybindings={keybindings} activeThreadId={activeThreadId} />
2102	)}	2103	)}
2103	{activeProjectName && (	2104	{activeProjectName && <GitActionsControl gitCwd={gitCwd} activeThreadId={activeThreadId} />}
2104	<GitActionsControl api={api} gitCwd={gitCwd} activeThreadId={activeThreadId} />
2105	)}
2106	<Toggle	2105	<Toggle
2107	className="shrink-0"	2106	className="shrink-0"
2108	pressed={diffOpen}	2107	pressed={diffOpen}
...	@@ -2134,8 +2133,11 @@ const ThreadErrorBanner = memo(function ThreadErrorBanner({ error }: { error: st	...	@@ -2134,8 +2133,11 @@ const ThreadErrorBanner = memo(function ThreadErrorBanner({ error }: { error: st
2134		2133
2135	interface PendingApprovalsPanelProps {	2134	interface PendingApprovalsPanelProps {
2136	pendingApprovals: PendingApproval[];	2135	pendingApprovals: PendingApproval[];
2137	respondingRequestIds: string[];	2136	respondingRequestIds: ApprovalRequestId[];
2138	onRespondToApproval: (requestId: string, decision: ProviderApprovalDecision) => Promise<void>;	2137	onRespondToApproval: (
		2138	requestId: ApprovalRequestId,
		2139	decision: ProviderApprovalDecision,
		2140	) => Promise<void>;
2139	}	2141	}
2140		2142
2141	const PendingApprovalsPanel = memo(function PendingApprovalsPanel({	2143	const PendingApprovalsPanel = memo(function PendingApprovalsPanel({
...	@@ -2211,13 +2213,13 @@ interface MessagesTimelineProps {	...	@@ -2211,13 +2213,13 @@ interface MessagesTimelineProps {
2211	timelineEntries: ReturnType<typeof deriveTimelineEntries>;	2213	timelineEntries: ReturnType<typeof deriveTimelineEntries>;
2212	completionDividerBeforeEntryId: string \| null;	2214	completionDividerBeforeEntryId: string \| null;
2213	completionSummary: string \| null;	2215	completionSummary: string \| null;
2214	turnDiffSummaryByAssistantMessageId: Map<string, TurnDiffSummary>;	2216	turnDiffSummaryByAssistantMessageId: Map<MessageId, TurnDiffSummary>;
2215	nowIso: string;	2217	nowIso: string;
2216	expandedWorkGroups: Record<string, boolean>;	2218	expandedWorkGroups: Record<string, boolean>;
2217	onToggleWorkGroup: (groupId: string) => void;	2219	onToggleWorkGroup: (groupId: string) => void;
2218	onOpenTurnDiff: (turnId: string, filePath?: string) => void;	2220	onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
2219	revertTurnCountByUserMessageId: Map<string, number>;	2221	revertTurnCountByUserMessageId: Map<MessageId, number>;
2220	onRevertUserMessage: (messageId: string) => void;	2222	onRevertUserMessage: (messageId: MessageId) => void;
2221	isRevertingCheckpoint: boolean;	2223	isRevertingCheckpoint: boolean;
2222	onImageExpand: (image: ExpandedImagePreview) => void;	2224	onImageExpand: (image: ExpandedImagePreview) => void;
2223	markdownCwd: string \| undefined;	2225	markdownCwd: string \| undefined;
...	@@ -2667,7 +2669,7 @@ const OpenInPicker = memo(function OpenInPicker({	...	@@ -2667,7 +2669,7 @@ const OpenInPicker = memo(function OpenInPicker({
2667	activeThreadId,	2669	activeThreadId,
2668	}: {	2670	}: {
2669	keybindings: ResolvedKeybindingsConfig;	2671	keybindings: ResolvedKeybindingsConfig;
2670	activeThreadId: string \| null;	2672	activeThreadId: ThreadId \| null;
2671	}) {	2673	}) {
2672	const [lastEditor, setLastEditor] = useState<EditorId>(() => {	2674	const [lastEditor, setLastEditor] = useState<EditorId>(() => {
2673	const stored = localStorage.getItem(LAST_EDITOR_KEY);	2675	const stored = localStorage.getItem(LAST_EDITOR_KEY);
...	@@ -2692,13 +2694,13 @@ const OpenInPicker = memo(function OpenInPicker({	...	@@ -2692,13 +2694,13 @@ const OpenInPicker = memo(function OpenInPicker({
2692	] satisfies { label: string; Icon: Icon; value: EditorId }[];	2694	] satisfies { label: string; Icon: Icon; value: EditorId }[];
2693	const primaryOption = options.find(({ value }) => value === lastEditor);	2695	const primaryOption = options.find(({ value }) => value === lastEditor);
2694		2696
2695	const api = useNativeApi();
2696	const { state } = useStore();	2697	const { state } = useStore();
2697	const activeThread = state.threads.find((t) => t.id === activeThreadId);	2698	const activeThread = state.threads.find((t) => t.id === activeThreadId);
2698	const activeProject = state.projects.find((p) => p.id === activeThread?.projectId);	2699	const activeProject = state.projects.find((p) => p.id === activeThread?.projectId);
2699		2700
2700	const openInEditor = useCallback(	2701	const openInEditor = useCallback(
2701	(editorId: EditorId \| null) => {	2702	(editorId: EditorId \| null) => {
		2703	const api = readNativeApi();
2702	if (!api \|\| !activeProject) return;	2704	if (!api \|\| !activeProject) return;
2703	const editor = editorId ?? lastEditor;	2705	const editor = editorId ?? lastEditor;
2704	const cwd = activeThread?.worktreePath ?? activeProject.cwd;	2706	const cwd = activeThread?.worktreePath ?? activeProject.cwd;
...	@@ -2706,7 +2708,7 @@ const OpenInPicker = memo(function OpenInPicker({	...	@@ -2706,7 +2708,7 @@ const OpenInPicker = memo(function OpenInPicker({
2706	localStorage.setItem(LAST_EDITOR_KEY, editor);	2708	localStorage.setItem(LAST_EDITOR_KEY, editor);
2707	setLastEditor(editor);	2709	setLastEditor(editor);
2708	},	2710	},
2709	[api, activeProject, activeThread, lastEditor, setLastEditor],	2711	[activeProject, activeThread, lastEditor, setLastEditor],
2710	);	2712	);
2711		2713
2712	const openFavoriteEditorShortcutLabel = useMemo(	2714	const openFavoriteEditorShortcutLabel = useMemo(
...	@@ -2716,6 +2718,7 @@ const OpenInPicker = memo(function OpenInPicker({	...	@@ -2716,6 +2718,7 @@ const OpenInPicker = memo(function OpenInPicker({
2716		2718
2717	useEffect(() => {	2719	useEffect(() => {
2718	const handler = (e: globalThis.KeyboardEvent) => {	2720	const handler = (e: globalThis.KeyboardEvent) => {
		2721	const api = readNativeApi();
2719	if (!isOpenFavoriteEditorShortcut(e, keybindings)) return;	2722	if (!isOpenFavoriteEditorShortcut(e, keybindings)) return;
2720	if (!api \|\| !activeProject) return;	2723	if (!api \|\| !activeProject) return;
2721		2724
...	@@ -2725,7 +2728,7 @@ const OpenInPicker = memo(function OpenInPicker({	...	@@ -2725,7 +2728,7 @@ const OpenInPicker = memo(function OpenInPicker({
2725	};	2728	};
2726	window.addEventListener("keydown", handler);	2729	window.addEventListener("keydown", handler);
2727	return () => window.removeEventListener("keydown", handler);	2730	return () => window.removeEventListener("keydown", handler);
2728	}, [api, activeProject, activeThread, keybindings, lastEditor]);	2731	}, [activeProject, activeThread, keybindings, lastEditor]);
2729		2732
2730	return (	2733	return (
2731	<Group aria-label="Subscription actions">	2734	<Group aria-label="Subscription actions">

apps/web/src/components/DiffPanel.tsx+8-11

 @@ -2,13 +2,13 @@ import { parsePatchFiles } from "@pierre/diffs";
 import { FileDiff, type FileDiffMetadata, Virtualizer } from "@pierre/diffs/react";
 import { useQuery } from "@tanstack/react-query";
 import { useNavigate, useParams, useSearch } from "@tanstack/react-router";
+import { ThreadId, type TurnId } from "@t3tools/contracts";
 import { ChevronLeftIcon, ChevronRightIcon, Columns2Icon, Rows3Icon } from "lucide-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { checkpointDiffQueryOptions } from "~/lib/providerReactQuery";
 import { cn } from "~/lib/utils";
 import { parseDiffRouteSearch, stripDiffSearchParams } from "../diffRouteSearch";
 import { isElectron } from "../env";
-import { useNativeApi } from "../hooks/useNativeApi";
 import { useTheme } from "../hooks/useTheme";
 import { buildPatchCacheKey } from "../lib/diffRendering";
 import { useTurnDiffSummaries } from "../hooks/useTurnDiffSummaries";
 @@ -81,7 +81,6 @@ interface DiffPanelProps {
 export { DiffWorkerPoolProvider } from "./DiffWorkerPoolProvider";
 export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
-  const api = useNativeApi();
   const navigate = useNavigate();
   const { resolvedTheme } = useTheme();
   const { state } = useStore();
 @@ -90,13 +89,11 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
   const turnStripRef = useRef<HTMLDivElement>(null);
   const [canScrollTurnStripLeft, setCanScrollTurnStripLeft] = useState(false);
   const [canScrollTurnStripRight, setCanScrollTurnStripRight] = useState(false);
-  const params = useParams({ strict: false });
+  const routeThreadId = useParams({
-  const rawSearch = useSearch({ strict: false });
+    strict: false,
-  const routeThreadId = typeof params.threadId === "string" ? params.threadId : null;
+    select: (params) => (params.threadId ? ThreadId.makeUnsafe(params.threadId) : null),
-  const diffSearch = useMemo(
+  });
-    () => parseDiffRouteSearch(rawSearch as Record<string, unknown>),
+  const diffSearch = useSearch({ strict: false, select: (search) => parseDiffRouteSearch(search) });
-    [rawSearch],
-  );
   const activeThreadId = routeThreadId;
   const activeThread = state.threads.find((thread) => thread.id === activeThreadId);
   const { turnDiffSummaries, inferredCheckpointTurnCountByTurnId } =
 @@ -169,7 +166,7 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
     return `conversation:${orderedTurnDiffSummaries.map((summary) => summary.turnId).join(",")}`;
   }, [orderedTurnDiffSummaries, selectedTurn]);
   const activeCheckpointDiffQuery = useQuery(
-    checkpointDiffQueryOptions(api, {
+    checkpointDiffQueryOptions({
       threadId: activeThreadId,
       fromTurnCount: activeCheckpointRange?.fromTurnCount ?? null,
       toTurnCount: activeCheckpointRange?.toTurnCount ?? null,
 @@ -216,7 +213,7 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
     target?.scrollIntoView({ block: "nearest" });
   }, [selectedFilePath, renderableFiles]);
-  const selectTurn = (turnId: string) => {
+  const selectTurn = (turnId: TurnId) => {
     if (!activeThread) return;
     void navigate({
       to: "/$threadId",

apps/web/src/components/GitActionsControl.tsx+19-17

...	@@ -1,4 +1,4 @@	...	@@ -1,4 +1,4 @@
1	import { type GitStatusResult, type GitStackedAction, type NativeApi } from "@t3tools/contracts";	1	import { type GitStatusResult, type GitStackedAction, type ThreadId } from "@t3tools/contracts";
2	import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";	2	import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
3	import { useCallback, useEffect, useMemo, useState } from "react";	3	import { useCallback, useEffect, useMemo, useState } from "react";
4	import { ChevronDownIcon, CloudUploadIcon, GitCommitIcon, InfoIcon } from "lucide-react";	4	import { ChevronDownIcon, CloudUploadIcon, GitCommitIcon, InfoIcon } from "lucide-react";
...	@@ -39,11 +39,11 @@ import {	...	@@ -39,11 +39,11 @@ import {
39	invalidateGitQueries,	39	invalidateGitQueries,
40	} from "~/lib/gitReactQuery";	40	} from "~/lib/gitReactQuery";
41	import { preferredTerminalEditor, resolvePathLinkTarget } from "~/terminal-links";	41	import { preferredTerminalEditor, resolvePathLinkTarget } from "~/terminal-links";
		42	import { readNativeApi } from "~/nativeApi";
42		43
43	interface GitActionsControlProps {	44	interface GitActionsControlProps {
44	api: NativeApi \| undefined;
45	gitCwd: string \| null;	45	gitCwd: string \| null;
46	activeThreadId: string \| null;	46	activeThreadId: ThreadId \| null;
47	}	47	}
48		48
49	function getMenuActionDisabledReason(	49	function getMenuActionDisabledReason(
...	@@ -136,7 +136,7 @@ function GitQuickActionIcon({ quickAction }: { quickAction: GitQuickAction }) {	...	@@ -136,7 +136,7 @@ function GitQuickActionIcon({ quickAction }: { quickAction: GitQuickAction }) {
136	return <InfoIcon className={iconClassName} />;	136	return <InfoIcon className={iconClassName} />;
137	}	137	}
138		138
139	export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitActionsControlProps) {	139	export default function GitActionsControl({ gitCwd, activeThreadId }: GitActionsControlProps) {
140	const threadToastData = useMemo(	140	const threadToastData = useMemo(
141	() => (activeThreadId ? { threadId: activeThreadId } : undefined),	141	() => (activeThreadId ? { threadId: activeThreadId } : undefined),
142	[activeThreadId],	142	[activeThreadId],
...	@@ -145,11 +145,9 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -145,11 +145,9 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
145	const [activeDialogAction, setActiveDialogAction] = useState<GitDialogAction \| null>(null);	145	const [activeDialogAction, setActiveDialogAction] = useState<GitDialogAction \| null>(null);
146	const [dialogCommitMessage, setDialogCommitMessage] = useState("");	146	const [dialogCommitMessage, setDialogCommitMessage] = useState("");
147		147
148	const { data: gitStatus = null, error: gitStatusError } = useQuery(	148	const { data: gitStatus = null, error: gitStatusError } = useQuery(gitStatusQueryOptions(gitCwd));
149	gitStatusQueryOptions(api, gitCwd),
150	);
151		149
152	const { data: branchList = null } = useQuery(gitBranchesQueryOptions(api, gitCwd));	150	const { data: branchList = null } = useQuery(gitBranchesQueryOptions(gitCwd));
153	// Default to true while loading so we don't flash init controls.	151	// Default to true while loading so we don't flash init controls.
154	const isRepo = branchList?.isRepo ?? true;	152	const isRepo = branchList?.isRepo ?? true;
155	const currentBranch = branchList?.branches.find((branch) => branch.current)?.name ?? null;	153	const currentBranch = branchList?.branches.find((branch) => branch.current)?.name ?? null;
...	@@ -163,12 +161,12 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -163,12 +161,12 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
163		161
164	const gitStatusForActions = isGitStatusOutOfSync ? null : gitStatus;	162	const gitStatusForActions = isGitStatusOutOfSync ? null : gitStatus;
165		163
166	const initMutation = useMutation(gitInitMutationOptions({ api, cwd: gitCwd, queryClient }));	164	const initMutation = useMutation(gitInitMutationOptions({ cwd: gitCwd, queryClient }));
167		165
168	const runImmediateGitActionMutation = useMutation(	166	const runImmediateGitActionMutation = useMutation(
169	gitRunStackedActionMutationOptions({ api, cwd: gitCwd, queryClient }),	167	gitRunStackedActionMutationOptions({ cwd: gitCwd, queryClient }),
170	);	168	);
171	const pullMutation = useMutation(gitPullMutationOptions({ api, cwd: gitCwd, queryClient }));	169	const pullMutation = useMutation(gitPullMutationOptions({ cwd: gitCwd, queryClient }));
172		170
173	const isGitActionRunning = runImmediateGitActionMutation.isPending \|\| pullMutation.isPending;	171	const isGitActionRunning = runImmediateGitActionMutation.isPending \|\| pullMutation.isPending;
174	const isDefaultBranch = useMemo(() => {	172	const isDefaultBranch = useMemo(() => {
...	@@ -192,6 +190,7 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -192,6 +190,7 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
192		190
193	const maybeConfirmPushToDefaultBranch = useCallback(	191	const maybeConfirmPushToDefaultBranch = useCallback(
194	async (action: GitStackedAction): Promise<boolean> => {	192	async (action: GitStackedAction): Promise<boolean> => {
		193	const api = readNativeApi();
195	if (!api) return false;	194	if (!api) return false;
196	if (	195	if (
197	!requiresDefaultBranchConfirmation(action, isDefaultBranch) \|\|	196	!requiresDefaultBranchConfirmation(action, isDefaultBranch) \|\|
...	@@ -203,10 +202,11 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -203,10 +202,11 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
203	`You're about to push to the default branch "${gitStatusForActions.branch}". Continue?`,	202	`You're about to push to the default branch "${gitStatusForActions.branch}". Continue?`,
204	);	203	);
205	},	204	},
206	[api, gitStatusForActions?.branch, isDefaultBranch],	205	[gitStatusForActions?.branch, isDefaultBranch],
207	);	206	);
208		207
209	const openExistingPr = useCallback(async () => {	208	const openExistingPr = useCallback(async () => {
		209	const api = readNativeApi();
210	if (!api) {	210	if (!api) {
211	toastManager.add({	211	toastManager.add({
212	type: "error",	212	type: "error",
...	@@ -232,8 +232,7 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -232,8 +232,7 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
232	data: threadToastData,	232	data: threadToastData,
233	});	233	});
234	});	234	});
235	}, [api, gitStatusForActions?.openPr?.url, threadToastData]);	235	}, [gitStatusForActions?.openPr?.url, threadToastData]);
236
237	const runGitActionWithToast = useCallback(	236	const runGitActionWithToast = useCallback(
238	async ({	237	async ({
239	action,	238	action,
...	@@ -329,8 +328,10 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -329,8 +328,10 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
329	actionProps: {	328	actionProps: {
330	children: "Open PR",	329	children: "Open PR",
331	onClick: () => {	330	onClick: () => {
		331	const api = readNativeApi();
		332	if (!api) return;
332	closeResultToast();	333	closeResultToast();
333	void api?.shell.openExternal(prUrl);	334	void api.shell.openExternal(prUrl);
334	},	335	},
335	},	336	},
336	}	337	}
...	@@ -356,8 +357,8 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -356,8 +357,8 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
356	});	357	});
357	}	358	}
358	},	359	},
		360
359	[	361	[
360	api,
361	gitStatusForActions?.branch,	362	gitStatusForActions?.branch,
362	gitStatusForActions?.hasWorkingTreeChanges,	363	gitStatusForActions?.hasWorkingTreeChanges,
363	gitStatusForActions?.openPr?.url,	364	gitStatusForActions?.openPr?.url,
...	@@ -447,6 +448,7 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -447,6 +448,7 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
447		448
448	const openChangedFileInEditor = useCallback(	449	const openChangedFileInEditor = useCallback(
449	(filePath: string) => {	450	(filePath: string) => {
		451	const api = readNativeApi();
450	if (!api \|\| !gitCwd) {	452	if (!api \|\| !gitCwd) {
451	toastManager.add({	453	toastManager.add({
452	type: "error",	454	type: "error",
...	@@ -465,7 +467,7 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc	...	@@ -465,7 +467,7 @@ export default function GitActionsControl({ api, gitCwd, activeThreadId }: GitAc
465	});	467	});
466	});	468	});
467	},	469	},
468	[api, gitCwd, threadToastData],	470	[gitCwd, threadToastData],
469	);	471	);
470		472
471	if (!gitCwd) return null;	473	if (!gitCwd) return null;

apps/web/src/components/Sidebar.tsx+34-40

 @@ -1,25 +1,23 @@
 import { ChevronRightIcon, TerminalIcon } from "lucide-react";
 import { useCallback, useEffect, useMemo, useState } from "react";
-import type { ResolvedKeybindingsConfig } from "@t3tools/contracts";
+import {
+  DEFAULT_MODEL,
+  ProjectId,
+  ThreadId,
+  type ResolvedKeybindingsConfig,
+} from "@t3tools/contracts";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useParams } from "@tanstack/react-router";
 import { useAppSettings } from "../appSettings";
 import { isElectron } from "../env";
 import { APP_STAGE_LABEL } from "../branding";
-import { DEFAULT_MODEL } from "../model-logic";
+import { newCommandId, newProjectId, newThreadId } from "../lib/orchestrationIds";
-import {
-  asProjectId,
-  asThreadId,
-  newCommandId,
-  newProjectId,
-  newThreadId,
-} from "../lib/orchestrationIds";
 import { useStore } from "../store";
 import { isChatNewLocalShortcut, isChatNewShortcut } from "../keybindings";
 import { type Thread } from "../types";
-import { useNativeApi } from "../hooks/useNativeApi";
 import { gitRemoveWorktreeMutationOptions } from "../lib/gitReactQuery";
 import { serverConfigQueryOptions } from "../lib/serverReactQuery";
+import { readNativeApi } from "../nativeApi";
 import { toastManager } from "./ui/toast";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "./ui/collapsible";
 import {
 @@ -37,6 +35,7 @@ import {
   SidebarTrigger,
 } from "./ui/sidebar";
 import { formatWorktreePathForDisplay, getOrphanedWorktreePathForThread } from "../worktreeCleanup";
+import { isNonEmpty as isNonEmptyString } from "effect/String";
 const EMPTY_KEYBINDINGS: ResolvedKeybindingsConfig = [];
 @@ -143,33 +142,33 @@ function T3Wordmark() {
 export default function Sidebar() {
   const { state, dispatch } = useStore();
-  const api = useNativeApi();
   const navigate = useNavigate();
   const { settings: appSettings } = useAppSettings();
-  const params = useParams({ strict: false });
+  const routeThreadId = useParams({
-  const routeThreadId = typeof params.threadId === "string" ? params.threadId : null;
+    strict: false,
+    select: (params) => (params.threadId ? ThreadId.makeUnsafe(params.threadId) : null),
+  });
   const { data: keybindings = EMPTY_KEYBINDINGS } = useQuery({
-    ...serverConfigQueryOptions(api),
+    ...serverConfigQueryOptions(),
     select: (config) => config.keybindings,
   });
   const queryClient = useQueryClient();
-  const removeWorktreeMutation = useMutation(
+  const removeWorktreeMutation = useMutation(gitRemoveWorktreeMutationOptions({ queryClient }));
-    gitRemoveWorktreeMutationOptions({ api, queryClient }),
-  );
   const [addingProject, setAddingProject] = useState(false);
   const [newCwd, setNewCwd] = useState("");
   const [isPickingFolder, setIsPickingFolder] = useState(false);
   const [isAddingProject, setIsAddingProject] = useState(false);
-  const pendingApprovalByThreadId = useMemo(() => new Map<string, boolean>(), []);
+  const pendingApprovalByThreadId = useMemo(() => new Map<ThreadId, boolean>(), []);
   const handleNewThread = useCallback(
     (
-      projectId: string,
+      projectId: ProjectId,
       options?: {
         branch?: string | null;
         worktreePath?: string | null;
       },
     ): Promise<void> => {
+      const api = readNativeApi();
       if (!api) return Promise.resolve();
       const threadId = newThreadId();
       const createdAt = new Date().toISOString();
 @@ -180,7 +179,7 @@ export default function Sidebar() {
           type: "thread.create",
           commandId: newCommandId(),
           threadId,
-          projectId: asProjectId(projectId),
+          projectId,
           title: "New thread",
           model,
           branch: options?.branch ?? null,
 @@ -202,11 +201,11 @@ export default function Sidebar() {
         });
       })();
     },
-    [api, dispatch, navigate, state.projects],
+    [dispatch, navigate, state.projects],
   );
   const focusMostRecentThreadForProject = useCallback(
-    (projectId: string) => {
+    (projectId: ProjectId) => {
       const latestThread = state.threads
         .filter((thread) => thread.projectId === projectId)
         .toSorted((a, b) => {
 @@ -228,6 +227,7 @@ export default function Sidebar() {
     async (rawCwd: string) => {
       const cwd = rawCwd.trim();
       if (!cwd || isAddingProject) return;
+      const api = readNativeApi();
       setIsAddingProject(true);
       try {
 @@ -240,7 +240,7 @@ export default function Sidebar() {
         const projectId = newProjectId();
         const createdAt = new Date().toISOString();
-        const title = cwd.split(/[/\\]/).filter(Boolean).at(-1) ?? cwd;
+        const title = cwd.split(/[/\\]/).findLast(isNonEmptyString) ?? cwd;
         await api.orchestration.dispatchCommand({
           type: "project.create",
           commandId: newCommandId(),
 @@ -257,14 +257,7 @@ export default function Sidebar() {
         setAddingProject(false);
       }
     },
-    [
+    [focusMostRecentThreadForProject, handleNewThread, isAddingProject, state.projects],
-      api,
-      focusMostRecentThreadForProject,
-      handleNewThread,
-      isAddingProject,
-      state.projects,
-      state.threads,
-    ],
   );
   const handleAddProject = () => {
 @@ -272,6 +265,7 @@ export default function Sidebar() {
   };
   const handlePickFolder = async () => {
+    const api = readNativeApi();
     if (!api || isPickingFolder) return;
     setIsPickingFolder(true);
     try {
 @@ -284,7 +278,8 @@ export default function Sidebar() {
   };
   const handleThreadContextMenu = useCallback(
-    async (threadId: string, position: { x: number; y: number }) => {
+    async (threadId: ThreadId, position: { x: number; y: number }) => {
+      const api = readNativeApi();
       if (!api) return;
       const clicked = await api.contextMenu.show([{ id: "delete", label: "Delete" }], position);
       if (clicked !== "delete") return;
 @@ -324,7 +319,7 @@ export default function Sidebar() {
           .dispatchCommand({
             type: "thread.session.stop",
             commandId: newCommandId(),
-            threadId: asThreadId(threadId),
+            threadId,
             createdAt: new Date().toISOString(),
           })
           .catch(() => undefined);
 @@ -344,7 +339,7 @@ export default function Sidebar() {
       await api.orchestration.dispatchCommand({
         type: "thread.delete",
         commandId: newCommandId(),
-        threadId: asThreadId(threadId),
+        threadId,
       });
       if (shouldNavigateToFallback) {
         if (fallbackThreadId) {
 @@ -384,9 +379,7 @@ export default function Sidebar() {
       }
     },
     [
-      api,
       appSettings.confirmThreadDelete,
-      dispatch,
       navigate,
       removeWorktreeMutation,
       routeThreadId,
 @@ -396,7 +389,8 @@ export default function Sidebar() {
   );
   const handleProjectContextMenu = useCallback(
-    async (projectId: string, position: { x: number; y: number }) => {
+    async (projectId: ProjectId, position: { x: number; y: number }) => {
+      const api = readNativeApi();
       if (!api) return;
       const clicked = await api.contextMenu.show([{ id: "delete", label: "Delete" }], position);
       if (clicked !== "delete") return;
 @@ -423,7 +417,7 @@ export default function Sidebar() {
         await api.orchestration.dispatchCommand({
           type: "project.delete",
           commandId: newCommandId(),
-          projectId: asProjectId(projectId),
+          projectId,
         });
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error deleting project.";
 @@ -435,7 +429,7 @@ export default function Sidebar() {
         });
       }
     },
-    [api, state.projects, state.threads],
+    [state.projects, state.threads],
   );
   useEffect(() => {
 @@ -687,7 +681,7 @@ export default function Sidebar() {
                 if (event.key === "Escape") setAddingProject(false);
               }}
             />
-            {isElectron && api && (
+            {isElectron && (
               <button
                 type="button"
                 className="mb-2 flex w-full items-center justify-center rounded-md border border-border px-2 py-1.5 text-xs text-muted-foreground transition-colors duration-150 hover:bg-secondary disabled:cursor-not-allowed disabled:opacity-60"

apps/web/src/components/ThreadTerminalDrawer.tsx+14-20

...	@@ -1,6 +1,6 @@	...	@@ -1,6 +1,6 @@
1	import { FitAddon } from "@xterm/addon-fit";	1	import { FitAddon } from "@xterm/addon-fit";
2	import { Plus, SquareSplitHorizontal, TerminalSquare, Trash2, XIcon } from "lucide-react";	2	import { Plus, SquareSplitHorizontal, TerminalSquare, Trash2, XIcon } from "lucide-react";
3	import { type NativeApi } from "@t3tools/contracts";	3	import { type ThreadId } from "@t3tools/contracts";
4	import { Terminal, type ITheme } from "@xterm/xterm";	4	import { Terminal, type ITheme } from "@xterm/xterm";
5	import {	5	import {
6	type PointerEvent as ReactPointerEvent,	6	type PointerEvent as ReactPointerEvent,
...	@@ -25,6 +25,7 @@ import {	...	@@ -25,6 +25,7 @@ import {
25	MAX_THREAD_TERMINAL_COUNT,	25	MAX_THREAD_TERMINAL_COUNT,
26	type ThreadTerminalGroup,	26	type ThreadTerminalGroup,
27	} from "../types";	27	} from "../types";
		28	import { readNativeApi } from "~/nativeApi";
28		29
29	const MIN_DRAWER_HEIGHT = 180;	30	const MIN_DRAWER_HEIGHT = 180;
30	const MAX_DRAWER_HEIGHT_RATIO = 0.75;	31	const MAX_DRAWER_HEIGHT_RATIO = 0.75;
...	@@ -107,8 +108,7 @@ function terminalThemeFromApp(): ITheme {	...	@@ -107,8 +108,7 @@ function terminalThemeFromApp(): ITheme {
107	}	108	}
108		109
109	interface TerminalViewportProps {	110	interface TerminalViewportProps {
110	api: NativeApi;	111	threadId: ThreadId;
111	threadId: string;
112	terminalId: string;	112	terminalId: string;
113	cwd: string;	113	cwd: string;
114	runtimeEnv?: Record<string, string>;	114	runtimeEnv?: Record<string, string>;
...	@@ -119,7 +119,6 @@ interface TerminalViewportProps {	...	@@ -119,7 +119,6 @@ interface TerminalViewportProps {
119	}	119	}
120		120
121	function TerminalViewport({	121	function TerminalViewport({
122	api,
123	threadId,	122	threadId,
124	terminalId,	123	terminalId,
125	cwd,	124	cwd,
...	@@ -155,6 +154,9 @@ function TerminalViewport({	...	@@ -155,6 +154,9 @@ function TerminalViewport({
155	terminalRef.current = terminal;	154	terminalRef.current = terminal;
156	fitAddonRef.current = fitAddon;	155	fitAddonRef.current = fitAddon;
157		156
		157	const api = readNativeApi();
		158	if (!api) return;
		159
158	const sendTerminalInput = async (data: string, fallbackError: string) => {	160	const sendTerminalInput = async (data: string, fallbackError: string) => {
159	const activeTerminal = terminalRef.current;	161	const activeTerminal = terminalRef.current;
160	if (!activeTerminal) return;	162	if (!activeTerminal) return;
...	@@ -210,14 +212,10 @@ function TerminalViewport({	...	@@ -210,14 +212,10 @@ function TerminalViewport({
210	end: { x: match.end, y: bufferLineNumber },	212	end: { x: match.end, y: bufferLineNumber },
211	},	213	},
212	activate: (event: MouseEvent) => {	214	activate: (event: MouseEvent) => {
213	if (!isTerminalLinkActivation(event)) {	215	if (!isTerminalLinkActivation(event)) return;
214	return;
215	}
216		216
217	const latestTerminal = terminalRef.current;	217	const latestTerminal = terminalRef.current;
218	if (!latestTerminal) {	218	if (!latestTerminal) return;
219	return;
220	}
221		219
222	if (match.kind === "url") {	220	if (match.kind === "url") {
223	void api.shell.openExternal(match.text).catch((error) => {	221	void api.shell.openExternal(match.text).catch((error) => {
...	@@ -297,7 +295,7 @@ function TerminalViewport({	...	@@ -297,7 +295,7 @@ function TerminalViewport({
297	}	295	}
298	};	296	};
299		297
300	const unsubscribe = api.terminal.onEvent((event) => {	298	const unsubscribe = api?.terminal.onEvent((event) => {
301	if (event.threadId !== threadId \|\| event.terminalId !== terminalId) return;	299	if (event.threadId !== threadId \|\| event.terminalId !== terminalId) return;
302	const activeTerminal = terminalRef.current;	300	const activeTerminal = terminalRef.current;
303	if (!activeTerminal) return;	301	if (!activeTerminal) return;
...	@@ -372,7 +370,7 @@ function TerminalViewport({	...	@@ -372,7 +370,7 @@ function TerminalViewport({
372	fitAddonRef.current = null;	370	fitAddonRef.current = null;
373	terminal.dispose();	371	terminal.dispose();
374	};	372	};
375	}, [api, cwd, runtimeEnv, terminalId, threadId]);	373	}, [cwd, runtimeEnv, terminalId, threadId]);
376		374
377	useEffect(() => {	375	useEffect(() => {
378	if (!autoFocus) return;	376	if (!autoFocus) return;
...	@@ -387,9 +385,10 @@ function TerminalViewport({	...	@@ -387,9 +385,10 @@ function TerminalViewport({
387	}, [autoFocus, focusRequestId]);	385	}, [autoFocus, focusRequestId]);
388		386
389	useEffect(() => {	387	useEffect(() => {
		388	const api = readNativeApi();
390	const terminal = terminalRef.current;	389	const terminal = terminalRef.current;
391	const fitAddon = fitAddonRef.current;	390	const fitAddon = fitAddonRef.current;
392	if (!terminal \|\| !fitAddon) return;	391	if (!api \|\| !terminal \|\| !fitAddon) return;
393	const wasAtBottom = terminal.buffer.active.viewportY >= terminal.buffer.active.baseY;	392	const wasAtBottom = terminal.buffer.active.viewportY >= terminal.buffer.active.baseY;
394	const frame = window.requestAnimationFrame(() => {	393	const frame = window.requestAnimationFrame(() => {
395	fitAddon.fit();	394	fitAddon.fit();
...	@@ -408,14 +407,12 @@ function TerminalViewport({	...	@@ -408,14 +407,12 @@ function TerminalViewport({
408	return () => {	407	return () => {
409	window.cancelAnimationFrame(frame);	408	window.cancelAnimationFrame(frame);
410	};	409	};
411	}, [api, drawerHeight, resizeEpoch, terminalId, threadId]);	410	}, [drawerHeight, resizeEpoch, terminalId, threadId]);
412
413	return <div ref={containerRef} className="h-full w-full overflow-hidden rounded-[4px]" />;	411	return <div ref={containerRef} className="h-full w-full overflow-hidden rounded-[4px]" />;
414	}	412	}
415		413
416	interface ThreadTerminalDrawerProps {	414	interface ThreadTerminalDrawerProps {
417	api: NativeApi;	415	threadId: ThreadId;
418	threadId: string;
419	cwd: string;	416	cwd: string;
420	runtimeEnv?: Record<string, string>;	417	runtimeEnv?: Record<string, string>;
421	height: number;	418	height: number;
...	@@ -464,7 +461,6 @@ function TerminalActionButton({ label, className, onClick, children }: TerminalA	...	@@ -464,7 +461,6 @@ function TerminalActionButton({ label, className, onClick, children }: TerminalA
464	}	461	}
465		462
466	export default function ThreadTerminalDrawer({	463	export default function ThreadTerminalDrawer({
467	api,
468	threadId,	464	threadId,
469	cwd,	465	cwd,
470	runtimeEnv,	466	runtimeEnv,
...	@@ -783,7 +779,6 @@ export default function ThreadTerminalDrawer({	...	@@ -783,7 +779,6 @@ export default function ThreadTerminalDrawer({
783	>	779	>
784	<div className="h-full p-1">	780	<div className="h-full p-1">
785	<TerminalViewport	781	<TerminalViewport
786	api={api}
787	threadId={threadId}	782	threadId={threadId}
788	terminalId={terminalId}	783	terminalId={terminalId}
789	cwd={cwd}	784	cwd={cwd}
...	@@ -801,7 +796,6 @@ export default function ThreadTerminalDrawer({	...	@@ -801,7 +796,6 @@ export default function ThreadTerminalDrawer({
801	<div className="h-full p-1">	796	<div className="h-full p-1">
802	<TerminalViewport	797	<TerminalViewport
803	key={resolvedActiveTerminalId}	798	key={resolvedActiveTerminalId}
804	api={api}
805	threadId={threadId}	799	threadId={threadId}
806	terminalId={resolvedActiveTerminalId}	800	terminalId={resolvedActiveTerminalId}
807	cwd={cwd}	801	cwd={cwd}

apps/web/src/components/ui/command.tsx+4-1

 @@ -133,7 +133,10 @@ function CommandEmpty({ className, ...props }: React.ComponentProps<typeof Autoc
 function CommandPanel({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
-      className="-mx-px not-has-[+[data-slot=command-footer]]:-mb-px relative min-h-0 rounded-t-xl not-has-[+[data-slot=command-footer]]:rounded-b-2xl border border-b-0 bg-popover bg-clip-padding shadow-xs/5 [clip-path:inset(0_1px)] not-has-[+[data-slot=command-footer]]:[clip-path:inset(0_1px_1px_1px_round_0_0_calc(var(--radius-2xl)-1px)_calc(var(--radius-2xl)-1px))] before:pointer-events-none before:absolute before:inset-0 before:rounded-t-[calc(var(--radius-xl)-1px)] **:data-[slot=scroll-area-scrollbar]:mt-2"
+      className={cn(
+        "-mx-px not-has-[+[data-slot=command-footer]]:-mb-px relative min-h-0 rounded-t-xl not-has-[+[data-slot=command-footer]]:rounded-b-2xl border border-b-0 bg-popover bg-clip-padding shadow-xs/5 [clip-path:inset(0_1px)] not-has-[+[data-slot=command-footer]]:[clip-path:inset(0_1px_1px_1px_round_0_0_calc(var(--radius-2xl)-1px)_calc(var(--radius-2xl)-1px))] before:pointer-events-none before:absolute before:inset-0 before:rounded-t-[calc(var(--radius-xl)-1px)] **:data-[slot=scroll-area-scrollbar]:mt-2",
+        className,
+      )}
       {...props}
     />
   );

apps/web/src/components/ui/sheet.tsx+1

...	@@ -49,6 +49,7 @@ function SheetViewport({	...	@@ -49,6 +49,7 @@ function SheetViewport({
49	side === "left" && "flex justify-start",	49	side === "left" && "flex justify-start",
50	side === "right" && "flex justify-end",	50	side === "right" && "flex justify-end",
51	variant === "inset" && "sm:p-4",	51	variant === "inset" && "sm:p-4",
		52	className,
52	)}	53	)}
53	data-slot="sheet-viewport"	54	data-slot="sheet-viewport"
54	{...props}	55	{...props}

apps/web/src/components/ui/toast.tsx+6-4

 @@ -3,6 +3,7 @@
 import { Toast } from "@base-ui/react/toast";
 import { useEffect } from "react";
 import { useParams } from "@tanstack/react-router";
+import { ThreadId } from "@t3tools/contracts";
 import {
   CircleAlertIcon,
   CircleCheckIcon,
 @@ -16,7 +17,7 @@ import { buttonVariants } from "~/components/ui/button";
 import { shouldHideCollapsedToastContent } from "./toast.logic";
 type ThreadToastData = {
-  threadId?: string | null;
+  threadId?: ThreadId | null;
   tooltipStyle?: boolean;
   dismissAfterVisibleMs?: number;
 };
 @@ -48,17 +49,18 @@ interface ToastProviderProps extends Toast.Provider.Props {
 function shouldRenderForActiveThread(
   data: ThreadToastData | undefined,
-  activeThreadId: string | null,
+  activeThreadId: ThreadId | null,
 ): boolean {
   const toastThreadId = data?.threadId;
   if (!toastThreadId) return true;
   return toastThreadId === activeThreadId;
 }
-function useActiveThreadIdFromRoute(): string | null {
+function useActiveThreadIdFromRoute(): ThreadId | null {
   return useParams({
     strict: false,
-    select: (params) => params.threadId ?? null,
+    select: (params) =>
+      typeof params.threadId === "string" ? ThreadId.makeUnsafe(params.threadId) : null,
   });
 }

apps/web/src/diffRouteSearch.ts+5-2

...	@@ -1,6 +1,8 @@	...	@@ -1,6 +1,8 @@
		1	import { TurnId } from "@t3tools/contracts";
		2
1	export interface DiffRouteSearch {	3	export interface DiffRouteSearch {
2	diff?: "1";	4	diff?: "1";
3	diffTurnId?: string;	5	diffTurnId?: TurnId;
4	diffFilePath?: string;	6	diffFilePath?: string;
5	}	7	}
6		8
...	@@ -25,7 +27,8 @@ export function stripDiffSearchParams<T extends Record<string, unknown>>(	...	@@ -25,7 +27,8 @@ export function stripDiffSearchParams<T extends Record<string, unknown>>(
25		27
26	export function parseDiffRouteSearch(search: Record<string, unknown>): DiffRouteSearch {	28	export function parseDiffRouteSearch(search: Record<string, unknown>): DiffRouteSearch {
27	const diff = isDiffOpenValue(search.diff) ? "1" : undefined;	29	const diff = isDiffOpenValue(search.diff) ? "1" : undefined;
28	const diffTurnId = diff ? normalizeSearchString(search.diffTurnId) : undefined;	30	const diffTurnIdRaw = diff ? normalizeSearchString(search.diffTurnId) : undefined;
		31	const diffTurnId = diffTurnIdRaw ? TurnId.makeUnsafe(diffTurnIdRaw) : undefined;
29	const diffFilePath = diff && diffTurnId ? normalizeSearchString(search.diffFilePath) : undefined;	32	const diffFilePath = diff && diffTurnId ? normalizeSearchString(search.diffFilePath) : undefined;
30		33
31	return {	34	return {

apps/web/src/historyBootstrap.test.ts+10-7

 @@ -1,20 +1,23 @@
+import { MessageId } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 import { buildBootstrapInput } from "./historyBootstrap";
+const messageId = (value: string) => MessageId.makeUnsafe(value);
 describe("buildBootstrapInput", () => {
   it("includes full transcript when under budget", () => {
     const result = buildBootstrapInput(
       [
         {
-          id: "u-1",
+          id: messageId("u-1"),
           role: "user",
           text: "hello",
           createdAt: "2026-02-09T00:00:00.000Z",
           streaming: false,
         },
         {
-          id: "a-1",
+          id: messageId("a-1"),
           role: "assistant",
           text: "world",
           createdAt: "2026-02-09T00:00:01.000Z",
 @@ -38,21 +41,21 @@ describe("buildBootstrapInput", () => {
     const result = buildBootstrapInput(
       [
         {
-          id: "u-1",
+          id: messageId("u-1"),
           role: "user",
           text: "first question with details",
           createdAt: "2026-02-09T00:00:00.000Z",
           streaming: false,
         },
         {
-          id: "a-1",
+          id: messageId("a-1"),
           role: "assistant",
           text: "first answer with details",
           createdAt: "2026-02-09T00:00:01.000Z",
           streaming: false,
         },
         {
-          id: "u-2",
+          id: messageId("u-2"),
           role: "user",
           text: "second question with details",
           createdAt: "2026-02-09T00:00:02.000Z",
 @@ -75,7 +78,7 @@ describe("buildBootstrapInput", () => {
     const result = buildBootstrapInput(
       [
         {
-          id: "u-1",
+          id: messageId("u-1"),
           role: "user",
           text: "old context",
           createdAt: "2026-02-09T00:00:00.000Z",
 @@ -96,7 +99,7 @@ describe("buildBootstrapInput", () => {
     const result = buildBootstrapInput(
       [
         {
-          id: "u-image",
+          id: messageId("u-image"),
           role: "user",
           text: "",
           attachments: [

apps/web/src/hooks/useNativeApi.ts deleted-6

...	@@ -1,6 +0,0 @@
1	import { useMemo } from "react";
2	import { readNativeApi } from "../nativeApi";
3
4	export function useNativeApi() {
5	return useMemo(() => readNativeApi(), []);
6	}

apps/web/src/lib/gitReactQuery.ts+36-53

 @@ -1,5 +1,6 @@
-import type { GitStackedAction, NativeApi } from "@t3tools/contracts";
+import type { GitStackedAction } from "@t3tools/contracts";
 import { mutationOptions, queryOptions, type QueryClient } from "@tanstack/react-query";
+import { ensureNativeApi } from "~/nativeApi";
 const GIT_STATUS_STALE_TIME_MS = 5_000;
 const GIT_STATUS_REFETCH_INTERVAL_MS = 15_000;
 @@ -16,16 +17,15 @@ export function invalidateGitQueries(queryClient: QueryClient) {
   return queryClient.invalidateQueries({ queryKey: gitQueryKeys.all });
 }
-export function gitStatusQueryOptions(api: NativeApi | undefined, cwd: string | null) {
+export function gitStatusQueryOptions(cwd: string | null) {
   return queryOptions({
     queryKey: gitQueryKeys.status(cwd),
     queryFn: async () => {
-      if (!api || !cwd) {
+      const api = ensureNativeApi();
-        throw new Error("Git status is unavailable.");
+      if (!cwd) throw new Error("Git status is unavailable.");
-      }
       return api.git.status({ cwd });
     },
-    enabled: !!api && !!cwd,
+    enabled: cwd !== null,
     staleTime: GIT_STATUS_STALE_TIME_MS,
     refetchOnWindowFocus: "always",
     refetchOnReconnect: "always",
 @@ -33,16 +33,15 @@ export function gitStatusQueryOptions(api: NativeApi | undefined, cwd: string |
   });
 }
-export function gitBranchesQueryOptions(api: NativeApi | undefined, cwd: string | null) {
+export function gitBranchesQueryOptions(cwd: string | null) {
   return queryOptions({
     queryKey: gitQueryKeys.branches(cwd),
     queryFn: async () => {
-      if (!api || !cwd) {
+      const api = ensureNativeApi();
-        throw new Error("Git branches are unavailable.");
+      if (!cwd) throw new Error("Git branches are unavailable.");
-      }
       return api.git.listBranches({ cwd });
     },
-    enabled: !!api && !!cwd,
+    enabled: cwd !== null,
     staleTime: GIT_BRANCHES_STALE_TIME_MS,
     refetchOnWindowFocus: true,
     refetchOnReconnect: true,
 @@ -50,15 +49,12 @@ export function gitBranchesQueryOptions(api: NativeApi | undefined, cwd: string
   });
 }
-export function gitInitMutationOptions(input: {
+export function gitInitMutationOptions(input: { cwd: string | null; queryClient: QueryClient }) {
-  api: NativeApi | undefined;
-  cwd: string | null;
-  queryClient: QueryClient;
-}) {
   return mutationOptions({
     mutationFn: async () => {
-      if (!input.api || !input.cwd) throw new Error("Git init is unavailable.");
+      const api = ensureNativeApi();
-      return input.api.git.init({ cwd: input.cwd });
+      if (!input.cwd) throw new Error("Git init is unavailable.");
+      return api.git.init({ cwd: input.cwd });
     },
     onSuccess: async () => {
       await invalidateGitQueries(input.queryClient);
 @@ -67,14 +63,14 @@ export function gitInitMutationOptions(input: {
 }
 export function gitCheckoutMutationOptions(input: {
-  api: NativeApi | undefined;
   cwd: string | null;
   queryClient: QueryClient;
 }) {
   return mutationOptions({
     mutationFn: async (branch: string) => {
-      if (!input.api || !input.cwd) throw new Error("Git checkout is unavailable.");
+      const api = ensureNativeApi();
-      return input.api.git.checkout({ cwd: input.cwd, branch });
+      if (!input.cwd) throw new Error("Git checkout is unavailable.");
+      return api.git.checkout({ cwd: input.cwd, branch });
     },
     onSuccess: async () => {
       await invalidateGitQueries(input.queryClient);
 @@ -83,15 +79,15 @@ export function gitCheckoutMutationOptions(input: {
 }
 export function gitCreateBranchAndCheckoutMutationOptions(input: {
-  api: NativeApi | undefined;
   cwd: string | null;
   queryClient: QueryClient;
 }) {
   return mutationOptions({
     mutationFn: async (branch: string) => {
-      if (!input.api || !input.cwd) throw new Error("Git branch creation is unavailable.");
+      const api = ensureNativeApi();
-      await input.api.git.createBranch({ cwd: input.cwd, branch });
+      if (!input.cwd) throw new Error("Git branch creation is unavailable.");
-      return input.api.git.checkout({ cwd: input.cwd, branch });
+      await api.git.createBranch({ cwd: input.cwd, branch });
+      return api.git.checkout({ cwd: input.cwd, branch });
     },
     onSuccess: async () => {
       await invalidateGitQueries(input.queryClient);
 @@ -100,7 +96,6 @@ export function gitCreateBranchAndCheckoutMutationOptions(input: {
 }
 export function gitRunStackedActionMutationOptions(input: {
-  api: NativeApi | undefined;
   cwd: string | null;
   queryClient: QueryClient;
 }) {
 @@ -112,10 +107,9 @@ export function gitRunStackedActionMutationOptions(input: {
       action: GitStackedAction;
       commitMessage?: string;
     }) => {
-      if (!input.api || !input.cwd) {
+      const api = ensureNativeApi();
-        throw new Error("Git action is unavailable.");
+      if (!input.cwd) throw new Error("Git action is unavailable.");
-      }
+      return api.git.runStackedAction({
-      return input.api.git.runStackedAction({
         cwd: input.cwd,
         action,
         ...(commitMessage ? { commitMessage } : {}),
 @@ -127,15 +121,12 @@ export function gitRunStackedActionMutationOptions(input: {
   });
 }
-export function gitPullMutationOptions(input: {
+export function gitPullMutationOptions(input: { cwd: string | null; queryClient: QueryClient }) {
-  api: NativeApi | undefined;
-  cwd: string | null;
-  queryClient: QueryClient;
-}) {
   return mutationOptions({
     mutationFn: async () => {
-      if (!input.api || !input.cwd) throw new Error("Git pull is unavailable.");
+      const api = ensureNativeApi();
-      return input.api.git.pull({ cwd: input.cwd });
+      if (!input.cwd) throw new Error("Git pull is unavailable.");
+      return api.git.pull({ cwd: input.cwd });
     },
     onSettled: async () => {
       await invalidateGitQueries(input.queryClient);
 @@ -143,10 +134,7 @@ export function gitPullMutationOptions(input: {
   });
 }
-export function gitCreateWorktreeMutationOptions(input: {
+export function gitCreateWorktreeMutationOptions(input: { queryClient: QueryClient }) {
-  api: NativeApi | undefined;
-  queryClient: QueryClient;
-}) {
   return mutationOptions({
     mutationFn: async ({
       cwd,
 @@ -159,10 +147,9 @@ export function gitCreateWorktreeMutationOptions(input: {
       newBranch: string;
       path?: string | null;
     }) => {
-      if (!input.api) {
+      const api = ensureNativeApi();
-        throw new Error("Git worktree creation is unavailable.");
+      if (!cwd) throw new Error("Git worktree creation is unavailable.");
-      }
+      return api.git.createWorktree({ cwd, branch, newBranch, path: path ?? null });
-      return input.api.git.createWorktree({ cwd, branch, newBranch, path: path ?? null });
     },
     onSettled: async () => {
       await invalidateGitQueries(input.queryClient);
 @@ -170,16 +157,12 @@ export function gitCreateWorktreeMutationOptions(input: {
   });
 }
-export function gitRemoveWorktreeMutationOptions(input: {
+export function gitRemoveWorktreeMutationOptions(input: { queryClient: QueryClient }) {
-  api: NativeApi | undefined;
-  queryClient: QueryClient;
-}) {
   return mutationOptions({
     mutationFn: async ({ cwd, path, force }: { cwd: string; path: string; force?: boolean }) => {
-      if (!input.api) {
+      const api = ensureNativeApi();
-        throw new Error("Git worktree removal is unavailable.");
+      if (!cwd) throw new Error("Git worktree removal is unavailable.");
-      }
+      return api.git.removeWorktree({ cwd, path, force });
-      return input.api.git.removeWorktree({ cwd, path, force });
     },
     onSettled: async () => {
       await invalidateGitQueries(input.queryClient);

apps/web/src/lib/orchestrationIds.ts-1

...	@@ -8,7 +8,6 @@ export const newThreadId = (): ThreadId => ThreadId.makeUnsafe(crypto.randomUUID	...	@@ -8,7 +8,6 @@ export const newThreadId = (): ThreadId => ThreadId.makeUnsafe(crypto.randomUUID
8		8
9	export const newMessageId = (): MessageId => MessageId.makeUnsafe(crypto.randomUUID());	9	export const newMessageId = (): MessageId => MessageId.makeUnsafe(crypto.randomUUID());
10		10
11	export const asThreadId = (value: string): ThreadId => ThreadId.makeUnsafe(value);
12		11
13	export const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);	12	export const asProjectId = (value: string): ProjectId => ProjectId.makeUnsafe(value);
14		13

apps/web/src/lib/projectReactQuery.ts+6-5

 @@ -1,5 +1,6 @@
-import type { NativeApi, ProjectSearchEntriesResult } from "@t3tools/contracts";
+import type { ProjectSearchEntriesResult } from "@t3tools/contracts";
 import { queryOptions } from "@tanstack/react-query";
+import { ensureNativeApi } from "~/nativeApi";
 export const projectQueryKeys = {
   all: ["projects"] as const,
 @@ -15,7 +16,6 @@ const EMPTY_SEARCH_ENTRIES_RESULT: ProjectSearchEntriesResult = {
 };
 export function projectSearchEntriesQueryOptions(input: {
-  api: NativeApi | undefined;
   cwd: string | null;
   query: string;
   enabled?: boolean;
 @@ -26,16 +26,17 @@ export function projectSearchEntriesQueryOptions(input: {
   return queryOptions({
     queryKey: projectQueryKeys.searchEntries(input.cwd, input.query, limit),
     queryFn: async () => {
-      if (!input.api || !input.cwd) {
+      const api = ensureNativeApi();
+      if (!input.cwd) {
         throw new Error("Workspace entry search is unavailable.");
       }
-      return input.api.projects.searchEntries({
+      return api.projects.searchEntries({
         cwd: input.cwd,
         query: input.query,
         limit,
       });
     },
-    enabled: (input.enabled ?? true) && Boolean(input.api && input.cwd),
+    enabled: (input.enabled ?? true) && input.cwd !== null,
     staleTime: input.staleTime ?? DEFAULT_SEARCH_ENTRIES_STALE_TIME,
     placeholderData: (previous) => previous ?? EMPTY_SEARCH_ENTRIES_RESULT,
   });

apps/web/src/lib/providerReactQuery.test.ts+57-27

...	@@ -1,12 +1,31 @@	...	@@ -1,12 +1,31 @@
1	import type { NativeApi } from "@t3tools/contracts";	1	import { ThreadId, type NativeApi } from "@t3tools/contracts";
2	import { QueryClient } from "@tanstack/react-query";	2	import { QueryClient } from "@tanstack/react-query";
3	import { describe, expect, it, vi } from "vitest";	3	import { afterEach, describe, expect, it, vi } from "vitest";
4	import { checkpointDiffQueryOptions, providerQueryKeys } from "./providerReactQuery";	4	import { checkpointDiffQueryOptions, providerQueryKeys } from "./providerReactQuery";
		5	import * as nativeApi from "../nativeApi";
		6
		7	const threadId = ThreadId.makeUnsafe("thread-id");
		8
		9	function mockNativeApi(input: {
		10	getTurnDiff: ReturnType<typeof vi.fn>;
		11	getFullThreadDiff: ReturnType<typeof vi.fn>;
		12	}) {
		13	vi.spyOn(nativeApi, "ensureNativeApi").mockReturnValue({
		14	orchestration: {
		15	getTurnDiff: input.getTurnDiff,
		16	getFullThreadDiff: input.getFullThreadDiff,
		17	},
		18	} as unknown as NativeApi);
		19	}
		20
		21	afterEach(() => {
		22	vi.restoreAllMocks();
		23	});
5		24
6	describe("providerQueryKeys.checkpointDiff", () => {	25	describe("providerQueryKeys.checkpointDiff", () => {
7	it("includes cacheScope so reused turn counts do not collide", () => {	26	it("includes cacheScope so reused turn counts do not collide", () => {
8	const baseInput = {	27	const baseInput = {
9	threadId: "thread-id",	28	threadId,
10	fromTurnCount: 1,	29	fromTurnCount: 1,
11	toTurnCount: 2,	30	toTurnCount: 2,
12	} as const;	31	} as const;
...	@@ -29,15 +48,10 @@ describe("checkpointDiffQueryOptions", () => {	...	@@ -29,15 +48,10 @@ describe("checkpointDiffQueryOptions", () => {
29	it("forwards checkpoint range to the provider API", async () => {	48	it("forwards checkpoint range to the provider API", async () => {
30	const getTurnDiff = vi.fn().mockResolvedValue({ diff: "patch" });	49	const getTurnDiff = vi.fn().mockResolvedValue({ diff: "patch" });
31	const getFullThreadDiff = vi.fn().mockResolvedValue({ diff: "patch" });	50	const getFullThreadDiff = vi.fn().mockResolvedValue({ diff: "patch" });
32	const api = {	51	mockNativeApi({ getTurnDiff, getFullThreadDiff });
33	orchestration: {	52
34	getTurnDiff,	53	const options = checkpointDiffQueryOptions({
35	getFullThreadDiff,	54	threadId,
36	},
37	} as unknown as NativeApi;
38
39	const options = checkpointDiffQueryOptions(api, {
40	threadId: "thread-id",
41	fromTurnCount: 3,	55	fromTurnCount: 3,
42	toTurnCount: 4,	56	toTurnCount: 4,
43	cacheScope: "turn:abc",	57	cacheScope: "turn:abc",
...	@@ -47,7 +61,7 @@ describe("checkpointDiffQueryOptions", () => {	...	@@ -47,7 +61,7 @@ describe("checkpointDiffQueryOptions", () => {
47	await queryClient.fetchQuery(options);	61	await queryClient.fetchQuery(options);
48		62
49	expect(getTurnDiff).toHaveBeenCalledWith({	63	expect(getTurnDiff).toHaveBeenCalledWith({
50	threadId: "thread-id",	64	threadId,
51	fromTurnCount: 3,	65	fromTurnCount: 3,
52	toTurnCount: 4,	66	toTurnCount: 4,
53	});	67	});
...	@@ -57,15 +71,10 @@ describe("checkpointDiffQueryOptions", () => {	...	@@ -57,15 +71,10 @@ describe("checkpointDiffQueryOptions", () => {
57	it("uses explicit full thread diff API when range starts from zero", async () => {	71	it("uses explicit full thread diff API when range starts from zero", async () => {
58	const getTurnDiff = vi.fn().mockResolvedValue({ diff: "patch" });	72	const getTurnDiff = vi.fn().mockResolvedValue({ diff: "patch" });
59	const getFullThreadDiff = vi.fn().mockResolvedValue({ diff: "patch" });	73	const getFullThreadDiff = vi.fn().mockResolvedValue({ diff: "patch" });
60	const api = {	74	mockNativeApi({ getTurnDiff, getFullThreadDiff });
61	orchestration: {	75
62	getTurnDiff,	76	const options = checkpointDiffQueryOptions({
63	getFullThreadDiff,	77	threadId,
64	},
65	} as unknown as NativeApi;
66
67	const options = checkpointDiffQueryOptions(api, {
68	threadId: "thread-id",
69	fromTurnCount: 0,	78	fromTurnCount: 0,
70	toTurnCount: 2,	79	toTurnCount: 2,
71	cacheScope: "thread:all",	80	cacheScope: "thread:all",
...	@@ -75,15 +84,36 @@ describe("checkpointDiffQueryOptions", () => {	...	@@ -75,15 +84,36 @@ describe("checkpointDiffQueryOptions", () => {
75	await queryClient.fetchQuery(options);	84	await queryClient.fetchQuery(options);
76		85
77	expect(getFullThreadDiff).toHaveBeenCalledWith({	86	expect(getFullThreadDiff).toHaveBeenCalledWith({
78	threadId: "thread-id",	87	threadId,
79	toTurnCount: 2,	88	toTurnCount: 2,
80	});	89	});
81	expect(getTurnDiff).not.toHaveBeenCalled();	90	expect(getTurnDiff).not.toHaveBeenCalled();
82	});	91	});
83		92
		93	it("fails fast on invalid range and does not call provider RPC", async () => {
		94	const getTurnDiff = vi.fn().mockResolvedValue({ diff: "patch" });
		95	const getFullThreadDiff = vi.fn().mockResolvedValue({ diff: "patch" });
		96	mockNativeApi({ getTurnDiff, getFullThreadDiff });
		97
		98	const options = checkpointDiffQueryOptions({
		99	threadId,
		100	fromTurnCount: 4,
		101	toTurnCount: 3,
		102	cacheScope: "turn:invalid",
		103	});
		104
		105	const queryClient = new QueryClient();
		106
		107	await expect(queryClient.fetchQuery(options)).rejects.toThrow(
		108	"Checkpoint diff is unavailable.",
		109	);
		110	expect(getTurnDiff).not.toHaveBeenCalled();
		111	expect(getFullThreadDiff).not.toHaveBeenCalled();
		112	});
		113
84	it("retries checkpoint-not-ready errors longer than generic failures", () => {	114	it("retries checkpoint-not-ready errors longer than generic failures", () => {
85	const options = checkpointDiffQueryOptions(undefined, {	115	const options = checkpointDiffQueryOptions({
86	threadId: "thread-id",	116	threadId,
87	fromTurnCount: 1,	117	fromTurnCount: 1,
88	toTurnCount: 2,	118	toTurnCount: 2,
89	cacheScope: "turn:abc",	119	cacheScope: "turn:abc",
...	@@ -106,8 +136,8 @@ describe("checkpointDiffQueryOptions", () => {	...	@@ -106,8 +136,8 @@ describe("checkpointDiffQueryOptions", () => {
106	});	136	});
107		137
108	it("backs off longer for checkpoint-not-ready errors", () => {	138	it("backs off longer for checkpoint-not-ready errors", () => {
109	const options = checkpointDiffQueryOptions(undefined, {	139	const options = checkpointDiffQueryOptions({
110	threadId: "thread-id",	140	threadId,
111	fromTurnCount: 1,	141	fromTurnCount: 1,
112	toTurnCount: 2,	142	toTurnCount: 2,
113	cacheScope: "turn:abc",	143	cacheScope: "turn:abc",

apps/web/src/lib/providerReactQuery.ts+32-32

 @@ -1,9 +1,14 @@
-import type { NativeApi } from "@t3tools/contracts";
+import {
+  OrchestrationGetFullThreadDiffInput,
+  OrchestrationGetTurnDiffInput,
+  ThreadId,
+} from "@t3tools/contracts";
 import { queryOptions } from "@tanstack/react-query";
-import { asThreadId } from "./orchestrationIds";
+import { Option, Schema } from "effect";
+import { ensureNativeApi } from "../nativeApi";
-export interface CheckpointDiffQueryInput {
+interface CheckpointDiffQueryInput {
-  threadId: string | null;
+  threadId: ThreadId | null;
   fromTurnCount: number | null;
   toTurnCount: number | null;
   cacheScope?: string | null;
 @@ -22,6 +27,21 @@ export const providerQueryKeys = {
     ] as const,
 };
+function decodeCheckpointDiffRequest(input: CheckpointDiffQueryInput) {
+  if (input.fromTurnCount === 0) {
+    return Schema.decodeUnknownOption(OrchestrationGetFullThreadDiffInput)({
+      threadId: input.threadId,
+      toTurnCount: input.toTurnCount,
+    }).pipe(Option.map((fields) => ({ kind: "fullThreadDiff" as const, input: fields })));
+  }
+  return Schema.decodeUnknownOption(OrchestrationGetTurnDiffInput)({
+    threadId: input.threadId,
+    fromTurnCount: input.fromTurnCount,
+    toTurnCount: input.toTurnCount,
+  }).pipe(Option.map((fields) => ({ kind: "turnDiff" as const, input: fields })));
+}
 function asCheckpointErrorMessage(error: unknown): string {
   if (error instanceof Error) {
     return error.message;
 @@ -41,42 +61,22 @@ function isCheckpointTemporarilyUnavailable(error: unknown): boolean {
   );
 }
-export function checkpointDiffQueryOptions(
+export function checkpointDiffQueryOptions(input: CheckpointDiffQueryInput) {
-  api: NativeApi | undefined,
+  const decodedRequest = decodeCheckpointDiffRequest(input);
-  input: CheckpointDiffQueryInput,
-) {
-  const hasValidRange =
-    typeof input.fromTurnCount === "number" &&
-    typeof input.toTurnCount === "number" &&
-    Number.isInteger(input.fromTurnCount) &&
-    Number.isInteger(input.toTurnCount) &&
-    input.fromTurnCount >= 0 &&
-    input.toTurnCount >= 0 &&
-    input.fromTurnCount <= input.toTurnCount;
   return queryOptions({
     queryKey: providerQueryKeys.checkpointDiff(input),
     queryFn: async () => {
-      if (!api || !input.threadId || !hasValidRange) {
+      const api = ensureNativeApi();
+      if (!input.threadId || decodedRequest._tag === "None") {
         throw new Error("Checkpoint diff is unavailable.");
       }
-      const { fromTurnCount, toTurnCount } = input;
+      if (decodedRequest.value.kind === "fullThreadDiff") {
-      if (typeof fromTurnCount !== "number" || typeof toTurnCount !== "number") {
+        return api.orchestration.getFullThreadDiff(decodedRequest.value.input);
-        throw new Error("Checkpoint diff range is invalid.");
-      }
-      if (fromTurnCount === 0) {
-        return api.orchestration.getFullThreadDiff({
-          threadId: asThreadId(input.threadId),
-          toTurnCount,
-        });
       }
-      return api.orchestration.getTurnDiff({
+      return api.orchestration.getTurnDiff(decodedRequest.value.input);
-        threadId: asThreadId(input.threadId),
-        fromTurnCount,
-        toTurnCount,
-      });
     },
-    enabled: !!api && !!input.threadId && hasValidRange,
+    enabled: !!input.threadId && decodedRequest._tag === "Some",
     staleTime: Infinity,
     retry: (failureCount, error) => {
       if (isCheckpointTemporarilyUnavailable(error)) {

apps/web/src/lib/serverReactQuery.ts+3-6

 @@ -1,21 +1,18 @@
-import type { NativeApi } from "@t3tools/contracts";
 import { queryOptions } from "@tanstack/react-query";
+import { ensureNativeApi } from "~/nativeApi";
 export const serverQueryKeys = {
   all: ["server"] as const,
   config: () => ["server", "config"] as const,
 };
-export function serverConfigQueryOptions(api: NativeApi | undefined) {
+export function serverConfigQueryOptions() {
   return queryOptions({
     queryKey: serverQueryKeys.config(),
     queryFn: async () => {
-      if (!api || !api.server || typeof api.server.getConfig !== "function") {
+      const api = ensureNativeApi();
-        throw new Error("Server config is unavailable.");
-      }
       return api.server.getConfig();
     },
-    enabled: !!api && !!api.server && typeof api.server.getConfig === "function",
     staleTime: Infinity,
   });
 }

apps/web/src/model-logic.test.ts deleted-33

...	@@ -1,33 +0,0 @@
1	import { describe, expect, it } from "vitest";
2	import { DEFAULT_MODEL, normalizeModelSlug, resolveModelSlug } from "./model-logic";
3
4	describe("normalizeModelSlug", () => {
5	it("maps 5.3 aliases to canonical codex slug", () => {
6	expect(normalizeModelSlug("5.3")).toBe("gpt-5.3-codex");
7	expect(normalizeModelSlug("gpt-5.3")).toBe("gpt-5.3-codex");
8	});
9
10	it("preserves non-aliased slugs", () => {
11	expect(normalizeModelSlug("gpt-5.3-codex")).toBe("gpt-5.3-codex");
12	expect(normalizeModelSlug("gpt-5.2-codex")).toBe("gpt-5.2-codex");
13	});
14
15	it("returns null for empty input", () => {
16	expect(normalizeModelSlug("")).toBeNull();
17	expect(normalizeModelSlug(" ")).toBeNull();
18	expect(normalizeModelSlug(null)).toBeNull();
19	expect(normalizeModelSlug(undefined)).toBeNull();
20	});
21	});
22
23	describe("resolveModelSlug", () => {
24	it("falls back to default for unknown models", () => {
25	expect(resolveModelSlug("gpt-4.1")).toBe(DEFAULT_MODEL);
26	});
27
28	it("resolves supported hard-coded models", () => {
29	expect(resolveModelSlug("gpt-5.3-codex")).toBe("gpt-5.3-codex");
30	expect(resolveModelSlug("gpt-5.2-codex")).toBe("gpt-5.2-codex");
31	expect(resolveModelSlug("gpt-5.2")).toBe("gpt-5.2");
32	});
33	});

apps/web/src/model-logic.ts deleted-10

...	@@ -1,10 +0,0 @@
1	export {
2	DEFAULT_MODEL,
3	MODEL_OPTIONS,
4	normalizeModelSlug,
5	resolveModelSlug,
6	} from "@t3tools/contracts";
7
8	export const REASONING_OPTIONS = ["xhigh", "high", "medium", "low"] as const;
9	export type ReasoningEffort = (typeof REASONING_OPTIONS)[number];
10	export const DEFAULT_REASONING: ReasoningEffort = "high";

apps/web/src/nativeApi.ts+8

...	@@ -16,3 +16,11 @@ export function readNativeApi(): NativeApi \| undefined {	...	@@ -16,3 +16,11 @@ export function readNativeApi(): NativeApi \| undefined {
16	cachedApi = createWsNativeApi();	16	cachedApi = createWsNativeApi();
17	return cachedApi;	17	return cachedApi;
18	}	18	}
		19
		20	export function ensureNativeApi(): NativeApi {
		21	const api = readNativeApi();
		22	if (!api) {
		23	throw new Error("Native API not found");
		24	}
		25	return api;
		26	}

apps/web/src/routes/__root.tsx+4-6

...	@@ -9,7 +9,7 @@ import { QueryClient, useQueryClient } from "@tanstack/react-query";	...	@@ -9,7 +9,7 @@ import { QueryClient, useQueryClient } from "@tanstack/react-query";
9	import { APP_DISPLAY_NAME } from "../branding";	9	import { APP_DISPLAY_NAME } from "../branding";
10	import { Button } from "../components/ui/button";	10	import { Button } from "../components/ui/button";
11	import { AnchoredToastProvider, ToastProvider } from "../components/ui/toast";	11	import { AnchoredToastProvider, ToastProvider } from "../components/ui/toast";
12	import { useNativeApi } from "../hooks/useNativeApi";	12	import { readNativeApi } from "../nativeApi";
13	import { useStore } from "../store";	13	import { useStore } from "../store";
14	import { onServerWelcome } from "../wsNativeApi";	14	import { onServerWelcome } from "../wsNativeApi";
15	import { providerQueryKeys } from "../lib/providerReactQuery";	15	import { providerQueryKeys } from "../lib/providerReactQuery";
...	@@ -22,9 +22,7 @@ export const Route = createRootRouteWithContext<{	...	@@ -22,9 +22,7 @@ export const Route = createRootRouteWithContext<{
22	});	22	});
23		23
24	function RootRouteView() {	24	function RootRouteView() {
25	const api = useNativeApi();	25	if (!readNativeApi()) {
26
27	if (!api) {
28	return (	26	return (
29	<div className="flex h-screen flex-col bg-background text-foreground">	27	<div className="flex h-screen flex-col bg-background text-foreground">
30	<div className="flex flex-1 items-center justify-center">	28	<div className="flex flex-1 items-center justify-center">
...	@@ -119,11 +117,11 @@ function errorDetails(error: unknown): string {	...	@@ -119,11 +117,11 @@ function errorDetails(error: unknown): string {
119	}	117	}
120		118
121	function EventRouter() {	119	function EventRouter() {
122	const api = useNativeApi();
123	const { dispatch } = useStore();	120	const { dispatch } = useStore();
124	const queryClient = useQueryClient();	121	const queryClient = useQueryClient();
125		122
126	useEffect(() => {	123	useEffect(() => {
		124	const api = readNativeApi();
127	if (!api) return;	125	if (!api) return;
128	let disposed = false;	126	let disposed = false;
129	let latestSequence = 0;	127	let latestSequence = 0;
...	@@ -177,7 +175,7 @@ function EventRouter() {	...	@@ -177,7 +175,7 @@ function EventRouter() {
177	unsubDomainEvent();	175	unsubDomainEvent();
178	unsubWelcome();	176	unsubWelcome();
179	};	177	};
180	}, [api, dispatch, queryClient]);	178	}, [dispatch, queryClient]);
181		179
182	return null;	180	return null;
183	}	181	}

apps/web/src/routes/_chat.$threadId.tsx+6-8

...	@@ -1,3 +1,4 @@	...	@@ -1,3 +1,4 @@
		1	import { ThreadId } from "@t3tools/contracts";
1	import { createFileRoute, useNavigate } from "@tanstack/react-router";	2	import { createFileRoute, useNavigate } from "@tanstack/react-router";
2	import { Suspense, lazy, type ReactNode, useCallback, useEffect } from "react";	3	import { Suspense, lazy, type ReactNode, useCallback, useEffect } from "react";
3		4
...	@@ -133,9 +134,11 @@ const DiffPanelInlineSidebar = (props: {	...	@@ -133,9 +134,11 @@ const DiffPanelInlineSidebar = (props: {
133	function ChatThreadRouteView() {	134	function ChatThreadRouteView() {
134	const { state } = useStore();	135	const { state } = useStore();
135	const navigate = useNavigate();	136	const navigate = useNavigate();
136	const { threadId } = Route.useParams();	137	const threadId = Route.useParams({
		138	select: (params) => ThreadId.makeUnsafe(params.threadId),
		139	});
137	const search = Route.useSearch();	140	const search = Route.useSearch();
138	const threadExists = threadId ? state.threads.some((thread) => thread.id === threadId) : false;	141	const threadExists = state.threads.some((thread) => thread.id === threadId);
139	const diffOpen = search.diff === "1";	142	const diffOpen = search.diff === "1";
140	const shouldUseDiffSheet = useMediaQuery(DIFF_INLINE_LAYOUT_MEDIA_QUERY);	143	const shouldUseDiffSheet = useMediaQuery(DIFF_INLINE_LAYOUT_MEDIA_QUERY);
141	const closeDiff = useCallback(() => {	144	const closeDiff = useCallback(() => {
...	@@ -159,11 +162,6 @@ function ChatThreadRouteView() {	...	@@ -159,11 +162,6 @@ function ChatThreadRouteView() {
159	}, [navigate, threadId]);	162	}, [navigate, threadId]);
160		163
161	useEffect(() => {	164	useEffect(() => {
162	if (!threadId) {
163	void navigate({ to: "/", replace: true });
164	return;
165	}
166
167	if (!state.threadsHydrated) {	165	if (!state.threadsHydrated) {
168	return;	166	return;
169	}	167	}
...	@@ -174,7 +172,7 @@ function ChatThreadRouteView() {	...	@@ -174,7 +172,7 @@ function ChatThreadRouteView() {
174	}	172	}
175	}, [navigate, state.threadsHydrated, threadExists, threadId]);	173	}, [navigate, state.threadsHydrated, threadExists, threadId]);
176		174
177	if (!threadId \|\| !state.threadsHydrated \|\| !threadExists) {	175	if (!state.threadsHydrated \|\| !threadExists) {
178	return null;	176	return null;
179	}	177	}
180		178

apps/web/src/routes/_chat.tsx+1-1

...	@@ -3,7 +3,7 @@ import { useEffect } from "react";	...	@@ -3,7 +3,7 @@ import { useEffect } from "react";
3		3
4	import { DiffWorkerPoolProvider } from "../components/DiffWorkerPoolProvider";	4	import { DiffWorkerPoolProvider } from "../components/DiffWorkerPoolProvider";
5	import ThreadSidebar from "../components/Sidebar";	5	import ThreadSidebar from "../components/Sidebar";
6	import { SidebarInset, Sidebar, SidebarProvider } from "~/components/ui/sidebar";	6	import { Sidebar, SidebarProvider } from "~/components/ui/sidebar";
7		7
8	function ChatRouteLayout() {	8	function ChatRouteLayout() {
9	const navigate = useNavigate();	9	const navigate = useNavigate();

apps/web/src/session-logic.test.ts+2-34

...	@@ -1,11 +1,7 @@	...	@@ -1,11 +1,7 @@
1	import { EventId, TurnId, type OrchestrationThreadActivity } from "@t3tools/contracts";	1	import { EventId, TurnId, type OrchestrationThreadActivity } from "@t3tools/contracts";
2	import { describe, expect, it } from "vitest";	2	import { describe, expect, it } from "vitest";
3		3
4	import {	4	import { derivePendingApprovals, deriveWorkLogEntries } from "./session-logic";
5	derivePendingApprovals,
6	deriveTurnDiffFilesFromUnifiedDiff,
7	deriveWorkLogEntries,
8	} from "./session-logic";
9		5
10	function makeActivity(overrides: {	6	function makeActivity(overrides: {
11	id?: string;	7	id?: string;
...	@@ -105,7 +101,7 @@ describe("deriveWorkLogEntries", () => {	...	@@ -105,7 +101,7 @@ describe("deriveWorkLogEntries", () => {
105	makeActivity({ id: "no-turn", summary: "Checkpoint captured", tone: "info" }),	101	makeActivity({ id: "no-turn", summary: "Checkpoint captured", tone: "info" }),
106	];	102	];
107		103
108	const entries = deriveWorkLogEntries(activities, "turn-2");	104	const entries = deriveWorkLogEntries(activities, TurnId.makeUnsafe("turn-2"));
109	expect(entries.map((entry) => entry.id)).toEqual(["turn-2"]);	105	expect(entries.map((entry) => entry.id)).toEqual(["turn-2"]);
110	});	106	});
111		107
...	@@ -130,31 +126,3 @@ describe("deriveWorkLogEntries", () => {	...	@@ -130,31 +126,3 @@ describe("deriveWorkLogEntries", () => {
130	expect(entries.map((entry) => entry.id)).toEqual(["tool-complete"]);	126	expect(entries.map((entry) => entry.id)).toEqual(["tool-complete"]);
131	});	127	});
132	});	128	});
133
134	describe("deriveTurnDiffFilesFromUnifiedDiff", () => {
135	it("extracts per-file +/- counts from unified diff", () => {
136	const diff = [
137	"diff --git a/a.txt b/a.txt",
138	"index 111..222 100644",
139	"--- a/a.txt",
140	"+++ b/a.txt",
141	"@@ -1 +1,2 @@",
142	"-old",
143	"+new",
144	"+extra",
145	"diff --git a/b.txt b/b.txt",
146	"index 333..444 100644",
147	"--- a/b.txt",
148	"+++ b/b.txt",
149	"@@ -2,2 +2 @@",
150	"-x",
151	"-y",
152	"+z",
153	].join("\n");
154
155	expect(deriveTurnDiffFilesFromUnifiedDiff(diff)).toEqual([
156	{ path: "a.txt", additions: 2, deletions: 1 },
157	{ path: "b.txt", additions: 1, deletions: 2 },
158	]);
159	});
160	});

apps/web/src/session-logic.ts+16-64

...	@@ -1,12 +1,11 @@	...	@@ -1,12 +1,11 @@
1	import type { OrchestrationThreadActivity, ProviderKind } from "@t3tools/contracts";	1	import {
		2	ApprovalRequestId,
		3	type OrchestrationThreadActivity,
		4	type ProviderKind,
		5	type TurnId,
		6	} from "@t3tools/contracts";
2		7
3	import type {	8	import type { ChatMessage, SessionPhase, ThreadSession, TurnDiffSummary } from "./types";
4	ChatMessage,
5	SessionPhase,
6	ThreadSession,
7	TurnDiffFileChange,
8	TurnDiffSummary,
9	} from "./types";
10		9
11	export const PROVIDER_OPTIONS: Array<{	10	export const PROVIDER_OPTIONS: Array<{
12	value: ProviderKind;	11	value: ProviderKind;
...	@@ -26,7 +25,7 @@ export interface WorkLogEntry {	...	@@ -26,7 +25,7 @@ export interface WorkLogEntry {
26	}	25	}
27		26
28	export interface PendingApproval {	27	export interface PendingApproval {
29	requestId: string;	28	requestId: ApprovalRequestId;
30	requestKind: "command" \| "file-change";	29	requestKind: "command" \| "file-change";
31	createdAt: string;	30	createdAt: string;
32	detail?: string;	31	detail?: string;
...	@@ -79,7 +78,7 @@ export function formatElapsed(startIso: string, endIso: string \| undefined): str	...	@@ -79,7 +78,7 @@ export function formatElapsed(startIso: string, endIso: string \| undefined): str
79	export function derivePendingApprovals(	78	export function derivePendingApprovals(
80	activities: ReadonlyArray<OrchestrationThreadActivity>,	79	activities: ReadonlyArray<OrchestrationThreadActivity>,
81	): PendingApproval[] {	80	): PendingApproval[] {
82	const openByRequestId = new Map<string, PendingApproval>();	81	const openByRequestId = new Map<ApprovalRequestId, PendingApproval>();
83	const ordered = [...activities].toSorted((left, right) =>	82	const ordered = [...activities].toSorted((left, right) =>
84	left.createdAt.localeCompare(right.createdAt),	83	left.createdAt.localeCompare(right.createdAt),
85	);	84	);
...	@@ -89,7 +88,10 @@ export function derivePendingApprovals(	...	@@ -89,7 +88,10 @@ export function derivePendingApprovals(
89	activity.payload && typeof activity.payload === "object"	88	activity.payload && typeof activity.payload === "object"
90	? (activity.payload as Record<string, unknown>)	89	? (activity.payload as Record<string, unknown>)
91	: null;	90	: null;
92	const requestId = payload && typeof payload.requestId === "string" ? payload.requestId : null;	91	const requestId =
		92	payload && typeof payload.requestId === "string"
		93	? ApprovalRequestId.makeUnsafe(payload.requestId)
		94	: null;
93	const requestKind =	95	const requestKind =
94	payload && (payload.requestKind === "command" \|\| payload.requestKind === "file-change")	96	payload && (payload.requestKind === "command" \|\| payload.requestKind === "file-change")
95	? payload.requestKind	97	? payload.requestKind
...	@@ -118,7 +120,7 @@ export function derivePendingApprovals(	...	@@ -118,7 +120,7 @@ export function derivePendingApprovals(
118		120
119	export function deriveWorkLogEntries(	121	export function deriveWorkLogEntries(
120	activities: ReadonlyArray<OrchestrationThreadActivity>,	122	activities: ReadonlyArray<OrchestrationThreadActivity>,
121	latestTurnId: string \| undefined,	123	latestTurnId: TurnId \| undefined,
122	): WorkLogEntry[] {	124	): WorkLogEntry[] {
123	const ordered = [...activities].toSorted((left, right) =>	125	const ordered = [...activities].toSorted((left, right) =>
124	left.createdAt.localeCompare(right.createdAt),	126	left.createdAt.localeCompare(right.createdAt),
...	@@ -163,55 +165,11 @@ export function deriveTimelineEntries(	...	@@ -163,55 +165,11 @@ export function deriveTimelineEntries(
163	return [...messageRows, ...workRows].toSorted((a, b) => a.createdAt.localeCompare(b.createdAt));	165	return [...messageRows, ...workRows].toSorted((a, b) => a.createdAt.localeCompare(b.createdAt));
164	}	166	}
165		167
166	export function deriveTurnDiffFilesFromUnifiedDiff(diff: string): TurnDiffFileChange[] {
167	const normalized = diff.replace(/\r\n/g, "\n");
168	const headerMatches = [...normalized.matchAll(/^diff --git .+$/gm)];
169	if (headerMatches.length === 0) {
170	return [];
171	}
172
173	const files: TurnDiffFileChange[] = [];
174	for (let index = 0; index < headerMatches.length; index += 1) {
175	const header = headerMatches[index];
176	if (!header) continue;
177	const start = header.index ?? 0;
178	const nextStart = headerMatches[index + 1]?.index ?? normalized.length;
179	const segment = normalized.slice(start, nextStart);
180	const headerLine = header[0];
181	if (!headerLine) continue;
182
183	const match = headerLine.match(/^diff --git a\/(.+?) b\/(.+)$/);
184	const filePath = match?.[2] ?? match?.[1];
185	if (!filePath) continue;
186
187	let additions = 0;
188	let deletions = 0;
189	for (const line of segment.split("\n")) {
190	if (line.startsWith("+++ ") \|\| line.startsWith("--- ")) continue;
191	if (line.startsWith("+")) {
192	additions += 1;
193	continue;
194	}
195	if (line.startsWith("-")) {
196	deletions += 1;
197	}
198	}
199
200	files.push({
201	path: filePath,
202	additions,
203	deletions,
204	});
205	}
206
207	return files.toSorted((left, right) => left.path.localeCompare(right.path));
208	}
209
210	export function inferCheckpointTurnCountByTurnId(	168	export function inferCheckpointTurnCountByTurnId(
211	summaries: TurnDiffSummary[],	169	summaries: TurnDiffSummary[],
212	): Record<string, number> {	170	): Record<TurnId, number> {
213	const sorted = [...summaries].toSorted((a, b) => a.completedAt.localeCompare(b.completedAt));	171	const sorted = [...summaries].toSorted((a, b) => a.completedAt.localeCompare(b.completedAt));
214	const result: Record<string, number> = {};	172	const result: Record<TurnId, number> = {};
215	for (let index = 0; index < sorted.length; index += 1) {	173	for (let index = 0; index < sorted.length; index += 1) {
216	const summary = sorted[index];	174	const summary = sorted[index];
217	if (!summary) continue;	175	if (!summary) continue;
...	@@ -220,12 +178,6 @@ export function inferCheckpointTurnCountByTurnId(	...	@@ -220,12 +178,6 @@ export function inferCheckpointTurnCountByTurnId(
220	return result;	178	return result;
221	}	179	}
222		180
223	export function deriveTurnDiffSummaries(
224	_events: ReadonlyArray<OrchestrationThreadActivity>,
225	): TurnDiffSummary[] {
226	return [];
227	}
228
229	export function derivePhase(session: ThreadSession \| null): SessionPhase {	181	export function derivePhase(session: ThreadSession \| null): SessionPhase {
230	if (!session \|\| session.status === "closed") return "disconnected";	182	if (!session \|\| session.status === "closed") return "disconnected";
231	if (session.status === "connecting") return "connecting";	183	if (session.status === "connecting") return "connecting";

apps/web/src/store.ts+23-16

 @@ -8,15 +8,20 @@ import {
   useReducer,
 } from "react";
-import { type OrchestrationReadModel, type OrchestrationSessionStatus } from "@t3tools/contracts";
+import {
-import { DEFAULT_MODEL, resolveModelSlug } from "./model-logic";
+  DEFAULT_MODEL,
+  ProviderSessionId,
+  ThreadId,
+  type OrchestrationReadModel,
+  type OrchestrationSessionStatus,
+  resolveModelSlug,
+} from "@t3tools/contracts";
 import {
   DEFAULT_THREAD_TERMINAL_HEIGHT,
   DEFAULT_THREAD_TERMINAL_ID,
   DEFAULT_RUNTIME_MODE,
   MAX_THREAD_TERMINAL_COUNT,
   type ChatMessage,
-  type ProjectScript,
   type Project,
   type RuntimeMode,
   type Thread,
 @@ -27,19 +32,19 @@ import {
 type Action =
   | { type: "SYNC_SERVER_READ_MODEL"; readModel: OrchestrationReadModel }
-  | { type: "MARK_THREAD_VISITED"; threadId: string; visitedAt?: string }
+  | { type: "MARK_THREAD_VISITED"; threadId: ThreadId; visitedAt?: string }
-  | { type: "TOGGLE_PROJECT"; projectId: string }
+  | { type: "TOGGLE_PROJECT"; projectId: Project["id"] }
-  | { type: "TOGGLE_THREAD_TERMINAL"; threadId: string }
+  | { type: "TOGGLE_THREAD_TERMINAL"; threadId: ThreadId }
-  | { type: "SET_THREAD_TERMINAL_OPEN"; threadId: string; open: boolean }
+  | { type: "SET_THREAD_TERMINAL_OPEN"; threadId: ThreadId; open: boolean }
-  | { type: "SET_THREAD_TERMINAL_HEIGHT"; threadId: string; height: number }
+  | { type: "SET_THREAD_TERMINAL_HEIGHT"; threadId: ThreadId; height: number }
-  | { type: "SPLIT_THREAD_TERMINAL"; threadId: string; terminalId: string }
+  | { type: "SPLIT_THREAD_TERMINAL"; threadId: ThreadId; terminalId: string }
-  | { type: "NEW_THREAD_TERMINAL"; threadId: string; terminalId: string }
+  | { type: "NEW_THREAD_TERMINAL"; threadId: ThreadId; terminalId: string }
-  | { type: "SET_THREAD_ACTIVE_TERMINAL"; threadId: string; terminalId: string }
+  | { type: "SET_THREAD_ACTIVE_TERMINAL"; threadId: ThreadId; terminalId: string }
-  | { type: "CLOSE_THREAD_TERMINAL"; threadId: string; terminalId: string }
+  | { type: "CLOSE_THREAD_TERMINAL"; threadId: ThreadId; terminalId: string }
-  | { type: "SET_ERROR"; threadId: string; error: string | null }
+  | { type: "SET_ERROR"; threadId: ThreadId; error: string | null }
   | {
       type: "SET_THREAD_BRANCH";
-      threadId: string;
+      threadId: ThreadId;
       branch: string | null;
       worktreePath: string | null;
     }
 @@ -127,7 +132,7 @@ function persistState(state: AppState): void {
 function updateThread(
   threads: Thread[],
-  threadId: string,
+  threadId: ThreadId,
   updater: (t: Thread) => Thread,
 ): Thread[] {
   return threads.map((t) => (t.id === threadId ? updater(t) : t));
 @@ -415,7 +420,9 @@ export function reducer(state: AppState, action: Action): AppState {
               existing?.activeTerminalGroupId ?? `group-${DEFAULT_THREAD_TERMINAL_ID}`,
             session: thread.session
               ? {
-                  sessionId: thread.session.providerSessionId ?? `thread:${thread.id}`,
+                  sessionId:
+                    thread.session.providerSessionId ??
+                    ProviderSessionId.makeUnsafe(`thread:${thread.id}`),
                   provider: toLegacyProvider(thread.session.providerName),
                   status: toLegacySessionStatus(thread.session.status),
                   orchestrationStatus: thread.session.status,

apps/web/src/threadFactory.ts deleted-42

...	@@ -1,42 +0,0 @@
1	import { DEFAULT_MODEL } from "./model-logic";
2	import { DEFAULT_THREAD_TERMINAL_HEIGHT, DEFAULT_THREAD_TERMINAL_ID, type Thread } from "./types";
3
4	interface CreateThreadOptions {
5	branch?: string \| null;
6	createdAt?: string;
7	model?: string;
8	title?: string;
9	worktreePath?: string \| null;
10	}
11
12	export function createThread(projectId: string, options: CreateThreadOptions = {}): Thread {
13	const createdAt = options.createdAt ?? new Date().toISOString();
14
15	return {
16	id: crypto.randomUUID(),
17	codexThreadId: null,
18	projectId,
19	title: options.title ?? "New thread",
20	model: options.model ?? DEFAULT_MODEL,
21	terminalOpen: false,
22	terminalHeight: DEFAULT_THREAD_TERMINAL_HEIGHT,
23	terminalIds: [DEFAULT_THREAD_TERMINAL_ID],
24	runningTerminalIds: [],
25	activeTerminalId: DEFAULT_THREAD_TERMINAL_ID,
26	terminalGroups: [
27	{
28	id: `group-${DEFAULT_THREAD_TERMINAL_ID}`,
29	terminalIds: [DEFAULT_THREAD_TERMINAL_ID],
30	},
31	],
32	activeTerminalGroupId: `group-${DEFAULT_THREAD_TERMINAL_ID}`,
33	session: null,
34	messages: [],
35	turnDiffSummaries: [],
36	activities: [],
37	error: null,
38	createdAt,
39	branch: options.branch ?? null,
40	worktreePath: options.worktreePath ?? null,
41	};
42	}

apps/web/src/types.ts+21-13

 @@ -2,6 +2,14 @@ import type {
   OrchestrationSessionStatus,
   OrchestrationThreadActivity,
   ProjectScript as ContractProjectScript,
+  ThreadId,
+  ProjectId,
+  TurnId,
+  MessageId,
+  CheckpointRef,
+  ProviderThreadId,
+  ProviderSessionId,
+  ProviderKind,
 } from "@t3tools/contracts";
 export type SessionPhase = "disconnected" | "connecting" | "ready" | "running";
 @@ -29,7 +37,7 @@ export interface ChatImageAttachment {
 export type ChatAttachment = ChatImageAttachment;
 export interface ChatMessage {
-  id: string;
+  id: MessageId;
   role: "user" | "assistant" | "system";
   text: string;
   attachments?: ChatAttachment[];
 @@ -46,17 +54,17 @@ export interface TurnDiffFileChange {
 }
 export interface TurnDiffSummary {
-  turnId: string;
+  turnId: TurnId;
   completedAt: string;
   status?: string | undefined;
   files: TurnDiffFileChange[];
-  checkpointRef?: string | undefined;
+  checkpointRef?: CheckpointRef | undefined;
-  assistantMessageId?: string | undefined;
+  assistantMessageId?: MessageId | undefined;
   checkpointTurnCount?: number | undefined;
 }
 export interface Project {
-  id: string;
+  id: ProjectId;
   name: string;
   cwd: string;
   model: string;
 @@ -65,9 +73,9 @@ export interface Project {
 }
 export interface Thread {
-  id: string;
+  id: ThreadId;
-  codexThreadId: string | null;
+  codexThreadId: ProviderThreadId | null;
-  projectId: string;
+  projectId: ProjectId;
   title: string;
   model: string;
   terminalOpen: boolean;
 @@ -81,7 +89,7 @@ export interface Thread {
   messages: ChatMessage[];
   error: string | null;
   createdAt: string;
-  latestTurnId?: string | undefined;
+  latestTurnId?: TurnId | undefined;
   latestTurnStartedAt?: string | undefined;
   latestTurnCompletedAt?: string | undefined;
   latestTurnDurationMs?: number | undefined;
 @@ -93,11 +101,11 @@ export interface Thread {
 }
 export interface ThreadSession {
-  sessionId: string;
+  sessionId: ProviderSessionId;
-  provider: "codex" | "claudeCode";
+  provider: ProviderKind;
   status: SessionPhase | "error" | "closed";
-  threadId: string | null;
+  threadId: ProviderThreadId | null;
-  activeTurnId?: string | undefined;
+  activeTurnId?: TurnId | undefined;
   createdAt: string;
   updatedAt: string;
   lastError?: string;

apps/web/src/worktreeCleanup.test.ts+24-11

 @@ -1,3 +1,4 @@
+import { ProjectId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 import { DEFAULT_THREAD_TERMINAL_HEIGHT, DEFAULT_THREAD_TERMINAL_ID, type Thread } from "./types";
 @@ -5,9 +6,9 @@ import { formatWorktreePathForDisplay, getOrphanedWorktreePathForThread } from "
 function makeThread(overrides: Partial<Thread> = {}): Thread {
   return {
-    id: "thread-1",
+    id: ThreadId.makeUnsafe("thread-1"),
     codexThreadId: null,
-    projectId: "project-1",
+    projectId: ProjectId.makeUnsafe("project-1"),
     title: "Thread",
     model: "gpt-5.3-codex",
     terminalOpen: false,
 @@ -36,37 +37,49 @@ function makeThread(overrides: Partial<Thread> = {}): Thread {
 describe("getOrphanedWorktreePathForThread", () => {
   it("returns null when the target thread does not exist", () => {
-    const result = getOrphanedWorktreePathForThread([], "missing-thread");
+    const result = getOrphanedWorktreePathForThread([], ThreadId.makeUnsafe("missing-thread"));
     expect(result).toBeNull();
   });
   it("returns null when the target thread has no worktree", () => {
     const threads = [makeThread()];
-    const result = getOrphanedWorktreePathForThread(threads, "thread-1");
+    const result = getOrphanedWorktreePathForThread(threads, ThreadId.makeUnsafe("thread-1"));
     expect(result).toBeNull();
   });
   it("returns the path when no other thread links to that worktree", () => {
     const threads = [makeThread({ worktreePath: "/tmp/repo/worktrees/feature-a" })];
-    const result = getOrphanedWorktreePathForThread(threads, "thread-1");
+    const result = getOrphanedWorktreePathForThread(threads, ThreadId.makeUnsafe("thread-1"));
     expect(result).toBe("/tmp/repo/worktrees/feature-a");
   });
   it("returns null when another thread links to the same worktree", () => {
     const threads = [
-      makeThread({ id: "thread-1", worktreePath: "/tmp/repo/worktrees/feature-a" }),
+      makeThread({
-      makeThread({ id: "thread-2", worktreePath: "/tmp/repo/worktrees/feature-a" }),
+        id: ThreadId.makeUnsafe("thread-1"),
+        worktreePath: "/tmp/repo/worktrees/feature-a",
+      }),
+      makeThread({
+        id: ThreadId.makeUnsafe("thread-2"),
+        worktreePath: "/tmp/repo/worktrees/feature-a",
+      }),
     ];
-    const result = getOrphanedWorktreePathForThread(threads, "thread-1");
+    const result = getOrphanedWorktreePathForThread(threads, ThreadId.makeUnsafe("thread-1"));
     expect(result).toBeNull();
   });
   it("ignores threads linked to different worktrees", () => {
     const threads = [
-      makeThread({ id: "thread-1", worktreePath: "/tmp/repo/worktrees/feature-a" }),
+      makeThread({
-      makeThread({ id: "thread-2", worktreePath: "/tmp/repo/worktrees/feature-b" }),
+        id: ThreadId.makeUnsafe("thread-1"),
+        worktreePath: "/tmp/repo/worktrees/feature-a",
+      }),
+      makeThread({
+        id: ThreadId.makeUnsafe("thread-2"),
+        worktreePath: "/tmp/repo/worktrees/feature-b",
+      }),
     ];
-    const result = getOrphanedWorktreePathForThread(threads, "thread-1");
+    const result = getOrphanedWorktreePathForThread(threads, ThreadId.makeUnsafe("thread-1"));
     expect(result).toBe("/tmp/repo/worktrees/feature-a");
   });
 });

apps/web/src/worktreeCleanup.ts+1-1

...	@@ -10,7 +10,7 @@ function normalizeWorktreePath(path: string \| null): string \| null {	...	@@ -10,7 +10,7 @@ function normalizeWorktreePath(path: string \| null): string \| null {
10		10
11	export function getOrphanedWorktreePathForThread(	11	export function getOrphanedWorktreePathForThread(
12	threads: readonly Thread[],	12	threads: readonly Thread[],
13	threadId: string,	13	threadId: Thread["id"],
14	): string \| null {	14	): string \| null {
15	const targetThread = threads.find((thread) => thread.id === threadId);	15	const targetThread = threads.find((thread) => thread.id === threadId);
16	if (!targetThread) {	16	if (!targetThread) {

apps/web/src/wsTransport.ts+1-6

...	@@ -13,12 +13,7 @@ const REQUEST_TIMEOUT_MS = 60_000;	...	@@ -13,12 +13,7 @@ const REQUEST_TIMEOUT_MS = 60_000;
13	const RECONNECT_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];	13	const RECONNECT_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
14	const decodeWsResponseFromJson = Schema.decodeUnknownExit(Schema.fromJsonString(WsResponse));	14	const decodeWsResponseFromJson = Schema.decodeUnknownExit(Schema.fromJsonString(WsResponse));
15	const isWsPushEnvelope = Schema.is(WsPush);	15	const isWsPushEnvelope = Schema.is(WsPush);
16		16	const isWebSocketResponseEnvelope = Schema.is(WebSocketResponse);
17	function isWebSocketResponseEnvelope(
18	message: typeof WsResponse.Type,
19	): message is WebSocketResponse {
20	return message instanceof WebSocketResponse;
21	}
22		17
23	interface WsRequestEnvelope {	18	interface WsRequestEnvelope {
24	id: string;	19	id: string;

packages/contracts/src/editor.ts+3-2

...	@@ -8,7 +8,8 @@ export const EDITORS = [	...	@@ -8,7 +8,8 @@ export const EDITORS = [
8	export const EditorId = Schema.Literals(EDITORS.map((e) => e.id));	8	export const EditorId = Schema.Literals(EDITORS.map((e) => e.id));
9	export type EditorId = typeof EditorId.Type;	9	export type EditorId = typeof EditorId.Type;
10		10
11	export class OpenInEditorInput extends Schema.Class<OpenInEditorInput>("OpenInEditorInput")({	11	export const OpenInEditorInput = Schema.Struct({
12	cwd: Schema.String,	12	cwd: Schema.String,
13	editor: EditorId,	13	editor: EditorId,
14	}) {}	14	});
		15	export type OpenInEditorInput = typeof OpenInEditorInput.Type;

packages/contracts/src/git.ts+48-48

 @@ -18,78 +18,79 @@ export const GitPrStepStatus = Schema.Literals([
   "skipped_not_requested",
 ]);
-export class GitBranch extends Schema.Class<GitBranch>("GitBranch")({
+export const GitBranch = Schema.Struct({
   name: TrimmedNonEmptyString,
   current: Schema.Boolean,
   isDefault: Schema.Boolean,
   worktreePath: TrimmedNonEmptyString.pipe(Schema.NullOr),
-}) {}
+});
+export type GitBranch = typeof GitBranch.Type;
-export class GitWorktree extends Schema.Class<GitWorktree>("GitWorktree")({
+export const GitWorktree = Schema.Struct({
   path: TrimmedNonEmptyString,
   branch: TrimmedNonEmptyString,
-}) {}
+});
+export type GitWorktree = typeof GitWorktree.Type;
 // RPC Inputs
-export class GitStatusInput extends Schema.Class<GitStatusInput>("GitStatusInput")({
+export const GitStatusInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
-}) {}
+});
+export type GitStatusInput = typeof GitStatusInput.Type;
-export class GitPullInput extends Schema.Class<GitPullInput>("GitPullInput")({
+export const GitPullInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
-}) {}
+});
+export type GitPullInput = typeof GitPullInput.Type;
-export class GitRunStackedActionInput extends Schema.Class<GitRunStackedActionInput>(
+export const GitRunStackedActionInput = Schema.Struct({
-  "GitRunStackedActionInput",
-)({
   cwd: TrimmedNonEmptyString,
   action: GitStackedAction,
   commitMessage: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(10_000))),
-}) {}
+});
+export type GitRunStackedActionInput = typeof GitRunStackedActionInput.Type;
-export class GitListBranchesInput extends Schema.Class<GitListBranchesInput>(
+export const GitListBranchesInput = Schema.Struct({
-  "GitListBranchesInput",
-)({
   cwd: TrimmedNonEmptyString,
-}) {}
+});
+export type GitListBranchesInput = typeof GitListBranchesInput.Type;
-export class GitCreateWorktreeInput extends Schema.Class<GitCreateWorktreeInput>(
+export const GitCreateWorktreeInput = Schema.Struct({
-  "GitCreateWorktreeInput",
-)({
   cwd: TrimmedNonEmptyString,
   branch: TrimmedNonEmptyString,
   newBranch: TrimmedNonEmptyString,
   path: TrimmedNonEmptyString.pipe(Schema.NullOr),
-}) {}
+});
+export type GitCreateWorktreeInput = typeof GitCreateWorktreeInput.Type;
-export class GitRemoveWorktreeInput extends Schema.Class<GitRemoveWorktreeInput>(
+export const GitRemoveWorktreeInput = Schema.Struct({
-  "GitRemoveWorktreeInput",
-)({
   cwd: TrimmedNonEmptyString,
   path: TrimmedNonEmptyString,
   force: Schema.optional(Schema.Boolean),
-}) {}
+});
+export type GitRemoveWorktreeInput = typeof GitRemoveWorktreeInput.Type;
-export class GitCreateBranchInput extends Schema.Class<GitCreateBranchInput>(
+export const GitCreateBranchInput = Schema.Struct({
-  "GitCreateBranchInput",
-)({
   cwd: TrimmedNonEmptyString,
   branch: TrimmedNonEmptyString,
-}) {}
+});
+export type GitCreateBranchInput = typeof GitCreateBranchInput.Type;
-export class GitCheckoutInput extends Schema.Class<GitCheckoutInput>("GitCheckoutInput")({
+export const GitCheckoutInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
   branch: TrimmedNonEmptyString,
-}) {}
+});
+export type GitCheckoutInput = typeof GitCheckoutInput.Type;
-export class GitInitInput extends Schema.Class<GitInitInput>("GitInitInput")({
+export const GitInitInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
-}) {}
+});
+export type GitInitInput = typeof GitInitInput.Type;
 // RPC Results
-export class GitStatusResult extends Schema.Class<GitStatusResult>("GitStatusResult")({
+export const GitStatusResult = Schema.Struct({
   branch: TrimmedNonEmptyString.pipe(Schema.NullOr),
   hasWorkingTreeChanges: Schema.Boolean,
   workingTree: Schema.Struct({
 @@ -113,24 +114,21 @@ export class GitStatusResult extends Schema.Class<GitStatusResult>("GitStatusRes
     baseBranch: TrimmedNonEmptyString,
     headBranch: TrimmedNonEmptyString,
   }).pipe(Schema.NullOr),
-}) {}
+});
+export type GitStatusResult = typeof GitStatusResult.Type;
-export class GitListBranchesResult extends Schema.Class<GitListBranchesResult>(
+export const GitListBranchesResult = Schema.Struct({
-  "GitListBranchesResult",
-)({
   branches: Schema.Array(GitBranch),
   isRepo: Schema.Boolean,
-}) {}
+});
+export type GitListBranchesResult = typeof GitListBranchesResult.Type;
-export class GitCreateWorktreeResult extends Schema.Class<GitCreateWorktreeResult>(
+export const GitCreateWorktreeResult = Schema.Struct({
-  "GitCreateWorktreeResult",
-)({
   worktree: GitWorktree,
-}) {}
+});
+export type GitCreateWorktreeResult = typeof GitCreateWorktreeResult.Type;
-export class GitRunStackedActionResult extends Schema.Class<GitRunStackedActionResult>(
+export const GitRunStackedActionResult = Schema.Struct({
-  "GitRunStackedActionResult",
-)({
   action: GitStackedAction,
   commit: Schema.Struct({
     status: GitCommitStepStatus,
 @@ -151,10 +149,12 @@ export class GitRunStackedActionResult extends Schema.Class<GitRunStackedActionR
     headBranch: Schema.optional(TrimmedNonEmptyString),
     title: Schema.optional(TrimmedNonEmptyString),
   }),
-}) {}
+});
+export type GitRunStackedActionResult = typeof GitRunStackedActionResult.Type;
-export class GitPullResult extends Schema.Class<GitPullResult>("GitPullResult")({
+export const GitPullResult = Schema.Struct({
   status: Schema.Literals(["pulled", "skipped_up_to_date"]),
   branch: TrimmedNonEmptyString,
   upstreamBranch: TrimmedNonEmptyString.pipe(Schema.NullOr),
-}) {}
+});
+export type GitPullResult = typeof GitPullResult.Type;

packages/contracts/src/keybindings.ts+12-14

 @@ -44,25 +44,27 @@ export const KeybindingWhen = Schema.Trim.check(
   Schema.isMaxLength(MAX_KEYBINDING_WHEN_LENGTH),
 );
 export type KeybindingWhen = typeof KeybindingWhen.Type;
-export class KeybindingRule extends Schema.Class<KeybindingRule>("KeybindingRule")({
+export const KeybindingRule = Schema.Struct({
   key: KeybindingValue,
   command: KeybindingCommand,
   when: Schema.optional(KeybindingWhen),
-}) {}
+});
+export type KeybindingRule = typeof KeybindingRule.Type;
 export const KeybindingsConfig = Schema.Array(KeybindingRule).check(
   Schema.isMaxLength(MAX_KEYBINDINGS_COUNT),
 );
 export type KeybindingsConfig = typeof KeybindingsConfig.Type;
-export class KeybindingShortcut extends Schema.Class<KeybindingShortcut>("KeybindingShortcut")({
+export const KeybindingShortcut = Schema.Struct({
   key: KeybindingValue,
   metaKey: Schema.Boolean,
   ctrlKey: Schema.Boolean,
   shiftKey: Schema.Boolean,
   altKey: Schema.Boolean,
   modKey: Schema.Boolean,
-}) {}
+});
+export type KeybindingShortcut = typeof KeybindingShortcut.Type;
 export const KeybindingWhenNode: Schema.Schema<KeybindingWhenNode> = Schema.Union([
   Schema.Struct({
 @@ -90,16 +92,12 @@ export type KeybindingWhenNode =
   | { type: "and"; left: KeybindingWhenNode; right: KeybindingWhenNode }
   | { type: "or"; left: KeybindingWhenNode; right: KeybindingWhenNode };
-export class ResolvedKeybindingRule extends Schema.Class<ResolvedKeybindingRule>(
+export const ResolvedKeybindingRule = Schema.Struct({
-  "ResolvedKeybindingRule",
+  command: KeybindingCommand,
-)(
+  shortcut: KeybindingShortcut,
-  {
+  whenAst: Schema.optional(KeybindingWhenNode),
-    command: KeybindingCommand,
+}).annotate({ parseOptions: { onExcessProperty: "ignore" } });
-    shortcut: KeybindingShortcut,
+export type ResolvedKeybindingRule = typeof ResolvedKeybindingRule.Type;
-    whenAst: Schema.optional(KeybindingWhenNode),
-  },
-  { parseOptions: { onExcessProperty: "ignore" } },
-) {}
 export const ResolvedKeybindingsConfig = Schema.Array(ResolvedKeybindingRule).check(
   Schema.isMaxLength(MAX_KEYBINDINGS_COUNT),

packages/contracts/src/model.ts+4

...	@@ -37,3 +37,7 @@ export function resolveModelSlug(model: string \| null \| undefined): ModelSlug {	...	@@ -37,3 +37,7 @@ export function resolveModelSlug(model: string \| null \| undefined): ModelSlug {
37		37
38	return MODEL_OPTIONS.some((option) => option.slug === normalized) ? normalized : DEFAULT_MODEL;	38	return MODEL_OPTIONS.some((option) => option.slug === normalized) ? normalized : DEFAULT_MODEL;
39	}	39	}
		40
		41	export const REASONING_OPTIONS = ["xhigh", "high", "medium", "low"] as const;
		42	export type ReasoningEffort = (typeof REASONING_OPTIONS)[number];
		43	export const DEFAULT_REASONING: ReasoningEffort = "high";

packages/contracts/src/orchestration.test.ts created+46

...	@@ -0,0 +1,46 @@
1	import { assert, it } from "@effect/vitest";
2	import { Effect, Schema } from "effect";
3
4	import { OrchestrationGetTurnDiffInput, ThreadTurnDiff } from "./orchestration";
5
6	const decodeTurnDiffInput = Schema.decodeUnknownEffect(OrchestrationGetTurnDiffInput);
7	const decodeThreadTurnDiff = Schema.decodeUnknownEffect(ThreadTurnDiff);
8
9	it.effect("parses turn diff input when fromTurnCount <= toTurnCount", () =>
10	Effect.gen(function* () {
11	const parsed = yield* decodeTurnDiffInput({
12	threadId: "thread-1",
13	fromTurnCount: 1,
14	toTurnCount: 2,
15	});
16	assert.strictEqual(parsed.fromTurnCount, 1);
17	assert.strictEqual(parsed.toTurnCount, 2);
18	}),
19	);
20
21	it.effect("rejects turn diff input when fromTurnCount > toTurnCount", () =>
22	Effect.gen(function* () {
23	const result = yield* Effect.exit(
24	decodeTurnDiffInput({
25	threadId: "thread-1",
26	fromTurnCount: 3,
27	toTurnCount: 2,
28	}),
29	);
30	assert.strictEqual(result._tag, "Failure");
31	}),
32	);
33
34	it.effect("rejects thread turn diff when fromTurnCount > toTurnCount", () =>
35	Effect.gen(function* () {
36	const result = yield* Effect.exit(
37	decodeThreadTurnDiff({
38	threadId: "thread-1",
39	fromTurnCount: 3,
40	toTurnCount: 2,
41	diff: "patch",
42	}),
43	);
44	assert.strictEqual(result._tag, "Failure");
45	}),
46	);

packages/contracts/src/orchestration.ts+22-11

 @@ -1,4 +1,4 @@
-import { Schema } from "effect";
+import { Option, Schema, SchemaIssue, Struct } from "effect";
 export const ORCHESTRATION_WS_METHODS = {
   getSnapshot: "orchestration.getSnapshot",
 @@ -777,13 +777,24 @@ export type OrchestrationCommandReceiptStatus = typeof OrchestrationCommandRecei
 export const TurnCountRange = Schema.Struct({
   fromTurnCount: NonNegativeInt,
   toTurnCount: NonNegativeInt,
-});
+}).check(
+  Schema.makeFilter(
+    (input) =>
+      input.fromTurnCount <= input.toTurnCount ||
+      new SchemaIssue.InvalidValue(Option.some(input.fromTurnCount), {
+        message: "fromTurnCount must be less than or equal to toTurnCount",
+      }),
+    { identifier: "OrchestrationTurnDiffRange" },
+  ),
+);
-export const ThreadTurnDiff = Schema.Struct({
+export const ThreadTurnDiff = TurnCountRange.mapFields(
-  threadId: ThreadId,
+  Struct.assign({
-  ...TurnCountRange.fields,
+    threadId: ThreadId,
-  diff: Schema.String,
+    diff: Schema.String,
-});
+  }),
+  { unsafePreserveChecks: true },
+);
 export const ProviderSessionRuntimeStatus = Schema.Literals([
   "starting",
 @@ -829,10 +840,10 @@ export type OrchestrationGetSnapshotInput = typeof OrchestrationGetSnapshotInput
 export const OrchestrationGetSnapshotResult = OrchestrationReadModel;
 export type OrchestrationGetSnapshotResult = typeof OrchestrationGetSnapshotResult.Type;
-export const OrchestrationGetTurnDiffInput = Schema.Struct({
+export const OrchestrationGetTurnDiffInput = TurnCountRange.mapFields(
-  threadId: ThreadId,
+  Struct.assign({ threadId: ThreadId }),
-  ...TurnCountRange.fields,
+  { unsafePreserveChecks: true },
-});
+);
 export type OrchestrationGetTurnDiffInput = typeof OrchestrationGetTurnDiffInput.Type;
 export const OrchestrationGetTurnDiffResult = ThreadTurnDiff;

packages/contracts/src/project.ts+9-10

 @@ -3,28 +3,27 @@ import { Schema } from "effect";
 export const PROJECT_SEARCH_ENTRIES_MAX_LIMIT = 200;
 const TrimmedNonEmptyString = Schema.Trimmed.check(Schema.isNonEmpty());
-export class ProjectSearchEntriesInput extends Schema.Class<ProjectSearchEntriesInput>(
+export const ProjectSearchEntriesInput = Schema.Struct({
-  "ProjectSearchEntriesInput",
-)({
   cwd: TrimmedNonEmptyString,
   query: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
   limit: Schema.Int.check(
     Schema.isGreaterThanOrEqualTo(1),
     Schema.isLessThanOrEqualTo(PROJECT_SEARCH_ENTRIES_MAX_LIMIT),
   ),
-}) {}
+});
+export type ProjectSearchEntriesInput = typeof ProjectSearchEntriesInput.Type;
 export const ProjectEntryKind = Schema.Literals(["file", "directory"]);
-export class ProjectEntry extends Schema.Class<ProjectEntry>("ProjectEntry")({
+export const ProjectEntry = Schema.Struct({
   path: TrimmedNonEmptyString,
   kind: ProjectEntryKind,
   parentPath: Schema.optional(TrimmedNonEmptyString),
-}) {}
+});
+export type ProjectEntry = typeof ProjectEntry.Type;
-export class ProjectSearchEntriesResult extends Schema.Class<ProjectSearchEntriesResult>(
+export const ProjectSearchEntriesResult = Schema.Struct({
-  "ProjectSearchEntriesResult",
-)({
   entries: Schema.Array(ProjectEntry),
   truncated: Schema.Boolean,
-}) {}
+});
+export type ProjectSearchEntriesResult = typeof ProjectSearchEntriesResult.Type;

packages/contracts/src/ws.test.ts created+39

...	@@ -0,0 +1,39 @@
1	import { assert, it } from "@effect/vitest";
2	import { Effect, Schema } from "effect";
3
4	import { ORCHESTRATION_WS_METHODS } from "./orchestration";
5	import { WebSocketRequest } from "./ws";
6
7	const decodeWebSocketRequest = Schema.decodeUnknownEffect(WebSocketRequest);
8
9	it.effect("accepts getTurnDiff requests when fromTurnCount <= toTurnCount", () =>
10	Effect.gen(function* () {
11	const parsed = yield* decodeWebSocketRequest({
12	id: "req-1",
13	body: {
14	_tag: ORCHESTRATION_WS_METHODS.getTurnDiff,
15	threadId: "thread-1",
16	fromTurnCount: 1,
17	toTurnCount: 2,
18	},
19	});
20	assert.strictEqual(parsed.body._tag, ORCHESTRATION_WS_METHODS.getTurnDiff);
21	}),
22	);
23
24	it.effect("rejects getTurnDiff requests when fromTurnCount > toTurnCount", () =>
25	Effect.gen(function* () {
26	const result = yield* Effect.exit(
27	decodeWebSocketRequest({
28	id: "req-1",
29	body: {
30	_tag: ORCHESTRATION_WS_METHODS.getTurnDiff,
31	threadId: "thread-1",
32	fromTurnCount: 3,
33	toTurnCount: 2,
34	},
35	}),
36	);
37	assert.strictEqual(result._tag, "Failure");
38	}),
39	);

packages/contracts/src/ws.ts+49-33

...	@@ -1,4 +1,4 @@	...	@@ -1,4 +1,4 @@
1	import { Schema } from "effect";	1	import { Schema, Struct } from "effect";
2		2
3	import {	3	import {
4	ClientOrchestrationCommand,	4	ClientOrchestrationCommand,
...	@@ -76,43 +76,56 @@ export const WS_CHANNELS = {	...	@@ -76,43 +76,56 @@ export const WS_CHANNELS = {
76		76
77	// -- Tagged Union of all request body schemas ─────────────────────────	77	// -- Tagged Union of all request body schemas ─────────────────────────
78		78
79	export const WebSocketRequestBody = Schema.TaggedUnion({	79	const tagRequestBody = <const Tag extends string, const Fields extends Schema.Struct.Fields>(
		80	tag: Tag,
		81	schema: Schema.Struct<Fields>,
		82	) =>
		83	schema.mapFields(
		84	Struct.assign({ _tag: Schema.tag(tag) }),
		85	// PreserveChecks is safe here. No existing schema should have checks depending on the tag
		86	{ unsafePreserveChecks: true },
		87	);
		88
		89	export const WebSocketRequestBody = Schema.Union([
80	// Orchestration methods	90	// Orchestration methods
81	[ORCHESTRATION_WS_METHODS.dispatchCommand]: { command: ClientOrchestrationCommand },	91	tagRequestBody(
82	[ORCHESTRATION_WS_METHODS.getSnapshot]: OrchestrationGetSnapshotInput.fields,	92	ORCHESTRATION_WS_METHODS.dispatchCommand,
83	[ORCHESTRATION_WS_METHODS.getTurnDiff]: OrchestrationGetTurnDiffInput.fields,	93	Schema.Struct({ command: ClientOrchestrationCommand }),
84	[ORCHESTRATION_WS_METHODS.getFullThreadDiff]: OrchestrationGetFullThreadDiffInput.fields,	94	),
85	[ORCHESTRATION_WS_METHODS.replayEvents]: OrchestrationReplayEventsInput.fields,	95	tagRequestBody(ORCHESTRATION_WS_METHODS.getSnapshot, OrchestrationGetSnapshotInput),
		96	tagRequestBody(ORCHESTRATION_WS_METHODS.getTurnDiff, OrchestrationGetTurnDiffInput),
		97	tagRequestBody(ORCHESTRATION_WS_METHODS.getFullThreadDiff, OrchestrationGetFullThreadDiffInput),
		98	tagRequestBody(ORCHESTRATION_WS_METHODS.replayEvents, OrchestrationReplayEventsInput),
86		99
87	// Project Search	100	// Project Search
88	[WS_METHODS.projectsSearchEntries]: ProjectSearchEntriesInput.fields,	101	tagRequestBody(WS_METHODS.projectsSearchEntries, ProjectSearchEntriesInput),
89		102
90	// Shell methods	103	// Shell methods
91	[WS_METHODS.shellOpenInEditor]: OpenInEditorInput.fields,	104	tagRequestBody(WS_METHODS.shellOpenInEditor, OpenInEditorInput),
92		105
93	// Git methods	106	// Git methods
94	[WS_METHODS.gitPull]: GitPullInput.fields,	107	tagRequestBody(WS_METHODS.gitPull, GitPullInput),
95	[WS_METHODS.gitStatus]: GitStatusInput.fields,	108	tagRequestBody(WS_METHODS.gitStatus, GitStatusInput),
96	[WS_METHODS.gitRunStackedAction]: GitRunStackedActionInput.fields,	109	tagRequestBody(WS_METHODS.gitRunStackedAction, GitRunStackedActionInput),
97	[WS_METHODS.gitListBranches]: GitListBranchesInput.fields,	110	tagRequestBody(WS_METHODS.gitListBranches, GitListBranchesInput),
98	[WS_METHODS.gitCreateWorktree]: GitCreateWorktreeInput.fields,	111	tagRequestBody(WS_METHODS.gitCreateWorktree, GitCreateWorktreeInput),
99	[WS_METHODS.gitRemoveWorktree]: GitRemoveWorktreeInput.fields,	112	tagRequestBody(WS_METHODS.gitRemoveWorktree, GitRemoveWorktreeInput),
100	[WS_METHODS.gitCreateBranch]: GitCreateBranchInput.fields,	113	tagRequestBody(WS_METHODS.gitCreateBranch, GitCreateBranchInput),
101	[WS_METHODS.gitCheckout]: GitCheckoutInput.fields,	114	tagRequestBody(WS_METHODS.gitCheckout, GitCheckoutInput),
102	[WS_METHODS.gitInit]: GitInitInput.fields,	115	tagRequestBody(WS_METHODS.gitInit, GitInitInput),
103		116
104	// Terminal methods	117	// Terminal methods
105	[WS_METHODS.terminalOpen]: TerminalOpenInput.fields,	118	tagRequestBody(WS_METHODS.terminalOpen, TerminalOpenInput),
106	[WS_METHODS.terminalWrite]: TerminalWriteInput.fields,	119	tagRequestBody(WS_METHODS.terminalWrite, TerminalWriteInput),
107	[WS_METHODS.terminalResize]: TerminalResizeInput.fields,	120	tagRequestBody(WS_METHODS.terminalResize, TerminalResizeInput),
108	[WS_METHODS.terminalClear]: TerminalClearInput.fields,	121	tagRequestBody(WS_METHODS.terminalClear, TerminalClearInput),
109	[WS_METHODS.terminalRestart]: TerminalRestartInput.fields,	122	tagRequestBody(WS_METHODS.terminalRestart, TerminalRestartInput),
110	[WS_METHODS.terminalClose]: TerminalCloseInput.fields,	123	tagRequestBody(WS_METHODS.terminalClose, TerminalCloseInput),
111		124
112	// Server meta	125	// Server meta
113	[WS_METHODS.serverGetConfig]: {},	126	tagRequestBody(WS_METHODS.serverGetConfig, Schema.Struct({})),
114	[WS_METHODS.serverUpsertKeybinding]: KeybindingRule.fields,	127	tagRequestBody(WS_METHODS.serverUpsertKeybinding, KeybindingRule),
115	});	128	]);
116		129
117	export const WebSocketRequest = Schema.Struct({	130	export const WebSocketRequest = Schema.Struct({
118	id: Schema.String,	131	id: Schema.String,
...	@@ -120,7 +133,7 @@ export const WebSocketRequest = Schema.Struct({	...	@@ -120,7 +133,7 @@ export const WebSocketRequest = Schema.Struct({
120	});	133	});
121	export type WebSocketRequest = typeof WebSocketRequest.Type;	134	export type WebSocketRequest = typeof WebSocketRequest.Type;
122		135
123	export class WebSocketResponse extends Schema.Class<WebSocketResponse>("WebSocketResponse")({	136	export const WebSocketResponse = Schema.Struct({
124	id: Schema.String,	137	id: Schema.String,
125	result: Schema.optional(Schema.Unknown),	138	result: Schema.optional(Schema.Unknown),
126	error: Schema.optional(	139	error: Schema.optional(
...	@@ -128,13 +141,15 @@ export class WebSocketResponse extends Schema.Class<WebSocketResponse>("WebSocke	...	@@ -128,13 +141,15 @@ export class WebSocketResponse extends Schema.Class<WebSocketResponse>("WebSocke
128	message: Schema.String,	141	message: Schema.String,
129	}),	142	}),
130	),	143	),
131	}) {}	144	});
		145	export type WebSocketResponse = typeof WebSocketResponse.Type;
132		146
133	export class WsPush extends Schema.Class<WsPush>("WsPushEvent")({	147	export const WsPush = Schema.Struct({
134	type: Schema.Literal("push"),	148	type: Schema.Literal("push"),
135	channel: Schema.String,	149	channel: Schema.String,
136	data: Schema.Unknown,	150	data: Schema.Unknown,
137	}) {}	151	});
		152	export type WsPush = typeof WsPush.Type;
138		153
139	// ── Union of all server → client messages ─────────────────────────────	154	// ── Union of all server → client messages ─────────────────────────────
140		155
...	@@ -143,7 +158,8 @@ export type WsResponse = typeof WsResponse.Type;	...	@@ -143,7 +158,8 @@ export type WsResponse = typeof WsResponse.Type;
143		158
144	// ── Server welcome payload ───────────────────────────────────────────	159	// ── Server welcome payload ───────────────────────────────────────────
145		160
146	export class WsWelcomePayload extends Schema.Class<WsWelcomePayload>("WsWelcomePayload")({	161	export const WsWelcomePayload = Schema.Struct({
147	cwd: Schema.String,	162	cwd: Schema.String,
148	projectName: Schema.String,	163	projectName: Schema.String,
149	}) {}	164	});
		165	export type WsWelcomePayload = typeof WsWelcomePayload.Type;

author	Julius Marminge <julius0216@outlook.com> 2026-02-25 15:05:58-08:00
committer	Julius Marminge <jmarminge@gmail.com> 2026-02-26 13:20:36-08:00
log	c2b9680a5efc0855d24fb5a4bdcf9320469354d4
tree	a07436d65c5e019f4da1b97dbe62a18eb3a65ea7
parent	a973e43421c9829a7450a7fe06d5f0e81c1b98c1

...	@@ -216,7 +216,7 @@ export class GitCoreService {	...	@@ -216,7 +216,7 @@ export class GitCoreService {
216		216
217	async status(input: GitStatusInput): Promise<GitStatusResult> {	217	async status(input: GitStatusInput): Promise<GitStatusResult> {
218	const details = await this.statusDetails(input.cwd);	218	const details = await this.statusDetails(input.cwd);
219	return GitStatusResult.makeUnsafe({	219	return {
220	branch: details.branch,	220	branch: details.branch,
221	hasWorkingTreeChanges: details.hasWorkingTreeChanges,	221	hasWorkingTreeChanges: details.hasWorkingTreeChanges,
222	workingTree: details.workingTree,	222	workingTree: details.workingTree,
...	@@ -224,7 +224,7 @@ export class GitCoreService {	...	@@ -224,7 +224,7 @@ export class GitCoreService {
224	aheadCount: details.aheadCount,	224	aheadCount: details.aheadCount,
225	behindCount: details.behindCount,	225	behindCount: details.behindCount,
226	openPr: null,	226	openPr: null,
227	});	227	};
228	}	228	}
229		229
230	async statusDetails(cwd: string): Promise<GitStatusDetails> {	230	async statusDetails(cwd: string): Promise<GitStatusDetails> {
...	@@ -385,11 +385,11 @@ export class GitCoreService {	...	@@ -385,11 +385,11 @@ export class GitCoreService {
385	});	385	});
386	const afterSha = trimStdout(await this.gitStdout(cwd, ["rev-parse", "HEAD"], true));	386	const afterSha = trimStdout(await this.gitStdout(cwd, ["rev-parse", "HEAD"], true));
387	const refreshed = await this.statusDetails(cwd);	387	const refreshed = await this.statusDetails(cwd);
388	return GitPullResult.makeUnsafe({	388	return {
389	status: beforeSha.length > 0 && beforeSha === afterSha ? "skipped_up_to_date" : "pulled",	389	status: beforeSha.length > 0 && beforeSha === afterSha ? "skipped_up_to_date" : "pulled",
390	branch,	390	branch,
391	upstreamBranch: refreshed.upstreamRef,	391	upstreamBranch: refreshed.upstreamRef,
392	});	392	};
393	}	393	}
394		394
395	async readRangeContext(cwd: string, baseBranch: string): Promise<GitRangeContext> {	395	async readRangeContext(cwd: string, baseBranch: string): Promise<GitRangeContext> {

buuuunch of cleanup