@prohost/cli 0.13.2 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,101 @@ Versions follow [semver](https://semver.org/). Publishing is automated: merging
 a version bump to `main` triggers `.github/workflows/npm-publish-cli.yml`, which
 builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
+## Unreleased
+
+## 0.14.0
+
+- **Code threads on this Mac: installed agents, honest shells, one prompt, who sizes.**
+  The host declares `code_thread_agent_claude_code` / `code_thread_agent_codex` for each
+  agent whose binary resolves on the daemon's `PATH` (re-checked per status frame), so a
+  `--host-only` Mac offers Claude Code and Codex, not only Shell; a start for one that is
+  missing fails saying which binary. A reply into a shell window is refused as the new
+  `shell_window` (was `terminal_gone`). New windows start at the size they'll be viewed at
+  (`resize-window` right after `new-window`), and a shell's first prompt waits for its first viewer's size to settle
+  (`tmux wait-for`), so it shows one prompt instead of one per resize. Each window is
+  sized by `resize-window` (so `window-size manual` per window; tmux 3.4 exits at start with
+  it in a config) to one viewer: whoever attaches, types, focuses or sends
+  `{"type":"claim"}` (never a watch viewer), applied once quiet 300 ms and never for a size it
+  already has, since Claude Code reprints its transcript on every width change. A viewer that
+  sent `{"type":"hello","client":{"kind","label"}}` is told who that is and whether the pane is
+  in copy mode (`{"type":"sizer",...,"scrolled"}`). Copy mode is the pane's, so it is left when
+  the sizing viewer changes and when the viewer that scrolled detaches. `scroll-on-clear off`:
+  a full-screen redraw no longer leaves a copy of the old screen in scrollback (Claude Code's
+  header repeated once per resize). No copy-mode position box and no coloured border at a
+  window's edge; typed text and relayed replies leave copy mode first (q / Esc / Ctrl+C there
+  still only leave it).
+
+- **`runtime_status` reports the machine's short hostname** (`hostname`, up to its first dot). The
+  server keeps it against the socket and on a run started while this is the pairing's only socket,
+  for ProhostAI staff only. With `--machine`, that name is sent as given (`build.eu` stays whole)
+  instead of the real hostname, and one the server can't use as a hostname (`Front desk`) means no machine is recorded. An older server
+  ignores it.
+- **`Claude Ultra` plan label.** `get_usage`'s `subscription_type: "ultra"` now reads
+  `Claude Ultra`. The value is inferred from `pro` / `max`; no real response has confirmed it yet.
+- **Host Code threads on this Mac (off by default).** `prohost agent
+  code-host enable` lets `agent run` take `code_thread.start_requested`,
+  `code_thread.input_requested` and `code_thread.approval_decided`: one worktree and one window in a private tmux
+  server per thread, running Claude Code, Codex or a shell, re-adopted after a
+  restart. Claude Code / Codex hooks are passed on their command lines (never
+  installed globally) and post the thread's prompts, turns, permission prompts
+  and interrupts with a narrow, expiring token. `prohost agent code-host remote
+  on` additionally lets the machine's owner attach and type from ProhostAI
+  through the relay (`/v1/code-hosts/*`), or from the desktop app over
+  loopback. While hosting, the heartbeat carries optional `host` stats. New
+  optional dependency: `node-pty` 1.1.0.
+- **`agent run --host-only`.** Hosts Code threads with no `--exec`: every
+  `agent.run_requested` is closed at once as failed ("This computer only hosts
+  Code threads; it doesn't answer messages."), nothing is executed, and the
+  harness declares `host_only`. Mutually exclusive with `--exec`;
+  `install-daemon --host-only` passes it through; listed in `--help`.
+- **`code-host/activity.json` for keep-awake.** While hosting, the daemon
+  writes `{"v":1,"busy":bool,"updatedAt":ISO}` (0600, atomic, at least every
+  30 s; removed when hosting stops): busy while any hosted agent is mid-turn
+  (Claude Code `UserPromptSubmit` → `Stop`; a goal or typed reply → Codex's
+  turn-complete; Esc/Ctrl+C from an attached viewer ends it; 6 h cap per
+  turn). Readers treat `updatedAt` older than ~3 min as not busy.
+- **Folder Code threads.** A `code_thread.start_requested` with `folder` runs
+  in that folder in place (no worktree, no branch), or with `separateCopy` in a
+  worktree and branch of the folder's git checkout. Only a folder this Mac has
+  opened, or one inside it (after realpath), starts; anything else is refused.
+  `prohost agent code-host folders add|list|remove` keeps the opened folders
+  (`code-host/folders.json`); the status frame reports them as
+  `code_host_folders` with `code_host_home`, and the host declares
+  `code_thread_folders`. A shell in an opened folder starts with `remote off`.
+- **Folder threads, follow-ups.** A separate copy refuses a subfolder its
+  branch doesn't have, and one that resolves outside the new worktree (a
+  symlink on that branch), instead of starting in the worktree's root or in
+  the owner's files. Changes to `folders.json` (`folders add`/`remove`, a
+  start moving its folder to the front) take an inter-process lock, so two at
+  once never drop a folder. The tmux server and every pane no longer inherit
+  `ELECTRON_RUN_AS_NODE` / `PROHOST_CLI_RUN` from a daemon the desktop app runs
+  on Electron; the hook shim sets `ELECTRON_RUN_AS_NODE=1` for itself only.
+- **The desktop app attaches locally with `remote off`.** The 127.0.0.1 socket
+  and `local.json` are served whenever hosting is on; with the remote switch
+  off they admit only a viewer token the relay vouches for as `local`, and
+  `remote off` ends every other desktop viewer. `code-host disable` closes the
+  socket at once.
+
+## 0.13.3
+
+- **Every turn the agent answers in reaches the thread.** When a command the
+  agent ran in the background (or one Claude Code moved to the background at
+  its two-minute timeout) is still running as the agent ends its turn, Claude
+  Code keeps the session alive and wakes it with another turn when the command
+  finishes. The CLI posted only the last turn, so a follow-up that said
+  `[NO_REPLY]`, or just "nothing in my earlier reply changes", replaced the real
+  answer: 3 of the Customer Support Bot's 155 runs lost theirs that way. A turn
+  that ends while a background task is still running is now posted as soon as
+  it ends ("the review is still running; I'll post the result"), each under an
+  idempotency key of its own (`prohost-cli-run-<run>-turn-<n>`). The run's last
+  turn is posted as before, under the run's key. A later `[NO_REPLY]` or a
+  repeat of the previous answer takes back nothing; a last turn that fails
+  (a usage limit) is still reported as the run's failure. Posts go strictly in
+  order: one the server refuses is retried under its own key and holds back
+  the rest (if it never lands, the run fails as a rejected reply does), and
+  nothing more is posted once the run is cancelled. A run that ends in one turn
+  is unchanged.
+
 ## 0.13.2
 
 - **A run stopped by the Claude usage limit tells ProhostAI when the limit

package/README.md

@@ -632,8 +632,137 @@ workspace's `.claude/`: a skill that points it at the repo's PR protocol
 the `gh pr create` gate hook the fleet uses. Nothing else about the default
 workspace changes.
 
+### Hosting Code threads on this Mac (off by default)
+
+ProhostAI can show agent terminals — Claude Code, Codex or a plain shell — as
+**Code** threads in the inbox. This machine can host them, but only once its
+owner says so, here, on this machine. Nothing the server sends can turn it on.
+
+```bash
+prohost agent code-host enable                 # host Code threads (needs --repos on agent run)
+prohost agent code-host remote on              # also let *you* attach and type from ProhostAI
+prohost agent code-host status
+prohost agent code-host remote off             # refuses the next viewer at once
+prohost agent code-host disable
+
+prohost agent code-host folders add ~/code/app # open a folder for Code threads (the desktop app does this)
+prohost agent code-host folders list [--json]
+prohost agent code-host folders remove ~/code/app
+```
+
+Restart `agent run` (or the daemon) after `enable` / `disable`.
+
+**Host only: Code threads without an agent that answers.** `prohost agent run
+--host-only` (or `install-daemon --host-only`) takes no `--exec`. It keeps
+everything hosting needs — the connection, presence, status, the desktop
+app's local socket, `activity.json` — and executes nothing anyone sends: every
+run requested of this agent (a mention, a DM) is closed at once as failed with
+"This computer only hosts Code threads; it doesn't answer messages." It
+declares the `host_only` capability. `--host-only` and `--exec` can't be used
+together, and `prohost --help` lists `--host-only` on builds that have it. A
+host-only agent runs no agent of its own, so it has no account: its Code
+threads run Claude Code or Codex on this Mac's default login, as a terminal you
+opened would (`--account` is refused with `--host-only`, and an account already
+on the pairing is reported as unused at start). The
+desktop app's "This Mac" daemon runs this way.
+
+- **Folder threads, in place.** A thread can also run in a folder instead of a
+  repository: in that folder itself, with no worktree and no branch, the way a
+  terminal you open there would. The desktop app's folder picker adds what you
+  pick to this Mac's **opened folders** (`folders add`;
+  `$PROHOST_HOME/code-host/folders.json`, `0600`, the 50 most recent, each
+  stored as its realpath). A thread started from anywhere else — your phone,
+  the web — may only run in one of those folders or a folder inside one,
+  checked after resolving symlinks, so a link that points out of an opened
+  folder does not count as inside it. Anything else is refused with "This
+  folder hasn't been opened on this Mac." A thread that starts moves its
+  folder to the front of the list. The list (with whether each is a git
+  repository, and your home directory for showing `~/…`) is reported to
+  ProhostAI so your phone can offer it; `--repos` is not needed for folders.
+- **Work in a separate copy.** For a folder in a git repository, a thread can
+  instead get its own worktree and branch of that checkout, exactly as a
+  repository thread does, opened in the same subfolder. Your checkout is never
+  switched. A folder outside git can't, and says so; neither can a subfolder
+  the branch doesn't have (untracked or ignored) or one that is a link out of
+  the copy on that branch — the thread is refused, never started elsewhere.
+- **The goal is optional.** A thread with no goal opens Claude Code or Codex
+  with no prompt, or just the shell.
+
+- **One worktree and one tmux window per repository thread.** The repository is matched
+  against `--repos` by its `origin` remote (else by directory name), checked out
+  under `$PROHOST_HOME/worktrees/`, and switched to the thread's branch. The
+  windows live in a private tmux server (`tmux -L prohost-<id>`; your own tmux
+  is untouched), so they survive the agent restarting and are re-adopted. You
+  need `tmux` installed (`brew install tmux`).
+- **Hooks without touching your config.** Claude Code is started with
+  `--settings` and Codex with `-c notify=…`, naming a shim that does nothing
+  unless `$PROHOST_TERMINAL_ID` is set — your own `claude` sessions never see
+  them, and `~/.claude` / `~/.codex` are never written. They report the prompt,
+  the end of each turn, permission prompts and Esc/Ctrl+C to the thread, using a
+  narrow token the relay issues (`$PROHOST_HOME/code-host/hook.json`, `0600`,
+  expires in a day) — never your API key, never a Claude or Codex credential.
+  ProhostAI saves the conversation, not your terminal. An Allow / Deny chosen in
+  ProhostAI answers the prompt in the terminal (Enter, Down+Enter, Escape) —
+  only if that prompt is still the one on screen.
+- **Reply recovery after a permission menu.** New Claude Code windows check
+  the installed version before choosing their hooks. Claude Code 2.1.295 or
+  newer records tool invocation IDs before permission processing; replies can
+  resume when the transcript confirms those calls finished. Recording failures
+  block the request. Older or unverifiable versions, already-running windows,
+  and subagent permission prompts wait for a new user prompt or a completed
+  turn when the menu's outcome is uncertain. Start a new window after upgrading
+  to use the invocation hooks.
+  Keep the daemon running: it reports verified completion back to the thread,
+  including after the waiting hook exits, and retries reports after reconnect.
+- **Replies from ProhostAI go to the agent, never to a shell.** Typing a reply
+  or an Allow / Deny into a terminal from ProhostAI needs `remote on`, read at
+  every event. It reaches only a running Claude Code or Codex: never a shell
+  thread, and never the shell an agent leaves behind when it exits. Starting a
+  shell thread for a repository also needs `remote on`; a shell in an opened
+  folder starts with it off, where only the desktop app on this Mac can type
+  into it. A reply or decision that is redelivered
+  after a reconnect is never typed twice. A goal is always passed after `--`,
+  so it can't become an option.
+- **A remote terminal is remote code execution on this Mac.** With `remote on`,
+  the machine's owner (whoever paired it) — and nobody else — can attach from the
+  web, phone or desktop app and type. Off, the relay refuses every viewer and
+  this machine refuses every dial. Terminal bytes are relayed, never stored.
+- **The desktop app on this Mac attaches over `127.0.0.1`**, not the relay,
+  whenever hosting is on — with `remote off` too. The socket's port and token
+  are in `$PROHOST_HOME/code-host/local.json` (`0600`, new every start; removed
+  by `disable` at once). Any request with an `Origin` header — every browser —
+  is refused, and every attach's viewer token is checked with the relay, which
+  vouches for who it is. With `remote off` it admits only a token ProhostAI
+  minted for this Mac's own desktop app, which the relay refuses for any
+  relayed attach; `remote off` ends every other viewer at once.
+- **Whether an agent is working, for keep-awake.** While hosting, the daemon
+  keeps `$PROHOST_HOME/code-host/activity.json` (`0600`, written atomically):
+  `{"v":1,"busy":true|false,"updatedAt":"<ISO>"}`. `busy` is true while any
+  thread's agent is mid-turn: from Claude Code's prompt to its `Stop`, from a
+  goal or a reply (not a `/` command) this Mac types to Codex's turn-complete, ended early by Esc
+  or Ctrl+C in an attached terminal, and never for longer than 6 hours per
+  turn. The file is rewritten at least every 30 s and removed when hosting
+  stops. **A reader must treat an `updatedAt` older than about 3 minutes as
+  not busy**, so a daemon that died never keeps the Mac awake. The desktop
+  app's "Keep this Mac awake while an agent is working" reads it. A prompt
+  typed straight into a Codex terminal isn't seen until that turn ends.
+- **Attaching needs `node-pty`**, an optional dependency with prebuilt macOS
+  binaries. Where it doesn't load, threads still run; only attaching answers
+  `pty_unavailable`.
+- While hosting, the heartbeat also reports this machine's CPU, memory,
+  memory pressure, battery and model (`vm_stat`, `sysctl`, `pmset`) for the
+  thread's Machine card.
+
 ### The trust model — read this once
 
+**`--host-only` is the exception: it runs nothing anyone sends.** No message,
+mention or DM executes a command on a host-only machine; each requested run is
+refused. What it does run are Code-thread terminals, and only as described
+under "Hosting Code threads on this Mac": a thread starts only in a repository
+from `--repos` or a folder this Mac has opened; nothing from ProhostAI types
+into one without `remote on`; with `remote off` only the desktop app on this
+Mac attaches; and only the pairing's owner can attach at all.
+
 `agent run` is a standing instruction to execute a command on your machine when
 someone in your ProhostAI workspace asks. Be clear-eyed about what that means:
 

package/dist/agent/claude.d.ts

@@ -171,6 +171,13 @@ export interface ClaudeStream {
      * that isn't Claude Code's at all.
      */
     drainToolEvents(): ToolEvent[];
+    /**
+     * Answers from turns that ended while a background task was still running —
+     * turns another can follow — in order, since the last call. Taken, not
+     * copied: {@link finish} no longer includes them. Empty for a run that ends
+     * in one turn, which is every run that starts no background task.
+     */
+    takeEarlyAnswers(): string[];
     /**
      * Model, Claude Code version and capacity windows the stream announced —
      * `system/init.{model, claude_code_version}` and the last
@@ -237,6 +244,27 @@ export declare function toolArgsPreview(name: string, input: unknown): string |
  * vocabulary belongs to Claude Code and grows without asking us, and a reader
  * that failed on an unknown `type` would turn a Claude Code release into a
  * fleet of broken laptops.
+ *
+ * **One invocation, several turns.** A run usually ends in one `result`
+ * event. It ends in more when a background task — a Bash
+ * `run_in_background`, or a command Claude Code moved to the
+ * background at its two-minute timeout — is still running when the agent ends
+ * its turn: Claude Code keeps the process alive, wakes the session with the
+ * task's notification when it finishes, and runs another turn that ends in a
+ * `result` of its own. The agent writes each of those turns as a message to the
+ * thread ("the review is still running, I'll post the result when it lands";
+ * "nothing in my earlier reply changes"), so each one that answers is a message
+ * of its own. Reading only the last event lost the answer three times in 155
+ * Customer Support Bot runs: twice to a trailing "nothing else changed", once
+ * (2026-10-22, Claude Code 2.1.308) to a trailing `[NO_REPLY]`.
+ *
+ * A turn that ends while a background task is still running can be followed by
+ * another, so it is handed out at once ({@link ClaudeStream.takeEarlyAnswers})
+ * for the harness to post while the run goes on. Whatever answered and was not
+ * taken is the run's reply from {@link ClaudeStream.finish}. Any answer
+ * followed by another turn is early too: it is not the run's last word.
+ * `[NO_REPLY]` and a repeat of the answer before take back nothing that was
+ * already said; a last turn that failed is still the run's outcome.
  */
 export declare function readClaudeStream(): ClaudeStream;
 /**

package/dist/agent/claude.js

@@ -17,6 +17,7 @@
 import { randomBytes } from 'node:crypto';
 import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { NO_REPLY_TOKEN, isNoReply } from './contract.js';
 import { prohostHome } from './credentials.js';
 import { MCP_SERVER_NAME } from './mcp.js';
 import { fromClaudeRateLimitInfo } from './runtime_status.js';
@@ -458,13 +459,45 @@ function toolResultText(content) {
  * vocabulary belongs to Claude Code and grows without asking us, and a reader
  * that failed on an unknown `type` would turn a Claude Code release into a
  * fleet of broken laptops.
+ *
+ * **One invocation, several turns.** A run usually ends in one `result`
+ * event. It ends in more when a background task — a Bash
+ * `run_in_background`, or a command Claude Code moved to the
+ * background at its two-minute timeout — is still running when the agent ends
+ * its turn: Claude Code keeps the process alive, wakes the session with the
+ * task's notification when it finishes, and runs another turn that ends in a
+ * `result` of its own. The agent writes each of those turns as a message to the
+ * thread ("the review is still running, I'll post the result when it lands";
+ * "nothing in my earlier reply changes"), so each one that answers is a message
+ * of its own. Reading only the last event lost the answer three times in 155
+ * Customer Support Bot runs: twice to a trailing "nothing else changed", once
+ * (2026-10-22, Claude Code 2.1.308) to a trailing `[NO_REPLY]`.
+ *
+ * A turn that ends while a background task is still running can be followed by
+ * another, so it is handed out at once ({@link ClaudeStream.takeEarlyAnswers})
+ * for the harness to post while the run goes on. Whatever answered and was not
+ * taken is the run's reply from {@link ClaudeStream.finish}. Any answer
+ * followed by another turn is early too: it is not the run's last word.
+ * `[NO_REPLY]` and a repeat of the answer before take back nothing that was
+ * already said; a last turn that failed is still the run's outcome.
  */
 export function readClaudeStream() {
     let buffer = '';
     let session;
     let lastActivity;
     let lastText;
+    /** The last `result` event: what decides a run in which no turn answered. */
     let result;
+    /** Answered turns not yet handed out, in order, and whether another turn can follow each. */
+    const answers = [];
+    /** Whether any turn answered, handed out or not. */
+    let answered = false;
+    /** The last answer, so a turn that only repeats it is not said twice. */
+    let lastAnswer;
+    /** Every turn's refused tools, for the run's report. */
+    const denials = new Set();
+    /** Background tasks running as of the last `background_tasks_changed`. */
+    let backgroundTasks = 0;
     /** The last `assistant` event that was an API error rather than an answer. */
     let apiError;
     /** When a `rate_limit_event` said the limit is hit: its reset, epoch seconds. */
@@ -563,8 +596,26 @@ export function readClaudeStream() {
         // from whichever arrives first — they all name the same session.
         if (!session)
             session = text(event.session_id);
+        if (event.type === 'system' && event.subtype === 'background_tasks_changed' && Array.isArray(event.tasks)) {
+            backgroundTasks = event.tasks.length;
+        }
         if (event.type === 'result') {
+            // One per turn: see "One invocation, several turns" above.
             result = event;
+            const turn = outputFromEnvelope(event);
+            for (const name of turn.denials)
+                denials.add(name);
+            // Another turn ended, so no answer before it is the run's last word.
+            for (const answer of answers)
+                answer.early = true;
+            if (turn.ok && !isNoReply(turn.text)) {
+                // Kept as written, so a one-turn run's reply is byte for byte what it was.
+                const said = turn.text.trim();
+                if (said !== lastAnswer)
+                    answers.push({ text: turn.text, early: backgroundTasks > 0 });
+                lastAnswer = said;
+                answered = true;
+            }
             return;
         }
         if (event.type === 'user') {
@@ -595,6 +646,24 @@ export function readClaudeStream() {
         else if (written)
             lastActivity = written.replace(/\s+/g, ' ').trim().slice(0, MAX_ACTIVITY_CHARS);
     };
+    /** The run's outcome from its turns; only meaningful once a `result` arrived. */
+    const outcome = (last) => {
+        const final = outputFromEnvelope(last);
+        // A last turn that failed is the run's outcome even after an answer — a
+        // usage limit must still say when to try again. Every answer before it was
+        // handed out early the moment this turn ended.
+        if (!answered || !final.ok)
+            return final;
+        const sessionId = final.sessionId ?? session;
+        // Everything still unsaid, or — when all of it was handed out early — the
+        // token that says this turn adds nothing.
+        const text = answers.length === 1
+            ? answers[0].text
+            : answers.length > 0
+                ? answers.map((answer) => answer.text.trim()).join('\n\n')
+                : NO_REPLY_TOKEN;
+        return { ok: true, text, sessionId, denials: [...denials] };
+    };
     /** A trailing event with no newline after it is still an event. */
     const flushTail = () => {
         const tail = buffer.trim();
@@ -628,6 +697,16 @@ export function readClaudeStream() {
             toolEvents = [];
             return drained;
         },
+        takeEarlyAnswers: () => {
+            // Up to the last turn another can follow: an answer before it is just as
+            // surely not the run's last word, and order is the thread's order.
+            let through = -1;
+            answers.forEach((answer, index) => {
+                if (answer.early)
+                    through = index;
+            });
+            return answers.splice(0, through + 1).map((answer) => answer.text);
+        },
         observed: () => ({ ...observed }),
         salvage: () => {
             const trimmed = lastText?.trim();
@@ -638,9 +717,9 @@ export function readClaudeStream() {
         error: () => {
             flushTail();
             if (result) {
-                const outcome = outputFromEnvelope(result);
-                if (!outcome.ok)
-                    return outcome.error;
+                const turned = outcome(result);
+                if (!turned.ok)
+                    return turned.error;
             }
             return apiError?.text;
         },
@@ -664,7 +743,7 @@ export function readClaudeStream() {
             // result.
             flushTail();
             if (result)
-                return outputFromEnvelope(result);
+                return outcome(result);
             // No `result` event: either the command isn't emitting the stream we
             // asked for, or it died before finishing. Either way the whole-output
             // parser gives the better error message, and it still understands a

package/dist/agent/command.d.ts

@@ -57,4 +57,12 @@ export declare function parseConcurrency(raw: string | boolean | undefined): num
 export declare function daemonEnvironment(): Record<string, string>;
 /** Dispatch an ``agent`` subcommand. Returns the process exit code. */
 export declare function runAgent(subcommand: string | undefined, flags: Flags, printHelp: () => void, args?: string[]): Promise<number>;
+/**
+ * `--exec <command>` or `--host-only`, exactly one: what this harness does with a run. `null`
+ * after explaining why not. Host-only runs nothing anyone sends; it only hosts Code threads.
+ */
+export declare function execOrHostOnly(flags: Flags, verb: 'run' | 'install-daemon'): {
+    exec: string;
+    hostOnly: boolean;
+} | null;
 export {};

package/dist/agent/command.js

@@ -20,6 +20,8 @@ import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome,
 import { DEFAULT_EXEC_TIMEOUT_MS, DEFAULT_IDLE_TIMEOUT_MS, runAgentHarness } from './run.js';
 import { MAX_CONCURRENCY } from './scheduler.js';
 import { ReposFlagError, isCheckout, parseReposFlag } from './worktrees.js';
+import { codeHostCommand } from '../codehost/command.js';
+import { loadSettings as loadCodeHostSettings } from '../codehost/settings.js';
 import { announceUpgradeIfAvailable } from '../upgrade.js';
 import { DEFAULT_WS_URL } from '../listen.js';
 function flagString(flags, name) {
@@ -223,10 +225,12 @@ export async function runAgent(subcommand, flags, printHelp, args = []) {
         return listCommand();
     if (subcommand === 'workspace')
         return workspaceCommand(args, flags);
+    if (subcommand === 'code-host')
+        return codeHostCommand(args, flags);
     process.stderr.write(subcommand
         ? `Unknown agent subcommand: ${subcommand}\n\n`
         : 'Missing agent subcommand — expected `pair`, `run`, `install-daemon`, `uninstall-daemon`, ' +
-            '`account`, `list`, or `workspace`.\n\n');
+            '`account`, `list`, `workspace`, or `code-host`.\n\n');
     printHelp();
     return 1;
 }
@@ -256,12 +260,35 @@ function loadOrExplain(streamOverride) {
     }
     return credentials;
 }
-async function installDaemonCommand(flags) {
+/**
+ * `--exec <command>` or `--host-only`, exactly one: what this harness does with a run. `null`
+ * after explaining why not. Host-only runs nothing anyone sends; it only hosts Code threads.
+ */
+export function execOrHostOnly(flags, verb) {
     const exec = flagString(flags, 'exec');
+    const hostOnly = flags['host-only'] === true;
+    if (hostOnly && flags.exec !== undefined) {
+        process.stderr.write('--host-only and --exec can\'t be used together: a host-only agent runs no command.\n');
+        return null;
+    }
+    if (hostOnly && flags.account !== undefined) {
+        process.stderr.write("--host-only and --account can't be used together: a host-only agent runs no agent of its own, " +
+            "so its Code threads use this Mac's default Claude Code / Codex login.\n");
+        return null;
+    }
+    if (hostOnly)
+        return { exec: '', hostOnly: true };
     if (!exec) {
-        process.stderr.write("Missing required flag: --exec. Example: prohost agent install-daemon --exec 'claude -p'\n");
-        return 1;
+        process.stderr.write(`Missing required flag: --exec (or --host-only). Example: prohost agent ${verb} --exec 'claude -p'\n`);
+        return null;
     }
+    return { exec, hostOnly: false };
+}
+async function installDaemonCommand(flags) {
+    const mode = execOrHostOnly(flags, 'install-daemon');
+    if (!mode)
+        return 1;
+    const { exec } = mode;
     const credentials = loadOrExplain(flagString(flags, 'url'));
     if (!credentials)
         return 1;
@@ -299,6 +326,7 @@ async function installDaemonCommand(flags) {
         execPath: process.execPath,
         scriptPath: cliEntrypoint(),
         exec,
+        hostOnly: mode.hostOnly,
         workdir,
         timeoutSeconds,
         idleTimeoutSeconds,
@@ -420,10 +448,14 @@ async function pairCommand(flags) {
     return 0;
 }
 async function runCommand(flags) {
-    const exec = flagString(flags, 'exec');
-    if (!exec) {
-        process.stderr.write("Missing required flag: --exec. Example: prohost agent run --exec 'claude -p'\n");
+    const mode = execOrHostOnly(flags, 'run');
+    if (!mode)
         return 1;
+    const { exec, hostOnly } = mode;
+    if (hostOnly && !loadCodeHostSettings().enabled) {
+        // Not fatal: under a supervisor an exit would only restart into the same state.
+        process.stderr.write('! --host-only: Code-thread hosting is off on this machine (prohost agent code-host enable), ' +
+            'so this agent will refuse every run and host nothing until it is turned on and the agent restarts.\n');
     }
     const credentials = loadOrExplain(flagString(flags, 'url') ?? process.env.PROHOST_WS_URL);
     if (!credentials)
@@ -465,6 +497,7 @@ async function runCommand(flags) {
     try {
         const metrics = await runAgentHarness({
             exec,
+            hostOnly,
             credentials,
             url: flagString(flags, 'url') ?? process.env.PROHOST_WS_URL,
             machine: flagString(flags, 'machine'),

package/dist/agent/daemon.d.ts

@@ -79,8 +79,10 @@ export interface HarnessInvocation {
     execPath: string;
     /** Absolute path of the CLI entrypoint script. */
     scriptPath: string;
-    /** The `--exec` command, verbatim. */
+    /** The `--exec` command, verbatim. Unused with {@link hostOnly}. */
     exec: string;
+    /** `--host-only` instead of `--exec`: the daemon hosts Code threads and runs nothing. */
+    hostOnly?: boolean;
     workdir: string;
     timeoutSeconds?: number;
     /** Seconds of total silence before a run is treated as stalled. */

package/dist/agent/daemon.js

@@ -171,8 +171,7 @@ export function harnessArguments(invocation) {
         invocation.scriptPath,
         'agent',
         'run',
-        '--exec',
-        invocation.exec,
+        ...(invocation.hostOnly ? ['--host-only'] : ['--exec', invocation.exec]),
         '--workdir',
         invocation.workdir,
     ];

package/dist/agent/run.d.ts

@@ -28,10 +28,13 @@
  */
 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 { AgentCredentials } from './credentials.js';
 import type { RunCapabilities } from './capabilities.js';
 import type { QuotaProvider } from './runtime_status.js';
+import type { CodeHostLike } from '../codehost/host.js';
+import type { AccountEnvResult, CodeAgent } from '../codehost/terminals.js';
 /**
  * Default ceiling on one agent invocation: none.
  *
@@ -72,9 +75,20 @@ export declare const DEFAULT_IDLE_TIMEOUT_MS = 900000;
  * uses it to stop a run from sitting on CI after the PR is open.
  */
 export declare const PAIRED_RUN_ENV_VAR = "PROHOST_PAIRED_RUN";
+/** What a run sent to a `--host-only` harness is answered with: it never executes. */
+export declare 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 declare const HOST_ONLY_CAPABILITY = "host_only";
 export interface AgentRunOptions {
-    /** Shell command that runs the agent, e.g. ``claude -p``. */
+    /** Shell command that runs the agent, e.g. ``claude -p``. Empty with {@link hostOnly}. */
     exec: string;
+    /**
+     * `--host-only`: this harness hosts Code threads (control socket, presence,
+     * status, the local server, activity) and executes nothing anyone sends. Every
+     * `agent.run_requested` it receives is closed at once as failed with
+     * {@link HOST_ONLY_REFUSAL}, so a mention never hangs.
+     */
+    hostOnly?: boolean;
     credentials: AgentCredentials;
     /** Websocket endpoint override. Defaults to the paired value. */
     url?: string;
@@ -176,6 +190,12 @@ export interface AgentRunOptions {
      * inject a fake so no extra request lands in their recorded calls.
      */
     capabilityProbe?: () => Promise<RunCapabilities>;
+    /**
+     * The Code-thread host (`codehost/host.ts`). Unset, one is built only when
+     * this machine's owner turned hosting on (`prohost agent code-host enable`);
+     * `null` never hosts. Tests inject a fake.
+     */
+    codeHost?: CodeHostLike | null;
 }
 export interface AgentRunMetrics {
     connections: number;
@@ -228,5 +248,14 @@ export declare function codexMcpEntryProvider(options: AgentRunOptions, log: (li
  * 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 declare function codeThreadAccountEnv(account: HarnessAccount | undefined, agent: CodeAgent): AccountEnvResult;
 export declare function runAgentHarness(options: AgentRunOptions): Promise<AgentRunMetrics>;
 export {};