From 1e9b7f1157a8607257785ed20fb656036d0988ec Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Sat, 4 Apr 2026 20:20:33 +0700 Subject: [PATCH] fix: make worktreeRoot backward-compatible for old clients/daemons worktreeRoot was added as a required field in 9154f8fc, which breaks old clients parsing new daemon responses and new clients parsing old daemon responses. Made it .optional() with .transform() fallbacks. Also added a critical rule to CLAUDE.md: schema changes must always be backward-compatible in both directions. --- CLAUDE.md | 6 ++ packages/server/src/shared/messages.ts | 69 +++++++++++-------- .../src/shared/messages.workspaces.test.ts | 67 ++++++++++++++++++ 3 files changed, 115 insertions(+), 27 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 44c854c88..a4eddcbad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,12 @@ See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for full setup, build sync requir - **NEVER assume a timeout means the service needs restarting** — timeouts can be transient. - **NEVER add auth checks to tests** — agent providers handle their own auth. - **Always run typecheck after every change.** +- **NEVER make breaking changes to WebSocket or message schemas.** The mobile app in the App Store always lags behind the daemon, and daemons in the wild lag behind new app releases. Both directions must work. Every schema change MUST be backward-compatible: + - New fields: always `.optional()` with a sensible default or `.transform()` fallback. + - Never change a field from optional to required. + - Never remove a field — deprecate it (keep accepting it, stop sending it). + - Never narrow a field's type (e.g. `string` → `enum`, `nullable` → non-null). + - Test with: "does a 6-month-old client still parse this?" and "does a 6-month-old daemon still send something this client accepts?" ## Debugging diff --git a/packages/server/src/shared/messages.ts b/packages/server/src/shared/messages.ts index 5dcd0b00a..9e256dbf2 100644 --- a/packages/server/src/shared/messages.ts +++ b/packages/server/src/shared/messages.ts @@ -1607,35 +1607,50 @@ export const ArtifactMessageSchema = z.object({ }), }); -export const ProjectCheckoutLiteNotGitPayloadSchema = z.object({ - cwd: z.string(), - isGit: z.literal(false), - currentBranch: z.null(), - remoteUrl: z.null(), - worktreeRoot: z.null(), - isPaseoOwnedWorktree: z.literal(false), - mainRepoRoot: z.null(), -}); +export const ProjectCheckoutLiteNotGitPayloadSchema = z + .object({ + cwd: z.string(), + isGit: z.literal(false), + currentBranch: z.null(), + remoteUrl: z.null(), + worktreeRoot: z.null().optional(), + isPaseoOwnedWorktree: z.literal(false), + mainRepoRoot: z.null(), + }) + .transform((value) => ({ + ...value, + worktreeRoot: null, + })); -export const ProjectCheckoutLiteGitNonPaseoPayloadSchema = z.object({ - cwd: z.string(), - isGit: z.literal(true), - currentBranch: z.string().nullable(), - remoteUrl: z.string().nullable(), - worktreeRoot: z.string(), - isPaseoOwnedWorktree: z.literal(false), - mainRepoRoot: z.null(), -}); +export const ProjectCheckoutLiteGitNonPaseoPayloadSchema = z + .object({ + cwd: z.string(), + isGit: z.literal(true), + currentBranch: z.string().nullable(), + remoteUrl: z.string().nullable(), + worktreeRoot: z.string().optional(), + isPaseoOwnedWorktree: z.literal(false), + mainRepoRoot: z.null(), + }) + .transform((value) => ({ + ...value, + worktreeRoot: value.worktreeRoot ?? value.cwd, + })); -export const ProjectCheckoutLiteGitPaseoPayloadSchema = z.object({ - cwd: z.string(), - isGit: z.literal(true), - currentBranch: z.string().nullable(), - remoteUrl: z.string().nullable(), - worktreeRoot: z.string(), - isPaseoOwnedWorktree: z.literal(true), - mainRepoRoot: z.string(), -}); +export const ProjectCheckoutLiteGitPaseoPayloadSchema = z + .object({ + cwd: z.string(), + isGit: z.literal(true), + currentBranch: z.string().nullable(), + remoteUrl: z.string().nullable(), + worktreeRoot: z.string().optional(), + isPaseoOwnedWorktree: z.literal(true), + mainRepoRoot: z.string(), + }) + .transform((value) => ({ + ...value, + worktreeRoot: value.worktreeRoot ?? value.cwd, + })); export const ProjectCheckoutLitePayloadSchema = z.union([ ProjectCheckoutLiteNotGitPayloadSchema, diff --git a/packages/server/src/shared/messages.workspaces.test.ts b/packages/server/src/shared/messages.workspaces.test.ts index 3f62d3a60..18085890e 100644 --- a/packages/server/src/shared/messages.workspaces.test.ts +++ b/packages/server/src/shared/messages.workspaces.test.ts @@ -50,4 +50,71 @@ describe("workspace message schemas", () => { expect(result.success).toBe(false); }); + + test("parses legacy fetch_agents_response checkout payloads without worktreeRoot", () => { + const result = SessionOutboundMessageSchema.safeParse({ + type: "fetch_agents_response", + payload: { + requestId: "req-1", + entries: [ + { + agent: { + id: "agent-1", + provider: "codex", + cwd: "C:\\repo", + model: null, + features: [], + thinkingOptionId: null, + effectiveThinkingOptionId: null, + createdAt: "2026-04-04T00:00:00.000Z", + updatedAt: "2026-04-04T00:00:00.000Z", + lastUserMessageAt: null, + status: "running", + capabilities: { + supportsStreaming: true, + supportsSessionPersistence: true, + supportsDynamicModes: true, + supportsMcpServers: true, + supportsReasoningStream: true, + supportsToolInvocations: true, + }, + currentModeId: null, + availableModes: [], + pendingPermissions: [], + persistence: null, + title: "Agent 1", + labels: {}, + requiresAttention: false, + attentionReason: null, + }, + project: { + projectKey: "remote:github.com/acme/repo", + projectName: "acme/repo", + checkout: { + cwd: "C:\\repo", + isGit: true, + currentBranch: "main", + remoteUrl: "https://github.com/acme/repo.git", + isPaseoOwnedWorktree: false, + mainRepoRoot: null, + }, + }, + }, + ], + pageInfo: { + nextCursor: null, + prevCursor: null, + hasMore: false, + }, + }, + }); + + expect(result.success).toBe(true); + if (!result.success) { + return; + } + + const checkout = result.data.payload.entries[0]?.project.checkout; + expect(checkout?.worktreeRoot).toBe("C:\\repo"); + }); });