@prohost/cli 0.13.2 → 0.14.0

package/dist/agent/run.js

@@ -27,10 +27,12 @@
  * way a stop pressed in the UI reaches a machine that accepts no connections.
  */
 import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import WebSocket from 'ws';
 import { HarnessAccount } from './account_runtime.js';
-import { EVENT_AGENT_CONFIG_UPDATED, machineId } from './accounts.js';
+import { EVENT_AGENT_CONFIG_UPDATED, accountEnv, machineId } 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';
@@ -45,11 +47,13 @@ import { buildPrompt, replyFromStdout } from './prompt.js';
 import { NO_CAPABILITIES, capabilityProbe } from './capabilities.js';
 import { RunStore } from './runstore.js';
 import { DEFAULT_CONCURRENCY, MAX_CONCURRENCY, RunScheduler } from './scheduler.js';
-import { RUNTIME_STATUS_FEATURE, RuntimeStatusReporter, claudeQuotaProvider, codexConfiguredModel, codexQuotaProvider, modelFromExec, parseVersion, readCodexObservation, } from './runtime_status.js';
+import { CODE_HOST_FOLDERS_FEATURE, RUNTIME_STATUS_FEATURE, RuntimeStatusReporter, claudeQuotaProvider, codexConfiguredModel, codexQuotaProvider, modelFromExec, parseVersion, readCodexObservation, shortHostname, } from './runtime_status.js';
 import { SessionStore, sessionKeyFor } from './sessionstore.js';
 import { verifySignature } from './signature.js';
 import { VENUE_RUN_TOKEN_CAPABILITY, apiForRun, claudeSupportsVenueSessions, claudeVenueCommand, VENUE_PROGRESS, VENUE_SESSION_FEATURE, VENUE_SESSION_FRAME, VENUE_SESSION_OPEN_FRAME, VENUE_GRANT_CHECK_MS, VENUE_EXPIRY_MARGIN_MS, VENUE_GRANT_ENDED_ERROR, VENUE_GRANT_EXPIRED_ERROR, isVenueRun, venueEnv, venueGrantLive, venueGrantRemainingMs, venueRunFromSession, venueWorkdir, } from './venue.js';
 import { RUN_REPOS_ENV_VAR, WorktreeManager } from './worktrees.js';
+import { CODE_THREAD_FOLDERS_CAPABILITY, CODE_THREADS_CAPABILITY, CodeHost, RefusedDeliveryError, REMOTE_TERMINAL_CAPABILITY, EVENT_CODE_THREAD_APPROVAL_DECIDED, EVENT_CODE_THREAD_INPUT_REQUESTED, EVENT_CODE_THREAD_START_REQUESTED, } from '../codehost/host.js';
+import { loadSettings as loadCodeHostSettings } from '../codehost/settings.js';
 import { isWebhookEvent } from '../forward.js';
 import { DEFAULT_WS_URL } from '../listen.js';
 import { ServerLiveness, enableTcpKeepAlive, seconds, terminateSocket } from '../liveness.js';
@@ -105,9 +109,15 @@ const HANDSHAKE_TIMEOUT_MS = 30_000;
  * uses it to stop a run from sitting on CI after the PR is open.
  */
 export const PAIRED_RUN_ENV_VAR = 'PROHOST_PAIRED_RUN';
+/** What a run sent to a `--host-only` harness is answered with: it never executes. */
+export const HOST_ONLY_REFUSAL = "This computer only hosts Code threads; it doesn't answer messages.";
+/** Declared by a `--host-only` harness: it executes no runs (the server may say so, or stop sending them). */
+export const HOST_ONLY_CAPABILITY = 'host_only';
 /** Ack status codes reported back over the socket for each frame. */
 const ACK_ACCEPTED = 200;
 const ACK_IGNORED = 204;
+/** A Code-thread reply or decision refused before anything was typed; the ack names why. */
+const ACK_REFUSED = 409;
 const ACK_REJECTED = 401;
 /** Received, but the run could not be taken on yet: the server keeps retrying the delivery. */
 const ACK_RETRY = 503;
@@ -638,7 +648,13 @@ toolEvents,
 /** Harness-set variables for this run's command, over the brain's own. */
 runEnv, 
 /** A venue run's own empty working directory; marks the turn as a venue session. */
-venueCwd) {
+venueCwd, 
+/**
+ * Where an answer goes the moment its turn ends while a background task is
+ * still running (see `readClaudeStream`). Absent, such answers stay in the
+ * turn's reply.
+ */
+onEarlyAnswer) {
     // `--timeout` is a ceiling on the run, not on each attempt: the retry below
     // must not let one run take twice what the operator allowed. Both attempts
     // share one deadline, which costs the retry nothing in practice — a rejected
@@ -699,6 +715,9 @@ venueCwd) {
         // The heartbeat line above is unchanged for older servers; the events are
         // the richer channel a newer server renders beneath it.
         toolEvents?.push(reader.drainToolEvents());
+        if (onEarlyAnswer)
+            for (const answer of reader.takeEarlyAnswers())
+                onEarlyAnswer(answer);
     };
     /**
      * Undo an eagerly recorded Claude session after an ordinary failed turn.
@@ -746,8 +765,16 @@ venueCwd) {
                     : undefined,
         });
         // Whatever the stream announced — model, version, capacity — is true of
-        // this machine whether or not the turn succeeded.
-        return reader ? running.finally(() => runtime.observe(reader.observed())) : running;
+        // this machine whether or not the turn succeeded. Its last event may have
+        // come without a newline: ended here, so a turn it closed still hands out
+        // the answers before it.
+        return reader
+            ? running.finally(() => {
+                reader.push('\n');
+                observe(reader);
+                runtime.observe(reader.observed());
+            })
+            : running;
     };
     // Wall clock for the whole turn, retry included — what the operator waited,
     // rather than what the last attempt took.
@@ -1026,13 +1053,63 @@ mcp) {
     // workspace, and on this machine's log: never the agent's words about the
     // connected team's thread (see `VENUE_PROGRESS`).
     const turnControl = venue ? { ...control, report: () => control.report(VENUE_PROGRESS) } : control;
+    // A turn the agent ended while a background task was still running is a
+    // message of its own, posted as it lands: the agent wrote it for the thread
+    // ("the review is still running, I'll post the result"), and another turn
+    // may follow it by minutes. Strictly in order, each under a key of its own
+    // that every retry reuses, so an answer the server took but whose response
+    // was lost can't land twice. One that can't be posted holds back everything
+    // after it — the run's last reply included — and nothing is sent once the
+    // run has been stopped.
+    const early = [];
+    let earlyCount = 0;
+    let earlyPosted = 0;
+    let earlyPosts = Promise.resolve();
+    const earlyPath = run.reply_path;
+    const earlyBodyKey = run.reply_body_key;
+    const stoppedNow = () => control.signal.aborted || control.disposition() !== undefined;
+    const postEarly = async () => {
+        if (!earlyPath || !earlyBodyKey)
+            return;
+        while (early.length > 0) {
+            // The tool calls that led here are on the timeline before the answer.
+            await toolEvents.flush();
+            if (stoppedNow()) {
+                early.length = 0;
+                return;
+            }
+            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);
+            if (!posted.ok) {
+                if (!stoppedNow())
+                    log(`${timestamp()} ! ${label} could not post an answer yet (${describeFailure(posted)})`);
+                return;
+            }
+            early.shift();
+            earlyPosted += 1;
+            log(`${timestamp()} ✓ ${label} posted an answer; a background task is still running`);
+        }
+    };
+    const onEarlyAnswer = !options.dryRun && earlyPath && earlyBodyKey
+        ? (answer) => {
+            earlyCount += 1;
+            early.push({ answer, key: `${run.run_id}-turn-${earlyCount}` });
+            earlyPosts = earlyPosts.then(postEarly);
+        }
+        : undefined;
     let result;
     try {
-        result = await runTurn(run, prompt, options, runtime, mcp, turnControl, log, toolEvents, runEnv, venueDir?.dir);
+        result = await runTurn(run, prompt, options, runtime, mcp, turnControl, log, toolEvents, runEnv, venueDir?.dir, onEarlyAnswer);
     }
     finally {
         venueDir?.remove();
+        await earlyPosts;
     }
+    // One more try for an answer that couldn't be posted while the run worked.
+    if (early.length > 0)
+        await postEarly();
     // 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;
@@ -1116,14 +1193,29 @@ mcp) {
         log(`    [dry-run] nothing was sent and the run was left open`);
         return 'skipped';
     }
+    // An earlier answer still not in the thread: posting the last one would put
+    // it out of order, and posting the earlier one under any other key could
+    // post it twice. The run fails the way a rejected reply does.
+    if (early.length > 0) {
+        log(`${timestamp()} ✗ ${label} ${early.length} answer(s) could not be posted (${seconds}s)`);
+        if (result.sessionRecorded)
+            runtime.sessions.forget(sessionKeyFor(run));
+        const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: 'posting the reply failed: an earlier answer could not be posted' }, log, sleep, runtime.model());
+        return reported.ok ? 'failed' : 'unreported';
+    }
     // The agent decided not to reply — the usual answer when it was woken as a
     // bystander (`reply_expected: false`). A finished run, not a failure: nothing
     // is posted, and the completion says so, so the server records a deliberate
     // silence and clears the thinking indicator as one. Checked on every run, not
     // only bystander ones: the literal token must never reach a thread.
     if (isNoReply(reply)) {
-        log(`${timestamp()} ✓ ${label} chose not to reply (${seconds}s)`);
-        const completed = await completeWithRetry(api, run.completion_path, { ok: true, silent: true }, log, sleep, runtime.model());
+        // Silence only when nothing was said: a last turn that adds nothing to
+        // answers already in the thread is a run that replied.
+        const silent = earlyPosted === 0;
+        log(silent
+            ? `${timestamp()} ✓ ${label} chose not to reply (${seconds}s)`
+            : `${timestamp()} ✓ ${label} replied in ${seconds}s (${earlyPosted} posted while it worked)`);
+        const completed = await completeWithRetry(api, run.completion_path, silent ? { ok: true, silent: true } : { ok: true }, log, sleep, runtime.model());
         if (!completed.ok) {
             log(`    ! could not mark the run complete (${describeFailure(completed)})`);
             return 'unreported';
@@ -1188,7 +1280,8 @@ mcp) {
         log(`${timestamp()} ! ${label} replied, but marking it complete failed (${describeFailure(completed)})`);
         return 'unreported';
     }
-    log(`${timestamp()} ✓ ${label} replied in ${seconds}s (${reply.length} chars)`);
+    const alsoPosted = earlyPosted > 0 ? `, ${earlyPosted} more posted while it worked` : '';
+    log(`${timestamp()} ✓ ${label} replied in ${seconds}s (${reply.length} chars${alsoPosted})`);
     return 'succeeded';
 }
 /**
@@ -1197,6 +1290,63 @@ mcp) {
  * Reconnects on any drop with jittered exponential backoff; an ``auth_error``
  * is fatal, because retrying a rejected credential just hammers the server.
  */
+/**
+ * The login a Code thread's agent runs on: the account picked for this
+ * agent, as its ordinary runs get it. A thread for the other CLI, or an
+ * account that is no longer on this machine, is refused rather than run on
+ * some other login — it would spend a subscription the agent doesn't report.
+ * A harness without accounts (a plain `--exec`) and shell threads use the
+ * operator's default login, exactly as everything else they run does.
+ */
+export function codeThreadAccountEnv(account, agent) {
+    if (!account || agent === 'shell')
+        return { ok: true, env: {} };
+    if (account.runtime !== agent) {
+        const name = (runtime) => (runtime === 'codex' ? 'Codex' : 'Claude Code');
+        return {
+            ok: false,
+            reason: `this Mac's agent runs ${name(account.runtime)}, so it can't host a ${name(agent)} thread`,
+        };
+    }
+    const resolved = account.resolve();
+    return resolved.ok ? { ok: true, env: accountEnv(resolved.record) } : { ok: false, reason: resolved.error };
+}
+/**
+ * The Code-thread host, when this machine's owner turned hosting on — else
+ * `undefined`, and nothing about the harness changes.
+ */
+function buildCodeHost(options, machine, id, log, slots, accountEnv, onRemoteChanged, onCodeHostChanged) {
+    const env = { ...process.env, ...options.env };
+    if (!loadCodeHostSettings(env).enabled)
+        return undefined;
+    // The same id the event socket authenticates with, so both name one machine.
+    if (!id) {
+        log(`${timestamp()} ! Code-thread hosting is on, but this machine has no id yet — not hosting`);
+        return undefined;
+    }
+    try {
+        return new CodeHost({
+            env,
+            baseUrl: options.credentials.base_url,
+            apiKey: options.credentials.api_key,
+            machineId: id,
+            machine,
+            clientVersion: CLI_VERSION,
+            accountId: options.credentials.prohost_account?.id,
+            repos: options.repos ?? [],
+            cliEntrypoint: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+            log,
+            slots,
+            accountEnv,
+            onRemoteChanged,
+            onCodeHostChanged,
+        });
+    }
+    catch (err) {
+        log(`${timestamp()} ! Code-thread hosting unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
 export async function runAgentHarness(options) {
     const log = options.onLine ?? ((line) => process.stdout.write(`${line}\n`));
     const Ctor = options.webSocketCtor ?? WebSocket;
@@ -1205,9 +1355,19 @@ export async function runAgentHarness(options) {
     const url = options.url ?? streamUrlFor(options.credentials, DEFAULT_WS_URL);
     const metrics = newMetrics();
     const runtime = buildRuntime(options, log);
+    if (options.hostOnly && options.credentials.account && options.credentials.account !== 'default') {
+        // Host-only runs no agent of its own, so it has no account to pick: never a silent switch.
+        log(`${timestamp()} ! --host-only: this pairing's account "${options.credentials.account}" is not used — ` +
+            "Code threads run on this Mac's default Claude Code / Codex login");
+    }
     // Keys this computer's accounts server-side; the label above is display
     // only. Only a runtime that reports accounts needs one.
-    const machineIdValue = runtime.account ? machineId({ ...process.env, ...options.env }) : undefined;
+    // Hosting Code threads needs it too: the server finds a Mac by this id.
+    const hostingCodeThreads = !options.dryRun &&
+        (options.codeHost !== undefined
+            ? options.codeHost !== null
+            : loadCodeHostSettings({ ...process.env, ...options.env }).enabled);
+    const machineIdValue = runtime.account || hostingCodeThreads ? machineId({ ...process.env, ...options.env }) : undefined;
     // A credential file written by 0.1.0 stores a socket URL on a host that only
     // ever answers 403. Upgrading the CLI would not have fixed those installs on
     // its own — the stored value wins over the constant — so say what happened
@@ -1248,7 +1408,30 @@ export async function runAgentHarness(options) {
         accountKeys: runtime.account ? () => runtime.account.keys() : undefined,
         // A run in flight reports fresh numbers when it ends; don't probe beside it.
         isBusy: () => [...accepted.values()].some((entry) => entry.executing),
-        capabilities: () => (runtime.venueSessions ? [VENUE_RUN_TOKEN_CAPABILITY] : []),
+        capabilities: () => [
+            ...(runtime.venueSessions ? [VENUE_RUN_TOKEN_CAPABILITY] : []),
+            ...(options.hostOnly ? [HOST_ONLY_CAPABILITY] : []),
+            // Only a harness that hosts threads and handles `code_thread.*` says so:
+            // the server sends a Mac start only to a socket that declared it.
+            // Only while the relay hasn't refused the pairing: the server lists and admits on it.
+            // With which instance this home is: the server binds each thread to the one that started it.
+            // With folder starts (`folder` / `separateCopy`): the server sends one only to a socket saying so.
+            // With the agents whose binaries resolve here, re-checked per frame: the server offers only those.
+            ...(codeHost?.authorized()
+                ? [CODE_THREADS_CAPABILITY, CODE_THREAD_FOLDERS_CAPABILITY, codeHost.instanceCapability(), ...(codeHost.agentCapabilities?.() ?? [])]
+                : []),
+            // Read on every frame, so `remote off` stops being declared at the next one.
+            ...(codeHost?.authorized() && codeHost.remoteTerminalAllowed() ? [REMOTE_TERMINAL_CAPABILITY] : []),
+        ],
+        // `--machine` names this machine everywhere, exactly as given: whoever set it never sends the
+        // real hostname. Only the real hostname is cut to its short form.
+        hostname: () => (options.machine == null ? shortHostname() : options.machine),
+        // Only while hosting Code threads: the owner's opt-in covers sending this machine's load.
+        host: () => codeHost?.latestStats(),
+        // What a person may pick for a thread on this Mac; the server lists these and refuses others.
+        codeHostRepos: () => (codeHost?.authorized() ? codeHost.offeredRepos?.() : undefined),
+        // The folders this Mac has opened, and its home (for `~/…`): what a phone may start a thread in.
+        codeHostFolders: () => (codeHost?.authorized() ? codeHost.openedFolders?.() : undefined),
         log,
     });
     runtime.observe = (observation) => status.observe(observation);
@@ -1311,6 +1494,17 @@ export async function runAgentHarness(options) {
     const concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, Math.floor(options.concurrency ?? DEFAULT_CONCURRENCY)));
     const scheduler = new RunScheduler(concurrency);
     const worktrees = new WorktreeManager({ repos: options.repos ?? [], env: options.env, log });
+    const codeHost = !hostingCodeThreads
+        ? undefined
+        : options.codeHost === undefined
+            ? buildCodeHost(options, machine, machineIdValue, log, () => ({ busy: scheduler.active, total: concurrency }), (agent) => codeThreadAccountEnv(runtime.account, agent), () => status.capabilitiesChanged(), () => status.codeHostChanged())
+            : (options.codeHost ?? undefined);
+    if (codeHost) {
+        await codeHost.start().catch((err) => {
+            log(`${timestamp()} ! Code-thread hosting did not start: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    let codeHostIgnoredLogged = false;
     if (concurrency > 1) {
         log(`${timestamp()} ⚙ up to ${concurrency} runs at once${options.concurrency === undefined ? ' (the default; --concurrency 1 for one at a time)' : ''} — runs in the same conversation still take turns` +
             (worktrees.enabled
@@ -1427,6 +1621,13 @@ export async function runAgentHarness(options) {
         log(`${timestamp()} … disconnected; reconnecting in ${(delay / 1000).toFixed(1)}s`);
         await sleep(delay);
     }
+    // Remote terminals end the moment the harness does — before draining runs,
+    // which can take hours: nothing may attach or type after a stop. The
+    // terminals themselves stay (tmux owns them; the next start re-adopts them).
+    // Fail-soft: a cleanup error must never keep an in-flight run from reporting.
+    await codeHost?.stop().catch((err) => {
+        log(`${timestamp()} ! stopping Code-thread hosting: ${err instanceof Error ? err.message : String(err)}`);
+    });
     // Let an in-flight run finish reporting before we hand back metrics — and
     // any cancellation the heartbeat loop started and deliberately did not wait
     // for, so the harness never exits with a run half-closed.
@@ -1562,8 +1763,11 @@ export async function runAgentHarness(options) {
                     // mentions" describes a narrower trigger than the one this harness
                     // actually waits on, and sends anyone debugging a silent agent to
                     // read mention code instead of the run dispatcher.
-                    log(`${timestamp()} ● connected as "${name}" — waiting for ` +
-                        `${EVENT_AGENT_RUN_REQUESTED} (exec: ${options.exec})`);
+                    log(options.hostOnly
+                        ? `${timestamp()} ● connected as "${name}" — hosting Code threads only; ` +
+                            `every ${EVENT_AGENT_RUN_REQUESTED} is refused, nothing is executed`
+                        : `${timestamp()} ● connected as "${name}" — waiting for ` +
+                            `${EVENT_AGENT_RUN_REQUESTED} (exec: ${options.exec})`);
                     // Only a server that says it understands the frame gets one; an
                     // older server may treat an unknown frame type as a protocol error.
                     // A pick made while this agent was offline: the server repeats it on
@@ -1580,7 +1784,10 @@ export async function runAgentHarness(options) {
                     venueSessionsOffered = Array.isArray(f.features) && f.features.includes(VENUE_SESSION_FEATURE);
                     if (Array.isArray(f.features) && f.features.includes(RUNTIME_STATUS_FEATURE)) {
                         primeStatus();
-                        status.attach((frame) => ws.send(JSON.stringify(frame)));
+                        // A server that takes the opened folders whole (64 KiB frames) and early when they change.
+                        status.attach((frame) => ws.send(JSON.stringify(frame)), {
+                            codeHostFolders: f.features.includes(CODE_HOST_FOLDERS_FEATURE),
+                        });
                     }
                     return;
                 }
@@ -1611,9 +1818,9 @@ export async function runAgentHarness(options) {
                 if (!isWebhookEvent(frame))
                     return;
                 metrics.eventsReceived += 1;
-                const ack = (status) => {
+                const ack = (status, reason) => {
                     try {
-                        ws.send(JSON.stringify({ type: 'ack', delivery_id: frame.delivery_id, status }));
+                        ws.send(JSON.stringify({ type: 'ack', delivery_id: frame.delivery_id, status, ...(reason ? { reason } : {}) }));
                     }
                     catch {
                         /* best-effort */
@@ -1634,6 +1841,72 @@ export async function runAgentHarness(options) {
                     ack(applied ? ACK_ACCEPTED : ACK_IGNORED);
                     return;
                 }
+                if (frame.event === EVENT_CODE_THREAD_START_REQUESTED ||
+                    frame.event === EVENT_CODE_THREAD_INPUT_REQUESTED ||
+                    frame.event === EVENT_CODE_THREAD_APPROVAL_DECIDED) {
+                    if (!codeHost) {
+                        if (!codeHostIgnoredLogged) {
+                            codeHostIgnoredLogged = true;
+                            log(options.dryRun
+                                ? `${timestamp()} ◦ ${frame.event} ignored — [dry-run] Code-thread actions are disabled`
+                                : `${timestamp()} ◦ ${frame.event} ignored — this machine does not host Code threads ` +
+                                    '(prohost agent code-host enable)');
+                        }
+                        metrics.ignored += 1;
+                        ack(ACK_IGNORED);
+                        return;
+                    }
+                    // It starts processes on this machine, so it is held to the run's signature rule.
+                    if (!verifySignature(options.credentials.webhook_secret, frame.payload, frame.signature) &&
+                        !options.allowUnverified) {
+                        metrics.signatureRejections += 1;
+                        log(`${timestamp()} ✗ rejected ${frame.event} — signature did not verify`);
+                        ack(ACK_REJECTED);
+                        return;
+                    }
+                    const data = eventData(frame.payload);
+                    if (!codeHost.admits(frame.event, data)) {
+                        log(`${timestamp()} ◦ ${frame.event} refused — it needs the remote terminal on ` +
+                            '(prohost agent code-host remote on)');
+                        metrics.ignored += 1;
+                        // A reply or decision refused only for the switch: 409 + why, so the server hands it
+                        // back on the thread rather than count it delivered.
+                        const refusal = codeHost.refusal(frame.event);
+                        if (refusal)
+                            ack(ACK_REFUSED, refusal);
+                        else
+                            ack(ACK_IGNORED);
+                        return;
+                    }
+                    const starting = frame.event === EVENT_CODE_THREAD_START_REQUESTED;
+                    const handled = starting
+                        ? codeHost.handleStart(data)
+                        : frame.event === EVENT_CODE_THREAD_INPUT_REQUESTED
+                            ? codeHost.handleInput(data, frame.delivery_id)
+                            : codeHost.handleApproval(data, frame.delivery_id);
+                    // Acknowledged once handled, never before: a start acked and then
+                    // lost to a crash or a shutdown would leave its thread starting
+                    // forever. A start that ran — or failed, which it reports — is 200;
+                    // one that threw is retried, and the redelivery finds any window it
+                    // made (or joins the start still in flight). Input and approvals are
+                    // 200 when they reached a pane here, 409 + reason when refused before
+                    // typing anything (the server hands them back), else 204.
+                    background.push(handled
+                        .then((ok) => {
+                        ack(starting || ok ? ACK_ACCEPTED : ACK_IGNORED);
+                    })
+                        .catch((err) => {
+                        if (err instanceof RefusedDeliveryError) {
+                            log(`${timestamp()} ◦ ${frame.event} refused before typing anything: ${err.reason}`);
+                            metrics.ignored += 1;
+                            ack(ACK_REFUSED, err.reason);
+                            return;
+                        }
+                        log(`${timestamp()} ✗ ${frame.event} failed: ${err instanceof Error ? err.message : String(err)}`);
+                        ack(ACK_RETRY);
+                    }));
+                    return;
+                }
                 if (frame.event !== EVENT_AGENT_RUN_REQUESTED) {
                     if (frame.event === EVENT_MENTION_CREATED || frame.event === EVENT_MESSAGE_TEAM_CHAT) {
                         // "runs are triggered by mentions" was wrong twice over: the gate
@@ -1678,6 +1951,28 @@ export async function runAgentHarness(options) {
                 handledThisSession.add(run.run_id);
                 /** Take the run on: track it, heartbeat it, queue it. */
                 const accept = (run) => {
+                    if (options.hostOnly && !previous) {
+                        // Never executed: closed out as failed at once, through the run's own completion
+                        // path, so the person who mentioned this machine hears why instead of waiting.
+                        metrics.runsFailed += 1;
+                        if (options.dryRun) {
+                            log(`${timestamp()} [dry-run] would refuse run ${run.run_id.slice(0, 12)} — this harness only hosts Code threads`);
+                            return;
+                        }
+                        log(`${timestamp()} ⊘ run ${run.run_id.slice(0, 12)} refused — this harness only hosts Code threads`);
+                        background.push(completeWithRetry(apiForRun(api, run), run.completion_path, { ok: false, error: HOST_ONLY_REFUSAL }, log, sleep)
+                            .then((closed) => {
+                            if (closed.ok)
+                                runs.markCompleted(run.run_id);
+                            else
+                                handledThisSession.delete(run.run_id);
+                        })
+                            .catch((err) => {
+                            handledThisSession.delete(run.run_id);
+                            log(`${timestamp()} ✗ refusing run ${run.run_id.slice(0, 12)} failed: ${String(err)}`);
+                        }));
+                        return;
+                    }
                     if (previous) {
                         // We ran this one before but never got a terminal state accepted —
                         // most likely the process died between the command and the

package/dist/agent/runtime_status.d.ts

@@ -36,6 +36,34 @@ export declare const STATUS_INTERVAL_MS: number;
  * the frame that carried a change.
  */
 export declare const MIN_FRAME_SPACING_MS = 31000;
+/**
+ * Inside that window the server still accepts a frame whose capabilities
+ * changed, one per 5 s (`MIN_CAPABILITY_CHANGE_INTERVAL_SECONDS`), and a strict
+ * narrowing (a capability dropped, nothing added) one per second
+ * (`MIN_CAPABILITY_NARROWING_INTERVAL_SECONDS`). A capability can be a switch
+ * the server enforces (`remote_terminal`). Margin on both.
+ */
+export declare const MIN_CAPABILITY_CHANGE_SPACING_MS = 6000;
+export declare const MIN_CAPABILITY_NARROWING_SPACING_MS = 1500;
+/**
+ * The server drops a status frame over 8 KB (`MAX_FRAME_BYTES`). The opened
+ * folders are the one part of it that can grow that far, so they are cut,
+ * oldest first, until the frame fits under this, with margin.
+ */
+export declare const MAX_STATUS_FRAME_BYTES = 8000;
+/**
+ * The budget once the server lists {@link CODE_HOST_FOLDERS_FEATURE} in `auth_ok.features`: it
+ * takes frames up to 64 KiB, so all 50 folders fit. Margin under the cap.
+ */
+export declare const MAX_LARGE_STATUS_FRAME_BYTES: number;
+/**
+ * A server listing this feature takes a status frame up to 64 KiB, and one whose
+ * `code_host_repos` / `code_host_folders` / `code_host_home` changed inside its spacing window
+ * (a 5 s floor) — the opened folders reach phones within seconds of `folders add`.
+ */
+export declare const CODE_HOST_FOLDERS_FEATURE = "code_host_folders";
+/** The early code-host frame's spacing: the server's 5 s floor, with margin. */
+export declare const MIN_CODE_HOST_CHANGE_SPACING_MS = 6000;
 /** Ask the agent CLI for fresh numbers when the last ones are this old. */
 export declare const QUOTA_REFRESH_AFTER_MS: number;
 /** Ceiling on one idle quota probe. */
@@ -80,8 +108,10 @@ export declare function fromClaudeRateLimitInfo(info: unknown): QuotaWindow[];
  * Windows from a `get_usage` control response (0–100, ISO strings).
  *
  * A window with a usage but a `null` reset is kept, with `resets_at: null` —
- * that is how an idle account's 5-hour window reads, and dropping it is what
- * left paired agents showing a weekly window and nothing else (B3).
+ * that is how an idle account's 5-hour window reads. Reporting stays complete:
+ * dropping it here, with the list replaced whole by each source, erased a known
+ * 5-hour window (B3). Whether to show an idle one is the server's call (it
+ * doesn't: `shared.ai_usage.windows.visible_windows`).
  *
  * Per-model weekly windows come from `rate_limits.limits[]` rows of kind
  * `weekly_scoped` (classified on `kind`, as the schema asks, never on a
@@ -181,9 +211,16 @@ export interface AccountsSnapshot {
      */
     all?: AccountBlock[];
 }
+/** This machine's hostname up to its first dot (`studio-001.local` is `studio-001`), or `undefined`. */
+export declare function shortHostname(raw?: string): string | undefined;
 export interface RuntimeStatusReporterOptions {
     /** `claude_code` | `codex` | `goose` | `custom`. */
     runtime: string;
+    /**
+     * The machine's short hostname, for ProhostAI staff reading a run's details. Defaults to
+     * {@link shortHostname}; `agent run` passes its `--machine` name when one was given.
+     */
+    hostname?: () => string | undefined;
     /** Idle quota source; omit for a runtime that has none. */
     provider?: QuotaProvider;
     /**
@@ -212,6 +249,29 @@ export interface RuntimeStatusReporterOptions {
      * frame, so a downgraded harness stops declaring what it no longer does.
      */
     capabilities?: () => string[];
+    /**
+     * This machine's load (`codehost/host_stats.ts`), read for every frame. Only
+     * set while Code-thread hosting is on — the owner's opt-in — so a harness
+     * that doesn't host threads sends exactly the frame it always did.
+     */
+    host?: () => Record<string, unknown> | undefined;
+    /**
+     * The repositories this harness offers Code threads (`codehost/checkouts.ts`),
+     * read for every frame. Only set while it hosts them; `undefined` sends none.
+     */
+    codeHostRepos?: () => string[] | undefined;
+    /**
+     * The folders this harness has opened for Code threads and its home directory
+     * (`codehost/folders.ts`), read for every frame as `code_host_folders` /
+     * `code_host_home`. Only set while it hosts them; `undefined` sends neither.
+     */
+    codeHostFolders?: () => {
+        folders: {
+            path: string;
+            git: boolean;
+        }[];
+        home: string;
+    } | undefined;
     now?: () => number;
     /** Timer seam for tests. Returns a cancel function. */
     schedule?: (fn: () => void, ms: number) => () => void;
@@ -235,6 +295,16 @@ export declare class RuntimeStatusReporter {
     private quotaObservedAt;
     private send;
     private lastSentAt;
+    /** The capabilities the last frame carried, and when a changed set last went out at once. */
+    private lastSentCapabilities;
+    private lastCapabilityChangeAt;
+    private lastCapabilityNarrowingAt;
+    /** The code-host fields the last frame carried, and when a changed set last went out early. */
+    private lastSentCodeHost;
+    private lastCodeHostChangeAt;
+    private cancelCodeHostPending;
+    /** The server lists {@link CODE_HOST_FOLDERS_FEATURE}: 64 KiB frames, early code-host frames. */
+    private codeHostServer;
     private cancelPending;
     private cancelTick;
     private refreshing;
@@ -253,6 +323,13 @@ export declare class RuntimeStatusReporter {
     setAccounts(snapshot: AccountsSnapshot | undefined, options?: {
         quiet?: boolean;
     }): void;
+    /**
+     * What the harness declares changed (the remote-terminal switch): sent at
+     * once, since the server lets a changed capability set through its spacing
+     * window and stops sending what this machine now refuses; and again in the
+     * next spaced slot, for a server that predates that.
+     */
+    capabilitiesChanged(): void;
     /**
      * The account choice changed (an operator picked one in ProhostAI): re-read
      * accounts and capacity on the next tick rather than in fifteen minutes.
@@ -261,11 +338,28 @@ export declare class RuntimeStatusReporter {
     /** The model to report on a run's completion, when nothing more specific is known. */
     model(): string | undefined;
     /** Start reporting on a socket that advertised the feature. */
-    attach(send: (frame: Record<string, unknown>) => void): void;
+    attach(send: (frame: Record<string, unknown>) => void, server?: {
+        codeHostFolders?: boolean;
+    }): void;
+    /**
+     * What this Mac offers Code threads changed (its opened folders, say, after `folders add`). A
+     * server listing {@link CODE_HOST_FOLDERS_FEATURE} takes such a frame early, at most every
+     * {@link MIN_CODE_HOST_CHANGE_SPACING_MS}; an older one gets it in the next spaced slot.
+     */
+    codeHostChanged(): void;
+    private codeHostKey;
     /** Stop reporting — the socket is gone. */
     detach(): void;
     /** The frame as it would be sent now. */
     frame(): Record<string, unknown>;
+    /**
+     * `frame` with the opened folders, as many as fit (newest kept): under {@link MAX_STATUS_FRAME_BYTES},
+     * or {@link MAX_LARGE_STATUS_FRAME_BYTES} for a server that takes large frames.
+     */
+    private withCodeHostFolders;
+    private codeHostReposField;
+    private hostnameField;
+    private hostField;
     /**
      * Whether the machine's registry no longer holds exactly the accounts the
      * snapshot lists: another agent home started on a login of its own, or an
@@ -278,6 +372,8 @@ export declare class RuntimeStatusReporter {
     private refresh;
     /** Send now if spacing allows, else once it does. Coalesces. */
     private sendSoon;
+    private capabilitiesList;
+    private capabilitiesKey;
     private flush;
 }
 export {};