@prohost/cli 0.10.4 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,73 @@ 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>`.
 
+## 0.12.0
+
+- **`agent run` handles up to three conversations at once by default.**
+  `--concurrency` used to default to 1, so a one-line question in one thread
+  waited behind a long job in another. It now defaults to 3. Runs in the same
+  conversation still take turns, in order; only different conversations
+  overlap.
+- **This changes existing pairings on upgrade.** `install-daemon` records
+  `--concurrency` only when it was given, so a daemon installed without it
+  goes from one run at a time to three once it restarts on 0.12.0. Two things
+  follow:
+  - every run spends the same login's quota, so at busy times a subscription's
+    window is used up to three times as fast;
+  - without `--repos`, overlapping runs share every checkout on the machine.
+    Each run is told so, and told not to switch a shared checkout's branch.
+    Pass `--repos` to give each conversation its own.
+- **`--concurrency 1` is the old behaviour**, exactly: one run at a time, in
+  arrival order, and a prompt that says nothing about sharing the machine. For
+  a daemon, run `install-daemon` again with `--concurrency 1`.
+- **`--repos ~/app,~/site` means what it says.** A shell expands only the `~`
+  that starts the word, so every entry after the first used to resolve to a
+  directory named `~` under the current one. The CLI now reads a leading `~`
+  or `~/` on each entry as the home directory.
+- The startup line that reports the limit says when it is the default and how
+  to turn it off.
+
+## 0.11.0
+
+- **Pair only with the workspace you expect.** `prohost agent pair --code <c>
+  --expect-account <workspace-id>` (or `$PROHOST_EXPECT_ACCOUNT`) redeems the
+  code only if it belongs to that workspace. A pairing code doesn't say whose
+  it is, and redeeming one makes this computer that workspace's runtime, so a
+  code from somewhere unexpected could pair a computer with the wrong
+  workspace. With an expectation the CLI calls the new
+  `POST /v1/agent-pairing/redeem-bound` and nothing else:
+  - a code for another workspace is refused and left unspent, and an existing
+    pairing keeps working;
+  - a refusal is never retried on the plain endpoint. Its message covers every
+    reading of the server's one generic 404: an invalid, expired or used code,
+    a code for a different workspace, or a server without bound pairing;
+  - a value that isn't a workspace id, a bare flag, or an environment variable
+    that is set but empty stops the pairing before the code is spent.
+- **Pairing says which workspace it paired in**, and records it in `agent.json`
+  as `prohost_account: { id, name }` when the server reports it, with or
+  without `--expect-account`. `agent list` shows the name. Files written by an
+  older CLI load as before.
+- Without `--expect-account` the pairing request is byte-for-byte what 0.10.4
+  sent.
+- **A structured result for programs that run `agent pair`.** Set
+  `$PROHOST_PAIR_RESULT_FILE` to an absolute path and the CLI writes
+  `{ "version": 1, "outcome", "revoked_previous_credential", "message" }` there
+  on every exit it controls. The printed output includes names the server
+  chose, which can be worded as anything, so a program that classified a
+  pairing by searching that output could be steered by them; `outcome` and
+  `revoked_previous_credential` are set by what the CLI did instead. Outcomes:
+  `paired`, `code_rejected`, `bound_rejected`, `workspace_unconfirmed`,
+  `rate_limited`, `unreachable`, `no_subscription`, `invalid_arguments`,
+  `failed`. The file holds no pairing code, API key or signing secret and
+  nothing from `agent.json`; it is written atomically, `chmod 600`. A path
+  that isn't absolute or can't be written is a one-line warning and never
+  fails a pairing. Unset, nothing changes.
+
+To tell whether a CLI supports this without pairing: `prohost --version` is
+`0.11.0` or later, or `prohost --help` mentions `--expect-account`. An older
+CLI silently ignores the flag and the environment variable and pairs without
+the check.
+
 ## 0.10.4
 
 - **A day's rebuilt totals wait for its 0.10.1 rows to land.** If the server

package/README.md

@@ -74,6 +74,84 @@ required to receive runs.
 
 You can also pass the code as `$PROHOST_PAIRING_CODE`.
 
+#### Pairing only with the workspace you expect
+
+A pairing code doesn't say which workspace it belongs to, and redeeming one
+makes this computer that workspace's runtime. If you know which workspace you
+mean to pair with, say so, and a code for any other workspace is refused:
+
+```bash
+npx @prohost/cli agent pair --code <pairing-code> --expect-account <workspace-id>
+```
+
+`<workspace-id>` is the workspace's id (a UUID). You can pass it as
+`$PROHOST_EXPECT_ACCOUNT` instead. The ProhostAI desktop app does this for you
+with the workspace it is signed in to.
+
+- A code for another workspace is **refused and left unspent**: it stays valid
+  for whoever it belongs to, and if this computer was already paired, that
+  pairing keeps working.
+- A refusal is never retried without the check. The server answers one generic
+  404 whether the code is invalid, expired, already used, or simply for a
+  different workspace — or if it is a server that doesn't support this yet — so
+  the CLI tells you all of those and stops.
+- A value that isn't a workspace id stops the pairing before the code is spent.
+- On success the CLI prints the workspace it paired in and records it in
+  `agent.json` as `prohost_account` (`{ "id", "name" }`). Pairing without
+  `--expect-account` records it too, when the server reports it.
+
+`--expect-account` is unrelated to `--account`, which picks the Claude Code or
+Codex login an agent runs on.
+
+Needs CLI 0.11.0 or later. An older CLI ignores a flag it doesn't know and
+pairs without the check, so a script that depends on it should confirm the
+version first (`prohost --version`), or that `prohost --help` mentions
+`--expect-account`.
+
+#### If a program runs `agent pair` for you
+
+What `agent pair` prints is written for a person. It includes text the server
+chose — the agent's name, the workspace's name — and those can be anything,
+including a sentence this CLI prints itself. So a program must not decide what
+happened by searching the output. Set `$PROHOST_PAIR_RESULT_FILE` to an
+absolute path and read the JSON the CLI writes there instead:
+
+```json
+{ "version": 1, "outcome": "paired", "revoked_previous_credential": false, "message": "Paired." }
+```
+
+| `outcome` | What happened |
+| --- | --- |
+| `paired` | The code was redeemed and the credential stored. |
+| `code_rejected` | Pairing without `--expect-account` got a 404: the code is invalid, expired or already used. |
+| `bound_rejected` | Pairing with `--expect-account` got a 404: any of the above, or the code is for another workspace, or the server has no workspace-bound pairing. Not retried without the check. |
+| `workspace_unconfirmed` | Pairing with `--expect-account` succeeded, but the answer did not name the expected workspace. The code is spent; nothing was saved. |
+| `rate_limited` | Too many attempts from this IP. |
+| `unreachable` | The request got no answer. |
+| `no_subscription` | Redeemed, but no event subscription was provisioned. The code is spent; nothing was saved. |
+| `invalid_arguments` | Stopped before the code was spent: a missing code, a flag with no value, an expectation that isn't a workspace id (or is set but empty), a refused URL, an unknown `--account`. |
+| `failed` | Anything else. |
+
+- `outcome` and `revoked_previous_credential` are set by what the CLI did, never
+  worked out from any text.
+- `revoked_previous_credential` is `true` exactly when this run found the
+  credential stored for the same agent already revoked by the redeem and
+  removed it from disk.
+- `message` is what the CLI said about the outcome, for display only. It can
+  contain server-chosen text; don't parse it. On `paired` it is the fixed
+  string `Paired.`
+- The file never contains the pairing code, the API key (not even its masked
+  prefix), the signing secret, or anything from `agent.json`.
+- It is written on every exit `agent pair` controls, atomically (a temp file
+  beside it, then a rename) and `chmod 600`, replacing whatever was at the
+  path. The directory must already exist.
+- It never changes what pairing does. A path that isn't absolute, or one that
+  can't be written, is a one-line warning on stderr and nothing more. Without
+  the variable, nothing is written and the output is unchanged.
+
+The names live in `src/agent/pair_result.ts` (`PAIR_RESULT_FILE_ENV`,
+`PAIR_RESULT_VERSION`, `PAIR_OUTCOMES`).
+
 ### 3. Run
 
 ```bash
@@ -435,9 +513,9 @@ on the machine via `ps` and a process environment is not. Literal `headers`,
 treatment: the CLI translates them to Codex's environment-indirection fields,
 so their values do not appear in process arguments.
 
-Runs are handled one at a time unless you raise `--concurrency` (see "Running
-several conversations at once"), and each run executes **at most once on this
-machine** — even across restarts. Started runs are recorded in
+Up to three runs are handled at once, in different conversations (see "Running
+several conversations at once"; `--concurrency 1` is one at a time), and each
+run executes **at most once on this machine** — even across restarts. Started runs are recorded in
 `~/.prohost/runs.json` before the command launches, so a webhook redelivery
 that arrives after a crash or restart will close the run out rather than run
 your agent a second time. That matters because your agent holds a credential:
@@ -491,21 +569,30 @@ naming the pid that holds `$PROHOST_HOME/run.lock`.
 
 ### Running several conversations at once
 
-By default a second request waits for the first, however unrelated they are —
-a one-line question in one thread sits behind a two-hour job in another.
-`--concurrency <n>` (1 to 16) lets up to `n` runs execute at once:
+Up to three runs execute at once, so a one-line question in one thread does
+not sit behind a two-hour job in another. `--concurrency <n>` (1 to 16) sets
+the limit:
 
 ```bash
-prohost agent run --exec 'claude -p' --concurrency 3 --repos ~/code/app,~/code/site
+prohost agent run --exec 'claude -p' --concurrency 5 --repos ~/code/app,~/code/site
 ```
 
+`--concurrency 1` is one run at a time, in the order they arrived — what every
+version before 0.12.0 did unless told otherwise.
+
 - **Runs in the same conversation still take turns, in order.** Each turn
   resumes the session the last one left, so two turns of one thread never
   overlap. Only different conversations run side by side.
 - **Every run spends the same login's quota.** Three runs at once use a
-  subscription's 5-hour window about three times as fast. Start small.
+  subscription's 5-hour window about three times as fast. Lower the limit if
+  the window runs out at busy times.
 - **They share the machine.** The agent is told other runs may be executing
-  beside it. If it edits code, also pass `--repos`.
+  beside it and, without `--repos`, that no git checkout is its own. If it
+  edits code, pass `--repos`.
+- **A daemon follows the default.** `install-daemon` records `--concurrency`
+  only when you give it, so a daemon installed without it runs three at once
+  after upgrading to 0.12.0 and restarting. Reinstall with `--concurrency 1`
+  to keep it at one.
 
 `--repos` takes a comma-separated list of git checkouts the agent works on.
 Each conversation then gets its own `git worktree` of every one, at
@@ -523,7 +610,7 @@ original repository and are never touched. Each worktree is a full working
 copy, and dependencies installed inside it are not shared, so budget disk for
 it.
 
-`--repos` works without `--concurrency` too. If a checkout cannot be made (a
+`--repos` works at any `--concurrency`, 1 included. If a checkout cannot be made (a
 full disk, a path that is no longer a repository), the run still happens: the
 agent is told to treat that repository as read-only for the run.
 
@@ -581,7 +668,7 @@ same judgement.
 | `--exec` | *(required)* | Command to run for each requested run. Prompt arrives on stdin. |
 | `--idle-timeout` | `900` | Seconds a run may produce **no output at all** before it is treated as stalled and killed. Any byte on stdout or stderr resets it. `0` disables it — see "Long runs". |
 | `--timeout` | `0` | Seconds one run may take before the command is killed, however busy it is. `0` — the default — means no wall-clock limit. Set it if you want a hard ceiling as well. |
-| `--concurrency` | `1` | How many runs may execute at once (1–16). Runs in one conversation always take turns. See "Running several conversations at once". |
+| `--concurrency` | `3` | How many runs may execute at once (1–16); `1` is one at a time. Runs in one conversation always take turns. See "Running several conversations at once". |
 | `--repos` | — | Comma-separated git checkouts the agent works on. Each conversation gets its own worktree of every one. |
 | `--dry-run` | off | Print the reply that would be posted; write nothing. |
 | `--workdir` | `~/.prohost/workspace` | Working directory for the command. See "Where your agent runs". |
@@ -682,6 +769,7 @@ decision to make.
 | Flag | Default | What it does |
 | --- | --- | --- |
 | `--code` | `$PROHOST_PAIRING_CODE` | The one-time pairing code. |
+| `--expect-account` | `$PROHOST_EXPECT_ACCOUNT` | Pair only if the code belongs to this workspace (its id). A code for any other workspace is refused and left unspent, and the pairing is never retried without the check. |
 | `--account` | the home's current account, else `default` | Which Claude Code / Codex login this agent runs on (see Accounts). |
 | `--webhook-url` | none | Also push events to this HTTPS endpoint. Omit for stream-only, which is the normal laptop setup. |
 | `--base-url` | `https://connect.prohost.ai` | Public API base. Must be `https://`; `http://` only for `localhost`, `127.0.0.1` and `[::1]`. `agent run` refuses an `agent.json` whose API, MCP or stream URL is plain http/ws off loopback. |
@@ -702,6 +790,8 @@ has real credentials.
 | `No paired agent found` | Run `prohost agent pair --code <code>` first. |
 | `no event subscription was provisioned` | Pairing half-failed server-side and nothing was saved. The code is spent — generate a fresh one and pair again. |
 | `Pairing code is invalid, expired, or already used` | Codes are single-use with a 15-minute life. Generate a fresh one. |
+| `Pairing was refused, and nothing was paired` | You paired with `--expect-account` (or the desktop app did). The code is invalid, expired or used; or it belongs to a different workspace than the one expected; or the server doesn't support workspace-bound pairing yet. Generate a fresh code in the workspace you mean to pair with. Don't retry without the check unless you trust where the code came from. |
+| `must be a workspace id` | `--expect-account` / `$PROHOST_EXPECT_ACCOUNT` was given something that isn't a workspace id (a UUID), or was set but empty. Nothing was sent. |
 | `auth_error: invalid_api_key` | The connection was revoked in ProhostAI. Re-pair. |
 | `auth_error: insufficient_scope` | The credential isn't allowed to stream events — ask your ProhostAI admin to re-issue the pairing. |
 | `auth_error: stream_subscription_unavailable` | The connection has no event subscription to stream. Re-pair. |

package/dist/agent/command.js

@@ -15,6 +15,7 @@ import { AccountError, loadAccounts, setAgentAccount } from './accounts.js';
 import { storedCredentialsProblem } from './base-url.js';
 import { acquireRunLock } from './lock.js';
 import { PairError, runPair } from './pair.js';
+import { PAIR_RESULT_VERSION, withoutCode, writePairResult } from './pair_result.js';
 import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome, streamUrlFor, tryLoadCredentials, } from './credentials.js';
 import { DEFAULT_EXEC_TIMEOUT_MS, DEFAULT_IDLE_TIMEOUT_MS, runAgentHarness } from './run.js';
 import { MAX_CONCURRENCY } from './scheduler.js';
@@ -345,49 +346,78 @@ async function uninstallDaemonCommand() {
 }
 async function pairCommand(flags) {
     const code = flagString(flags, 'code') ?? process.env.PROHOST_PAIRING_CODE;
-    if (!code) {
-        process.stderr.write('Missing pairing code. Pass --code or set $PROHOST_PAIRING_CODE.\n');
+    // For a program that launched this: what happened, as a fact set by the
+    // branch that ran — written to `$PROHOST_PAIR_RESULT_FILE` when that is set,
+    // and nothing at all when it is not. See `pair_result.ts`.
+    const report = (outcome, message, revokedPreviousCredential = false) => writePairResult({
+        version: PAIR_RESULT_VERSION,
+        outcome,
+        revoked_previous_credential: revokedPreviousCredential,
+        message: withoutCode(message, code),
+    });
+    /** Stop before the code is spent: say why, record it, exit 1. */
+    const refuse = (line) => {
+        process.stderr.write(`${line}\n`);
+        report('invalid_arguments', line.replace(/^✗\s*/, ''));
         return 1;
-    }
+    };
+    if (!code)
+        return refuse('Missing pairing code. Pass --code or set $PROHOST_PAIRING_CODE.');
     // Checked before the code is spent: a typo here must not cost a pairing.
     const account = flagString(flags, 'account');
-    if (flags.account === true) {
-        process.stderr.write('--account needs a label, e.g. --account work\n');
-        return 1;
-    }
+    if (flags.account === true)
+        return refuse('--account needs a label, e.g. --account work');
     // A re-pair keeps the account the home already runs on unless told otherwise.
     const previousAccount = tryLoadCredentials()?.account;
-    if (account && !accountExists(account))
-        return 1;
+    const accountProblem = account ? unknownAccountProblem(account) : undefined;
+    if (accountProblem)
+        return refuse(accountProblem);
+    // The workspace this computer expects the code to belong to. Once asked for
+    // — by flag or by environment, with or without a usable value — the pairing
+    // is workspace-bound or it does not happen: a bare flag stops here, and an
+    // empty or malformed value is refused by `runPair` before the code is spent.
+    // It is never dropped in favour of an unbound pairing.
+    if (flags['expect-account'] === true) {
+        return refuse('--expect-account needs a workspace id, e.g. --expect-account 0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b');
+    }
+    const expectAccount = flagString(flags, 'expect-account') ?? process.env.PROHOST_EXPECT_ACCOUNT;
     try {
         await runPair({
             code,
             baseUrl: flagString(flags, 'base-url'),
             wsUrl: flagString(flags, 'url') ?? process.env.PROHOST_WS_URL,
             webhookUrl: flagString(flags, 'webhook-url'),
+            expectAccount,
         });
-        const chosen = account ?? previousAccount;
-        if (chosen) {
-            try {
-                setAgentAccount(chosen, undefined);
-                process.stdout.write(`  Account      ${chosen}\n`);
-            }
-            catch (err) {
-                // Paired either way; only the carried-over account is gone.
-                if (!(err instanceof AccountError))
-                    throw err;
-                process.stderr.write(`! ${err.message} This agent will use the default login.\n`);
-            }
-        }
-        return 0;
     }
     catch (err) {
         if (err instanceof PairError) {
             process.stderr.write(`✗ ${err.message}\n`);
+            report(err.outcome, err.message, err.revokedPreviousCredential);
             return 1;
         }
+        report('failed', 'Pairing failed unexpectedly.');
         throw err;
     }
+    // Recorded now, before the login step below: the pairing is done and stored,
+    // and nothing that follows can unsay it. Deliberately says nothing else —
+    // the agent and workspace are in `agent.json`, and a result file that
+    // repeated them would be one more place for a credential-adjacent fact.
+    report('paired', 'Paired.');
+    const chosen = account ?? previousAccount;
+    if (chosen) {
+        try {
+            setAgentAccount(chosen, undefined);
+            process.stdout.write(`  Account      ${chosen}\n`);
+        }
+        catch (err) {
+            // Paired either way; only the carried-over account is gone.
+            if (!(err instanceof AccountError))
+                throw err;
+            process.stderr.write(`! ${err.message} This agent will use the default login.\n`);
+        }
+    }
+    return 0;
 }
 async function runCommand(flags) {
     const exec = flagString(flags, 'exec');
@@ -462,20 +492,19 @@ async function runCommand(flags) {
         lock.release();
     }
 }
-/** Whether an account label exists on this machine (any runtime), explaining if not. */
-function accountExists(label) {
+/** What to say when an account label is not on this machine (any runtime); `undefined` when it is. */
+function unknownAccountProblem(label) {
     if (label === 'default')
-        return true;
+        return undefined;
     try {
         // Validates only; the write happens once pairing has succeeded.
         if (loadAccounts().some((a) => a.label === label))
-            return true;
+            return undefined;
     }
     catch {
         /* fall through */
     }
-    process.stderr.write(`✗ No account named "${label}" on this machine. Add it first: prohost agent account add ${label} --runtime claude|codex\n`);
-    return false;
+    return `✗ No account named "${label}" on this machine. Add it first: prohost agent account add ${label} --runtime claude|codex`;
 }
 /** `--account <label>` on install-daemon: persist it to agent.json. */
 function applyAccountFlag(flags) {

package/dist/agent/contract.d.ts

@@ -16,6 +16,7 @@
  *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/events` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
+ *   - `POST /v1/agent-pairing/redeem-bound` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
 /** Default host for the public API (`api_public`, mounted under `/v1`). */
@@ -103,6 +104,17 @@ export interface ToolEvent {
 }
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export declare const REDEEM_PATH = "/v1/agent-pairing/redeem";
+/**
+ * `POST` — the same exchange, but only if the code belongs to the workspace
+ * named in `expected_account_id`. A code for any other workspace answers the
+ * same generic 404 as an unknown one and is not consumed.
+ *
+ * A separate path on purpose, so it fails closed: a server that predates it
+ * answers 404 and nothing is redeemed, where an older `/redeem` would ignore
+ * an unknown field and redeem unbound. So a 404 here must NEVER be retried on
+ * {@link REDEEM_PATH}.
+ */
+export declare const REDEEM_BOUND_PATH = "/v1/agent-pairing/redeem-bound";
 /** `POST` — send a message into a conversation as the paired agent. */
 export declare function conversationMessagesPath(conversationId: string): string;
 /** `POST` — close out a run. Must be called for every run, success or not. */

package/dist/agent/contract.js

@@ -16,6 +16,7 @@
  *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/events` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
+ *   - `POST /v1/agent-pairing/redeem-bound` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
 /** Default host for the public API (`api_public`, mounted under `/v1`). */
@@ -81,6 +82,17 @@ export const MAX_PROGRESS_CHARS = 200;
 export const MAX_TOOL_EVENTS_PER_BATCH = 50;
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export const REDEEM_PATH = '/v1/agent-pairing/redeem';
+/**
+ * `POST` — the same exchange, but only if the code belongs to the workspace
+ * named in `expected_account_id`. A code for any other workspace answers the
+ * same generic 404 as an unknown one and is not consumed.
+ *
+ * A separate path on purpose, so it fails closed: a server that predates it
+ * answers 404 and nothing is redeemed, where an older `/redeem` would ignore
+ * an unknown field and redeem unbound. So a 404 here must NEVER be retried on
+ * {@link REDEEM_PATH}.
+ */
+export const REDEEM_BOUND_PATH = '/v1/agent-pairing/redeem-bound';
 /** `POST` — send a message into a conversation as the paired agent. */
 export function conversationMessagesPath(conversationId) {
     return `/v1/conversations/${encodeURIComponent(conversationId)}/messages`;

package/dist/agent/credentials.d.ts

@@ -10,6 +10,15 @@ export interface StoredAgent {
     name: string;
     user_id: string;
 }
+/**
+ * The ProhostAI workspace an agent is paired in, as the server named it when
+ * the code was redeemed.
+ */
+export interface ProhostAccount {
+    id: string;
+    /** ``null`` for a workspace that has no name. */
+    name: string | null;
+}
 export interface AgentCredentials {
     /** Schema version, so a future format change can migrate rather than crash. */
     version: number;
@@ -43,6 +52,17 @@ export interface AgentCredentials {
      * — see `accounts.ts`. Absent means the CLI's own default login.
      */
     account?: string;
+    /**
+     * The ProhostAI workspace this agent was paired in. Not to be confused with
+     * `account` above, which is a login on this machine and predates this field
+     * — nor with a "paired account", which on the server also means such a
+     * login. Hence `prohost_account`: the account on ProhostAI's side.
+     *
+     * Written by pairing since 0.11.0, from what the server reported. Absent in
+     * a file written by an older CLI, or paired against a server that did not
+     * say — nothing reads it to make a decision, so an absent one is fine.
+     */
+    prohost_account?: ProhostAccount;
 }
 /**
  * On-disk credential schema version.

package/dist/agent/daemon.d.ts

@@ -90,7 +90,10 @@ export interface HarnessInvocation {
     allowUnverified?: boolean;
     /** Gate tools behind permission prompts (the `--safe-tools` opt-out). */
     safeTools?: boolean;
-    /** Runs allowed at once; omitted for the default of one. */
+    /**
+     * Runs allowed at once. Omitted unless `--concurrency` was given, so an
+     * installed daemon follows the CLI's default rather than freezing one.
+     */
     concurrency?: number;
     /** Absolute checkouts each conversation gets its own worktree of. */
     repos?: string[];

package/dist/agent/list.d.ts

@@ -15,6 +15,9 @@ export interface AgentHomeInfo {
     home: string;
     /** Agent name from `agent.json`; `undefined` when the home is not paired. */
     name?: string;
+    /** Name of the ProhostAI workspace it was paired in, when pairing recorded one. */
+    pairedIn?: string;
+    /** The Claude Code / Codex login it runs on — not the workspace. */
     account: string;
     /** From the daemon's `--exec`, when a daemon names one. */
     exec?: string;

package/dist/agent/list.js

@@ -87,6 +87,7 @@ export function findAgentHomes(options = {}) {
         found.push({
             home,
             name: credentials?.agent?.name,
+            pairedIn: credentials?.prohost_account?.name ?? undefined,
             account: credentials?.account ?? DEFAULT_ACCOUNT_LABEL,
             exec: meta.exec,
             daemon: meta.plist ? (daemonRunning(label) ? 'running' : 'installed') : 'not installed',
@@ -108,7 +109,10 @@ export async function renderAgentList(options = {}) {
         lines.push('  (none paired on this machine — prohost agent pair --code <code>)');
     for (const agent of agents) {
         const running = agent.runPid ? `running (pid ${agent.runPid})` : `daemon ${agent.daemon}`;
-        lines.push(`  ${agent.name ?? '(not paired)'}  ·  account ${agent.account}  ·  ${running}`);
+        // The ProhostAI workspace, when pairing recorded one (0.11.0+). `account`
+        // on the same line is the login on this machine, a different thing.
+        const pairedIn = agent.pairedIn ? `  ·  paired in ${agent.pairedIn}` : '';
+        lines.push(`  ${agent.name ?? '(not paired)'}${pairedIn}  ·  account ${agent.account}  ·  ${running}`);
         lines.push(`      home ${agent.home}${agent.exec ? `  ·  exec ${agent.exec}` : ''}`);
     }
     const accounts = loadAccounts(env);

package/dist/agent/pair.d.ts

@@ -8,8 +8,23 @@
  * Codes are single-use and expire after 15 minutes. Every redeem failure comes
  * back as one generic 404 by design, so the error text here can't be more
  * specific than "invalid, expired, or already used".
+ *
+ * Workspace-bound pairing (`--expect-account`)
+ * --------------------------------------------
+ * A code says nothing about which workspace it belongs to, and redeeming one
+ * makes this computer that workspace's runtime. Someone handed another
+ * person's code would pair their computer with that person's workspace. A
+ * caller that knows which workspace it means — the desktop app, signed in to
+ * one — passes its id, and the code is then redeemed on the bound endpoint,
+ * which refuses a code for any other workspace without consuming it.
+ *
+ * With an expectation, the bound endpoint is the ONLY one called. Its 404 is
+ * never retried on the plain endpoint: that would redeem the very code the
+ * check exists to stop, and against a server that predates the bound endpoint
+ * a fallback would turn "refused" into "redeemed unbound".
  */
 import type { AgentCredentials } from './credentials.js';
+import type { PairOutcome } from './pair_result.js';
 export interface PairOptions {
     /** The one-time code from the hire modal. */
     code: string;
@@ -28,6 +43,14 @@ export interface PairOptions {
      * needs the events pushed over HTTPS.
      */
     webhookUrl?: string;
+    /**
+     * The id of the workspace this computer expects the code to belong to
+     * (`--expect-account` / `$PROHOST_EXPECT_ACCOUNT`). When set — to anything,
+     * including a value that turns out not to be an id — the pairing is bound:
+     * it either goes through the bound endpoint for exactly that workspace or
+     * does not happen. `undefined` is the unbound pairing, unchanged.
+     */
+    expectAccount?: string;
     fetchImpl?: typeof fetch;
     /** Line-oriented output sink. Defaults to stdout. */
     onLine?: (line: string) => void;
@@ -38,7 +61,20 @@ export interface PairResult {
     credentials: AgentCredentials;
     path: string;
 }
+/**
+ * A pairing that did not complete, with what kind of failure it was.
+ *
+ * `outcome` and `revokedPreviousCredential` are set where the failure is
+ * detected — by the branch that ran — so a caller never has to read them back
+ * out of `message`, which can contain text the server chose.
+ */
 export declare class PairError extends Error {
+    readonly outcome: Exclude<PairOutcome, 'paired'>;
+    /** This run removed a stored credential the redeem had already revoked. */
+    readonly revokedPreviousCredential: boolean;
+    constructor(message: string, outcome?: Exclude<PairOutcome, 'paired'>, 
+    /** This run removed a stored credential the redeem had already revoked. */
+    revokedPreviousCredential?: boolean);
 }
 /**
  * Redeem ``code`` and persist the resulting credentials.

package/dist/agent/pair.js

@@ -8,19 +8,63 @@
  * Codes are single-use and expire after 15 minutes. Every redeem failure comes
  * back as one generic 404 by design, so the error text here can't be more
  * specific than "invalid, expired, or already used".
+ *
+ * Workspace-bound pairing (`--expect-account`)
+ * --------------------------------------------
+ * A code says nothing about which workspace it belongs to, and redeeming one
+ * makes this computer that workspace's runtime. Someone handed another
+ * person's code would pair their computer with that person's workspace. A
+ * caller that knows which workspace it means — the desktop app, signed in to
+ * one — passes its id, and the code is then redeemed on the bound endpoint,
+ * which refuses a code for any other workspace without consuming it.
+ *
+ * With an expectation, the bound endpoint is the ONLY one called. Its 404 is
+ * never retried on the plain endpoint: that would redeem the very code the
+ * check exists to stop, and against a server that predates the bound endpoint
+ * a fallback would turn "refused" into "redeemed unbound".
  */
 import { USER_AGENT } from '../version.js';
 import { baseUrlProblem, endpointProblem, isAllowedBaseUrl } from './base-url.js';
-import { DEFAULT_API_BASE_URL, REDEEM_PATH } from './contract.js';
+import { DEFAULT_API_BASE_URL, REDEEM_BOUND_PATH, REDEEM_PATH } from './contract.js';
 import { CREDENTIALS_VERSION, clearCredentials, maskSecret, saveCredentials, tryLoadCredentials, wsUrlFromBaseUrl, } from './credentials.js';
 import { DEFAULT_WS_URL } from '../listen.js';
+/**
+ * A pairing that did not complete, with what kind of failure it was.
+ *
+ * `outcome` and `revokedPreviousCredential` are set where the failure is
+ * detected — by the branch that ran — so a caller never has to read them back
+ * out of `message`, which can contain text the server chose.
+ */
 export class PairError extends Error {
+    outcome;
+    revokedPreviousCredential;
+    constructor(message, outcome = 'failed', 
+    /** This run removed a stored credential the redeem had already revoked. */
+    revokedPreviousCredential = false) {
+        super(message);
+        this.outcome = outcome;
+        this.revokedPreviousCredential = revokedPreviousCredential;
+        this.name = 'PairError';
+    }
 }
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Whether a value is a UUID string, which is how the server types ids. */
 function isUuid(value) {
     return typeof value === 'string' && UUID_PATTERN.test(value);
 }
+/**
+ * The workspace the server says the agent was paired in, or `undefined` when
+ * it did not say (an older server) or said something unusable.
+ */
+function serverAccount(value) {
+    if (!value || typeof value !== 'object' || !isUuid(value.id))
+        return undefined;
+    return { id: value.id, name: typeof value.name === 'string' && value.name ? value.name : null };
+}
+/** How a workspace is shown: its name when it has one, always its id. */
+function describeAccount(account) {
+    return account.name ? `${account.name} (${account.id})` : `(unnamed workspace) (${account.id})`;
+}
 /**
  * Derive the API base from the server-reported MCP URL, so the server wins —
  * unless it is one the API key may not be sent to (see `base-url.ts`).
@@ -63,33 +107,55 @@ export async function runPair(options) {
     // key comes back from it.
     const baseProblem = baseUrlProblem(baseUrl);
     if (baseProblem)
-        throw new PairError(`--base-url rejected: ${baseProblem}`);
+        throw new PairError(`--base-url rejected: ${baseProblem}`, 'invalid_arguments');
     const wsProblem = options.wsUrl ? endpointProblem(options.wsUrl, 'ws') : undefined;
     if (wsProblem)
-        throw new PairError(`--url rejected: ${wsProblem}`);
+        throw new PairError(`--url rejected: ${wsProblem}`, 'invalid_arguments');
     if (options.webhookUrl && !options.webhookUrl.startsWith('https://')) {
-        throw new PairError('--webhook-url must be an https:// URL');
+        throw new PairError('--webhook-url must be an https:// URL', 'invalid_arguments');
+    }
+    // An expectation that was asked for is never quietly dropped: a value that
+    // is not a workspace id stops the pairing here, before the code is spent,
+    // rather than falling through to an unbound one.
+    const bound = options.expectAccount !== undefined;
+    const expected = bound && isUuid(options.expectAccount) ? options.expectAccount.toLowerCase() : undefined;
+    if (bound && expected === undefined) {
+        throw new PairError('--expect-account (or $PROHOST_EXPECT_ACCOUNT) must be a workspace id — a UUID such as ' +
+            '0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b. Nothing was sent, and the code is unspent.', 'invalid_arguments');
     }
     let response;
     try {
-        response = await fetchImpl(`${baseUrl}${REDEEM_PATH}`, {
+        response = await fetchImpl(`${baseUrl}${bound ? REDEEM_BOUND_PATH : REDEEM_PATH}`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
             body: JSON.stringify({
                 code: options.code,
+                ...(bound ? { expected_account_id: expected } : {}),
                 ...(options.webhookUrl ? { webhook_url: options.webhookUrl } : {}),
             }),
         });
     }
     catch (err) {
-        throw new PairError(`Could not reach ${baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+        throw new PairError(`Could not reach ${baseUrl}: ${err instanceof Error ? err.message : String(err)}`, 'unreachable');
+    }
+    if (response.status === 404 && bound) {
+        // Deliberately NOT retried on the plain endpoint — see the module comment.
+        // The server answers one generic 404 for all of these, so say all of them.
+        throw new PairError('Pairing was refused, and nothing was paired. One of these is true:\n' +
+            '  - the code is invalid, expired, or already used (codes are single-use and expire ' +
+            '15 minutes after they are generated);\n' +
+            `  - the code is not for the workspace this computer expects (${expected});\n` +
+            '  - this server does not support workspace-bound pairing yet.\n' +
+            'Generate a fresh code in the workspace you mean to pair with. This was not retried ' +
+            'without the workspace check: a code from a workspace you did not expect is exactly ' +
+            'what the check is there to stop.', 'bound_rejected');
     }
     if (response.status === 404) {
         throw new PairError('Pairing code is invalid, expired, or already used. Codes are single-use and ' +
-            'expire 15 minutes after they are generated — generate a fresh one.');
+            'expire 15 minutes after they are generated — generate a fresh one.', 'code_rejected');
     }
     if (response.status === 429) {
-        throw new PairError('Too many pairing attempts from this IP. Wait an hour and retry.');
+        throw new PairError('Too many pairing attempts from this IP. Wait an hour and retry.', 'rate_limited');
     }
     if (!response.ok) {
         throw new PairError(`Pairing failed with HTTP ${response.status}.`);
@@ -104,6 +170,30 @@ export async function runPair(options) {
     if (!body || typeof body.api_key !== 'string' || !body.agent) {
         throw new PairError('Pairing response was missing an api_key or agent.');
     }
+    // Redeem revokes the credential previously paired for this agent, on every
+    // path that reaches here. So when what came back cannot be kept, whatever is
+    // on disk for the same agent is already dead — leaving it would send the
+    // operator chasing an `invalid_api_key` at `agent run` instead of the real
+    // cause.
+    const discardRevokedCredential = () => {
+        const stored = tryLoadCredentials(options.env);
+        return stored?.agent?.id === body.agent.id && clearCredentials(options.env);
+    };
+    // A bound redeem that succeeded names the workspace it paired in. One that
+    // does not — or names another — did not do what was asked, whatever the
+    // status code said; the credential it returned is not one to keep.
+    const prohostAccount = serverAccount(body.account);
+    if (bound && prohostAccount?.id.toLowerCase() !== expected) {
+        const staleRevoked = discardRevokedCredential();
+        throw new PairError(`The server did not confirm the workspace this computer expects (${expected}): it ` +
+            `${prohostAccount ? `answered for ${describeAccount(prohostAccount)}` : 'named no workspace'}.\n` +
+            '  The pairing code is spent, and nothing from this pairing was saved. If an agent now ' +
+            'shows as paired in ProhostAI that you did not mean to pair, disconnect it there.' +
+            (staleRevoked
+                ? '\n  The previously stored credential for this agent was revoked by this redeem ' +
+                    'and has been removed.'
+                : ''), 'workspace_unconfirmed', staleRevoked);
+    }
     // The response is JSON off the wire, so the TypeScript cast proves nothing.
     // Check the two fields that decide how this pairing behaves, rather than
     // coercing them and reporting the consequences much later as a websocket
@@ -131,18 +221,15 @@ export async function runPair(options) {
     if (!body.subscription_id) {
         // Redeem revokes the previously paired credential unconditionally, even on
         // this path (`connections.py` step 6 runs after the provisioning failure is
-        // swallowed). So on a re-pair of the same agent, whatever is on disk is
-        // already dead — leaving it would send the operator chasing an
-        // `invalid_api_key` at `agent run` instead of the real cause.
-        const stored = tryLoadCredentials(options.env);
-        const staleRevoked = stored?.agent?.id === body.agent.id && clearCredentials(options.env);
+        // swallowed) — see `discardRevokedCredential`.
+        const staleRevoked = discardRevokedCredential();
         throw new PairError('Pairing completed but no event subscription was provisioned, so this agent ' +
             'would never receive a run.\n' +
             '  The pairing code is spent either way — generate a fresh one and pair again.\n' +
             (staleRevoked
                 ? '  The previously stored credential for this agent was revoked by this ' +
                     'redeem and has been removed.'
-                : '  Nothing was saved.'));
+                : '  Nothing was saved.'), 'no_subscription', staleRevoked);
     }
     // Where the websocket host comes from, in order:
     //
@@ -172,9 +259,15 @@ export async function runPair(options) {
         events: body.events ?? [],
         agent: body.agent,
         paired_at: new Date().toISOString(),
+        // Only what the server just said: a workspace remembered from an earlier
+        // pairing would be a guess about this one.
+        ...(prohostAccount ? { prohost_account: prohostAccount } : {}),
     };
     const file = saveCredentials(credentials, options.env);
     onLine(`✓ Paired as "${body.agent.name}" (agent ${body.agent.id})`);
+    if (prohostAccount) {
+        onLine(`  Workspace    ${describeAccount(prohostAccount)}${bound ? ' — the workspace this computer expected' : ''}`);
+    }
     onLine(`  API key      ${maskSecret(body.api_key)}  (stored, never printed in full)`);
     onLine(`  Credentials  ${file}  (chmod 600)`);
     onLine(`  MCP URL      ${credentials.mcp_url}`);

package/dist/agent/pair_result.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A structured result of `prohost agent pair`, for a program that launched it.
+ *
+ * The CLI's stdout and stderr are for a person. They carry text the SERVER
+ * chose — the agent's name, the workspace's name — and whoever controls a
+ * workspace can name either anything, including a sentence this CLI prints
+ * itself. A caller that decides what happened by searching that output can
+ * therefore be steered by text an attacker wrote. This is what such a caller
+ * reads instead: `outcome` and `revoked_previous_credential` are set by the
+ * code path that ran, never derived from any text.
+ *
+ * Opt-in: written only when `$PROHOST_PAIR_RESULT_FILE` names an absolute
+ * path, on every exit path `agent pair` controls, success and failure. It
+ * never changes what pairing does: a path that is not absolute, or a write
+ * that fails, is one warning line on stderr and nothing else.
+ *
+ * It holds no secret and nothing from `agent.json`: not the pairing code, not
+ * the API key (not even its masked prefix), not the signing secret. `message`
+ * is for display only and must not be used to decide anything — it may
+ * contain server-chosen text.
+ *
+ * This module is the contract. A caller that wants to pin it (the desktop
+ * app's tests) reads the constants below.
+ */
+/** Environment variable naming the file to write. Must be an absolute path. */
+export declare const PAIR_RESULT_FILE_ENV = "PROHOST_PAIR_RESULT_FILE";
+/** `version` of the shape below. */
+export declare const PAIR_RESULT_VERSION = 1;
+/**
+ * Every value `outcome` can take.
+ *
+ *  - `paired` — the code was redeemed and the credential stored.
+ *  - `code_rejected` — an unbound redeem answered 404: the code is invalid,
+ *    expired or already used.
+ *  - `bound_rejected` — a workspace-bound redeem answered 404: any of the
+ *    above, or the code is for another workspace, or the server has no bound
+ *    redeem. Never retried unbound.
+ *  - `workspace_unconfirmed` — a workspace-bound redeem succeeded but its
+ *    answer did not name the expected workspace. The code is spent; nothing
+ *    was saved.
+ *  - `rate_limited` — 429.
+ *  - `unreachable` — the request never got an answer.
+ *  - `no_subscription` — redeemed, but no event subscription was provisioned.
+ *    The code is spent; nothing was saved.
+ *  - `invalid_arguments` — stopped before the code was spent: a missing code,
+ *    a bare or malformed flag, an empty or malformed expectation, a refused URL.
+ *  - `failed` — anything else.
+ */
+export declare const PAIR_OUTCOMES: readonly ["paired", "code_rejected", "bound_rejected", "workspace_unconfirmed", "rate_limited", "unreachable", "no_subscription", "invalid_arguments", "failed"];
+export type PairOutcome = (typeof PAIR_OUTCOMES)[number];
+export interface PairResult {
+    version: typeof PAIR_RESULT_VERSION;
+    outcome: PairOutcome;
+    /**
+     * True exactly when this run found the credential previously stored for the
+     * same agent already revoked by the redeem, and removed it from disk.
+     */
+    revoked_previous_credential: boolean;
+    /** What the CLI said about this outcome. Display only. */
+    message: string;
+}
+/**
+ * `message` with the pairing code removed, should anything have echoed it
+ * (a transport error quoting a URL or a body, say). Nothing this CLI writes
+ * includes the code; this is so that stays true whatever a library says.
+ */
+export declare function withoutCode(message: string, code: string | undefined): string;
+/**
+ * Write `result` to the file `$PROHOST_PAIR_RESULT_FILE` names, if it names
+ * one. Atomic (a temp file beside it, then a rename) and owner-only. Never
+ * throws and never affects pairing: every failure is one line on stderr.
+ */
+export declare function writePairResult(result: PairResult, env?: NodeJS.ProcessEnv, warn?: (line: string) => void): void;

package/dist/agent/pair_result.js

@@ -0,0 +1,99 @@
+/**
+ * A structured result of `prohost agent pair`, for a program that launched it.
+ *
+ * The CLI's stdout and stderr are for a person. They carry text the SERVER
+ * chose — the agent's name, the workspace's name — and whoever controls a
+ * workspace can name either anything, including a sentence this CLI prints
+ * itself. A caller that decides what happened by searching that output can
+ * therefore be steered by text an attacker wrote. This is what such a caller
+ * reads instead: `outcome` and `revoked_previous_credential` are set by the
+ * code path that ran, never derived from any text.
+ *
+ * Opt-in: written only when `$PROHOST_PAIR_RESULT_FILE` names an absolute
+ * path, on every exit path `agent pair` controls, success and failure. It
+ * never changes what pairing does: a path that is not absolute, or a write
+ * that fails, is one warning line on stderr and nothing else.
+ *
+ * It holds no secret and nothing from `agent.json`: not the pairing code, not
+ * the API key (not even its masked prefix), not the signing secret. `message`
+ * is for display only and must not be used to decide anything — it may
+ * contain server-chosen text.
+ *
+ * This module is the contract. A caller that wants to pin it (the desktop
+ * app's tests) reads the constants below.
+ */
+import { chmodSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/** Environment variable naming the file to write. Must be an absolute path. */
+export const PAIR_RESULT_FILE_ENV = 'PROHOST_PAIR_RESULT_FILE';
+/** `version` of the shape below. */
+export const PAIR_RESULT_VERSION = 1;
+/**
+ * Every value `outcome` can take.
+ *
+ *  - `paired` — the code was redeemed and the credential stored.
+ *  - `code_rejected` — an unbound redeem answered 404: the code is invalid,
+ *    expired or already used.
+ *  - `bound_rejected` — a workspace-bound redeem answered 404: any of the
+ *    above, or the code is for another workspace, or the server has no bound
+ *    redeem. Never retried unbound.
+ *  - `workspace_unconfirmed` — a workspace-bound redeem succeeded but its
+ *    answer did not name the expected workspace. The code is spent; nothing
+ *    was saved.
+ *  - `rate_limited` — 429.
+ *  - `unreachable` — the request never got an answer.
+ *  - `no_subscription` — redeemed, but no event subscription was provisioned.
+ *    The code is spent; nothing was saved.
+ *  - `invalid_arguments` — stopped before the code was spent: a missing code,
+ *    a bare or malformed flag, an empty or malformed expectation, a refused URL.
+ *  - `failed` — anything else.
+ */
+export const PAIR_OUTCOMES = [
+    'paired',
+    'code_rejected',
+    'bound_rejected',
+    'workspace_unconfirmed',
+    'rate_limited',
+    'unreachable',
+    'no_subscription',
+    'invalid_arguments',
+    'failed',
+];
+/** Codes shorter than this are not redacted: the replacement would mangle ordinary words. */
+const MIN_REDACTABLE_CODE = 6;
+/**
+ * `message` with the pairing code removed, should anything have echoed it
+ * (a transport error quoting a URL or a body, say). Nothing this CLI writes
+ * includes the code; this is so that stays true whatever a library says.
+ */
+export function withoutCode(message, code) {
+    if (!code || code.length < MIN_REDACTABLE_CODE)
+        return message;
+    return message.split(code).join('[pairing code]');
+}
+/**
+ * Write `result` to the file `$PROHOST_PAIR_RESULT_FILE` names, if it names
+ * one. Atomic (a temp file beside it, then a rename) and owner-only. Never
+ * throws and never affects pairing: every failure is one line on stderr.
+ */
+export function writePairResult(result, env = process.env, warn = (line) => process.stderr.write(`${line}\n`)) {
+    const target = env[PAIR_RESULT_FILE_ENV];
+    if (target === undefined)
+        return;
+    if (!path.isAbsolute(target)) {
+        warn(`! $${PAIR_RESULT_FILE_ENV} must be an absolute path; no pairing result was written.`);
+        return;
+    }
+    const temp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+    try {
+        // `wx`: never write through something already sitting at the temp name.
+        writeFileSync(temp, `${JSON.stringify(result)}\n`, { mode: 0o600, flag: 'wx' });
+        // The mode above is masked by the umask; set it outright.
+        chmodSync(temp, 0o600);
+        renameSync(temp, target);
+    }
+    catch (err) {
+        rmSync(temp, { force: true });
+        warn(`! Could not write the pairing result to $${PAIR_RESULT_FILE_ENV}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/agent/prompt.d.ts

@@ -74,7 +74,7 @@ export interface PromptContext {
     idleTimeoutMs?: number;
     /**
      * Other runs may be executing on this machine at the same moment
-     * (`--concurrency` above 1).
+     * (the default; `--concurrency 1` turns it off).
      *
      * Said because it changes what is safe: an agent that believes it has the
      * machine to itself switches branches in a shared checkout and writes

package/dist/agent/prompt.js

@@ -10,7 +10,7 @@ import { NO_REPLY_TOKEN } from './contract.js';
 /**
  * What the agent is told about sharing the machine and where its checkouts are.
  *
- * Empty when neither `--concurrency` nor `--repos` is in play.
+ * Empty for `--concurrency 1` without `--repos`.
  */
 function isolationLines(context) {
     const lines = [];
@@ -18,6 +18,12 @@ function isolationLines(context) {
     const failures = context.checkoutFailures ?? [];
     if (context.parallel) {
         lines.push('- Other conversations may be running on this machine right now, as other', '  processes of you, in this same working directory. Give any scratch file', '  a name unique to this run, and do not assume a file or a git branch', '  you did not create in this conversation is yours to change.');
+        // Without `--repos` — the usual pairing — nothing moves a run off the
+        // checkouts its standing instructions name, and `git switch` there changes
+        // the files under whichever run is reading them.
+        if (checkouts.length === 0 && failures.length === 0) {
+            lines.push('- No git checkout on this machine is private to this conversation.', '  Another run may be reading one while you work, so do not switch its', '  branch or leave it half-changed: if the work needs a branch of its', '  own, do it in a separate `git worktree` you create for it.');
+        }
     }
     if (checkouts.length > 0) {
         lines.push('- This conversation has its own git checkouts. Do all repository work', '  in them, and nowhere else:', ...checkouts.map((checkout) => `    ${checkout.name}: ${checkout.path}`), '  They are worktrees private to this conversation and they persist', '  between your runs here, so a branch or an uncommitted change you find', '  in one is your own earlier work in this thread. Wherever your other', '  instructions name one of these as the place to work, use the path', '  above instead:', ...checkouts.map((checkout) => `    ${checkout.source}`), '  Never switch branches, commit, or edit files in those originals —', '  other runs read them. Do not run `git worktree add` yourself.');

package/dist/agent/run.d.ts

@@ -10,12 +10,13 @@
  *
  * Two deliberate safety properties:
  *
- * * **Runs are serialized by default.** One local agent, one run at a time;
- *   concurrent frames queue. Agents hold working directories and rate limits,
- *   and running several at once is a good way to corrupt both. `--concurrency`
- *   raises the limit for runs in *different* conversations only — two turns of
- *   one conversation never overlap (see `scheduler.ts`) — and `--repos` gives
- *   each conversation its own git checkouts to do it in (see `worktrees.ts`).
+ * * **Runs in one conversation are serialized.** Two turns of one conversation
+ *   never overlap (see `scheduler.ts`). Runs in *different* conversations may:
+ *   up to `--concurrency` of them at once, {@link DEFAULT_CONCURRENCY} when the
+ *   flag is absent, and frames beyond that queue. Agents hold working
+ *   directories and rate limits, so every overlapping run is told it is
+ *   sharing the machine, `--repos` gives each conversation its own git
+ *   checkouts (see `worktrees.ts`), and `--concurrency 1` is one run at a time.
  * * **Runs are deduped on ``run_id``.** Webhook deliveries retry, and each
  *   attempt is mirrored to this socket. Without dedupe a retry would execute
  *   the command a second time and post a second reply.
@@ -108,9 +109,10 @@ export interface AgentRunOptions {
      */
     cwd?: string;
     /**
-     * How many runs may execute at once. Defaults to 1 — one run at a time, as
-     * before. Above 1, runs in different conversations overlap; runs in the same
-     * conversation still wait for each other.
+     * How many runs may execute at once. Defaults to
+     * {@link DEFAULT_CONCURRENCY}. Above 1, runs in different conversations
+     * overlap; runs in the same conversation still wait for each other. 1 is one
+     * run at a time, in arrival order.
      */
     concurrency?: number;
     /**

package/dist/agent/run.js

@@ -10,12 +10,13 @@
  *
  * Two deliberate safety properties:
  *
- * * **Runs are serialized by default.** One local agent, one run at a time;
- *   concurrent frames queue. Agents hold working directories and rate limits,
- *   and running several at once is a good way to corrupt both. `--concurrency`
- *   raises the limit for runs in *different* conversations only — two turns of
- *   one conversation never overlap (see `scheduler.ts`) — and `--repos` gives
- *   each conversation its own git checkouts to do it in (see `worktrees.ts`).
+ * * **Runs in one conversation are serialized.** Two turns of one conversation
+ *   never overlap (see `scheduler.ts`). Runs in *different* conversations may:
+ *   up to `--concurrency` of them at once, {@link DEFAULT_CONCURRENCY} when the
+ *   flag is absent, and frames beyond that queue. Agents hold working
+ *   directories and rate limits, so every overlapping run is told it is
+ *   sharing the machine, `--repos` gives each conversation its own git
+ *   checkouts (see `worktrees.ts`), and `--concurrency 1` is one run at a time.
  * * **Runs are deduped on ``run_id``.** Webhook deliveries retry, and each
  *   attempt is mirrored to this socket. Without dedupe a retry would execute
  *   the command a second time and post a second reply.
@@ -43,7 +44,7 @@ import { HeartbeatLoop } from './heartbeat.js';
 import { buildPrompt, replyFromStdout } from './prompt.js';
 import { NO_CAPABILITIES, capabilityProbe } from './capabilities.js';
 import { RunStore } from './runstore.js';
-import { MAX_CONCURRENCY, RunScheduler } from './scheduler.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 { SessionStore, sessionKeyFor } from './sessionstore.js';
 import { verifySignature } from './signature.js';
@@ -1152,11 +1153,11 @@ export async function runAgentHarness(options) {
         }
         return true;
     };
-    const concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, Math.floor(options.concurrency ?? 1)));
+    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 });
     if (concurrency > 1) {
-        log(`${timestamp()} ⚙ up to ${concurrency} runs at once — runs in the same conversation still take turns` +
+        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
                 ? ''
                 : '. No --repos given: runs share every checkout on this machine, so name the ' +

package/dist/agent/scheduler.d.ts

@@ -2,10 +2,11 @@
  * Which accepted runs execute now, and which wait.
  *
  * `agent run` used to chain every run onto one promise: one local agent, one
- * run at a time. That is still the default, and with a limit of 1 this
- * scheduler is exactly that chain — strict arrival order, nothing overlapping.
+ * run at a time. With a limit of 1 this scheduler is still exactly that chain
+ * — strict arrival order, nothing overlapping — and `--concurrency 1` asks for
+ * it. The harness default is {@link DEFAULT_CONCURRENCY}.
  *
- * `--concurrency N` lifts the limit without lifting the rule that actually
+ * A limit above 1 lifts the cap without lifting the rule that actually
  * protects an answer: **two runs on the same lane never overlap, and they start
  * in the order they arrived.** A lane is a conversation (see `sessionKeyFor`).
  * Each turn resumes the session the previous turn left, so running two turns of
@@ -19,6 +20,13 @@
  */
 /** Most runs one harness will execute at once, whatever the flag says. */
 export declare const MAX_CONCURRENCY = 16;
+/**
+ * Runs `agent run` executes at once when `--concurrency` is not given.
+ *
+ * Not 1: a one-line question in one thread should not sit behind a two-hour
+ * job in another. Not higher: every run spends the same login's quota.
+ */
+export declare const DEFAULT_CONCURRENCY = 3;
 export declare class RunScheduler {
     private readonly limit;
     private readonly pending;

package/dist/agent/scheduler.js

@@ -2,10 +2,11 @@
  * Which accepted runs execute now, and which wait.
  *
  * `agent run` used to chain every run onto one promise: one local agent, one
- * run at a time. That is still the default, and with a limit of 1 this
- * scheduler is exactly that chain — strict arrival order, nothing overlapping.
+ * run at a time. With a limit of 1 this scheduler is still exactly that chain
+ * — strict arrival order, nothing overlapping — and `--concurrency 1` asks for
+ * it. The harness default is {@link DEFAULT_CONCURRENCY}.
  *
- * `--concurrency N` lifts the limit without lifting the rule that actually
+ * A limit above 1 lifts the cap without lifting the rule that actually
  * protects an answer: **two runs on the same lane never overlap, and they start
  * in the order they arrived.** A lane is a conversation (see `sessionKeyFor`).
  * Each turn resumes the session the previous turn left, so running two turns of
@@ -19,6 +20,13 @@
  */
 /** Most runs one harness will execute at once, whatever the flag says. */
 export const MAX_CONCURRENCY = 16;
+/**
+ * Runs `agent run` executes at once when `--concurrency` is not given.
+ *
+ * Not 1: a one-line question in one thread should not sit behind a two-hour
+ * job in another. Not higher: every run spends the same login's quota.
+ */
+export const DEFAULT_CONCURRENCY = 3;
 export class RunScheduler {
     limit;
     pending = [];

package/dist/agent/worktrees.d.ts

@@ -72,10 +72,16 @@ export declare function laneDirName(lane: string): string;
  * forever. A running harness instead reports the checkout it could not make on
  * each run, and keeps answering.
  *
+ * A leading `~` is the home directory. A shell only expands the one that
+ * starts the word, so in `--repos ~/app,~/site` the second arrives as typed —
+ * and resolved as-is it would name a directory called `~` under wherever the
+ * harness was started.
+ *
  * @throws ReposFlagError naming the entry that is wrong.
  */
 export declare function parseReposFlag(raw: string, options?: {
     requireCheckouts?: boolean;
+    home?: string;
 }): string[];
 /** Whether `repo` is the top of a git checkout (a clone, or a worktree of one). */
 export declare function isCheckout(repo: string): boolean;

package/dist/agent/worktrees.js

@@ -30,6 +30,7 @@
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, rmdirSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { prohostHome } from './credentials.js';
 /** Child-process env var naming the directory that holds this run's checkouts. */
@@ -83,6 +84,11 @@ function lastLine(text) {
  * forever. A running harness instead reports the checkout it could not make on
  * each run, and keeps answering.
  *
+ * A leading `~` is the home directory. A shell only expands the one that
+ * starts the word, so in `--repos ~/app,~/site` the second arrives as typed —
+ * and resolved as-is it would name a directory called `~` under wherever the
+ * harness was started.
+ *
  * @throws ReposFlagError naming the entry that is wrong.
  */
 export function parseReposFlag(raw, options = {}) {
@@ -95,7 +101,7 @@ export function parseReposFlag(raw, options = {}) {
     const repos = [];
     const names = new Map();
     for (const entry of entries) {
-        const repo = path.resolve(entry);
+        const repo = path.resolve(expandHome(entry, options.home));
         if (options.requireCheckouts && !isCheckout(repo)) {
             throw new ReposFlagError(`--repos: ${repo} is not the top of a git checkout (no .git there).`);
         }
@@ -110,6 +116,11 @@ export function parseReposFlag(raw, options = {}) {
     }
     return repos;
 }
+function expandHome(entry, home = os.homedir()) {
+    if (entry === '~')
+        return home;
+    return entry.startsWith('~/') ? path.join(home, entry.slice(2)) : entry;
+}
 /** Whether `repo` is the top of a git checkout (a clone, or a worktree of one). */
 export function isCheckout(repo) {
     return existsSync(path.join(repo, '.git'));

package/dist/index.js

@@ -27,7 +27,8 @@ function printHelp() {
         '',
         'Usage:',
         '  prohost listen --forward-to <local-url> [--api-key <key>] [--url <ws-url>] [--machine <name>] [--subscription-id <id>]',
-        '  prohost agent pair --code <pairing-code> [--account <label>] [--webhook-url <https-url>] [--base-url <url>]',
+        '  prohost agent pair --code <pairing-code> [--expect-account <workspace-id>] [--account <label>]',
+        '                     [--webhook-url <https-url>] [--base-url <url>]',
         "  prohost agent run --exec '<command>' [--concurrency <n>] [--repos <checkout,…>] [--idle-timeout <seconds>]",
         '                    [--timeout <seconds>] [--dry-run] [--workdir <dir>]',
         "  prohost agent install-daemon --exec '<command>' [--workdir <dir>] [--account <label>]   Keep the agent running",
@@ -49,6 +50,10 @@ function printHelp() {
         '',
         'agent pair flags:',
         '  --code           One-time pairing code from the hire modal. Defaults to $PROHOST_PAIRING_CODE.',
+        '  --expect-account Pair only if the code belongs to this ProhostAI workspace (its id, a UUID).',
+        '                   A code for any other workspace is refused and left unspent, and the pairing',
+        '                   is never retried without the check. Defaults to $PROHOST_EXPECT_ACCOUNT.',
+        '                   Not the same as --account, which picks a Claude Code / Codex login.',
         '  --webhook-url    Also push events to this HTTPS endpoint. Omit it: stream-only is the normal setup.',
         '  --base-url       Public API base. Defaults to https://connect.prohost.ai. Must be https:// (http:// only for localhost).',
         '',
@@ -60,10 +65,10 @@ function printHelp() {
         '  --timeout        Seconds one run may take before it is killed, however busy it is.',
         '                   Defaults to 0 — no wall-clock limit, because a long run is not a stuck',
         '                   one. Set it if you want a hard ceiling as well as the stall watchdog.',
-        '  --concurrency    How many runs may execute at once, 1 to 16. Defaults to 1. Runs in the same',
+        '  --concurrency    How many runs may execute at once, 1 to 16. Defaults to 3. Runs in the same',
         '                   conversation always take turns, so only different conversations overlap.',
         '                   Every run spends the same login\'s quota, and they share this machine —',
-        '                   pair it with --repos if the agent edits code.',
+        '                   pair it with --repos if the agent edits code. Pass 1 for one run at a time.',
         '  --repos          Comma-separated git checkouts the agent works on. Each conversation gets',
         '                   its own `git worktree` of every one under $PROHOST_HOME/worktrees, kept for',
         '                   the life of the thread and removed after 14 idle days if it is clean. The',
@@ -128,6 +133,9 @@ function printHelp() {
         '  PROHOST_API_KEY       Used by `listen` when --api-key is not provided.',
         '  PROHOST_WS_URL        Used when --url is not provided.',
         '  PROHOST_PAIRING_CODE  Used by `agent pair` when --code is not provided.',
+        '  PROHOST_EXPECT_ACCOUNT  Used by `agent pair` when --expect-account is not provided.',
+        '  PROHOST_PAIR_RESULT_FILE  Absolute path. `agent pair` writes what happened there as JSON, for a',
+        '                        program that launched it to read instead of this output. See the README.',
         '  PROHOST_HOME          Credential, ledger, workspace and log directory. Defaults to ~/.prohost.',
         '  PROHOST_ACCOUNTS_ROOT Machine-wide account registry shared by every agent. Defaults to ~/.prohost-accounts.',
     ];

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.10.4";
+export declare const CLI_VERSION = "0.12.0";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.10.4";
+export declare const USER_AGENT = "prohost-cli/0.12.0";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.10.4';
+export const CLI_VERSION = '0.12.0';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.10.4",
+  "version": "0.12.0",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",