@floh-solutions/pharos-cli 0.31.1 → 0.33.0

package/dist/commands/delegate.js

@@ -1,11 +1,12 @@
 import { execFile } from "node:child_process";
-import { stat } from "node:fs/promises";
+import { realpath, stat } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
 import { findApp, HOSTS, HOST_IDS, AGENT_IDS, MODES, isAgentId, isHostId, isMode, } from "../delegate/hosts.js";
+import { ARGUS_NEW_WORKER, ARGUS_REASONS, ARGUS_TEXT_LIMIT, ARGUS_WAIT_SECONDS, ArgusUnreachableError, askArgus, candidatesSupport, delegateCandidatesRequest, delegateRequest, delegateStatusRequest, fleetStatusRequest, isFailure, mapRefusal, parseCandidates, parseFleet, rankWorkers, readDelegation, readTimeoutMs, systemArgusDeps, unreachable, } from "../delegate/argus.js";
 import { asTypedInput, LAUNCH_SCRIPT, launchCommand, SEND_TO_TAB_SCRIPT } from "../delegate/quote.js";
 import { findSessions, rankSessions, systemProbes, } from "../delegate/sessions.js";
-import { BRIDGE_EXTENSION_ID, bridgeAtLeast, CLAUDE_EXTENSION_ID, extensionsDirectory, installedExtensions, SESSION_BRIDGE_VERSION, } from "../delegate/vsix.js";
+import { BRIDGE_EXTENSION_ID, bridgeAtLeast, bundledBridge, bundledVsixPath, CLAUDE_EXTENSION_ID, extensionsDirectory, installBridge, installedExtensions, SESSION_BRIDGE_VERSION, } from "../delegate/vsix.js";
 import { CliError, EXIT_FAILED, EXIT_USAGE, emit, emitText, usageError } from "../output.js";
 import { resolveOnPath } from "./doctor.js";
 const run = promisify(execFile);
@@ -20,14 +21,47 @@ export const REASONS = [
     "automation-denied",
     "folder-missing",
     "unsupported",
-    /** `--session <id>` named a session that is no longer a target on this folder. */
+    /**
+     * `--session <id>` named a session that is no longer a target on this folder.
+     *
+     * On Navarch it is also what the daemon's `worker-not-eligible` becomes: the
+     * row you picked is not one this machine will deliver to, whether it exited,
+     * took a mission, or was never a candidate. Same fact, same fix — read the
+     * list again and pick from it.
+     */
     "session-gone",
+    // **`session-not-targetable` was here and is gone** (#1412). It said the
+    // `delegate` op could not express a target worker at all; argus #1402 added
+    // `worker`, so no call can produce it any more. A daemon that predates that
+    // field is `argusd-outdated`, which is the truth and carries the fix (reload
+    // the daemon) — where this one carried none.
+    //
+    // …and the Argus socket's own, each naming a different fix. See
+    // `delegate/argus.js` — they are defined there because that is where the
+    // daemon's reasons are mapped onto them.
+    ...ARGUS_REASONS,
 ];
+/**
+ * A second, narrower axis on a refusal: WHICH shape of a reason this is.
+ *
+ * One value so far, and it exists because one `bridge-not-installed` now has a
+ * different fix from the others. The app renders that reason with an Install
+ * button; `stale-window` means the install has already happened and what is
+ * needed is a window reload, so the app can swap the button for a reload hint
+ * (#1409, #1413) without reading the prose.
+ *
+ * **Optional, and absent on every refusal that does not need it.** A decoder
+ * that has never seen it keeps working — which is what lets the app adopt it
+ * whenever it gets to it rather than in lockstep with this release.
+ */
+export const CAUSES = ["stale-window"];
 export const SYSTEM_DEPS = {
     findApp,
     resolveOnPath,
     probes: systemProbes,
     installedExtensions,
+    bundledBridge,
+    installBridge: (host, env) => installBridge({ env, hosts: [host] }),
     osascript: async (source, args) => {
         // `--` ends option parsing, so a prompt that begins with a dash is an
         // argument and not a flag. Every variable value travels as argv; nothing
@@ -49,6 +83,7 @@ export const SYSTEM_DEPS = {
         // never appears in `claude agents --json`. Scrubbed here at the source.
         await run("/usr/bin/open", [uri], { timeout: 30_000, env: childEnv(process.env) });
     },
+    argus: systemArgusDeps,
 };
 /**
  * The environment to hand a launched app or shell, with this session's
@@ -74,8 +109,42 @@ export function childEnv(env) {
     }
     return clean;
 }
+/**
+ * Navarch is the only host whose ids are worker uuids, and its route has
+ * already returned by the time either pid host runs — so a pick reaching them
+ * can only be a pid or `new`.
+ *
+ * A guard rather than a cast, because the day that stops being true this says
+ * so here instead of handing `undefined` to a `find` and reporting the wrong
+ * session as gone.
+ */
+function tabPick(pick) {
+    if (pick === undefined || pick.kind !== "worker")
+        return pick;
+    throw new CliError(`--session ${pick.id} is a Navarch worker id, and this route delivers by process id.`, "internal", EXIT_FAILED);
+}
+/**
+ * The mirror of {@link tabPick}: {@link sessionPick} parses a navarch `--session`
+ * as a uuid or `new` and nothing else, so a pid cannot reach that route.
+ *
+ * A guard rather than a cast for the same reason as its twin — the day the
+ * parse changes, this says so here instead of sending a process id to argusd
+ * as a worker uuid and getting `bad-worker` back about a value nobody typed.
+ */
+function workerPick(pick) {
+    if (pick === undefined || pick.kind !== "pid")
+        return pick;
+    throw new CliError(`--session ${pick.pid} is a process id, and Navarch delivers by worker uuid.`, "internal", EXIT_FAILED);
+}
 /** The reserved id. `--list` never prints it, so it can never shadow a real session. */
 export const NEW_SESSION = "new";
+/**
+ * Any C0 or C1 control character, which is what the daemon refuses `text` for
+ * (`CharacterSet.controlCharacters`) — a tab as much as a newline.
+ */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+/** A worker id as `fleet_status` spells it — canonical uuid, upper case. */
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 /**
  * `--session <id>` → a pick, or a usage error.
  *
@@ -94,13 +163,58 @@ export function sessionPick(value, host) {
     }
     if (given === NEW_SESSION)
         return { kind: "new" };
+    // **Navarch's ids are worker uuids**, so a uuid is WELL FORMED there and a
+    // pid is not. That distinction is the whole point of parsing per host: an id
+    // this verb could have printed must reach the route and be answered with a
+    // fact about the machine, and only an id it could never have printed is the
+    // caller getting the call wrong.
+    if (host === "navarch") {
+        if (!UUID.test(given)) {
+            throw usageError(`--session takes the \`id\` \`pharos delegate --list\` printed, which in ${HOSTS[host].name} is a worker `
+                + `UUID, or the reserved ${NEW_SESSION} — not ${JSON.stringify(given)}.`, { session: given, host });
+        }
+        return { kind: "worker", id: given.toUpperCase() };
+    }
     if (!/^[0-9]+$/.test(given) || !Number.isSafeInteger(Number(given)) || Number(given) <= 0) {
         throw usageError(`--session takes the \`id\` \`pharos delegate --list\` printed, which in ${HOSTS[host].name} is a process `
-            + `id, or the reserved ${NEW_SESSION} — not ${JSON.stringify(given)}. (Navarch's ids are worker UUIDs, and `
-            + "that route is not available yet.)", { session: given, host });
+            + `id, or the reserved ${NEW_SESSION} — not ${JSON.stringify(given)}. (Navarch's ids are worker UUIDs; `
+            + "pass --host navarch for those.)", { session: given, host });
     }
     return { kind: "pid", pid: Number(given) };
 }
+/**
+ * `--gh-account <login>` → the value to send, or a usage error.
+ *
+ * **A usage error and never a refusal**, the same split `--session` makes: a
+ * refusal is a fact about this machine that the app renders with a fix beside
+ * it, and "you passed an empty string" is not a fact about the machine. The
+ * one refusal this flag can produce is `gh-account-unknown`, and it comes off
+ * the socket — the daemon holds the accounts, so only the daemon can say an
+ * account is not one of them.
+ *
+ * **A login-shaped token: no whitespace.** `gh` logins have none, and neither
+ * does any spelling this CLI derives — it resolves a project folder's origin
+ * against `repos.json` and gets a login. Navarch will ALSO match a human's
+ * account *label*, and a label may well contain a space; such a label cannot
+ * be named through this flag, and the login always can. That is the trade, and
+ * it is the right way round: a value with a space in it reaching argusd would
+ * be one quoting mistake away from arriving as two.
+ */
+export function ghAccountOption(value) {
+    if (value === undefined)
+        return undefined;
+    const given = value.trim();
+    if (given === "") {
+        throw usageError("--gh-account needs a GitHub login, or the name of an account bound in Navarch ▸ Accounts. "
+            + "Leave the flag off to let the session run as whoever this machine is logged in as.");
+    }
+    if (/\s/.test(given) || CONTROL.test(given)) {
+        throw usageError(`--gh-account takes one login-shaped token and ${JSON.stringify(value)} is not one: a GitHub `
+            + "login has no spaces. (Navarch also matches an account's label, which may have one — pass "
+            + "the login instead; it always resolves.)", { ghAccount: value });
+    }
+    return given;
+}
 export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
     const host = oneOf(options.host, "--host", HOST_IDS, isHostId);
     const agent = oneOf(options.agent, "--agent", AGENT_IDS, isAgentId);
@@ -113,11 +227,35 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
         throw usageError("--list and --session are different questions: --list reports what is running and sends nothing, "
             + "--session sends to one of the ids it printed. Pass one.");
     }
+    const status = (options.status ?? "").trim();
+    const asking = options.status !== undefined;
+    if (asking && (options.list || options.session !== undefined)) {
+        throw usageError("--status asks what became of a delegation that is already in flight, so it takes neither "
+            + "--list nor --session. Pass the request id on its own.");
+    }
+    if (asking && host !== "navarch") {
+        throw usageError(`--status is a Navarch question: it is the only route that can answer \`pending\`, because it is `
+            + `the only one where a person may have to approve the hand-off first. ${HOSTS[host].name} `
+            + "answers sent or launched on the call itself.", { host });
+    }
+    if (asking && status === "") {
+        throw usageError("--status needs the `request` id the delegation answered with.");
+    }
     const pick = sessionPick(options.session, host);
+    // **Accepted everywhere, honoured only by Navarch.** It is validated for
+    // shape on every host so a typo is caught where it was typed; what happens
+    // to it after that is the route's, and for the three hosts that cannot bind
+    // an identity it is a sentence on the outcome rather than a refusal. Only
+    // Navarch STARTS a session on the caller's behalf — a Terminal window and a
+    // VS Code terminal both inherit whatever `gh` this machine is logged in as,
+    // and there is nothing this verb could do about that short of writing to
+    // somebody's keyring.
+    const ghAccount = ghAccountOption(options.ghAccount);
     // **`--list` needs no prompt**, and demanding one would make the app build a
-    // message it is only going to throw away to refresh a menu.
+    // message it is only going to throw away to refresh a menu. Nor does
+    // `--status`, which is a read about a delegation whose text was sent already.
     const text = (options.text ?? "").replace(/\r\n/g, "\n").trim();
-    if (text === "" && !options.list) {
+    if (text === "" && !options.list && !asking) {
         throw usageError("Nothing to send. Pass the prompt with --text, --file or --stdin.");
     }
     const folder = (options.folder ?? "").trim();
@@ -127,13 +265,43 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
         throw usageError(`--folder must be absolute, got ${JSON.stringify(folder)}.`, { folder });
     }
     const base = { host, agent, mode, folder };
-    const refuse = (reason, detail) => emitRefusal(io, options.pretty, { ok: false, reason, detail, ...base });
+    /**
+     * What `--gh-account` did on a host that cannot honour it: nothing, said out
+     * loud. Appended in ONE place rather than by each route, because a route
+     * that forgot it would be the silent case this sentence exists to prevent —
+     * and the app renders `detail` verbatim, so a value that travelled and did
+     * nothing has to be in it. `--list` and `--status` are not sends and do not
+     * get it; they never reach {@link succeed} with anything to say about a
+     * session this call started.
+     */
+    const accountNote = ghAccount === undefined || host === "navarch"
+        ? ""
+        : ` The GitHub account “${ghAccount}” was not applied: only Navarch starts a session on your `
+            + `behalf and can bind one to it. A ${HOSTS[host].name} session runs as whichever account `
+            + "`gh` on this machine is logged in as.";
+    const refuse = (reason, detail, extra = {}) => emitRefusal(io, options.pretty, {
+        ok: false,
+        reason,
+        ...(extra.cause === undefined ? {} : { cause: extra.cause }),
+        detail,
+        ...base,
+        ...(extra.delegation === undefined ? {} : { delegation: extra.delegation }),
+    });
     const succeed = (outcome) => emitOutcome(io, options.pretty, {
         ok: true,
         ...base,
         ...outcome,
+        detail: outcome.detail + accountNote,
         ...(options.dryRun ? { dryRun: true } : {}),
     });
+    // **`--status` asks the daemon, and nothing else.** It deliberately skips
+    // both checks below: the folder may well have been unlinked in the minutes a
+    // person spent deciding at the approval card, and Navarch itself need not be
+    // running — the row it reads is argusd's own. Refusing a status read for
+    // either would leave the one delegation that mattered permanently
+    // unobservable, which is the failure `delegate_status` exists to prevent.
+    if (asking)
+        return navarchStatus(io, env, status, base, deps, refuse, succeed);
     // Cheapest fact first: nothing else is worth asking about a folder that is
     // not there, and it is the one refusal that is entirely the caller's to fix.
     const info = await stat(folder).catch(() => null);
@@ -147,23 +315,14 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
             + "Spotlight and at the usual paths under /Applications and ~/Applications."
             + (HOSTS[host].cask === undefined ? "" : ` \`brew install --cask ${HOSTS[host].cask}\` installs it.`));
     }
-    // Navarch is refused before the agent is even resolved: it cannot take a
-    // delegation at all yet, so an `agent-not-installed` about it would name the
-    // wrong problem.
-    //
-    // **`--list` is refused here too, rather than answering with rows.** The
-    // contract gives a Navarch row the worker's UUID as its `id` and the worker's
-    // name as its `name`, and both come from `fleet_status` over the Argus socket
-    // — which is #1393's half of this. Listing the pids instead would hand the
-    // app ids that `--session` can never accept, so the whole route is one honest
-    // refusal until #1393 lifts it in one place.
+    // **Navarch takes both verbs before the agent is even resolved**, and that
+    // is not an oversight. Nothing here runs the agent: argusd spawns a worker
+    // through Navarch, from the app's own login shell and its own PATH. A
+    // `resolveOnPath` refusal would report a fact about THIS process's PATH as
+    // though it were a fact about the machine — and a GUI-launched Pharos has
+    // roughly `/usr/bin:/bin`, so it would refuse on nearly every real call.
     if (host === "navarch") {
-        return refuse("unsupported", "Navarch cannot take a delegation yet, and cannot list its sessions either. The Argus side of "
-            + "it exists — #1378 added a `delegate` op that finds-or-creates a worker on a folder without "
-            + "a board todo, which every other operator action there still needs — but this verb does not "
-            + "speak that socket yet. #1393 on the ask-agent board is the todo that teaches it, and it is "
-            + "also what supplies the worker ids `--session` would take; until it lands, choose Terminal "
-            + "or VS Code.");
+        return delegateToNavarch(io, env, agent, folder, text, base, options, workerPick(pick), ghAccount, deps, refuse, succeed);
     }
     // **May be null, and that is not always a refusal.** The Terminal route runs
     // the agent by this path, so it must exist there; the VS Code extension route
@@ -174,11 +333,11 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
         return listSessions(io, host, agent, mode, folder, agentPath, env, deps, options.pretty, refuse);
     }
     if (host === "vscode" || host === "vscode-insiders") {
-        return delegateToVsCode(host, agent, mode, folder, text, agentPath, env, deps, options.dryRun, pick, refuse, succeed);
+        return delegateToVsCode(host, agent, mode, folder, text, agentPath, env, deps, options.dryRun, tabPick(pick), refuse, succeed);
     }
     if (agentPath === null)
         return refuse("agent-not-installed", agentNotInstalled(agent, env));
-    return delegateToTerminal(agent, folder, text, agentPath, env, deps, options.dryRun, pick, refuse, succeed);
+    return delegateToTerminal(agent, folder, text, agentPath, env, deps, options.dryRun, tabPick(pick), refuse, succeed);
 }
 /**
  * `--list` — the inventory, and nothing else.
@@ -263,6 +422,442 @@ function displayName(session) {
 function nameOf(agent) {
     return agent === "claude" ? "Claude" : "Codex";
 }
+// MARK: - Navarch, over the Argus socket
+/**
+ * `--host navarch` — the send, the inventory and the dry run.
+ *
+ * All three go through one function because all three rest on the same read,
+ * and which of them needs it is the whole contract:
+ *
+ *  1. **`delegate_candidates`** — the find, asked rather than performed
+ *     (argus #1402). It answers two questions at once, and both matter here:
+ *     *who is on this folder*, as the daemon's own ranked list rather than as
+ *     this CLI's prediction of it; and *does this daemon read a target at
+ *     all*, since the op landed in the same change as `worker` and
+ *     `gh_account`. A daemon that answers `unknown-op` serves neither, and it
+ *     would IGNORE both rather than refuse them — so `--session` and
+ *     `--gh-account` are refused `argusd-outdated` there with nothing sent,
+ *     while `--list` falls back to `fleet_status` and says so in `source`.
+ *  2. …and nothing else. **A plain send asks for none of it**: one round trip,
+ *     the daemon does the find that counts, and its own answer says where the
+ *     prompt landed.
+ *
+ * A pick is deliberately **not** re-checked against that list before a real
+ * send. The daemon validates `worker` against the very predicate the list came
+ * from — one rule, three callers — and its refusal names which of six reasons
+ * it was. A second copy of the rule here could only disagree with it, and the
+ * disagreeing copy is the one nobody is looking at.
+ */
+async function delegateToNavarch(io, env, agent, folder, text, base, options, pick, ghAccount, deps, refuse, succeed) {
+    const kind = agent;
+    const argus = deps.argus(env);
+    // The daemon's own compare resolves `~`, `.`/`..` and the three symlinked
+    // prefixes macOS ships — and no others. A folder reached through a symlink
+    // somebody made would miss every worker on it, so it is canonicalised here,
+    // exactly as the Terminal route canonicalises before matching a cwd.
+    const directory = await canonicalFolder(folder);
+    /** Does this call carry a field argus #1402 added? Both are ignored by an older daemon. */
+    const aims = pick !== undefined || ghAccount !== undefined;
+    try {
+        const found = options.list || options.dryRun || aims
+            ? await navarchCandidates(argus, kind, directory)
+            : null;
+        if (found !== null && isFailure(found))
+            return refuseFailure(refuse, found);
+        const ranked = found?.workers ?? [];
+        const target = found?.target ?? null;
+        // `found!` below, three times and for one reason: `--list`, `--dry-run` and
+        // a call that `aims` are exactly the three that set it, so inside each of
+        // them the read has happened. A plain send is the only path where it is
+        // null, and it returns before any of them.
+        if (options.list)
+            return emitNavarchList(io, base, agent, found, options.pretty);
+        // **The version gate, and it is the reason a pick costs a round trip.**
+        // `delegate` ignores a key it does not know, so on a daemon that predates
+        // #1402 a `worker` is discarded and the find runs anyway — `sent`, about a
+        // pane the person did not choose — and a `gh_account` is discarded too,
+        // leaving a fresh worker running as whoever `gh` last logged in as. Both
+        // are exactly what these flags exist to prevent, and neither is visible in
+        // the reply, so the only place to catch it is here, before the send.
+        if (aims && found !== null && found.source === "fleet_status") {
+            return refuse("argusd-outdated", targetUnsupported(pick, ghAccount));
+        }
+        const oneLine = navarchText(text);
+        if (options.dryRun) {
+            const picked = pick === undefined
+                ? headOf(ranked, target)
+                : pick.kind === "new"
+                    ? null
+                    : (ranked.find((worker) => worker.id === pick.id) ?? null);
+            // The one refusal a dry run can predict exactly, and only because the
+            // gate above has already run: a named worker means `aims`, so the list
+            // in hand is `delegate_candidates`' own — the very set `delegate`
+            // validates `worker` against. A uuid missing from it is a uuid the send
+            // would refuse `worker-not-eligible`.
+            if (pick?.kind === "worker" && picked === null) {
+                return refuse("session-gone", wouldBeGone(pick.id, ranked, agent));
+            }
+            return succeed({
+                action: picked === null ? "launched" : "sent",
+                session: null,
+                sessions: rowsOf(ranked, agent, target),
+                source: found.source,
+                detail: dryRunDetail(picked, pick, ranked, agent, folder, ghAccount, found.source),
+            });
+        }
+        const reply = await askArgus(argus, delegateRequest({
+            directory,
+            kind,
+            text: oneLine,
+            ...(pick === undefined
+                ? {}
+                : { worker: pick.kind === "new" ? ARGUS_NEW_WORKER : pick.id }),
+            ...(ghAccount === undefined ? {} : { ghAccount }),
+        }), readTimeoutMs(ARGUS_WAIT_SECONDS));
+        const outcome = readDelegation(reply);
+        if (isFailure(outcome))
+            return refuseFailure(refuse, outcome);
+        return succeed({
+            action: outcome.action,
+            session: null,
+            detail: navarchDetail(outcome, agent, folder),
+            delegation: reportOf(outcome),
+        });
+    }
+    catch (error) {
+        return socketFailure(error, refuse);
+    }
+}
+/** `--status <request>` — what became of a delegation that answered `pending`. */
+async function navarchStatus(io, env, request, base, deps, refuse, succeed) {
+    void io;
+    try {
+        // **`wait` is 0 here, deliberately.** The daemon will park a status read
+        // until the action settles, and that is the right tool for a program that
+        // can afford to sit still — but this one is called by an app refreshing a
+        // row, and a call that blocks for a minute is a spinner nobody asked for.
+        // The app polls instead; argus keeps the row for an hour, which is sized
+        // for a person at lunch rather than for a park.
+        const reply = await askArgus(deps.argus(env), delegateStatusRequest(request, 0), readTimeoutMs(0));
+        const outcome = readDelegation(reply);
+        if (isFailure(outcome))
+            return refuseFailure(refuse, outcome);
+        return succeed({
+            action: outcome.action,
+            session: null,
+            detail: navarchDetail(outcome, base.agent, outcome.directory === "" ? base.folder : outcome.directory),
+            delegation: reportOf(outcome),
+        });
+    }
+    catch (error) {
+        return socketFailure(error, refuse);
+    }
+}
+/**
+ * One `delegate_candidates` read, with the fallback an un-reloaded daemon
+ * needs — or the refusal that stopped it.
+ *
+ * Three daemons answer this, and `candidatesSupport` tells them apart by the
+ * `reason` KEY rather than by prose:
+ *
+ * - **it served the read** → the rows are the daemon's own, ranked by the
+ *   daemon's own rule, and every #1402 field is honoured;
+ * - **`unknown-op`** → it serves `delegate` and predates #1402. `fleet_status`
+ *   answers on every generation of argusd, so the list is still worth having —
+ *   as this CLI's prediction, marked `fleet_status`;
+ * - **no `reason` at all** → it predates `delegate` itself, which
+ *   {@link mapRefusal} already turns into `argusd-outdated`. Listing workers a
+ *   send is about to refuse to touch would be worse than saying so.
+ *
+ * `bad-directory` and `bad-kind` are mapped like any other refusal: the read
+ * validates them exactly as `delegate` does, so an empty list stays an answer
+ * ("nothing eligible there") and a folder that is not there stays a typo.
+ */
+async function navarchCandidates(argus, kind, directory) {
+    const reply = await askArgus(argus, delegateCandidatesRequest(directory, kind), readTimeoutMs(0));
+    const support = candidatesSupport(reply);
+    if (support !== "no-op") {
+        if (!reply.ok)
+            return mapRefusal(reply);
+        const { workers, target } = parseCandidates(reply);
+        return { workers, target, source: "daemon" };
+    }
+    const fleet = await askArgus(argus, fleetStatusRequest(), readTimeoutMs(0));
+    if (!fleet.ok)
+        return mapRefusal(fleet);
+    const workers = rankWorkers(parseFleet(fleet), kind, directory);
+    return { workers, target: workers[0]?.id ?? null, source: "fleet_status" };
+}
+/**
+ * `--session` or `--gh-account` against an argusd that predates argus #1402 —
+ * the refusal, and it is `argusd-outdated` because a reload is the fix.
+ *
+ * **The danger is that it would not refuse.** `delegate` reads the keys it
+ * knows and ignores the rest, so a target it has never heard of is discarded
+ * and the find runs anyway. The caller gets `sent`, naming a worker the person
+ * did not pick — or a fresh worker running as whoever `gh` was last logged in
+ * as. Nothing in the reply distinguishes that from having been obeyed, which
+ * is why the check is here and not in a reading of the answer.
+ */
+function targetUnsupported(pick, ghAccount) {
+    const asked = [
+        pick === undefined ? "" : pick.kind === "new" ? "`--session new`" : `\`--session ${pick.id}\``,
+        ghAccount === undefined ? "" : `\`--gh-account ${ghAccount}\``,
+    ].filter((part) => part !== "");
+    return (`${asked.join(" and ")} ${asked.length > 1 ? "name things" : "names something"} the argusd running `
+        + "on this machine cannot be told. It serves the delegate verb — a plain hand-off works — but the "
+        + "target worker and the GitHub account arrived with argus #1402, and this daemon predates it: it "
+        + "does not serve `delegate_candidates` either. It would not refuse them, it would IGNORE them: do "
+        + "its own find and report `sent` about a worker you did not choose, or start one running as "
+        + "whichever account `gh` was last logged in as. So nothing was sent. Reload argusd — deliberately, "
+        + "because a reload ends every live worker session — or delegate without these flags, which works "
+        + "on the daemon you have.");
+}
+/**
+ * A `--dry-run --session <uuid>` whose worker is not on the daemon's own list.
+ *
+ * Predicted rather than performed, and exact where the list came from the
+ * daemon: `delegate_candidates` lists from the very predicate `delegate`
+ * validates `worker` against, so a uuid missing from it is a uuid the send
+ * would refuse `worker-not-eligible` — which is this verb's `session-gone`.
+ */
+function wouldBeGone(id, ranked, agent) {
+    const now = ranked.length === 0
+        ? `No ${nameOf(agent)} worker is free in Navarch on this folder`
+        : `What it would accept: ${ranked.map((worker) => `${worker.name} (${worker.id})`).join(", ")}`;
+    return (`Worker ${id} is not one argusd would deliver to on this folder — it has exited, taken a board `
+        + "mission, is an Argus Agent, or was never there. That is the daemon's own answer to its own "
+        + `find, so a real run would be refused \`session-gone\` for exactly this. ${now}. Nothing was `
+        + "sent and nothing would be started: a chosen session is a choice. Re-read the inventory with "
+        + "`pharos delegate --list --host navarch`, or pass `--session new` to start a fresh worker on "
+        + "purpose.");
+}
+/** What a dry run would do, in the dry run's own tense. */
+function dryRunDetail(picked, pick, ranked, agent, folder, ghAccount, source) {
+    const core = picked !== null
+        ? `Would ask Navarch to type the prompt into “${picked.name}” (${statusWord(picked.status)}).`
+            + (pick === undefined
+                ? source === "daemon"
+                    ? " That is the worker argusd itself names as the target for this folder."
+                    : " The find is argusd's rather than this CLI's, so this is the worker it would pick from"
+                        + " the snapshot as it stands now."
+                : " It was named with `--session`, and argusd validates that pick against the same list it"
+                    + " came from.")
+        : pick?.kind === "new"
+            ? `Would ask Navarch to start a FRESH ${nameOf(agent)} worker in ${folder}`
+                + (ranked.length === 0
+                    ? ", which is what would have happened anyway: none is free on this folder."
+                    : `, leaving the ${ranked.length === 1 ? "one" : String(ranked.length)} already there alone.`)
+            : `Would ask Navarch to start a ${nameOf(agent)} worker in ${folder} and type the prompt into `
+                + "it. No worker of that kind is free on this folder — a worker holding a board mission and "
+                + "an Argus Agent are both deliberately not candidates.";
+    // The account is only ever bound to a worker that is STARTED, so a dry run
+    // that predicts a send has to say the value would travel and do nothing —
+    // the same sentence argusd appends to the real answer.
+    const account = ghAccount === undefined
+        ? ""
+        : picked === null
+            ? ` It would run as the GitHub account “${ghAccount}”, and argusd refuses `
+                + "`gh-account-unknown` rather than substituting one if it does not know that name."
+            : ` The GitHub account “${ghAccount}” would not be applied: the prompt would land in a worker `
+                + "that is already running, and its account stands.";
+    return core + account;
+}
+/** The inventory, in the shape every host answers `--list` in. */
+function emitNavarchList(io, base, agent, found, pretty) {
+    const rows = rowsOf(found.workers, agent, found.target);
+    const agentName = nameOf(agent);
+    const head = rows.length === 0
+        ? `No ${agentName} worker is free in Navarch on ${base.folder}. A delegation would start one. `
+            + "A worker holding a board mission, and an Argus Agent, are running agents that are "
+            + "deliberately not candidates — so this can read empty with panes open on that folder."
+        : `${rows.length} ${agentName} worker${rows.length === 1 ? "" : "s"} in Navarch on ${base.folder}. `
+            + `A plain delegate would use ${(rows.find((row) => row.recommended) ?? rows[0]).name} `
+            + `(${(rows.find((row) => row.recommended) ?? rows[0]).status}).`;
+    // **Which side answered, in the list's own prose as well as in `source`.**
+    // The two lists are not the same claim: one is what argusd says it would
+    // accept, the other is what this CLI predicts it would — and on the older
+    // daemon the pick a caller makes from it cannot be honoured at all, which is
+    // the thing a person reading the list needs to know BEFORE they pick.
+    const provenance = found.source === "daemon"
+        ? " argusd answered this list itself (`delegate_candidates`), so a row here is a row it accepts:"
+            + " `--session` takes any of these ids."
+        : " This argusd predates `delegate_candidates` (argus #1402), so the list is this CLI's own"
+            + " reading of `fleet_status` and a prediction of the daemon's find. `--session` and"
+            + " `--gh-account` are refused `argusd-outdated` against it — reloading argusd is what lifts"
+            + " that, and it ends every live worker session.";
+    const detail = head + provenance;
+    // **`incomplete` is false and means it.** Every other host infers the list
+    // from `ps` and a probe that can fail; both reads here are the daemon's own
+    // register of what it is running, so a short answer is an answer and not a
+    // gap.
+    const listing = {
+        ok: true,
+        ...base,
+        sessions: rows,
+        incomplete: false,
+        source: found.source,
+        detail,
+    };
+    if (!pretty)
+        return emit(io, listing);
+    return emitText(io, [
+        detail,
+        ...rows.map((row) => `${row.recommended ? "*" : " "} ${row.id}  ${row.name} — ${row.status}, ${row.detail}`),
+    ].join("\n"));
+}
+/**
+ * The rows, with `recommended` on the one the daemon would take.
+ *
+ * `target` is read rather than assumed to be `[0]`, even though the two are
+ * the same by construction — it is the daemon's own statement of what a plain
+ * delegate takes, and `recommended` is defined as exactly that. It falls back
+ * to the head for the `fleet_status` route, where the ranking is this CLI's
+ * and there is nobody else to ask.
+ */
+function rowsOf(ranked, agent, target) {
+    const head = headOf(ranked, target);
+    return ranked.map((worker) => workerRow(worker, agent, worker === head));
+}
+/**
+ * The worker a plain delegate would take: the daemon's own `target` where
+ * there is one to read, and the head of the ranking otherwise — which is the
+ * `fleet_status` fallback, where there is nobody to ask and this CLI's own
+ * rule is all there is.
+ */
+function headOf(ranked, target) {
+    if (target !== null) {
+        const named = ranked.find((worker) => worker.id === target);
+        if (named !== undefined)
+            return named;
+    }
+    return ranked[0] ?? null;
+}
+/**
+ * One worker as a menu row.
+ *
+ * `status` is the contract's three words, and the mapping is not a translation
+ * exercise: **`needs_input` is reported `busy`**. A worker sitting on a trust
+ * dialog looks idle from every angle except the one that matters — text typed
+ * at it is swallowed by the dialog, which is the `failed` Navarch reports
+ * afterwards — so calling it idle in a menu invites the person to choose the
+ * one pane that cannot take the work. `starting` is `busy` for the same
+ * reason: there is no input box yet.
+ *
+ * `detail` stays a LOCATOR and never repeats the status word, because the app
+ * composes its second line as status + detail.
+ */
+function workerRow(worker, agent, recommended) {
+    return {
+        id: worker.id,
+        name: worker.name === "" ? `${nameOf(agent)} · ${worker.id.slice(0, 8)}` : worker.name,
+        agent,
+        host: "navarch",
+        status: statusWord(worker.status),
+        detail: worker.status === "needs_input"
+            ? "Navarch, on a prompt"
+            : worker.stage === ""
+                ? "Navarch"
+                : `Navarch · ${worker.stage}`,
+        recommended,
+    };
+}
+function statusWord(status) {
+    switch (status) {
+        case "waiting":
+        case "idle":
+            return "idle";
+        case "running":
+        case "starting":
+        case "needs_input":
+            return "busy";
+        default:
+            return "unknown";
+    }
+}
+/** Prose for a person, on top of what argus already wrote. */
+function navarchDetail(outcome, agent, folder) {
+    const said = outcome.detail.trim();
+    if (outcome.action !== "pending") {
+        return said === ""
+            ? `Navarch ${outcome.action === "launched" ? "started a worker in" : "sent the prompt to a worker in"} ${folder}.`
+            : said;
+    }
+    // The one answer the app must render as a FACT rather than as a failure: a
+    // card is up in Navarch and a person has to allow it. Nothing has gone wrong,
+    // and nothing has been delivered either.
+    const queued = said === "" ? "" : ` (${said})`;
+    return (`Navarch is asking you to approve this hand-off${queued}. Nothing has been typed yet: the first `
+        + `delegation on a machine raises a card showing the folder, the ${nameOf(agent)} worker and the `
+        + "line verbatim, and “Always allow” turns on nothing else. Approve it in Navarch, then ask again "
+        + `with \`pharos delegate --host navarch --status ${outcome.request}\`.`);
+}
+function reportOf(outcome) {
+    return {
+        request: outcome.request,
+        worker: outcome.worker,
+        name: outcome.name,
+        created: outcome.created,
+        todo: outcome.todo,
+    };
+}
+/** A refusal that came off the socket, in this verb's own shape. */
+function refuseFailure(refuse, failure) {
+    return refuse(failure.reason, failure.detail, failure.delegation === undefined ? undefined : { delegation: reportOf(failure.delegation) });
+}
+/**
+ * A socket that was not there, or a conversation that broke.
+ *
+ * The split is the CLI's ordinary one and it earns its keep here: **nothing
+ * listening is a fact about the machine with a fix on it** — open Navarch, and
+ * argusd comes with it — so it is a refusal on stdout. A park that outlived its
+ * own deadline, or a line that is not JSON, is a failure and takes stderr and
+ * exit 1. Reporting the second as the first would tell somebody to open an app
+ * that is already open.
+ */
+function socketFailure(error, refuse) {
+    if (error instanceof ArgusUnreachableError)
+        return refuseFailure(refuse, unreachable(error));
+    if (error instanceof CliError)
+        throw error;
+    throw new CliError(`The Argus socket did not answer: ${messageOf(error)}`, "internal", EXIT_FAILED, {
+        host: "navarch",
+    });
+}
+/**
+ * The prompt, held to what the wire takes: ONE line of printable characters.
+ *
+ * The daemon refuses anything else (`bad-text`) and is right to: the receiving
+ * TUI submits on Enter and Navarch owns that Enter, so a payload carrying its
+ * own control codes is a remote control rather than a message. Checked here so
+ * the refusal names the flag the caller passed rather than arriving as a wire
+ * error about a field — and **never silently flattened**, because a prompt
+ * rewritten on its way out is a prompt nobody proof-read.
+ */
+function navarchText(text) {
+    if (CONTROL.test(text)) {
+        throw usageError("Navarch takes the prompt as ONE line: the worker's TUI submits on Enter and Navarch owns that "
+            + "Enter, so a prompt carrying its own newlines or tabs would arrive as several messages, or as "
+            + "none. Fold it into one line — pharos will not do that for you, because a prompt rewritten on "
+            + "its way out is a prompt nobody proof-read. (Terminal and the VS Code hosts take several "
+            + "lines; they paste rather than type.)", { host: "navarch", lines: text.split("\n").length });
+    }
+    if (text.length > ARGUS_TEXT_LIMIT) {
+        throw usageError(`Navarch takes at most ${ARGUS_TEXT_LIMIT} characters in one line, and this prompt is `
+            + `${text.length}. Shorten it, or point the agent at the work item and let it fetch the detail `
+            + "itself — which is what the app's own prompt does.", { host: "navarch", characters: text.length, limit: ARGUS_TEXT_LIMIT });
+    }
+    return text;
+}
+/** `realpath`, falling back to the path as given when it cannot be resolved. */
+async function canonicalFolder(folder) {
+    try {
+        return await realpath(folder);
+    }
+    catch {
+        return folder;
+    }
+}
 /**
  * The `session-gone` detail: what was asked for, what is actually there, and
  * why nothing was started instead.
@@ -303,6 +898,64 @@ function agentNotInstalled(agent, env) {
         + (agent === "claude" ? "`npm i -g @anthropic-ai/claude-code`" : "`npm i -g @openai/codex`")
         + " puts it there. If it IS installed, `pharos doctor` prints the PATH that was searched.");
 }
+/**
+ * `--session` against a bridge that cannot carry one — the version gate's
+ * detail, which has three shapes because it has three different fixes.
+ *
+ * `running` is the version in place AFTER the route's own install attempt, so
+ * reaching here at all means one of three things: an upgrade was tried and
+ * failed (`upgradeFailure` says how), this pharos ships nothing to replace it
+ * with, or what it ships is no newer. Each of those is somebody doing a
+ * different thing next, which is why none of them is folded into the others.
+ */
+function sessionTooOld(name, running, shipped, upgradeFailure) {
+    const unreadable = running === null || running === "";
+    const head = `The Pharos bridge in ${name} `
+        + (unreadable
+            ? "carries no version this can read, so it cannot be shown to understand"
+            : `is ${running}, which predates`)
+        + ` \`--session\` — that arrived in ${SESSION_BRIDGE_VERSION}. It does not ignore the session in the `
+        + "URI: it refuses any query key it does not know, so the prompt would never reach the editor and "
+        + "this would have reported it as sent.";
+    const fix = upgradeFailure !== null
+        ? ` Replacing it with ${shipped ?? "the one this pharos ships"} was tried on the way here and failed: `
+            + `${upgradeFailure} \`pharos setup --install vscode-bridge\` runs the same install on its own.`
+        : shipped === null
+            ? " This pharos ships no bridge it can offer as a replacement, so updating pharos is what brings one."
+            : bridgeAtLeast(shipped, SESSION_BRIDGE_VERSION)
+                ? ` \`pharos setup --install vscode-bridge\` replaces it with the one this pharos ships (${shipped}).`
+                : ` This pharos ships ${shipped}, which is no newer, so updating pharos is what brings one.`;
+    return `${head}${fix} Delegating WITHOUT --session works with the bridge you have.`;
+}
+/**
+ * The one state installing cannot fix, because the files are only half of it.
+ *
+ * VS Code replaces an extension's files immediately; the extension host in a
+ * window that is ALREADY OPEN goes on running the code it activated with until
+ * that window reloads. For an ordinary delegation that costs nothing — the old
+ * bridge handles the URI. For `--session` against a bridge that predated
+ * {@link SESSION_BRIDGE_VERSION} it costs the prompt: that code refuses the
+ * whole URI rather than ignoring the parameter, `open` succeeds anyway, and
+ * this verb would answer `sent` about a message nobody received.
+ *
+ * So it refuses once, and only once — the reload (or the next window) is all
+ * that stands between the person and a working send. `cause` is what tells the
+ * app this `bridge-not-installed` wants a reload rather than its Install
+ * button: the install has already happened.
+ */
+function staleWindow(name, replaced, now, dryRun) {
+    const installed = now === null || now === "" ? "the bundled bridge" : now;
+    return (`${dryRun ? `Installing ${installed} into ${name} would replace` : `The Pharos bridge in ${name} was just replaced with ${installed}, over`} `
+        + `${replaced}, which predates \`--session\` (${SESSION_BRIDGE_VERSION}). A ${name} window that is `
+        + `already open still runs ${replaced} until it reloads, and ${replaced} does not ignore a session in `
+        + "the URI — it refuses the whole thing, so the prompt would be reported as sent and never arrive. "
+        + (dryRun
+            ? "A real run would install it and then refuse once, for this reason: reload that window "
+                + "(Developer: Reload Window) or open a new one first. Delegating WITHOUT --session would work "
+                + "either way."
+            : "Reload that window (Developer: Reload Window) or open a new one, then run this again. "
+                + "Delegating WITHOUT --session works either way."));
+}
 /**
  * The URI the bridge handles.
  *
@@ -335,31 +988,35 @@ async function delegateToVsCode(host, agent, mode, folder, text, agentPath, env,
     }
     const extensions = await deps.installedExtensions(host, env);
     const bridge = extensions?.find((extension) => extension.id === BRIDGE_EXTENSION_ID);
-    if (bridge === undefined) {
+    const bundled = await deps.bundledBridge(env);
+    const shipped = bundled?.manifest.version ?? null;
+    // Nothing installed and nothing to install with: the one state this route can
+    // do nothing about. A package that ships no `.vsix` is a real state — the
+    // bridge's build writes it and a checkout that has not run it has none — so
+    // it is named rather than reported as an absent extension, which would send
+    // somebody to an install that refuses for a different reason.
+    if (bridge === undefined && bundled === null) {
         const directory = extensionsDirectory(host, env) ?? "the extensions directory";
         return refuse("bridge-not-installed", `The Pharos bridge (${BRIDGE_EXTENSION_ID}) is not installed in ${name} — looked in ${directory}`
             + (extensions === null ? ", which does not exist: that VS Code has never run" : "")
-            + ". `pharos setup --install vscode-bridge` installs the one this pharos ships.");
-    }
-    // **A bridge older than `--session` does not ignore it — it refuses the whole
-    // URI.** It rejects any query key it does not know (the guard that makes a
-    // single-encoded `&` in a prompt loud instead of silently truncating one), so
-    // an unexpected `session` trips it and the prompt never reaches the editor.
-    // Nothing comes back from VS Code to say so — `open` succeeds either way — so
-    // without this check the verb answers `sent` about a message that was thrown
-    // away, and the app tells the person it was delivered. Every machine that
-    // installed the bridge before this release carries one of these.
-    //
-    // `bridge-not-installed` rather than a new reason id: the fix the app already
-    // renders for it — `pharos setup --install vscode-bridge` — is exactly the
-    // fix for this, and a reason id is a contract the app decodes.
-    if (pick !== undefined && !bridgeAtLeast(bridge.version, SESSION_BRIDGE_VERSION)) {
-        return refuse("bridge-not-installed", `The Pharos bridge installed in ${name} is ${bridge.version}, which predates \`--session\` — that `
-            + `arrived in ${SESSION_BRIDGE_VERSION}. It would not ignore the session in the URI: it refuses `
-            + "any query key it does not know, so the prompt would never reach the editor and this would have "
-            + "reported it as sent. `pharos setup --install vscode-bridge` replaces it with the one this pharos "
-            + "ships. Delegating WITHOUT --session works with the bridge you have.");
+            + `. This pharos ships no bridge to install either (${bundledVsixPath(env)} is absent), so there is `
+            + "nothing here to put in: `pnpm --filter ./packages/pharos-vscode build` writes one in a checkout, "
+            + "and a published pharos packs it.");
     }
+    // **What this pharos ships goes in, on the way.** Absent, or older than the
+    // bundled one, and the same verified installer `setup --install
+    // vscode-bridge` runs is run first — for this flavour only. That is the whole
+    // of #1394: `npm i -g` runs no installer, so before this a CLI update carried
+    // a bridge that never reached an editor.
+    //
+    // A version that cannot be compared is left alone. `shipped` is null when the
+    // package has a `.vsix` whose version could not be read at all, and replacing
+    // a working bridge on a guess is the one move that can make a machine worse.
+    const wanted = bridge === undefined
+        ? "install"
+        : shipped !== null && !bridgeAtLeast(bridge.version, shipped)
+            ? "upgrade"
+            : null;
     const claudeExt = extensions?.find((extension) => extension.id === CLAUDE_EXTENSION_ID);
     const usesExtensionBinary = mode === "extension" && agent === "claude" && claudeExt !== undefined;
     // **The extension route needs no agent on PATH.** The Claude Code extension
@@ -396,6 +1053,88 @@ async function delegateToVsCode(host, agent, mode, folder, text, agentPath, env,
             return refuse("session-gone", sessionGone(pick.pid, agent, host, ranked, sessions, incomplete, probeDetail));
         }
     }
+    // **The install happens HERE, after every refusal that is a pure fact.** An
+    // agent off PATH and a pick that has vanished would both have refused anyway,
+    // and provisioning somebody's editor on the way to a refusal is a side effect
+    // on a call that delivered nothing. Past this line the only thing left to do
+    // is open the URI.
+    //
+    // It costs a few seconds — `code --install-extension` spawns Electron — and
+    // it costs them once per CLI update per flavour, on the call that is already
+    // about that editor.
+    let running = bridge?.version ?? null;
+    /** The version this replaced, when it replaced one. Null on a fresh install. */
+    let replaced = null;
+    let leadNote = "";
+    let tailNote = "";
+    /** Why an upgrade did not happen, when one was tried. The version gate quotes it. */
+    let upgradeFailure = null;
+    if (wanted !== null) {
+        const into = `${shipped ?? "the bridge this pharos ships"} into ${name}`;
+        if (dryRun) {
+            running = shipped;
+            replaced = wanted === "upgrade" ? bridge.version : null;
+            leadNote =
+                `Would install ${into} first`
+                    + (replaced === null ? "" : `, replacing ${replaced}`)
+                    + " — the same checksum-verified `--install-extension --force` that `pharos setup --install "
+                    + "vscode-bridge` runs. ";
+        }
+        else {
+            const outcome = await deps.installBridge(host, env);
+            if (outcome.ok) {
+                running = shipped;
+                replaced = wanted === "upgrade" ? bridge.version : null;
+                leadNote = `Installed the Pharos bridge ${into} first${replaced === null ? "" : `, replacing ${replaced}`}. `;
+            }
+            else if (wanted === "install") {
+                // Nothing was there to fall back on, so this is the refusal the route
+                // had before — with what was tried, rather than with an instruction to
+                // try the same thing by hand.
+                return refuse("bridge-not-installed", `The Pharos bridge (${BRIDGE_EXTENSION_ID}) is not installed in ${name}, and installing the one `
+                    + `this pharos ships${shipped === null ? "" : ` (${shipped})`} failed. ${outcome.detail}`
+                    + (outcome.command === null ? "" : ` The command was: ${outcome.command}.`)
+                    + " `pharos setup --install vscode-bridge` runs the same install on its own.");
+            }
+            else {
+                // **A failed UPGRADE is not a refusal.** The bridge that was there is
+                // still there and still serves this delegation; refusing would take
+                // away something that worked before this release existed.
+                upgradeFailure = outcome.detail;
+                tailNote =
+                    ` This pharos ships ${shipped} and installing it over ${bridge.version} failed, so ${bridge.version} `
+                        + `handled this. ${outcome.detail}`;
+            }
+        }
+    }
+    // The version gate, now asked about the bridge that is actually in place —
+    // which after the block above may be the one just installed, or the old one
+    // an upgrade failed to replace. **A bridge older than `--session` does not
+    // ignore it: it refuses the whole URI**, because it rejects any query key it
+    // does not know (the guard that makes a single-encoded `&` in a prompt loud
+    // instead of silently truncating one). Nothing comes back from VS Code to say
+    // so — `open` succeeds either way — so without this the verb answers `sent`
+    // about a message that was thrown away and the app tells the person it
+    // arrived.
+    //
+    // `bridge-not-installed` rather than a new reason id: the fix the app already
+    // renders for it is the fix for this, and a reason id is a contract it
+    // decodes.
+    if (pick !== undefined && !bridgeAtLeast(running ?? "", SESSION_BRIDGE_VERSION)) {
+        return refuse("bridge-not-installed", sessionTooOld(name, running, shipped, upgradeFailure));
+    }
+    // …and the case installing cannot fix, because the files are only half of it.
+    if (pick !== undefined && replaced !== null && !bridgeAtLeast(replaced, SESSION_BRIDGE_VERSION)) {
+        return refuse("bridge-not-installed", staleWindow(name, replaced, running, dryRun), { cause: "stale-window" });
+    }
+    // A replacement a window may not have picked up yet is worth saying whenever
+    // it happened — but only as a note, because for a delegation that names no
+    // session the old bridge handles the URI perfectly well.
+    if (replaced !== null) {
+        tailNote +=
+            ` A ${name} window that was already open keeps ${replaced} until it reloads (Developer: Reload Window);`
+                + ` the next window gets ${running ?? "the new one"}. Either serves this delegation.`;
+    }
     const uri = delegateUri(spec.vscode.scheme, { folder, agent, mode, text, session: pick });
     const agentName = nameOf(agent);
     const claudeExtInstalled = mode === "extension" && agent === "claude" ? claudeExt !== undefined : true;
@@ -419,11 +1158,18 @@ async function delegateToVsCode(host, agent, mode, folder, text, agentPath, env,
                 + `in an integrated terminal in ${folder}.`;
     // A deliberate new session makes "a session may exist that was not seen"
     // beside the point: one was not wanted. So the two notes are exclusive.
-    const detail = pick?.kind === "new"
-        ? `${core}${asked}`
-        : session === null && incomplete
-            ? `${core} Detection was incomplete (${probeDetail ?? "a probe failed"}); a running session may exist that could not be found.`
-            : core;
+    //
+    // **What was done first leads and the caveats trail.** The app renders this
+    // sentence as-is, and "Installed the Pharos bridge 0.3.0 into VS Code
+    // Insiders first." is the fact somebody needs before the one about where the
+    // prompt went.
+    const detail = leadNote
+        + (pick?.kind === "new"
+            ? `${core}${asked}`
+            : session === null && incomplete
+                ? `${core} Detection was incomplete (${probeDetail ?? "a probe failed"}); a running session may exist that could not be found.`
+                : core)
+        + tailNote;
     if (!dryRun) {
         try {
             await deps.open(uri);