@floh-solutions/pharos-cli 0.32.0 → 0.33.0

package/dist/commands/delegate.js

@@ -3,10 +3,10 @@ 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_REASONS, ARGUS_TEXT_LIMIT, ARGUS_WAIT_SECONDS, ArgusUnreachableError, askArgus, delegateRequest, delegateStatusRequest, fleetStatusRequest, isFailure, parseFleet, PROBE_REQUEST, rankWorkers, readDelegation, readTimeoutMs, servesDelegate, systemArgusDeps, unreachable, } from "../delegate/argus.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);
@@ -21,25 +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-gone",
     /**
-     * `--session` named a Navarch worker that is not the one the daemon's own
-     * find would pick, or asked for a new one — neither of which the `delegate`
-     * op can express: it takes no target worker (argus #1402). The id is real
-     * and the session is alive, which is why this is not `session-gone`.
+     * `--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-not-targetable",
+    "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
@@ -101,6 +123,19 @@ function tabPick(pick) {
         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";
 /**
@@ -147,6 +182,39 @@ export function sessionPick(value, 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);
@@ -174,6 +242,15 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
         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. Nor does
     // `--status`, which is a read about a delegation whose text was sent already.
@@ -188,17 +265,33 @@ 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, delegation) => emitRefusal(io, options.pretty, {
+    /**
+     * 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,
-        ...(delegation === undefined ? {} : { delegation }),
+        ...(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
@@ -229,7 +322,7 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
     // 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 delegateToNavarch(io, env, agent, folder, text, base, options, pick, deps, refuse, succeed);
+        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
@@ -333,23 +426,29 @@ function nameOf(agent) {
 /**
  * `--host navarch` — the send, the inventory and the dry run.
  *
- * All three go through one function because all three need the same two facts,
- * and the order they are established in is the whole contract:
- *
- *  1. **Does this argusd serve the verb?** `fleet_status` answers on every
- *     generation of the daemon — measured against one built from the commit
- *     before `delegate` — so a `--list` that skipped this would happily
- *     enumerate workers that a send is about to refuse to touch. The probe is a
- *     `delegate_status` read about an id that cannot exist: free, ungated,
- *     side-effect-free. See {@link PROBE_REQUEST}.
- *  2. **Who is on the folder**, which is a PREDICTION and never the find
- *     itself. The daemon does the find that counts, against a snapshot that may
- *     have moved since this read.
- *
- * A plain send needs neither and asks for neither: one round trip, and the
- * daemon's own answer says where it landed.
+ * 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, deps, refuse, succeed) {
+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
@@ -357,39 +456,64 @@ async function delegateToNavarch(io, env, agent, folder, text, base, options, pi
     // 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 {
-        // `--session new`, and any pick that is not the worker the daemon would
-        // choose, are refused BEFORE anything is sent — see {@link notTargetable}.
-        const listing = options.list || options.dryRun || pick !== undefined
-            ? await navarchFleet(argus, kind, directory)
+        const found = options.list || options.dryRun || aims
+            ? await navarchCandidates(argus, kind, directory)
             : null;
-        if (listing !== null && isFailure(listing))
-            return refuseFailure(refuse, listing);
-        const ranked = listing ?? [];
+        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, ranked, options.pretty);
-        if (pick !== undefined) {
-            const gap = notTargetable(pick, ranked, agent);
-            if (gap !== null)
-                return refuse("session-not-targetable", gap);
+            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);
-        const target = ranked[0] ?? null;
         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: target === null ? "launched" : "sent",
+                action: picked === null ? "launched" : "sent",
                 session: null,
-                sessions: ranked.map((worker, index) => workerRow(worker, agent, index === 0)),
-                detail: target === null
-                    ? `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."
-                    : `Would ask Navarch to type the prompt into “${target.name}” (${statusWord(target.status)}). `
-                        + "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.",
+                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 }), readTimeoutMs(ARGUS_WAIT_SECONDS));
+        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);
@@ -430,75 +554,151 @@ async function navarchStatus(io, env, request, base, deps, refuse, succeed) {
     }
 }
 /**
- * The probe, then the fleet, then the find — ranked the way the daemon ranks
- * it. The candidates on that folder with `[0]` first, or the refusal that
- * stopped it.
+ * 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 navarchFleet(argus, kind, directory) {
-    const probe = await askArgus(argus, delegateStatusRequest(PROBE_REQUEST, 0), readTimeoutMs(0));
-    if (!servesDelegate(probe)) {
-        // `servesDelegate` is false only for a refusal, and a refusal with no
-        // `reason` is a pre-delegate daemon whatever its prose says — which
-        // `readDelegation` has already turned into `argusd-outdated`.
-        const failure = readDelegation(probe);
-        if (isFailure(failure))
-            return failure;
+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) {
-        const failure = readDelegation(fleet);
-        if (isFailure(failure))
-            return failure;
-    }
-    return fleet.ok ? rankWorkers(parseFleet(fleet), kind, directory) : [];
+    if (!fleet.ok)
+        return mapRefusal(fleet);
+    const workers = rankWorkers(parseFleet(fleet), kind, directory);
+    return { workers, target: workers[0]?.id ?? null, source: "fleet_status" };
 }
 /**
- * Why `--session` cannot be honoured here yet, or null when it can.
- *
- * **The `delegate` op takes no target worker.** The find lives entirely in the
- * daemon (`BoardStore.delegateTarget`) and Navarch types into whatever it
- * named, so the only pick this CLI can promise is the one the daemon would
- * have made anyway — verified against an isolated daemon, where two eligible
- * workers on one folder always drew the lower uuid. Answering `sent` about any
- * other is answering about a pane the person did not choose, which is the one
- * failure this verb is built around not producing.
- *
- * It is NOT `session-gone`: that id is a real, live worker, and telling
- * somebody their session had died would send them looking for a corpse. argus
- * #1402 adds the target field; when it lands this refusal goes and nothing
- * else here changes.
+ * `--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 notTargetable(pick, ranked, agent) {
-    const head = ranked[0] ?? null;
-    if (pick.kind === "worker" && head !== null && head.id === pick.id)
-        return null;
-    const what = pick.kind === "new"
-        ? "Starting a fresh worker beside the ones already on this folder"
-        : `Delivering to worker ${pick.kind === "worker" ? pick.id : ""}`;
-    const instead = head === null
-        ? `there is no ${nameOf(agent)} worker free on this folder, so a delegation starts one — which is `
-            + "what `--session new` asks for, and already what would happen without it"
-        : `a delegation on this folder goes to “${head.name}” (${head.id}), because argusd does the find `
-            + "itself and this verb cannot override it";
-    return (`${what} is not something the Argus \`delegate\` op can express yet: it takes a folder and a kind, `
-        + `never a worker. Right now ${instead}. Nothing was sent. Board todo #1402 in the argus repo adds `
-        + "the target field; until it lands, delegate without `--session` to use the worker `--list` marks "
-        + "`recommended`.");
+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, ranked, pretty) {
-    const rows = ranked.map((worker, index) => workerRow(worker, agent, index === 0));
+function emitNavarchList(io, base, agent, found, pretty) {
+    const rows = rowsOf(found.workers, agent, found.target);
     const agentName = nameOf(agent);
-    const detail = rows.length === 0
+    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[0].name} (${rows[0].status}).`;
+            + `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; this one is 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, detail };
+    // 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, [
@@ -506,6 +706,33 @@ function emitNavarchList(io, base, agent, ranked, pretty) {
         ...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.
  *
@@ -576,7 +803,7 @@ function reportOf(outcome) {
 }
 /** 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 : reportOf(failure.delegation));
+    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.
@@ -671,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.
  *
@@ -703,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
@@ -764,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;
@@ -787,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);