@floh-solutions/pharos-cli 0.31.1 → 0.33.0

package/dist/commands/doctor.js

@@ -3,7 +3,9 @@ import { access, constants } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { delimiter, join } from "node:path";
 import { promisify } from "node:util";
+import { MARKETPLACE_NAME, PLUGIN } from "../capabilities.js";
 import { CONVERT_RELEASE } from "../convert.js";
+import { argusSocketPath, ArgusUnreachableError, askArgus, candidatesSupport, delegateCandidatesRequest, delegateStatusRequest, PROBE_REQUEST, readTimeoutMs, servesDelegate, systemArgusDeps, } from "../delegate/argus.js";
 import { findApp, HOSTS } from "../delegate/hosts.js";
 import { BRIDGE_EXTENSION_ID, bridgeAtLeast, bundledBridge, bundledVsixPath, CLAUDE_EXTENSION_ID, CODEX_EXTENSION_ID, extensionsDirectory, installedExtensions, SESSION_BRIDGE_VERSION, } from "../delegate/vsix.js";
 import { emit, emitText } from "../output.js";
@@ -198,22 +200,24 @@ export async function runDoctor(io, env, options, pretty, version) {
                 + "`pharos setup --convert` replaces it.";
     }
     const config = configCheck(env);
-    // **Run together, reported in order.** These three are independent of each
-    // other and every one of them is slow for a different reason — `claude plugin
-    // list` shells out to another CLI, `--verify` makes two Azure DevOps calls,
-    // and `gh auth status` validates each token against github.com. Serially that
-    // is the sum; the report is assembled afterwards, so the order a reader sees
-    // is unchanged.
-    const [skill, scopes, github, delegation] = await Promise.all([
+    // **Run together, reported in order.** These four are independent of each
+    // other and every one of them is slow for a different reason — the skill rows
+    // shell out to another CLI, `--verify` makes two Azure DevOps calls, and `gh
+    // auth status` validates each token against github.com. Serially that is the
+    // sum; the report is assembled afterwards, so the order a reader sees is
+    // unchanged.
+    const [skills, scopes, github, delegation] = await Promise.all([
         // The skill is what teaches a session this tool exists. A CLI installed
         // without it is a CLI nobody reaches for, so its absence belongs in tier 0
-        // beside the things that make pharos work at all.
-        skillCheck(env),
+        // beside the things that make pharos work at all. One row per agent that is
+        // actually here — the probes above have already answered that, so this asks
+        // nothing it can read.
+        skillChecks(env, checks.find((c) => c.id === "claude"), checks.find((c) => c.id === "codex")),
         options.verify ? verifyScopes(env, config.ok) : Promise.resolve([]),
         githubChecks(env, checks.find((c) => c.id === "gh"), options.verify),
         delegationChecks(env),
     ]);
-    checks.push(skill, config, ...scopes, ...github, ...delegation);
+    checks.push(...skills, config, ...scopes, ...github, ...delegation);
     const result = {
         ok: checks.filter((c) => c.tier === 0).every((c) => c.ok),
         checks,
@@ -321,35 +325,90 @@ function installCommand(probe) {
     return probe.install.apt ?? null;
 }
 /**
- * Is the skill installed as a Claude Code plugin, and is it CURRENT?
+ * Is the skill installed for each agent on this machine, and is it CURRENT?
  *
- * Both halves matter, and the second one is the half that hides. **Publishing a
- * new version to the marketplace does not update an installed plugin** — found
- * on the author's own machine, running 1.17.0 at user scope and 1.12.0 at
- * project scope while 1.19.0 had been published. Seven versions of corrections
- * that shipped and were never read.
+ * ## One row per agent FOUND, and that is the whole shape (#1399)
  *
- * So this reports the installed version, and the reader can compare. A skill
- * silently behind is the same shape as a stale `pharos-convert`: present,
- * plausible, and answering from a world that has moved.
+ * The skill used to be one row about Claude Code, because Claude Code was the
+ * only agent that could install it. **Codex reads the same Claude-format
+ * `.claude-plugin/marketplace.json`** — it generates its own
+ * `.codex-plugin/plugin.json` scoped to `./skills/pharos` and reports
+ * `pharos@floh-skills installed, enabled 1.28.0` — so a machine can now run two
+ * agents, and one of them can be several versions behind the other or missing
+ * the skill entirely. One row cannot hold two independent answers.
+ *
+ * So: `skill` keeps its id and now means *the skill in Claude Code*, and
+ * `skill-codex` is the Codex row. **Each is emitted only when its agent is
+ * actually on PATH**, which is the same rule the `<host>-bridge` rows follow —
+ * the `claude` and `codex` rows below in tier 2 are the fact for a missing
+ * agent, and a column of red about a tool you do not use is noise.
+ *
+ * That fixes something that was wrong before it: the old row reported `ok:
+ * false` whenever `claude` was absent, and it is TIER 0, so a perfectly healthy
+ * Codex-only machine was told pharos itself was not in working order.
+ *
+ * ## The half that hides
+ *
+ * **Publishing a new version to the marketplace does not update an installed
+ * plugin** — found on the author's own machine, running 1.17.0 at user scope
+ * and 1.12.0 at project scope while 1.19.0 had been published. Seven versions
+ * of corrections that shipped and were never read. Each agent has its own
+ * update command and they are not the same, so each row names its own.
+ *
+ * There is no comparison against "the version this CLI ships", deliberately:
+ * the skill's version is a field in the marketplace manifest over in
+ * `floh-skills`, bumped by hand at release time, and the npm package does not
+ * carry it. A constant copied in here would be the `CONVERT_RELEASE` hash
+ * written by hand — a number nobody checked, confidently wrong the first time
+ * somebody forgets it. What IS measurable is the two agents against each other,
+ * and {@link markSkillDrift} says so when they disagree.
  */
-async function skillCheck(env) {
-    const base = {
-        id: "skill",
-        name: "The pharos skill",
+async function skillChecks(env, claude, codex) {
+    const wanted = [];
+    if (claude?.ok === true)
+        wanted.push(claudeSkillCheck(env));
+    if (codex?.ok === true)
+        wanted.push(codexSkillCheck(env));
+    const rows = await Promise.all(wanted);
+    markSkillDrift(rows);
+    return rows;
+}
+/** What every skill row promises, whichever agent it is about. */
+function skillBase(id, agent) {
+    return {
+        id,
+        name: `The pharos skill in ${agent}`,
         tier: 0,
-        unlocks: "Claude Code knows to reach for pharos without being told.",
-        without: "The CLI works, but no session knows it is there.",
+        unlocks: `${agent} knows to reach for pharos without being told.`,
+        without: `The CLI works, but no ${agent} session knows it is there.`,
         install: "pharos setup --install skill",
     };
+}
+/**
+ * The Claude Code row. Only reached when `claude` is on PATH.
+ *
+ * A failure here is therefore NOT "no plugin system" — that was the old
+ * meaning, and it is now the absent row. It is a `claude` that could not answer,
+ * which is a third state and is worded as one: reporting "not installed" about
+ * a question nobody managed to ask is the overclaim `gh-auth` exists to avoid.
+ */
+async function claudeSkillCheck(env) {
+    const base = skillBase("skill", "Claude Code");
     try {
         const { stdout } = await run("claude", ["plugin", "list"], { timeout: 20_000, env });
         // `pharos@floh-skills` then a Version line somewhere after it. Scoped to a
         // window rather than the whole output, so another plugin's version cannot
         // be read as this one's.
-        const at = stdout.indexOf("pharos@floh-skills");
+        const at = stdout.indexOf(PLUGIN);
         if (at === -1) {
-            return { ...base, ok: false, version: null, path: null };
+            return {
+                ...base,
+                ok: false,
+                version: null,
+                path: null,
+                note: `Claude Code is here and \`${PLUGIN}\` is not among its plugins. `
+                    + "`pharos setup --install skill` adds the marketplace and installs it.",
+            };
         }
         const version = /Version:\s*(\S+)/.exec(stdout.slice(at, at + 200))?.[1] ?? null;
         return {
@@ -358,22 +417,170 @@ async function skillCheck(env) {
             version,
             path: null,
             note: "Publishing a new skill does NOT update an installed one — "
-                + "`claude plugin update pharos@floh-skills` does, and a restart loads it.",
+                + `\`claude plugin update ${PLUGIN}\` does, and a restart loads it.`,
         };
     }
-    catch {
-        // No `claude` on PATH: codex, antigravity and a plain shell all use this
-        // CLI and have no plugin system. Not a failure, just not applicable.
+    catch (error) {
         return {
             ...base,
             ok: false,
             version: null,
             path: null,
             install: null,
-            note: "No `claude` command here, so there is no plugin system to check. If you use another "
-                + "agent, point it at the skill in the floh-skills repository.",
+            note: `\`claude plugin list\` could not be run: ${messageOf(error)}. So this is NOT known to `
+                + "be missing — the question could not be asked. A Claude Code without a plugin "
+                + "subcommand is the likely cause.",
+        };
+    }
+}
+/**
+ * The Codex row. Only reached when `codex` is on PATH.
+ *
+ * `codex plugin list --json --available --marketplace floh-skills` is the whole
+ * probe, and every part of that command line is load-bearing:
+ *
+ *   - **`--marketplace`** narrows it to ours. Without it `--available`
+ *     enumerates every remote marketplace Codex knows — 3712 entries on the
+ *     machine this was measured on. Narrowed it is nine, offline, in 0.07s.
+ *   - **`--available`** is what separates *the marketplace is configured and
+ *     pharos is not installed from it* from *there is no floh-skills
+ *     marketplace here at all*. Both are fixed by the same command, but they
+ *     are different facts and a reader deserves the true one.
+ *   - **`--json`** because the table is a table. An unknown marketplace name is
+ *     two empty arrays and exit 0, so absence never arrives as an error.
+ *
+ * The table is still read as a fallback: a Codex old enough to have `codex
+ * plugin` and not `--json` would otherwise be reported as "not installed",
+ * which is the one answer that is worse than "could not tell".
+ */
+async function codexSkillCheck(env) {
+    const base = skillBase("skill-codex", "Codex");
+    const state = await codexPluginState(env);
+    if (state.kind === "installed") {
+        return {
+            ...base,
+            ok: true,
+            version: state.version,
+            path: null,
+            note: "Publishing a new skill does NOT update an installed one, and for Codex it takes two "
+                + `commands rather than one: \`codex plugin marketplace upgrade ${MARKETPLACE_NAME}\` `
+                + `refreshes the snapshot, then \`codex plugin add ${PLUGIN}\` installs from it. `
+                + "Codex reads the same Claude-format marketplace manifest we publish for Claude Code.",
+        };
+    }
+    if (state.kind === "not-installed") {
+        return {
+            ...base,
+            ok: false,
+            version: null,
+            path: null,
+            note: `Codex has the ${MARKETPLACE_NAME} marketplace configured and has not installed `
+                + `\`${PLUGIN}\` from it`
+                + `${state.offered === null ? "" : ` — the snapshot offers ${state.offered}`}. `
+                + "`pharos setup --install skill` installs it.",
+        };
+    }
+    if (state.kind === "no-marketplace") {
+        return {
+            ...base,
+            ok: false,
+            version: null,
+            path: null,
+            note: `Codex has no ${MARKETPLACE_NAME} marketplace configured, so there is nothing to `
+                + "install the skill from yet. `pharos setup --install skill` adds it and installs.",
         };
     }
+    return {
+        ...base,
+        ok: false,
+        version: null,
+        path: null,
+        // No install command: we do not know that `pharos setup --install skill`
+        // can work here, and a button that fails is worse than no button. The
+        // likely fix is named in prose instead.
+        install: null,
+        note: `Codex is here but could not be asked: ${state.detail}. So this is NOT known to be `
+            + "missing. A Codex predating `codex plugin` is the likely cause; `npm i -g @openai/codex` "
+            + "updates it.",
+    };
+}
+async function codexPluginState(env) {
+    const args = ["plugin", "list", "--json", "--available", "--marketplace", MARKETPLACE_NAME];
+    let jsonFailure;
+    try {
+        const { stdout } = await run("codex", args, {
+            timeout: 20_000,
+            maxBuffer: 4 * 1024 * 1024,
+            env,
+        });
+        const parsed = JSON.parse(stdout);
+        const ours = (list) => (list ?? []).find((entry) => entry.pluginId === PLUGIN);
+        const installed = ours(parsed.installed);
+        if (installed !== undefined) {
+            return { kind: "installed", version: asVersion(installed.version) };
+        }
+        const available = ours(parsed.available);
+        if (available !== undefined) {
+            return { kind: "not-installed", offered: asVersion(available.version) };
+        }
+        return { kind: "no-marketplace" };
+    }
+    catch (error) {
+        jsonFailure = messageOf(error);
+    }
+    // The table. Same question, worse grammar: one row per plugin, the status
+    // column reading `installed, enabled` or `not installed`.
+    try {
+        const { stdout } = await run("codex", ["plugin", "list", "--marketplace", MARKETPLACE_NAME], {
+            timeout: 20_000,
+            maxBuffer: 4 * 1024 * 1024,
+            env,
+        });
+        const line = stdout.split("\n").find((row) => row.trimStart().startsWith(PLUGIN));
+        if (line === undefined)
+            return { kind: "no-marketplace" };
+        // Read only what follows the id, so a marketplace or path containing the
+        // word cannot be mistaken for the status.
+        const rest = line.slice(line.indexOf(PLUGIN) + PLUGIN.length);
+        if (/\bnot installed\b/.test(rest))
+            return { kind: "not-installed", offered: null };
+        if (/\binstalled\b/.test(rest)) {
+            return { kind: "installed", version: /(\d+\.\d+\.\d+[\w.+-]*)/.exec(rest)?.[1] ?? null };
+        }
+        return { kind: "unasked", detail: `\`codex plugin list\` printed a row this cannot read` };
+    }
+    catch (error) {
+        return { kind: "unasked", detail: `${jsonFailure}; and without --json: ${messageOf(error)}` };
+    }
+}
+function asVersion(value) {
+    return typeof value === "string" && value !== "" ? value : null;
+}
+/**
+ * Two agents, one skill, two different versions — say so on both rows.
+ *
+ * This is the comparison that is actually available here (see
+ * {@link skillChecks}), and it is the origin bug wearing the other hat: the
+ * operator's machine ran Claude Code on 1.27.0 while Codex, installed by hand
+ * minutes earlier, was on 1.28.0. Nothing anywhere reported it, and each row on
+ * its own looks entirely healthy.
+ *
+ * Exported because it is the assertable half: arranging two agents at two
+ * versions on a real machine is not something a test may do.
+ */
+export function markSkillDrift(rows) {
+    const installed = rows.filter((row) => row.ok && row.version !== null);
+    if (installed.length < 2)
+        return;
+    const versions = new Set(installed.map((row) => row.version));
+    if (versions.size < 2)
+        return;
+    const inventory = installed.map((row) => `${row.name} has ${row.version}`).join(", ");
+    for (const row of installed) {
+        row.note = `${row.note ?? ""} One skill, two versions on this machine: ${inventory}. `
+            + "Update the older one — the two agents install from the same marketplace and there is "
+            + "no reason for them to disagree.";
+    }
 }
 /** Configuration, read from the environment — no network unless asked. */
 function configCheck(env) {
@@ -1001,6 +1208,9 @@ async function delegationChecks(env) {
         app: await findApp(id, env),
     })));
     const checks = hosts.map(({ id, app }) => hostCheck(id, app));
+    const navarch = hosts.find(({ id }) => id === "navarch");
+    if (navarch?.app != null)
+        checks.push(await argusDelegateCheck(env));
     const bundled = await bundledBridge(env);
     for (const { id, app } of hosts) {
         if (app === null || (id !== "vscode" && id !== "vscode-insiders"))
@@ -1009,13 +1219,128 @@ async function delegationChecks(env) {
     }
     return checks;
 }
+/**
+ * Does the argusd **running right now** serve `delegate`?
+ *
+ * The one fact about this route that nothing else on this machine reports, and
+ * the one a person otherwise learns from their first failed hand-off. It is a
+ * separate row rather than a footnote on `navarch` because the two answer
+ * different questions: that row is "is the app installed", read off the disk,
+ * and **argusd outlives the app** — that is the feature that keeps worker
+ * sessions alive across a restart, and it is exactly why master, the installed
+ * app and the running daemon drift apart. A machine can have Navarch 1.2 in
+ * `/Applications` and a daemon from last week holding the socket.
+ *
+ * **Emitted only when Navarch is installed.** On a machine without it the
+ * answer is always no and the `navarch` row already says why; a second
+ * permanently-red row is the kind nobody reads.
+ *
+ * The probe is a `delegate_status` read about an all-zero id. That op is a pure
+ * read of the daemon's own table — not gated, not rate-limited, and about an id
+ * only it mints — so asking about one that cannot exist costs a round trip and
+ * changes nothing. A current daemon answers `unknown-request`; one that
+ * predates the verb answers `unknown op` with no `reason` key at all, which is
+ * the same tell `delegate` itself uses.
+ *
+ * `install` is null on purpose: the fix is a reload, and a reload ends every
+ * live worker session. That is a person's to time, never a button.
+ *
+ * **A daemon that serves the verb is then asked a second question**, because
+ * there are two generations of "current" and they behave differently (#1412).
+ * argus #1402 added a target worker, a GitHub account and the
+ * `delegate_candidates` read in one change, so one probe answers for all
+ * three — and the gap matters more than a version gap usually does: `delegate`
+ * IGNORES a key it does not know, so on the older daemon `--session` would be
+ * discarded and the prompt typed into whichever worker the find liked. The CLI
+ * refuses rather than let that happen, and this row is where somebody finds
+ * out before they hit it. It stays `ok: true`: the verb works, and a red row
+ * for a feature the machine has never used is a red row nobody reads.
+ */
+async function argusDelegateCheck(env) {
+    const socketPath = argusSocketPath(env);
+    const base = {
+        id: "argus-delegate",
+        name: "Argus delegation (argusd)",
+        tier: 2,
+        unlocks: "`pharos delegate --host navarch` — handing a work item to a worker in Navarch, and `--list`"
+            + " of the workers on a folder.",
+        without: "That host is refused by name; Terminal and the VS Code hosts still work.",
+        version: null,
+        path: socketPath,
+        install: null,
+    };
+    let reply;
+    try {
+        reply = await askArgus(systemArgusDeps(env), delegateStatusRequest(PROBE_REQUEST, 0), readTimeoutMs(0));
+    }
+    catch (error) {
+        return {
+            ...base,
+            ok: false,
+            note: error instanceof ArgusUnreachableError
+                ? `Nothing is listening on ${socketPath} (${error.code}). argusd holds a Navarch worker's`
+                    + " terminal, and opening Navarch starts it."
+                : `The socket at ${socketPath} did not answer: ${error instanceof Error ? error.message : String(error)}.`,
+        };
+    }
+    if (servesDelegate(reply)) {
+        return {
+            ...base,
+            ok: true,
+            note: `argusd is running at ${socketPath} and serves the delegate verb.`
+                + ` ${await targetSupportNote(systemArgusDeps(env))}`,
+        };
+    }
+    return {
+        ...base,
+        ok: false,
+        note: "argusd is running and PREDATES the delegate verb, so a delegation to Navarch is refused"
+            + " (argusd-outdated) however new the app is. Reload the daemon — deliberately, because a reload"
+            + " ends every live worker session, so it is yours to time. Note that its own refusal may instead"
+            + " say the request is missing a board todo; it is not, and that message is the old daemon"
+            + " forwarding a verb it does not itself know.",
+    };
+}
+/**
+ * Does this daemon read a target worker and a GitHub account? — one sentence
+ * for the `argus-delegate` row.
+ *
+ * The probe is `delegate_candidates` with **no `directory`**, which is the
+ * cheapest form of the question: a daemon that serves the op refuses
+ * `bad-directory` (it validates exactly as `delegate` does), and one that does
+ * not answers `unknown-op`. Either way nothing is read, nothing is written,
+ * and no folder has to exist for the question to be askable — which matters,
+ * because `doctor` is asked on machines with no project linked at all.
+ *
+ * A socket that breaks between the two reads says so rather than guessing: the
+ * row above it has already reported the daemon is up, so silence here would
+ * read as an answer.
+ */
+export async function targetSupportNote(argus) {
+    let reply;
+    try {
+        reply = await askArgus(argus, delegateCandidatesRequest("", "claude"), readTimeoutMs(0));
+    }
+    catch (error) {
+        return "Whether it also serves `delegate_candidates` and `gh_account` could not be read: "
+            + `${error instanceof Error ? error.message : String(error)}.`;
+    }
+    return candidatesSupport(reply) === "no-op"
+        ? "It PREDATES `delegate_candidates` and `gh_account` (argus #1402), so `--list --host navarch`"
+            + " falls back to reading `fleet_status` itself, and `--session` and `--gh-account` are refused"
+            + " `argusd-outdated` there — this daemon would ignore both rather than refuse them, and type"
+            + " the prompt into whichever worker its own find picked. Reloading argusd lifts that, and"
+            + " ends every live worker session."
+        : "It also serves `delegate_candidates` and `gh_account` (argus #1402), so `--list --host navarch`"
+            + " is the daemon's own answer to its own find, and `--session` and `--gh-account` are honoured.";
+}
 function hostCheck(id, app) {
     const spec = HOSTS[id];
     const unlocks = {
         terminal: "`pharos delegate --host terminal` — typed into the Terminal tab that already runs the agent, or a new window.",
         vscode: "`pharos delegate --host vscode` — through the Pharos bridge, into the session in VS Code.",
         "vscode-insiders": "`pharos delegate --host vscode-insiders` — the same, in VS Code Insiders.",
-        navarch: "`pharos delegate --host navarch` — a worker in the Argus app, once #1393 lands.",
+        navarch: "`pharos delegate --host navarch` — a worker in the Argus app, over argusd's own socket.",
     };
     // Only the VS Code flavours have an install line. Terminal ships with macOS
     // and Navarch is distributed by hand, so a command would be a guess.
@@ -1036,7 +1361,12 @@ function hostCheck(id, app) {
                 ? `Not found by bundle id ${spec.bundleId} — asked Spotlight, then looked at ${spec.candidates.join(" and ")}.`
                 : `Found by ${app.via === "spotlight" ? "Spotlight" : "its well-known path"} (bundle id ${spec.bundleId}).`
                     + (id === "navarch"
-                        ? " The argus-side `delegate` op it needs exists (#1378); this CLI does not speak that socket yet (#1393), so `pharos delegate --host navarch` still answers unsupported — for `--list` too."
+                        ? " Delegating there goes over argusd's board socket rather than through the app:"
+                            + " the daemon finds a worker on the folder and Navarch types into it."
+                            + " **argusd outlives Navarch**, so this row saying the app is installed does not mean"
+                            + " the running daemon serves the verb — an argusd started before it answers"
+                            + " `argusd-outdated`, and the fix is a reload, which ends every live worker session"
+                            + " and is yours to time."
                         : ""),
     };
 }
@@ -1063,22 +1393,35 @@ async function extensionChecks(host, env, shippedBridge) {
      * the one this pharos ships stays `ok:true` with a note, because `ok:false`
      * should mean "something you asked for does not work" rather than "there is a
      * newer one" — otherwise every future bump nags on every machine.
+     *
+     * **This row reports; it no longer has to be acted on to be fixed.** Since
+     * #1394 `pharos delegate --host <flavour>` installs or upgrades the bridge on
+     * its way to opening a URI, so an absent or older one is put right by the
+     * first delegation. `pharos setup --install vscode-bridge` stays the way to
+     * do it ahead of time — and the note says so, because a row that names no fix
+     * reads as a row nobody can act on.
      */
     const bridgeStale = bridge !== undefined && !bridgeAtLeast(bridge.version, SESSION_BRIDGE_VERSION);
+    /** What now fixes an absent or outdated bridge, in both the words a person needs. */
+    const onTheWay = `\`pharos delegate --host ${host}\` installs it on its way to the editor, and `
+        + "`pharos setup --install vscode-bridge` does it ahead of time.";
     const bridgeNote = bridge === undefined
         ? shippedBridge === null
             ? `${where} This pharos ships no bridge either (${bundledVsixPath(env)} is absent) — the ship todo packs it; until then \`--install vscode-bridge\` refuses by name.`
-            : `${where} This pharos ships ${shippedBridge}.`
+            : `${where} This pharos ships ${shippedBridge}. ${onTheWay}`
         : bridgeStale
             ? `${where} Installed ${bridge.version}, which predates \`pharos delegate --session\` (${SESSION_BRIDGE_VERSION}). `
                 + "It does not ignore the session — it refuses the whole URI, because it rejects any query key it does "
                 + `not know — so picking a session in ${flavour} sends nothing. Delegating without --session still works. `
-                + `\`pharos setup --install vscode-bridge\` replaces it${shippedBridge === null ? "" : ` with ${shippedBridge}`}.`
+                + (shippedBridge === null || !bridgeAtLeast(shippedBridge, SESSION_BRIDGE_VERSION)
+                    ? `\`pharos setup --install vscode-bridge\` replaces it${shippedBridge === null ? "" : ` with ${shippedBridge}`}.`
+                    : `${onTheWay} A ${flavour} window that was already open keeps ${bridge.version} until it reloads, `
+                        + "so the first --session delegation after the replacement is refused once and says so.")
             : shippedBridge === null
                 ? `${where} Installed ${bridge.version}; this pharos ships no bridge to compare it with.`
                 : bridge.version === shippedBridge
                     ? `${where} Installed ${bridge.version}, which is the one this pharos ships.`
-                    : `${where} Installed ${bridge.version}, but this pharos ships ${shippedBridge}. It serves every verb this pharos has; the URI contract may still have moved. \`pharos setup --install vscode-bridge\` replaces it.`;
+                    : `${where} Installed ${bridge.version}, but this pharos ships ${shippedBridge}. It serves every verb this pharos has; the URI contract may still have moved. ${onTheWay}`;
     return [
         {
             id: `${host}-claude-ext`,
@@ -1109,7 +1452,7 @@ async function extensionChecks(host, env, shippedBridge) {
             name: `Pharos bridge in ${flavour}`,
             tier: 2,
             unlocks: `\`pharos delegate --host ${host}\` at all: the bridge is what puts the prompt into a session inside ${flavour}. Nothing else can. From ${SESSION_BRIDGE_VERSION} it also honours \`--session\`, which is how a person picks between two sessions on one folder.`,
-            without: `Delegating to ${flavour} is refused by name (bridge-not-installed) — and so is \`--session\` against a bridge older than ${SESSION_BRIDGE_VERSION}, which would otherwise report a prompt as sent while refusing the URI.`,
+            without: `Delegating to ${flavour} installs the bridge this pharos ships first, and is refused by name (bridge-not-installed) only when that install fails or there is none to install. \`--session\` against a bridge older than ${SESSION_BRIDGE_VERSION} is refused ONCE even after it is replaced — a window already open keeps the old one, and the old one refuses the whole URI rather than ignoring the session, which would otherwise report a prompt as sent.`,
             ok: bridge !== undefined && !bridgeStale,
             version: bridge?.version ?? null,
             path: bridge?.path ?? null,