@prohost/cli 0.10.4 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.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
@@ -682,6 +760,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 +781,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/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/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).',
         '',
@@ -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.11.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.11.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.11.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.11.0",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",