@devries-cameron20 / t3code-1 / commits / ae268d9350
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(server): a provider CLI that dies at startup names its exit and EPERM (#39299)

Julius Marminge committed Nov 19, 2026 at 12:24 UTC ae268d93502832ba49f5d0a2a6754c958a43d6e2
4 files changed +72 -9
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+42 -7
@@ -229,6 +229,7 @@ import {
229 makeProviderFailure,
230 makeProviderRetryTurnItem,
231 PROVIDER_RETRY_BUDGET_MS,
232 + providerProcessExitGuidance,
233 } from "@t3tools/provider-core/server/failure";
234 import { turnScopedSelectionTransition } from "@t3tools/provider-core/server/selectionTransition";
235 import { providerMessageTextWithAttachmentPaths } from "@t3tools/provider-core/server/attachmentPrompt";
@@ -798,6 +799,19 @@ export class ClaudeConversationNotFoundError extends Schema.TaggedError<ClaudeCo
799 }
800 }
801
802 +export class ClaudeCodeStartupExitError extends Schema.TaggedError<ClaudeCodeStartupExitError>()(
803 + "ClaudeCodeStartupExitError",
804 + {
805 + status: Schema.String,
806 + guidance: Schema.String,
807 + cause: Schema.Defect(),
808 + },
809 +) {
810 + override get message(): string {
811 + return `${this.status} before it started. ${this.guidance}`;
812 + }
813 +}
814 +
815 class ClaudeMcpRegistrationTimeoutError extends Schema.TaggedError<ClaudeMcpRegistrationTimeoutError>()(
816 "ClaudeMcpRegistrationTimeoutError",
817 { phase: Schema.Literals(["initialize", "setMcpServers"]) },
@@ -922,20 +936,26 @@ const CLAUDE_PROCESS_EXIT_ERROR_CLASSES: ReadonlySet<unknown> = new Set([
936 ]);
937
938 // The SDK's exit Error appends Claude's stderr tail to `message`; `telemetryMessage` omits it.
925 -function claudeProcessExitFailure(
926 - cause: Cause.Cause<ClaudeAgentSdkQueryRunnerError>,
927 -): { readonly message: string; readonly code: string } | undefined {
928 - const error = Cause.squash(cause);
929 - const sdkError = isClaudeAgentSdkQueryRunnerError(error) ? error.cause : error;
939 +function claudeProcessExit(
940 + sdkError: unknown,
941 +): { readonly status: string; readonly code: string } | undefined {
942 if (typeof sdkError !== "object" || sdkError === null) return undefined;
943 const { errorClass, telemetryMessage } = sdkError as Record<string, unknown>;
944 return typeof errorClass === "string" &&
945 CLAUDE_PROCESS_EXIT_ERROR_CLASSES.has(errorClass) &&
946 typeof telemetryMessage === "string"
935 - ? { message: `${telemetryMessage}.`, code: errorClass }
947 + ? { status: telemetryMessage, code: errorClass }
948 : undefined;
949 }
950
951 +function claudeProcessExitFailure(
952 + cause: Cause.Cause<ClaudeAgentSdkQueryRunnerError>,
953 +): { readonly message: string; readonly code: string } | undefined {
954 + const error = Cause.squash(cause);
955 + const exit = claudeProcessExit(isClaudeAgentSdkQueryRunnerError(error) ? error.cause : error);
956 + return exit === undefined ? undefined : { message: `${exit.status}.`, code: exit.code };
957 +}
958 +
959 function closeClaudeQuery(queryRuntime: ClaudeQuery) {
960 return Effect.try({
961 try: () => queryRuntime.close(),
@@ -1752,13 +1772,28 @@ export const layerQueryRunner: Layer.Layer<
1772 );
1773 }
1774 const refusedRoot = !answered && stderrTail.includes(CLAUDE_ROOT_REFUSAL);
1775 + const startupExit = answered ? undefined : claudeProcessExit(cause);
1776 + if (startupExit !== undefined) {
1777 + // The turn failure omits this output, so the log is the only place it is kept.
1778 + yield* Effect.logWarning("orchestration-v2.claude-startup-exit", {
1779 + threadId: input.threadId,
1780 + status: startupExit.status,
1781 + stderr: stderrTail,
1782 + });
1783 + }
1784 return yield* queryRunnerError(
1785 refusedRoot
1786 ? new ClaudeCodeRootRefusalError({ cause })
1787 : conversationMissing ||
1788 (!answered && stderrTail.includes(CLAUDE_CONVERSATION_NOT_FOUND))
1789 ? new ClaudeConversationNotFoundError({ cause })
1761 - : cause,
1790 + : startupExit !== undefined
1791 + ? new ClaudeCodeStartupExitError({
1792 + status: startupExit.status,
1793 + guidance: providerProcessExitGuidance(stderrTail),
1794 + cause,
1795 + })
1796 + : cause,
1797 "fromAsyncIterable",
1798 );
1799 }),
apps/server/src/orchestration-v2/Adapters/ClaudeAgentSdkQueryRunner.test.ts
+2
@@ -870,6 +870,8 @@ describe.skipIf(HostProcess.Platform.defaultValue() === "win32")("Claude CLI pro
870
871 const unknown = yield* startupFailureMessage("token=sk-private-123");
872 assert.notInclude(unknown, "sk-private-123");
873 + // The exit status carries no private text and tells the user the CLI itself died.
874 + assert.include(unknown, "Claude Code process exited with code 1");
875
876 const missingConversation = yield* startupFailureMessage(
877 "No conversation found with session ID: sk-private-123",
packages/provider-core/src/server/failure.test.ts
+10
@@ -163,6 +163,16 @@ it("names how the provider process exited and the stage it failed in, without it
163 makeProviderFailure({ cause: { _tag: "AcpProcessExitedError", code: 1 } }).message,
164 "The provider process exited with code 1. Check the server logs for the provider's output, then retry the turn.",
165 );
166 + const denied = makeProviderFailure({
167 + cause: {
168 + _tag: "CodexAppServerProcessExitedError",
169 + code: 1,
170 + stderr: "Error: Operation not permitted (os error 1) at /Users/private/Desktop",
171 + },
172 + }).message;
173 + assert.include(denied, "The provider process exited with code 1. It was denied access");
174 + assert.include(denied, "Files and Folders");
175 + assert.notInclude(denied, "/Users/private");
176 });
177
178 it("tells the user to sign in only when an ACP agent answers auth_required", () => {
packages/provider-core/src/server/failure.ts
+18 -2
@@ -67,6 +67,19 @@ const PROVIDER_FAILURE_CATEGORIES: Partial<
67 },
68 };
69
70 +// macOS privacy protection (TCC) refuses a CLI the project folder with EPERM.
71 +const PERMISSION_DENIED_OUTPUT = /\bEPERM\b|Operation not permitted/u;
72 +
73 +/**
74 + * What to do after a provider CLI exits on its own. Only recognises the
75 + * output; the output itself stays out of the message.
76 + */
77 +export function providerProcessExitGuidance(output: unknown): string {
78 + return typeof output === "string" && PERMISSION_DENIED_OUTPUT.test(output)
79 + ? "It was denied access to a file or folder (EPERM). On macOS, allow T3 Code under System Settings > Privacy & Security > Files and Folders, or move the project out of Desktop, Documents, or Downloads, then retry the turn."
80 + : "Check the server logs for the provider's output, then retry the turn.";
81 +}
82 +
83 // codex_protocol::protocol::validate_thread_goal_objective
84 const CODEX_GOAL_VALIDATION_MESSAGE =
85 /^goal objective must (?:not be empty|be at most \d{1,6} characters)$/u;
@@ -122,6 +135,7 @@ function curatedCauseMessages(cause: unknown): {
135 case "ClaudeSettingsLaunchArgError":
136 case "ClaudeMcpRegistrationTimeoutError":
137 case "ClaudeCodeRootRefusalError":
138 + case "ClaudeCodeStartupExitError":
139 case "ClaudeConversationNotFoundError":
140 case "CursorModelUnavailableError":
141 case "CodexGoalObjectiveTooLongError":
@@ -150,11 +164,13 @@ function curatedCauseMessages(cause: unknown): {
164 }
165 break;
166 }
153 - case "AcpProcessExitedError": {
167 + case "AcpProcessExitedError":
168 + case "CodexAppServerProcessExitedError": {
169 const exit = `provider process exited${processExitStatus(cause)}`;
170 const stage = category === undefined ? `The ${exit}` : `${category.summary}: the ${exit}`;
171 + const guidance = providerProcessExitGuidance((cause as Record<string, unknown>).stderr);
172 return {
157 - known: `${stage}. Check the server logs for the provider's output, then retry the turn.`,
173 + known: `${stage}. ${guidance}`,
174 category: categoryMessage(),
175 };
176 }