litmus-cli 1.4.28 → 1.4.29

package/dist/commands/connect.js

@@ -1,13 +1,16 @@
 import os from "os";
 import path from "path";
 import readline from "readline";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "fs";
+import { randomBytes } from "crypto";
 import { execFileSync, spawn, spawnSync } from "child_process";
 import chalk from "chalk";
 import ora from "ora";
 import { fetchInitMetadata, startWorkspace, getConnection, fetchEditorChatConfig, ServerError, hintForError } from "../lib/api.js";
 import { applyEditorChatConfig } from "../lib/chat-model-config.js";
 import { resolveApiBase } from "../lib/api-base.js";
+import { editorInstallCandidates, editorSpawnSpec } from "../lib/editor-binary.js";
+import { parseEditorVersion, parseWorkspaceProbe, remoteProbeCommand, seedVerdict, verifyVerdict, VERIFY_SCHEDULE_MS, } from "../lib/editor-server.js";
 import { fatal, success, info, warn, setErrorContext } from "../lib/errors.js";
 import { editorEndingForewarning } from "../lib/session-end.js";
 /**
@@ -249,7 +252,26 @@ function writeSshConfig(alias, block, controlBlock) {
     writeFileSync(cfgPath, upsertSshConfigContent(existing, alias, block, controlBlock), { mode: 0o600 });
     return cfgPath;
 }
-const NATIVE_EDITORS = {
+/**
+ * The two editors, and the one place every measured difference between them lives.
+ *
+ * EXPORTED so the tests drive the SHIPPED record rather than literals they wrote
+ * themselves — an assertion against a fixture declared in the test file is a tautology,
+ * and `requiresSeedMatch`, `seedCommitPath` and `serverHomeDir` could all have been
+ * changed here with every test staying green.
+ *
+ * `seedCommitPath` and `serverHomeDir` are CROSS-TIER and their drift is silent: the
+ * first is `CACHE_ROOT` in `infra/codespaces-v2-image/scripts/install-{vscode,cursor}-
+ * server.sh`, the second the home subdir `litmus-firstboot.sh`'s `prewarm_editor` links
+ * into. A probe pointed at a path the image no longer writes reads "no seed" and "no
+ * logs" — which this module deliberately treats as missing inputs, so the launch
+ * proceeds unrefused and the verification stops being able to see a server. Nothing
+ * fails; the guarantee just quietly stops existing. `backend/tests/
+ * test_editor_server_paths.py` holds the pair, in pytest rather than vitest because the
+ * CLI suite is path-filtered on `cli/**` and an image-only edit is exactly the edit that
+ * has to fail.
+ */
+export const NATIVE_EDITORS = {
     vscode: {
         ide: "vscode",
         bin: "code",
@@ -257,6 +279,9 @@ const NATIVE_EDITORS = {
         label: "VS Code",
         remoteSshExt: "ms-vscode-remote.remote-ssh",
         shellCommand: "Shell Command: Install 'code' command",
+        seedCommitPath: "/opt/vscode-server-cache/COMMIT",
+        serverHomeDir: ".vscode-server",
+        requiresSeedMatch: false,
     },
     cursor: {
         ide: "cursor",
@@ -265,17 +290,61 @@ const NATIVE_EDITORS = {
         label: "Cursor",
         remoteSshExt: "anysphere.remote-ssh",
         shellCommand: "Shell Command: Install 'cursor' command",
+        seedCommitPath: "/opt/cursor-server-cache/COMMIT",
+        serverHomeDir: ".cursor-server",
+        requiresSeedMatch: true,
     },
 };
-function hasEditorCli(ed) {
+/**
+ * Can this command be RUN, and what build does it say it is — one spawn for both.
+ *
+ * `--version` exits 0 on both editors and prints three lines that name neither of them
+ * (see `NATIVE_EDITORS`), so this proves existence and a COMMIT and must never drift back
+ * into standing for an identity; `identifyEditorCli` is that, and it still runs `--help`
+ * against whatever this resolves to.
+ *
+ * ENG-2332 — it takes a COMMAND rather than `ed.bin`, because the command may be an
+ * absolute path inside the application bundle, and it goes through `editorSpawnSpec` so
+ * that a Windows `code.cmd` is probed the way it would be driven. Probing one way and
+ * driving another is how a check passes for a command that cannot actually be launched.
+ *
+ * It returns the VERSION rather than a boolean because an existence probe that discards
+ * stdout only to have the caller spawn the same command again for the same output is one
+ * subprocess and one 10s timeout on the critical path for nothing — and, worse, two
+ * readings that can disagree about which binary answered. Null is "cannot be run"; a
+ * record with null fields is "it ran and said nothing we could read", which is a missing
+ * input for `seedVerdict` and not an absent editor.
+ */
+function probeEditorCli(command) {
+    const spec = editorSpawnSpec(command, ["--version"], process.platform);
+    // No argv can drive this command on this platform (a `%` in the path, on Windows) — the
+    // same answer as a command that will not run. See `editorSpawnSpec`; throwing here is
+    // what aborted the connection for a candidate whose username contained a `%`.
+    if (!spec)
+        return null;
     try {
-        execFileSync(ed.bin, ["--version"], { stdio: "ignore" });
-        return true;
+        const probed = spawnSync(spec.command, spec.args, { encoding: "utf8", shell: spec.shell, timeout: 10000 });
+        if (probed.error || probed.status !== 0)
+            return null;
+        return parseEditorVersion(probed.stdout ?? null);
     }
     catch {
-        return false;
+        return null;
     }
 }
+function resolveEditorCommand(ed) {
+    const onPath = probeEditorCli(ed.bin);
+    if (onPath)
+        return { command: ed.bin, source: "path", version: onPath };
+    for (const candidate of editorInstallCandidates(ed.ide, process.platform, process.env, os.homedir())) {
+        if (!existsSync(candidate))
+            continue;
+        const version = probeEditorCli(candidate);
+        if (version)
+            return { command: candidate, source: "install-location", version };
+    }
+    return null;
+}
 /**
  * Map `--help` output to an editor we know, or null.
  *
@@ -314,11 +383,16 @@ export function identifyEditorBanner(helpOutput) {
  * stdout only — a chatty wrapper's stderr must not become an identity — and a timeout,
  * so a hung binary cannot wedge connect.
  */
-function runEditorHelp(bin) {
+function runEditorHelp(command) {
+    const spec = editorSpawnSpec(command, ["--help"], process.platform);
+    // Undrivable reads as "could not ask", which `identifyEditorCli` turns into
+    // `unverified` — the direction this probe is already required to fail in.
+    if (!spec)
+        return null;
     try {
-        const probed = spawnSync(bin, ["--help"], {
+        const probed = spawnSync(spec.command, spec.args, {
             encoding: "utf8",
-            shell: process.platform === "win32",
+            shell: spec.shell,
             timeout: 10000,
         });
         if (probed.error)
@@ -330,8 +404,8 @@ function runEditorHelp(bin) {
         return null;
     }
 }
-export function identifyEditorCli(ed, run = runEditorHelp) {
-    const out = run(ed.bin);
+export function identifyEditorCli(ed, command, run = runEditorHelp) {
+    const out = run(command);
     if (out === null)
         return { kind: "unverified" };
     const actual = identifyEditorBanner(out);
@@ -389,37 +463,552 @@ export function editorMismatchLines(chosen, actual, reentry = CURSOR_REENTRY_FAL
     lines.push("");
     return lines;
 }
+/**
+ * ENG-2332 — the refusal when the candidate's editor is a different build from the one
+ * this workspace has, and the route to the workspace that still works.
+ *
+ * It says what was compared and what it means, because "version mismatch" on its own
+ * reads as pedantry and a candidate mid-assessment will look for a way round it. What it
+ * must never do is offer one: there is no flag, no retry and no "open it anyway" here,
+ * since the thing on the other side of that door is a window that looks completely normal
+ * and records nothing (`lib/editor-server.ts` carries the measurement).
+ *
+ * The browser IDE leads, because it is the same container, the same files and the same
+ * capture, and it is the one route that cannot have this fault — it is served FROM the
+ * workspace rather than fetched INTO it. When the workspace publishes no URL the fallback
+ * is the terminal, which is a real way to work and not a consolation.
+ */
+export function editorSeedMismatchLines(ed, verdict, browserIdeUrl, alias) {
+    const short = (c) => c.slice(0, 12);
+    const width = Math.max(`Your ${ed.label}:`.length, "This workspace:".length) + 1;
+    const lines = [
+        "",
+        chalk.yellow.bold(`  ⚠  Your ${ed.label} is a different build from the one this workspace holds.`),
+        "",
+        `     ${`Your ${ed.label}:`.padEnd(width)}${verdict.clientVersion ?? "unknown version"} (${short(verdict.clientCommit)})`,
+        `     ${"This workspace:".padEnd(width)}${short(verdict.seedCommit)}`,
+        "",
+        `     ${ed.label} runs its own matching server inside the workspace, and downloads one`,
+        "     when the build does not match. This workspace has no route out to the internet,",
+        "     so that download cannot happen — and when it fails, a window still opens. It",
+        "     looks completely normal, it is not attached to your workspace, and anything you",
+        chalk.yellow("     do in it is not recorded."),
+        "",
+        `     So nothing has been opened. Your workspace is up and waiting — nothing is lost.`,
+        "",
+    ];
+    if (browserIdeUrl) {
+        lines.push("     Use the browser IDE instead — same workspace, same files, fully recorded:");
+        lines.push(`       ${chalk.cyan(browserIdeUrl)}`);
+        lines.push("");
+        lines.push(chalk.dim("     (It is also on your assessment page, so you do not need to keep this link.)"));
+    }
+    else {
+        lines.push("     Open your assessment page and use the browser IDE there — same workspace,");
+        lines.push("     same files, fully recorded. To work from a terminal instead:");
+        lines.push("");
+        lines.push(`       ${chalk.cyan(`ssh ${alias}`)}`);
+    }
+    lines.push("");
+    return lines;
+}
+/**
+ * ENG-2332 — what to say when the editor CLI cannot be found anywhere.
+ *
+ * The line this replaces offered `<bin> --remote ssh-remote+<alias> …` as the
+ * remediation for `<bin>` not existing. Everything here is something the candidate can do
+ * WITHOUT that command: the editor's own Remote-SSH picker (the alias is already in their
+ * `~/.ssh/config`), the palette command that would put the CLI on PATH, and the browser
+ * IDE, which needs nothing installed at all.
+ */
+export function editorNotFoundLines(ed, alias, browserIdeUrl) {
+    const lines = [
+        "",
+        chalk.yellow.bold(`  ⚠  Couldn't find ${ed.label}'s \`${ed.bin}\` command on this machine.`),
+        "",
+        `     It is not on your PATH and it is not where ${ed.label}'s installer puts it, so`,
+        "     nothing has been opened. Your workspace is up and waiting — nothing is lost.",
+        "",
+        `     Your SSH config is already written, so from inside ${ed.label} you can connect`,
+        "     with no command line at all:",
+        "",
+        `       Command Palette → ${chalk.bold("Remote-SSH: Connect to Host…")} → ${chalk.bold(alias)}`,
+        "",
+        `     (Needs the "${ed.remoteSshExt}" extension, which ${ed.label} will offer to install.)`,
+        "",
+        `     To get the \`${ed.bin}\` command for next time: in ${ed.label}, Command Palette →`,
+        `     "${ed.shellCommand}", then open a NEW terminal.`,
+    ];
+    if (browserIdeUrl) {
+        lines.push("");
+        lines.push("     Or skip the editor entirely — the browser IDE needs nothing installed:");
+        lines.push(`       ${chalk.cyan(browserIdeUrl)}`);
+    }
+    lines.push("");
+    return lines;
+}
+/**
+ * ENG-2332 — the positive signal, which the CLI had none of.
+ *
+ * It states exactly what was verified and not one step more. A server running in the
+ * workspace means the window is editing the container's files, so the file, terminal and
+ * commit lanes are live — that is what "recorded" may claim here.
+ *
+ * IT MAY NOT CLAIM AI CAPTURE ON CURSOR, and that is not hedging. Cursor reads its hooks
+ * configuration once, at application startup (ENG-1728, measured): a candidate who
+ * connected from an already-running Cursor has a live, correct, never-loaded hook, and
+ * their prompts are not recorded although everything else is. The verification above
+ * cannot see that — a server is up either way — so a flat "your work is being recorded"
+ * would be the same false reassurance this ticket is about, moved one lane along. The
+ * full notice is printed at selection time; this restates only the dependency.
+ */
+export function editorConnectedLines(ed, alias) {
+    const lines = [chalk.dim(`  Workspace: ${alias}:${REMOTE_WORKSPACE_DIR}`)];
+    if (ed.ide === "cursor") {
+        lines.push(chalk.dim("  Your AI prompts are recorded only if you quit Cursor completely before this opened;"));
+        lines.push(chalk.dim("  reloading the window or reconnecting does not load the hook."));
+    }
+    return lines;
+}
+/**
+ * ENG-2332 — what to say when a window opened and no server came up in the workspace.
+ *
+ * This is the copy the ticket was opened about. It used to be
+ * "If a new window doesn't appear, run litmus connect again" — which is wrong twice: a
+ * window DOES appear in this failure, and re-running connect cannot change the state,
+ * which is exactly what had the reporter run it four times. So it names what was
+ * observed, and every route it offers is one this failure does not block.
+ *
+ * `seed` rides along because on VS Code a mismatch is not a refusal (see
+ * `requiresSeedMatch`) — so when a VS Code launch does fail, the build difference is the
+ * first thing worth knowing, and it is already in hand.
+ *
+ * WHAT IT MAY NOT SAY IS THAT NOTHING WILL CHANGE. That is what it said first, and it is
+ * a claim about the future made on a reading that stops at the verification budget. A VS
+ * Code client whose build the image did not bake is NOT refused (`requiresSeedMatch`), so
+ * its launch legitimately goes on to fetch a server through the mirror — a ~28.6 MB CLI
+ * and, on a prewarm miss, the whole bundle — and a slow link can still be fetching when
+ * the budget runs out. Telling that candidate their window is dead and pointing them
+ * elsewhere is the harm `unverified` exists to avoid, arriving on the branch below it.
+ * So it states the bound it actually waited (derived from `VERIFY_SCHEDULE_MS`, never a
+ * second hard-coded copy), says the window may yet attach, and offers the other two
+ * routes rather than instructing an exit. What it still may not do is tell them to re-run
+ * this command, which is the original bug.
+ *
+ * AND IT MAY NOT HAND THEM A CHECK THAT PASSES ON THE DEAD WINDOW. It pointed at the
+ * remote indicator — "the bottom-left corner reads SSH: <alias>" — and this repo has
+ * measured that indicator PRESENT in exactly the failure case: `lib/editor-server.ts`'s
+ * header records the never-attached window carrying `"remoteAuthority":
+ * "ssh-remote+<alias>"` and being indistinguishable from a working one, and
+ * `lib/session-end.ts` records (ENG-2154) that a window whose transport is gone still
+ * reads `[SSH: <host>]`. A candidate told to look at the corner sees what they were told
+ * to look for and goes on working unrecorded, which is this ticket's own bug re-entering
+ * through its remediation. The honest sentence is that the two windows look the same —
+ * that is WHY the CLI checks — so the copy says so and names no visual test at all.
+ */
+export function editorNotConnectedLines(ed, alias, browserIdeUrl, seed, launchLog) {
+    const waited = Math.round(VERIFY_SCHEDULE_MS[VERIFY_SCHEDULE_MS.length - 1] / 1000);
+    const lines = [
+        "",
+        chalk.yellow.bold(`  ⚠  ${ed.label} opened, but it never started a server in your workspace.`),
+        "",
+        `     A ${ed.label} window is on screen and it is NOT attached to your workspace: it is`,
+        "     running against your own machine. Anything you do in that window is work on your",
+        chalk.yellow("     laptop, and it is not recorded."),
+        "",
+        `     We watched your workspace for ${waited} seconds after opening it and nothing`,
+        `     started there. A first-ever ${ed.label} connection can still be downloading its`,
+        "     server at that point and attach a little later. There is nothing you can check",
+        "     by eye: an attached window and an unattached one look exactly the same, which is",
+        "     why this command checks your workspace instead of asking you to.",
+        "",
+    ];
+    if (seed.kind === "mismatch") {
+        lines.push(`     The likely reason: your ${ed.label} is build ${seed.clientCommit.slice(0, 12)} and this`);
+        lines.push(`     workspace holds ${seed.seedCommit.slice(0, 12)}. It could not fetch a matching one.`);
+        lines.push("");
+    }
+    if (browserIdeUrl) {
+        lines.push("     You can work in the browser IDE instead — same workspace, same files, fully");
+        lines.push("     recorded, and nothing to install:");
+        lines.push(`       ${chalk.cyan(browserIdeUrl)}`);
+    }
+    else {
+        lines.push("     You can work in the browser IDE instead, from your assessment page — same");
+        lines.push("     workspace, same files, fully recorded.");
+    }
+    lines.push("");
+    lines.push("     You can also work from a terminal, which does not need the editor at all:");
+    lines.push(`       ${chalk.cyan(`ssh ${alias}`)}`);
+    if (launchLog) {
+        lines.push("");
+        lines.push(chalk.dim(`     ${ed.label} said, while trying to open:`));
+        for (const line of launchLog.split(/\r?\n/).slice(-8))
+            lines.push(chalk.dim(`       ${line}`));
+    }
+    lines.push("");
+    return lines;
+}
+/**
+ * ENG-2332 — what to say when the editor never started at all.
+ *
+ * THIS BRANCH EXISTS BECAUSE THE ONE ABOVE MUST NOT BE REACHABLE WITHOUT A WINDOW.
+ * `editorNotConnectedLines` opens by stating, as a fact, that a window is on screen and
+ * running against the candidate's own machine; when `spawn` itself fails that sentence is
+ * false, and the reading the verification produces is identical either way (no server,
+ * empty launch log). So the spawn error is recorded (`EditorLaunchHandle`) and routed
+ * here instead, where the only claim made is the one we can support.
+ *
+ * It offers the same two routes and, like every other failure branch, offers rather than
+ * instructs: there is no window to close, and re-running this command is the remediation
+ * the ticket was opened about. The error text is carried verbatim because it is the whole
+ * of what we know — `ENOENT` on a resolved path means the app moved or was removed since
+ * the `--version` probe a moment earlier, which is a thing the candidate can act on and
+ * we cannot diagnose for them.
+ */
+export function editorLaunchFailedLines(ed, alias, browserIdeUrl, error, launchLog) {
+    const lines = [
+        "",
+        chalk.yellow.bold(`  ⚠  ${ed.label} could not be started, so no window was opened.`),
+        "",
+        `     We found the ${ed.label} command and it answered a moment ago, but running it`,
+        "     failed:",
+        `       ${chalk.dim(error)}`,
+        "",
+        `     That usually means ${ed.label} was moved, removed or updated between those two`,
+        "     moments. Nothing has been opened and nothing is being recorded yet.",
+        "",
+    ];
+    if (browserIdeUrl) {
+        lines.push("     You can work in the browser IDE instead — same workspace, same files, fully");
+        lines.push("     recorded, and nothing to install:");
+        lines.push(`       ${chalk.cyan(browserIdeUrl)}`);
+    }
+    else {
+        lines.push("     You can work in the browser IDE instead, from your assessment page — same");
+        lines.push("     workspace, same files, fully recorded.");
+    }
+    lines.push("");
+    lines.push("     You can also work from a terminal, which does not need the editor at all:");
+    lines.push(`       ${chalk.cyan(`ssh ${alias}`)}`);
+    if (launchLog) {
+        lines.push("");
+        lines.push(chalk.dim(`     ${ed.label} said, while trying to open:`));
+        for (const line of launchLog.split(/\r?\n/).slice(-8))
+            lines.push(chalk.dim(`       ${line}`));
+    }
+    lines.push("");
+    return lines;
+}
+/**
+ * ENG-2332 — what to say when we could not reach the workspace to ask at all.
+ *
+ * Three-valued on purpose: "we could not check" is not "nothing came up", and saying
+ * either of the other two here would be a claim we cannot make. It lives beside the other
+ * copy rather than inline in `runConnect` so that what it may and may not say is testable
+ * — it is bound by the same rule as `editorNotConnectedLines` and broke it the same way.
+ *
+ * It may NOT tell the candidate to look at the remote indicator. That indicator is
+ * rendered from the remote authority, which the never-attached window carries (see
+ * `lib/editor-server.ts`'s header, and ENG-2154 in `lib/session-end.ts`), so the check
+ * passes in exactly the case it was offered to detect. It states the ambiguity instead
+ * and offers the two routes that are not in doubt.
+ */
+export function editorUnverifiedLines(ed, alias, browserIdeUrl) {
+    const lines = [
+        `  Your ${ed.label} window may or may not be attached to your workspace, and there is`,
+        "  nothing you can check by eye: an attached window and an unattached one look exactly",
+        `  the same. An unattached one runs on your own machine and is ${chalk.yellow("not recorded")}.`,
+        "",
+    ];
+    if (browserIdeUrl) {
+        lines.push("  You can work in the browser IDE instead — same workspace, same files, fully");
+        lines.push("  recorded, and nothing to install:");
+        lines.push(`    ${chalk.cyan(browserIdeUrl)}`);
+    }
+    else {
+        lines.push("  You can work in the browser IDE instead, from your assessment page — same");
+        lines.push("  workspace, same files, fully recorded.");
+    }
+    lines.push("");
+    lines.push("  You can also work from a terminal, which does not need the editor at all:");
+    lines.push(`    ${chalk.cyan(`ssh ${alias}`)}`);
+    return lines;
+}
 /**
  * Ensure the Remote-SSH extension is installed in the user's editor before we
  * open the remote window (the `gh codespace code` model). Best-effort: a
  * marketplace/network failure returns "failed" rather than aborting connect —
  * the caller tells the user how to install it by hand. Assumes the editor's CLI
- * exists (caller gates on hasEditorCli()).
+ * has been resolved (caller gates on `resolveEditorCommand`).
  */
-function ensureRemoteSshExtension(ed) {
+function ensureRemoteSshExtension(ed, command) {
+    const list = editorSpawnSpec(command, ["--list-extensions"], process.platform);
+    // Undrivable on this platform — the same outcome as an install that would not run.
+    // `failed` is already best-effort and never aborts connect.
+    if (!list)
+        return "failed";
     try {
-        const list = execFileSync(ed.bin, ["--list-extensions"], { encoding: "utf8" });
-        if (list.split(/\r?\n/).some((l) => l.trim().toLowerCase() === ed.remoteSshExt)) {
+        const listed = spawnSync(list.command, list.args, { encoding: "utf8", shell: list.shell, timeout: 60000 });
+        if (!listed.error && (listed.stdout ?? "").split(/\r?\n/).some((l) => l.trim().toLowerCase() === ed.remoteSshExt)) {
             return "present";
         }
     }
     catch {
         // Couldn't list (unexpected) — fall through and try to install anyway.
     }
+    const install = editorSpawnSpec(command, ["--install-extension", ed.remoteSshExt, "--force"], process.platform);
+    if (!install)
+        return "failed";
     try {
-        execFileSync(ed.bin, ["--install-extension", ed.remoteSshExt, "--force"], { stdio: "ignore" });
-        return "installed";
+        const done = spawnSync(install.command, install.args, { stdio: "ignore", shell: install.shell, timeout: 120000 });
+        return !done.error && done.status === 0 ? "installed" : "failed";
     }
     catch {
         return "failed";
     }
 }
-function launchEditor(ed, alias) {
-    const child = spawn(ed.bin, ["--remote", `ssh-remote+${alias}`, REMOTE_WORKSPACE_DIR], {
+/**
+ * ENG-2332 — where the editor's own output goes.
+ *
+ * It used to go to `stdio: "ignore"`, which is the mechanical half of this ticket: a
+ * resolver that cannot fetch its server writes its reason here and nowhere else, so
+ * discarding it leaves exit code 0, an empty terminal and a dead window as the entire
+ * record of the failure.
+ *
+ * A FILE and not a pipe, and that is not a style choice. The child is `detached` and
+ * outlives this process by design; a pipe belongs to the parent, so once `litmus connect`
+ * returns the editor would be writing into a closed pipe and could take an EPIPE for it.
+ * A file descriptor on a real file has neither problem, survives our exit, and is still
+ * here when a candidate is asked for it.
+ *
+ * THE NAME IS PER RUN, and both reasons are real. `os.tmpdir()` is a shared `/tmp` on a
+ * Linux box with no `TMPDIR`, so a fixed name is a name another local user can create
+ * first — and `openSync(path, "w")` FOLLOWS a symlink and TRUNCATES, so a link planted
+ * there redirects the editor's output into, or empties, a file of theirs. And two
+ * `litmus connect` runs on one machine would otherwise share the file, so a candidate
+ * being walked through one failure can be shown the other run's output. The pid plus a
+ * random suffix answers both; `openEditorLaunchLog` then refuses to follow a link or to
+ * reuse an existing name, so an attacker who guesses one gets nothing rather than a
+ * write.
+ */
+export function editorLaunchLogPath() {
+    const unique = randomBytes(6).toString("hex");
+    return path.join(os.tmpdir(), `litmus-connect-editor.${process.pid}.${unique}.log`);
+}
+/**
+ * Open the launch log for the child, or answer null when we cannot do it safely.
+ *
+ * `O_EXCL | O_NOFOLLOW` is the whole point: EXCL means an existing name — planted or
+ * left over — is refused rather than written into, and NOFOLLOW means a symlink at that
+ * name is refused rather than followed to its target. Neither is reachable in the
+ * ordinary case, since the name carries a random suffix; they are what makes the
+ * ordinary case's safety a property of the open rather than of the name being unguessed.
+ * A refusal costs the diagnostics from one launch and never the launch.
+ */
+export function openEditorLaunchLog(logPath) {
+    try {
+        return openSync(logPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ENG-2332, Greptile P1 on #2442 — ON WINDOWS THE `error` EVENT IS NOT THE FAILURE.
+ *
+ * `editorSpawnSpec` gives every Windows launch `shell: true`, so what `spawn` starts is
+ * `cmd.exe`, not the editor. `cmd.exe` starts fine essentially always — a missing `.cmd`,
+ * a path that stopped resolving, an editor that refuses its own argv are all reported by
+ * cmd.exe EXITING non-zero, not by an `error` event. So a handle watching only `error`
+ * reports "the window opened" for every one of them, which collapses the whole
+ * spawn-failed / opened-but-unattached distinction back into the wrong branch on exactly
+ * the platform the resolution work was added for.
+ *
+ * A NON-ZERO EXIT IS THEREFORE A LAUNCH FAILURE, and a zero exit is not. Both editors'
+ * CLIs return immediately after handing the argv to an already-running instance, so an
+ * ordinary successful launch exits 0 within moments and the process being gone says
+ * nothing. That asymmetry is what makes the exit code readable at all.
+ *
+ * The listeners outlive `unref()`: it stops the child holding the event loop open, and we
+ * are awaiting the verification anyway, so an exit inside the window still reaches us.
+ * Whichever signal arrives first wins and neither overwrites the other, because both
+ * describe the same thing — no window was created — and the first is the more specific.
+ */
+export function launchEditor(ed, command, alias, logPath) {
+    const spec = editorSpawnSpec(command, ["--remote", `ssh-remote+${alias}`, REMOTE_WORKSPACE_DIR], process.platform);
+    if (!spec) {
+        // No argv drives this command here, so nothing was started and nothing will be. This
+        // is a launch failure rather than a throw for the reason `editorSpawnSpec` gives: the
+        // command came off the candidate's own filesystem, and their username is not a reason
+        // to abort a connection to a workspace that is already up.
+        const why = `no command line can start ${command} on this platform`;
+        return { launchFailure: () => why };
+    }
+    // A tmpdir we cannot write is not a reason to refuse to open the editor.
+    const out = openEditorLaunchLog(logPath) ?? "ignore";
+    const child = spawn(spec.command, spec.args, {
         detached: true,
-        stdio: "ignore",
+        shell: spec.shell,
+        stdio: ["ignore", out, out],
+    });
+    // Node keeps its own copy of the descriptor for the child; ours is finished with the
+    // moment the spawn has it, and leaving it open would hold the file for our lifetime.
+    if (typeof out === "number") {
+        try {
+            closeSync(out);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    let failure = null;
+    const record = (why) => {
+        if (failure === null)
+            failure = why;
+    };
+    child.on("error", (err) => {
+        record(err.message || String(err));
+    });
+    child.on("exit", (code, signal) => {
+        if (signal !== null)
+            record(`${ed.label} was killed by ${signal} before it could start`);
+        else if (code !== null && code !== 0)
+            record(`${ed.label} exited immediately with code ${code}`);
     });
     child.unref();
+    return { launchFailure: () => failure };
+}
+/**
+ * Point at the editor's own output. `namePath` is for the branch where a human is
+ * walking a candidate through a failure: there the file is named whether or not
+ * `--verbose` was asked for, since `editorLaunchLogPath` gives it a per-run suffix that
+ * nobody can guess unaided.
+ *
+ * A PATH IS NAMED ONLY WHEN THERE IS SOMETHING AT IT, and the reason is that the file
+ * routinely does not exist. `launchEditor` falls back to `stdio: "ignore"` whenever
+ * `openEditorLaunchLog` refuses — an unwritable tmpdir, or its own `O_EXCL`/`O_NOFOLLOW`
+ * refusal — and even on the ordinary path the measured failure is an editor that exits 0
+ * and prints nothing, so an empty file is the common case rather than the odd one.
+ * Handing a support person a path with nothing behind it reads as the CLI having lost
+ * the log, which is a worse answer than saying plainly that the editor wrote nothing.
+ */
+export function editorLaunchOutputLines(logPath, launchLog, verbose, namePath) {
+    if (!namePath && !verbose)
+        return [];
+    if (!launchLog)
+        return [chalk.dim("  The editor wrote no output while opening.")];
+    const lines = [chalk.dim(`  Editor output: ${logPath}`)];
+    if (verbose)
+        for (const line of launchLog.split(/\r?\n/))
+            lines.push(chalk.dim(`    ${line}`));
+    return lines;
+}
+/** What the editor wrote while trying to open, or null when it said nothing. */
+function readEditorLaunchLog(logPath) {
+    try {
+        const text = readFileSync(logPath, "utf8").trim();
+        return text.length > 0 ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sshProbeRunner(alias) {
+    return (remoteCommand) => {
+        try {
+            const probed = spawnSync("ssh", ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10", "-o", "LogLevel=ERROR", alias, remoteCommand], { encoding: "utf8", timeout: 20000 });
+            if (probed.error)
+                return null;
+            return probed.stdout ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+}
+function probeWorkspace(ed, run) {
+    return parseWorkspaceProbe(run(remoteProbeCommand(ed.serverHomeDir, ed.seedCommitPath)));
+}
+/**
+ * ENG-2332 — poll the workspace until a server appears, or the budget runs out.
+ *
+ * Returns as soon as there is evidence, so the ordinary case costs one probe and a few
+ * seconds; the schedule is what bounds the other case (`VERIFY_SCHEDULE_MS` carries why
+ * it is a widening list rather than a fixed interval).
+ *
+ * A reading that FAILED and a reading that said "nothing here" are kept apart to the end:
+ * one probe answering over a flaky link must not turn a run that has already read the
+ * workspace several times into "we could not tell". So `not-connected` needs a probe
+ * that ANSWERED IT — the fallback below carries `verifyVerdict`'s own verdict forward
+ * rather than re-deriving one from "did anything read at all", which is a second copy of
+ * the same reasoning and was already one clause short of it: with no baseline the log
+ * signal is unusable, so a successful reading of an empty workspace is not evidence of
+ * anything and must not become `not-connected` here after `verifyVerdict` has just
+ * refused to call it that.
+ *
+ * A FAILED SPAWN ENDS THE WAIT IMMEDIATELY. The whole budget is spent waiting for a
+ * window to start a server, and a window that was never created will not — so the poll
+ * stops the moment `launched.launchFailure()` answers, rather than charging the candidate
+ * ~60 seconds for a question already settled. The wait is unchanged for every other
+ * case. It cannot be checked once up front: `spawn` reports the error on a later tick,
+ * so the first check has to come after an await, which is why the sleep is sliced rather
+ * than taken whole.
+ */
+const SPAWN_ERROR_POLL_MS = 200;
+export async function verifyEditorAttached(ed, baseline, run, onWait, launched) {
+    const started = Date.now();
+    const budget = VERIFY_SCHEDULE_MS[VERIFY_SCHEDULE_MS.length - 1];
+    let sawNotConnected = false;
+    for (const at of VERIFY_SCHEDULE_MS) {
+        const remaining = at - (Date.now() - started);
+        // A probe that spends its own timeout can carry the elapsed time past a later entry;
+        // skipping those keeps the WAIT the candidate experiences at the stated budget rather
+        // than at the budget plus however many probes went slowly.
+        if (remaining <= -1000 && at < budget)
+            continue;
+        if (remaining > 0) {
+            const until = Date.now() + remaining;
+            for (let left = remaining; left > 0; left = until - Date.now()) {
+                await sleep(Math.min(SPAWN_ERROR_POLL_MS, left));
+                if (launched.launchFailure() !== null)
+                    return { kind: "unverified" };
+            }
+        }
+        if (launched.launchFailure() !== null)
+            return { kind: "unverified" };
+        onWait(Math.round((Date.now() - started) / 1000));
+        const current = probeWorkspace(ed, run);
+        const verdict = verifyVerdict(baseline, current);
+        if (verdict.kind === "connected")
+            return verdict;
+        if (verdict.kind === "not-connected")
+            sawNotConnected = true;
+    }
+    return sawNotConnected ? { kind: "not-connected" } : { kind: "unverified" };
+}
+export async function attemptEditorLaunch(ed, io) {
+    // ONE reading answers both halves: the build the workspace holds, and — as the
+    // verification's baseline — what was already there before we opened anything. Taking
+    // it once means one extra command in the candidate's own activity record, not two.
+    const baseline = io.probe(ed);
+    const seed = seedVerdict(io.clientVersion, baseline);
+    if (seed.kind === "mismatch" && ed.requiresSeedMatch) {
+        return { kind: "refused", reason: "seed-mismatch", seed };
+    }
+    const extension = io.ensureExtension();
+    const logPath = io.launchLogPath();
+    const launched = io.launch(logPath);
+    const verdict = await io.verifyAttached(baseline, launched);
+    const launchLog = io.readLaunchLog(logPath);
+    // Read AFTER the await, never before it: `spawn` reports this on a later tick, so a
+    // check taken at the call site would still be null for a launch that had already
+    // failed. A verdict answered over a workspace says nothing about whether the window
+    // exists, so the error outranks it rather than being folded into it.
+    const error = launched.launchFailure();
+    if (error !== null)
+        return { kind: "launch-failed", seed, extension, error, logPath, launchLog };
+    return { kind: "launched", seed, extension, verdict, logPath, launchLog };
 }
 /**
  * Resolve which editor to open: an explicit --ide flag wins; otherwise prompt.
@@ -748,7 +1337,8 @@ export function browserFallback(hasUrl, ideWasChosen) {
         return "browser";
     return ideWasChosen ? "unavailable" : "vscode";
 }
-export async function runConnect(token, ideOpt) {
+export async function runConnect(token, ideOpt, opts = {}) {
+    const verbose = Boolean(opts.verbose);
     const apiBase = resolveApiBase(process.env.LITMUS_API_URL);
     setErrorContext({ token, apiBase });
     // 1. Authenticate + learn the backend URL. This does NOT mark the candidate
@@ -896,11 +1486,20 @@ export async function runConnect(token, ideOpt) {
     // reassigned `ide` for the compiler, so pin the descriptor explicitly rather than
     // indexing with a widened key.
     const editor = ide === "cursor" ? NATIVE_EDITORS.cursor : NATIVE_EDITORS.vscode;
+    // ENG-2332 — find the editor's CLI before asking what it is. PATH first, then the
+    // places its installer puts it, because "not on PATH" was being reported as "not
+    // installed" on a machine where the binary was sitting in the application bundle the
+    // whole time. Null here means we genuinely could not find a way to drive it.
+    const resolved = resolveEditorCommand(editor);
     // ENG-2152 — resolve WHAT THAT COMMAND ACTUALLY IS before anything acts on the choice.
     // `bin` is a name on PATH, and on a machine where Cursor is the default editor `code`
     // can be Cursor's own CLI. The verdict is taken here, above the Copilot Chat step,
     // because that step is the first thing that acts on the candidate's answer.
-    const identity = identifyEditorCli(editor);
+    //
+    // With nothing resolved there is nothing to probe, and `unverified` is what that means:
+    // it is the absence branch's job to say so, below the mismatch refusal, so a candidate
+    // whose `code` is Cursor is told THAT rather than that their editor is missing.
+    const identity = resolved ? identifyEditorCli(editor, resolved.command) : { kind: "unverified" };
     // 5b. Point this machine's Copilot Chat at the Litmus gateway (ENG-1475).
     //
     //     ONLY ON THE NATIVE VS CODE PATH, and that is the whole reason it is here rather
@@ -987,35 +1586,26 @@ export async function runConnect(token, ideOpt) {
     // reports success and the candidate is told we readied VS Code's Remote-SSH for them.
     //
     // Above the ABSENCE check too, and that ordering is what makes this hold on Windows.
-    // The probe can READ a `code.cmd` (it goes through a shell there), but `hasEditorCli`
-    // and `launchEditor` still cannot DRIVE one, so a Windows candidate has always landed
-    // on the manual-instructions branch below — a pre-existing gap this ticket does not
-    // widen and deliberately does not paper over: giving those two a shell without proving
-    // the spawn works would turn clear instructions into a silent nothing. Checking the
-    // mismatch first means a Windows candidate whose `code` is Cursor is told so, rather
-    // than told their editor is not installed.
+    // Every probe and every spawn now goes through `editorSpawnSpec`, so a Windows
+    // `code.cmd` is driven the same way it is read (ENG-2332); before that, the probe could
+    // READ one and the launch could not DRIVE one, so every Windows candidate landed on the
+    // manual-instructions branch. Checking the mismatch first means a Windows candidate
+    // whose `code` is Cursor is told so, rather than told their editor is not installed.
     if (identity.kind === "mismatch") {
         for (const line of editorMismatchLines(editor, NATIVE_EDITORS[identity.actual], reentry)) {
             console.log(line);
         }
         return;
     }
-    if (identity.kind === "unverified") {
-        // Proceeding as asked — see `EditorIdentity`. Said out loud because it is the one line
-        // that tells us, when a candidate reports opening the wrong editor, that the probe
-        // could not read this machine rather than that it read it wrong.
-        console.log(chalk.dim(`  (Couldn't confirm that \`${editor.bin}\` is ${editor.label}; opening it as you asked.)`));
-    }
-    if (!hasEditorCli(editor)) {
-        console.log();
-        warn(`${editor.label} \`${editor.bin}\` command not found on PATH.`);
-        console.log("  Connect manually:");
-        console.log(chalk.cyan(`    ${editor.bin} --remote ssh-remote+${alias} ${REMOTE_WORKSPACE_DIR}`));
-        console.log(`  or in ${editor.label}: Remote-SSH → Connect to Host → ${chalk.bold(alias)}.`);
-        console.log(chalk.dim(`  (Install \`${editor.bin}\` on PATH via ${editor.label}'s "${editor.shellCommand}".)`));
+    if (!resolved) {
+        // ENG-2332 — the CLI is not on PATH and not where the installer puts it. Everything
+        // offered here is reachable WITHOUT it; the line this replaced offered
+        // `<bin> --remote …`, i.e. the binary whose absence is the message.
+        for (const line of editorNotFoundLines(editor, alias, conn.browser_ide_url ?? null))
+            console.log(line);
         // The full-quit requirement outlives this degraded path — arguably it matters MORE
-        // here, since a candidate typing the command by hand is doing it from a shell that
-        // may well be inside the Cursor they still have to quit.
+        // here, since a candidate connecting by hand is doing it from an editor they still
+        // have to quit.
         //
         // ENG-2145: and so does the way back. This used to point at "the note above", which
         // is a back-reference to a notice printed BEFORE a boot wait that can run to two
@@ -1023,27 +1613,130 @@ export async function runConnect(token, ideOpt) {
         // about this very command, which by then has returned. So the route is restated
         // here in full rather than referred to.
         if (ide === "cursor") {
-            console.log(chalk.yellow("  Quit Cursor completely before you run that, or your work is not recorded."));
+            console.log(chalk.yellow("  Quit Cursor completely before you connect, or your work is not recorded."));
             for (const line of cursorReentryLines(reentry))
                 console.log(line);
         }
         return;
     }
-    const extSpinner = ora(`Checking ${editor.label} Remote-SSH extension...`).start();
-    const ext = ensureRemoteSshExtension(editor);
-    if (ext === "present")
-        extSpinner.succeed("Remote-SSH extension ready");
-    else if (ext === "installed")
-        extSpinner.succeed(`Installed the ${editor.label} Remote-SSH extension`);
-    else
-        extSpinner.warn("Couldn't auto-install the Remote-SSH extension");
-    launchEditor(editor, alias);
-    success(`Opening ${editor.label} → ${alias}`);
-    if (ext === "failed") {
-        console.log(chalk.dim(`  If the window won't connect, install "Remote - SSH" (${editor.remoteSshExt}) from the Extensions panel, then run litmus connect again.`));
+    if (identity.kind === "unverified") {
+        // Proceeding as asked — see `EditorIdentity`. Said out loud because it is the one line
+        // that tells us, when a candidate reports opening the wrong editor, that the probe
+        // could not read this machine rather than that it read it wrong.
+        //
+        // ENG-2332 — BELOW the absence branch, not above it. With nothing resolved the
+        // identity is `unverified` for the trivial reason that there was nothing to ask, so
+        // printing this first produced "opening it as you asked" immediately followed by
+        // "not found on PATH" — two lines contradicting each other about whether anything was
+        // about to open, which is on the ticket in its own right.
+        console.log(chalk.dim(`  (Couldn't confirm that \`${editor.bin}\` is ${editor.label}; opening it as you asked.)`));
+    }
+    if (resolved.source === "install-location") {
+        info(`Using ${editor.label} at ${resolved.command}`);
+        console.log(chalk.dim(`  (\`${editor.bin}\` isn't on your PATH. ${editor.label}'s "${editor.shellCommand}" adds it.)`));
+    }
+    // ENG-2332 — the version check BEFORE anything is opened, then the verification after
+    // it. Both, and their order, live in `attemptEditorLaunch`: the guarantee here is a
+    // property of the SEQUENCE, so it is held in one testable unit rather than in the
+    // arrangement of the lines below. Everything this block still owns is output.
+    const probe = sshProbeRunner(alias);
+    // A holder rather than a `let`, because the spinner is created inside a callback and
+    // read after the await: a plain binding would be narrowed to `null` by control flow
+    // that cannot see the closure that assigns it. Each spinner is also started INSIDE the
+    // step it describes — the workspace read can take twenty seconds, and a spinner saying
+    // "Checking the Remote-SSH extension" through it names the wrong step, on the one path
+    // where the next thing the candidate may see is a refusal that installed nothing.
+    const spinners = { verify: null };
+    const readSpinner = ora(`Checking your workspace...`).start();
+    const outcome = await attemptEditorLaunch(editor, {
+        probe: (ed) => {
+            const reading = probeWorkspace(ed, probe);
+            readSpinner.stop();
+            return reading;
+        },
+        clientVersion: resolved.version,
+        ensureExtension: () => {
+            const extSpinner = ora(`Checking ${editor.label} Remote-SSH extension...`).start();
+            const state = ensureRemoteSshExtension(editor, resolved.command);
+            if (state === "present")
+                extSpinner.succeed("Remote-SSH extension ready");
+            else if (state === "installed")
+                extSpinner.succeed(`Installed the ${editor.label} Remote-SSH extension`);
+            else
+                extSpinner.warn("Couldn't auto-install the Remote-SSH extension");
+            return state;
+        },
+        launchLogPath: editorLaunchLogPath,
+        launch: (logPath) => {
+            const launched = launchEditor(editor, resolved.command, alias, logPath);
+            // The launch is not the result, so nothing claims one here. What used to be printed
+            // at this point was `✔ Opening <editor> → <alias>`, which is true of a spawn that is
+            // about to fail, and was the last thing the CLI said in a session where nothing was
+            // ever recorded.
+            spinners.verify = ora(`Opening ${editor.label} — waiting for it to start in your workspace...`).start();
+            return launched;
+        },
+        readLaunchLog: readEditorLaunchLog,
+        verifyAttached: (baseline, launched) => verifyEditorAttached(editor, baseline, probe, (waited) => {
+            if (spinners.verify) {
+                spinners.verify.text = `Opening ${editor.label} — waiting for it to start in your workspace... (${waited}s)`;
+            }
+        }, launched),
+    });
+    if (outcome.kind === "refused") {
+        for (const line of editorSeedMismatchLines(editor, outcome.seed, conn.browser_ide_url ?? null, alias)) {
+            console.log(line);
+        }
+        return;
+    }
+    const launchSpinner = spinners.verify;
+    if (outcome.kind === "launch-failed") {
+        // No window was created, so none of the not-connected copy is true here. See
+        // `editorLaunchFailedLines`.
+        launchSpinner?.fail(`Couldn't start ${editor.label}.`);
+        for (const line of editorLaunchFailedLines(editor, alias, conn.browser_ide_url ?? null, outcome.error, verbose ? null : outcome.launchLog)) {
+            console.log(line);
+        }
+        for (const line of editorLaunchOutputLines(outcome.logPath, outcome.launchLog, verbose, true))
+            console.log(line);
+        return;
+    }
+    if (outcome.verdict.kind === "connected") {
+        launchSpinner?.succeed(`${editor.label} is running in your workspace — your files, terminal and commits are recorded.`);
+        for (const line of editorConnectedLines(editor, alias))
+            console.log(line);
+    }
+    else if (outcome.verdict.kind === "unverified") {
+        // Three-valued on purpose: we could not reach the workspace to ask, which is not the
+        // same as knowing nothing came up, and saying either of the other two here would be a
+        // claim we cannot make. See `verifyVerdict`.
+        launchSpinner?.warn(`Couldn't check whether ${editor.label} attached to your workspace.`);
+        for (const line of editorUnverifiedLines(editor, alias, conn.browser_ide_url ?? null))
+            console.log(line);
     }
     else {
-        console.log(chalk.dim("  If a new window doesn't appear, run litmus connect again."));
+        launchSpinner?.fail(`${editor.label} did not start in your workspace.`);
+        // Under --verbose the whole log is printed below, so the copy's own 8-line tail is
+        // withheld rather than repeated; without it that tail is the only view of the output.
+        for (const line of editorNotConnectedLines(editor, alias, conn.browser_ide_url ?? null, outcome.seed, verbose ? null : outcome.launchLog)) {
+            console.log(line);
+        }
+        if (outcome.extension === "failed") {
+            console.log(chalk.dim(`  The Remote-SSH extension ("${editor.remoteSshExt}") also failed to install, which would explain this.`));
+        }
+        // The one outcome somebody is walked through, and the log now carries a per-run
+        // suffix — so its PATH is named here whether or not --verbose was asked for.
+        for (const line of editorLaunchOutputLines(outcome.logPath, outcome.launchLog, verbose, true))
+            console.log(line);
+        return;
+    }
+    // The log's PATH is named on every branch a human gets walked through, and `unverified`
+    // is one: it is precisely the branch where we could not reach the workspace at all, so
+    // the editor's own resolver message is the only evidence anybody has — and the name
+    // carries a per-run suffix nobody can guess unaided. `editorLaunchOutputLines` still
+    // withholds a path with nothing behind it.
+    for (const line of editorLaunchOutputLines(outcome.logPath, outcome.launchLog, verbose, outcome.verdict.kind !== "connected")) {
+        console.log(line);
     }
     // ENG-2154. The window we have just opened outlives the session, and what it
     // does when the session ends looks like a failure. This is the only moment