litmus-cli 1.4.28 → 1.4.30

package/dist/lib/editor-binary.js

@@ -0,0 +1,72 @@
+import path from "path";
+/**
+ * Where each editor's CLI lives when its installer put it there, per platform.
+ *
+ * Paths are built with the TARGET's separator (`path.win32` / `path.posix`) and never
+ * with the bare `path`, which is bound to the host: a Windows expectation assembled with
+ * a POSIX `path` passes on a POSIX host precisely when the shipped code is wrong there.
+ * That is `chat-model-config.ts`'s `pathFor` rule, and the tests beside this assert
+ * literal strings for the same reason.
+ */
+export function editorInstallCandidates(ide, platform, env, home) {
+    if (platform === "darwin") {
+        const bundle = ide === "cursor" ? "Cursor.app" : "Visual Studio Code.app";
+        const bin = ide === "cursor" ? "cursor" : "code";
+        // A user-local install under ~/Applications is what a drag-install without admin
+        // rights produces, and is invisible to anything that only looks at /Applications.
+        return ["/Applications", path.posix.join(home, "Applications")].map((root) => path.posix.join(root, bundle, "Contents", "Resources", "app", "bin", bin));
+    }
+    if (platform === "win32") {
+        const local = env.LOCALAPPDATA;
+        const programFiles = env.ProgramFiles;
+        const programFilesX86 = env["ProgramFiles(x86)"];
+        const out = [];
+        if (ide === "cursor") {
+            // Cursor's Windows installer is per-user by default; the machine-wide option
+            // lands under Program Files with the same tree beneath it.
+            if (local)
+                out.push(path.win32.join(local, "Programs", "cursor", "resources", "app", "bin", "cursor.cmd"));
+            if (programFiles)
+                out.push(path.win32.join(programFiles, "cursor", "resources", "app", "bin", "cursor.cmd"));
+        }
+        else {
+            if (local)
+                out.push(path.win32.join(local, "Programs", "Microsoft VS Code", "bin", "code.cmd"));
+            if (programFiles)
+                out.push(path.win32.join(programFiles, "Microsoft VS Code", "bin", "code.cmd"));
+            if (programFilesX86)
+                out.push(path.win32.join(programFilesX86, "Microsoft VS Code", "bin", "code.cmd"));
+        }
+        return out;
+    }
+    // Linux. Package installs and the vendor tarballs; an AppImage left in ~/Downloads is
+    // not reachable from here and is the documented residual.
+    const bin = ide === "cursor" ? "cursor" : "code";
+    const roots = ide === "cursor"
+        ? ["/usr/share/cursor/bin", "/opt/Cursor/bin", "/opt/cursor/bin", path.posix.join(home, ".local", "bin")]
+        : ["/usr/share/code/bin", "/opt/visual-studio-code/bin", "/snap/bin", path.posix.join(home, ".local", "bin")];
+    return roots.map((root) => path.posix.join(root, bin));
+}
+const SHELL_SAFE_ARG = /^[A-Za-z0-9_@+=:,./\\-]+$/;
+/**
+ * What a quoted `cmd.exe` token cannot carry. A `"` closes the quoting this opens, `%`
+ * is expanded inside quotes, and a control character can end the line outright.
+ * Everything else — spaces, `&`, `|`, `^`, parentheses — is literal once quoted, which
+ * is why the command may hold them and an unquoted ARGUMENT may not.
+ */
+// eslint-disable-next-line no-control-regex
+const WIN32_UNQUOTABLE_COMMAND = /["%\u0000-\u001f]/;
+export function editorSpawnSpec(command, args, platform) {
+    if (platform !== "win32")
+        return { command, args, shell: false };
+    for (const a of args) {
+        if (!SHELL_SAFE_ARG.test(a))
+            throw new Error(`refusing to build a shell command line around: ${a}`);
+    }
+    // Not an error — see the block comment. A command we cannot quote is a command we
+    // cannot drive, which is the same answer as a command that will not run.
+    if (WIN32_UNQUOTABLE_COMMAND.test(command))
+        return null;
+    return { command: `"${command}"`, args, shell: true };
+}
+//# sourceMappingURL=editor-binary.js.map

package/dist/lib/editor-binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-binary.js","sourceRoot":"","sources":["../../src/lib/editor-binary.ts"],"names":[],"mappings":"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"}

package/dist/lib/editor-ide.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The native editors `litmus connect` can drive.
+ *
+ * It lives here rather than in `commands/connect.ts` only so that the lib modules the
+ * connect flow leans on — `editor-binary.ts`, and anything after it — can name an editor
+ * without importing the command back and closing a cycle. `connect.ts` re-exports it, so
+ * the record it belongs to (`NATIVE_EDITORS`, which carries every measured difference
+ * between the two) is still the one place that describes them.
+ */
+export type NativeIde = "vscode" | "cursor";
+//# sourceMappingURL=editor-ide.d.ts.map

package/dist/lib/editor-ide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-ide.d.ts","sourceRoot":"","sources":["../../src/lib/editor-ide.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA"}

package/dist/lib/editor-ide.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=editor-ide.js.map

package/dist/lib/editor-ide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-ide.js","sourceRoot":"","sources":["../../src/lib/editor-ide.ts"],"names":[],"mappings":""}

package/dist/lib/editor-server.d.ts

@@ -0,0 +1,253 @@
+/**
+ * ENG-2332 — whether a native editor can, and then DID, start its server inside the
+ * workspace. Everything here is pure or takes its one side effect as an argument, so the
+ * decisions are testable without a Cursor install and without a live container.
+ *
+ * ## The failure this exists to stop
+ *
+ * A VS Code-family editor opening a Remote-SSH window does not run anything of ours: it
+ * copies its OWN server build into the remote home and launches it there. Which build is
+ * decided by the CLIENT, by commit, and the two editors are pinned to each other — a
+ * 3.19.13 client will not talk to a 3.20.21 server, it fetches its own.
+ *
+ * A Codespaces v2 container has sealed egress. It cannot reach `api2.cursor.sh`,
+ * `downloads.cursor.com` or `github.com` (measured from inside a prod workspace,
+ * 2026-09-15: `curl` returns 000 after a 12s timeout). The only route a non-baked client
+ * has is the mirror (`infra/vscode-mirror/`, ENG-1062 for VS Code, ENG-1265 + ENG-1936
+ * for Cursor), and a mirror route that has stopped matching what a client asks for is
+ * indistinguishable, from the client's side, from no route at all.
+ *
+ * What the client does then is the whole problem: it gives up and opens the window
+ * anyway. MEASURED on macOS against a live prod workspace (ENG-2332):
+ *
+ *   - `cursor --remote ssh-remote+<alias> <dir>` exits 0 and prints nothing.
+ *   - A window appears, carrying the remote authority — `storage.json` records
+ *     `"remoteAuthority": "ssh-remote+<alias>"` — and Cursor's ordinary agent home
+ *     screen. It is indistinguishable from a working one.
+ *   - The renderer log says `Started local extension host`, and every
+ *     `$updateShellExecCapabilities` is refused as `non-authoritative host`.
+ *   - Nothing under `~/.cursor-server` on the VM is touched. No `data/logs` is created.
+ *     No server process exists.
+ *
+ * So the candidate works in what looks like their editor, on their own laptop's files,
+ * and NOTHING IS RECORDED. That is the worst outcome this product has, and until this
+ * module every signal the CLI printed said it had worked.
+ *
+ * ## The two questions, and why they are both asked
+ *
+ * `seedVerdict` asks BEFORE launching: is the client's commit the one the image baked?
+ * `verifyVerdict` asks AFTER: did a server actually come up? Neither replaces the other.
+ * The first cannot be conclusive (the mirror may well serve a drifted client, and does
+ * for VS Code), and the second cannot be prompt — it costs the candidate up to a minute
+ * of waiting and, on a refusal, they have already opened a window. Asking both means the
+ * common, knowable failure is refused in advance and every other one is still loud.
+ *
+ * ## Why the probe is one shell command, and what it costs
+ *
+ * Each probe is `ssh <alias> <command>`, which sshd serves by exec'ing the candidate's
+ * login shell — so `/etc/ld.so.preload`'s `libttee.so` tees it and it lands in
+ * `candidate_activity_logs` as a `terminal_command`. That is acceptable and is NOT
+ * silent: the probe carries no pty, so `libttee`'s `tty_origin()` stamps it
+ * `origin: "tool"` (ENG-2179), which the read side groups as machinery rather than as
+ * something the candidate typed, and which the idle clock (ENG-2167) reads as a
+ * connection and never as work. It is still a row per probe, so the schedule below is
+ * deliberately sparse and backs off rather than polling on a fixed short interval.
+ */
+/** What one probe of the workspace answered. Every field is three-valued on purpose. */
+export interface WorkspaceProbe {
+    /**
+     * The server commit the IMAGE baked, from the cache pointer, or null when the pointer
+     * is absent or unreadable. Null is "we do not know", never "there is no bundle".
+     */
+    seedCommit: string | null;
+    /** How many processes the workspace is running out of this editor's server tree. */
+    serverProcesses: number;
+    /**
+     * Newest entry under `<serverHome>/data/logs`, or null when that directory does not
+     * exist. The names are timestamps (`20260915T200622`), so lexicographic order is
+     * chronological order and no `stat` is needed.
+     */
+    newestLogDir: string | null;
+}
+/**
+ * The command a probe runs in the workspace. POSIX `sh` only, and built from two
+ * constants we own — never from anything a candidate or a company supplies.
+ *
+ * Four details are load-bearing, and three of them are about one thing: `ps` output is
+ * full of near-misses, and a false POSITIVE here certifies a window that records nothing.
+ *
+ * The LEADING DOT keeps the pattern off the browser IDE — `~/.openvscode-server` contains
+ * `vscode-server` but not `/.vscode-server/`, and the browser IDE's node process is
+ * running on every healthy container, so a pattern without the dot answers "connected"
+ * for a native editor that never attached. The `[.]` bracket keeps it off the `grep` in
+ * that same listing, and the ANCHOR keeps it off everything that merely names the path.
+ * See the comments in the body for the measurements behind each.
+ *
+ * THE HOME SPELLING IS NOT THE ONLY ONE A HEALTHY CONTAINER PRODUCES, and missing the
+ * other one is silent. `litmus-firstboot.sh`'s `prewarm_editor` installs the baked bundle
+ * as a SYMLINK — `~/.<editor>-server/cli/servers/Stable-<commit>/server` ->
+ * `/opt/<editor>-server-cache/<commit>` — and the VS Code-family server bootstrap
+ * resolves its own root with `readlink -f "$0"` before exec'ing node, so on a PREWARMED
+ * (commit-matching, i.e. healthy) container argv[0] can be the `/opt` path. This repo
+ * already records both spellings for exactly these trees:
+ * `frontend/lib/server/tool-command-origin.ts`'s `SYSTEM_EDITOR_MARKERS` lists
+ * `/opt/vscode-server-cache/` and `/opt/cursor-server-cache/` beside `/.vscode-server/`.
+ * So `serverProcessPattern` carries both as alternatives, and every property above still
+ * holds of the added one: it is anchored at argv[0], so a candidate's `ls
+ * /opt/cursor-server-cache` is still not a server; it still cannot self-match, because
+ * the probe's own argv[0] is `sh` and the cache root reaches the command only as a shell
+ * VARIABLE, never as a literal followed by a slash; and unlike the home spelling that
+ * tree is root-owned on a read-only rootfs, so a candidate cannot put a binary there to
+ * forge one.
+ *
+ * WHAT IS STILL UNMEASURED, stated rather than implied: the controls behind this pattern
+ * are synthetic argv lines, taken on a laptop and not against a real prewarmed container.
+ * `ps -eo args=` on a live attached workspace, for both editors, is still to be confirmed.
+ * Adding the alternative is the safe direction in the meantime — it can only restore a
+ * signal that would otherwise be silent on the HEALTHY path, and the failure it prevents
+ * is the false alarm `verifyVerdict` names: a candidate who re-runs `litmus connect` with
+ * a window already open joins the running server, writes no new log directory, and would
+ * be told their work is not recorded.
+ *
+ * The banner is printed FIRST and unconditionally. `ssh` mixes the remote command's
+ * stdout with anything the login shell's rc files print, and a candidate's own `.bashrc`
+ * can write whatever it likes; a run that did not reach the banner is not a reading.
+ *
+ * `ps -eo args=` and not `pgrep`: procps is what the container has (the browser IDE's own
+ * monitor loop runs `ps -ax -o …`, ENG-2143), and `pgrep` is not guaranteed. A missing
+ * `ps` yields `proc 0`, which is the safe direction — it can only withhold a "connected"
+ * verdict, never manufacture one.
+ */
+/**
+ * The argv[0] pattern the probe hands `grep -E`, as ONE derivation used two ways.
+ *
+ * `remoteProbeCommand` calls it with the shell EXPRESSIONS that expand to the two names
+ * (`${d#.}` and `${c}`), so the alternation reaches the container as a pattern built from
+ * shell variables; a test calls it with the literal names and gets the ERE the container
+ * will actually run. Keeping both behind one function is what stops the anchor or the
+ * alternation being right in one form and wrong in the other.
+ */
+export declare function serverProcessPattern(serverHomeName: string, cacheRoot: string): string;
+/**
+ * The names under `<serverHome>/data/logs` this probe will consider, as an ERE.
+ *
+ * The maximum is taken lexicographically, which is chronological ONLY over timestamps —
+ * and in C collation every letter sorts above every digit, so one stray `.log`, lock file
+ * or future named subdirectory becomes the maximum forever. The direction that breaks in
+ * is the bad one: `newestLogDir` stops advancing, the log signal dies silently, and a
+ * genuinely attached editor reads as `not-connected` — the false alarm at a working
+ * candidate that the process signal exists to prevent. So the invariant the field's
+ * docstring states is ENFORCED here rather than assumed, and a directory holding nothing
+ * timestamp-shaped answers "no logs", which is a missing input.
+ *
+ * The prefix is anchored and the tail is not: a build that appends a suffix to the
+ * timestamp still sorts chronologically, while a name that does not START with one cannot
+ * poison the maximum.
+ */
+export declare const LOG_DIR_NAME_ERE = "^[0-9]{8}T[0-9]{6}";
+export declare function remoteProbeCommand(serverHomeDir: string, seedCommitPath: string): string;
+/**
+ * Read a probe's stdout. Returns null for anything that is not a complete reading —
+ * a missing banner, a missing field, a non-commit `seed` — because a partial probe that
+ * degrades into a WorkspaceProbe with plausible zeros is a probe that reports "no server
+ * is running" when what happened is that the probe did not run.
+ */
+export declare function parseWorkspaceProbe(stdout: string | null): WorkspaceProbe | null;
+/** What `<editor> --version` says about itself. */
+export interface EditorVersion {
+    version: string | null;
+    commit: string | null;
+}
+/**
+ * Read `code --version` / `cursor --version`. Both print exactly three lines — version,
+ * commit, arch — and NEITHER prints a product name (the measurement is in
+ * `NATIVE_EDITORS`' block comment in `connect.ts`, and is why identity is read off
+ * `--help` instead). The commit is found by SHAPE rather than by line number, so a build
+ * that adds a line does not silently shift which field we read; the version is the first
+ * line that is not the commit.
+ */
+export declare function parseEditorVersion(stdout: string | null): EditorVersion;
+/**
+ * Whether the client will find its own server already in the workspace.
+ *
+ * `unknown` is the answer to every missing input, and the direction that fails in is the
+ * point. We can positively assert only one thing — "these two commits are both readable
+ * and they differ" — so an unreadable `--version`, an unreachable workspace, an image
+ * with no pointer and an editor that names its build some other way may only move the
+ * answer towards "we could not tell", never towards a refusal. Refusing on a probe that
+ * failed for its own reasons would take a working editor away from a candidate on the
+ * strength of nothing; proceeding leaves them where they were before this existed, and
+ * `verifyVerdict` below is what still makes that loud.
+ */
+export type SeedVerdict = {
+    kind: "match";
+    commit: string;
+} | {
+    kind: "mismatch";
+    clientCommit: string;
+    clientVersion: string | null;
+    seedCommit: string;
+} | {
+    kind: "unknown";
+    reason: "no-client-commit" | "no-workspace-reading" | "no-seed";
+};
+export declare function seedVerdict(client: EditorVersion, probe: WorkspaceProbe | null): SeedVerdict;
+/**
+ * Did a server come up because of THIS launch?
+ *
+ * THE TWO SIGNALS ARE READ DIFFERENTLY, and which is which is the whole of this.
+ *
+ * A LOG DIRECTORY IS AN ARTIFACT ON DISK, so it must be NEW. The home mount persists
+ * across park, resume and re-provision, so `<serverHome>/data/logs` from a connection
+ * last Tuesday is still sitting there today; a verdict keyed on its mere existence
+ * answers "connected" for the exact candidate this ticket is about — one whose second
+ * `litmus connect` attaches to nothing. That is why the caller takes a BASELINE probe
+ * before launching and hands it back here.
+ *
+ * SO A MISSING BASELINE DISABLES THAT SIGNAL ENTIRELY, and reading it as "there was no
+ * log directory before" is the same false reassurance arriving by a different road. The
+ * baseline probe is one `ssh`, and every way it can fail — a flaky link, a key that
+ * wants a passphrase, a container mid-resume — answers null; a candidate who has
+ * connected to this workspace before still has last Tuesday's `data/logs` sitting in the
+ * persistent home, so a null baseline plus a dead launch would be certified "connected"
+ * on an artifact this launch did not create. A missing input may only move the answer
+ * towards "we could not tell", which is the posture every other verdict in this module
+ * already takes, so with no baseline only a RUNNING PROCESS may conclude anything and
+ * everything else is `unverified` — never `not-connected`, because we have no reading to
+ * call anything new against.
+ *
+ * And the comparison is `>` rather than `!==`: the names are timestamps, so a directory
+ * that merely CHANGED (an editor pruning its own logs, a name that sorts earlier) is not
+ * evidence that this launch wrote one.
+ *
+ * A RUNNING PROCESS IS A STATEMENT ABOUT NOW, and needs no baseline. Park is `docker
+ * stop`, so every process in the container dies with it and one that is running belongs
+ * to this container's current run — nothing stale can be seen here. Requiring it to be
+ * new as well is what an earlier cut of this did, and it is wrong in the direction that
+ * matters: a candidate who already has a window open and runs `litmus connect` again
+ * gets a second window attached to the SAME server, creating no process and no log
+ * directory, and would have been told their work was not being recorded. Telling a
+ * working candidate to abandon their editor is worse than the residual, which is narrow
+ * and named: a server already up that this particular window fails to join reads as
+ * connected. For Cursor the one known cause of that — a build mismatch — has already
+ * refused the launch before this is ever asked.
+ */
+export type VerifyVerdict = {
+    kind: "connected";
+    via: "process" | "logs";
+} | {
+    kind: "not-connected";
+} | {
+    kind: "unverified";
+};
+export declare function verifyVerdict(baseline: WorkspaceProbe | null, current: WorkspaceProbe | null): VerifyVerdict;
+/**
+ * When to probe, in milliseconds after the launch, and why it is a list rather than an
+ * interval. Every entry costs one `terminal_command` row in the candidate's own activity
+ * record (see this module's header), so the schedule spends its probes where the answer
+ * changes — a cache hit attaches in seconds — and backs off rather than paying twenty
+ * rows to shave a second off a case that was going to fail anyway. The last entry IS the
+ * budget: ~60s, which is the ticket's bound and comfortably past a warm attach.
+ */
+export declare const VERIFY_SCHEDULE_MS: readonly number[];
+//# sourceMappingURL=editor-server.d.ts.map

package/dist/lib/editor-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-server.d.ts","sourceRoot":"","sources":["../../src/lib/editor-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,oFAAoF;IACpF,eAAe,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,uBAAuB,CAAA;AAEpD,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAkDxF;AAKD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,GAAG,IAAI,CAwBhF;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CASvE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC5F;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,kBAAkB,GAAG,sBAAsB,GAAG,SAAS,CAAA;CAAE,CAAA;AAExF,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,GAAG,WAAW,CAW5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAA;AAE1B,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,aAAa,CAU5G;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAA2D,CAAA"}

package/dist/lib/editor-server.js

@@ -0,0 +1,286 @@
+/**
+ * ENG-2332 — whether a native editor can, and then DID, start its server inside the
+ * workspace. Everything here is pure or takes its one side effect as an argument, so the
+ * decisions are testable without a Cursor install and without a live container.
+ *
+ * ## The failure this exists to stop
+ *
+ * A VS Code-family editor opening a Remote-SSH window does not run anything of ours: it
+ * copies its OWN server build into the remote home and launches it there. Which build is
+ * decided by the CLIENT, by commit, and the two editors are pinned to each other — a
+ * 3.19.13 client will not talk to a 3.20.21 server, it fetches its own.
+ *
+ * A Codespaces v2 container has sealed egress. It cannot reach `api2.cursor.sh`,
+ * `downloads.cursor.com` or `github.com` (measured from inside a prod workspace,
+ * 2026-09-15: `curl` returns 000 after a 12s timeout). The only route a non-baked client
+ * has is the mirror (`infra/vscode-mirror/`, ENG-1062 for VS Code, ENG-1265 + ENG-1936
+ * for Cursor), and a mirror route that has stopped matching what a client asks for is
+ * indistinguishable, from the client's side, from no route at all.
+ *
+ * What the client does then is the whole problem: it gives up and opens the window
+ * anyway. MEASURED on macOS against a live prod workspace (ENG-2332):
+ *
+ *   - `cursor --remote ssh-remote+<alias> <dir>` exits 0 and prints nothing.
+ *   - A window appears, carrying the remote authority — `storage.json` records
+ *     `"remoteAuthority": "ssh-remote+<alias>"` — and Cursor's ordinary agent home
+ *     screen. It is indistinguishable from a working one.
+ *   - The renderer log says `Started local extension host`, and every
+ *     `$updateShellExecCapabilities` is refused as `non-authoritative host`.
+ *   - Nothing under `~/.cursor-server` on the VM is touched. No `data/logs` is created.
+ *     No server process exists.
+ *
+ * So the candidate works in what looks like their editor, on their own laptop's files,
+ * and NOTHING IS RECORDED. That is the worst outcome this product has, and until this
+ * module every signal the CLI printed said it had worked.
+ *
+ * ## The two questions, and why they are both asked
+ *
+ * `seedVerdict` asks BEFORE launching: is the client's commit the one the image baked?
+ * `verifyVerdict` asks AFTER: did a server actually come up? Neither replaces the other.
+ * The first cannot be conclusive (the mirror may well serve a drifted client, and does
+ * for VS Code), and the second cannot be prompt — it costs the candidate up to a minute
+ * of waiting and, on a refusal, they have already opened a window. Asking both means the
+ * common, knowable failure is refused in advance and every other one is still loud.
+ *
+ * ## Why the probe is one shell command, and what it costs
+ *
+ * Each probe is `ssh <alias> <command>`, which sshd serves by exec'ing the candidate's
+ * login shell — so `/etc/ld.so.preload`'s `libttee.so` tees it and it lands in
+ * `candidate_activity_logs` as a `terminal_command`. That is acceptable and is NOT
+ * silent: the probe carries no pty, so `libttee`'s `tty_origin()` stamps it
+ * `origin: "tool"` (ENG-2179), which the read side groups as machinery rather than as
+ * something the candidate typed, and which the idle clock (ENG-2167) reads as a
+ * connection and never as work. It is still a row per probe, so the schedule below is
+ * deliberately sparse and backs off rather than polling on a fixed short interval.
+ */
+/** A probe line's shape, so a truncated or interleaved read is refused rather than parsed. */
+const PROBE_BANNER = "litmus-probe 1";
+/**
+ * The command a probe runs in the workspace. POSIX `sh` only, and built from two
+ * constants we own — never from anything a candidate or a company supplies.
+ *
+ * Four details are load-bearing, and three of them are about one thing: `ps` output is
+ * full of near-misses, and a false POSITIVE here certifies a window that records nothing.
+ *
+ * The LEADING DOT keeps the pattern off the browser IDE — `~/.openvscode-server` contains
+ * `vscode-server` but not `/.vscode-server/`, and the browser IDE's node process is
+ * running on every healthy container, so a pattern without the dot answers "connected"
+ * for a native editor that never attached. The `[.]` bracket keeps it off the `grep` in
+ * that same listing, and the ANCHOR keeps it off everything that merely names the path.
+ * See the comments in the body for the measurements behind each.
+ *
+ * THE HOME SPELLING IS NOT THE ONLY ONE A HEALTHY CONTAINER PRODUCES, and missing the
+ * other one is silent. `litmus-firstboot.sh`'s `prewarm_editor` installs the baked bundle
+ * as a SYMLINK — `~/.<editor>-server/cli/servers/Stable-<commit>/server` ->
+ * `/opt/<editor>-server-cache/<commit>` — and the VS Code-family server bootstrap
+ * resolves its own root with `readlink -f "$0"` before exec'ing node, so on a PREWARMED
+ * (commit-matching, i.e. healthy) container argv[0] can be the `/opt` path. This repo
+ * already records both spellings for exactly these trees:
+ * `frontend/lib/server/tool-command-origin.ts`'s `SYSTEM_EDITOR_MARKERS` lists
+ * `/opt/vscode-server-cache/` and `/opt/cursor-server-cache/` beside `/.vscode-server/`.
+ * So `serverProcessPattern` carries both as alternatives, and every property above still
+ * holds of the added one: it is anchored at argv[0], so a candidate's `ls
+ * /opt/cursor-server-cache` is still not a server; it still cannot self-match, because
+ * the probe's own argv[0] is `sh` and the cache root reaches the command only as a shell
+ * VARIABLE, never as a literal followed by a slash; and unlike the home spelling that
+ * tree is root-owned on a read-only rootfs, so a candidate cannot put a binary there to
+ * forge one.
+ *
+ * WHAT IS STILL UNMEASURED, stated rather than implied: the controls behind this pattern
+ * are synthetic argv lines, taken on a laptop and not against a real prewarmed container.
+ * `ps -eo args=` on a live attached workspace, for both editors, is still to be confirmed.
+ * Adding the alternative is the safe direction in the meantime — it can only restore a
+ * signal that would otherwise be silent on the HEALTHY path, and the failure it prevents
+ * is the false alarm `verifyVerdict` names: a candidate who re-runs `litmus connect` with
+ * a window already open joins the running server, writes no new log directory, and would
+ * be told their work is not recorded.
+ *
+ * The banner is printed FIRST and unconditionally. `ssh` mixes the remote command's
+ * stdout with anything the login shell's rc files print, and a candidate's own `.bashrc`
+ * can write whatever it likes; a run that did not reach the banner is not a reading.
+ *
+ * `ps -eo args=` and not `pgrep`: procps is what the container has (the browser IDE's own
+ * monitor loop runs `ps -ax -o …`, ENG-2143), and `pgrep` is not guaranteed. A missing
+ * `ps` yields `proc 0`, which is the safe direction — it can only withhold a "connected"
+ * verdict, never manufacture one.
+ */
+/**
+ * The argv[0] pattern the probe hands `grep -E`, as ONE derivation used two ways.
+ *
+ * `remoteProbeCommand` calls it with the shell EXPRESSIONS that expand to the two names
+ * (`${d#.}` and `${c}`), so the alternation reaches the container as a pattern built from
+ * shell variables; a test calls it with the literal names and gets the ERE the container
+ * will actually run. Keeping both behind one function is what stops the anchor or the
+ * alternation being right in one form and wrong in the other.
+ */
+export function serverProcessPattern(serverHomeName, cacheRoot) {
+    return `^[^ ]*(/[.]${serverHomeName}/|${cacheRoot}/)`;
+}
+/**
+ * The names under `<serverHome>/data/logs` this probe will consider, as an ERE.
+ *
+ * The maximum is taken lexicographically, which is chronological ONLY over timestamps —
+ * and in C collation every letter sorts above every digit, so one stray `.log`, lock file
+ * or future named subdirectory becomes the maximum forever. The direction that breaks in
+ * is the bad one: `newestLogDir` stops advancing, the log signal dies silently, and a
+ * genuinely attached editor reads as `not-connected` — the false alarm at a working
+ * candidate that the process signal exists to prevent. So the invariant the field's
+ * docstring states is ENFORCED here rather than assumed, and a directory holding nothing
+ * timestamp-shaped answers "no logs", which is a missing input.
+ *
+ * The prefix is anchored and the tail is not: a build that appends a suffix to the
+ * timestamp still sorts chronologically, while a name that does not START with one cannot
+ * poison the maximum.
+ */
+export const LOG_DIR_NAME_ERE = "^[0-9]{8}T[0-9]{6}";
+export function remoteProbeCommand(serverHomeDir, seedCommitPath) {
+    // Both arguments are module constants in `connect.ts`. Assert that rather than trust
+    // it: a probe body is a shell program, and the day one of these becomes derived from
+    // anything else, this is the line that has to fail instead of interpolating.
+    if (!/^\.[a-z0-9-]+$/.test(serverHomeDir))
+        throw new Error(`unsafe server home dir: ${serverHomeDir}`);
+    if (!/^\/[A-Za-z0-9/_.-]+$/.test(seedCommitPath))
+        throw new Error(`unsafe seed path: ${seedCommitPath}`);
+    // The baked bundle and its pointer are ONE tree: `/opt/<editor>-server-cache/COMMIT`
+    // sits inside `/opt/<editor>-server-cache/`. Deriving the root from the pointer rather
+    // than declaring it again keeps the record in `connect.ts` the only place either is
+    // spelled — a second literal is a copy that goes stale silently, which is exactly what
+    // `backend/tests/test_editor_server_paths.py` pins the first one against.
+    const cacheRoot = seedCommitPath.replace(/\/[^/]+$/, "");
+    if (!/^\/[A-Za-z0-9/_.-]+$/.test(cacheRoot))
+        throw new Error(`unsafe seed path: ${seedCommitPath}`);
+    // THE COMMAND MUST NOT CONTAIN THE STRING IT SEARCHES FOR. `ps -eo args=` lists this
+    // probe's own `sh -c <command>` process, so a body carrying a literal
+    // `/.cursor-server/` — which the obvious spelling of the logs path does — matches
+    // itself. MEASURED: the first cut of this returned `proc 4` on a laptop with no server
+    // of any kind running. The consequence is not a false "connected", because the BASELINE
+    // probe matches itself too and `verifyVerdict` then sees a process that was already
+    // there; it is worse than that — the process signal quietly stops being a signal, and
+    // the whole verification silently rests on the log directory alone.
+    //
+    // So the directory name is held in `$d` and never written next to a slash, and the
+    // pattern keeps `[.]` (which also stops it matching the `grep` in that same listing).
+    // `${d#.}` strips the leading dot so the bracket can supply it.
+    //
+    // AND THE PATTERN IS ANCHORED AT ARGV[0], because the dangerous direction here is a
+    // false POSITIVE: a probe that certifies a dead window is worse than one that says
+    // nothing. A candidate's own `ls ~/.cursor-server`, a `grep` over it, an editor's file
+    // watcher — any of them puts that path in a `ps` listing while proving nothing about a
+    // server. `^[^ ]*` requires the path to be the EXECUTABLE, which it is for the server
+    // (its node binary lives inside that tree) and is not for anything merely naming it.
+    // A server launched some other way loses this signal and keeps the log one, which is
+    // the safe way for it to be wrong.
+    const logs = `"$HOME/$d/data/logs"`;
+    // Both names reach the pattern as shell VARIABLES, never as literals followed by a
+    // slash, so the command text still cannot hold the string it searches for.
+    const pattern = serverProcessPattern("${d#.}", "${c}");
+    return [
+        `printf '${PROBE_BANNER}\\n';`,
+        `d=${serverHomeDir};`,
+        `c=${cacheRoot};`,
+        `if [ -r '${seedCommitPath}' ]; then`,
+        `printf 'seed %s\\n' "$(tr -d '\\r\\n' < '${seedCommitPath}' 2>/dev/null)";`,
+        `else printf 'seed -\\n'; fi;`,
+        `printf 'proc %s\\n' "$(ps -eo args= 2>/dev/null | grep -Ec "${pattern}" || true)";`,
+        `if [ -d ${logs} ]; then`,
+        `printf 'log %s\\n' "$(ls -1 ${logs} 2>/dev/null | grep -E '${LOG_DIR_NAME_ERE}' | sort | tail -n 1)";`,
+        `else printf 'log -\\n'; fi`,
+    ].join(" ");
+}
+/** A 40-hex commit, the only shape either editor names a server build by. */
+const COMMIT_RE = /^[0-9a-f]{40}$/;
+/**
+ * Read a probe's stdout. Returns null for anything that is not a complete reading —
+ * a missing banner, a missing field, a non-commit `seed` — because a partial probe that
+ * degrades into a WorkspaceProbe with plausible zeros is a probe that reports "no server
+ * is running" when what happened is that the probe did not run.
+ */
+export function parseWorkspaceProbe(stdout) {
+    if (!stdout)
+        return null;
+    const lines = stdout.split(/\r?\n/).map((l) => l.trim());
+    if (!lines.includes(PROBE_BANNER))
+        return null;
+    const field = (name) => {
+        // LAST match wins: an rc file that echoes something shaped like a field cannot
+        // displace ours, because ours are printed after the shell has finished starting.
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (lines[i] === name || lines[i].startsWith(`${name} `))
+                return lines[i].slice(name.length).trim();
+        }
+        return null;
+    };
+    const seedRaw = field("seed");
+    const procRaw = field("proc");
+    const logRaw = field("log");
+    if (seedRaw === null || procRaw === null || logRaw === null)
+        return null;
+    const proc = Number.parseInt(procRaw, 10);
+    if (!Number.isFinite(proc) || proc < 0)
+        return null;
+    const seedCommit = COMMIT_RE.test(seedRaw) ? seedRaw : null;
+    return {
+        seedCommit,
+        serverProcesses: proc,
+        newestLogDir: logRaw === "-" || logRaw === "" ? null : logRaw,
+    };
+}
+/**
+ * Read `code --version` / `cursor --version`. Both print exactly three lines — version,
+ * commit, arch — and NEITHER prints a product name (the measurement is in
+ * `NATIVE_EDITORS`' block comment in `connect.ts`, and is why identity is read off
+ * `--help` instead). The commit is found by SHAPE rather than by line number, so a build
+ * that adds a line does not silently shift which field we read; the version is the first
+ * line that is not the commit.
+ */
+export function parseEditorVersion(stdout) {
+    if (!stdout)
+        return { version: null, commit: null };
+    const lines = stdout
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    const commit = lines.find((l) => COMMIT_RE.test(l)) ?? null;
+    const version = lines.find((l) => !COMMIT_RE.test(l) && /^\d+\.\d+/.test(l)) ?? null;
+    return { version, commit };
+}
+export function seedVerdict(client, probe) {
+    if (!client.commit)
+        return { kind: "unknown", reason: "no-client-commit" };
+    if (!probe)
+        return { kind: "unknown", reason: "no-workspace-reading" };
+    if (!probe.seedCommit)
+        return { kind: "unknown", reason: "no-seed" };
+    if (probe.seedCommit === client.commit)
+        return { kind: "match", commit: client.commit };
+    return {
+        kind: "mismatch",
+        clientCommit: client.commit,
+        clientVersion: client.version,
+        seedCommit: probe.seedCommit,
+    };
+}
+export function verifyVerdict(baseline, current) {
+    if (!current)
+        return { kind: "unverified" };
+    if (current.serverProcesses > 0)
+        return { kind: "connected", via: "process" };
+    if (!baseline)
+        return { kind: "unverified" };
+    if (current.newestLogDir !== null && current.newestLogDir > (baseline.newestLogDir ?? "")) {
+        return { kind: "connected", via: "logs" };
+    }
+    // No server running and a log directory that has not advanced is the measured failure:
+    // the client gave up before writing anything to the workspace at all.
+    return { kind: "not-connected" };
+}
+/**
+ * When to probe, in milliseconds after the launch, and why it is a list rather than an
+ * interval. Every entry costs one `terminal_command` row in the candidate's own activity
+ * record (see this module's header), so the schedule spends its probes where the answer
+ * changes — a cache hit attaches in seconds — and backs off rather than paying twenty
+ * rows to shave a second off a case that was going to fail anyway. The last entry IS the
+ * budget: ~60s, which is the ticket's bound and comfortably past a warm attach.
+ */
+export const VERIFY_SCHEDULE_MS = [4000, 9000, 15000, 23000, 33000, 45000, 60000];
+//# sourceMappingURL=editor-server.js.map