@floh-solutions/pharos-cli 0.29.0 → 0.31.0

package/dist/delegate/hosts.js

@@ -0,0 +1,154 @@
+import { execFile } from "node:child_process";
+import { access, constants } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+export const HOST_IDS = ["terminal", "vscode", "vscode-insiders", "navarch"];
+export const AGENT_IDS = ["claude", "codex"];
+export const MODES = ["terminal", "extension"];
+export const HOSTS = {
+    terminal: {
+        id: "terminal",
+        name: "Terminal",
+        bundleId: "com.apple.Terminal",
+        candidates: [
+            "/System/Applications/Utilities/Terminal.app",
+            "/Applications/Utilities/Terminal.app",
+        ],
+    },
+    vscode: {
+        id: "vscode",
+        name: "Visual Studio Code",
+        bundleId: "com.microsoft.VSCode",
+        candidates: ["/Applications/Visual Studio Code.app", "~/Applications/Visual Studio Code.app"],
+        cask: "visual-studio-code",
+        vscode: {
+            extensionsDir: ".vscode/extensions",
+            scheme: "vscode",
+            helper: ["Visual Studio Code.app", "Code Helper"],
+        },
+    },
+    "vscode-insiders": {
+        id: "vscode-insiders",
+        name: "Visual Studio Code - Insiders",
+        bundleId: "com.microsoft.VSCodeInsiders",
+        candidates: [
+            "/Applications/Visual Studio Code - Insiders.app",
+            "~/Applications/Visual Studio Code - Insiders.app",
+        ],
+        cask: "visual-studio-code@insiders",
+        vscode: {
+            extensionsDir: ".vscode-insiders/extensions",
+            scheme: "vscode-insiders",
+            helper: ["Visual Studio Code - Insiders.app", "Code - Insiders Helper"],
+        },
+    },
+    navarch: {
+        id: "navarch",
+        name: "Navarch",
+        bundleId: "com.argus.app",
+        candidates: ["/Applications/Navarch.app", "~/Applications/Navarch.app"],
+    },
+};
+export function isHostId(value) {
+    return HOST_IDS.includes(value);
+}
+export function isAgentId(value) {
+    return AGENT_IDS.includes(value);
+}
+export function isMode(value) {
+    return MODES.includes(value);
+}
+/**
+ * Is the app installed, where, and which version. Never throws — absence is an
+ * answer. Always `null` off macOS: every host here is a macOS application.
+ */
+export async function findApp(host, env = process.env) {
+    if (platform() !== "darwin")
+        return null;
+    const spec = HOSTS[host];
+    const found = await spotlight(spec.bundleId);
+    if (found !== null)
+        return { path: found, version: await bundleVersion(found), via: "spotlight" };
+    const home = env["HOME"] ?? homedir();
+    for (const candidate of spec.candidates) {
+        const path = candidate.startsWith("~/") ? join(home, candidate.slice(2)) : candidate;
+        if (await exists(join(path, "Contents", "Info.plist"))) {
+            return { path, version: await bundleVersion(path), via: "path" };
+        }
+    }
+    return null;
+}
+/**
+ * Spotlight's answer, or null. Several bundles can carry one id (a copy on an
+ * external disk, an old version in the Trash); `/Applications` wins, then the
+ * first the index lists.
+ */
+async function spotlight(bundleId) {
+    try {
+        const { stdout } = await run("/usr/bin/mdfind", [`kMDItemCFBundleIdentifier == '${bundleId}'`], { timeout: 5_000, maxBuffer: 1024 * 1024 });
+        const paths = stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.endsWith(".app") && !line.includes("/.Trash/"));
+        if (paths.length === 0)
+            return null;
+        return paths.find((path) => path.startsWith("/Applications/") || path.startsWith("/System/")) ?? paths[0];
+    }
+    catch {
+        return null;
+    }
+}
+/** `CFBundleShortVersionString`, read the way scripts are meant to: `plutil -extract … raw`. */
+export async function bundleVersion(appPath) {
+    try {
+        const { stdout } = await run("/usr/bin/plutil", ["-extract", "CFBundleShortVersionString", "raw", "-o", "-", join(appPath, "Contents", "Info.plist")], { timeout: 5_000 });
+        const version = stdout.trim();
+        return version === "" ? null : version;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The CLI inside a VS Code bundle.
+ *
+ * `code` is often NOT on PATH — it was not on the reference machine — because
+ * putting it there is a menu action ("Install 'code' command in PATH") that
+ * most people never take. The bundle always carries it, at the same relative
+ * path in both flavours.
+ */
+export function bundleCli(appPath) {
+    return join(appPath, "Contents", "Resources", "app", "bin", "code");
+}
+/**
+ * Which host a process belongs to, from its command as `ps` prints it.
+ *
+ * Measured chains on the reference machine: a Terminal tab is
+ * `login ← Terminal.app/Contents/MacOS/Terminal`; a Navarch worker is
+ * `zsh ← argusd`; a VS Code integrated terminal's shell hangs off a
+ * `Code - Insiders Helper (Plugin)` process inside the bundle. Insiders is
+ * tested before stable because its names contain the stable ones.
+ */
+export function hostOfCommand(comm) {
+    if (comm.endsWith("Terminal.app/Contents/MacOS/Terminal"))
+        return "terminal";
+    for (const id of ["vscode-insiders", "vscode"]) {
+        if (HOSTS[id].vscode.helper.some((marker) => comm.includes(marker)))
+            return id;
+    }
+    if (comm.endsWith("/argusd") || comm === "argusd" || comm.includes("Navarch.app/"))
+        return "navarch";
+    return null;
+}
+async function exists(path) {
+    try {
+        await access(path, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=hosts.js.map

package/dist/delegate/hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.js","sourceRoot":"","sources":["../../src/delegate/hosts.ts"],"names":[],"mappings":"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"}

package/dist/delegate/quote.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Getting a prompt into a terminal without a shell or AppleScript reading it.
+ *
+ * Two languages sit between `pharos delegate` and the agent, and each has its
+ * own idea of what a quote, a dollar or a backtick means:
+ *
+ *   1. **AppleScript**, which carries the text to Terminal.app. It is NOT
+ *      quoted at all: the script sources below take the text as an `argv`
+ *      item (`osascript -e '…' -- <tty> <text>`), so nothing the person typed
+ *      is ever spliced into AppleScript source. Measured: a value holding `"`,
+ *      `'`, `$HOME`, a backtick and a backslash comes back from `on run argv`
+ *      byte for byte. The alternative — escaping into a string literal — is a
+ *      second quoting scheme to get wrong, and getting it wrong runs code.
+ *   2. **The shell**, for the ONE route that goes through one: a new Terminal
+ *      window runs `cd '<folder>' && '<agent>' '<text>'` in the person's login
+ *      shell. That string is built here with single quotes, which is the only
+ *      shell quoting that means "no interpretation whatsoever" — inside `'…'`
+ *      nothing is special except `'` itself, spelled `'\''`.
+ *
+ * Injecting into a RUNNING session goes through neither: `do script … in tab`
+ * writes the string to the tab's tty as typed input, so the agent's own input
+ * box reads it, and shells and scripts never see it.
+ */
+/** POSIX single-quoting: safe in `sh`, `bash` and `zsh`, and nothing is special inside. */
+export declare function shellQuote(value: string): string;
+/**
+ * The command a NEW Terminal window runs when no session was found.
+ *
+ * The agent is spawned by its resolved absolute path rather than its name: a
+ * fresh login shell may not have run the nvm or Homebrew init that puts
+ * `claude` on PATH yet, and an absolute path does not care.
+ */
+export declare function launchCommand(folder: string, agentPath: string, text: string): string;
+/**
+ * Bracketed paste, as the terminal would wrap a real paste.
+ *
+ * A running agent submits on Enter, so typing a multi-line prompt into it
+ * sends the first line and leaves the rest as a second message. Wrapped in
+ * `ESC[200~ … ESC[201~` the same bytes arrive as ONE paste, which the input
+ * box inserts whole; the return `do script` appends afterwards then submits it.
+ * Navarch's `WorkerManager.sendLine` does the same thing for the same reason.
+ */
+export declare const BRACKETED_PASTE: {
+    readonly open: "\u001B[200~";
+    readonly close: "\u001B[201~";
+};
+/** Newlines become spaces — the fallback when bracketed paste cannot be trusted. */
+export declare function foldLines(text: string): string;
+/**
+ * What to type into a running session.
+ *
+ * Single-line text is typed as-is. Multi-line text is wrapped in bracketed
+ * paste, or folded to one line when the caller has reason not to trust the
+ * paste. Which one the Terminal route uses is a measurement recorded on
+ * `commands/delegate.ts`.
+ *
+ * **C0 control bytes are stripped first**, keeping only tab and newline. This
+ * is what wraps the text in bracketed paste, so a raw `ESC[201~` (or any stray
+ * escape) in the prompt could otherwise close the paste early and have the rest
+ * reach the TUI as keystrokes. `\n` is kept — it is what decides bracketed vs.
+ * single-line — and `\t` is a legitimate character in a prompt.
+ */
+export declare function asTypedInput(text: string, multiline?: "bracketed" | "fold"): string;
+/**
+ * AppleScript sources. **No user text is ever interpolated into these** — a
+ * test asserts it — everything variable arrives through `argv`.
+ */
+/**
+ * Type into the tab whose tty matches, bring it forward, and say what happened.
+ *
+ * `do script … in t` writes to that tab's tty as if typed and follows it with a
+ * return. Answers `sent`, or `no-tab` when no window has a tab on that tty —
+ * the session exists, but not in a Terminal.app this instance can see.
+ */
+export declare const SEND_TO_TAB_SCRIPT = "on run argv\n  set targetTty to item 1 of argv\n  set theText to item 2 of argv\n  tell application \"Terminal\"\n    repeat with w in windows\n      repeat with t in tabs of w\n        if tty of t is targetTty then\n          do script theText in t\n          set selected tab of w to t\n          set index of w to 1\n          activate\n          return \"sent\"\n        end if\n      end repeat\n    end repeat\n  end tell\n  return \"no-tab\"\nend run";
+/** A new window running one shell command, brought to the front. */
+export declare const LAUNCH_SCRIPT = "on run argv\n  set theCommand to item 1 of argv\n  tell application \"Terminal\"\n    do script theCommand\n    activate\n  end tell\n  return \"launched\"\nend run";
+//# sourceMappingURL=quote.d.ts.map

package/dist/delegate/quote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quote.d.ts","sourceRoot":"","sources":["../../src/delegate/quote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAqBD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;CAA+C,CAAC;AAE5E,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,WAAW,GAAG,MAAoB,GAAG,MAAM,CAOhG;AAED;;;GAGG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,8cAiBvB,CAAC;AAET,oEAAoE;AACpE,eAAO,MAAM,aAAa,yKAOlB,CAAC"}

package/dist/delegate/quote.js

@@ -0,0 +1,134 @@
+/**
+ * Getting a prompt into a terminal without a shell or AppleScript reading it.
+ *
+ * Two languages sit between `pharos delegate` and the agent, and each has its
+ * own idea of what a quote, a dollar or a backtick means:
+ *
+ *   1. **AppleScript**, which carries the text to Terminal.app. It is NOT
+ *      quoted at all: the script sources below take the text as an `argv`
+ *      item (`osascript -e '…' -- <tty> <text>`), so nothing the person typed
+ *      is ever spliced into AppleScript source. Measured: a value holding `"`,
+ *      `'`, `$HOME`, a backtick and a backslash comes back from `on run argv`
+ *      byte for byte. The alternative — escaping into a string literal — is a
+ *      second quoting scheme to get wrong, and getting it wrong runs code.
+ *   2. **The shell**, for the ONE route that goes through one: a new Terminal
+ *      window runs `cd '<folder>' && '<agent>' '<text>'` in the person's login
+ *      shell. That string is built here with single quotes, which is the only
+ *      shell quoting that means "no interpretation whatsoever" — inside `'…'`
+ *      nothing is special except `'` itself, spelled `'\''`.
+ *
+ * Injecting into a RUNNING session goes through neither: `do script … in tab`
+ * writes the string to the tab's tty as typed input, so the agent's own input
+ * box reads it, and shells and scripts never see it.
+ */
+/** POSIX single-quoting: safe in `sh`, `bash` and `zsh`, and nothing is special inside. */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Clear this session's Claude Code identity from the launched shell, in the
+ * command itself.
+ *
+ * **The Terminal route cannot rely on scrubbing the spawner's environment.** A
+ * new Terminal tab inherits Terminal.app's environment, not `osascript`'s, so
+ * when Terminal was itself launched from inside a Claude session (measured:
+ * #1375, and note 4792) every tab already carries `CLAUDE_CODE_*` — and a
+ * `claude` started there registers as a *child* of that session, invisible to
+ * `claude agents --json` with its transcript off. Clearing the markers in the
+ * shell command fixes it wherever the command runs, independent of the ambient
+ * environment. `CLAUDE_CODE_SSE_PORT` is kept — it points a child at a shared
+ * MCP server, not at the parent's identity. `env`/`sed` are in `/usr/bin`, on
+ * every PATH; `__v` is unset last so it does not leak into the agent.
+ */
+const CLEAR_CLAUDE_ENV = "for __v in $(env | sed -n 's/^\\(CLAUDE_CODE_[A-Za-z0-9_]*\\)=.*/\\1/p'); "
+    + 'do [ "$__v" = CLAUDE_CODE_SSE_PORT ] || unset "$__v"; done; unset CLAUDECODE CLAUDE_PID __v';
+/**
+ * The command a NEW Terminal window runs when no session was found.
+ *
+ * The agent is spawned by its resolved absolute path rather than its name: a
+ * fresh login shell may not have run the nvm or Homebrew init that puts
+ * `claude` on PATH yet, and an absolute path does not care.
+ */
+export function launchCommand(folder, agentPath, text) {
+    // `--` ends the agent's own option parsing, so a prompt that begins with a
+    // dash is the prompt and not a misread flag. Measured: `claude -- '-foo'` and
+    // `codex -- '-foo'` both take the text as the prompt (claude 2.1.268, codex
+    // 0.154.0, clap's standard terminator).
+    return `${CLEAR_CLAUDE_ENV}; cd ${shellQuote(folder)} && ${shellQuote(agentPath)} -- ${shellQuote(text)}`;
+}
+/**
+ * Bracketed paste, as the terminal would wrap a real paste.
+ *
+ * A running agent submits on Enter, so typing a multi-line prompt into it
+ * sends the first line and leaves the rest as a second message. Wrapped in
+ * `ESC[200~ … ESC[201~` the same bytes arrive as ONE paste, which the input
+ * box inserts whole; the return `do script` appends afterwards then submits it.
+ * Navarch's `WorkerManager.sendLine` does the same thing for the same reason.
+ */
+export const BRACKETED_PASTE = { open: "[200~", close: "[201~" };
+/** Newlines become spaces — the fallback when bracketed paste cannot be trusted. */
+export function foldLines(text) {
+    return text.replace(/\r?\n/g, " ").replace(/ {2,}/g, " ").trim();
+}
+/**
+ * What to type into a running session.
+ *
+ * Single-line text is typed as-is. Multi-line text is wrapped in bracketed
+ * paste, or folded to one line when the caller has reason not to trust the
+ * paste. Which one the Terminal route uses is a measurement recorded on
+ * `commands/delegate.ts`.
+ *
+ * **C0 control bytes are stripped first**, keeping only tab and newline. This
+ * is what wraps the text in bracketed paste, so a raw `ESC[201~` (or any stray
+ * escape) in the prompt could otherwise close the paste early and have the rest
+ * reach the TUI as keystrokes. `\n` is kept — it is what decides bracketed vs.
+ * single-line — and `\t` is a legitimate character in a prompt.
+ */
+export function asTypedInput(text, multiline = "bracketed") {
+    const stripped = text.replace(/[\u0000-\u0008\u000B-\u001F\u007F]/g, "");
+    const trimmed = stripped.replace(/\r\n/g, "\n").replace(/\n+$/, "");
+    if (!trimmed.includes("\n"))
+        return trimmed;
+    return multiline === "fold"
+        ? foldLines(trimmed)
+        : `${BRACKETED_PASTE.open}${trimmed}${BRACKETED_PASTE.close}`;
+}
+/**
+ * AppleScript sources. **No user text is ever interpolated into these** — a
+ * test asserts it — everything variable arrives through `argv`.
+ */
+/**
+ * Type into the tab whose tty matches, bring it forward, and say what happened.
+ *
+ * `do script … in t` writes to that tab's tty as if typed and follows it with a
+ * return. Answers `sent`, or `no-tab` when no window has a tab on that tty —
+ * the session exists, but not in a Terminal.app this instance can see.
+ */
+export const SEND_TO_TAB_SCRIPT = `on run argv
+  set targetTty to item 1 of argv
+  set theText to item 2 of argv
+  tell application "Terminal"
+    repeat with w in windows
+      repeat with t in tabs of w
+        if tty of t is targetTty then
+          do script theText in t
+          set selected tab of w to t
+          set index of w to 1
+          activate
+          return "sent"
+        end if
+      end repeat
+    end repeat
+  end tell
+  return "no-tab"
+end run`;
+/** A new window running one shell command, brought to the front. */
+export const LAUNCH_SCRIPT = `on run argv
+  set theCommand to item 1 of argv
+  tell application "Terminal"
+    do script theCommand
+    activate
+  end tell
+  return "launched"
+end run`;
+//# sourceMappingURL=quote.js.map

package/dist/delegate/quote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quote.js","sourceRoot":"","sources":["../../src/delegate/quote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,2FAA2F;AAC3F,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,gBAAgB,GACpB,4EAA4E;MAC1E,6FAA6F,CAAC;AAElG;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,SAAiB,EAAE,IAAY;IAC3E,2EAA2E;IAC3E,8EAA8E;IAC9E,4EAA4E;IAC5E,wCAAwC;IACxC,OAAO,GAAG,gBAAgB,QAAQ,UAAU,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,SAAS,CAAC,OAAO,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;AAC5G,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAW,CAAC;AAE5E,oFAAoF;AACpF,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,YAAkC,WAAW;IACtF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,qCAAqC,EAAE,EAAE,CAAC,CAAC;IACzE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IAC5C,OAAO,SAAS,KAAK,MAAM;QACzB,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC;QACpB,CAAC,CAAC,GAAG,eAAe,CAAC,IAAI,GAAG,OAAO,GAAG,eAAe,CAAC,KAAK,EAAE,CAAC;AAClE,CAAC;AAED;;;GAGG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;QAiB1B,CAAC;AAET,oEAAoE;AACpE,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;QAOrB,CAAC"}

package/dist/delegate/sessions.d.ts

@@ -0,0 +1,121 @@
+import { type AgentId, type HostId } from "./hosts.js";
+/**
+ * Which agent sessions are running, where, and inside which host.
+ *
+ * ## Two agents, two routes — measured 2026-09-10
+ *
+ * | agent | route | what it gives |
+ * |---|---|---|
+ * | Claude Code 2.1.268 | `claude agents --json` | every session, interactive ones included: `pid`, `cwd`, `sessionId`, `name`, `status` (`idle`/`busy`). No tty needed. |
+ * | Codex CLI 0.154.0 | `ps -axo pid,ppid,tty,comm` for `codex`, then `lsof -a -p PID -d cwd -Fn` | pid and cwd. `codex queue --thread` exists but needs the app-server daemon, which was not running, so TUI sessions are not reachable through it. |
+ *
+ * ## The host is the process tree
+ *
+ * Neither route says which application a session lives in, and that is the
+ * question `pharos delegate --host` asks. Walking `ppid` up does: this very
+ * session's chain was `zsh ← claude ← zsh ← argusd` (Navarch), a Terminal tab
+ * ends at `Terminal.app/Contents/MacOS/Terminal`, and a VS Code integrated
+ * terminal hangs off a `Code … Helper` process. One `ps` of the whole table,
+ * walked in memory.
+ *
+ * ## `TIOCSTI` is not an option
+ *
+ * Typing into another process's tty directly is refused by the kernel from a
+ * non-controlling process — `EACCES`, confirmed with a private pty. So the
+ * pid and tty found here are handed to the HOST (Terminal's `do script … in
+ * tab`, the VS Code bridge), which owns the terminal and may write to it.
+ */
+export interface ProcessRow {
+    pid: number;
+    ppid: number;
+    /** `/dev/ttys003`, or null for `??`. */
+    tty: string | null;
+    /** The command as `ps` prints it — often a full path, sometimes just `claude`. */
+    comm: string;
+}
+/**
+ * `ps -axo pid,ppid,tty,comm`, parsed.
+ *
+ * The command column is taken as everything after the third column because
+ * it contains spaces — `/Applications/ChatGPT.app/…/Codex (Service)` is one
+ * command. The header line does not match the numeric shape and is dropped.
+ */
+export declare function parsePs(text: string): ProcessRow[];
+export interface ClaudeAgent {
+    pid: number;
+    cwd: string;
+    kind?: string;
+    sessionId?: string;
+    name?: string;
+    status?: string;
+    startedAt?: number;
+}
+/**
+ * `claude agents --json`, parsed tolerantly: an array of objects with a numeric
+ * `pid` and a string `cwd` is all that is required, so a field Claude Code
+ * adds or drops in a later release changes nothing here.
+ */
+export declare function parseClaudeAgents(json: string): ClaudeAgent[];
+/** `lsof -a -p PID -d cwd -Fn` prints `p<pid>`, `fcwd`, `n<path>`; the path is what we want. */
+export declare function parseLsofCwd(text: string): string | null;
+/** The ancestors of a pid, nearest first, stopping at launchd or a cycle. */
+export declare function ancestry(pid: number, rows: readonly ProcessRow[]): ProcessRow[];
+/** The first ancestor that is a known host, or null. */
+export declare function hostOfPid(pid: number, rows: readonly ProcessRow[]): HostId | null;
+export interface Session {
+    agent: AgentId;
+    pid: number;
+    cwd: string;
+    name: string | null;
+    status: "idle" | "busy" | null;
+    tty: string | null;
+    host: HostId | null;
+}
+/** The probes, injectable so the selection logic is testable against fixtures. */
+export interface SessionProbes {
+    ps(): Promise<string>;
+    claudeAgents(): Promise<string>;
+    lsofCwd(pid: number): Promise<string>;
+}
+/**
+ * What detection found, and whether it could be trusted to be complete.
+ *
+ * **`incomplete` is the difference between "no session" and "could not tell".**
+ * An older `claude` without an `agents` subcommand, a hang, or a failed `lsof`
+ * all yield an empty list — and reported as "nothing running" that reads as a
+ * fact when it is a failure. So the caller is told, and says so in the detail
+ * before it launches a second session beside one it simply could not see.
+ */
+export interface Detection {
+    sessions: Session[];
+    incomplete: boolean;
+    /** One clause naming what failed, for the detail. Null when nothing did. */
+    detail: string | null;
+}
+export declare function systemProbes(env: NodeJS.ProcessEnv, claudePath: string | null): SessionProbes;
+/**
+ * Every session of `agent` whose working directory is `folder`, with its host.
+ *
+ * Working directories are compared after `realpath` on both sides, so a
+ * symlinked checkout and its target read as one folder. A session whose cwd
+ * cannot be resolved is compared as printed.
+ */
+export declare function findSessions(agent: AgentId, folder: string, probes: SessionProbes): Promise<Detection>;
+/**
+ * Every session in the requested host that could be delivered to, best first.
+ *
+ * Idle beats busy: a prompt typed into a busy session queues behind the turn
+ * in progress, which works but is a worse experience than a session that is
+ * waiting for exactly this. Among equals the lowest pid — the longest-lived,
+ * which is usually the one the person thinks of as "the" session.
+ *
+ * **This is the ONE ranking, and `--list` and a plain delegate both read it.**
+ * `recommended` on a listed row is not a second implementation of the choice:
+ * it is `[0]` of this array, which is exactly what {@link chooseSession}
+ * returns. Two rankings would be two answers, and the app would mark a row the
+ * verb does not actually use.
+ */
+export declare function rankSessions(sessions: readonly Session[], host: HostId): Session[];
+/** Which session to send to, among those in the requested host: the best-ranked one. */
+export declare function chooseSession(sessions: readonly Session[], host: HostId): Session | null;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/delegate/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/delegate/sessions.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiB,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAItE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAclD;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAwB7D;AAED,gGAAgG;AAChG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKxD;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,EAAE,CAa/E;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,GAAG,IAAI,CAMjF;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CAkB7F;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,CAAC,CA6DpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAclF;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAExF"}