@dynamicagents/plugins 0.12.0 → 0.13.0

package/dist/claude-code/run.js

@@ -1,4 +1,5 @@
 import { shellQuote } from "@cloudflare/computer";
+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. */
@@ -6,21 +7,27 @@ 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.
@@ -44,6 +51,41 @@ 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`.
  *
@@ -73,17 +115,19 @@ function gitIdentityEnv(author) {
  * 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.
+ * 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: `http-gateway` egress intercepts
  * transparently, so the client talks to the real hostname and the gateway sees
@@ -132,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.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.
@@ -155,9 +244,10 @@ export function buildLaunch(options) {
         env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS = String(options.maxConcurrentSubagents);
     return {
         command: argv.join(" "),
-        // The last three 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
@@ -172,6 +262,8 @@ export function buildLaunch(options) {
                 ? { IS_SANDBOX: "1" }
                 : undefined),
             ...gitIdentityEnv(options.author),
+            ...(options.github ? githubEnv() : undefined),
+            [CONFIG_DIR_ENV_KEY]: SESSION_CONFIG_DIR,
             [RESERVED_ENV_KEY]: CREDENTIAL_PLACEHOLDER
         }
     };
@@ -204,8 +296,8 @@ function changedReading(previous, next) {
     const after = { ...next };
     return [...new Set([...Object.keys(before), ...Object.keys(after)])].some((key) => before[key] !== after[key]);
 }
-/** Distinguishes "the window ran out" from a real stream event in the race below. */
-const WINDOW_EXPIRED = Symbol("window-expired");
+/** 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.
  *
@@ -217,7 +309,7 @@ const WINDOW_EXPIRED = Symbol("window-expired");
  */
 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";
 }
 /**
@@ -226,26 +318,26 @@ function isExecBusy(err) {
  * `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.
+ * 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* window's attachment, not yet released.
- *
- * An exec's event stream admits one subscriber at a time. A chunk boundary asks
- * for the next one within milliseconds of the last one returning, 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. So the
- * boundary races the teardown every time, and {@link attachRun} answers by
+ * 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 at a Workflow step
- * as a plain `Error` with no `code` — unlike `EEXEC_BUSY` and `EEXEC_LOST`
+ * 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.
@@ -263,11 +355,11 @@ function isExecSubscribed(err) {
  * 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 Workflow step retries with a fresh
- * isolate — which is the right escalation, and the one this whole mechanism
- * exists to stop being the *first* resort.
+ * 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 boundary normally clears
+ * 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.
  */
@@ -287,18 +379,18 @@ 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 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.
+ * 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);
@@ -315,21 +407,22 @@ 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.
  *
- * **Waits out a subscriber the previous window has not released yet**, and that
+ * **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 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}.
+ * 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
@@ -346,14 +439,16 @@ export async function attachRun(runtime, cursor, options = {}) {
             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.
+                // 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)
+            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
@@ -362,66 +457,90 @@ export async function attachRun(runtime, cursor, options = {}) {
             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 the Workflow was absorbing it a retry at a time.
-            console.info("[claude-code] the previous window is still attached — waiting", { execId: cursor.execId, waitMs });
+            // 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();
     /**
-     * The window's notes, in order — built as the stream is parsed rather than
+     * 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 window's reading only — see `DrainOutcome`. Starting undefined also
-    // means the first reading of each window reaches the log, which is what keeps
+    // 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 a post is a
-     * signed round trip, so awaiting one inside the read loop would stall the
-     * drain for as long as the session keeps talking. Failures are swallowed here
-     * because the sink's own contract is best-effort; settled before the drain
-     * returns, so nothing is cut short when the RPC unwinds.
+     * 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 a whole window's 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) {
             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
@@ -452,15 +571,24 @@ export async function drainRun(handle, cursor, options) {
             }
         }
         // Numbered from the running total, so a note has the same key whether it is
-        // posted from here or returned on the outcome — and the same key again when
-        // a retry replays this part of the stream, which is what makes the duplicate
-        // harmless. See `toProgress`.
+        // 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(() => { });
+                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
@@ -485,45 +613,65 @@ export async function drainRun(handle, cursor, options) {
      * 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
-     * gatekeeper has never seen.
+     * 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 persist, at most every
-     * {@link CHECKPOINT_MIN_MS}.
+     * 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 posted; offered to a
-        // caller that posts nothing, it advances a cursor past notes that were never
-        // delivered, and a chunk dying after it loses them permanently. The
+        // 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)
+        if (!sink || !options.onProgress || rejected)
             return;
-        if (now() - checkpointedAt < CHECKPOINT_MIN_MS)
+        if (newHandle)
+            newHandle = false;
+        else if (now() - checkpointedAt < CHECKPOINT_MIN_MS)
             return;
         checkpointedAt = now();
         const at = checkpoint();
-        sunk = sunk.then(() => sink(at)).catch(() => { });
+        // 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) => {
-        const next = checkpoint();
         // Everything the sink was given has been delivered before the outcome
-        // naming it is returned, so a caller cannot commit a cursor that claims
-        // notes nobody posted.
+        // 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,
@@ -542,7 +690,9 @@ export async function drainRun(handle, cursor, options) {
                 // 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 {
@@ -566,14 +716,11 @@ export async function drainRun(handle, cursor, options) {
              * 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, so this last read
-             * can outlast the window that was left — and the step with it. Cutting it
-             * short to keep the window would trade a late chunk for edits that never
-             * land, and that trade is not close: a step killed with the pull still in
-             * flight is retried, and the sync resumes from the blocks it has already
-             * committed. A pull that *fails* is the case above, and nothing retries
-             * that. See {@link file://./config.ts ClaudeCodeConfig.windowMs} for how
-             * the window is sized around an unbounded tail.
+             * 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();
@@ -582,22 +729,30 @@ export async function drainRun(handle, cursor, options) {
                 consume(next.value);
                 continue;
             }
-            const remaining = deadline - now();
-            if (remaining <= 0)
-                return await yieldWindow();
-            const timer = windowTimer(remaining);
-            const next = await Promise.race([reader.read(), timer.expired]).finally(timer.clear);
-            if (next === WINDOW_EXPIRED)
-                return await yieldWindow();
+            if (options.signal?.aborted)
+                return await stop();
+            const stopping = stopped(options.signal);
+            const next = await Promise.race([
+                reader.read(),
+                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.
+                // 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();
     }
@@ -621,46 +776,92 @@ 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.** `finish` awaits every
-     * progress post this window queued — signed round trips to the gatekeeper, one
-     * per note — and holding the attachment open across them handed the next chunk
-     * a subscriber that was still live for no reason but ordering. Safe in this
-     * order because `finish` reads only what `consume` already put in local state,
-     * and takes nothing off the stream. It does not close the race that
-     * {@link attachRun} waits out — the release is still asynchronous on the far
-     * side — it just stops this end adding to it.
+     * **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();
-        await reader.cancel("chunk window expired").catch(() => { });
+        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));
 }
 /**
- * What's left of the window, as a race a read can win.
+ * The caller's signal, as a race a read can win.
  *
- * Cleared by the caller whichever side wins: one is armed per read, and a timer
- * left pending holds the facet's `executeChunk` open until the window's end, so
- * a session that finishes in seconds would still cost the whole window.
+ * Cleared by the caller whichever side wins: one listener is added per read,
+ * and a session is many reads.
  */
-function windowTimer(ms) {
-    let id;
-    const expired = new Promise((resolve) => {
-        id = setTimeout(() => resolve(WINDOW_EXPIRED), ms);
+function stopped(signal) {
+    let onAbort = () => { };
+    const promise = new Promise((resolve) => {
+        onAbort = () => resolve(STOPPED);
+        signal?.addEventListener("abort", onAbort, { once: true });
     });
-    return { expired, clear: () => clearTimeout(id) };
+    return {
+        promise,
+        clear: () => signal?.removeEventListener("abort", onAbort)
+    };
 }
 /** How much stderr is worth carrying, in characters. */
 const STDERR_MAX = 2_000;