@devries-cameron20 / t3code-1 / commits / 6d35d09060
Fork 0

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

fix(cli): t3 triage points at the prompt when the agent fails to start (#28192)

Julius Marminge committed Nov 11, 2026 at 16:11 UTC 6d35d09060a901d15e31ab7ccdeedfe6696c23c5
2 files changed +123 -7
apps/server/src/cli/triage.test.ts new
+75
@@ -0,0 +1,75 @@
1 +// @effect-diagnostics nodeBuiltinImport:off - CLI integration spawns a fake agent from PATH.
2 +import * as NodeFS from "node:fs";
3 +import * as NodePath from "node:path";
4 +
5 +import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
6 +import * as NodeServices from "@effect/platform-node/NodeServices";
7 +import { TRIAGE_PROMPT_FILE_NAME } from "@t3tools/contracts";
8 +import * as NetService from "@t3tools/shared/Net";
9 +import { assert, it } from "@effect/vitest";
10 +import * as Effect from "effect/Effect";
11 +import * as FileSystem from "effect/FileSystem";
12 +import * as Layer from "effect/Layer";
13 +import * as TestConsole from "effect/testing/TestConsole";
14 +import { Command } from "effect/cli";
15 +import { vi } from "vite-plus/test";
16 +
17 +import { cli } from "../binCli.ts";
18 +import { buildTriageLaunchPrompt } from "../triage/triagePrompt.ts";
19 +
20 +const FAILING_AGENT_POSIX = `#!/bin/sh
21 +echo "Error: There is not enough space on the disk. (os error 112)" >&2
22 +exit 1
23 +`;
24 +const FAILING_AGENT_WINDOWS = `@echo Error: There is not enough space on the disk. (os error 112) 1>&2
25 +@exit /b 1
26 +`;
27 +
28 +it.live("a failed agent launch points at the prompt it could not run", () =>
29 + Effect.gen(function* () {
30 + const fs = yield* FileSystem.FileSystem;
31 + const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-triage-cli-" });
32 + const binDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-triage-bin-" });
33 + const codexHome = NodePath.join(baseDir, "codex-home");
34 + NodeFS.writeFileSync(NodePath.join(binDir, "codex"), FAILING_AGENT_POSIX, { mode: 0o755 });
35 + NodeFS.writeFileSync(NodePath.join(binDir, "codex.cmd"), FAILING_AGENT_WINDOWS);
36 + yield* Effect.acquireRelease(
37 + // PATH holds only the fake agent, so a broken fixture can never fall through to a real codex.
38 + Effect.sync(() => {
39 + vi.stubEnv("PATH", binDir);
40 + vi.stubEnv("CODEX_HOME", codexHome);
41 + }),
42 + () => Effect.sync(() => vi.unstubAllEnvs()),
43 + );
44 + const previousExitCode = process.exitCode;
45 + yield* Effect.addFinalizer(() =>
46 + Effect.sync(() => {
47 + process.exitCode = previousExitCode;
48 + }),
49 + );
50 +
51 + yield* Command.runWith(cli, { version: "0.0.0" })([
52 + "triage",
53 + "--agent",
54 + "codex",
55 + "--base-dir",
56 + baseDir,
57 + ]);
58 + const output = (yield* TestConsole.logLines).join("\n");
59 +
60 + assert.equal(process.exitCode, 1);
61 + const promptFilePath = NodeFS.readdirSync(baseDir, { recursive: true, encoding: "utf8" })
62 + .filter((entry) => NodePath.basename(entry) === TRIAGE_PROMPT_FILE_NAME)
63 + .map((entry) => NodePath.join(baseDir, entry))[0];
64 + assert.isDefined(promptFilePath);
65 + assert.include(output, promptFilePath);
66 + assert.include(output, buildTriageLaunchPrompt(promptFilePath));
67 + assert.include(output, NodePath.join(NodePath.dirname(promptFilePath), "context.md"));
68 + assert.include(output, `Codex keeps its state in ${codexHome}.`);
69 + assert.include(output, "set CODEX_HOME to a folder on another drive");
70 + }).pipe(
71 + Effect.provide(
72 + Layer.mergeAll(NodeServices.layer, NodeCrypto.layer, NetService.layer, TestConsole.layer),
73 + ),
74 + ),
75 +);
apps/server/src/cli/triage.ts
+48 -7
@@ -1,5 +1,7 @@
1 // @effect-diagnostics nodeBuiltinImport:off
2 import * as NodeChildProcess from "node:child_process";
3 +import * as NodeOS from "node:os";
4 +import * as NodePath from "node:path";
5 import * as NodeReadlinePromises from "node:readline/promises";
6
7 import { isCommandAvailable, resolveSpawnCommand } from "@t3tools/shared/shell";
@@ -23,13 +25,30 @@ interface TriageAgent {
25 readonly id: "claude" | "codex";
26 readonly command: string;
27 readonly label: string;
28 + readonly stateDirEnv: string;
29 + readonly defaultStateDir: string;
30 }
31
32 const TRIAGE_AGENTS: ReadonlyArray<TriageAgent> = [
29 - { id: "claude", command: "claude", label: "Claude Code" },
30 - { id: "codex", command: "codex", label: "Codex" },
33 + {
34 + id: "claude",
35 + command: "claude",
36 + label: "Claude Code",
37 + stateDirEnv: "CLAUDE_CONFIG_DIR",
38 + defaultStateDir: ".claude",
39 + },
40 + {
41 + id: "codex",
42 + command: "codex",
43 + label: "Codex",
44 + stateDirEnv: "CODEX_HOME",
45 + defaultStateDir: ".codex",
46 + },
47 ];
48
49 +const resolveAgentStateDir = (agent: TriageAgent) =>
50 + process.env[agent.stateDirEnv]?.trim() || NodePath.join(NodeOS.homedir(), agent.defaultStateDir);
51 +
52 export class TriageAgentUnavailableError extends Schema.TaggedError<TriageAgentUnavailableError>()(
53 "TriageAgentUnavailableError",
54 { agent: Schema.String },
@@ -102,6 +121,15 @@ const runInteractiveSession = (input: {
121 child.once("exit", (code, signal) => resume(Effect.succeed(code ?? (signal === null ? 0 : 1))));
122 });
123
124 +const describeTriageFiles = (session: {
125 + readonly promptFilePath: string;
126 + readonly contextFilePath: string;
127 +}) => [
128 + "The triage prompt and machine context were written to:",
129 + ` ${session.promptFilePath}`,
130 + ` ${session.contextFilePath}`,
131 +];
132 +
133 const agentFlag = Flag.Literals("agent", ["claude", "codex"]).pipe(
134 Flag.withDescription("Agent CLI to use. Default: ask when both are installed."),
135 Flag.optional,
@@ -164,16 +192,14 @@ export const triageCommand = Command.make("triage", {
192 }
193
194 // Windows .cmd shims cannot carry multiline argv; the prompt file also serves as the paste fallback.
167 - const { sessionDir, promptFilePath, contextFilePath } = session;
195 + const { sessionDir, promptFilePath } = session;
196
197 if (selected === undefined) {
198 yield* Console.log(
199 [
200 "No supported agent CLI (claude, codex) was found on this machine.",
201 "",
174 - "The triage prompt and machine context were written to:",
175 - ` ${promptFilePath}`,
176 - ` ${contextFilePath}`,
202 + ...describeTriageFiles(session),
203 "",
204 "Paste the prompt file into any coding agent to run triage by hand.",
205 ].join("\n"),
@@ -182,14 +208,29 @@ export const triageCommand = Command.make("triage", {
208 }
209
210 const model = Option.getOrUndefined(flags.model);
211 + const launchPrompt = buildTriageLaunchPrompt(promptFilePath);
212 const spawnSpec = yield* resolveSpawnCommand(selected.command, [
213 ...(model === undefined ? [] : ["--model", model]),
187 - buildTriageLaunchPrompt(promptFilePath),
214 + launchPrompt,
215 ]);
216 yield* Console.log(`Starting ${selected.label}. It will ask what went wrong.\n`);
217 const exitCode = yield* runInteractiveSession({ ...spawnSpec, cwd: sessionDir });
218 if (exitCode !== 0) {
219 process.exitCode = exitCode;
220 + yield* Console.log(
221 + [
222 + "",
223 + `${selected.label} exited with code ${String(exitCode)}.`,
224 + "",
225 + `${selected.label} keeps its state in ${resolveAgentStateDir(selected)}.`,
226 + `If that drive is out of space, free some up or set ${selected.stateDirEnv} to a folder on another drive.`,
227 + "",
228 + ...describeTriageFiles(session),
229 + "",
230 + `To retry, start \`${selected.command}\` yourself with any flags it suggested, or use any coding agent, and give it this prompt:`,
231 + launchPrompt,
232 + ].join("\n"),
233 + );
234 }
235 }),
236 ),