The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 06:00 UTC
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
}