The best way to control Claude Code, Codex and more from any computer or phone
fix(web): terminal file links preserve numeric filename suffixes (#37201)
Co-authored-by: Grok 4.7 <noreply@x.ai> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Wout Stiens committed
Nov 15, 2026 at 14:01 UTC
304cf149c8cb5e2c1ab921428773361752d7aff2
9 files changed
+253
-30
apps/server/src/process/externalLauncher.test.ts
+42
-5
@@ -117,8 +117,8 @@ it.effect.skipIf(windowsHost)("opens home-relative targets using the server home
117
const spawned: ChildProcess.StandardCommand[] = [];
118
yield* Effect.gen(function* () {
119
const launcher = yield* ExternalLauncher.ExternalLauncher;
120
- for (const cwd of ["~/Applications/My App.app", "/Applications/My App.app"]) {
121
- yield* launcher.launchEditor({ editor: "file-manager", cwd });
120
+ for (const cwd of ["~/Applications/My App.app", "/Applications/My App.app", "/tmp/a:12"]) {
121
+ yield* launcher.launchEditor({ editor: "file-manager", cwd, position: { line: 5 } });
122
}
123
yield* launcher.launchEditor({ editor: "vscode", cwd: "~/notes/todo.md:3" });
124
yield* launcher.launchEditor({
@@ -141,6 +141,7 @@ it.effect.skipIf(windowsHost)("opens home-relative targets using the server home
141
[
142
["/Users/server/Applications/My App.app"],
143
["/Applications/My App.app"],
144
+ ["/tmp/a:12"],
145
["--goto", "/Users/server/notes/todo.md:3"],
146
["/Users/server/notes", "--line", "3", "/Users/server/notes/todo.md"],
147
],
@@ -203,12 +204,20 @@ it.effect.skipIf(windowsHost)(
204
const path = yield* Path.Path;
205
const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
206
const project = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-project-" });
206
- const codePath = path.join(binDir, "code");
207
- yield* fileSystem.writeFileString(codePath, "#!/bin/sh\n");
208
- yield* fileSystem.chmod(codePath, 0o755);
207
+ for (const name of ["code", "zeditor", "idea"]) {
208
+ const executable = path.join(binDir, name);
209
+ yield* fileSystem.writeFileString(executable, "#!/bin/sh\n");
210
+ yield* fileSystem.chmod(executable, 0o755);
211
+ }
212
const colonProject = path.join(project, "build:2026");
213
yield* fileSystem.makeDirectory(colonProject);
214
const file = `${path.join(project, "file.ts")}:3:7`;
215
+ const exactFile = path.join(project, "a:12");
216
+ yield* fileSystem.writeFileString(exactFile, "exact");
217
+ yield* fileSystem.makeDirectory(`${exactFile}:1:1`);
218
+ const positionedFile = path.join(project, "position.txt");
219
+ yield* fileSystem.writeFileString(positionedFile, "position");
220
+ yield* fileSystem.writeFileString(`${positionedFile}:7`, "collision");
221
222
const spawned: ChildProcess.StandardCommand[] = [];
223
yield* Effect.gen(function* () {
@@ -216,6 +225,27 @@ it.effect.skipIf(windowsHost)(
225
yield* launcher.launchEditor({ editor: "vscode", cwd: project });
226
yield* launcher.launchEditor({ editor: "vscode", cwd: file });
227
yield* launcher.launchEditor({ editor: "vscode", cwd: colonProject });
228
+ for (const position of [{}, { line: 5 }]) {
229
+ yield* launcher.launchEditor({ editor: "vscode", cwd: exactFile, position });
230
+ }
231
+
232
+ yield* launcher.launchEditor({ editor: "zed", cwd: exactFile, position: {} });
233
+ yield* launcher.launchEditor({
234
+ editor: "zed",
235
+ cwd: positionedFile,
236
+ position: { line: 5, column: 3 },
237
+ });
238
+ yield* launcher.launchEditor({ editor: "zed", cwd: positionedFile, position: { line: 7 } });
239
+ yield* launcher.launchEditor({
240
+ editor: "vscode",
241
+ cwd: `${project}/exponent:1e3`,
242
+ position: { line: 5 },
243
+ });
244
+ yield* launcher.launchEditor({
245
+ editor: "idea",
246
+ cwd: exactFile,
247
+ position: { line: 5, column: 3 },
248
+ });
249
}).pipe(
250
Effect.provide(
251
layerTest({
@@ -233,6 +263,13 @@ it.effect.skipIf(windowsHost)(
263
["--new-window", project],
264
["--goto", file],
265
["--new-window", colonProject],
266
+ [exactFile],
267
+ [exactFile],
268
+ [exactFile],
269
+ [`${positionedFile}:5:3`],
270
+ [positionedFile],
271
+ [`${project}/exponent:1e3`],
272
+ ["--line", "5", "--column", "2", exactFile],
273
],
274
);
275
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
apps/server/src/process/externalLauncher.ts
+37
-6
@@ -142,17 +142,37 @@ function resolveCommandEditorArgs(
142
target: string,
143
isDirectory: boolean,
144
projectRoot: string | undefined,
145
+ position: LaunchEditorInput["position"],
146
): ReadonlyArray<string> {
146
- const parsedTarget = parseTargetPathAndPosition(target);
147
+ const parsedTarget =
148
+ position === undefined
149
+ ? parseTargetPathAndPosition(target)
150
+ : Option.fromUndefinedOr(position.line).pipe(
151
+ Option.map((line) => ({
152
+ path: target,
153
+ line: String(line),
154
+ column: Option.fromUndefinedOr(position.column).pipe(Option.map(String)),
155
+ })),
156
+ );
157
+ const positionedTarget = Option.match(parsedTarget, {
158
+ onNone: () => target,
159
+ onSome: ({ path, line, column }) => [path, line, ...Option.toArray(column)].join(":"),
160
+ });
161
162
switch (editor.launchStyle) {
163
case "direct-path":
150
- return [target];
164
+ return [positionedTarget];
165
case "goto":
166
// An existing folder wins over a position: `build:2026` is a legal folder name.
167
// Without a window flag, VS Code's window settings may replace the user's last active window.
168
if (isDirectory) return ["--new-window", target];
155
- return Option.isSome(parsedTarget) ? ["--goto", target] : [target];
169
+ // VS Code splits every numeric colon segment, including ones inside the filename.
170
+ if (
171
+ position !== undefined &&
172
+ target.split(":").some((segment) => !Number.isNaN(Number(segment)))
173
+ )
174
+ return [target];
175
+ return Option.isSome(parsedTarget) ? ["--goto", positionedTarget] : [target];
176
case "line-column":
177
return Option.match(parsedTarget, {
178
onNone: () => [target],
@@ -526,6 +546,18 @@ const resolveEditorLaunch = Effect.fn("resolveEditorLaunch")(function* (
546
return yield* new ExternalLauncherUnknownEditorError({ editor: input.editor });
547
}
548
549
+ const target = input.cwd;
550
+ let position = input.position;
551
+ if (editorDef.id === "zed" && position?.line !== undefined) {
552
+ // Zed resolves existing paths before positions, so ambiguous spellings must stay literal.
553
+ const collision =
554
+ /:\d+(?=:|$)/.test(target) ||
555
+ (yield* (yield* FileSystem.FileSystem)
556
+ .exists(`${target}:${position.line}${position.column ? `:${position.column}` : ""}`)
557
+ .pipe(Effect.orElseSucceed(() => true)));
558
+ if (collision) position = {};
559
+ }
560
+
561
if (editorDef.commands) {
562
const resolved = yield* resolveEditorCommand(editorDef, env);
563
if (Option.isNone(resolved)) {
@@ -537,7 +569,7 @@ const resolveEditorLaunch = Effect.fn("resolveEditorLaunch")(function* (
569
const { command, baseArgs } = resolved.value;
570
const isDirectory =
571
editorDef.launchStyle === "goto" &&
540
- (yield* (yield* FileSystem.FileSystem).stat(input.cwd).pipe(
572
+ (yield* (yield* FileSystem.FileSystem).stat(target).pipe(
573
Effect.map((info) => info.type === "Directory"),
574
Effect.orElseSucceed(() => false),
575
));
@@ -547,7 +579,7 @@ const resolveEditorLaunch = Effect.fn("resolveEditorLaunch")(function* (
579
command,
580
args: [
581
...baseArgs,
550
- ...resolveCommandEditorArgs(editorDef, input.cwd, isDirectory, input.projectRoot),
582
+ ...resolveCommandEditorArgs(editorDef, target, isDirectory, input.projectRoot, position),
583
],
584
};
585
}
@@ -561,7 +593,6 @@ const resolveEditorLaunch = Effect.fn("resolveEditorLaunch")(function* (
593
return yield* new ExternalLauncherUnsupportedEditorError({ editor: input.editor });
594
}
595
564
- const target = input.cwd;
596
if (input.reveal === true) {
597
return yield* resolveFileManagerRevealLaunch(target, platform, env, command);
598
}
apps/web/src/editorPreferences.test.ts
+22
@@ -88,3 +88,25 @@ it.each(["read", "write"] as const)(
88
});
89
},
90
);
91
+
92
+it.each([
93
+ ["file:///work/read%20me.md", "/work/read me.md", {}],
94
+ [
95
+ "file://foreign/share/read%20me.md:12#L5",
96
+ String.raw`\\foreign\share\read me.md:12`,
97
+ { line: 5 },
98
+ ],
99
+ ["file:///work/report.txt:12", "/work/report.txt:12", {}],
100
+ ["file:///work/report.txt:12#L5C3", "/work/report.txt:12", { line: 5, column: 3 }],
101
+])(
102
+ "sends a plain exact path for %s to compatible and older servers",
103
+ async (uri, cwd, position) => {
104
+ state.allowed.add(secondary);
105
+ const open = useOpenInPreferredEditor(secondary, ["vscode"]);
106
+ await open(uri);
107
+ expect(state.run).toHaveBeenCalledExactlyOnceWith({
108
+ environmentId: secondary,
109
+ input: { cwd, position, editor: "vscode" },
110
+ });
111
+ },
112
+);
apps/web/src/editorPreferences.ts
+6
-1
@@ -10,6 +10,8 @@ import {
10
type AtomCommandFailure,
11
type AtomCommandResult,
12
} from "@t3tools/client-runtime/state/runtime";
13
+import { parseFileUrlHref, splitFilePathPosition } from "@t3tools/shared/fileLinks";
14
+import { safeDecodeURIComponent } from "@t3tools/shared/markdownLinks";
15
import * as Cause from "effect/Cause";
16
import * as Schema from "effect/Schema";
17
import { AsyncResult } from "effect/reactivity";
@@ -127,10 +129,13 @@ export function useOpenInPreferredEditor(
129
),
130
);
131
}
132
+ const uri = /^file:\/\//iu.test(targetPath) ? parseFileUrlHref(targetPath) : null;
133
+ const { line, column } = uri ? splitFilePathPosition("", uri.hash) : {};
134
const result = await openInEditor({
135
environmentId,
136
input: {
133
- cwd: targetPath,
137
+ cwd: uri ? safeDecodeURIComponent(uri.path) : targetPath,
138
+ ...(uri ? { position: { line, column } } : {}),
139
editor,
140
...(projectRoot ? { projectRoot } : {}),
141
},
apps/web/src/hooks/useFileMetadata.ts
+12
-2
@@ -3,12 +3,17 @@ import {
3
type EnvironmentId,
4
type ScopedThreadRef,
5
} from "@t3tools/contracts";
6
-import { resolvePathLinkTarget, splitFilePathPosition } from "@t3tools/shared/fileLinks";
6
+import {
7
+ parseFileUrlHref,
8
+ resolvePathLinkTarget,
9
+ splitFilePathPosition,
10
+} from "@t3tools/shared/fileLinks";
11
import {
12
isAbsolutePath,
13
isNetworkPath,
14
normalizeProjectPathForComparison,
15
} from "@t3tools/shared/path";
16
+import { safeDecodeURIComponent } from "@t3tools/shared/markdownLinks";
17
import { useContext } from "react";
18
19
import { useEnvironmentScope } from "../state/session";
@@ -22,9 +27,14 @@ export function getFileMetadataQueryAtom(
27
cwd?: string,
28
threadRef?: ScopedThreadRef | null,
29
) {
30
+ const uri = /^file:\/\//iu.test(path) ? parseFileUrlHref(path) : null;
31
const hostPath = splitFilePathPosition(path).path;
32
const targetPath = normalizeProjectPathForComparison(
27
- hostPath.startsWith("~/") || !cwd ? hostPath : resolvePathLinkTarget(hostPath, cwd),
33
+ uri
34
+ ? safeDecodeURIComponent(uri.path)
35
+ : hostPath.startsWith("~/") || !cwd
36
+ ? hostPath
37
+ : resolvePathLinkTarget(hostPath, cwd),
38
);
39
const absolute = isAbsolutePath(targetPath) || targetPath.startsWith("~/");
40
return (
apps/web/src/terminal-links.test.ts
+22
-1
@@ -351,11 +351,32 @@ describe("resolvePathLinkTarget", () => {
351
// regression: #36005 OSC 8 file URIs were joined onto the cwd as relative paths
352
it("does not resolve an OSC 8 file URI target against the cwd", () => {
353
expect(resolveTerminalLinkTarget("file:///var/tmp/report.txt", "/workspace/project")).toBe(
354
- "/var/tmp/report.txt",
354
+ "file:///var/tmp/report.txt",
355
);
356
expect(
357
resolveTerminalLinkTarget("file://remote.invalid/var/tmp/report.txt", "/workspace/project"),
358
).not.toMatch(/^\/workspace\/project\//);
359
+ expect(
360
+ resolveTerminalLinkTarget(
361
+ "file://myhost/var/tmp/report.txt:12#L5",
362
+ "/workspace/project",
363
+ "myhost",
364
+ ),
365
+ ).toBe("file:///var/tmp/report.txt:12#L5");
366
+ expect(
367
+ resolveTerminalLinkTarget(
368
+ "file://foreign/var/tmp/report.txt:12#L5",
369
+ "/workspace/project",
370
+ "myhost",
371
+ ),
372
+ ).toBe("file://foreign/var/tmp/report.txt:12#L5");
373
+ for (const name of ["report.txt:12-64", "report.txt:0", "report.txt:12"]) {
374
+ const uri = `file:///var/tmp/${encodeURIComponent(name)}`;
375
+ expect(resolveTerminalLinkTarget(uri, "/workspace/project")).toBe(uri);
376
+ }
377
+ expect(
378
+ resolveTerminalLinkTarget("file:///var/tmp/report.txt:12#L5", "/workspace/project"),
379
+ ).toBe("file:///var/tmp/report.txt:12#L5");
380
expect(resolvePathLinkTarget("file:notes.md", "/workspace/project")).toBe(
381
"/workspace/project/file:notes.md",
382
);
apps/web/src/terminal-links.ts
+6
-14
@@ -1,11 +1,4 @@
1
-import {
2
- formatFilePathPosition,
3
- parseFileUrlHref,
4
- resolvePathLinkTarget,
5
- splitFilePathPosition,
6
-} from "@t3tools/shared/fileLinks";
7
-import { safeDecodeURIComponent } from "@t3tools/shared/markdownLinks";
8
-import { stripSlashPrefixedWindowsDrive } from "@t3tools/shared/path";
1
+import { parseFileUrlHref, resolvePathLinkTarget } from "@t3tools/shared/fileLinks";
2
import { isMacPlatform } from "./lib/utils";
3
4
export type TerminalLinkKind = "url" | "path";
@@ -165,16 +158,15 @@ export function isTerminalUrl(value: string): boolean {
158
/**
159
* Explicit OSC 8 targets may be `file://` URIs; everything else is a path relative to `cwd`.
160
* `hostname` is the terminal's environment's, which producers such as GNU `ls` put in the URI.
161
+ * A URI's path is the exact filename, so only its `#L12C3` hash is a position.
162
*/
163
export function resolveTerminalLinkTarget(text: string, cwd: string, hostname?: string): string {
164
const fileUrl = /^file:\/\//iu.test(text) ? parseFileUrlHref(text, hostname) : null;
165
if (!fileUrl) return resolvePathLinkTarget(text, cwd);
172
- return formatFilePathPosition(
173
- splitFilePathPosition(
174
- stripSlashPrefixedWindowsDrive(safeDecodeURIComponent(fileUrl.path)),
175
- fileUrl.hash,
176
- ),
177
- );
166
+ // Keep URI identity until consumers decode the filename, separately from its position.
167
+ const uri = new URL(text);
168
+ if (!fileUrl.path.startsWith("\\")) uri.hostname = "";
169
+ return uri.href;
170
}
171
172
export function collectWrappedTerminalLinkLine(
packages/contracts/src/editor.ts
+8
-1
@@ -1,5 +1,5 @@
1
import * as Schema from "effect/Schema";
2
-import { TrimmedNonEmptyString } from "./baseSchemas.ts";
2
+import { PositiveInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
3
4
export const EditorLaunchStyle = Schema.Literals(["direct-path", "goto", "line-column"]);
5
export type EditorLaunchStyle = typeof EditorLaunchStyle.Type;
@@ -157,6 +157,13 @@ export type FileManagerRevealKind = typeof FileManagerRevealKind.Type;
157
export const LaunchEditorInput = Schema.Struct({
158
cwd: TrimmedNonEmptyString,
159
editor: EditorId,
160
+ /** When present, cwd is an exact path; {} opens it without a position. Omit for diagnostic suffix parsing. */
161
+ position: Schema.optional(
162
+ Schema.Struct({
163
+ line: Schema.optional(PositiveInt),
164
+ column: Schema.optional(PositiveInt),
165
+ }),
166
+ ),
167
/** Workspace the target belongs to; JetBrains IDEs open positioned files in this project. */
168
projectRoot: Schema.optional(TrimmedNonEmptyString),
169
/** Only for file-manager; requires the server's shellRevealInFileManager capability. */
scripts/scenarios/terminal-file-uri-opens-its-exact-file.e2e.ts
new
+98
@@ -0,0 +1,98 @@
1
+/// <reference lib="dom" />
2
+// The DOM lib types the function this scenario runs in the page.
3
+import { expect } from "e2e";
4
+import * as Effect from "effect/Effect";
5
+import * as FileSystem from "effect/FileSystem";
6
+
7
+import { T3_HOME } from "../e2e.config.ts";
8
+import { runPromise, test, WEB } from "./t3.ts";
9
+
10
+const EDITOR_ARGS = `${T3_HOME}/editor-args.txt`;
11
+
12
+/** The file's lines, or none while it does not exist. */
13
+const readLines = (file: string) =>
14
+ runPromise(
15
+ Effect.gen(function* () {
16
+ const fs = yield* FileSystem.FileSystem;
17
+ if (!(yield* fs.exists(file))) return [];
18
+ return (yield* fs.readFileString(file)).trim().split("\n");
19
+ }),
20
+ );
21
+
22
+const removeEditorArgs = () =>
23
+ runPromise(
24
+ Effect.flatMap(FileSystem.FileSystem, (fs) => fs.remove(EDITOR_ARGS, { force: true })),
25
+ );
26
+
27
+// GNU ls, made hostless, for filenames that end like a position.
28
+const listed = (name: string) =>
29
+ `command ls -d --hyperlink=always --color=never -1 --quoting-style=literal -- '${name}' | sed -E 's@file://[^/]+/@file:///@'`;
30
+// An opaque label, so only the URI can name the file.
31
+const hashed = (uriPath: string) =>
32
+ `printf '\\033]8;;file://%s\\033\\\\CLICKME\\033]8;;\\033\\\\\\n' "$PWD/${uriPath}"`;
33
+
34
+const LINKS = [
35
+ { print: listed("report.txt:12-64"), opens: ["report.txt:12-64"] },
36
+ { print: listed("zero.txt:0"), opens: ["zero.txt:0"] },
37
+ { print: hashed("numeric.txt%3A12#L5"), opens: ["numeric.txt:12"] },
38
+ { print: hashed("position.txt#L5C3"), opens: ["--goto", "position.txt:5:3"] },
39
+ { print: listed("build:2026"), opens: ["--new-window", "build:2026"] },
40
+];
41
+
42
+test(
43
+ "Ctrl+click on a terminal file URI opens the exact file it names, even one ending like a position",
44
+ WEB,
45
+ async ({ t3, app, browser, screen }) => {
46
+ await removeEditorArgs();
47
+ const files: Record<string, string> = {
48
+ "build:2026/keep.txt": "keep\n",
49
+ "numeric.txt:12:1:1/keep.txt": "decoy\n",
50
+ };
51
+ for (const name of ["report.txt:12-64", "zero.txt:0", "numeric.txt:12", "position.txt"]) {
52
+ files[name] = `${name}\n`;
53
+ }
54
+ // Enough rows to scroll, so every row is the link. Scripts keep the typed commands short.
55
+ for (const [index, link] of LINKS.entries()) {
56
+ files[`print-${index}.sh`] =
57
+ `for i in $(seq 1 100); do ${link.print}; done; touch printed-${index}\n`;
58
+ }
59
+ const project = await t3.project("demo", files);
60
+ const thread = await t3.thread({ project, title: "List", messages: ["List it"] });
61
+ await t3.open(thread);
62
+
63
+ await screen.getByRole("button", "Toggle terminal drawer").tap();
64
+ const input = screen.getByRole("textbox", "Terminal input");
65
+ // The input mounts before fonts and WASM finish loading and its handlers are installed.
66
+ await expect(input).toHaveAttribute("data-workspace-focus-default", "");
67
+
68
+ for (const [index, { opens }] of LINKS.entries()) {
69
+ await removeEditorArgs();
70
+ await input.focus();
71
+ await browser.keyboard.type(`bash print-${index}.sh\n`);
72
+ await expect
73
+ .poll(() => readLines(`${project}/printed-${index}`), { timeout: 30_000 })
74
+ .toEqual([""]);
75
+ await app.screenshot(`printed-${index}`);
76
+
77
+ // The terminal draws on a canvas, so point at the first cells of a row near its middle.
78
+ const canvas = await browser.evaluate(() => {
79
+ const box = document
80
+ .querySelector('[aria-label="Terminal input"]')
81
+ ?.parentElement?.querySelector("canvas")
82
+ ?.getBoundingClientRect();
83
+ return box ? { x: box.x, y: box.y, width: box.width, height: box.height } : null;
84
+ });
85
+ if (!canvas) throw new Error("The terminal canvas is not on the page.");
86
+ // Alternate rows, or a quick second click on the same spot counts as a double-click.
87
+ await browser.mouse.move(canvas.x + 16, canvas.y + canvas.height / 2 - (index % 2) * 40);
88
+ await browser.keyboard.down("Control");
89
+ await browser.mouse.down();
90
+ await browser.mouse.up();
91
+ await browser.keyboard.up("Control");
92
+
93
+ await expect
94
+ .poll(() => readLines(EDITOR_ARGS), { timeout: 15_000 })
95
+ .toEqual(["--classic", ...opens.slice(0, -1), `${project}/${opens.at(-1)}`]);
96
+ }
97
+ },
98
+);