@prohost/cli 0.12.2 → 0.12.3

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.3
+
+- **A run stopped by the Claude usage limit says so.** It used to fail with
+  "agent command exited 1", the reason left in the stream the CLI never read.
+  It now reports `Claude usage limit reached on <machine>: You've hit your
+  weekly limit · resets Oct 16 at 11am (America/New_York)`, and the thread's
+  notice shows it.
+- **That run keeps its conversation's session, and runs once.** A resumed run
+  that failed for any reason was taken for a session Claude Code could no
+  longer find, because every stream event names the session. The CLI then
+  dropped the conversation's session and ran the turn again from scratch, which
+  spent quota and, at a usage limit, failed a second time. A resume now counts
+  as rejected only when no session started. A run stopped by the usage limit
+  is not run again, and the next run after the reset continues the
+  conversation.
+- **Any Claude Code or Codex run that exits non-zero reports its own error**
+  (an API error, a failed turn), not just the exit code. Only that message is
+  read from the stream; tool output stays on this machine.
+
 ## 0.12.2
 
 - **Two agents on one computer no longer delete each other's account.** Every

package/README.md

@@ -233,7 +233,9 @@ and gets a reply that has forgotten asking. The CLI reads the `session_id` out
 of Claude Code's JSON output, records it per conversation in
 `~/.prohost/sessions.json`, and `--resume`s it next time. Sessions don't live
 forever; when one is gone the run is retried once from scratch rather than
-failing.
+failing. A run stopped by your Claude usage limit is not retried: it fails
+with Claude Code's own message, which says when the limit resets, and the
+conversation keeps its session for the next run.
 
 **It lets the agent actually do things.** Runs are invoked with
 `--dangerously-skip-permissions`, so tool calls execute without stopping to ask.

package/dist/agent/claude.d.ts

@@ -177,6 +177,28 @@ export interface ClaudeStream {
      * `rate_limit_event`. Fields the stream never mentioned are absent.
      */
     observed(): RuntimeObservation;
+    /**
+     * Why the turn failed, in Claude Code's own words: the error a `result`
+     * event reported, or else the API error an `assistant` event carried in
+     * place of an answer. `undefined` when the stream said neither.
+     *
+     * Read for a run that exited non-zero, whose stdout is otherwise never
+     * looked at — without it such a run reports only "exited 1". Never the raw
+     * stream: that carries the output of every tool call, and this text is
+     * echoed into a workspace thread.
+     */
+    error(): string | undefined;
+    /**
+     * Claude Code's message when the subscription's usage limit stopped the
+     * turn — "You've hit your weekly limit · resets Oct 16 at 11am
+     * (America/New_York)" — or `undefined` when something else did.
+     *
+     * Recognised by the `rate_limit` error on the `assistant` event Claude Code
+     * writes in place of an answer, or by a `rate_limit_event` whose status is
+     * `rejected` with no overage to fall back on. Running the turn again cannot
+     * help until the limit resets, so a caller must not retry it.
+     */
+    usageLimit(): string | undefined;
     /**
      * The turn's outcome. ``stdout`` is the complete captured output, used only
      * when the stream held no `result` event — a crashed binary, a login prompt,
@@ -218,11 +240,20 @@ export declare function readClaudeStream(): ClaudeStream;
  * and the ledger has no way to know. A stale entry must not turn into a
  * permanently broken surface, so the caller retries once without `--resume`.
  *
- * The observed failure is exit 1, empty stdout, and
- * `No conversation found with session ID: <uuid>` on stderr. Matching is
- * broader than that string because the wording is not ours to depend on, and it
- * is gated by the caller on the run having actually failed — so a *successful*
- * run whose reply text happens to quote a session id is never mistaken for one.
+ * The observed failure (Claude Code 2.1.296) is exit 1, `No conversation found
+ * with session ID: <uuid>` on stderr, and on stdout a lone `result` event with
+ * that message in `errors` — no `system`/`init` event, because no session ever
+ * started. Matching is broader than that string because the wording is not
+ * ours to depend on, and it is gated by the caller on the run having actually
+ * failed — so a *successful* run whose reply text happens to quote a session id
+ * is never mistaken for one.
+ *
+ * A stream that announced its session or produced an assistant message is a
+ * resume that **worked**, whatever went wrong after it. That guard is what
+ * keeps an ordinary failed turn from matching: every stream-json event carries
+ * `session_id`, so "the output mentions the session id" — which this used to
+ * accept — is true of every resumed run, and a resumed run that then hit a
+ * usage limit was retried from scratch and lost its thread's session.
  */
 export declare function looksLikeResumeFailure(output: string, sessionId: string): boolean;
 /** Absolute path of the generated MCP config. */

package/dist/agent/claude.js

@@ -209,6 +209,19 @@ function resultEnvelope(stdout) {
 function text(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * The `errors` an `error_during_execution` envelope carries instead of a
+ * `result` — e.g. `No conversation found with session ID: <uuid>` for a
+ * rejected `--resume` (Claude Code 2.1.296).
+ */
+function envelopeErrors(parsed) {
+    if (!Array.isArray(parsed.errors))
+        return undefined;
+    return text(parsed.errors.filter((entry) => typeof entry === 'string' && entry.length > 0).join('; '));
+}
 /**
  * Turn a `result` envelope into the harness's view of the turn.
  *
@@ -229,7 +242,7 @@ function outputFromEnvelope(parsed) {
             ok: false,
             sessionId,
             denials,
-            error: result ?? `claude reported an error (${String(parsed.subtype ?? 'unknown')})`,
+            error: result ?? envelopeErrors(parsed) ?? `claude reported an error (${String(parsed.subtype ?? 'unknown')})`,
         };
     }
     if (!result) {
@@ -452,6 +465,10 @@ export function readClaudeStream() {
     let lastActivity;
     let lastText;
     let result;
+    /** The last `assistant` event that was an API error rather than an answer. */
+    let apiError;
+    /** When a `rate_limit_event` said the limit is hit: its reset, epoch seconds. */
+    let limitRejected;
     let toolEvents = [];
     // `tool_use.id` → tool name, so a result can be reported under the name of
     // the call it answers. Deleted on the result: bounded by tools in flight.
@@ -534,6 +551,13 @@ export function readClaudeStream() {
             const windows = fromClaudeRateLimitInfo(event.rate_limit_info);
             if (windows.length > 0)
                 observed.quota_windows = windows;
+            const info = asRecord(event.rate_limit_info);
+            // `rejected` with overage still `allowed` is a turn that carries on, on
+            // overage; only a rejection with nothing to fall back on stops it.
+            const overage = info?.overageStatus;
+            if (info?.status === 'rejected' && overage !== 'allowed' && overage !== 'allowed_warning') {
+                limitRejected = { resetsAt: typeof info.resetsAt === 'number' ? info.resetsAt : undefined };
+            }
         }
         // Present on the `system`/`init` event, and repeated on most others. Taken
         // from whichever arrives first — they all name the same session.
@@ -551,6 +575,15 @@ export function readClaudeStream() {
         }
         if (event.type !== 'assistant')
             return;
+        // Claude Code writes an API failure — a usage limit, a billing or auth
+        // error — as an assistant message whose text is the explanation, marked by
+        // `error` (stream-json) or `isApiErrorMessage` (the transcript shape).
+        if (typeof event.error === 'string' || event.isApiErrorMessage === true) {
+            apiError = {
+                kind: event.apiError === 'usage_limit_reached' ? 'rate_limit' : text(event.error),
+                text: assistantContent(event).text?.trim() || undefined,
+            };
+        }
         collectToolUses(event);
         const { text: written, tool } = assistantContent(event);
         if (written)
@@ -562,6 +595,14 @@ export function readClaudeStream() {
         else if (written)
             lastActivity = written.replace(/\s+/g, ' ').trim().slice(0, MAX_ACTIVITY_CHARS);
     };
+    /** A trailing event with no newline after it is still an event. */
+    const flushTail = () => {
+        const tail = buffer.trim();
+        if (tail) {
+            handle(tail);
+            buffer = '';
+        }
+    };
     return {
         push(chunk) {
             buffer += chunk;
@@ -594,14 +635,30 @@ export function readClaudeStream() {
                 return undefined;
             return trimmed.length > MAX_SALVAGE_CHARS ? trimmed.slice(-MAX_SALVAGE_CHARS) : trimmed;
         },
-        finish(stdout) {
-            // A trailing event with no newline after it is still an event — a binary
-            // that exits without flushing a final `\n` must not lose its result.
-            const tail = buffer.trim();
-            if (tail) {
-                handle(tail);
-                buffer = '';
+        error: () => {
+            flushTail();
+            if (result) {
+                const outcome = outputFromEnvelope(result);
+                if (!outcome.ok)
+                    return outcome.error;
             }
+            return apiError?.text;
+        },
+        usageLimit: () => {
+            flushTail();
+            if (apiError?.kind === 'rate_limit')
+                return apiError.text ?? 'usage limit reached';
+            if (!limitRejected)
+                return undefined;
+            const { resetsAt } = limitRejected;
+            return resetsAt === undefined
+                ? 'usage limit reached'
+                : `usage limit reached · resets ${new Date(resetsAt * 1000).toISOString()}`;
+        },
+        finish(stdout) {
+            // A binary that exits without flushing a final `\n` must not lose its
+            // result.
+            flushTail();
             if (result)
                 return outputFromEnvelope(result);
             // No `result` event: either the command isn't emitting the stream we
@@ -621,19 +678,42 @@ export function readClaudeStream() {
  * and the ledger has no way to know. A stale entry must not turn into a
  * permanently broken surface, so the caller retries once without `--resume`.
  *
- * The observed failure is exit 1, empty stdout, and
- * `No conversation found with session ID: <uuid>` on stderr. Matching is
- * broader than that string because the wording is not ours to depend on, and it
- * is gated by the caller on the run having actually failed — so a *successful*
- * run whose reply text happens to quote a session id is never mistaken for one.
+ * The observed failure (Claude Code 2.1.296) is exit 1, `No conversation found
+ * with session ID: <uuid>` on stderr, and on stdout a lone `result` event with
+ * that message in `errors` — no `system`/`init` event, because no session ever
+ * started. Matching is broader than that string because the wording is not
+ * ours to depend on, and it is gated by the caller on the run having actually
+ * failed — so a *successful* run whose reply text happens to quote a session id
+ * is never mistaken for one.
+ *
+ * A stream that announced its session or produced an assistant message is a
+ * resume that **worked**, whatever went wrong after it. That guard is what
+ * keeps an ordinary failed turn from matching: every stream-json event carries
+ * `session_id`, so "the output mentions the session id" — which this used to
+ * accept — is true of every resumed run, and a resumed run that then hit a
+ * usage limit was retried from scratch and lost its thread's session.
  */
 export function looksLikeResumeFailure(output, sessionId) {
     if (!sessionId)
         return false;
-    if (output.includes(sessionId))
-        return true;
+    if (sessionStarted(output))
+        return false;
     return /no (conversation|session)[^\n]{0,40}found|session[^\n]{0,40}not found|--resume|resume[^\n]{0,20}(failed|invalid|expired)/i.test(output);
 }
+/** Did this output include the `system`/`init` or an `assistant` event of a running session? */
+function sessionStarted(output) {
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        const event = asObject(trimmed);
+        if (!event)
+            continue;
+        if ((event.type === 'system' && event.subtype === 'init') || event.type === 'assistant')
+            return true;
+    }
+    return false;
+}
 /** Absolute path of the generated MCP config. */
 export function mcpConfigPath(env = process.env) {
     return path.join(prohostHome(env), MCP_CONFIG_FILENAME);

package/dist/agent/codex.d.ts

@@ -518,6 +518,15 @@ export type CodexOutput = {
  * the model (verified against 0.144.1, same convention as Claude Code).
  */
 export declare function parseCodexOutput(stdout: string): CodexOutput;
+/**
+ * The failure a Codex run reported about itself — the last `turn.failed` or
+ * `error` event's message — or `undefined` if it reported none.
+ *
+ * For a run that exited non-zero, whose stdout is otherwise never read: without
+ * this such a run reports only "exited 1". Only that message, never the stream
+ * around it, which carries command output and would be echoed into a thread.
+ */
+export declare function codexFailureMessage(stdout: string): string | undefined;
 /**
  * Does this look like the resume having been rejected, rather than the agent
  * having failed at its actual work?

package/dist/agent/codex.js

@@ -1053,6 +1053,27 @@ export function parseCodexOutput(stdout) {
             : 'codex returned no output',
     };
 }
+/**
+ * The failure a Codex run reported about itself — the last `turn.failed` or
+ * `error` event's message — or `undefined` if it reported none.
+ *
+ * For a run that exited non-zero, whose stdout is otherwise never read: without
+ * this such a run reports only "exited 1". Only that message, never the stream
+ * around it, which carries command output and would be echoed into a thread.
+ */
+export function codexFailureMessage(stdout) {
+    let failure;
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        const event = asObject(trimmed);
+        if (event && (event.type === 'turn.failed' || event.type === 'error')) {
+            failure = failureMessage(event) ?? failure;
+        }
+    }
+    return failure;
+}
 /**
  * Name the tool this item was refused, or `undefined` if it wasn't refused.
  *

package/dist/agent/run.js

@@ -33,7 +33,7 @@ import { HarnessAccount } from './account_runtime.js';
 import { EVENT_AGENT_CONFIG_UPDATED, machineId } from './accounts.js';
 import { completeRun, describeFailure, isIdempotencyInFlight, postReply } from './api.js';
 import { MAX_SALVAGE_CHARS, claudeCommand, isClaudeExec, looksLikeResumeFailure, readClaudeStream, writeMcpConfig, } from './claude.js';
-import { APPS_FEATURE, MCP_API_KEY_ENV_VAR, PLUGINS_DISABLED_OVERRIDE, codexBinary, codexCommand, codexMcpInventoryFlag, codexProfileName, codexShellSyntax, extraMcpEntries, isCodexExec, isolateConfiguredServers, listMcpServers, mcpServersOverride, prohostMcpEntry, looksLikeCodexResumeFailure, parseCodexOutput, } from './codex.js';
+import { APPS_FEATURE, MCP_API_KEY_ENV_VAR, PLUGINS_DISABLED_OVERRIDE, codexBinary, codexCommand, codexMcpInventoryFlag, codexProfileName, codexShellSyntax, extraMcpEntries, isCodexExec, isolateConfiguredServers, listMcpServers, mcpServersOverride, prohostMcpEntry, codexFailureMessage, looksLikeCodexResumeFailure, parseCodexOutput, } from './codex.js';
 import { ToolEventQueue } from './events.js';
 import { EXTRA_MCP_FILENAME, loadExtraMcpServers } from './extras.js';
 import { MCP_SERVER_NAME, MCP_TOOL_PATTERN } from './mcp.js';
@@ -723,6 +723,18 @@ runEnv) {
     if (mcp.error) {
         return { ok: false, reason: 'MCP isolation could not be established', detail: mcp.error, durationMs: 0 };
     }
+    /**
+     * A turn the Claude subscription's usage limit stopped, worded for the
+     * thread: whose limit (this machine's login) and, in Claude Code's own
+     * words, when it resets. The only fix is waiting, so the reason says that
+     * rather than "exited 1".
+     */
+    const usageLimitFailure = (said, stderr = '') => ({
+        ok: false,
+        reason: `Claude usage limit reached on ${options.machine ?? os.hostname()}`,
+        detail: [said, stderr.includes(said) ? '' : stderr].filter((part) => part.length > 0).join('\n'),
+        durationMs: elapsed(),
+    });
     const failure = (result) => {
         // A killed run has no reply, but it usually has most of one. Reporting the
         // tail of what the agent was writing turns "no output for 15 minutes" into
@@ -751,7 +763,20 @@ runEnv) {
         // completion `error` is capped server-side, and of the two, what the agent
         // was saying beats the last 500 characters of its logging.
         const stderrTail = result.stderr.trim().slice(salvaged ? -200 : -500);
-        const detail = [stderrTail, salvaged ? `unfinished answer: ${salvaged}` : '']
+        const limit = killed ? undefined : stream?.usageLimit();
+        if (limit)
+            return usageLimitFailure(limit, stderrTail);
+        // What the brain itself said went wrong — a shaped brain reports it on
+        // stdout, which a non-zero exit otherwise leaves unread. First, because the
+        // thread shows only the opening of this text.
+        const said = killed
+            ? undefined
+            : (stream?.error() ?? (runtime.brain === 'codex' ? codexFailureMessage(result.stdout) : undefined))?.slice(0, MAX_SALVAGE_CHARS);
+        const detail = [
+            said ?? '',
+            said && stderrTail.includes(said) ? '' : stderrTail,
+            salvaged ? `unfinished answer: ${salvaged}` : '',
+        ]
             .filter((part) => part.length > 0)
             .join('\n');
         return {
@@ -794,6 +819,9 @@ runEnv) {
     const resumeFailed = codex ? looksLikeCodexResumeFailure : looksLikeResumeFailure;
     if (!result.ok &&
         sessionId &&
+        // A usage limit fails a fresh session exactly as it failed this one, and
+        // the retry would cost the thread its session for nothing.
+        !stream?.usageLimit() &&
         resumeFailed(`${result.stderr}\n${result.stdout}`, sessionId) &&
         // Skipped rather than squeezed into a token budget: a retry with no time
         // left would be killed on the spot and reported as a timeout, which is a
@@ -811,8 +839,11 @@ runEnv) {
         // transcript is real, it holds however long the agent worked, and the next
         // delivery on that surface can resume it. Only a turn that failed on its
         // own — a crash, an unparseable answer — has no continuity worth keeping.
-        if (!result.timedOut && !result.idleTimedOut && !result.cancelled)
+        // A usage limit is not the turn failing on its own either: the session is
+        // the thread's, and the next turn after the reset should continue it.
+        if (!result.timedOut && !result.idleTimedOut && !result.cancelled && !stream?.usageLimit()) {
             forgetRecordedSession();
+        }
         return failure(result);
     }
     // A denied tool is not an error either brain reports — the turn succeeds and
@@ -852,6 +883,9 @@ runEnv) {
         toolEvents?.push(stream.drainToolEvents());
     reportDenials(parsed.denials);
     if (!parsed.ok) {
+        const limit = stream?.usageLimit();
+        if (limit)
+            return usageLimitFailure(limit);
         forgetRecordedSession();
         return {
             ok: false,

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.12.2";
+export declare const CLI_VERSION = "0.12.3";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.12.2";
+export declare const USER_AGENT = "prohost-cli/0.12.3";

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.12.2';
+export const CLI_VERSION = '0.12.3';
 /** 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.12.2",
+  "version": "0.12.3",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",