@floh-solutions/pharos-cli 0.31.0 → 0.32.0

package/dist/commands/delegate.js

@@ -1,11 +1,12 @@
 import { execFile } from "node:child_process";
-import { stat } from "node:fs/promises";
+import { realpath, stat } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
 import { findApp, HOSTS, HOST_IDS, AGENT_IDS, MODES, isAgentId, isHostId, isMode, } from "../delegate/hosts.js";
+import { ARGUS_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 { asTypedInput, LAUNCH_SCRIPT, launchCommand, SEND_TO_TAB_SCRIPT } from "../delegate/quote.js";
 import { findSessions, rankSessions, systemProbes, } from "../delegate/sessions.js";
-import { BRIDGE_EXTENSION_ID, CLAUDE_EXTENSION_ID, extensionsDirectory, installedExtensions, } from "../delegate/vsix.js";
+import { BRIDGE_EXTENSION_ID, bridgeAtLeast, CLAUDE_EXTENSION_ID, extensionsDirectory, 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);
@@ -22,6 +23,17 @@ export const REASONS = [
     "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-not-targetable",
+    // …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,
 ];
 export const SYSTEM_DEPS = {
     findApp,
@@ -49,6 +61,7 @@ export const SYSTEM_DEPS = {
         // never appears in `claude agents --json`. Scrubbed here at the source.
         await run("/usr/bin/open", [uri], { timeout: 30_000, env: childEnv(process.env) });
     },
+    argus: systemArgusDeps,
 };
 /**
  * The environment to hand a launched app or shell, with this session's
@@ -74,8 +87,29 @@ export function childEnv(env) {
     }
     return clean;
 }
+/**
+ * Navarch is the only host whose ids are worker uuids, and its route has
+ * already returned by the time either pid host runs — so a pick reaching them
+ * can only be a pid or `new`.
+ *
+ * A guard rather than a cast, because the day that stops being true this says
+ * so here instead of handing `undefined` to a `find` and reporting the wrong
+ * session as gone.
+ */
+function tabPick(pick) {
+    if (pick === undefined || pick.kind !== "worker")
+        return pick;
+    throw new CliError(`--session ${pick.id} is a Navarch worker id, and this route delivers by process id.`, "internal", EXIT_FAILED);
+}
 /** The reserved id. `--list` never prints it, so it can never shadow a real session. */
 export const NEW_SESSION = "new";
+/**
+ * Any C0 or C1 control character, which is what the daemon refuses `text` for
+ * (`CharacterSet.controlCharacters`) — a tab as much as a newline.
+ */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+/** A worker id as `fleet_status` spells it — canonical uuid, upper case. */
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 /**
  * `--session <id>` → a pick, or a usage error.
  *
@@ -94,10 +128,22 @@ export function sessionPick(value, host) {
     }
     if (given === NEW_SESSION)
         return { kind: "new" };
+    // **Navarch's ids are worker uuids**, so a uuid is WELL FORMED there and a
+    // pid is not. That distinction is the whole point of parsing per host: an id
+    // this verb could have printed must reach the route and be answered with a
+    // fact about the machine, and only an id it could never have printed is the
+    // caller getting the call wrong.
+    if (host === "navarch") {
+        if (!UUID.test(given)) {
+            throw usageError(`--session takes the \`id\` \`pharos delegate --list\` printed, which in ${HOSTS[host].name} is a worker `
+                + `UUID, or the reserved ${NEW_SESSION} — not ${JSON.stringify(given)}.`, { session: given, host });
+        }
+        return { kind: "worker", id: given.toUpperCase() };
+    }
     if (!/^[0-9]+$/.test(given) || !Number.isSafeInteger(Number(given)) || Number(given) <= 0) {
         throw usageError(`--session takes the \`id\` \`pharos delegate --list\` printed, which in ${HOSTS[host].name} is a process `
-            + `id, or the reserved ${NEW_SESSION} — not ${JSON.stringify(given)}. (Navarch's ids are worker UUIDs, and `
-            + "that route is not available yet.)", { session: given, host });
+            + `id, or the reserved ${NEW_SESSION} — not ${JSON.stringify(given)}. (Navarch's ids are worker UUIDs; `
+            + "pass --host navarch for those.)", { session: given, host });
     }
     return { kind: "pid", pid: Number(given) };
 }
@@ -113,11 +159,26 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
         throw usageError("--list and --session are different questions: --list reports what is running and sends nothing, "
             + "--session sends to one of the ids it printed. Pass one.");
     }
+    const status = (options.status ?? "").trim();
+    const asking = options.status !== undefined;
+    if (asking && (options.list || options.session !== undefined)) {
+        throw usageError("--status asks what became of a delegation that is already in flight, so it takes neither "
+            + "--list nor --session. Pass the request id on its own.");
+    }
+    if (asking && host !== "navarch") {
+        throw usageError(`--status is a Navarch question: it is the only route that can answer \`pending\`, because it is `
+            + `the only one where a person may have to approve the hand-off first. ${HOSTS[host].name} `
+            + "answers sent or launched on the call itself.", { host });
+    }
+    if (asking && status === "") {
+        throw usageError("--status needs the `request` id the delegation answered with.");
+    }
     const pick = sessionPick(options.session, host);
     // **`--list` needs no prompt**, and demanding one would make the app build a
-    // message it is only going to throw away to refresh a menu.
+    // message it is only going to throw away to refresh a menu. Nor does
+    // `--status`, which is a read about a delegation whose text was sent already.
     const text = (options.text ?? "").replace(/\r\n/g, "\n").trim();
-    if (text === "" && !options.list) {
+    if (text === "" && !options.list && !asking) {
         throw usageError("Nothing to send. Pass the prompt with --text, --file or --stdin.");
     }
     const folder = (options.folder ?? "").trim();
@@ -127,13 +188,27 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
         throw usageError(`--folder must be absolute, got ${JSON.stringify(folder)}.`, { folder });
     }
     const base = { host, agent, mode, folder };
-    const refuse = (reason, detail) => emitRefusal(io, options.pretty, { ok: false, reason, detail, ...base });
+    const refuse = (reason, detail, delegation) => emitRefusal(io, options.pretty, {
+        ok: false,
+        reason,
+        detail,
+        ...base,
+        ...(delegation === undefined ? {} : { delegation }),
+    });
     const succeed = (outcome) => emitOutcome(io, options.pretty, {
         ok: true,
         ...base,
         ...outcome,
         ...(options.dryRun ? { dryRun: true } : {}),
     });
+    // **`--status` asks the daemon, and nothing else.** It deliberately skips
+    // both checks below: the folder may well have been unlinked in the minutes a
+    // person spent deciding at the approval card, and Navarch itself need not be
+    // running — the row it reads is argusd's own. Refusing a status read for
+    // either would leave the one delegation that mattered permanently
+    // unobservable, which is the failure `delegate_status` exists to prevent.
+    if (asking)
+        return navarchStatus(io, env, status, base, deps, refuse, succeed);
     // Cheapest fact first: nothing else is worth asking about a folder that is
     // not there, and it is the one refusal that is entirely the caller's to fix.
     const info = await stat(folder).catch(() => null);
@@ -147,23 +222,14 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
             + "Spotlight and at the usual paths under /Applications and ~/Applications."
             + (HOSTS[host].cask === undefined ? "" : ` \`brew install --cask ${HOSTS[host].cask}\` installs it.`));
     }
-    // Navarch is refused before the agent is even resolved: it cannot take a
-    // delegation at all yet, so an `agent-not-installed` about it would name the
-    // wrong problem.
-    //
-    // **`--list` is refused here too, rather than answering with rows.** The
-    // contract gives a Navarch row the worker's UUID as its `id` and the worker's
-    // name as its `name`, and both come from `fleet_status` over the Argus socket
-    // — which is #1393's half of this. Listing the pids instead would hand the
-    // app ids that `--session` can never accept, so the whole route is one honest
-    // refusal until #1393 lifts it in one place.
+    // **Navarch takes both verbs before the agent is even resolved**, and that
+    // is not an oversight. Nothing here runs the agent: argusd spawns a worker
+    // through Navarch, from the app's own login shell and its own PATH. A
+    // `resolveOnPath` refusal would report a fact about THIS process's PATH as
+    // though it were a fact about the machine — and a GUI-launched Pharos has
+    // roughly `/usr/bin:/bin`, so it would refuse on nearly every real call.
     if (host === "navarch") {
-        return refuse("unsupported", "Navarch cannot take a delegation yet, and cannot list its sessions either. The Argus side of "
-            + "it exists — #1378 added a `delegate` op that finds-or-creates a worker on a folder without "
-            + "a board todo, which every other operator action there still needs — but this verb does not "
-            + "speak that socket yet. #1393 on the ask-agent board is the todo that teaches it, and it is "
-            + "also what supplies the worker ids `--session` would take; until it lands, choose Terminal "
-            + "or VS Code.");
+        return delegateToNavarch(io, env, agent, folder, text, base, options, pick, deps, refuse, succeed);
     }
     // **May be null, and that is not always a refusal.** The Terminal route runs
     // the agent by this path, so it must exist there; the VS Code extension route
@@ -174,11 +240,11 @@ export async function runDelegate(io, env, options, deps = SYSTEM_DEPS) {
         return listSessions(io, host, agent, mode, folder, agentPath, env, deps, options.pretty, refuse);
     }
     if (host === "vscode" || host === "vscode-insiders") {
-        return delegateToVsCode(host, agent, mode, folder, text, agentPath, env, deps, options.dryRun, pick, refuse, succeed);
+        return delegateToVsCode(host, agent, mode, folder, text, agentPath, env, deps, options.dryRun, tabPick(pick), refuse, succeed);
     }
     if (agentPath === null)
         return refuse("agent-not-installed", agentNotInstalled(agent, env));
-    return delegateToTerminal(agent, folder, text, agentPath, env, deps, options.dryRun, pick, refuse, succeed);
+    return delegateToTerminal(agent, folder, text, agentPath, env, deps, options.dryRun, tabPick(pick), refuse, succeed);
 }
 /**
  * `--list` — the inventory, and nothing else.
@@ -263,19 +329,336 @@ function displayName(session) {
 function nameOf(agent) {
     return agent === "claude" ? "Claude" : "Codex";
 }
+// MARK: - Navarch, over the Argus socket
+/**
+ * `--host navarch` — the send, the inventory and the dry run.
+ *
+ * All three go through one function because all three 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.
+ */
+async function delegateToNavarch(io, env, agent, folder, text, base, options, pick, deps, refuse, succeed) {
+    const kind = agent;
+    const argus = deps.argus(env);
+    // The daemon's own compare resolves `~`, `.`/`..` and the three symlinked
+    // prefixes macOS ships — and no others. A folder reached through a symlink
+    // somebody made would miss every worker on it, so it is canonicalised here,
+    // exactly as the Terminal route canonicalises before matching a cwd.
+    const directory = await canonicalFolder(folder);
+    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)
+            : null;
+        if (listing !== null && isFailure(listing))
+            return refuseFailure(refuse, listing);
+        const ranked = listing ?? [];
+        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);
+        }
+        const oneLine = navarchText(text);
+        const target = ranked[0] ?? null;
+        if (options.dryRun) {
+            return succeed({
+                action: target === 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.",
+            });
+        }
+        const reply = await askArgus(argus, delegateRequest({ directory, kind, text: oneLine }), readTimeoutMs(ARGUS_WAIT_SECONDS));
+        const outcome = readDelegation(reply);
+        if (isFailure(outcome))
+            return refuseFailure(refuse, outcome);
+        return succeed({
+            action: outcome.action,
+            session: null,
+            detail: navarchDetail(outcome, agent, folder),
+            delegation: reportOf(outcome),
+        });
+    }
+    catch (error) {
+        return socketFailure(error, refuse);
+    }
+}
+/** `--status <request>` — what became of a delegation that answered `pending`. */
+async function navarchStatus(io, env, request, base, deps, refuse, succeed) {
+    void io;
+    try {
+        // **`wait` is 0 here, deliberately.** The daemon will park a status read
+        // until the action settles, and that is the right tool for a program that
+        // can afford to sit still — but this one is called by an app refreshing a
+        // row, and a call that blocks for a minute is a spinner nobody asked for.
+        // The app polls instead; argus keeps the row for an hour, which is sized
+        // for a person at lunch rather than for a park.
+        const reply = await askArgus(deps.argus(env), delegateStatusRequest(request, 0), readTimeoutMs(0));
+        const outcome = readDelegation(reply);
+        if (isFailure(outcome))
+            return refuseFailure(refuse, outcome);
+        return succeed({
+            action: outcome.action,
+            session: null,
+            detail: navarchDetail(outcome, base.agent, outcome.directory === "" ? base.folder : outcome.directory),
+            delegation: reportOf(outcome),
+        });
+    }
+    catch (error) {
+        return socketFailure(error, refuse);
+    }
+}
+/**
+ * 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.
+ */
+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;
+    }
+    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) : [];
+}
+/**
+ * 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.
+ */
+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`.");
+}
+/** 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));
+    const agentName = nameOf(agent);
+    const detail = 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}).`;
+    // **`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 };
+    if (!pretty)
+        return emit(io, listing);
+    return emitText(io, [
+        detail,
+        ...rows.map((row) => `${row.recommended ? "*" : " "} ${row.id}  ${row.name} — ${row.status}, ${row.detail}`),
+    ].join("\n"));
+}
+/**
+ * One worker as a menu row.
+ *
+ * `status` is the contract's three words, and the mapping is not a translation
+ * exercise: **`needs_input` is reported `busy`**. A worker sitting on a trust
+ * dialog looks idle from every angle except the one that matters — text typed
+ * at it is swallowed by the dialog, which is the `failed` Navarch reports
+ * afterwards — so calling it idle in a menu invites the person to choose the
+ * one pane that cannot take the work. `starting` is `busy` for the same
+ * reason: there is no input box yet.
+ *
+ * `detail` stays a LOCATOR and never repeats the status word, because the app
+ * composes its second line as status + detail.
+ */
+function workerRow(worker, agent, recommended) {
+    return {
+        id: worker.id,
+        name: worker.name === "" ? `${nameOf(agent)} · ${worker.id.slice(0, 8)}` : worker.name,
+        agent,
+        host: "navarch",
+        status: statusWord(worker.status),
+        detail: worker.status === "needs_input"
+            ? "Navarch, on a prompt"
+            : worker.stage === ""
+                ? "Navarch"
+                : `Navarch · ${worker.stage}`,
+        recommended,
+    };
+}
+function statusWord(status) {
+    switch (status) {
+        case "waiting":
+        case "idle":
+            return "idle";
+        case "running":
+        case "starting":
+        case "needs_input":
+            return "busy";
+        default:
+            return "unknown";
+    }
+}
+/** Prose for a person, on top of what argus already wrote. */
+function navarchDetail(outcome, agent, folder) {
+    const said = outcome.detail.trim();
+    if (outcome.action !== "pending") {
+        return said === ""
+            ? `Navarch ${outcome.action === "launched" ? "started a worker in" : "sent the prompt to a worker in"} ${folder}.`
+            : said;
+    }
+    // The one answer the app must render as a FACT rather than as a failure: a
+    // card is up in Navarch and a person has to allow it. Nothing has gone wrong,
+    // and nothing has been delivered either.
+    const queued = said === "" ? "" : ` (${said})`;
+    return (`Navarch is asking you to approve this hand-off${queued}. Nothing has been typed yet: the first `
+        + `delegation on a machine raises a card showing the folder, the ${nameOf(agent)} worker and the `
+        + "line verbatim, and “Always allow” turns on nothing else. Approve it in Navarch, then ask again "
+        + `with \`pharos delegate --host navarch --status ${outcome.request}\`.`);
+}
+function reportOf(outcome) {
+    return {
+        request: outcome.request,
+        worker: outcome.worker,
+        name: outcome.name,
+        created: outcome.created,
+        todo: outcome.todo,
+    };
+}
+/** A refusal that came off the socket, in this verb's own shape. */
+function refuseFailure(refuse, failure) {
+    return refuse(failure.reason, failure.detail, failure.delegation === undefined ? undefined : reportOf(failure.delegation));
+}
+/**
+ * A socket that was not there, or a conversation that broke.
+ *
+ * The split is the CLI's ordinary one and it earns its keep here: **nothing
+ * listening is a fact about the machine with a fix on it** — open Navarch, and
+ * argusd comes with it — so it is a refusal on stdout. A park that outlived its
+ * own deadline, or a line that is not JSON, is a failure and takes stderr and
+ * exit 1. Reporting the second as the first would tell somebody to open an app
+ * that is already open.
+ */
+function socketFailure(error, refuse) {
+    if (error instanceof ArgusUnreachableError)
+        return refuseFailure(refuse, unreachable(error));
+    if (error instanceof CliError)
+        throw error;
+    throw new CliError(`The Argus socket did not answer: ${messageOf(error)}`, "internal", EXIT_FAILED, {
+        host: "navarch",
+    });
+}
+/**
+ * The prompt, held to what the wire takes: ONE line of printable characters.
+ *
+ * The daemon refuses anything else (`bad-text`) and is right to: the receiving
+ * TUI submits on Enter and Navarch owns that Enter, so a payload carrying its
+ * own control codes is a remote control rather than a message. Checked here so
+ * the refusal names the flag the caller passed rather than arriving as a wire
+ * error about a field — and **never silently flattened**, because a prompt
+ * rewritten on its way out is a prompt nobody proof-read.
+ */
+function navarchText(text) {
+    if (CONTROL.test(text)) {
+        throw usageError("Navarch takes the prompt as ONE line: the worker's TUI submits on Enter and Navarch owns that "
+            + "Enter, so a prompt carrying its own newlines or tabs would arrive as several messages, or as "
+            + "none. Fold it into one line — pharos will not do that for you, because a prompt rewritten on "
+            + "its way out is a prompt nobody proof-read. (Terminal and the VS Code hosts take several "
+            + "lines; they paste rather than type.)", { host: "navarch", lines: text.split("\n").length });
+    }
+    if (text.length > ARGUS_TEXT_LIMIT) {
+        throw usageError(`Navarch takes at most ${ARGUS_TEXT_LIMIT} characters in one line, and this prompt is `
+            + `${text.length}. Shorten it, or point the agent at the work item and let it fetch the detail `
+            + "itself — which is what the app's own prompt does.", { host: "navarch", characters: text.length, limit: ARGUS_TEXT_LIMIT });
+    }
+    return text;
+}
+/** `realpath`, falling back to the path as given when it cannot be resolved. */
+async function canonicalFolder(folder) {
+    try {
+        return await realpath(folder);
+    }
+    catch {
+        return folder;
+    }
+}
 /**
  * The `session-gone` detail: what was asked for, what is actually there, and
  * why nothing was started instead.
+ *
+ * **`all` is every session on the folder, not the ranked ones**, because the
+ * most useful thing this can say is often that the pid is alive somewhere
+ * else. "It is gone" and "it is running in Navarch, not in Terminal" lead to
+ * completely different next moves, and the ranked list — filtered to the
+ * requested host — cannot tell them apart.
  */
-function sessionGone(pid, agent, host, ranked, incomplete, probeDetail) {
+function sessionGone(pid, agent, host, ranked, all, incomplete, probeDetail) {
     const agentName = nameOf(agent);
+    const found = all.find((session) => session.pid === pid);
+    const what = found === undefined
+        ? `Session ${pid} is no longer a ${agentName} session on this folder — it exited, moved, or the list `
+            + "it came from is stale."
+        : found.host !== host
+            ? `Session ${pid} is running on this folder, but in `
+                + `${found.host === null ? "an application this cannot delegate to" : HOSTS[found.host].name}, not in `
+                + `${HOSTS[host].name} — ask for that host instead.`
+            : `Session ${pid} is running on this folder in ${HOSTS[host].name}, but it holds no controlling tty, `
+                + "so there is nothing to type into.";
     const now = ranked.length === 0
-        ? `No ${agentName} session is in ${HOSTS[host].name} on this folder now`
+        ? `No ${agentName} session can be delivered to in ${HOSTS[host].name} on this folder`
         : `What is there now: ${ranked.map((session) => `${displayName(session)} (pid ${session.pid})`).join(", ")}`;
-    return (`Session ${pid} is no longer a ${agentName} session in ${HOSTS[host].name} on this folder — it exited, `
-        + `moved, or the list it came from is stale. ${now}. Nothing was sent and nothing was launched: a chosen `
-        + "session is a choice, so this refuses rather than quietly starting a second one. Re-read the inventory "
-        + "with `pharos delegate --list`, or pass `--session new` to start a fresh session on purpose."
+    return (`${what} ${now}. Nothing was sent and nothing was launched: a chosen session is a choice, so this refuses `
+        + "rather than quietly starting a second one. Re-read the inventory with `pharos delegate --list`, or pass "
+        + "`--session new` to start a fresh session on purpose."
         + (incomplete
             ? ` Detection was also incomplete (${probeDetail ?? "a probe failed"}), so the session may be running and unseeable.`
             : ""));
@@ -326,6 +709,25 @@ async function delegateToVsCode(host, agent, mode, folder, text, agentPath, env,
             + (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.");
+    }
     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
@@ -359,7 +761,7 @@ async function delegateToVsCode(host, agent, mode, folder, text, agentPath, env,
     else {
         session = ranked.find((found) => found.pid === pick.pid) ?? null;
         if (session === null) {
-            return refuse("session-gone", sessionGone(pick.pid, agent, host, ranked, incomplete, probeDetail));
+            return refuse("session-gone", sessionGone(pick.pid, agent, host, ranked, sessions, incomplete, probeDetail));
         }
     }
     const uri = delegateUri(spec.vscode.scheme, { folder, agent, mode, text, session: pick });
@@ -434,7 +836,7 @@ async function delegateToTerminal(agent, folder, text, agentPath, env, deps, dry
     else {
         session = ranked.find((found) => found.pid === pick.pid) ?? null;
         if (session === null) {
-            return refuse("session-gone", sessionGone(pick.pid, agent, "terminal", ranked, incomplete, probeDetail));
+            return refuse("session-gone", sessionGone(pick.pid, agent, "terminal", ranked, sessions, incomplete, probeDetail));
         }
     }
     const agentName = nameOf(agent);