@floh-solutions/pharos-cli 0.31.1 → 0.33.0

package/dist/delegate/argus.js

@@ -0,0 +1,709 @@
+import { connect } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * The Argus board socket — the route to a coding agent running in Navarch.
+ *
+ * ## Why there is a fourth route at all
+ *
+ * Terminal takes an Apple Event and VS Code takes a URI, because in both the
+ * thing that owns the terminal is the application. Navarch owns neither: a
+ * worker's PTY belongs to `argusd`, a daemon that outlives the app, and the
+ * app is what watches a screen settle before typing into it. So the delegation
+ * goes over `argusd`'s own socket as one verb — `delegate` — and the two
+ * halves split where the knowledge is: the daemon validates and does the find,
+ * the app starts a worker if there is none, waits for a screen that can take
+ * text, types, and reports back.
+ *
+ * The contract is `docs/delegation-plan.md` in the argus repo (board #1378).
+ * Everything below was measured against an isolated `argusd` built from argus
+ * master `2aaefd3` on 2026-09-11; the fixtures in `test/argus.test.ts` are that
+ * daemon's replies verbatim.
+ *
+ * ## Spoken directly, not through `argus-board`
+ *
+ * `~/.config/argus/bin/argus-board` frames exactly this — one newline-
+ * terminated JSON object in, one line back — and shelling out to it would have
+ * been half the code. It is wrong here for one measured reason: **that script
+ * stamps the CALLER'S identity onto every request**, from the environment.
+ * `_agent` from `$ARGUS_AGENT`, `_worker` from `$ARGUS_WORKER`, plus `_sub`,
+ * `_persona` and `_mission`. A `pharos delegate` run inside an Argus worker —
+ * which is precisely where Pharos.app's Ask Agent runs it — would therefore
+ * raise an approval card naming that worker, and file the ledger entry and the
+ * outcome note under it. The card is the whole point of the dial: it has to
+ * read *Pharos wants to hand work to a claude worker in …*, which is a
+ * question a person can answer.
+ *
+ * Speaking the socket means exactly the keys below travel, and nothing this
+ * process happens to have been started with. It also lets a park hold for the
+ * daemon's full wait (the script's own deadline is `wait + 5`, tuned for the
+ * board's reads) and keeps a transport failure distinguishable from a refusal,
+ * which a script that prints one line for both cannot be.
+ *
+ * ## `ARGUS_BOARD_SOCK` is honoured
+ *
+ * The same variable `argus-board` reads. It is how an isolated daemon is
+ * reached, and a session pointed at one should not have this verb quietly
+ * talking to the live fleet instead.
+ */
+/** Where `argusd` binds its board socket, unless the environment says otherwise. */
+export function argusSocketPath(env = process.env) {
+    const override = (env["ARGUS_BOARD_SOCK"] ?? "").trim();
+    if (override !== "")
+        return override;
+    return join(env["HOME"] ?? homedir(), ".config", "argus", "argus-board.sock");
+}
+/** The one-line limit the daemon holds `text` to (`BoardStore.sendTextLimit`). */
+export const ARGUS_TEXT_LIMIT = 4000;
+/**
+ * How long to ask the daemon to park, in seconds.
+ *
+ * **60, always, and never the default 10.** Two measured reasons. A delegation
+ * onto an empty folder has to start a worker and wait out a cold agent's first
+ * screen — `FleetControl.delegateSpawnWindow` is 45s — so a ten-second answer
+ * is `pending` with the real outcome landing half a minute later in a reply
+ * nobody is reading. And on the default autonomy dial the first hand-off on a
+ * machine raises an approval card, which answers `pending` the instant it goes
+ * up whatever the wait is; the wait is what catches the person who clicks
+ * *Allow* straight away, and ten seconds does not.
+ *
+ * 60 is also the daemon's ceiling (`maxFleetWait`), so this is "as long as it
+ * will hold", not a number picked here.
+ */
+export const ARGUS_WAIT_SECONDS = 60;
+/** What the request is stamped with. The card names this; an anonymous one reads "A program outside the fleet". */
+export const ARGUS_AGENT = "Pharos";
+/**
+ * Decode one line. Anything that is not a JSON object with a boolean-ish `ok`
+ * is a transport fault rather than an answer, and is reported as one.
+ */
+export function parseArgusReply(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return null;
+    const row = parsed;
+    if (row["ok"] === true) {
+        const data = row["data"];
+        return { ok: true, data: isRecord(data) ? data : {} };
+    }
+    if (row["ok"] === false) {
+        return {
+            ok: false,
+            reason: typeof row["reason"] === "string" ? row["reason"] : null,
+            error: typeof row["error"] === "string" ? row["error"] : "",
+            data: isRecord(row["data"]) ? row["data"] : null,
+        };
+    }
+    return null;
+}
+/**
+ * The socket was there and the conversation still failed — a park that outlived
+ * its own deadline, a daemon that closed mid-answer, a line that is not JSON.
+ *
+ * Separate from a refusal on purpose: a refusal is a fact about this machine
+ * with a fix on it, and this is the CLI's ordinary failure.
+ */
+export class ArgusTransportError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "ArgusTransportError";
+        this.code = code;
+    }
+}
+/** Nothing is listening: the socket file is absent, or the connect was refused. */
+export class ArgusUnreachableError extends Error {
+    code;
+    socketPath;
+    constructor(message, code, socketPath) {
+        super(message);
+        this.name = "ArgusUnreachableError";
+        this.code = code;
+        this.socketPath = socketPath;
+    }
+}
+/**
+ * A connect that was REFUSED is retried; one that answered is not.
+ *
+ * `ECONNREFUSED` on a unix socket does not mean "nothing is listening". A
+ * socket whose accept backlog is full refuses with the same errno, and argus
+ * measured 48 of 64 concurrent connects refused by a daemon that was running
+ * and answered normally seconds later (`argus-board`, #742). So a refusal is
+ * worth one more try — and it is the one failure that is safe to repeat for a
+ * WRITE, because a connect that was never accepted sent no bytes and there is
+ * nothing to duplicate.
+ */
+const CONNECT_ATTEMPTS = 3;
+const CONNECT_BACKOFF_MS = 120;
+export function systemArgusDeps(env = process.env) {
+    const socketPath = argusSocketPath(env);
+    return {
+        ask: async (request, timeoutMs) => {
+            let last = null;
+            for (let attempt = 0; attempt < CONNECT_ATTEMPTS; attempt += 1) {
+                try {
+                    return await askOnce(socketPath, request, timeoutMs);
+                }
+                catch (error) {
+                    if (!(error instanceof ArgusUnreachableError) || error.code !== "ECONNREFUSED")
+                        throw error;
+                    last = error;
+                    await pause(CONNECT_BACKOFF_MS * (attempt + 1));
+                }
+            }
+            throw last ?? new ArgusUnreachableError("the Argus socket refused every attempt", "ECONNREFUSED", socketPath);
+        },
+    };
+}
+function pause(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms).unref?.();
+    });
+}
+function askOnce(socketPath, request, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({ path: socketPath });
+        let buffer = "";
+        let settled = false;
+        const done = (error, line) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            if (error !== null)
+                reject(error);
+            else
+                resolve(line);
+        };
+        // An IDLE timeout, which is the right one: the daemon holds the reply for
+        // the whole park and sends nothing at all in the meantime, so any data is
+        // the answer and no data for this long is a park that outlived its own
+        // deadline.
+        socket.setTimeout(timeoutMs, () => {
+            done(new ArgusTransportError(`argusd did not answer within ${Math.round(timeoutMs / 1000)}s`, "ETIMEDOUT"));
+        });
+        socket.on("connect", () => {
+            socket.write(`${JSON.stringify(request)}\n`);
+        });
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            const newline = buffer.indexOf("\n");
+            if (newline >= 0)
+                done(null, buffer.slice(0, newline));
+        });
+        socket.on("error", (error) => {
+            const code = error.code ?? "";
+            if (code === "ENOENT" || code === "ECONNREFUSED") {
+                done(new ArgusUnreachableError(error.message, code, socketPath));
+                return;
+            }
+            done(new ArgusTransportError(error.message, code === "" ? "EIO" : code));
+        });
+        socket.on("close", () => {
+            // Closed without a newline. A line that arrived whole but unterminated is
+            // still an answer; nothing at all is a daemon that hung up mid-reply.
+            if (buffer.trim() !== "")
+                done(null, buffer.trim());
+            else
+                done(new ArgusTransportError("argusd closed the connection without answering", "EPIPE"));
+        });
+    });
+}
+/**
+ * The refusal ids this route adds to `delegate`'s closed set.
+ *
+ * Every one names a DIFFERENT fix, which is the whole reason they are told
+ * apart — the app renders a fact and the fix beside it, and two states that
+ * share a word send somebody to the wrong Settings pane. `unsupported` and
+ * `folder-missing` are not here because the verb already has them and they
+ * mean the same thing on this route.
+ */
+export const ARGUS_REASONS = [
+    /** No `argusd`. Nothing is listening on the socket — opening Navarch starts one. */
+    "argusd-not-running",
+    /** `argusd` is running and predates the verb. The fix is a reload, which ends every live session. */
+    "argusd-outdated",
+    /** `argusd` is up, Navarch is not. Only the app can start or type into a worker. */
+    "navarch-not-running",
+    /** The gate: this request did not carry operator authority. */
+    "not-an-operator",
+    /** Twelve operator writes a minute, and this one was the thirteenth. */
+    "rate-limited",
+    /** A person said no at the approval card, or the dial is set to Never. */
+    "declined",
+    /** Navarch tried and nothing was delivered — a trust dialog, a blank screen, a worker that exited. */
+    "delivery-failed",
+    /** `--status` for a delegation this core does not hold: another core's, or one that aged out. */
+    "request-unknown",
+    /**
+     * `--gh-account` named an identity this core has never heard of, AND a worker
+     * would be started (#1402).
+     *
+     * Passed through as its own id rather than folded into `argus-refused`,
+     * because it is the one socket refusal with a fix a PERSON performs and the
+     * app can name: add the account in Navarch ▸ Accounts, or ask with a
+     * spelling this core knows — the daemon puts every label and login it holds
+     * in `detail` and in `data.known`.
+     *
+     * There is deliberately no fallback on either side. A worker with no binding
+     * runs as whatever `gh` was last logged in as, and a hand-off that commits
+     * under the wrong identity is the failure this resolution exists to prevent.
+     */
+    "gh-account-unknown",
+    /** The daemon refused for a reason this pharos has no id for. Its own reason and prose travel in the detail. */
+    "argus-refused",
+];
+/**
+ * Generic over what it is paired with, because three different reads return
+ * "the thing, or the refusal that stopped it": a delegation, a fleet, a list.
+ */
+export function isFailure(value) {
+    return "reason" in value && "detail" in value && "argus" in value;
+}
+/**
+ * The delegation inside a reply, or the refusal it is instead.
+ *
+ * One function for all three answers — `delegate`, the end of its park and
+ * `delegate_status` — because the daemon builds all three from one builder and
+ * a caller that parsed them separately would be inventing a difference.
+ */
+export function readDelegation(reply) {
+    if (reply.ok)
+        return readRow(reply.data);
+    const failure = mapRefusal(reply);
+    // `declined` and `failed` are reported WITH the row, so the app can still say
+    // which worker and which folder it was about.
+    if (reply.data !== null && typeof reply.data["action"] === "string") {
+        failure.delegation = readRow(reply.data);
+    }
+    return failure;
+}
+function readRow(data) {
+    const action = data["action"];
+    return {
+        action: action === "sent" || action === "launched" ? action : "pending",
+        request: text(data["request"]),
+        worker: optional(data["worker"]),
+        name: optional(data["name"]),
+        created: data["created"] === true,
+        kind: text(data["kind"]),
+        directory: text(data["directory"]),
+        host: text(data["host"]),
+        todo: typeof data["todo"] === "number" ? data["todo"] : null,
+        detail: text(data["detail"]),
+    };
+}
+/**
+ * A refusal, as an id this CLI's caller already renders.
+ *
+ * ## The rule that matters: **no `reason` key is an OLD DAEMON**
+ *
+ * `reason` arrived with `delegate` itself, so an `argusd` too old to serve the
+ * verb is also too old to stamp one. That is not a corner — it is the first
+ * thing this route meets on any machine whose daemon has not been reloaded,
+ * which on the machine this was written on was every machine the day it
+ * landed. And an old daemon says three different things, two of which accuse
+ * this CLI of a bug it does not have (measured against argus `2fa7bf0`, the
+ * commit before the verb):
+ *
+ * | what is attached | what comes back, with no `reason` |
+ * |---|---|
+ * | old daemon, old app or none | `unknown op 'delegate' — see argus-board help …` |
+ * | old daemon, **new Navarch publishing `delegate`** | `delegate requires a "todo" (id) — the work it serves` |
+ * | …the same, unstamped | `'delegate' is an Argus Agent action — this session was not started as one. …` |
+ *
+ * The middle row is the trap: an old daemon forwards any verb the app claims
+ * it can run, and that forwarder demands the `todo` this verb exists to
+ * remove. A caller that believed the prose would go and add one. So the test
+ * is the MISSING KEY and never the wording — the wording only chooses how
+ * sharply the detail can put it. A current daemon stamps a reason on every
+ * refusal, and argus asserts that in `Tests/delegate_test.py` precisely so this
+ * inference stays true.
+ */
+export function mapRefusal(reply) {
+    const argus = { reason: reply.reason, error: reply.error };
+    const said = reply.error.trim();
+    const because = said === "" ? "" : ` argusd said: ${said}`;
+    if (reply.reason === null) {
+        const shape = /^unknown op '/.test(said)
+            ? "It does not know the verb at all"
+            : said.includes('requires a "todo"')
+                ? "It is forwarding the verb to Navarch, which is newer than it is, and its forwarder still "
+                    + "demands the board todo this verb exists to do without — the message blames the request "
+                    + "and the request is fine"
+                : "It refused without the stable reason every current refusal carries";
+        return {
+            reason: "argusd-outdated",
+            detail: "The argusd running on this machine predates the delegate verb. "
+                + `${shape}. Reload it — deliberately, because a reload ends every live worker session — `
+                + `and Navarch will come back with it.${because}`,
+            argus,
+        };
+    }
+    switch (reply.reason) {
+        case "unknown-op":
+            return {
+                reason: "argusd-outdated",
+                detail: "The argusd running on this machine does not serve the delegate verb. Reload it — "
+                    + "deliberately, because a reload ends every live worker session."
+                    + because,
+                argus,
+            };
+        case "no-core":
+            return {
+                reason: "navarch-not-running",
+                detail: "argusd is running but Navarch is not, and only the app can start a worker or type into "
+                    + "one. Open Navarch and try again."
+                    + because,
+                argus,
+            };
+        case "unsupported":
+            return {
+                reason: "unsupported",
+                detail: "The Navarch running on this machine is an older build that does not serve delegations. "
+                    + "Update it — `./scripts/make-app.sh --install` in the argus repo — and try again."
+                    + because,
+                argus,
+            };
+        case "not-an-operator":
+            return {
+                reason: "not-an-operator",
+                detail: "argusd refused the delegation for want of operator authority, which pharos stamps on "
+                    + "every request it sends. That means the daemon did not read the stamp — it is almost "
+                    + "always one that predates the verb."
+                    + because,
+                argus,
+            };
+        case "rate-limited":
+            return {
+                reason: "rate-limited",
+                detail: "argusd caps operator writes at twelve a minute and this delegation was over it. Wait a "
+                    + "minute and send it again; nothing was delivered."
+                    + because,
+                argus,
+            };
+        case "declined":
+            return {
+                reason: "declined",
+                detail: said === "" ? "The delegation was declined in Navarch. Nothing was delivered." : said,
+                argus,
+            };
+        case "failed":
+            return {
+                reason: "delivery-failed",
+                detail: said === "" ? "Navarch could not deliver the prompt. Nothing was typed." : said,
+                argus,
+            };
+        case "bad-directory":
+            return {
+                reason: "folder-missing",
+                detail: "argusd does not see that folder on this machine. The linked folder for this project has "
+                    + "moved or was never here — pick it again in Settings ▸ Agents."
+                    + because,
+                argus,
+            };
+        // **The daemon's `worker-not-eligible` is this verb's `session-gone`** —
+        // the same meaning to a caller, which is the only question that decides
+        // whether two ids should be one. Both say: the row you named is not one
+        // this machine will deliver to, nothing was sent, and the fix is to read
+        // the list again and pick from it. An app that renders `session-gone` for
+        // a Terminal pid that has exited renders exactly the right thing here.
+        //
+        // **The daemon's own sentence is kept verbatim rather than rewritten**,
+        // because it names WHICH of six it was — exited, an Argus Agent, holding
+        // mission #N, the wrong kind, on another Mac, in another folder — and each
+        // of those is a different next move for the person. Our own framing is
+        // added around it, not over it.
+        case "worker-not-eligible":
+            return {
+                reason: "session-gone",
+                detail: (said === "" ? "That worker is not one argusd will deliver to." : said)
+                    + " Nothing was sent and nothing was started: a chosen session is a choice, so this refuses "
+                    + "rather than quietly using another worker. Re-read the inventory with `pharos delegate "
+                    + "--list --host navarch`, or pass `--session new` to start a fresh worker on purpose.",
+                argus,
+            };
+        // Passed through as itself. The fix is a person's — add the account in
+        // Navarch ▸ Accounts, or ask with a spelling this core knows — and argusd
+        // has already named every label and login it holds, so rewriting the
+        // sentence could only lose the list.
+        case "gh-account-unknown":
+            return {
+                reason: "gh-account-unknown",
+                detail: said === ""
+                    ? "Navarch has no GitHub account by that name, and this delegation would start a worker — "
+                        + "which must not run as whichever account `gh` happens to be logged in as."
+                    : said,
+                argus,
+            };
+        case "unknown-request":
+            return {
+                reason: "request-unknown",
+                detail: "argusd holds no delegation with that id — it was made on another core, or it has aged "
+                    + "out (delegations are kept for an hour). A status read cannot recover one; delegate "
+                    + "again."
+                    + because,
+                argus,
+            };
+        default:
+            return {
+                reason: "argus-refused",
+                detail: `argusd refused the delegation (${reply.reason}). This pharos has no fix for that reason, `
+                    + `so here is what it said verbatim: ${said === "" ? "(nothing)" : said}`,
+                argus,
+            };
+    }
+}
+/**
+ * The word that means "start one anyway", beside the uuids `worker` also takes
+ * (`BoardStore.delegateFreshWorker`).
+ *
+ * It is the same spelling as this CLI's own reserved `--session new`, and that
+ * is a coincidence worth keeping rather than a shared constant: one is a value
+ * a person types at a flag, the other is a value on argus's wire, and the day
+ * either side renames its own the other must not silently follow.
+ */
+export const ARGUS_NEW_WORKER = "new";
+/**
+ * The request, built in one place.
+ *
+ * `host`, `name`, `stage` and `project` are deliberately never sent. `host`
+ * would name a remote machine and this CLI's `--host` means the application, so
+ * spelling one here would be a collision waiting to pick the wrong worker;
+ * `name` names a NEW worker, which Navarch derives better than a caller can;
+ * `project` and `stage` belong to a board this delegation does not have.
+ *
+ * **`worker` and `gh_account` are omitted when absent rather than sent null.**
+ * The daemon reads a JSON null as absent, so either would work — but a daemon
+ * that predates #1402 IGNORES both keys silently, and an omitted key keeps the
+ * two requests byte-identical to what that daemon has always been sent. The
+ * capability check that stops us sending them to a daemon that would ignore
+ * them is the caller's; see `delegate.ts`.
+ */
+export function delegateRequest(job) {
+    const aimed = (job.worker ?? "").trim();
+    const account = (job.ghAccount ?? "").trim();
+    return {
+        op: "delegate",
+        _fleet: "1",
+        _agent: ARGUS_AGENT,
+        directory: job.directory,
+        kind: job.kind,
+        text: job.text,
+        wait: job.wait ?? ARGUS_WAIT_SECONDS,
+        ...(aimed === "" ? {} : { worker: aimed }),
+        ...(account === "" ? {} : { gh_account: account }),
+    };
+}
+/**
+ * `delegate_candidates` — **the find, asked instead of performed** (#1402).
+ *
+ * A read: ungated, not rate-limited, and answered from the same fleet snapshot
+ * `fleet_status` is served from, so it says strictly less than this socket
+ * already tells everyone on it. It is stamped like every other request from
+ * here all the same, so a refusal cannot be about the stamp.
+ *
+ * `host` is deliberately not sent. It would name a remote machine, and this
+ * CLI's `--host` means the application — the daemon defaults it to empty,
+ * which is this Mac, and that is the only fleet this verb can reach.
+ */
+export function delegateCandidatesRequest(directory, kind) {
+    return { op: "delegate_candidates", _fleet: "1", _agent: ARGUS_AGENT, directory, kind };
+}
+export function delegateStatusRequest(request, wait = 0) {
+    return { op: "delegate_status", _fleet: "1", _agent: ARGUS_AGENT, request, wait };
+}
+export function fleetStatusRequest() {
+    // A read, and the daemon never gates one — but it is stamped like every other
+    // request from here so a refusal cannot be about the stamp.
+    return { op: "fleet_status", _fleet: "1", _agent: ARGUS_AGENT };
+}
+/**
+ * How long to wait on the socket for a park of `wait` seconds.
+ *
+ * The daemon has to notice its own deadline and write a reply after it, so the
+ * read has to outlast the park or every timed-out delegation reads as a broken
+ * socket. Ten seconds of margin, the same shape `argus-board` uses (it allows
+ * five, for reads that are not parked on a person).
+ */
+export function readTimeoutMs(waitSeconds) {
+    return (waitSeconds + 10) * 1000;
+}
+export async function askArgus(deps, request, timeoutMs) {
+    const line = await deps.ask(request, timeoutMs);
+    const reply = parseArgusReply(line);
+    if (reply === null) {
+        throw new ArgusTransportError(`argusd answered with something that is not a reply: ${line.slice(0, 200)}`, "EBADMSG");
+    }
+    return reply;
+}
+/** The refusal for a socket nothing is listening on. */
+export function unreachable(error) {
+    return {
+        reason: "argusd-not-running",
+        detail: `Nothing is listening on the Argus socket at ${error.socketPath} (${error.code}). argusd is `
+            + "what holds a Navarch worker's terminal, and opening Navarch starts it — so open Navarch "
+            + "and try again. If it IS open, the socket has moved: ARGUS_BOARD_SOCK overrides where this "
+            + "looks.",
+        argus: { reason: null, error: `${error.code}: ${error.message}` },
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Empty is not absent, and on this wire the difference is load-bearing. */
+function optional(value) {
+    return typeof value === "string" && value !== "" ? value : null;
+}
+export function parseFleet(reply) {
+    return parseWorkers(reply.data["workers"]);
+}
+export function parseCandidates(reply) {
+    return { workers: parseWorkers(reply.data["candidates"]), target: optional(reply.data["target"]) };
+}
+function parseWorkers(value) {
+    const workers = value;
+    if (!Array.isArray(workers))
+        return [];
+    const rows = [];
+    for (const entry of workers) {
+        if (!isRecord(entry))
+            continue;
+        const id = text(entry["id"]);
+        if (id === "")
+            continue;
+        rows.push({
+            id,
+            name: text(entry["name"]),
+            kind: text(entry["kind"]),
+            status: text(entry["status"]),
+            stage: text(entry["stage"]),
+            directory: text(entry["directory"]),
+            host: text(entry["host"]),
+            todo: typeof entry["todo"] === "number" ? entry["todo"] : null,
+            fleet: entry["fleet"] === true,
+        });
+    }
+    return rows;
+}
+/**
+ * Is this worker a candidate for a delegation onto `directory`?
+ *
+ * `BoardStore.delegateTarget`, rule for rule. Two of the five exclusions are
+ * the interesting ones, and both look like perfectly good targets from here:
+ *
+ * - **a mission worker** runs in a shared base checkout and would match, and
+ *   typing an unrelated work item into an agent mid-branch derails the todo it
+ *   is holding;
+ * - **an Argus Agent** is a claude worker with no mission sitting in a base
+ *   checkout — which is exactly the folder a person links in Pharos. A
+ *   delegation landing there hands the work item to the thing that *drives* the
+ *   fleet, in the session whose next turn can start missions and type into
+ *   every other worker.
+ *
+ * **Mission-hood is weaker here than it is inside the daemon**, and the
+ * difference is worth knowing. The daemon tests `missionTodo` on the worker
+ * itself; `fleet_status` only writes `todo` onto the row when the board still
+ * holds that todo, so a mission whose todo was deleted reads as free here and
+ * is excluded there. The direction of the error is the safe one — this can
+ * only list or predict a worker the daemon would decline to use, never hide
+ * one it would pick — but it is why a prediction is all this is, and why the
+ * send itself never names a worker: the daemon does the find that counts.
+ */
+export function eligible(worker, kind, directory) {
+    return (worker.status !== "exited"
+        && worker.kind === kind
+        && worker.todo === null
+        && !worker.fleet
+        // Local only. This CLI has no way to name a remote machine — `--host` here
+        // means the application — so a worker on one is never a candidate.
+        && worker.host.trim() === ""
+        && sameFolder(worker.directory, directory));
+}
+/**
+ * Two spellings of one folder.
+ *
+ * The daemon compares `standardizingPath` on both sides, which expands `~`,
+ * drops `.`/`..` and a trailing slash and resolves the symlinked prefixes
+ * macOS ships (`/tmp` → `/private/tmp`) — but NOT an arbitrary symlink
+ * somebody made. That is why the caller canonicalises the folder with
+ * `realpath` before it gets here, the same way the Terminal route does; this
+ * is the rest of the daemon's normalisation, and it is case-insensitive
+ * because `caseInsensitiveCompare` is what the daemon uses.
+ */
+export function sameFolder(a, b) {
+    return standardize(a).toLowerCase() === standardize(b).toLowerCase();
+}
+function standardize(path) {
+    let value = path.trim();
+    if (value === "")
+        return "";
+    // `/tmp`, `/var` and `/etc` are symlinks into `/private` on macOS, and
+    // `standardizingPath` resolves exactly those three.
+    for (const prefix of ["/tmp", "/var", "/etc"]) {
+        if (value === prefix || value.startsWith(`${prefix}/`)) {
+            value = `/private${value}`;
+            break;
+        }
+    }
+    while (value.length > 1 && value.endsWith("/"))
+        value = value.slice(0, -1);
+    return value;
+}
+/**
+ * The candidates for a delegation onto `directory`, in the order the daemon
+ * would pick them. `[0]` is the worker a plain delegate takes.
+ *
+ * **The tie-break is the id and never the status**, because two calls a second
+ * apart must pick the same pane. A worker that has not painted yet is worst —
+ * there is no box to type into — and everything else is equal, so `starting`
+ * sinks and the rest sort on a uuid that never changes.
+ */
+export function rankWorkers(workers, kind, directory) {
+    return workers
+        .filter((worker) => eligible(worker, kind, directory))
+        .sort((a, b) => {
+        const starting = Number(a.status === "starting") - Number(b.status === "starting");
+        if (starting !== 0)
+            return starting;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+}
+// MARK: - Does this daemon serve the verb at all?
+/**
+ * The read that answers "has this argusd been reloaded since `delegate`
+ * landed?" without delegating anything.
+ *
+ * `delegate_status` is a pure read of the daemon's own table — not gated, not
+ * rate-limited, and about an id it minted — so asking it about one that cannot
+ * exist costs nothing and changes nothing. A current daemon answers
+ * `unknown-request`; one that predates the verb answers `unknown op
+ * 'delegate_status'` with no `reason` at all, which is the same tell the send
+ * path uses.
+ *
+ * It earns its round trip on `--list` and `--dry-run`, which otherwise read
+ * `fleet_status` — a verb every generation of the daemon serves — and would
+ * cheerfully list workers that a send is about to refuse to deliver to.
+ */
+export const PROBE_REQUEST = "00000000-0000-0000-0000-000000000000";
+/** True when the reply says this daemon knows the delegate family. */
+export function servesDelegate(reply) {
+    return reply.ok || reply.reason !== null;
+}
+export function candidatesSupport(reply) {
+    if (reply.ok)
+        return "yes";
+    if (reply.reason === null)
+        return "pre-delegate";
+    return reply.reason === "unknown-op" ? "no-op" : "yes";
+}
+//# sourceMappingURL=argus.js.map