litmus-cli 1.4.66 → 1.4.68

package/dist/commands/connect.js

@@ -1,12 +1,14 @@
+import { ConnectionAttempt } from "../lib/connection-attempt.js";
+import { updateSshConfig } from "../lib/ssh-config-file.js";
 import os from "os";
 import path from "path";
 import readline from "readline";
-import { closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "fs";
+import { closeSync, constants, existsSync, mkdirSync, openSync, readFileSync } 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, isNetworkError } from "../lib/api.js";
+import { fetchInitMetadata, startWorkspace, getConnection, fetchEditorChatConfig, ServerError, hintForError, isNetworkError, workspaceStartNetworkDetail } from "../lib/api.js";
 import { applyEditorChatConfig } from "../lib/chat-model-config.js";
 import { finishSkillImport, offerSkillImport, startSkillImport } from "../lib/connect-skills.js";
 import { resolveApiBase } from "../lib/api-base.js";
@@ -16,7 +18,7 @@ import { parseEditorVersion, parseWorkspaceProbe, remoteProbeCommand, seedVerdic
 import { fatal, holdExitFor, success, info, warn, setErrorContext, reportEvent } from "../lib/errors.js";
 import { oldWindowsSshHint, openSshSession, parseOpenSshVersion, proxyJumpBroken, readEditorSettings, readSshVersionBanner, SSH_CONNECTION_FAILED, sshExecutableFor, sshPreflight, sshPreflightHint, } from "../lib/ssh-client.js";
 import { editorEndingForewarning } from "../lib/session-end.js";
-import { attemptQuit, attemptRelaunch, platformSupportsGracefulCursorRestart, realCursorProcessIo, } from "../lib/cursor-restart.js";
+import { attemptRelaunch, platformSupportsGracefulCursorRestart, realCursorProcessIo, } from "../lib/cursor-restart.js";
 /**
  * `litmus connect <token>` — the CLI connector for the v2 codespace, modeled on
  * `gh codespace ssh/code`. It removes the manual "paste your public key + copy
@@ -320,13 +322,9 @@ function ensureSshKey(keyPath) {
         stdio: "ignore",
     });
 }
-function writeSshConfig(alias, block, controlBlock) {
+async function writeSshConfig(alias, block, controlBlock) {
     const cfgPath = path.join(os.homedir(), ".ssh", "config");
-    const dir = path.dirname(cfgPath);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const existing = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : "";
-    writeFileSync(cfgPath, upsertSshConfigContent(existing, alias, block, controlBlock), { mode: 0o600 });
+    await updateSshConfig(cfgPath, (existing) => upsertSshConfigContent(existing, alias, block, controlBlock));
     return cfgPath;
 }
 /**
@@ -412,7 +410,7 @@ function probeEditorCli(command) {
         return null;
     }
 }
-function resolveEditorCommand(ed) {
+export function resolveEditorCommand(ed) {
     const onPath = probeEditorCli(ed.bin);
     if (onPath)
         return { command: ed.bin, source: "path", version: onPath };
@@ -599,9 +597,6 @@ export function editorSeedMismatchLines(ed, verdict, pageUrl, alias) {
 export function editorNotFoundLines(ed, alias, pageUrl) {
     return [
         chalk.yellow.bold(`⚠ Couldn't find ${ed.label}'s \`${ed.bin}\` command, so nothing was opened.`),
-        // Greptile on #3071: this route never restarts Cursor, and Cursor only loads the
-        // workspace's prompt recording when the app starts (gotcha 090).
-        ...(ed.ide === "cursor" ? ["  Quit Cursor completely and reopen it first, or your AI prompts won't be recorded."] : []),
         `  In ${ed.label}: Command Palette → ${chalk.bold("Remote-SSH: Connect to Host…")} → ${chalk.bold(alias)}`,
         `  To get the \`${ed.bin}\` command for next time: Command Palette → "${ed.shellCommand}".`,
         workNowLine(alias, pageUrl),
@@ -690,7 +685,7 @@ export function editorUnverifiedLines(ed, alias, pageUrl) {
  * null skips the conflict check rather than stopping connect: the check only refuses on
  * evidence, never on a failed read.
  */
-function listEditorExtensions(command) {
+export function listEditorExtensions(command) {
     const list = editorSpawnSpec(command, ["--list-extensions"], process.platform);
     if (!list)
         return null;
@@ -702,22 +697,13 @@ function listEditorExtensions(command) {
         return null;
     }
 }
-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)
+export function ensureRemoteSshExtension(ed, command, listed) {
+    // An unreadable inventory is not evidence of absence; don't mutate it blindly.
+    if (listed === null)
         return "failed";
-    try {
-        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 (listed.split(/\r?\n/).some((l) => l.trim().toLowerCase() === ed.remoteSshExt))
+        return "present";
+    const install = editorSpawnSpec(command, ["--install-extension", ed.remoteSshExt], process.platform);
     if (!install)
         return "failed";
     try {
@@ -871,11 +857,11 @@ function readEditorLaunchLog(logPath) {
         return null;
     }
 }
-function sshProbeRunner(alias) {
+export function sshProbeRunner(alias, executable = "ssh") {
     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)
+            const probed = spawnSync(executable, ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10", "-o", "LogLevel=ERROR", alias, remoteCommand], { encoding: "utf8", timeout: 20000 });
+            if (probed.error || probed.status !== 0)
                 return null;
             return probed.stdout ?? null;
         }
@@ -1043,52 +1029,10 @@ export function keepWaitingForWorkspace(elapsedMs, status) {
 export function candidatePageUrl(apiBase, assessmentId) {
     return `${apiBase}/candidate/${assessmentId}`;
 }
-/**
- * ENG-1950 — the one thing a Cursor candidate has to be told when they pick Cursor.
- *
- * Cursor reads its prompt-recording setup once, at application startup (ENG-1728,
- * measured), so a Cursor that is already open when the workspace opens records no AI
- * prompts while everything else works. ENG-2890: on macOS connect quits and reopens
- * Cursor itself (`lib/cursor-restart.ts`), so nothing is said here and the restart step
- * speaks when it acts. Elsewhere a graceful quit cannot be confirmed, so the candidate is
- * asked to do it, in two lines: the 23-line notice this replaced was the wall the
- * ENG-2890 candidate read past. The second line exists because quitting Cursor also
- * closes its integrated terminal, and with it this command (ENG-2145).
- */
-export function cursorSelectionNoticeLines(platform = process.platform) {
-    if (platformSupportsGracefulCursorRestart(platform))
-        return [];
-    return [
-        "  Before Cursor opens, quit it completely (File → Exit), or your AI prompts won't be recorded.",
-        "  If this terminal is inside Cursor, run the same litmus connect command from another terminal.",
-    ];
-}
-/**
- * ENG-2890 — is this process running in Cursor's integrated terminal?
- *
- * Quitting Cursor kills its terminals, so the macOS auto-restart would kill this CLI
- * between the quit and the relaunch, leaving no editor and no command. `TERM_PROGRAM`
- * is "vscode" in VS Code AND in Cursor's terminal, so one of Cursor's own markers is
- * required as well: its trace id, its ToDesktop bundle id, or its bundled askpass node.
- * VS Code's terminal (bundle id `com.microsoft.VSCode`, no trace id) is not a match.
- */
-export function runningInsideCursorTerminal(env = process.env) {
-    if (env.TERM_PROGRAM !== "vscode")
-        return false;
-    return (Boolean(env.CURSOR_TRACE_ID) ||
-        (env.__CFBundleIdentifier ?? "").includes("todesktop") ||
-        (env.VSCODE_GIT_ASKPASS_NODE ?? "").includes("Cursor"));
-}
-/** ENG-2890 — said instead of quitting Cursor out from under this terminal. */
-export function insideCursorTerminalLines() {
-    return [
-        chalk.yellow.bold("⚠ This terminal is inside Cursor, and restarting Cursor would close it."),
-        "  Run the same litmus connect command from Terminal or iTerm instead.",
-    ];
+/** Remote hooks initialize in the remote window; no desktop restart is required (ENG-3176). */
+export function cursorSelectionNoticeLines(_platform = process.platform) {
+    return [];
 }
-/** ENG-2890 — the one line connect prints before its macOS auto-restart of Cursor. */
-/** Cursor success when this command could not confirm a fresh start (gotcha 090). */
-export const CURSOR_RECORDING_CAVEAT_LINE = "  If Cursor was open before this, quit it and run the same litmus connect command again, or your AI prompts won't be recorded.";
 /** How long a freshly started Cursor gets to finish restoring its session (ENG-2884). */
 export const CURSOR_SETTLE_MS = 6000;
 /** When, into the attach wait, the open request is sent to Cursor a second time. */
@@ -1131,18 +1075,6 @@ export function resendableLaunch(launch) {
         },
     };
 }
-export const CURSOR_RESTARTING_LINE = "Restarting Cursor so your AI prompts are recorded (it reopens on its own)...";
-/**
- * ENG-2890 — the quit was asked for and Cursor is still running, so nothing is
- * launched (see the gate in `connectFlow`). `renderCursorRestartOutcome`'s longer form
- * stays with init and doctor.
- */
-export function cursorQuitUnconfirmedLines() {
-    return [
-        chalk.red.bold("✖ Cursor didn't quit. It may be waiting on a \"Save changes?\" dialog."),
-        "  Quit Cursor yourself, then run the same litmus connect command again from Terminal or iTerm.",
-    ];
-}
 /**
  * Map a menu answer to an editor. (ENG-1667 item 3; Cursor added by ENG-1950.)
  *
@@ -1309,8 +1241,7 @@ function pruneStaleHostKeys(p) {
     // known_hosts as [host]:port, so a bare-host -R would miss it.
     if (p.port)
         targets.push(`[${p.host}]:${p.port}`);
-    if (p.jumpHost)
-        targets.push(p.jumpPort ? `[${p.jumpHost}]:${p.jumpPort}` : p.jumpHost);
+    // The shared bastion is not reprovisioned with this workspace. Preserve its pinned key.
     for (const t of targets) {
         try {
             execFileSync("ssh-keygen", ["-R", t], { stdio: "ignore" });
@@ -1337,18 +1268,34 @@ export async function runConnect(token, ideOpt, opts = {}) {
     // printed last, on every way out of the flow, so it neither delays the editor nor
     // is lost when a later step fails. The workspace lines follow it, so the candidate's
     // last read is where they are and what the session ending looks like.
+    setErrorContext({ token, apiBase: resolveApiBase(process.env.LITMUS_API_URL) });
+    const attempt = new ConnectionAttempt();
     const skillImport = { report: null, footer: [], sshAlias: null, publishedPorts: [] };
+    // Register before entering the flow: a fast fatal report can settle before the
+    // caller's finally begins, especially while an async SSH config write is unwinding.
+    let releaseExitHold;
+    holdExitFor(new Promise((resolve) => { releaseExitHold = resolve; }));
     try {
-        await connectFlow(token, ideOpt, opts, skillImport);
+        await connectFlow(token, ideOpt, opts, skillImport, attempt);
+    }
+    catch (error) {
+        attempt.finish("failed");
+        attempt.evidence(error instanceof Error ? error.message : null);
+        throw error;
     }
     finally {
-        // Held, so a `fatal` in the flow waits for the upload and its report (ENG-2919).
-        await holdExitFor((async () => {
+        try {
+            await attempt.flush();
+            if (opts.verbose || attempt.needsSupport)
+                console.log(chalk.dim(`  Connection ID: ${attempt.id}`));
             if (skillImport.report)
                 await finishSkillImport(skillImport.report);
             for (const line of skillImport.footer)
                 console.log(line);
-        })());
+        }
+        finally {
+            releaseExitHold();
+        }
     }
     // The ssh route's session runs last, so nothing we print lands inside the remote shell.
     if (!skillImport.sshAlias)
@@ -1380,7 +1327,7 @@ async function openSshRoute(alias) {
     if (status)
         process.exitCode = status;
 }
-async function connectFlow(token, ideOpt, opts, skillImport) {
+async function connectFlow(token, ideOpt, opts, skillImport, attempt) {
     const verbose = Boolean(opts.verbose);
     const apiBase = resolveApiBase(process.env.LITMUS_API_URL);
     setErrorContext({ token, apiBase });
@@ -1395,6 +1342,8 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
         spinner.succeed(meta.assessmentName);
     }
     catch (err) {
+        attempt.evidence(workspaceStartNetworkDetail(err));
+        attempt.evidence(err instanceof Error ? err.message : null);
         // ENG-2895: the Error line below says what failed; a second "Connection failed" line
         // above it was the same fact twice, and wrong when the cause was a rejected token.
         spinner.stop();
@@ -1417,28 +1366,37 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     // ENG-2890 — the assessment page is the one re-entry route connect prints: its URL
     // carries only the assessment id, never the token.
     const pageUrl = candidatePageUrl(apiBase, meta.assessmentId);
+    attempt.stage("selection");
     const { ide: chosenIde, chosen: ideWasChosen } = await resolveIde(ideOpt, console.log);
     let ide = chosenIde;
+    attempt.editor(ide);
     // ENG-2814: asked here, next to the editor choice, and uploaded once the workspace is
     // ready. Never fails the connect. See `lib/connect-skills.ts`.
+    attempt.stage("skills");
     const pendingSkills = await offerSkillImport({
         backendUrl, token, flag: opts.skills, verbose,
     });
+    attempt.stage("ssh_key");
     // 2. Ensure a local SSH key (private key never leaves this machine).
     try {
         ensureSshKey(KEY_PATH);
     }
     catch (err) {
+        attempt.evidence(workspaceStartNetworkDetail(err));
+        attempt.evidence(err instanceof Error ? err.message : null);
         fatal("Couldn't create an SSH key.", "Install OpenSSH (it includes ssh-keygen), then run the same litmus connect command again.", { internalDetail: err instanceof Error ? err.message : String(err), severity: "warning" });
         return;
     }
     const pubkey = readFileSync(`${KEY_PATH}.pub`, "utf8").trim();
     // 3. Start the workspace with our public key.
+    attempt.stage("workspace_start");
     const boot = ora("Starting your workspace...").start();
     try {
         await startWorkspace(backendUrl, token, pubkey);
     }
     catch (err) {
+        attempt.evidence(workspaceStartNetworkDetail(err));
+        attempt.evidence(err instanceof Error ? err.message : null);
         // The Error line below names what went wrong; see the sign-in spinner above.
         boot.stop();
         const code = err instanceof ServerError ? err.errorCode : undefined;
@@ -1452,6 +1410,10 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
             fatal("This assessment is closed. Its deadline has passed.", "Contact the company if you need an extension.", { severity: "warning" });
             return;
         }
+        if (isNetworkError(err)) {
+            fatal("Couldn't reach Litmus to start your workspace.", "Check your internet connection, then run the same litmus connect command again. If it keeps happening, contact the company.", { internalDetail: workspaceStartNetworkDetail(err), severity: "error" });
+            return;
+        }
         const msg = err instanceof Error ? err.message : String(err);
         fatal(msg, "Run the same litmus connect command again in a moment. If it keeps happening, contact the company.", {
             severity: err instanceof ServerError && err.statusCode && err.statusCode < 500 ? "warning" : "error",
@@ -1490,6 +1452,8 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
         return;
     }
     boot.succeed("Workspace ready");
+    attempt.stage("workspace_ready");
+    attempt.checkpoint();
     if (pendingSkills)
         skillImport.report = holdExitFor(startSkillImport(backendUrl, token, pendingSkills, undefined, () => ide));
     // Browser IDE: no local SSH / VS Code needed — just open the signed URL.
@@ -1507,6 +1471,7 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
         if (fallback === "vscode") {
             warn("The browser IDE isn't available here. Opening VS Code instead.");
             ide = "vscode";
+            attempt.editor(ide);
         }
         else if (fallback === "unavailable") {
             fatal("The browser IDE isn't available for this workspace yet.", "Open it in VS Code instead: run the same litmus connect command with --ide vscode.", { severity: "warning" });
@@ -1514,6 +1479,8 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
         }
     }
     if (ide === "browser" && conn.browser_ide_url) {
+        attempt.stage("browser_open");
+        attempt.finish("browser_requested");
         // ENG-3137 — the workspace now trusts this machine's key, so the assessment page's
         // Plain SSH offers `ssh <alias>`. Write the entry that alias names, as every other
         // route does. Best-effort: a config we could not write must not cost the browser route.
@@ -1522,11 +1489,13 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
                 const parsed = parseSshCommand(conn.ssh_command);
                 const alias = aliasFor(conn.ssh_hostname, token);
                 pruneStaleHostKeys(parsed);
-                const cfgPath = writeSshConfig(alias, buildSshConfigBlock(alias, KEY_PATH, parsed), buildControlPathBlock(alias, parsed));
+                const cfgPath = await writeSshConfig(alias, buildSshConfigBlock(alias, KEY_PATH, parsed), buildControlPathBlock(alias, parsed));
                 if (verbose)
                     info(`SSH config written to ${cfgPath} (Host "${alias}")`);
             }
             catch (err) {
+                attempt.evidence(workspaceStartNetworkDetail(err));
+                attempt.evidence(err instanceof Error ? err.message : null);
                 if (verbose)
                     info(`SSH config not written: ${err instanceof Error ? err.message : String(err)}`);
             }
@@ -1552,6 +1521,13 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     //    Prune stale host keys first so a re-provisioned container's new key is
     //    accepted, not refused (ENG-1221).
     const parsed = parseSshCommand(conn.ssh_command);
+    // Reuse this observation across compatibility checks, preflight and diagnostics.
+    const sshBanners = new Map();
+    const sshBanner = (executable) => {
+        if (!sshBanners.has(executable))
+            sshBanners.set(executable, readSshVersionBanner(executable));
+        return sshBanners.get(executable) ?? null;
+    };
     // ENG-2682 — Windows' own OpenSSH below 8.1 cannot run the ProxyJump every bastion
     // route depends on (see `lib/ssh-client.ts`). Refuse before writing anything, with the
     // version named and a way out, rather than hand an editor a connection it will lose
@@ -1559,17 +1535,18 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     // `remote.SSH.path` when it names one, PATH's ssh otherwise.
     if (process.platform === "win32" && parsed.jumpHost && ide !== "browser") {
         const executable = sshExecutableFor(ide, ide === "ssh" ? null : readEditorSettings(ide));
-        const client = parseOpenSshVersion(readSshVersionBanner(executable) ?? "");
+        const client = parseOpenSshVersion(sshBanner(executable) ?? "");
         if (client && proxyJumpBroken(client)) {
             const where = executable === "ssh" ? "" : ` at ${executable}, set in remote.SSH.path`;
             fatal(`Your Windows SSH (${client.label}${where}) is too old to reach the workspace.`, oldWindowsSshHint(Boolean(conn.browser_ide_url)), { severity: "warning" });
             return;
         }
     }
+    attempt.stage("ssh_config");
     const alias = aliasFor(conn.ssh_hostname, token);
     pruneStaleHostKeys(parsed);
     const block = buildSshConfigBlock(alias, KEY_PATH, parsed);
-    const cfgPath = writeSshConfig(alias, block, buildControlPathBlock(alias, parsed));
+    const cfgPath = await writeSshConfig(alias, block, buildControlPathBlock(alias, parsed));
     if (verbose)
         info(`SSH config written to ${cfgPath} (Host "${alias}")`);
     // ENG-2693 — prove the connection before handing it off (see `sshPreflight`). The
@@ -1582,19 +1559,23 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     // Called per route, not here once: the native route runs it only AFTER the WSL check
     // (Greptile on #2844), so a candidate whose Windows editor cannot see WSL's config is
     // told that, rather than a generic ssh failure from the wrong side of the pairing.
+    const sshExecutable = sshExecutableFor(ide, ide === "ssh" ? null : readEditorSettings(ide));
     const preflightStops = async (route) => {
-        const sshExecutable = sshExecutableFor(route, route === "ssh" ? null : readEditorSettings(route));
         // ENG-2895: up to two 45s attempts, so it gets a spinner; it says nothing when it works.
         const checking = ora("Checking the connection to your workspace...").start();
+        attempt.stage("ssh_preflight");
+        attempt.fact("sshSelection", sshExecutable === "ssh" ? "path" : "editor-setting");
+        attempt.fact("sshVersion", parseOpenSshVersion(sshBanner(sshExecutable) ?? "")?.label);
         const preflight = await sshPreflight(alias, sshExecutable);
         checking.stop();
         if (preflight.ok)
             return false;
+        attempt.evidence(preflight.detail.join("\n"));
         fatal("Your computer couldn't open an SSH connection to the workspace.", sshPreflightHint(preflight.detail, Boolean(conn.browser_ide_url), verbose), {
             severity: "error",
             internalDetail: [
                 `route=${route} platform=${process.platform} ssh=${sshExecutable}`,
-                `client=${readSshVersionBanner(sshExecutable) ?? "unreadable"}`,
+                `client=${sshBanner(sshExecutable) ?? "unreadable"}`,
                 ...preflight.detail,
             ].join("\n"),
         });
@@ -1605,6 +1586,8 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     if (ide === "ssh") {
         if (await preflightStops("ssh"))
             return;
+        attempt.stage("ssh_handoff");
+        attempt.finish("ssh_ready");
         if (verbose)
             console.log(chalk.dim(`  (equivalently: ${conn.ssh_command})`));
         if (opts.tunnel) {
@@ -1630,7 +1613,12 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     // 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.
+    attempt.stage("editor_resolution");
     const resolved = resolveEditorCommand(editor);
+    attempt.editor(ide, resolved?.version.version);
+    attempt.fact("editorFound", Boolean(resolved));
+    attempt.fact("wsl", isWsl());
+    attempt.fact("editorCommit", resolved?.version.commit);
     // ENG-2683 — inside WSL, the editor on PATH is usually the WINDOWS app, and its
     // Remote-SSH reads Windows' ssh config, not the WSL one written above (see
     // `lib/wsl.ts`). Launching it would fail in the editor with nothing on our side, so say
@@ -1652,7 +1640,9 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     // 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.
+    attempt.stage("editor_resolution");
     const identity = resolved ? identifyEditorCli(editor, resolved.command) : { kind: "unverified" };
+    attempt.fact("editorIdentity", identity.kind);
     // 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
@@ -1696,8 +1686,7 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     //     no-op that touches nothing.
     //
     //     Cursor is still given no laptop-side equivalent of the WRITE: its AI is captured
-    //     in-container, which is what the Cursor restart (or, off macOS, the quit note at
-    //     selection time) protects.
+    //     in-container through the remote user hooks.
     //
     //     ENG-2152 — a MISMATCH refuses below and opens nothing, so it may not WRITE. See
     //     `chatConfigActionForIdentity`, which is where that belongs: keying the write on
@@ -1756,8 +1745,6 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
         // 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 Cursor these lines already say to quit and reopen it first, so the selection
-        // notice is not restated after them (ENG-2895: it was the third time in one run).
         for (const line of editorNotFoundLines(editor, alias, pageUrl))
             console.log(line);
         return;
@@ -1779,12 +1766,18 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
         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-3158 — before the workspace read, the Cursor quit and the launch, so a candidate
+    // ENG-3158 — before the workspace read and the launch, so a candidate
     // whose editor would take the connection with the wrong Remote-SSH loses no open Cursor
     // windows for a launch that cannot hold. Read-only: nothing is installed or removed.
+    attempt.stage("extensions");
+    const listed = listEditorExtensions(resolved.command);
+    attempt.fact("extensionInventory", listed === null ? "unavailable" : "read");
+    attempt.fact("requiredExtension", listed === null ? "unknown" : listed.split(/\r?\n/).includes(editor.remoteSshExt) ? "present" : "missing");
+    if (listed !== null)
+        attempt.fact("conflictingExtension", conflictingRemoteSshInstalled(editor, listed));
     if (editor.conflictingRemoteSshExt) {
-        const listed = listEditorExtensions(resolved.command);
         if (listed !== null && conflictingRemoteSshInstalled(editor, listed)) {
+            attempt.finish("extension_conflict");
             const editorCmd = pasteableEditorCommand(editor, resolved, process.platform);
             for (const line of conflictingRemoteSshLines(editor, editorCmd, alias, pageUrl))
                 console.log(line);
@@ -1796,70 +1789,19 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     // 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);
-    // ENG-2491, Greptile P1 on #2613 — the baseline probe is taken HERE, before
-    // any decision to quit Cursor, and the resulting `seedVerdict` is checked
-    // before quitting too. `attemptEditorLaunch` below REFUSES the launch on a
-    // mismatched build for any editor with `requiresSeedMatch` set (none today,
-    // ENG-2884), and a refusal opens nothing — so a quit sequenced
-    // ahead of that check could close every Cursor window on a path that was
-    // always going to end in "nothing was opened", with no way given back in
-    // locally. Checking the identical rule first means a quit only ever
-    // happens on a path already known to go on to a real launch attempt.
-    //
-    // The reading is taken ONCE and handed to `attemptEditorLaunch` as its own
-    // baseline too (`probe: () => baseline` below) — one SSH round trip, not
-    // two, for the same reason this file already takes it once for the seed
-    // check and the verification baseline together.
+    const probe = sshProbeRunner(alias, sshExecutable);
+    // Read once for both the seed check and attachment baseline.
     const readSpinner = ora(`Checking your workspace...`).start();
     const baseline = probeWorkspace(editor, probe, resolved.version.commit);
     readSpinner.stop();
     const seed = seedVerdict(resolved.version, baseline);
     const seedWillRefuseLaunch = seed.kind === "mismatch" && editor.requiresSeedMatch;
-    // ENG-2491 — Cursor reads its hooks configuration once, at its OWN launch,
-    // no matter which remote window it then opens (ENG-1728, measured) — so an
-    // ALREADY-RUNNING local Cursor never reloads even for a brand new
-    // Remote-SSH connection. This quits it with the same graceful, never-a-kill
-    // quit `init` uses (see lib/cursor-restart.ts). The launch a few lines
-    // below IS the relaunch — connect already opens the editor, so there is
-    // nothing else to relaunch it into.
-    //
-    // ENG-2890 — NOT from Cursor's own terminal: the quit would kill this
-    // process before the relaunch, leaving no editor and no command. That case
-    // stops before anything is touched, the same way an unconfirmed quit does.
-    //
-    // NEVER proceeds to launch on an unconfirmed quit. Doing so would hand the
-    // new `--remote` argv to the SAME still-running process — Cursor's
-    // single-instance lock just forwards it as a new window into a hooks
-    // service that already initialised — which is exactly today's silent
-    // failure, not a fix for it. So an unconfirmed quit stops here, the same
-    // way every other refusal in this file does: nothing opened, workspace
-    // still up and waiting, and the exact way back in.
-    // Whether the Cursor about to open is a FRESH start, so its prompt recording loads:
-    // it was not running, or this command confirmed it quit. Only then may success say the
-    // work is recorded (Greptile on #3071); elsewhere (Linux, Windows, an unreadable process
-    // list) the candidate was only asked to quit it, and nothing checked that they did.
+    // ENG-3176: never quit an existing desktop for remote hooks. Only a confirmed
+    // cold start needs the historical macOS launch/settle workaround.
     let cursorStartsFresh = false;
     if (!seedWillRefuseLaunch && ide === "cursor" && platformSupportsGracefulCursorRestart(process.platform)) {
         const cursorIo = realCursorProcessIo();
-        const presence = cursorIo.isRunning();
-        if (presence === "not-running")
-            cursorStartsFresh = true;
-        if (presence === "running") {
-            if (runningInsideCursorTerminal()) {
-                for (const line of insideCursorTerminalLines())
-                    console.log(line);
-                return;
-            }
-            info(CURSOR_RESTARTING_LINE);
-            const quit = await attemptQuit(cursorIo);
-            if (!quit) {
-                for (const line of cursorQuitUnconfirmedLines())
-                    console.log(line);
-                return;
-            }
-            cursorStartsFresh = true;
-        }
+        cursorStartsFresh = cursorIo.isRunning() === "not-running";
         // ENG-2884. A COLD start handed `--remote` loses it: measured twice on a real
         // profile (2026-10-01 21:11 and 2026-10-02 00:26 PT), Cursor 3 came up restoring its
         // previous session (the Agents window plus old folders) and never created the
@@ -1887,7 +1829,8 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
         clientVersion: resolved.version,
         ensureExtension: () => {
             const extSpinner = ora(`Checking ${editor.label} Remote-SSH extension...`).start();
-            const state = ensureRemoteSshExtension(editor, resolved.command);
+            const state = ensureRemoteSshExtension(editor, resolved.command, listed);
+            attempt.fact("extensionSetup", state);
             // ENG-2890: an internal step, so it says nothing when it worked.
             if (state === "failed") {
                 extSpinner.warn(`Couldn't install ${editor.label}'s Remote-SSH extension. If ${editor.label} asks for it, install it from the Extensions view.`);
@@ -1902,6 +1845,8 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
         },
         launchLogPath: editorLaunchLogPath,
         launch: (logPath) => {
+            attempt.stage("editor_launch");
+            attempt.checkpoint();
             const launched = launches.send(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
@@ -1911,18 +1856,21 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
             return launched;
         },
         readLaunchLog: () => launches.readLog(readEditorLaunchLog),
-        verifyAttached: (baseline, launched) => verifyEditorAttached(editor, baseline, probe, (waited) => {
-            if (spinners.verify) {
-                spinners.verify.text = `Opening ${editor.label} in your workspace... (${waited}s)`;
-            }
-            // ENG-2884: if the first request still produced no attached window, ask the
-            // (now running) Cursor once more. A window already opening for this folder is
-            // focused rather than duplicated, so a slow first attach costs nothing.
-            if (shouldResendCursorOpen(editor.ide, cursorStartsFresh, waited, resend)) {
-                resend.done = true;
-                launches.send(editorLaunchLogPath());
-            }
-        }, launched, resolved.version.commit),
+        verifyAttached: (baseline, launched) => {
+            attempt.stage("editor_verify");
+            return verifyEditorAttached(editor, baseline, probe, (waited) => {
+                if (spinners.verify) {
+                    spinners.verify.text = `Opening ${editor.label} in your workspace... (${waited}s)`;
+                }
+                // ENG-2884: if the first request still produced no attached window, ask the
+                // (now running) Cursor once more. A window already opening for this folder is
+                // focused rather than duplicated, so a slow first attach costs nothing.
+                if (shouldResendCursorOpen(editor.ide, cursorStartsFresh, waited, resend)) {
+                    resend.done = true;
+                    launches.send(editorLaunchLogPath());
+                }
+            }, launched, resolved.version.commit);
+        },
     });
     if (outcome.kind === "refused") {
         for (const line of editorSeedMismatchLines(editor, outcome.seed, pageUrl, alias)) {
@@ -1932,6 +1880,9 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
     }
     const launchSpinner = spinners.verify;
     if (outcome.kind === "launch-failed") {
+        attempt.finish("launch_failed");
+        attempt.evidence(outcome.error);
+        attempt.evidence(outcome.launchLog);
         // No window was created, so none of the not-connected copy is true here. See
         // `editorLaunchFailedLines`.
         launchSpinner?.fail(`Couldn't start ${editor.label}.`);
@@ -1941,16 +1892,14 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
             console.log(line);
         return;
     }
+    attempt.evidence(outcome.launchLog);
     if (outcome.verdict.kind === "connected") {
-        const recordingKnown = editor.ide !== "cursor" || cursorStartsFresh;
-        launchSpinner?.succeed(recordingKnown
-            ? `${editor.label} is open in your workspace. Your work is recorded.`
-            : `${editor.label} is open in your workspace.`);
-        if (!recordingKnown)
-            skillImport.footer.push(CURSOR_RECORDING_CAVEAT_LINE);
+        attempt.finish("server_detected");
+        launchSpinner?.succeed(`${editor.label}'s server is running in your workspace.`);
         skillImport.footer.push(...editorConnectedLines(editor, alias, verbose));
     }
     else if (outcome.verdict.kind === "unverified") {
+        attempt.finish("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`.
@@ -1959,6 +1908,7 @@ async function connectFlow(token, ideOpt, opts, skillImport) {
             console.log(line);
     }
     else {
+        attempt.finish("not_connected");
         launchSpinner?.fail(`${editor.label} hasn't connected to your workspace yet.`);
         for (const line of editorNotConnectedLines(editor, alias, pageUrl, verbose))
             console.log(line);