@prohost/cli 0.15.0 → 0.16.0

package/dist/agent/run.d.ts

@@ -30,9 +30,12 @@ import type { spawn } from 'node:child_process';
 import WebSocket from 'ws';
 import { HarnessAccount } from './account_runtime.js';
 import type { CommandRunner } from './accounts.js';
+import type { ApiOptions, ApiResult } from './api.js';
+import type { AgentRunRequest } from './contract.js';
 import type { AgentCredentials } from './credentials.js';
 import type { RunCapabilities } from './capabilities.js';
 import type { QuotaProvider } from './runtime_status.js';
+import { SessionStore } from './sessionstore.js';
 import type { CodeHostLike } from '../codehost/host.js';
 import type { AccountEnvResult, CodeAgent } from '../codehost/terminals.js';
 /**
@@ -196,6 +199,39 @@ export interface AgentRunOptions {
      * `null` never hosts. Tests inject a fake.
      */
     codeHost?: CodeHostLike | null;
+    /**
+     * `prohost host` only. Where this run's strict Claude MCP config is written,
+     * instead of `$PROHOST_HOME/mcp.json`: the key in it is the run's own token.
+     */
+    mcpConfigFile?: string;
+    /** `prohost host` only: said near the top of the prompt (see `PromptContext.resumeNote`). */
+    resumeNote?: string;
+    /**
+     * `prohost host` only: a turn stopped by the login's usage limit is handed
+     * back to the caller (`usage_limited`) instead of being completed, so the
+     * run can resume on another login of the same kind.
+     */
+    deferUsageLimit?: boolean;
+    /**
+     * `prohost host` only: variables for this run's command alone (a dedicated
+     * install's Claude token), read at each run so a rotation applies. A Claude
+     * Code harness also gives them to its sign-in and usage probes.
+     */
+    extraEnv?: NodeJS.ProcessEnv | (() => NodeJS.ProcessEnv);
+    /** `prohost host` only: skip the per-harness start-up lines (the host says them once). */
+    quietStartup?: boolean;
+    /**
+     * `prohost host` only: the server's send rule applies to this run's replies.
+     * The agent is asked to end a reply with {@link confidenceTrailer}; it is
+     * stripped, and `confidence` / `reply_class` go with the send.
+     */
+    replyConfidence?: boolean;
+    /**
+     * `prohost host` only: the employee's one session ledger, shared by its
+     * runs. Each run loading its own would let two overlapping conversations
+     * overwrite each other's entry when they persist.
+     */
+    sessions?: SessionStore;
 }
 export interface AgentRunMetrics {
     connections: number;
@@ -218,6 +254,53 @@ export interface AgentRunMetrics {
      */
     fatal?: string;
 }
+/**
+ * What one run amounted to.
+ *
+ * * ``succeeded`` / ``failed`` — the server accepted a terminal state. Settled.
+ * * ``cancelled`` — somebody pressed stop; the run was reported ``failed`` with
+ *   the marker error the server words as a cancellation. Settled.
+ * * ``resolved`` — the server had already closed the run out (it was reaped, or
+ *   finished elsewhere). Nothing was posted and nothing was reported, because
+ *   there is no longer anything to report to. Settled all the same.
+ * * ``unreported`` — the work is done but the completion never landed. The run
+ *   stays open in the ledger so a redelivery can report it without re-running
+ *   the agent.
+ * * ``skipped`` — a dry run. No writes were made, so it is neither a success
+ *   nor a failure and must not be counted as either.
+ */
+type RunOutcome = 'succeeded' | 'failed' | 'cancelled' | 'resolved' | 'unreported' | 'skipped';
+/**
+ * A send the server answered without sending, deliberately: `held_as_suggestion`
+ * (saved as a draft for the team — the send rule) or `ai_muted` (the thread is
+ * muted; nothing saved, nothing to retry). Either way the run is done.
+ */
+export declare function isHeldAsSuggestion(result: ApiResult): boolean;
+/**
+ * A reply without its confidence trailer (`[[confidence=0.9 reply_class=general]]`,
+ * see `replyConfidence`), and what the last one said. Every trailer is removed,
+ * wherever the model put it and however it dressed it, even one that can't be
+ * read: none may reach a guest. A line left with nothing else on it goes too.
+ */
+export declare function splitConfidence(reply: string): {
+    text: string;
+    confidence?: number;
+    replyClass?: string;
+};
+/**
+ * Why a run stopped early, when it stopped because something outside said so —
+ * or, for `expired`, because a venue run's grant is about to end.
+ */
+type Disposition = 'cancelled' | 'resolved' | 'expired';
+/** What a run in flight can see, and say, about being stopped. */
+interface RunControl {
+    /** Fires when the run must stop — cancelled, or closed server-side. */
+    signal: AbortSignal;
+    /** Why it was stopped, once it was. */
+    disposition(): Disposition | undefined;
+    /** Publish what the agent is doing, for the next heartbeat to carry. */
+    report(activity: string): void;
+}
 interface PreparedMcp {
     /** Claude Code: path of the strict generated MCP config. */
     mcpConfigPath?: string;
@@ -258,4 +341,30 @@ export declare function codexMcpEntryProvider(options: AgentRunOptions, log: (li
  */
 export declare function codeThreadAccountEnv(account: HarnessAccount | undefined, agent: CodeAgent): AccountEnvResult;
 export declare function runAgentHarness(options: AgentRunOptions): Promise<AgentRunMetrics>;
-export {};
+/** What one run executed for `prohost host` came to. */
+export interface HostedRunResult {
+    /**
+     * As `agent run` settles a run, plus `usage_limited`: the login's usage limit
+     * stopped the turn and nothing was reported (see `deferUsageLimit`).
+     */
+    outcome: RunOutcome | 'usage_limited';
+    /** When the limit lifts (ISO), for a `usage_limited` turn whose brain said. */
+    retryAfter?: string;
+    /** The model the run used, as far as the harness learnt. */
+    model?: string;
+}
+/**
+ * Execute one run that `prohost host` has already claimed, the way
+ * `agent run` executes one it accepted: the same prompt, Claude Code / Codex
+ * shaping, session continuity, tool events, reply and completion.
+ *
+ * `options.credentials.api_key` is the run's own token, and `options.env`
+ * points `PROHOST_HOME` at the employee's home (its sessions and workspace).
+ * Heartbeats, cancellation and the queue belong to the caller, which hands
+ * the outcome of each to `control`.
+ */
+export declare function executeHostedRun(run: AgentRunRequest, options: AgentRunOptions, control: RunControl, isolation: {
+    lane: string;
+    parallel: boolean;
+}, api: ApiOptions): Promise<HostedRunResult>;
+export type { RunControl as HostedRunControl, RunOutcome as HostedRunOutcome };

package/dist/agent/run.js

@@ -33,6 +33,7 @@ import { spawnSync } from 'node:child_process';
 import WebSocket from 'ws';
 import { HarnessAccount } from './account_runtime.js';
 import { EVENT_AGENT_CONFIG_UPDATED, accountEnv, machineId } from './accounts.js';
+import { defaultCommandRunner } from './accounts.js';
 import { completeRun, describeFailure, isIdempotencyInFlight, postReply } from './api.js';
 import { MAX_SALVAGE_CHARS, claudeCommand, isClaudeExec, looksLikeResumeFailure, readClaudeStream, writeMcpConfig, } from './claude.js';
 import { APPS_FEATURE, MCP_API_KEY_ENV_VAR, PLUGINS_DISABLED_OVERRIDE, codexBinary, codexCommand, codexMcpInventoryFlag, codexProfileName, codexShellSyntax, extraMcpEntries, isCodexExec, isolateConfiguredServers, listMcpServers, mcpServersOverride, prohostMcpEntry, codexFailureMessage, looksLikeCodexResumeFailure, parseCodexOutput, } from './codex.js';
@@ -208,6 +209,17 @@ const REPLAY_IN_FLIGHT_DELAY_MS = 5_000;
  *   answer, and the run is reported failed exactly once.
  */
 async function postReplyWithReplay(api, send, label, log, sleep) {
+    const result = await postReplyOnce(api, send, label, log, sleep);
+    // The send rule kept it as a suggestion for the team: handled, not failed.
+    if (isHeldAsSuggestion(result)) {
+        log(/ai_muted/.test(result.error ?? '')
+            ? `${timestamp()} ◦ ${label} reply was not sent: the thread is muted for AI`
+            : `${timestamp()} ◦ ${label} reply was held as a suggestion for the team (the employee's send rule)`);
+        return { ...result, ok: true };
+    }
+    return result;
+}
+async function postReplyOnce(api, send, label, log, sleep) {
     let posted = await send();
     // A real answer — success or a decision — is final. Only "no answer at all"
     // earns a replay.
@@ -258,6 +270,77 @@ function resolveWorkdir(options, log) {
         return undefined;
     }
 }
+/**
+ * A send the server answered without sending, deliberately: `held_as_suggestion`
+ * (saved as a draft for the team — the send rule) or `ai_muted` (the thread is
+ * muted; nothing saved, nothing to retry). Either way the run is done.
+ */
+export function isHeldAsSuggestion(result) {
+    return result.status === 409 && /held_as_suggestion|ai_muted/.test(result.error ?? '');
+}
+/** The run's extra variables, resolved now. */
+function extraEnvOf(options) {
+    return typeof options.extraEnv === 'function' ? options.extraEnv() : (options.extraEnv ?? {});
+}
+/** A line that is the confidence trailer, however the model dressed it (backticks, bold, commas, quotes). */
+/** A trailer token anywhere, with any decoration hugging it. */
+const TRAILER_TOKEN = /[`*_]*\[\[\s*confidence\b[^\]]*\]\][`*_]*\.?/gi;
+/** The confidence a trailer states: a plain decimal from 0 to 1, read whole — anything else is no confidence. */
+function trailerConfidence(token) {
+    const raw = /confidence\s*[=:]\s*["']?([^\s,"'\]]+)/i.exec(token)?.[1];
+    if (!raw || !/^(?:0|1|0?\.\d+|1\.0+|0\.\d+)$/.test(raw))
+        return undefined;
+    const value = Number(raw);
+    return value >= 0 && value <= 1 ? value : undefined;
+}
+/**
+ * A reply without its confidence trailer (`[[confidence=0.9 reply_class=general]]`,
+ * see `replyConfidence`), and what the last one said. Every trailer is removed,
+ * wherever the model put it and however it dressed it, even one that can't be
+ * read: none may reach a guest. A line left with nothing else on it goes too.
+ */
+export function splitConfidence(reply) {
+    const tokens = [...reply.matchAll(TRAILER_TOKEN)];
+    if (tokens.length === 0)
+        return { text: reply };
+    const last = tokens[tokens.length - 1][0];
+    // Whole tokens first (one may wrap onto the next line), marked; then a line
+    // left with nothing but a mark and decoration goes.
+    const MARK = '\u0000';
+    const text = reply
+        .replace(TRAILER_TOKEN, MARK)
+        .split('\n')
+        .flatMap((line) => {
+        if (!line.includes(MARK))
+            return [line];
+        const cleaned = line.split(MARK).join('').replace(/[ \t]+$/, '');
+        return /^[\s`*_>.]*$/.test(cleaned) ? [] : [cleaned];
+    })
+        .join('\n')
+        .replace(/\s+$/, '');
+    const confidence = trailerConfidence(last);
+    const replyClass = /reply_class\s*[=:]\s*["']?([A-Za-z_]{1,40})/i.exec(last)?.[1]?.toLowerCase();
+    if (confidence === undefined)
+        return { text };
+    return { text, confidence, ...(replyClass ? { replyClass } : {}) };
+}
+/** The send extras for one answer: the run's own, plus what its trailer said. */
+function shapeAnswer(answer, extra, on) {
+    if (!on)
+        return { text: answer, extra };
+    const shaped = splitConfidence(answer);
+    return {
+        text: shaped.text,
+        extra: shaped.confidence !== undefined
+            ? { ...extra, confidence: shaped.confidence, ...(shaped.replyClass ? { reply_class: shaped.replyClass } : {}) }
+            : extra,
+    };
+}
+/**
+ * A Codex turn its usage limit stopped. Codex says so in its own words on a
+ * failed turn; only `prohost host` acts on it (`deferUsageLimit`).
+ */
+const CODEX_USAGE_LIMIT = /usage limit|usage_limit_reached|hit your limit/i;
 /**
  * The lane a run waits on: runs sharing one never overlap.
  *
@@ -278,7 +361,7 @@ function laneFor(run) {
  */
 function buildRuntime(options, log) {
     const workdir = resolveWorkdir(options, log);
-    const sessions = SessionStore.load(options.env, log);
+    const sessions = options.sessions ?? SessionStore.load(options.env, log);
     const brain = isClaudeExec(options.exec)
         ? 'claude'
         : isCodexExec(options.exec)
@@ -307,11 +390,15 @@ function buildRuntime(options, log) {
         env: options.env,
         initialLabel: options.credentials.account,
         binary: brain === 'claude' ? (options.exec.trim().split(/\s+/)[0] ?? 'claude') : codexBinary(options.exec),
-        run: options.accountCommandRunner,
+        // A Claude harness's sign-in check sees the run's extra variables too (the Claude token).
+        run: brain === 'claude' && options.extraEnv
+            ? (command, args, env) => (options.accountCommandRunner ?? defaultCommandRunner)(command, args, { ...env, ...extraEnvOf(options) })
+            : options.accountCommandRunner,
         warn: (message) => log(`${timestamp()} ! ${message}`),
     });
     const mcpUrl = options.credentials.mcp_url;
     let announced = '';
+    const quiet = options.quietStartup === true;
     const announce = (lines) => {
         const message = lines.join('\n');
         if (message === announced)
@@ -320,7 +407,7 @@ function buildRuntime(options, log) {
             log(line);
         announced = message;
     };
-    if (!mcpUrl) {
+    if (!mcpUrl && !quiet) {
         log(`${timestamp()} ! this pairing carries no MCP endpoint; the agent will run without ProhostAI tools`);
     }
     const prepareMcp = brain === 'claude'
@@ -336,6 +423,7 @@ function buildRuntime(options, log) {
                     apiKey: options.credentials.api_key,
                     extraServers: extras.servers,
                     env: options.env,
+                    ...(options.mcpConfigFile ? { file: options.mcpConfigFile } : {}),
                 });
                 return { mcpConfigPath, mcpWired: Boolean(mcpUrl) };
             }
@@ -350,19 +438,21 @@ function buildRuntime(options, log) {
         : codexMcpEntryProvider(options, log, workdir, () => account.spawnEnv());
     const tools = mcpUrl ? `, ProhostAI tools prepared per run as ${MCP_SERVER_NAME}` : '';
     const where = workdir ? ` (workspace: ${workdir})` : '';
-    log(brain === 'claude'
-        ? `${timestamp()} ⚙ Claude Code detected — resuming a session per conversation${tools}${where}`
-        : `${timestamp()} ⚙ Codex detected — resuming a thread per conversation${tools}${where}`);
+    if (!quiet)
+        log(brain === 'claude'
+            ? `${timestamp()} ⚙ Claude Code detected — resuming a session per conversation${tools}${where}`
+            : `${timestamp()} ⚙ Codex detected — resuming a thread per conversation${tools}${where}`);
     // Said out loud every start-up, not buried in --help. This is the line that
     // tells an operator their machine will run tool calls, unprompted, on text
     // written by someone else in their workspace.
     const bypassFlag = brain === 'claude' ? '--dangerously-skip-permissions' : '--yolo';
-    log(skipPermissions
-        ? `${timestamp()} ⚠ tools run WITHOUT permission prompts ` +
-            `(${bypassFlag}). The agent acts as you, with your local ` +
-            'access, on instructions from your workspace. Use --safe-tools to gate them.'
-        : `${timestamp()} ⚙ --safe-tools: tools are permission-gated; anything needing ` +
-            'approval will not run (nobody is at a terminal to approve it).');
+    if (!quiet)
+        log(skipPermissions
+            ? `${timestamp()} ⚠ tools run WITHOUT permission prompts ` +
+                `(${bypassFlag}). The agent acts as you, with your local ` +
+                'access, on instructions from your workspace. Use --safe-tools to gate them.'
+            : `${timestamp()} ⚙ --safe-tools: tools are permission-gated; anything needing ` +
+                'approval will not run (nobody is at a terminal to approve it).');
     // The account is resolved before anything is prepared or spawned, and its
     // environment rides every spawn of this run. A missing account fails the
     // run closed, the same way an unprovable MCP boundary does.
@@ -377,7 +467,8 @@ function buildRuntime(options, log) {
             accountLabel: resolved.record.label,
         };
     };
-    log(`${timestamp()} ⚙ account: ${account.label()}`);
+    if (!quiet)
+        log(`${timestamp()} ⚙ account: ${account.label()}`);
     return {
         workdir,
         sessions,
@@ -884,6 +975,16 @@ onEarlyAnswer) {
     // the ledger can't know. One retry without it, because the alternative is a
     // surface that fails every run forever over an optimisation.
     const resumeFailed = codex ? looksLikeCodexResumeFailure : looksLikeResumeFailure;
+    /**
+     * A Codex turn its usage limit stopped may already have acted. For
+     * `prohost host` (which moves the thread to another login) its thread is
+     * remembered, so the next login continues it rather than starting over.
+     */
+    const keepCodexThreadOnLimit = (threadId, said) => {
+        if (!options.deferUsageLimit || !sessionKey || !threadId || !CODEX_USAGE_LIMIT.test(said))
+            return;
+        runtime.sessions.remember(sessionKey, threadId);
+    };
     if (!result.ok &&
         sessionId &&
         // A usage limit fails a fresh session exactly as it failed this one, and
@@ -911,6 +1012,8 @@ onEarlyAnswer) {
         if (!result.timedOut && !result.idleTimedOut && !result.cancelled && !stream?.usageLimit()) {
             forgetRecordedSession();
         }
+        if (codex)
+            keepCodexThreadOnLimit(parseCodexOutput(result.stdout).sessionId, `${codexFailureMessage(result.stdout) ?? ''}\n${result.stderr}`);
         return failure(result);
     }
     // A denied tool is not an error either brain reports — the turn succeeds and
@@ -929,6 +1032,7 @@ onEarlyAnswer) {
         runtime.observe(readCodexObservation(output.sessionId, { ...process.env, ...options.env, ...runtime.account?.spawnEnv() }));
         reportDenials(output.denials);
         if (!output.ok) {
+            keepCodexThreadOnLimit(output.sessionId, output.error ?? '');
             return {
                 ok: false,
                 reason: 'the agent did not produce a usable reply',
@@ -977,7 +1081,9 @@ onEarlyAnswer) {
  */
 async function handleRun(run, options, runtime, api, log, sleep, control, isolation, 
 /** Prepared by the caller, which also hands the run's account back. */
-mcp) {
+mcp, 
+/** Filled for a turn handed back as `usage_limited` (see `deferUsageLimit`). */
+limited) {
     const label = `run ${run.run_id.slice(0, 12)}`;
     const surface = run.conversation_id ?? run.kind ?? 'no conversation';
     // Answered with the run's own token, by a session with no tools and none of
@@ -1020,6 +1126,8 @@ mcp) {
         parallel: isolation.parallel,
         checkouts: checkouts?.checkouts,
         checkoutFailures: checkouts?.failures,
+        ...(options.resumeNote ? { resumeNote: options.resumeNote } : {}),
+        ...(options.replyConfidence && run.reply_surface === 'conversation' ? { askConfidence: true } : {}),
     });
     // Tool-call narration for the thread. A dry run makes no writes, so it gets
     // no path and every event is dropped; so does a server that advertised none.
@@ -1029,7 +1137,7 @@ mcp) {
         log,
         label,
     });
-    const runEnv = { [PAIRED_RUN_ENV_VAR]: '1' };
+    const runEnv = { ...extraEnvOf(options), [PAIRED_RUN_ENV_VAR]: '1' };
     if (checkouts && checkouts.checkouts.length > 0)
         runEnv[RUN_REPOS_ENV_VAR] = checkouts.dir;
     // The last moment before the agent starts: a venue run that waited in the
@@ -1081,7 +1189,10 @@ mcp) {
             const { answer, key } = early[0];
             const posted = await postReplyWithReplay(api, () => stoppedNow()
                 ? Promise.resolve({ ok: false, status: -1, error: 'the run was stopped' })
-                : postReply(api, earlyPath, earlyBodyKey, answer, key, run.reply_body_extra), label, log, sleep);
+                : (() => {
+                    const shaped = shapeAnswer(answer, run.reply_body_extra, options.replyConfidence);
+                    return postReply(api, earlyPath, earlyBodyKey, shaped.text, key, shaped.extra);
+                })(), label, log, sleep);
             if (!posted.ok) {
                 if (!stoppedNow())
                     log(`${timestamp()} ! ${label} could not post an answer yet (${describeFailure(posted)})`);
@@ -1159,6 +1270,18 @@ mcp) {
         }
         return 'cancelled';
     }
+    if (!result.ok && options.deferUsageLimit && !options.dryRun && !venue) {
+        const usageLimit = result.usageLimit ??
+            (runtime.brain === 'codex' && CODEX_USAGE_LIMIT.test(`${result.reason}\n${result.detail ?? ''}`) ? {} : undefined);
+        if (usageLimit) {
+            // Not completed: the caller moves the conversation to another login of
+            // the same kind, or completes it with this limit itself.
+            log(`${timestamp()} ⏸ ${label} hit this login's usage limit after ${seconds}s`);
+            if (limited && usageLimit.retryAfter)
+                limited.retryAfter = usageLimit.retryAfter;
+            return 'usage_limited';
+        }
+    }
     if (!result.ok) {
         const { reason } = result;
         // A venue run's detail is stderr and the agent's unfinished answer — the
@@ -1183,7 +1306,9 @@ mcp) {
         }
         return 'failed';
     }
-    const { reply } = result;
+    const shaped = shapeAnswer(result.reply, run.reply_body_extra, options.replyConfidence);
+    const reply = shaped.text;
+    const sendExtra = shaped.extra;
     if (options.dryRun) {
         const destination = run.reply_surface === 'none' ? '(no reply surface)' : `${run.reply_surface} ${run.reply_path}`;
         log(`${timestamp()} ◦ ${label} dry-run — would post to ${destination}:`);
@@ -1249,7 +1374,7 @@ mcp) {
     }
     const replyPath = run.reply_path;
     const replyBodyKey = run.reply_body_key;
-    const posted = await postReplyWithReplay(api, () => postReply(api, replyPath, replyBodyKey, reply, run.run_id, run.reply_body_extra), label, log, sleep);
+    const posted = await postReplyWithReplay(api, () => postReply(api, replyPath, replyBodyKey, reply, run.run_id, sendExtra), label, log, sleep);
     if (!posted.ok) {
         const failure = describeFailure(posted);
         // The server's reason can quote the thread (a reply-race refusal previews
@@ -1400,7 +1525,10 @@ export async function runAgentHarness(options) {
     const status = new RuntimeStatusReporter({
         runtime: runtime.runtimeName,
         provider: options.quotaProvider === undefined
-            ? defaultQuotaProvider(runtime.brain, options.exec, () => runtime.account?.spawnEnv() ?? {})
+            ? defaultQuotaProvider(runtime.brain, options.exec, () => ({
+                ...runtime.account?.spawnEnv(),
+                ...(runtime.brain === 'claude' ? extraEnvOf(options) : {}),
+            }))
             : (options.quotaProvider ?? undefined),
         accounts: runtime.account
             ? (known) => runtime.account.snapshot([...accepted.values()].some((entry) => entry.executing), known)
@@ -2179,3 +2307,42 @@ export async function runAgentHarness(options) {
         });
     }
 }
+/**
+ * Execute one run that `prohost host` has already claimed, the way
+ * `agent run` executes one it accepted: the same prompt, Claude Code / Codex
+ * shaping, session continuity, tool events, reply and completion.
+ *
+ * `options.credentials.api_key` is the run's own token, and `options.env`
+ * points `PROHOST_HOME` at the employee's home (its sessions and workspace).
+ * Heartbeats, cancellation and the queue belong to the caller, which hands
+ * the outcome of each to `control`.
+ */
+export async function executeHostedRun(run, options, control, isolation, api) {
+    const log = options.onLine ?? ((line) => process.stdout.write(`${line}\n`));
+    const sleep = options.sleepImpl ?? defaultSleep;
+    const runtime = buildRuntime(options, log);
+    const worktrees = new WorktreeManager({ repos: options.repos ?? [], env: options.env, log });
+    let mcp;
+    try {
+        mcp = runtime.prepareMcp();
+    }
+    catch (err) {
+        mcp = { mcpWired: false, error: `could not prepare the run (${String(err)})` };
+    }
+    const limited = {};
+    try {
+        const outcome = await handleRun(run, options, runtime, api, log, sleep, control, { lane: isolation.lane, parallel: isolation.parallel, worktrees }, mcp, limited).catch((err) => {
+            log(`${timestamp()} ✗ run ${run.run_id} crashed the run handler: ${String(err)}`);
+            return 'failed';
+        });
+        return {
+            outcome,
+            ...(outcome === 'usage_limited' && limited.retryAfter ? { retryAfter: limited.retryAfter } : {}),
+            model: runtime.model(),
+        };
+    }
+    finally {
+        if (mcp.accountLabel !== undefined)
+            runtime.account?.finishSpawn(mcp.accountLabel);
+    }
+}

package/dist/codehost/host.d.ts

@@ -93,6 +93,18 @@ export interface CodeHostLike {
      * (`agents.ts`), re-checked on every status frame: what the server offers for this Mac.
      */
     agentCapabilities?(): string[];
+    /** Terminal sessions open on this machine now (`prohost host` counts them against capacity). */
+    liveTerminals?(): Array<{
+        terminalId: string;
+        codeThreadId: string;
+        agent: string;
+    }>;
+    /**
+     * Report a start as failed without starting anything (the computer is
+     * paused), the way a failed start is reported: the thread never waits in
+     * `starting`. Resolves whether the report landed.
+     */
+    failStart?(data: Record<string, unknown>, reason: string): Promise<boolean>;
 }
 /** `code_thread.approval_decided` data, or `null`. */
 export declare function parseApprovalDecision(data: Record<string, unknown>): ApprovalRequest | null;
@@ -138,6 +150,13 @@ export interface CodeHostOptions {
     onCodeHostChanged?: () => void;
     /** The selected account's environment (see `CodeTerminalsOptions.accountEnv`). */
     accountEnv?: (agent: CodeAgent) => AccountEnvResult;
+    /** See `CodeHostRelayOptions.fallbackApiKey`. */
+    fallbackApiKey?: string;
+    /**
+     * The computer is paused (`prohost host pause`): no new viewer may dial in.
+     * Terminals already open, replies and approvals carry on.
+     */
+    paused?: () => boolean;
     tmux?: TmuxRunner;
     spawnPty?: () => PtySpawn | undefined;
     events?: CodeThreadEventSink;
@@ -190,6 +209,11 @@ export declare class CodeHost implements CodeHostLike {
     constructor(options: CodeHostOptions);
     settings(): CodeHostSettings;
     remoteTerminalAllowed(): boolean;
+    liveTerminals(): Array<{
+        terminalId: string;
+        codeThreadId: string;
+        agent: string;
+    }>;
     instanceCapability(): string;
     /**
      * Only the agents a start would accept: installed here, and runnable on this harness's login
@@ -272,6 +296,7 @@ export declare class CodeHost implements CodeHostLike {
      * Throws {@link UnreportedOutcomeError} when the outcome never reached the
      * server, so the harness asks for the delivery again rather than ack it.
      */
+    failStart(data: Record<string, unknown>, reason: string): Promise<boolean>;
     handleStart(data: Record<string, unknown>): Promise<boolean>;
     handleInput(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;
     handleApproval(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;

package/dist/codehost/host.js

@@ -24,7 +24,7 @@ import { LocalTerminalServer } from './local_server.js';
 import { loadNodePty } from './pty.js';
 import { CodeHostRelay } from './relay.js';
 import { codeHostDir, codeHostInstanceId, ensurePrivateDir, loadSettings } from './settings.js';
-import { CodeTerminals, execTmux } from './terminals.js';
+import { CodeTerminals, execTmux, isDefinitive } from './terminals.js';
 import { APPROVAL_DECISIONS, isValidId, socketNameFor, TMUX_CONF } from './tmux.js';
 export const EVENT_CODE_THREAD_START_REQUESTED = 'code_thread.start_requested';
 export const EVENT_CODE_THREAD_INPUT_REQUESTED = 'code_thread.input_requested';
@@ -204,6 +204,11 @@ export class CodeHost {
     remoteTerminalAllowed() {
         return this.settings().allowRemoteTerminal;
     }
+    liveTerminals() {
+        return this.terminals
+            .list()
+            .map((record) => ({ terminalId: record.terminalId, codeThreadId: record.codeThreadId, agent: record.agent }));
+    }
     instanceCapability() {
         return `${HOST_INSTANCE_CAPABILITY_PREFIX}${this.instanceId}`;
     }
@@ -243,6 +248,8 @@ export class CodeHost {
             this.relay = new CodeHostRelay({
                 baseUrl: this.options.baseUrl,
                 apiKey: this.options.apiKey,
+                ...(this.options.fallbackApiKey ? { fallbackApiKey: this.options.fallbackApiKey } : {}),
+                ...(this.options.paused ? { dialsPaused: this.options.paused } : {}),
                 machineId: this.options.machineId,
                 instanceId: this.instanceId,
                 machine: this.options.machine,
@@ -527,6 +534,14 @@ export class CodeHost {
      * Throws {@link UnreportedOutcomeError} when the outcome never reached the
      * server, so the harness asks for the delivery again rather than ack it.
      */
+    async failStart(data, reason) {
+        const request = parseStartRequest(data);
+        if (!request)
+            return true;
+        const status = await this.events.post(request.codeThreadId, event('failed', { reason }, Date.now()));
+        // Retryable answers (401 while the token renews, 408, 429, 5xx) leave the delivery to be retried.
+        return isDefinitive(status);
+    }
     async handleStart(data) {
         const request = parseStartRequest(data);
         if (!request)

package/dist/codehost/host_stats.d.ts

@@ -6,8 +6,10 @@
  * number comes from a stock tool or Node's `os` module; anything that can't be
  * read is `null`, never 0. macOS sources: `vm_stat` (memory in use),
  * `sysctl kern.memorystatus_vm_pressure_level` (pressure), `pmset -g batt`
- * (battery), `sysctl machdep.cpu.brand_string` (spec). Elsewhere only the
- * `os`-module numbers are reported.
+ * (battery), `sysctl machdep.cpu.brand_string` (spec). Linux: `/proc/meminfo`
+ * (memory in use), `/proc/pressure/memory` (pressure, PSI), and
+ * `/sys/class/power_supply` (battery). Windows: `typeperf` performance counters
+ * (memory in use, commit charge → pressure) and PowerShell's `Win32_Battery`.
  */
 import os from 'node:os';
 export type MemoryPressure = 'normal' | 'elevated' | 'critical';
@@ -31,6 +33,47 @@ export declare function parsePmset(text: string): {
     batteryPct: number | null;
     onBattery: boolean | null;
 };
+/**
+ * Linux PSI (`/proc/pressure/memory`): the share of the last 10 s some / all
+ * runnable tasks stalled on memory. `full` stalls mean the machine is
+ * thrashing; sustained `some` stalls mean reclaim is getting in the way.
+ */
+export declare function pressureFromPsi(text: string): MemoryPressure | null;
+/** Bytes in use per `/proc/meminfo`: MemTotal − MemAvailable (what `free` calls used). */
+export declare function usedFromMeminfo(text: string): number | undefined;
+/** `/sys/class/power_supply/BAT*`: its `capacity` and `status`, and whether any AC supply is online. */
+export declare function linuxBattery(supplies: Array<{
+    name: string;
+    type?: string;
+    capacity?: string;
+    status?: string;
+    online?: string;
+}>): {
+    batteryPct: number | null;
+    onBattery: boolean | null;
+};
+/**
+ * One `typeperf -sc 1` sample of `\Memory\Available MBytes` and
+ * `\Memory\% Committed Bytes In Use`: the last CSV row, quoted values.
+ */
+export declare function parseTypeperf(text: string): {
+    availableMb?: number;
+    committedPct?: number;
+};
+/**
+ * Windows has no single pressure level, so it is read from what the memory
+ * manager is short of: physical memory left, and the commit charge against
+ * its limit (past which allocations fail outright).
+ */
+export declare function windowsPressure(sample: {
+    availableMb?: number;
+    committedPct?: number;
+}, totalBytes: number | undefined): MemoryPressure | null;
+/** PowerShell `Win32_Battery` as `<BatteryStatus>,<EstimatedChargeRemaining>`; 1 = discharging. */
+export declare function parseWindowsBattery(text: string): {
+    batteryPct: number | null;
+    onBattery: boolean | null;
+};
 /** e.g. `Apple M3 Max · 64 GB`. */
 export declare function specFrom(brand: string | undefined, totalBytes: number | undefined): string | null;
 interface CpuSample {
@@ -51,6 +94,10 @@ export interface HostStatsSamplerOptions {
         busy: number;
         total: number;
     } | undefined;
+    /** Reads a small system file (`/proc`, `/sys`); `undefined` when it can't. */
+    readFile?: (file: string) => string | undefined;
+    /** Lists a directory (`/sys/class/power_supply`); empty when it can't. */
+    listDir?: (dir: string) => string[];
 }
 /** Samples on demand. Keeps the previous CPU sample so each call reports the interval since the last. */
 export declare class HostStatsSampler {