@prohost/cli 0.6.0 → 0.8.0

package/dist/agent/contract.js

@@ -14,6 +14,7 @@
  *   - payload shape — `shared/events/payloads/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/complete` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
+ *   - `POST /v1/agent-runs/{id}/events` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
@@ -27,6 +28,29 @@ export const EVENT_MESSAGE_TEAM_CHAT = 'message.team_chat';
 /** Terminal statuses accepted by the run-completion endpoint. */
 export const RUN_STATUS_SUCCEEDED = 'succeeded';
 export const RUN_STATUS_FAILED = 'failed';
+/**
+ * Completion `outcome` for a run that deliberately posted nothing.
+ *
+ * Sent with `status: succeeded`: declining is a finished run, not a failure.
+ * The server records it the way an in-product `[NO_REPLY]` run is recorded and
+ * clears the thinking indicator as a "chose silence" rather than implying a
+ * reply landed. A server that predates the field ignores it, so it needs no
+ * version negotiation.
+ */
+export const RUN_OUTCOME_SILENT = 'silent';
+/**
+ * What the agent writes as its WHOLE answer to say "no reply".
+ *
+ * The same token the in-product brain uses, so an agent's instructions read the
+ * same on either runtime. Matched on the trimmed output, case-insensitively —
+ * and never posted: the literal token landing in a thread is the one outcome
+ * that is worse than either replying or not.
+ */
+export const NO_REPLY_TOKEN = '[NO_REPLY]';
+/** Whether the agent's output is the no-reply token and nothing else. */
+export function isNoReply(output) {
+    return output.trim().toUpperCase() === NO_REPLY_TOKEN;
+}
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export const MAX_ERROR_CHARS = 1000;
 /** Server-side cap on the `model` field of a completion (`MAX_MODEL_CHARS`). */
@@ -48,6 +72,13 @@ export const RUN_ERROR_CANCELLED_BY_USER = 'cancelled_by_user';
  * enormous block of text can't turn a keep-alive into a payload.
  */
 export const MAX_PROGRESS_CHARS = 200;
+/**
+ * Server-side cap on events per `POST /v1/agent-runs/{id}/events` call
+ * (`shared.agents.external_tool_events.MAX_EVENTS_PER_REQUEST`). The run event
+ * also carries it as `events.max_batch`; this is the value for a payload that
+ * omits it, and the ceiling either way.
+ */
+export const MAX_TOOL_EVENTS_PER_BATCH = 50;
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export const REDEEM_PATH = '/v1/agent-pairing/redeem';
 /** `POST` — send a message into a conversation as the paired agent. */
@@ -117,6 +148,8 @@ export const MAX_ATTACHMENTS = 10;
  * quietly stop half-way through with nothing to explain it.
  */
 export const MAX_SYSTEM_PROMPT_CHARS = 20_000;
+/** Ceiling on `trigger.brief` — the server's `MAX_TRIGGER_BRIEF_CHARS`. */
+export const MAX_TRIGGER_BRIEF_CHARS = 32_000;
 /**
  * Fallback for a server that predates `reply_instructions.body_field`.
  *
@@ -221,6 +254,16 @@ function systemPrompt(value) {
         return undefined;
     return text.length > MAX_SYSTEM_PROMPT_CHARS ? text.slice(0, MAX_SYSTEM_PROMPT_CHARS) : text;
 }
+/**
+ * Bound the server's work order. Same backstop as {@link systemPrompt}, at the
+ * server's own ceiling for the field (`MAX_TRIGGER_BRIEF_CHARS`).
+ */
+function brief(value) {
+    const text = str(value);
+    if (!text)
+        return undefined;
+    return text.length > MAX_TRIGGER_BRIEF_CHARS ? text.slice(0, MAX_TRIGGER_BRIEF_CHARS) : text;
+}
 function parseMessage(entry) {
     const attachments = attachmentList(entry.attachments);
     // Not `str()`: an image-only message carries an empty string here and is a
@@ -265,6 +308,7 @@ export function parseRunRequest(data) {
     const replyInstructions = obj(data.reply_instructions);
     const completion = obj(data.completion);
     const heartbeat = obj(data.heartbeat);
+    const events = obj(data.events);
     const context = obj(data.context);
     const declaredSurface = str(replyInstructions.surface);
     const conversationId = str(data.conversation_id) ?? str(replyInstructions.conversation_id);
@@ -295,6 +339,11 @@ export function parseRunRequest(data) {
         trigger_text: str(trigger.text_excerpt),
         trigger_attachments: attachmentList(trigger.attachments ?? data.trigger_attachments),
         trigger_user_id: str(trigger.user_id),
+        trigger_brief: brief(trigger.brief),
+        // Only an explicit `false` opts out. Absent, null, or anything malformed
+        // keeps today's behaviour — an agent that stays quiet when it was asked
+        // something is a worse failure than one that answers an aside.
+        reply_expected: data.reply_expected !== false,
         trigger_type: str(trigger.type),
         trigger_entity_id: str(trigger.entity_id),
         reply_surface: surface,
@@ -310,6 +359,8 @@ export function parseRunRequest(data) {
         // No fallback of its own: an absent block is not an error, it is an older
         // server, and `heartbeatPathFor` already knows what to do about that.
         heartbeat_path: str(heartbeat.path),
+        // Same shape, same reasoning, and no fallback at all — see the field.
+        events_path: str(events.path),
         // Accepted both at the top level and nested under `context`, because the
         // server can move them without a CLI release either way — and a published
         // CLI cannot be redeployed to follow.

package/dist/agent/credentials.d.ts

@@ -38,6 +38,11 @@ export interface AgentCredentials {
     events: string[];
     agent: StoredAgent;
     paired_at: string;
+    /**
+     * Label of the brain account (Claude Code / Codex login) this agent runs on
+     * — see `accounts.ts`. Absent means the CLI's own default login.
+     */
+    account?: string;
 }
 /**
  * On-disk credential schema version.

package/dist/agent/events.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Ships what the agent is doing, tool call by tool call, while it does it.
+ *
+ * The heartbeat carries one line every sixty seconds — "using Bash" — which is
+ * enough to prove a run is alive and nothing like enough to show what it is up
+ * to. Newer servers advertise a second path on the run event (`events.path`),
+ * which takes the tool-call lifecycle in small batches and renders it in the
+ * thread exactly as an in-product AI employee's tool calls are rendered.
+ *
+ * Three properties this module is written around:
+ *
+ * * **It never costs the run.** Posting is best-effort bookkeeping: a server
+ *   that answers `404` (built before the path existed), a network that drops,
+ *   a batch that is rejected — each costs at most that batch, never the reply
+ *   and never the completion. Nothing in here throws.
+ * * **Batches, not chatter.** Events are collected for about a second and sent
+ *   together, capped at the server's per-request limit, so a tool-heavy run
+ *   is a trickle of requests rather than one per tool.
+ * * **Nothing is left behind.** {@link ToolEventQueue.flush} is awaited before
+ *   the reply is posted and before the run is completed, so the timeline is
+ *   whole by the time the thread reads "done".
+ */
+import type { ApiOptions } from './api.js';
+import type { ToolEvent } from './contract.js';
+import type { Scheduler } from './heartbeat.js';
+/**
+ * How long events are collected before a batch goes out.
+ *
+ * Long enough that a `tool_use` and its `tool_result` a few hundred
+ * milliseconds later travel together (and land on the same timeline row in one
+ * write), short enough that the thread shows a tool within a moment of it
+ * starting.
+ */
+export declare const TOOL_EVENT_FLUSH_DELAY_MS = 1000;
+/**
+ * Cap on events waiting to be sent.
+ *
+ * A run that fires tools faster than the server accepts them — or against a
+ * server that is briefly unreachable — must not grow without bound for hours.
+ * The oldest are dropped: the server keeps the newest rows anyway, and an end
+ * whose start was dropped still lands as a settled row.
+ */
+export declare const MAX_QUEUED_TOOL_EVENTS = 500;
+/** What a run's stream reader hands its tool events to. */
+export interface ToolEventSink {
+    /** Queue events for the next batch. Never throws; empty input is a no-op. */
+    push(events: ToolEvent[]): void;
+    /** Send everything queued, now, and wait for it. Never rejects. */
+    flush(): Promise<void>;
+}
+export interface ToolEventQueueOptions {
+    api: ApiOptions;
+    /**
+     * Where the batches go — the run event's `events.path`. `undefined` means
+     * the server advertised none (an older server, or a dry run), and every
+     * event is dropped on the floor without a request being made.
+     */
+    path?: string;
+    log: (line: string) => void;
+    /** Defaults to {@link TOOL_EVENT_FLUSH_DELAY_MS}. */
+    delayMs?: number;
+    /** Defaults to an unref'd `setTimeout`. Tests drive the cadence by hand. */
+    scheduler?: Scheduler;
+    /** Prefix for log lines, e.g. `run 01JQ8Z4K2M`. */
+    label?: string;
+}
+/**
+ * Debounced, batched, fail-soft delivery of one run's tool events.
+ *
+ * One instance per run. Delivery stops for good — and the queue empties — on
+ * the first answer that says the server will never take these events: a `404`
+ * (no such endpoint, or a run this credential no longer owns) or a `409` (the
+ * run is already closed). A transient failure drops the batch it happened on
+ * AND everything queued behind it — one request deadline per flush, never
+ * ten — and leaves the queue live for the next push; a run's timeline is
+ * worth a retry of nothing.
+ */
+export declare class ToolEventQueue implements ToolEventSink {
+    private readonly options;
+    private queue;
+    private pending;
+    private inflight;
+    private disabled;
+    private warned;
+    private readonly delayMs;
+    private readonly scheduler;
+    private readonly label;
+    constructor(options: ToolEventQueueOptions);
+    /** Events waiting to be sent. Exposed for assertions. */
+    queued(): number;
+    /** Whether this queue will still make requests. Exposed for assertions. */
+    active(): boolean;
+    push(events: ToolEvent[]): void;
+    flush(): Promise<void>;
+    /**
+     * Stop for good. Called once the run has been reported, so a straggling
+     * timer can't post events for a run the server has already closed.
+     */
+    stop(): void;
+    private arm;
+    private drain;
+    /** One line per run for transient trouble, not one per batch. */
+    private warnOnce;
+}

package/dist/agent/events.js

@@ -0,0 +1,175 @@
+/**
+ * Ships what the agent is doing, tool call by tool call, while it does it.
+ *
+ * The heartbeat carries one line every sixty seconds — "using Bash" — which is
+ * enough to prove a run is alive and nothing like enough to show what it is up
+ * to. Newer servers advertise a second path on the run event (`events.path`),
+ * which takes the tool-call lifecycle in small batches and renders it in the
+ * thread exactly as an in-product AI employee's tool calls are rendered.
+ *
+ * Three properties this module is written around:
+ *
+ * * **It never costs the run.** Posting is best-effort bookkeeping: a server
+ *   that answers `404` (built before the path existed), a network that drops,
+ *   a batch that is rejected — each costs at most that batch, never the reply
+ *   and never the completion. Nothing in here throws.
+ * * **Batches, not chatter.** Events are collected for about a second and sent
+ *   together, capped at the server's per-request limit, so a tool-heavy run
+ *   is a trickle of requests rather than one per tool.
+ * * **Nothing is left behind.** {@link ToolEventQueue.flush} is awaited before
+ *   the reply is posted and before the run is completed, so the timeline is
+ *   whole by the time the thread reads "done".
+ */
+import { describeFailure, postToolEvents } from './api.js';
+import { MAX_TOOL_EVENTS_PER_BATCH } from './contract.js';
+/**
+ * How long events are collected before a batch goes out.
+ *
+ * Long enough that a `tool_use` and its `tool_result` a few hundred
+ * milliseconds later travel together (and land on the same timeline row in one
+ * write), short enough that the thread shows a tool within a moment of it
+ * starting.
+ */
+export const TOOL_EVENT_FLUSH_DELAY_MS = 1_000;
+/**
+ * Cap on events waiting to be sent.
+ *
+ * A run that fires tools faster than the server accepts them — or against a
+ * server that is briefly unreachable — must not grow without bound for hours.
+ * The oldest are dropped: the server keeps the newest rows anyway, and an end
+ * whose start was dropped still lands as a settled row.
+ */
+export const MAX_QUEUED_TOOL_EVENTS = 500;
+const defaultScheduler = (run, ms) => {
+    const timer = setTimeout(run, ms);
+    // Never the reason a process refuses to exit — same rule as the heartbeat.
+    timer.unref?.();
+    return { cancel: () => clearTimeout(timer) };
+};
+/**
+ * Debounced, batched, fail-soft delivery of one run's tool events.
+ *
+ * One instance per run. Delivery stops for good — and the queue empties — on
+ * the first answer that says the server will never take these events: a `404`
+ * (no such endpoint, or a run this credential no longer owns) or a `409` (the
+ * run is already closed). A transient failure drops the batch it happened on
+ * AND everything queued behind it — one request deadline per flush, never
+ * ten — and leaves the queue live for the next push; a run's timeline is
+ * worth a retry of nothing.
+ */
+export class ToolEventQueue {
+    options;
+    queue = [];
+    pending;
+    inflight;
+    disabled;
+    warned = false;
+    delayMs;
+    scheduler;
+    label;
+    constructor(options) {
+        this.options = options;
+        this.disabled = !options.path;
+        this.delayMs = options.delayMs ?? TOOL_EVENT_FLUSH_DELAY_MS;
+        this.scheduler = options.scheduler ?? defaultScheduler;
+        this.label = options.label ?? 'run';
+    }
+    /** Events waiting to be sent. Exposed for assertions. */
+    queued() {
+        return this.queue.length;
+    }
+    /** Whether this queue will still make requests. Exposed for assertions. */
+    active() {
+        return !this.disabled;
+    }
+    push(events) {
+        if (this.disabled || events.length === 0)
+            return;
+        this.queue.push(...events);
+        if (this.queue.length > MAX_QUEUED_TOOL_EVENTS) {
+            this.queue.splice(0, this.queue.length - MAX_QUEUED_TOOL_EVENTS);
+        }
+        this.arm();
+    }
+    async flush() {
+        this.pending?.cancel();
+        this.pending = undefined;
+        // A batch already on the wire finishes first; anything queued behind it
+        // goes out in the drain that follows.
+        if (this.inflight)
+            await this.inflight;
+        if (this.disabled || this.queue.length === 0)
+            return;
+        this.inflight = this.drain().finally(() => {
+            this.inflight = undefined;
+        });
+        await this.inflight;
+    }
+    /**
+     * Stop for good. Called once the run has been reported, so a straggling
+     * timer can't post events for a run the server has already closed.
+     */
+    stop() {
+        this.disabled = true;
+        this.queue = [];
+        this.pending?.cancel();
+        this.pending = undefined;
+    }
+    arm() {
+        if (this.disabled || this.pending || this.inflight)
+            return;
+        this.pending = this.scheduler(() => {
+            this.pending = undefined;
+            void this.flush();
+        }, this.delayMs);
+    }
+    async drain() {
+        const path = this.options.path;
+        if (!path)
+            return;
+        while (this.queue.length > 0 && !this.disabled) {
+            const batch = this.queue.splice(0, MAX_TOOL_EVENTS_PER_BATCH);
+            let result;
+            try {
+                result = await postToolEvents(this.options.api, path, batch);
+            }
+            catch (err) {
+                this.warnOnce(`threw: ${err instanceof Error ? err.message : String(err)}`);
+                this.queue = [];
+                return;
+            }
+            if (result.ok)
+                continue;
+            if (result.status === 404) {
+                // Said once, then silence — this is every older server's answer.
+                this.disabled = true;
+                this.queue = [];
+                this.options.log(`    ◦ ${this.label} tool events cannot be reported (HTTP 404) — this ProhostAI ` +
+                    'server has no tool-events endpoint, or no longer knows this run. The thread ' +
+                    'will show only the heartbeat line.');
+                return;
+            }
+            if (result.status === 409) {
+                // The run is over server-side; nothing left to narrate.
+                this.disabled = true;
+                this.queue = [];
+                return;
+            }
+            // Transient, by assumption — but not retried, and not pushed through
+            // either. The final flush is awaited before the reply goes out, so a
+            // dead endpoint with ten batches queued behind it would otherwise hold
+            // the finished agent for ten request deadlines. Drop what is queued,
+            // keep the queue live for whatever comes next.
+            this.warnOnce(`failed (${describeFailure(result)})${result.status !== 0 && result.error ? ` ${result.error}` : ''}`);
+            this.queue = [];
+            return;
+        }
+    }
+    /** One line per run for transient trouble, not one per batch. */
+    warnOnce(detail) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        this.options.log(`    ! reporting tool events for ${this.label} ${detail} — continuing without them`);
+    }
+}

package/dist/agent/list.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `prohost agent list` — every paired agent on this machine, and the accounts
+ * they can run on.
+ *
+ * An agent is an agent home (`$PROHOST_HOME`). They are found in three places:
+ * the default `~/.prohost`, the `$PROHOST_HOME` of this shell, and every home a
+ * `ai.prohost.agent.*` launchd plist pins — which is how agents installed as
+ * daemons from other shells are found at all.
+ *
+ * Read-only, and nothing secret is printed: an agent's name, its account
+ * label, and whether its daemon / a harness is running.
+ */
+import type { CommandRunner } from './accounts.js';
+export interface AgentHomeInfo {
+    home: string;
+    /** Agent name from `agent.json`; `undefined` when the home is not paired. */
+    name?: string;
+    account: string;
+    /** From the daemon's `--exec`, when a daemon names one. */
+    exec?: string;
+    daemon: 'running' | 'installed' | 'not installed';
+    /** A live `agent run` holding the home's run lock. */
+    runPid?: number;
+}
+/** `PROHOST_HOME` and the `--exec` value from one of our plists. */
+export declare function parsePlist(xml: string): {
+    home?: string;
+    exec?: string;
+};
+export interface ListOptions {
+    env?: NodeJS.ProcessEnv;
+    /** `~/Library/LaunchAgents`, overridable for tests. */
+    launchAgentsDir?: string;
+    /** Returns whether launchd reports the label as running. */
+    daemonRunning?: (label: string) => boolean;
+    run?: CommandRunner;
+}
+/** Every agent home this machine knows about, de-duplicated by resolved path. */
+export declare function findAgentHomes(options?: ListOptions): AgentHomeInfo[];
+/** Render `agent list`. */
+export declare function renderAgentList(options?: ListOptions): Promise<string[]>;

package/dist/agent/list.js

@@ -0,0 +1,126 @@
+/**
+ * `prohost agent list` — every paired agent on this machine, and the accounts
+ * they can run on.
+ *
+ * An agent is an agent home (`$PROHOST_HOME`). They are found in three places:
+ * the default `~/.prohost`, the `$PROHOST_HOME` of this shell, and every home a
+ * `ai.prohost.agent.*` launchd plist pins — which is how agents installed as
+ * daemons from other shells are found at all.
+ *
+ * Read-only, and nothing secret is printed: an agent's name, its account
+ * label, and whether its daemon / a harness is running.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_ACCOUNT_LABEL, checkAuth, loadAccounts, runtimeName } from './accounts.js';
+import { tryLoadCredentials } from './credentials.js';
+import { LAUNCHD_LABEL_PREFIX, launchdLabel } from './daemon.js';
+import { pidAlive, readRunLock } from './lock.js';
+function xmlUnescape(value) {
+    return value
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+/** `PROHOST_HOME` and the `--exec` value from one of our plists. */
+export function parsePlist(xml) {
+    const home = /<key>PROHOST_HOME<\/key>\s*<string>([^<]*)<\/string>/.exec(xml)?.[1];
+    const args = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(xml)?.[1] ?? '';
+    const words = [...args.matchAll(/<string>([^<]*)<\/string>/g)].map((m) => xmlUnescape(m[1] ?? ''));
+    const execIndex = words.indexOf('--exec');
+    return {
+        home: home === undefined ? undefined : xmlUnescape(home),
+        exec: execIndex >= 0 ? words[execIndex + 1] : undefined,
+    };
+}
+function defaultDaemonRunning(label) {
+    if (os.platform() !== 'darwin')
+        return false;
+    const uid = process.getuid?.() ?? 0;
+    const result = spawnSync('launchctl', ['print', `gui/${uid}/${label}`], { encoding: 'utf8', timeout: 5_000 });
+    return result.status === 0 && /^\s*state = running$/m.test(result.stdout ?? '');
+}
+/** Every agent home this machine knows about, de-duplicated by resolved path. */
+export function findAgentHomes(options = {}) {
+    const env = options.env ?? process.env;
+    const userHome = env.HOME || os.homedir();
+    const plistDir = options.launchAgentsDir ?? path.join(userHome, 'Library', 'LaunchAgents');
+    const daemonRunning = options.daemonRunning ?? defaultDaemonRunning;
+    const homes = new Map();
+    const add = (home, extra = {}) => {
+        const key = path.resolve(home);
+        const known = homes.get(key);
+        homes.set(key, { exec: extra.exec ?? known?.exec, plist: Boolean(extra.plist || known?.plist) });
+    };
+    add(path.join(userHome, '.prohost'));
+    if (env.PROHOST_HOME)
+        add(env.PROHOST_HOME);
+    let plists = [];
+    try {
+        plists = readdirSync(plistDir).filter((f) => f.startsWith(`${LAUNCHD_LABEL_PREFIX}.`) && f.endsWith('.plist'));
+    }
+    catch {
+        plists = [];
+    }
+    for (const file of plists) {
+        try {
+            const parsed = parsePlist(readFileSync(path.join(plistDir, file), 'utf8'));
+            if (parsed.home)
+                add(parsed.home, { exec: parsed.exec, plist: true });
+        }
+        catch {
+            /* unreadable plist — skip */
+        }
+    }
+    const found = [];
+    for (const [home, meta] of homes) {
+        const credentials = tryLoadCredentials({ ...env, PROHOST_HOME: home });
+        // The default home is listed only when something is actually there.
+        if (!credentials && !meta.plist && !existsSync(home))
+            continue;
+        const label = launchdLabel(home);
+        const lock = readRunLock({ ...env, PROHOST_HOME: home });
+        found.push({
+            home,
+            name: credentials?.agent?.name,
+            account: credentials?.account ?? DEFAULT_ACCOUNT_LABEL,
+            exec: meta.exec,
+            daemon: meta.plist ? (daemonRunning(label) ? 'running' : 'installed') : 'not installed',
+            runPid: lock && pidAlive(lock.pid) ? lock.pid : undefined,
+        });
+    }
+    return found;
+}
+function authText(check) {
+    return check.state === 'ok' ? 'signed in' : check.state === 'expired' ? 'signed out' : 'unknown';
+}
+/** Render `agent list`. */
+export async function renderAgentList(options = {}) {
+    const env = options.env ?? process.env;
+    const lines = [];
+    const agents = findAgentHomes(options);
+    lines.push('Agents');
+    if (agents.length === 0)
+        lines.push('  (none paired on this machine — prohost agent pair --code <code>)');
+    for (const agent of agents) {
+        const running = agent.runPid ? `running (pid ${agent.runPid})` : `daemon ${agent.daemon}`;
+        lines.push(`  ${agent.name ?? '(not paired)'}  ·  account ${agent.account}  ·  ${running}`);
+        lines.push(`      home ${agent.home}${agent.exec ? `  ·  exec ${agent.exec}` : ''}`);
+    }
+    const accounts = loadAccounts(env);
+    lines.push('', 'Accounts');
+    if (accounts.length === 0) {
+        lines.push('  (only the default logins — prohost agent account add <label> --runtime claude|codex)');
+    }
+    const checks = await Promise.all(accounts.map((a) => checkAuth(a, { run: options.run })));
+    accounts.forEach((account, i) => {
+        const users = agents.filter((a) => a.account === account.label).map((a) => a.name ?? a.home);
+        lines.push(`  ${account.label}  ·  ${runtimeName(account.runtime)}  ·  ${account.billing}  ·  ${authText(checks[i])}` +
+            (users.length > 0 ? `  ·  used by ${users.join(', ')}` : ''));
+    });
+    return lines;
+}

package/dist/agent/lock.d.ts

@@ -0,0 +1,37 @@
+/**
+ * One `agent run` per agent home.
+ *
+ * Two harnesses on the same `$PROHOST_HOME` share one credential, one run
+ * ledger and one session store, and both receive every run — so both execute
+ * it. That happens easily: a daemon is installed and the operator also starts
+ * `agent run` in a terminal to watch it. `$PROHOST_HOME/run.lock` makes the
+ * second one refuse to start, with the pid it lost to.
+ *
+ * Created with `O_EXCL`, holding the owner's pid and start time. A lock whose
+ * pid is no longer alive was left by a crash (or `kill -9`) and is taken over.
+ */
+export interface LockHolder {
+    pid: number;
+    started_at: string;
+}
+export type LockResult = {
+    ok: true;
+    release: () => void;
+} | {
+    ok: false;
+    holder: LockHolder;
+};
+export declare function runLockPath(env?: NodeJS.ProcessEnv): string;
+/** Whether a pid names a live process. EPERM means it exists but isn't ours. */
+export declare function pidAlive(pid: number): boolean;
+/** The current holder, if the lock file exists and is readable. */
+export declare function readRunLock(env?: NodeJS.ProcessEnv): LockHolder | undefined;
+/**
+ * Take the home's run lock, or report who holds it.
+ *
+ * @param isAlive Liveness check seam for tests.
+ */
+export declare function acquireRunLock(env?: NodeJS.ProcessEnv, options?: {
+    pid?: number;
+    isAlive?: (pid: number) => boolean;
+}): LockResult;