@prohost/cli 0.15.0 → 0.16.1

package/dist/agent/prompt.d.ts

@@ -99,6 +99,18 @@ export interface PromptContext {
         source: string;
         reason: string;
     }>;
+    /**
+     * Said right after the opening line: `prohost host` resumed this run on
+     * another AI login after the first one hit its usage limit, so the turn may
+     * be half done.
+     */
+    resumeNote?: string;
+    /**
+     * Ask the agent to end a customer-visible reply with its confidence line
+     * (`[[confidence=0.9 reply_class=general]]`): the server sends it only when
+     * confident enough and its class needs no approval, else saves a draft.
+     */
+    askConfidence?: boolean;
 }
 /** Build the stdin prompt for one run. */
 export declare function buildPrompt(run: AgentRunRequest, context: PromptContext): string;

package/dist/agent/prompt.js

@@ -175,6 +175,11 @@ export function buildPrompt(run, context) {
                         : `You have been given work on a ${run.reply_surface}. There is nowhere to post a reply.`,
         '',
     ];
+    if (context.resumeNote)
+        lines.push(context.resumeNote, '');
+    if (context.askConfidence) {
+        lines.push('End your reply with one last line, exactly: [[confidence=<0 to 1> reply_class=<class>]] — how sure you are', 'the reply is right and safe to send as is, and its class: general, pricing_action, billing_action,', 'legal_contractual or bug_in_our_code. That line is removed before sending; below the bar, or for a class', 'that needs approval, your reply is saved as a draft for the team instead of sent.', '');
+    }
     // The operator's own configuration comes first, above everything the server
     // generated. It is who this agent *is* — persona, house rules, escalation
     // policy — and an agent that meets its standing instructions only after four

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,59 @@ 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 sign-in checker that adds `extra` only when it runs `binary` (this
+ * harness's Claude): the account snapshot checks other runtimes' logins too,
+ * and a Codex check must never see the Claude token.
+ */
+export declare function scopedCommandRunner(binary: string, base: CommandRunner | undefined, extra: () => NodeJS.ProcessEnv): CommandRunner;
+/**
+ * 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 +347,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,18 @@ 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)) {
+        const muted = /ai_muted/.test(result.error ?? '');
+        log(muted
+            ? `${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, withheld: muted ? 'muted' : 'suggestion' };
+    }
+    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 +271,85 @@ 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 ?? '');
+}
+/**
+ * A sign-in checker that adds `extra` only when it runs `binary` (this
+ * harness's Claude): the account snapshot checks other runtimes' logins too,
+ * and a Codex check must never see the Claude token.
+ */
+export function scopedCommandRunner(binary, base, extra) {
+    return (command, args, env) => (base ?? defaultCommandRunner)(command, args, command === binary ? { ...env, ...extra() } : env);
+}
+/** 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 +370,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 +399,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
+            ? scopedCommandRunner(options.exec.trim().split(/\s+/)[0] ?? 'claude', options.accountCommandRunner, () => 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 +416,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 +432,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 +447,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 +476,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 +984,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 +1021,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 +1041,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 +1090,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 +1135,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 +1146,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
@@ -1065,6 +1182,8 @@ mcp) {
     let earlyCount = 0;
     let earlyPosted = 0;
     let earlyPosts = Promise.resolve();
+    /** An answer of this run was dropped because the thread is muted: its session must not continue. */
+    let muted = false;
     const earlyPath = run.reply_path;
     const earlyBodyKey = run.reply_body_key;
     const stoppedNow = () => control.signal.aborted || control.disposition() !== undefined;
@@ -1081,7 +1200,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)})`);
@@ -1089,6 +1211,8 @@ mcp) {
             }
             early.shift();
             earlyPosted += 1;
+            if (posted.withheld === 'muted')
+                muted = true;
             log(`${timestamp()} ✓ ${label} posted an answer; a background task is still running`);
         }
     };
@@ -1113,6 +1237,17 @@ mcp) {
     // A venue session is never continued: the next turn there starts fresh from
     // the thread the server sends, so nothing of this one is remembered.
     const sessionId = venue ? undefined : result.ok ? result.sessionId : undefined;
+    /**
+     * Continue the conversation's session from this turn — unless an answer of
+     * it was dropped because the thread is muted (any runtime): then the session
+     * holds a turn nobody saw, so it is forgotten, eager record or resumed one alike.
+     */
+    const settleSession = (id) => {
+        if (muted)
+            runtime.sessions.forget(sessionKeyFor(run));
+        else if (id)
+            runtime.sessions.remember(sessionKeyFor(run), id);
+    };
     // Whatever the turn did, the timeline is whole BEFORE the reply is posted or
     // the run is closed — a completion that beats its own last tool row would
     // leave a `calling` row on a finished run. Never rejects, and after `stop`
@@ -1159,6 +1294,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 +1330,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}:`);
@@ -1220,9 +1369,7 @@ mcp) {
             log(`    ! could not mark the run complete (${describeFailure(completed)})`);
             return 'unreported';
         }
-        if (sessionId) {
-            runtime.sessions.remember(sessionKeyFor(run), sessionId);
-        }
+        settleSession(sessionId);
         return 'succeeded';
     }
     // A run with no reply surface is a legitimate outcome, not an error: it was
@@ -1242,14 +1389,12 @@ mcp) {
             log(`    ! could not mark the run complete (${describeFailure(completed)})`);
             return 'unreported';
         }
-        if (sessionId) {
-            runtime.sessions.remember(sessionKeyFor(run), sessionId);
-        }
+        settleSession(sessionId);
         return 'succeeded';
     }
     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
@@ -1267,10 +1412,11 @@ mcp) {
     }
     // Advance continuity only after the answer is durable on its reply surface.
     // Remembering at process exit would strand the conversation behind an answer
-    // it never received whenever this POST is rejected.
-    if (sessionId) {
-        runtime.sessions.remember(sessionKeyFor(run), sessionId);
-    }
+    // it never received whenever this POST is rejected. A muted thread kept
+    // nothing of it, so its session is not advanced either (and an eager record undone).
+    if (posted.withheld === 'muted')
+        muted = true;
+    settleSession(sessionId);
     const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep, runtime.model());
     if (!completed.ok) {
         // The reply is already in the conversation, so this is a bookkeeping
@@ -1400,7 +1546,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 +2328,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>;