@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/claude-code/events.js

@@ -193,12 +193,83 @@ export function parseStream(buffer) {
                 events.push({ kind: "result", result: readResult(event) });
                 break;
             }
+            /**
+             * A top-level `type`, not a `system` subtype, so it is handled here and
+             * not in the subtype switch above.
+             *
+             * The placement is load-bearing rather than tidy: everything this switch
+             * does not name falls to `default`, which counts it as an unrecognised
+             * line and warns. A recognised shape parsed in the wrong place is
+             * therefore indistinguishable from a schema that moved — the drain reports
+             * a steady `skipped` on every session, and the reading it is dropping is
+             * the only free view of the subscription bucket anything here gets.
+             */
+            case "rate_limit_event": {
+                const info = readRateLimit(event);
+                if (!info) {
+                    skip(trimmed);
+                    break;
+                }
+                events.push({ kind: "rateLimit", info });
+                break;
+            }
             default:
                 skip(trimmed);
         }
     }
     return { events, carry, skipped, nested, ...(sample ? { sample } : {}) };
 }
+/**
+ * Read a `rate_limit_event` line, or nothing when it carries no status.
+ *
+ * `status` is the only required field: it is what decides whether anything is
+ * wrong, and a line without it says nothing this package can use — so it is
+ * skipped and sampled like any other unrecognised shape, rather than recorded as
+ * a bucket in an unknown state.
+ */
+function readRateLimit(event) {
+    const info = asRecord(event.rate_limit_info);
+    const status = info && str(info.status);
+    if (!info || !status)
+        return undefined;
+    const resetsAt = info.resetsAt;
+    return {
+        status,
+        // Finite is not enough. `1e308` is finite, and seconds past the `Date` range
+        // make `toISOString()` throw — inside `describe`, inside the drain's parse
+        // loop, which would take a whole session down over one malformed vendor
+        // field. The contract everywhere else here is to drop a bad line, not to
+        // raise, so the check is "does this name a moment" rather than "is this a
+        // number".
+        ...(typeof resetsAt === "number" && isRealDate(resetsAt * 1000)
+            ? { resetsAt }
+            : {}),
+        ...(str(info.rateLimitType)
+            ? { rateLimitType: str(info.rateLimitType) }
+            : {}),
+        ...(str(info.overageStatus)
+            ? { overageStatus: str(info.overageStatus) }
+            : {}),
+        ...(str(info.overageDisabledReason)
+            ? { overageDisabledReason: str(info.overageDisabledReason) }
+            : {})
+    };
+}
+/** Whether a millisecond value is one `Date` can actually represent. */
+function isRealDate(ms) {
+    return Number.isFinite(ms) && !Number.isNaN(new Date(ms).getTime());
+}
+/**
+ * The status a healthy bucket reports, and the only one ever observed.
+ *
+ * **Every other value is unclassified, not a refusal.** Nothing here knows what
+ * a non-`allowed` status means, and the one place that decides whether a
+ * credential is spent — `readRateLimitEvent` in this package's `credentials.ts`
+ * — recognises none of them, deliberately: retiring a working credential on a
+ * guess is the expensive half of that trade. What an unrecognised status earns
+ * is a note and a log, so somebody can name it.
+ */
+export const RATE_LIMIT_OK = "allowed";
 /** Read a `result` line. Total by construction — a missing field reads as zero. */
 function readResult(event) {
     const apiErrorStatus = event.api_error_status;
@@ -222,15 +293,11 @@ function readResult(event) {
         permissionDenials: denials
     };
 }
-/** How much of one progress note the parent is shown. */
-const PROGRESS_MAX_CHARS = 240;
 /**
  * How much of an unrecognised line is kept for the logs.
  *
- * Shorter than a progress note and for a different reason: a note is read by a
- * model deciding what to do next, whereas this is read by a person deciding
- * whether a schema moved. The discriminating part of a stream-json line is its
- * `type` and `subtype`, both of which are at the front.
+ * Read by a person deciding whether a schema moved, and the discriminating part
+ * of a stream-json line is its `type` and `subtype`, both at the front.
  */
 const SAMPLE_MAX_CHARS = 200;
 /**
@@ -273,8 +340,10 @@ function describe(event) {
         // Deliberately narrower than silencing the whole channel: `denied` and
         // `retry` below stay, because they are the only evidence of a session that
         // is being refused or throttled.
+        //
+        // Never clipped. A plan or a report cut mid-sentence reads as complete.
         case "assistant":
-            return event.text ? clip(event.text) : undefined;
+            return event.text || undefined;
         case "denied":
             // The one progress note that is more useful than the session's own
             // account of itself. A refused tool call is invisible in the transcript —
@@ -282,12 +351,29 @@ function describe(event) {
             // parent sees a subagent being resourceful and never learns it was fenced
             // in. Named tool first, because that is what distinguishes a broken
             // configuration from a deny rule doing its job.
-            return `permission denied${event.tool ? ` for ${event.tool}` : ""}: ${clip(event.reason)}`;
+            return `permission denied${event.tool ? ` for ${event.tool}` : ""}: ${event.reason}`;
         case "retry":
             // Surfaced deliberately. This is what a budget refusal from the egress
             // gateway looks like from inside the container, and a run that ends
             // shortly afterwards is explained by it.
-            return `retrying the model call: ${clip(event.detail)}`;
+            return `retrying the model call: ${event.detail}`;
+        case "rateLimit":
+            /**
+             * Silent while the bucket is fine, which is every line of a healthy
+             * session — one note per `rate_limit_event` would be the noisiest thing on
+             * the stream and would say "allowed" each time.
+             *
+             * The test is inverted deliberately: an unrecognised status produces a
+             * note rather than silence. The statuses are a vendor's and only
+             * {@link RATE_LIMIT_OK} has been seen, so a new one meaning "nearly out"
+             * should surface as prose somebody reads, not be assumed benign.
+             */
+            return event.info.status === RATE_LIMIT_OK
+                ? undefined
+                : `the ${event.info.rateLimitType ?? "subscription"} limit reports "${event.info.status}"` +
+                    (event.info.resetsAt === undefined
+                        ? ""
+                        : ` until ${new Date(event.info.resetsAt * 1000).toISOString()}`);
         // `init` names a session id nobody outside this package can use, and
         // `result` is the terminal outcome the caller reports itself.
         case "init":
@@ -295,6 +381,6 @@ function describe(event) {
             return undefined;
     }
 }
-function clip(text, max = PROGRESS_MAX_CHARS) {
+function clip(text, max) {
     return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
 }

package/dist/claude-code/index.d.ts

@@ -1,6 +1,6 @@
 import type { AgentPlugin } from "@dynamicagents/core";
 import type { CredentialStore, Lead } from "./credentials.js";
-import { type DrainCursor, type DrainOutcome, type SessionRuntime } from "./run.js";
+import { type DrainCursor, type DrainOutcome, type DrainOptions, type SessionRuntime } from "./run.js";
 import { type ClaudeCodeConfig } from "./config.js";
 /**
  * `@dynamicagents/plugins/claude-code` — subtasks that run the Claude Code CLI.
@@ -36,10 +36,9 @@ import { type ClaudeCodeConfig } from "./config.js";
  *
  * ## The 5-hour and weekly limits are routed around, not predicted
  *
- * 0.5.0 had a budget gate: an estimate of spend in dollars, and a refusal to
- * start work over a cap. 0.6.0 deletes it. The estimate was a guess about a
- * bucket nobody can read, and it only moved when a run *ended* — so it was never
- * a cap on spend, only a gate on starting.
+ * **No budget gate, and one must not come back.** An estimate of spend is a
+ * guess about a bucket nobody can read, and it only moves when a run *ends* — so
+ * it caps nothing, it only refuses to start.
  *
  * The gateway sees Anthropic's actual response, which is the one place the
  * bucket announces itself. So the credential is a **pool**: the first usable
@@ -71,9 +70,28 @@ export declare function claudeCodeSession(config: ClaudeCodeConfig): {
      * two sessions in one workspace under one id would spawn over each other —
      * see {@link execIdFor}.
      */
-    start(runtime: SessionRuntime, subtaskId: string | number, prompt: string, dir: string): Promise<DrainOutcome>;
-    /** Re-attach to a running session and drain one more window. */
-    resume(runtime: SessionRuntime, cursor: DrainCursor): Promise<DrainOutcome>;
+    start(runtime: SessionRuntime, subtaskId: string | number, prompt: string, dir: string, sinks?: Pick<DrainOptions, "onProgress" | "onCheckpoint">): Promise<DrainOutcome>;
+    /**
+     * Re-attach to a running session and drain one more window.
+     *
+     * **A session whose container was replaced is reported, not thrown.** The
+     * attachment is the first thing to notice a replacement, and the caller is a
+     * chunk loop with a cursor it will happily keep presenting: a throw here
+     * retries the same dead id until the chunk allowance runs out, and the run
+     * ends on a stack trace that names neither the session nor the cause. A
+     * terminal outcome ends it at the first attempt instead, with the exit code
+     * the runtime uses for a killed process and an explanation on `stderr`,
+     * which is exactly the channel a session that died without a result line
+     * already reports through.
+     *
+     * **What it must not say is that starting over is safe.** A session is an
+     * agent: by the time its container went, it may have written files that
+     * reached the workspace, committed, pushed, or called something outside
+     * altogether. None of that is visible from here — only that the attachment
+     * is gone — so the honest report is what is known plus where to look, and
+     * the decision belongs to whoever can read the durable state.
+     */
+    resume(runtime: SessionRuntime, cursor: DrainCursor, sinks?: Pick<DrainOptions, "onProgress" | "onCheckpoint">): Promise<DrainOutcome>;
     /** Stop a session — `SIGTERM`, so its own process tree goes with it. */
     stop(runtime: SessionRuntime, subtaskId: string | number): Promise<void>;
     /**
@@ -116,12 +134,12 @@ export type ClaudeCodeSession = ReturnType<typeof claudeCodeSession>;
 export declare function claudeCode(config: ClaudeCodeConfig): AgentPlugin;
 export { ANTHROPIC_HOST, claudeCodeEgress } from "./egress.js";
 export type { EgressConfig } from "./egress.js";
-export { credentialPool, readRefusal } from "./credentials.js";
+export { credentialPool, readRefusal, readRateLimitEvent } from "./credentials.js";
 export type { CredentialPool, CredentialPoolConfig, CredentialState, CredentialStore, Lead, Refusal } from "./credentials.js";
 export { buildLaunch, CLAUDE_EXEC_PREFIX, CREDENTIAL_PLACEHOLDER, execIdFor, freshCursor } from "./run.js";
-export type { DrainCursor, DrainOutcome, Launch, LaunchOptions, SessionRuntime } from "./run.js";
-export { parseStream, toProgress } from "./events.js";
-export type { ClaudeCodeEvent, ClaudeCodeResult, ClaudeCodeUsage } from "./events.js";
+export type { DrainCursor, DrainOptions, DrainOutcome, Launch, LaunchOptions, SessionRuntime } from "./run.js";
+export { parseStream, toProgress, RATE_LIMIT_OK } from "./events.js";
+export type { ClaudeCodeEvent, ClaudeCodeResult, ClaudeCodeUsage, RateLimitInfo } from "./events.js";
 export { CLAUDE_CODE_CAPABILITY, CLAUDE_CODE_RECIPE, CLAUDE_CODE_SPEC, CLAUDE_CODE_TYPE, WORKSPACE_RUNTIME_KEY } from "./recipe.js";
 export { DEFAULT_PERMISSION_MODE, DEFAULT_TIMEOUT_MS, DEFAULT_WINDOW_MS } from "./config.js";
-export type { ClaudeCodeConfig, PermissionMode } from "./config.js";
+export type { ClaudeCodeConfig, EffortLevel, PermissionMode } from "./config.js";

package/dist/claude-code/index.js

@@ -53,7 +53,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 import { definePlugin, PLUGIN_CONTRACT_VERSION } from "@dynamicagents/core";
 import { claudeCodeEgress } from "./egress.js";
 import { credentialPool } from "./credentials.js";
-import { attachRun, drainRun, execIdFor, freshCursor, killRun, startRun } from "./run.js";
+import { attachRun, drainRun, execIdFor, freshCursor, isExecLost, killRun, startRun } from "./run.js";
 import { DEFAULT_TIMEOUT_MS, DEFAULT_WINDOW_MS } from "./config.js";
 import { CLAUDE_CODE_SPEC, CLAUDE_CODE_TYPE, WORKSPACE_RUNTIME_KEY } from "./recipe.js";
 /**
@@ -90,10 +90,9 @@ import { CLAUDE_CODE_SPEC, CLAUDE_CODE_TYPE, WORKSPACE_RUNTIME_KEY } from "./rec
  *
  * ## The 5-hour and weekly limits are routed around, not predicted
  *
- * 0.5.0 had a budget gate: an estimate of spend in dollars, and a refusal to
- * start work over a cap. 0.6.0 deletes it. The estimate was a guess about a
- * bucket nobody can read, and it only moved when a run *ended* — so it was never
- * a cap on spend, only a gate on starting.
+ * **No budget gate, and one must not come back.** An estimate of spend is a
+ * guess about a bucket nobody can read, and it only moves when a run *ends* — so
+ * it caps nothing, it only refuses to start.
  *
  * The gateway sees Anthropic's actual response, which is the one place the
  * bucket announces itself. So the credential is a **pool**: the first usable
@@ -124,7 +123,7 @@ export function claudeCodeSession(config) {
         prompt,
         dir,
         ...(config.model ? { model: config.model } : {}),
-        ...(config.maxTurns === undefined ? {} : { maxTurns: config.maxTurns }),
+        ...(config.effort ? { effort: config.effort } : {}),
         ...(config.maxSubagentDepth === undefined
             ? {}
             : { maxSubagentDepth: config.maxSubagentDepth }),
@@ -134,7 +133,8 @@ export function claudeCodeSession(config) {
         // Forwarded only when set, so `buildLaunch` owns the default in one place
         // rather than this line resolving it and the flag being written twice.
         ...(config.permissionMode ? { permissionMode: config.permissionMode } : {}),
-        ...(config.env ? { env: config.env } : {})
+        ...(config.env ? { env: config.env } : {}),
+        ...(config.author ? { author: config.author } : {})
     });
     return {
         /**
@@ -144,7 +144,7 @@ export function claudeCodeSession(config) {
          * two sessions in one workspace under one id would spawn over each other —
          * see {@link execIdFor}.
          */
-        async start(runtime, subtaskId, prompt, dir) {
+        async start(runtime, subtaskId, prompt, dir, sinks = {}) {
             const env_1 = { stack: [], error: void 0, hasError: false };
             try {
                 const execId = execIdFor(subtaskId);
@@ -154,7 +154,10 @@ export function claudeCodeSession(config) {
                     execId,
                     timeoutMs
                 }), false);
-                return await drainRun(handle, freshCursor(execId), { windowMs });
+                return await drainRun(handle, freshCursor(execId), {
+                    windowMs,
+                    ...sinks
+                });
             }
             catch (e_1) {
                 env_1.error = e_1;
@@ -164,12 +167,56 @@ export function claudeCodeSession(config) {
                 __disposeResources(env_1);
             }
         },
-        /** Re-attach to a running session and drain one more window. */
-        async resume(runtime, cursor) {
+        /**
+         * Re-attach to a running session and drain one more window.
+         *
+         * **A session whose container was replaced is reported, not thrown.** The
+         * attachment is the first thing to notice a replacement, and the caller is a
+         * chunk loop with a cursor it will happily keep presenting: a throw here
+         * retries the same dead id until the chunk allowance runs out, and the run
+         * ends on a stack trace that names neither the session nor the cause. A
+         * terminal outcome ends it at the first attempt instead, with the exit code
+         * the runtime uses for a killed process and an explanation on `stderr`,
+         * which is exactly the channel a session that died without a result line
+         * already reports through.
+         *
+         * **What it must not say is that starting over is safe.** A session is an
+         * agent: by the time its container went, it may have written files that
+         * reached the workspace, committed, pushed, or called something outside
+         * altogether. None of that is visible from here — only that the attachment
+         * is gone — so the honest report is what is known plus where to look, and
+         * the decision belongs to whoever can read the durable state.
+         */
+        async resume(runtime, cursor, sinks = {}) {
             const env_2 = { stack: [], error: void 0, hasError: false };
             try {
-                const handle = __addDisposableResource(env_2, await attachRun(runtime, cursor), false);
-                return await drainRun(handle, cursor, { windowMs });
+                let handle;
+                try {
+                    handle = await attachRun(runtime, cursor);
+                }
+                catch (err) {
+                    if (!isExecLost(err))
+                        throw err;
+                    console.warn("[claude-code] the session's container was replaced", {
+                        execId: cursor.execId,
+                        err: String(err)
+                    });
+                    return {
+                        done: true,
+                        cursor,
+                        progress: [],
+                        exitCode: -1,
+                        stderr: "the container holding this session was replaced, so the session " +
+                            "was lost before it finished and cannot be re-attached. What it had " +
+                            "already written to the workspace is still there, and anything it " +
+                            "did outside the workspace — a commit, a push, a request — has " +
+                            "already happened. Check the workspace and the branch before " +
+                            "starting this subtask again, since a rerun repeats from the " +
+                            "beginning."
+                    };
+                }
+                const session = __addDisposableResource(env_2, handle, false);
+                return await drainRun(session, cursor, { windowMs, ...sinks });
             }
             catch (e_2) {
                 env_2.error = e_2;
@@ -272,8 +319,8 @@ export function claudeCode(config) {
     });
 }
 export { ANTHROPIC_HOST, claudeCodeEgress } from "./egress.js";
-export { credentialPool, readRefusal } from "./credentials.js";
+export { credentialPool, readRefusal, readRateLimitEvent } from "./credentials.js";
 export { buildLaunch, CLAUDE_EXEC_PREFIX, CREDENTIAL_PLACEHOLDER, execIdFor, freshCursor } from "./run.js";
-export { parseStream, toProgress } from "./events.js";
+export { parseStream, toProgress, RATE_LIMIT_OK } from "./events.js";
 export { CLAUDE_CODE_CAPABILITY, CLAUDE_CODE_RECIPE, CLAUDE_CODE_SPEC, CLAUDE_CODE_TYPE, WORKSPACE_RUNTIME_KEY } from "./recipe.js";
 export { DEFAULT_PERMISSION_MODE, DEFAULT_TIMEOUT_MS, DEFAULT_WINDOW_MS } from "./config.js";

package/dist/claude-code/run.d.ts

@@ -1,7 +1,7 @@
 import type { WorkspaceRuntimeExecHandle, WorkspaceRuntimeExecOptions, WorkspaceRuntimeGetOptions, WorkspaceRuntimeKillOptions } from "@cloudflare/computer";
 import type { ProgressEvent } from "@dynamicagents/core/subtasks";
-import { type ClaudeCodeResult } from "./events.js";
-import { type PermissionMode } from "./config.js";
+import { type ClaudeCodeResult, type RateLimitInfo } from "./events.js";
+import { type EffortLevel, type PermissionMode } from "./config.js";
 /**
  * Launching Claude Code in the workspace container, and draining it in windows.
  *
@@ -16,9 +16,8 @@ import { type PermissionMode } from "./config.js";
  *
  * The run is spawned under an exec id and left running. Each chunk re-attaches,
  * drains for a bounded window, and returns. That shape is not a preference: a
- * drain owned by an RPC that returns in milliseconds gets disposed mid-command,
- * which is exactly how the dependency install used to die halfway through
- * `npm ci`.
+ * drain owned by an RPC that returns in milliseconds gets disposed mid-command
+ * — the same way a dependency install dies halfway through `npm ci`.
  *
  * ## The cursor
  *
@@ -69,11 +68,10 @@ export declare function execIdFor(subtaskId: string | number): string;
 /**
  * What the container is given instead of a credential.
  *
- * Claude Code does not validate it locally — proven in the Phase 0c spike, where
- * a run with this exact value succeeded and the proxy log confirmed the
- * container only ever sent the placeholder. The egress gateway swaps in the real
- * credential on the way out, so a `postinstall` script that dumps the
- * environment learns this and nothing else.
+ * Claude Code does not validate it locally: a run with this exact value
+ * succeeds, and the container only ever sends the placeholder. The egress
+ * gateway swaps in the real credential on the way out, so a `postinstall` script
+ * that dumps the environment learns this and nothing else.
  *
  * Shaped like a real token deliberately: something that looks obviously fake
  * invites a future reader to "fix" it by putting the real one there.
@@ -85,16 +83,16 @@ export interface LaunchOptions {
     /** Where the checkout is. The session runs with this as its cwd. */
     dir: string;
     model?: string;
-    /** Ceiling on the *outer* session's turns. Advisory; the budget gate is not. */
-    maxTurns?: number;
     /**
-     * Caps on Claude Code's own subagent tree.
+     * How hard the model thinks, per turn. Unset, the model's own default.
      *
-     * These steer rather than enforce, and the distinction matters: the inner
-     * tree is invisible to Dynamic Agents' scheduler and unreachable by its
-     * cancellation sweep, so a cap it chooses to ignore has no backstop. What
-     * actually bounds the spend is the egress gateway, which every inner call
-     * also crosses.
+     * See {@link file://./config.ts ClaudeCodeConfig.effort} for what a level
+     * costs, and why an unrecognised one is worse here than a rejected one.
+     */
+    effort?: EffortLevel;
+    /**
+     * Caps on Claude Code's own subagent tree — advisory, for the reason
+     * {@link file://./config.ts ClaudeCodeConfig.maxSubagentDepth} gives.
      */
     maxSubagentDepth?: number;
     maxConcurrentSubagents?: number;
@@ -114,6 +112,14 @@ export interface LaunchOptions {
      * than trusted to the reader of that sentence.
      */
     env?: Record<string, string>;
+    /**
+     * Who this session's commits are attributed to — see
+     * {@link file://./config.ts ClaudeCodeConfig.author}.
+     */
+    author?: {
+        name: string;
+        email: string;
+    };
 }
 export interface Launch {
     command: string;
@@ -133,27 +139,20 @@ export interface Launch {
  * container is already an arbitrary-code-execution environment by design — the
  * install runs the repo's `postinstall`, the agent runs its test suite. Stripping
  * one door while the others stand open buys nothing and costs the agent its
- * context. (§4 of the design plan, cancelled 2026-08-21.)
+ * context.
  *
- * No `ANTHROPIC_BASE_URL` either, and that one is a genuine simplification over
- * the spike: `http-gateway` egress intercepts transparently, so the client talks
- * to the real hostname and the gateway sees it. Nothing has to be told to use a
- * proxy, which means nothing in the container can be told *not* to.
+ * No `ANTHROPIC_BASE_URL` either: `http-gateway` egress intercepts
+ * transparently, so the client talks to the real hostname and the gateway sees
+ * it. Nothing has to be told to use a proxy, which means nothing in the
+ * container can be told *not* to.
  *
  * ## `--permission-mode`, and the root guard behind it
  *
- * `-p` is headless. There is no terminal, so there is nobody to answer a
- * permission prompt — and Claude Code's headless path does not wait for one, it
- * **auto-denies**. Left unset the mode is `default`, and `default` gates Write,
- * Edit and every Bash command. A session in that state reads the repository
- * perfectly and cannot change one byte of it, while reporting prose that reads
- * like considered reluctance rather than a blocked tool. That cost this
- * deployment a day of "the container is fixed but nothing lands".
- *
- * So the mode is passed explicitly, and {@link DEFAULT_PERMISSION_MODE} is
- * `bypassPermissions` — see
- * {@link file://./config.ts ClaudeCodeConfig.permissionMode} for why the
- * permissive value is the correct default here rather than a concession.
+ * The mode is always passed explicitly, never left to the CLI's `default` — see
+ * {@link file://./config.ts ClaudeCodeConfig.permissionMode} for what an
+ * unset mode does to a headless session, and why
+ * {@link DEFAULT_PERMISSION_MODE} is the permissive value rather than a
+ * concession.
  *
  * **`IS_SANDBOX=1` ships in the same branch as the flag, and separating the two
  * breaks a session harder than passing no flag at all.** The container runs as
@@ -221,10 +220,22 @@ export type DrainOutcome = {
     done: false;
     cursor: DrainCursor;
     progress: ProgressEvent[];
+    /**
+     * The bucket as the client reported it **during this window**, if it did.
+     *
+     * Deliberately not carried on the cursor the way `result` is. A caller
+     * acts on this against whichever credential is leading *now*, so a reading
+     * replayed on every later chunk would let one window's observation retire
+     * a credential that was not even in use when it was taken. Absent means
+     * "this window learned nothing", which is the honest answer.
+     */
+    rateLimit?: RateLimitInfo;
 } | {
     done: true;
     cursor: DrainCursor;
     progress: ProgressEvent[];
+    /** The bucket as reported **in this window**. See the `done: false` arm. */
+    rateLimit?: RateLimitInfo;
     exitCode: number;
     /** Absent when the process died without ever emitting a `result` line. */
     result?: ClaudeCodeResult;
@@ -239,14 +250,69 @@ export interface DrainOptions {
     /**
      * How long this chunk may block before checkpointing and yielding.
      *
-     * Must stay comfortably under the Workflow step timeout, and it is what stops
-     * a run burning its whole chunk allowance in seconds: a drain that returned
-     * the moment it had nothing to read would exhaust `MAX_CHUNKS_PER_BRANCH`
-     * before the session finished thinking.
+     * **This is the coder path's soft limit**, justified the same way core's
+     * `CHUNK_SOFT_MS` is — by the step timeout — but checked as a deadline on
+     * reading the session's stdout stream rather than between turns, because a
+     * `claude -p` session runs its own loop inside the container and there are no
+     * core-visible turns to stop between. The stream is the only synchronisation
+     * point there is. {@link file://./config.ts ClaudeCodeConfig.windowMs} holds
+     * how the default is sized against that timeout, what the headroom it leaves
+     * is for, and why that headroom is an expectation rather than a guarantee.
+     *
+     * It is also what stops a run burning its whole chunk allowance in seconds: a
+     * drain that returned the moment it had nothing to read would exhaust
+     * `MAX_CHUNKS_PER_BRANCH` before the session finished thinking.
+     *
+     * **It is not the reporting interval**, and reading it as one is the mistake
+     * {@link DrainOptions.onProgress} exists to remove: a session that finishes
+     * inside a single window reaches no boundary at all, so a caller with nothing
+     * but the outcome learns everything at once, once the work is over.
      */
     windowMs: number;
+    /**
+     * Called with each note as it is parsed, rather than with all of them when the
+     * window ends.
+     *
+     * Notes are still returned on the outcome as well, so a caller that posts from
+     * here must drop what it is handed back, or the same note is posted twice. The
+     * keys are positional, so the gatekeeper would dedupe it, but paying for the
+     * second post to be discarded is not a plan.
+     *
+     * **Never awaited inside the read loop.** A post is a signed round trip to the
+     * gatekeeper — measured at ~700 ms — and awaiting one per note would stall
+     * reading the container's stream for as long as the session is talkative.
+     * Calls are chained instead, so they stay in order, and the chain is settled
+     * before the drain returns.
+     */
+    onProgress?: (event: ProgressEvent) => void | Promise<void>;
+    /**
+     * Called with a cursor that is safe to persist, no more often than
+     * {@link CHECKPOINT_MIN_MS}.
+     *
+     * **Only meaningful alongside `onProgress`, and that coupling is the whole
+     * point.** A caller normally commits the cursor after the drain returns,
+     * because a cursor written ahead of consuming events would skip events a retry
+     * never saw. A cursor offered here names a position whose notes have *already
+     * been handed to the sink*, so resuming from it loses nothing a person saw —
+     * which is only true because the sink posted them.
+     *
+     * Without it, a chunk that dies mid-window resumes from the last committed
+     * position, which is wherever the previous window ended. One production run
+     * lost six and a half minutes of a session that way and re-derived it by
+     * replaying the whole stream.
+     */
+    onCheckpoint?: (cursor: DrainCursor) => void | Promise<void>;
     now?: () => number;
 }
+/**
+ * Whether a thrown value means the session this cursor names is gone for good.
+ *
+ * `EEXEC_LOST` is the runtime saying the container that held the execution was
+ * replaced. The session died with it, and no attachment will ever find it — so
+ * unlike `EEXEC_BUSY`, which is a live session reached the wrong way, there is
+ * nothing to recover and retrying only spends chunks discovering that again.
+ */
+export declare function isExecLost(err: unknown): boolean;
 /**
  * Start a session, detached.
  *
@@ -257,13 +323,41 @@ export interface DrainOptions {
  * still running (`EEXEC_BUSY`). Without this the retry throws, every later retry
  * throws the same way, and a perfectly healthy session in the container becomes
  * unreachable.
+ *
+ * **The sync stays on the default, and `defer` is not an option here.** A
+ * deferred exec skips the post-command pull entirely and settles the outcome
+ * from the cursor instead — and its `cancel` reads the stream to the end first,
+ * so ending a window would block until the session exits rather than yielding
+ * the chunk. Both halves are exactly what this drain is built not to do.
  */
 export declare function startRun(runtime: SessionRuntime, options: LaunchOptions & {
     execId: string;
     timeoutMs: number;
 }): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
-/** Re-attach to a session this isolate did not start. */
-export declare function attachRun(runtime: SessionRuntime, cursor: DrainCursor): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
+/** The clock and the wait, injectable so a spec can drive the bound. */
+export interface AttachOptions {
+    now?: () => number;
+    wait?: (ms: number) => Promise<void>;
+}
+/**
+ * Re-attach to a session this isolate did not start.
+ *
+ * **Waits out a subscriber the previous window has not released yet**, and that
+ * wait is the point of this function rather than a refinement of it. The
+ * alternative is not "fail fast" — it is spending a Workflow retry to discover a
+ * condition that clears on its own in a second, when a chunk step's retries are
+ * what a deploy, a severed stub and a network drop have to be covered out of.
+ * Core sizes that budget and says why; what matters here is that this must not
+ * be charged to it. A deployment lost a twenty-one-minute session exactly that
+ * way — consecutive attach races used the retries up, and the redeploy that
+ * followed had no attempt left to be retried on. See {@link isExecSubscribed}.
+ *
+ * Everything else is rethrown on the first look, `EEXEC_LOST` above all: it is
+ * the runtime saying the container was replaced, `resume` turns it into a report
+ * for the model, and a retry loop would sit on it for {@link ATTACH_MAX_MS}
+ * learning nothing.
+ */
+export declare function attachRun(runtime: SessionRuntime, cursor: DrainCursor, options?: AttachOptions): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
 /**
  * Drain a session for one bounded window.
  *