@floh-solutions/pharos-cli 0.32.0 → 0.34.0

package/dist/commands/doctor.js

@@ -3,9 +3,11 @@ 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, delegateStatusRequest, PROBE_REQUEST, readTimeoutMs, servesDelegate, systemArgusDeps, } from "../delegate/argus.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 { carriedProfiles, carriedSentence, systemProbes } from "../delegate/sessions.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";
 const run = promisify(execFile);
@@ -199,22 +201,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,
@@ -322,35 +326,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 {
@@ -359,23 +418,171 @@ 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) {
     const missing = ["ADO_ORG", "ADO_PROJECT", "ADO_PAT"].filter((name) => (env[name] ?? "") === "");
@@ -995,13 +1202,34 @@ export async function repoAccessCheck(client, bindings, configPath) {
  * not `osascript`). Extensions from the flavour's `extensions.json`, then its
  * folder names. The bridge is compared to the one this CLI ships, read from
  * `vscode/pharos-bridge.json` beside the bundled `.vsix`.
+ *
+ * ## …and which login a RUNNING host would start a session as (#1431)
+ *
+ * A VS Code started from a shell that had `CLAUDE_CONFIG_DIR` set passes it
+ * to every terminal it opens, so a Claude session started there runs as that
+ * login — an Argus agent account, on the machine it was measured on. Nothing
+ * is wrong and nothing is refused; the row's note says so, with the fix,
+ * because the alternative is finding out from a session that answers as the
+ * wrong account. Terminal is asked the same question and cannot answer it on
+ * macOS 26 — a platform binary's environment is not shown to `ps -E` — so its
+ * row says nothing rather than something unverified.
  */
 async function delegationChecks(env) {
-    const hosts = await Promise.all(["terminal", "vscode", "vscode-insiders", "navarch"].map(async (id) => ({
-        id,
-        app: await findApp(id, env),
-    })));
-    const checks = hosts.map(({ id, app }) => hostCheck(id, app));
+    const [hosts, carried] = await Promise.all([
+        Promise.all(["terminal", "vscode", "vscode-insiders", "navarch"].map(async (id) => ({
+            id,
+            app: await findApp(id, env),
+        }))),
+        // `ps -E` is the BSD spelling, and every host here is a macOS app anyway.
+        // A failed read is no note rather than a wrong one.
+        platform() === "darwin" ? carriedProfiles(systemProbes(env, null)).catch(() => []) : Promise.resolve([]),
+    ]);
+    const home = env["HOME"] ?? homedir();
+    const checks = hosts.map(({ id, app }) => {
+        const check = hostCheck(id, app);
+        const note = hostCarriedNote(carried.find((entry) => entry.host === id) ?? null, home);
+        return note === "" ? check : { ...check, note: `${check.note ?? ""}${note}` };
+    });
     const navarch = hosts.find(({ id }) => id === "navarch");
     if (navarch?.app != null)
         checks.push(await argusDelegateCheck(env));
@@ -1038,6 +1266,17 @@ async function delegationChecks(env) {
  *
  * `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);
@@ -1070,7 +1309,8 @@ async function argusDelegateCheck(env) {
         return {
             ...base,
             ok: true,
-            note: `argusd is running at ${socketPath} and serves the delegate verb.`,
+            note: `argusd is running at ${socketPath} and serves the delegate verb.`
+                + ` ${await targetSupportNote(systemArgusDeps(env))}`,
         };
     }
     return {
@@ -1083,6 +1323,54 @@ async function argusDelegateCheck(env) {
             + " 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.";
+}
+/**
+ * What a host row adds when the running host carries a non-default
+ * `CLAUDE_CONFIG_DIR`, with its leading space — or nothing.
+ *
+ * The same sentence `pharos delegate` puts in its detail, from the same
+ * function, plus the one thing only a machine-wide report can add: that the
+ * sessions ALREADY running there are found and named, so the only surprise
+ * left is the next one it starts.
+ */
+export function hostCarriedNote(carried, home) {
+    if (carried === null)
+        return "";
+    return (` Running now as pid ${carried.pid}. ${carriedSentence(carried, home)} Sessions already running there are`
+        + ` still listed by \`pharos delegate --list\`, marked \`profile ${carried.profile}\`.`);
+}
 function hostCheck(id, app) {
     const spec = HOSTS[id];
     const unlocks = {
@@ -1142,22 +1430,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`,
@@ -1188,7 +1489,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,