@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/claude-code/run.js

@@ -1,35 +1,41 @@
 import { shellQuote } from "@cloudflare/computer";
-import { parseStream, toProgress } from "./events.js";
+import { GITHUB_ENV_KEYS, githubEnv } from "./github.js";
+import { parseStream, toProgress, RATE_LIMIT_OK } from "./events.js";
 import { DEFAULT_PERMISSION_MODE } from "./config.js";
 /** Namespace for every session exec id in a workspace. */
 export const CLAUDE_EXEC_PREFIX = "claude-code-run";
 /**
  * The exec id one session occupies.
  *
- * **Per subtask, not fixed**, and the difference is load-bearing. A workspace is
- * one Durable Object and one container, but subtasks are a flat *concurrent*
- * fan-out — two `claude-code` subtasks for the same caller and repository run at
- * the same time, against the same workspace. Under a single shared id they
- * would spawn over one another, each drain would attach to whichever exec won,
- * and `killRun` would stop somebody else's session. That is the displacement bug
- * the coder's install guard exists to prevent, in a new place; here the answer
- * is simply not to share the id.
+ * **Per run, not fixed**, and the difference is load-bearing. A workspace is
+ * one Durable Object and one container, but runs are concurrent — sessions in a
+ * scratchpad share their parent's container — so under a single shared id they would spawn
+ * over one another, each drain would attach to whichever exec won, and
+ * `killRun` would stop somebody else's session. That is the displacement bug the
+ * coder's install guard exists to prevent, in a new place; here the answer is
+ * simply not to share the id.
  *
- * Fixed *per subtask*, though, because the point is still to find it again: an
+ * Fixed *per run*, though, because the point is still to find it again: an
  * isolate that dies mid-drain leaves the session running in the container, and
- * `getExec` is how the next chunk re-attaches instead of starting a second one.
+ * `getExec` is how the next drain re-attaches instead of starting a second one.
  */
-export function execIdFor(subtaskId) {
-    return `${CLAUDE_EXEC_PREFIX}:${subtaskId}`;
+export function execIdFor(runId) {
+    return `${CLAUDE_EXEC_PREFIX}:${runId}`;
+}
+/**
+ * The id a run's follow-up turn runs under — its own, because the session's exec
+ * has already finished under {@link execIdFor} and an id names one process.
+ */
+export function followUpExecIdFor(runId) {
+    return `${execIdFor(runId)}:follow-up`;
 }
 /**
  * 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.
@@ -45,41 +51,96 @@ export const CREDENTIAL_PLACEHOLDER = "sk-ant-oat01-" + "0".repeat(24);
  * is refused rather than overridden.
  */
 const RESERVED_ENV_KEY = "CLAUDE_CODE_OAUTH_TOKEN";
+/**
+ * The workspace mount, `/workspace` in every image this plugin runs in.
+ * Whatever a session writes under it is synced into the workspace's Durable
+ * Object; whatever it writes anywhere else dies with the container.
+ */
+const WORKSPACE_MOUNT = "/workspace";
+/**
+ * Where every session keeps Claude Code's own state — its `CLAUDE_CONFIG_DIR`.
+ *
+ * The whole config directory moves, created if absent: the transcripts under
+ * `projects/<cwd-with-/-as-->/<session-id>.jsonl`, the session index,
+ * `.claude.json` and the auto-memory directory. None of it is a credential.
+ *
+ * This is what decides how long a session stays resumable. The CLI's own
+ * `$HOME/.claude` is on the container's disk, so a conversation there dies with
+ * the container — which a deploy, a rollout and the workspace's own idle timer
+ * all end. Under the workspace mount it is the Durable Object's storage, and the
+ * conversation outlives the container that held it; a later run can continue it
+ * from that same workspace object, and from no other.
+ *
+ * **Fixed, and never a host's to choose.** A transcript is found only where it
+ * was written, so every second place a session could write one is a resume that
+ * cannot find it. `env` cannot move it either: {@link buildLaunch} refuses the
+ * key.
+ *
+ * The directory is named {@link file://../computer/paths.ts SESSION_STATE_DIR},
+ * which is the name the file tools' walk steps over: a transcript records every
+ * line the session read, so a walk that descended into it would answer the
+ * parent's `grep` for a line of source with the session that quoted it. The
+ * name is written out here rather than imported, because `/claude-code` does
+ * not reach `/computer` — a spec holds the two to the same spelling.
+ */
+export const SESSION_CONFIG_DIR = `${WORKSPACE_MOUNT}/.claude-sessions`;
+/** The environment key {@link SESSION_CONFIG_DIR} travels as. */
+const CONFIG_DIR_ENV_KEY = "CLAUDE_CONFIG_DIR";
+/**
+ * Git's identity as an *environment*, not a `git config`.
+ *
+ * The session's cwd is one checkout, and what it commits in is not: a
+ * superproject's submodules, a scratch clone, anything it initialises are all
+ * separate repositories with separate configs, and `/repo` only ever configured
+ * the one it cloned. A config write would have to find each of them; the
+ * environment is inherited by every git the session starts, and it outranks all
+ * four config levels — so a checkout carrying a name from whenever it was
+ * created no longer decides who commits today.
+ *
+ * Both pairs, because they answer different questions: an amend or a rebase
+ * keeps the original author and stamps a fresh committer, and with only
+ * `GIT_AUTHOR_*` set that commit ends up half attributed.
+ */
+function gitIdentityEnv(author) {
+    if (!author)
+        return {};
+    return {
+        GIT_AUTHOR_NAME: author.name,
+        GIT_AUTHOR_EMAIL: author.email,
+        GIT_COMMITTER_NAME: author.name,
+        GIT_COMMITTER_EMAIL: author.email
+    };
+}
 /**
  * Build the command and environment for one session.
  *
  * `--output-format stream-json` with `--verbose`, because the stream is the only
- * way to report progress before the run ends and a run legitimately lasts longer
- * than any single chunk. `--verbose` is required: without it Claude Code emits
+ * way to report progress before the run ends, and a run lasts for minutes.
+ * `--verbose` is required: without it Claude Code emits
  * only the final result even in stream mode.
  *
- * Note what is **absent**. No `--bare`, no `--settings` override, no
- * `CLAUDE_CONFIG_DIR`: a cloned repository's `CLAUDE.md`, skills and hooks are
- * exactly the material that makes the agent good at that repository, and the
- * 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.)
+ * Note what is **absent**. No `--bare` and no `--settings` override: a cloned
+ * repository's `CLAUDE.md`, skills and hooks are exactly the material that makes
+ * the agent good at that repository, and the 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.
+ * `CLAUDE_CONFIG_DIR` is not that kind of flag, and every session gets it: it
+ * moves where the *client* keeps its own state, touching nothing a repository
+ * ships — see {@link SESSION_CONFIG_DIR}.
  *
- * 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
@@ -115,14 +176,59 @@ export function buildLaunch(options) {
             "hand it to every process in the container, including a cloned " +
             "repository's install scripts. Pass it as `credential` instead.");
     }
+    /**
+     * Refused for the same reason: a host that set it meant its sessions to keep
+     * their state somewhere else, and a transcript written anywhere but the one
+     * place is a conversation no later run will find.
+     */
+    if (options.env && CONFIG_DIR_ENV_KEY in options.env) {
+        throw new Error(`claude-code: ${CONFIG_DIR_ENV_KEY} cannot be set through \`env\`. Every ` +
+            `session keeps its state in ${SESSION_CONFIG_DIR}, which is where a ` +
+            "later run looks for the conversation it continues.");
+    }
+    /**
+     * Refused rather than dropped, both of them: dropped, a caller that asked to
+     * continue or fork a conversation gets a session that started one of its own,
+     * and reports it as the continuation of whatever it was told to continue. An
+     * empty id is the same state {@link file://./session.ts followUp} refuses,
+     * and refusing it here covers every caller of this option rather than that
+     * one path.
+     */
+    if (options.resume === "") {
+        throw new Error("claude-code: `resume` is the session id of the conversation to " +
+            "continue, so it cannot be empty. Launch without it to start one.");
+    }
+    if (options.fork && !options.resume) {
+        throw new Error("claude-code: `fork` forks a resumed conversation, so it needs the " +
+            "`resume` session id it is forking.");
+    }
+    /**
+     * Refused beside `github`: a host value would either hand the session a real
+     * token or point git's credential at something other than the placeholder.
+     */
+    const githubKey = options.github
+        ? GITHUB_ENV_KEYS.find((key) => options.env && key in options.env)
+        : undefined;
+    if (githubKey) {
+        throw new Error(`claude-code: ${githubKey} cannot be set through \`env\` when \`githubToken\` ` +
+            "is configured. The session presents a placeholder and the egress " +
+            "gateway swaps in the GitHub token on the way out.");
+    }
     const permissionMode = options.permissionMode ?? DEFAULT_PERMISSION_MODE;
     const argv = ["claude", "-p", shellQuote(options.prompt)];
+    if (options.resume)
+        argv.push("--resume", shellQuote(options.resume));
+    if (options.fork)
+        argv.push("--fork-session");
     argv.push("--output-format", "stream-json", "--verbose");
     argv.push("--permission-mode", permissionMode);
     if (options.model)
         argv.push("--model", shellQuote(options.model));
-    if (options.maxTurns !== undefined)
-        argv.push("--max-turns", String(options.maxTurns));
+    if (options.effort)
+        argv.push("--effort", options.effort);
+    if (options.jsonSchema) {
+        argv.push("--json-schema", shellQuote(JSON.stringify(options.jsonSchema)));
+    }
     const env = {
         // Pinned image; an autoupdate would move the wire shape the gateway and the
         // parser are both written against, mid-run and without a deploy.
@@ -138,16 +244,26 @@ export function buildLaunch(options) {
         env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS = String(options.maxConcurrentSubagents);
     return {
         command: argv.join(" "),
-        // The last two are applied **after** the host's environment rather than
-        // before it. For the placeholder that makes the guard above a second line
-        // rather than the only one; for `IS_SANDBOX` it means a host cannot unset
+        // Everything below `options.env` is applied **after** the host's environment
+        // rather than before it. For the placeholder and the config directory that
+        // makes the guards above a second line rather than the only one; for
+        // `IS_SANDBOX` it means a host cannot unset
         // the variable its own permission mode depends on — see the note above.
+        //
+        // For the identity it is what keeps the four keys one answer. Spread before
+        // `env`, a host that set `GIT_AUTHOR_NAME` there and `author` here would
+        // get the author from one and the committer from the other — a commit
+        // attributed to two people, which is the exact failure `author` exists to
+        // end. Last, `author` is simply the answer whenever a host gives one.
         env: {
             ...env,
             ...options.env,
             ...(permissionMode === "bypassPermissions"
                 ? { IS_SANDBOX: "1" }
                 : undefined),
+            ...gitIdentityEnv(options.author),
+            ...(options.github ? githubEnv() : undefined),
+            [CONFIG_DIR_ENV_KEY]: SESSION_CONFIG_DIR,
             [RESERVED_ENV_KEY]: CREDENTIAL_PLACEHOLDER
         }
     };
@@ -156,22 +272,125 @@ export function buildLaunch(options) {
 export function freshCursor(execId) {
     return { execId, seq: 0, carry: "", emitted: 0 };
 }
-/** Distinguishes "the window ran out" from a real stream event in the race below. */
-const WINDOW_EXPIRED = Symbol("window-expired");
+/**
+ * Whether a bucket reading says anything the last one did not.
+ *
+ * Every field, because each is separately actionable: the status decides whether
+ * a credential is worth using, `resetsAt` is when it recovers, the type says
+ * which bucket is talking, and the overage pair says whether spending past it is
+ * allowed and why not. Comparing only the status would hold a rollover — a new
+ * `resetsAt` under an unchanged `allowed` — out of the logs entirely.
+ *
+ * **Over the keys rather than a written-out list**, which is the difference
+ * between one bug and a class of them: a field added to
+ * {@link RateLimitInfo} and forgotten here does not make a smaller log, it makes
+ * a change to the reading that never reaches a log at all — the one failure this
+ * function exists to prevent, and a silent one. Shallow is exact because the
+ * reading is flat and every value on it is a primitive; a nested field would
+ * need this revisited, and the parser is where that would be decided.
+ */
+function changedReading(previous, next) {
+    if (previous === undefined)
+        return true;
+    const before = { ...previous };
+    const after = { ...next };
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])].some((key) => before[key] !== after[key]);
+}
+/** Distinguishes "the caller stopped the drain" from a stream event in the race below. */
+const STOPPED = Symbol("stopped");
+/**
+ * How rarely a drain offers a cursor to persist.
+ *
+ * A checkpoint is a Durable Object storage write, and the stream can carry many
+ * events a second while a session reads files — so this is a floor on the writes,
+ * not a schedule for them. Sized against what it is protecting: the loss it
+ * bounds is re-drained in seconds, so buying a smaller bound with a write per
+ * event would cost more than the bound is worth.
+ */
+const CHECKPOINT_MIN_MS = 30_000;
 /** Whether a thrown value is the runtime refusing to reuse a live exec id. */
-function isExecBusy(err) {
+export function isExecBusy(err) {
     return err?.code === "EEXEC_BUSY";
 }
+/**
+ * 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 discovers that again.
+ */
+export function isExecLost(err) {
+    return err?.code === "EEXEC_LOST";
+}
+/**
+ * Whether a thrown value is the *previous* drain's attachment, not yet released.
+ *
+ * An exec's event stream admits one subscriber at a time. A drain resumed after
+ * an eviction, or a follow-up asked for the moment a session ends, can ask for
+ * the next one while the last is still being released — and the release on the
+ * far side is asynchronous and unobservable from here: the workspace client
+ * carries `Symbol.dispose`, not `Symbol.asyncDispose`, so there is nothing a
+ * caller can await to know the attachment is gone. {@link attachRun} answers by
+ * waiting rather than by failing.
+ *
+ * **Matched on the message, not on a code, and that is not laziness.** This one
+ * is raised inside the container image rather than by the runtime client: the
+ * string appears nowhere in the Worker bundle, and it arrives here as a plain
+ * `Error` with no `code` — unlike `EEXEC_BUSY` and `EEXEC_LOST`
+ * above, which the client throws and codes. The code is checked first anyway, so
+ * the day the container starts sending one this keeps working and the string
+ * test becomes the fallback it should have been.
+ */
+function isExecSubscribed(err) {
+    const e = err;
+    if (e?.code === "EEXEC_SUBSCRIBED")
+        return true;
+    return (typeof e?.message === "string" &&
+        e.message.includes("already has a live subscriber"));
+}
+/**
+ * How long {@link attachRun} waits out a subscriber that has not been released.
+ *
+ * Bounded, because what it is waiting on may not be a teardown at all: an
+ * isolate that is genuinely wedged holding the stream releases it when it dies,
+ * and nothing here can tell that apart from one that is a moment from
+ * finishing. Exceeding this rethrows, so the turn fails and Think's recovery
+ * retries it on a fresh isolate — which is the right escalation, and the one
+ * this whole mechanism exists to stop being the *first* resort.
+ *
+ * Sized well above what the race costs in practice. The race normally clears
+ * on the first or second look, and a deployment where it took fifteen seconds is
+ * what this is sized to outlast.
+ */
+const ATTACH_MAX_MS = 30_000;
+/** The first gap between attach attempts, doubled up to {@link ATTACH_CAP_MS}. */
+const ATTACH_BACKOFF_MS = 250;
+/**
+ * The ceiling on that doubling.
+ *
+ * Without it the last gap before {@link ATTACH_MAX_MS} would be most of the
+ * budget, so a subscriber released early in it would still be waited out to the
+ * end. What this buys is that the wait ends soon after the release, rather than
+ * at the next power of two.
+ */
+const ATTACH_CAP_MS = 2_000;
 /**
  * Start a session, detached.
  *
  * **Falls back to attaching when the id is already live**, which is not a
- * nicety. `start` spawns and then drains for minutes, so a chunk that fails
- * anywhere after the spawn is retried by the Workflow with no cursor to resume
- * from — and `@cloudflare/computer` refuses to reuse an id whose execution is
- * still running (`EEXEC_BUSY`). Without this the retry throws, every later retry
+ * nicety. `start` spawns and then drains for minutes, so a turn cut anywhere
+ * after the spawn is recovered with no cursor stored yet — and
+ * `@cloudflare/computer` refuses to reuse an id whose execution is still
+ * running (`EEXEC_BUSY`). Without this the recovery throws, every later one
  * 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 stopping a drain would block until the session exits. Both halves are
+ * exactly what this drain is built not to do.
  */
 export async function startRun(runtime, options) {
     const { command, env } = buildLaunch(options);
@@ -188,51 +407,188 @@ export async function startRun(runtime, options) {
         if (!isExecBusy(err))
             throw err;
         console.info("[claude-code] a session is already running under this id — attaching", { execId: options.execId });
-        return await attachRun(runtime, freshCursor(options.execId));
+        return await attachRun(runtime, freshCursor(options.execId), {
+            signal: options.signal
+        });
     }
 }
-/** Re-attach to a session this isolate did not start. */
-export async function attachRun(runtime, cursor) {
-    return await runtime.getExec(cursor.execId, {
-        encoding: "utf8",
-        // `0` is a legal seq and also the beginning, so a fresh cursor resumes from
-        // the start either way. Later chunks name their own place.
-        resume: cursor.seq
-    });
+/**
+ * Re-attach to a session this isolate did not start.
+ *
+ * **Waits out a subscriber the previous drain 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 recovery to discover a
+ * condition that clears on its own in a second, when recoveries are what a
+ * deploy, a severed stub and a network drop have to be covered out of. 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 async function attachRun(runtime, cursor, options = {}) {
+    const now = options.now ?? Date.now;
+    const wait = options.wait ?? sleep;
+    const deadline = now() + ATTACH_MAX_MS;
+    let backoff = ATTACH_BACKOFF_MS;
+    for (;;) {
+        try {
+            return await runtime.getExec(cursor.execId, {
+                encoding: "utf8",
+                // `0` is a legal seq and also the beginning, so a fresh cursor resumes
+                // from the start either way. A stored cursor names its own place.
+                resume: cursor.seq
+            });
+        }
+        catch (err) {
+            // Rethrown rather than retried once the budget is gone, so the step still
+            // fails on a subscriber that is never coming back — just not first.
+            if (!isExecSubscribed(err) ||
+                now() >= deadline ||
+                options.signal?.aborted)
+                throw err;
+            // Clamped to what is left, so the last gap lands *on* the deadline rather
+            // than past it. Uncapped, a schedule whose final doubling straddles the
+            // bound would take one more look on the far side of it — and the bound
+            // would be a number in a comment rather than one the code keeps.
+            const waitMs = Math.min(backoff, deadline - now());
+            // One line per wait, not per attempt: this is the condition whose
+            // frequency is worth watching, and it went unnamed in the logs for as
+            // long as retries were absorbing it one at a time.
+            console.info("[claude-code] the previous drain is still attached — waiting", { execId: cursor.execId, waitMs });
+            await wait(waitMs);
+            backoff = Math.min(backoff * 2, ATTACH_CAP_MS);
+        }
+    }
 }
 /**
- * Drain a session for one bounded window.
+ * Drain a session to its end.
  *
- * Returns `done: false` when the window expired with the process still running —
- * the caller checkpoints the cursor and comes back — or `done: true` once the
- * stream has finished.
+ * Returns `done: true` once the stream has finished, or `done: false` when the
+ * caller's signal stopped the drain with the process still running.
  */
-export async function drainRun(handle, cursor, options) {
+export async function drainRun(handle, cursor, options = {}) {
     const now = options.now ?? Date.now;
-    const deadline = now() + options.windowMs;
     const reader = handle.getReader();
-    const events = [];
+    /**
+     * The drain's notes, in order — built as the stream is parsed rather than
+     * from a list of events at the end, so there is one place a note is numbered
+     * and the sink below cannot disagree with what is returned.
+     */
+    const progress = [];
+    let emitted = cursor.emitted;
     let buffer = cursor.carry;
+    let thinkingFrom = cursor.thinkingFrom;
     let seq = cursor.seq;
     let result = cursor.result;
+    // This drain's reading only — see `DrainOutcome`. Starting undefined also
+    // means the first reading of each drain reaches the log, which is what keeps
+    // a resumed session's bucket visible without carrying a stale one forward.
+    let rateLimit;
     let stderr = cursor.stderr ?? "";
+    let sessionId = cursor.sessionId;
+    /**
+     * Set when this drain is the one that learned the session id, and cleared by
+     * the checkpoint it lets through. See {@link DrainCursor.sessionId}.
+     */
+    let newHandle = false;
     let exitCode;
+    let checkpointedAt = now();
+    /**
+     * The sink's calls, chained rather than awaited.
+     *
+     * Ordering matters — these are sentences in a conversation — and awaiting
+     * one inside the read loop would stall the drain for as long as the session
+     * keeps talking. A rejected note does not stop the drain — a note is
+     * best-effort — but it is logged, and it ends the checkpoints: see
+     * `DrainOptions.onCheckpoint`. Settled before the drain returns or throws, so
+     * nothing is cut short when it unwinds, and nothing lands behind a drain that
+     * re-attaches after it.
+     */
+    let sunk = Promise.resolve();
+    /** Set once a note is rejected — see `DrainOptions.onCheckpoint`. */
+    let rejected = false;
+    /**
+     * The last position every note behind which reached the sink: where this
+     * drain began, then each checkpoint the chain reaches unrejected.
+     */
+    let safe = cursor;
     /**
      * Parse whatever complete lines the buffer now holds.
      *
      * Called after **every** stdout event rather than once at the end. Claude
-     * Code's stream carries whole tool results, so a chunk that only parsed on the
-     * way out would hold an eight-minute transcript of a noisy build in a Durable
-     * Object's memory; parsing eagerly keeps only `carry`, which is at most one
-     * incomplete line.
+     * Code's stream carries whole tool results, so a drain that only parsed on
+     * the way out would hold a whole session's transcript of a noisy build in a
+     * Durable Object's memory; parsing eagerly keeps only `carry`, which is at
+     * most one incomplete line.
      */
     const absorb = () => {
-        const parsed = parseStream(buffer);
+        const parsed = parseStream(buffer, {
+            now: now(),
+            ...(thinkingFrom === undefined ? {} : { thinkingFrom })
+        });
         buffer = parsed.carry;
+        thinkingFrom = parsed.thinkingFrom;
         for (const event of parsed.events) {
-            events.push(event);
             if (event.kind === "result")
                 result = event.result;
+            // The first one only, and it is the id of whatever this drain is actually
+            // draining: a resumed conversation's own, or the new one a fork starts.
+            if (event.kind === "init" && !sessionId) {
+                sessionId = event.sessionId;
+                newHandle = true;
+            }
+            if (event.kind === "rateLimit") {
+                /**
+                 * Logged when the reading **changes**, not per line — and a change is
+                 * any field of it, not just the status: a bucket rolling over moves
+                 * `resetsAt` while saying `allowed` throughout, and the new reset is
+                 * the useful half of that line.
+                 *
+                 * The client repeats itself for as long as a session runs, so a log per
+                 * event would be the noisiest thing this package writes and every copy
+                 * after the first would say the same thing. A change is the whole signal:
+                 * the first reading names the bucket and when it refills, and the only
+                 * other one that can happen is the bucket saying no — which is the line
+                 * nobody has captured yet, and the one the pool needs before it can be
+                 * trusted to act on a status rather than on a refused request.
+                 */
+                if (changedReading(rateLimit, event.info)) {
+                    const at = { execId: cursor.execId, ...event.info };
+                    // An unrecognised status is **not** reported as a refusal. Nothing
+                    // here knows what one means, and a log that calls it exhaustion is
+                    // how a healthy credential gets retired by the next person to read
+                    // it. See `RATE_LIMIT_OK`.
+                    if (event.info.status === RATE_LIMIT_OK)
+                        console.info("[claude-code] subscription bucket", at);
+                    else
+                        console.warn("[claude-code] unrecognised subscription status", at);
+                }
+                rateLimit = event.info;
+            }
+        }
+        // Numbered from the running total, so a note has the same key whether it is
+        // filed from here or returned on the outcome — and the same key again when
+        // a resumed drain replays this part of the stream, which is what makes the
+        // duplicate harmless. See `toProgress`.
+        for (const note of toProgress(parsed.events, emitted)) {
+            progress.push(note);
+            emitted++;
+            const sink = options.onProgress;
+            if (sink)
+                sunk = sunk
+                    .then(() => sink(note))
+                    .catch((err) => {
+                    rejected = true;
+                    console.warn("[claude-code] a note did not reach the parent", {
+                        execId: cursor.execId,
+                        key: note.key,
+                        err: String(err)
+                    });
+                });
         }
         if (parsed.skipped > 0) {
             // Not fatal, and deliberately not silent: a systematic schema change
@@ -251,29 +607,92 @@ export async function drainRun(handle, cursor, options) {
             });
         }
     };
-    const finish = (code) => {
-        const progress = toProgress(events, cursor.emitted);
-        const next = {
-            execId: cursor.execId,
-            seq,
-            carry: buffer,
-            emitted: cursor.emitted + progress.length,
-            ...(result ? { result } : {}),
-            ...(stderr ? { stderr } : {})
-        };
+    /**
+     * Where the drain has got to, as something safe to persist.
+     *
+     * One object, so `seq`, `carry` and `emitted` are written together — a cursor
+     * that advanced its position without its note count would renumber every key
+     * after it, and a replay would then post the whole tail again under keys the
+     * transcript has never seen.
+     */
+    const checkpoint = () => ({
+        execId: cursor.execId,
+        seq,
+        carry: buffer,
+        emitted,
+        ...(thinkingFrom === undefined ? {} : { thinkingFrom }),
+        ...(sessionId ? { sessionId } : {}),
+        ...(result ? { result } : {}),
+        ...(stderr ? { stderr } : {})
+    });
+    /**
+     * Offer the caller a cursor to store, at most every
+     * {@link CHECKPOINT_MIN_MS} — and once more the moment the session id appears.
+     *
+     * Fire-and-forget onto the same chain the notes ride, so a storage write
+     * cannot stall the read loop and cannot land before the notes it claims are
+     * already posted.
+     *
+     * **The id does not wait for the interval.** It is the handle to everything
+     * that follows — the one thing that lets a later run continue this
+     * conversation — and a session killed inside the first interval would
+     * otherwise leave none. One extra write per session buys that.
+     */
+    const offerCheckpoint = () => {
+        const sink = options.onCheckpoint;
+        // **Refused without `onProgress`, not merely discouraged.** A checkpoint is
+        // only safe because the notes behind it have been filed; offered to a
+        // caller that files nothing, it advances a cursor past notes that were never
+        // delivered, and a drain dying after it loses them permanently. The
+        // documented unsafe combination is one nothing can reach.
+        if (!sink || !options.onProgress || rejected)
+            return;
+        if (newHandle)
+            newHandle = false;
+        else if (now() - checkpointedAt < CHECKPOINT_MIN_MS)
+            return;
+        checkpointedAt = now();
+        const at = checkpoint();
+        // Checked again on the chain: a note queued ahead of this one may yet be
+        // rejected, and this cursor names it.
+        sunk = sunk
+            .then(() => {
+            if (rejected)
+                return;
+            safe = at;
+            return sink(at);
+        })
+            .catch(() => { });
+    };
+    const finish = async (code) => {
+        // Everything the sink was given has been delivered before the outcome
+        // naming it is returned, so a caller cannot store a cursor that claims
+        // notes nobody filed. After a rejected note it is the last cursor behind
+        // it: the caller stores it, and a drain resumed from there files the note
+        // again, while the notes after it replay under keys the transcript dedupes.
+        await sunk;
+        const next = rejected ? safe : checkpoint();
         return code === undefined
-            ? { done: false, cursor: next, progress }
+            ? {
+                done: false,
+                cursor: next,
+                progress,
+                ...(rateLimit ? { rateLimit } : {})
+            }
             : {
                 done: true,
                 cursor: next,
                 progress,
+                ...(rateLimit ? { rateLimit } : {}),
                 exitCode: code,
                 ...(result ? { result } : {}),
                 // Only when there is no result. A session that reported for itself has
                 // said everything worth saying, and its stderr is the CLI's own
                 // diagnostic chatter — surfacing that beside a perfectly good report
                 // would bury the report.
-                ...(!result && stderr ? { stderr } : {})
+                ...(!result && (SIGNALS[code] || stderr)
+                    ? { stderr: explainExit(code, stderr) }
+                    : {})
             };
     };
     try {
@@ -290,34 +709,50 @@ export async function drainRun(handle, cursor, options) {
              * simply not there.
              *
              * Reading on is also how the sync gets *awaited*: the wrapper resolves its
-             * pull before it closes the stream, so observing `done` means the sync has
-             * already finished.
+             * pull before it closes the stream, so observing `done` means the pull was
+             * attempted. Attempted, not guaranteed — a pull that fails leaves the
+             * stream closing normally and reports itself on the result the host does
+             * not see here, and nothing retries it on its own. The host drives any
+             * outstanding pull; see this plugin's README.
+             *
+             * It is also unbounded, deliberately: the pull carries whatever the
+             * session wrote, an install's dependency tree included. Cutting it short
+             * would trade a late report for edits that never land, and that trade is
+             * not close: a drain cut with the pull still in flight is resumed, and
+             * the sync resumes from the blocks it has already committed. A pull that
+             * *fails* is the case above, and nothing retries that.
              */
             if (exitCode !== undefined) {
                 const next = await reader.read();
                 if (next.done)
-                    return finish(exitCode);
+                    return await finish(exitCode);
                 consume(next.value);
                 continue;
             }
-            const remaining = deadline - now();
-            if (remaining <= 0)
-                return await yieldWindow();
+            if (options.signal?.aborted)
+                return await stop();
+            const stopping = stopped(options.signal);
             const next = await Promise.race([
                 reader.read(),
-                sleep(remaining).then(() => WINDOW_EXPIRED)
-            ]);
-            if (next === WINDOW_EXPIRED)
-                return await yieldWindow();
+                stopping.promise
+            ]).finally(stopping.clear);
+            if (next === STOPPED)
+                return await stop();
             if (next.done) {
                 // The stream ended without an `exit` event — the container went away
                 // under the run. Report it as a failure rather than as still-running,
-                // or the caller waits out its whole chunk budget on a dead process.
-                return finish(-1);
+                // or the caller would wait on a dead process.
+                stderr = containerLost(stderr);
+                return await finish(-1);
             }
             consume(next.value);
         }
     }
+    catch (err) {
+        // See `sunk`. It never rejects: each link catches its own.
+        await sunk;
+        throw err;
+    }
     finally {
         reader.releaseLock();
     }
@@ -326,6 +761,9 @@ export async function drainRun(handle, cursor, options) {
         if (event.name === "stdout" && event.value !== undefined) {
             buffer += event.value;
             absorb();
+            // After absorbing, never before: the position offered has to be one whose
+            // notes are already on the sink's queue.
+            offerCheckpoint();
         }
         // stderr is Claude Code's own diagnostics, not the protocol stream. Kept out
         // of the parser so a warning line cannot be mistaken for an event — but
@@ -338,25 +776,93 @@ export async function drainRun(handle, cursor, options) {
             exitCode = event.code ?? -1;
     }
     /**
-     * End the window with the session still running.
+     * End the drain with the session still running.
      *
      * **Cancels rather than merely releasing the lock.** Releasing leaves the
-     * attachment and its pending read alive on the far side, and a chunked run
-     * would strand one per window. `cancel` is the wrapper's own designed exit —
-     * it settles the pending read, resolves the sync outcome as `pending`, and
-     * lets the next chunk's `getExec` open a fresh attachment that will run the
-     * real sync when the session finally ends.
+     * attachment and its pending read alive on the far side, and the next drain
+     * would find it still subscribed. `cancel` is the wrapper's own designed exit
+     * — it settles the pending read, resolves the sync outcome as `pending`, and
+     * lets the next `getExec` open a fresh attachment that will run the real sync
+     * when the session finally ends.
+     *
+     * **Cancels before settling the sinks, not after**, so the attachment is not
+     * held open across notes still being filed. Safe in this order because
+     * `finish` reads only what `consume` already put in local state, and takes
+     * nothing off the stream.
      */
-    async function yieldWindow() {
+    async function stop() {
         absorb();
-        const outcome = finish();
-        await reader.cancel("chunk window expired").catch(() => { });
-        return outcome;
+        await reader.cancel("drain stopped").catch(() => { });
+        return await finish();
     }
 }
+/**
+ * The signal behind each exit code `computerd` maps one to — the ones a process
+ * is stopped from outside with.
+ */
+const SIGNALS = { 143: "SIGTERM", 137: "SIGKILL" };
+/** A resultless session's `stderr`, explained when a signal ended it. */
+function explainExit(code, stderr) {
+    const signal = SIGNALS[code];
+    if (!signal)
+        return stderr;
+    return endedFromOutside(`the process was stopped by ${signal} before it reported a result — its ` +
+        "container stopping, its time limit or a cancel does this.", stderr);
+}
+/**
+ * What a session reports on `stderr` when its container went away under it:
+ * the stream ended with no `exit` event, or a re-attach found the exec gone.
+ */
+export function containerLost(printed = "") {
+    return endedFromOutside("the container holding this session was stopped or replaced before the " +
+        "session finished — a deploy or a container rollout does this — so the " +
+        "process was ended from outside and reported no result.", printed);
+}
+/**
+ * The report for a process that did not end on its own: why, what that leaves,
+ * then what it had printed.
+ *
+ * **The cause comes first.** What the process printed is not why it ended, and
+ * without this it is all a report shows — so whatever came last, a startup
+ * warning included, reads as the cause.
+ *
+ * **What it must not say is that starting over is safe.** A session is an
+ * agent: by the time it was stopped, 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 process 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.
+ */
+function endedFromOutside(cause, printed) {
+    const said = printed.trim();
+    return (`${cause} 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 work again, since a rerun repeats from the beginning." +
+        (said
+            ? `\n\nWhat it had printed by then, which is not why it ended:\n${said}`
+            : ""));
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * The caller's signal, as a race a read can win.
+ *
+ * Cleared by the caller whichever side wins: one listener is added per read,
+ * and a session is many reads.
+ */
+function stopped(signal) {
+    let onAbort = () => { };
+    const promise = new Promise((resolve) => {
+        onAbort = () => resolve(STOPPED);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+    return {
+        promise,
+        clear: () => signal?.removeEventListener("abort", onAbort)
+    };
+}
 /** How much stderr is worth carrying, in characters. */
 const STDERR_MAX = 2_000;
 /**
@@ -372,9 +878,9 @@ const STDERR_MAX = 2_000;
  * gives up prints one line and exits, making that line the last thing there is.
  * Keeping both ends costs a few hundred characters and removes the guess.
  *
- * Not a re-implementation of `/computer`'s `truncateOutput`: reaching across the
- * subpath boundary for it would merge two realms `verify:exports` keeps apart,
- * which is the same reason `/repo` carries its own.
+ * Not `truncateOutput`, and the difference is the marker: this runs on every
+ * append, so the cut has to stay a single character rather than a sentence that
+ * would be re-cut and nested on the next one.
  */
 function boundStderr(text) {
     if (text.length <= STDERR_MAX)