@agentproto/adapter-claude-code-cloud 0.1.0 → 0.2.1

package/CLAUDE-CODE-CLOUD.md

@@ -12,7 +12,7 @@ relays the vendor's own client + sessions API onto ACP.
 
 | Method                 | Behaviour                                                                                                                                                                     |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `initialize`           | Returns `PROTOCOL_VERSION` + `agentCapabilities.loadSession=false` (re-attach is via the persisted vendor session id, AIP-66 §5).                                                |
+| `initialize`           | Returns `PROTOCOL_VERSION` + `agentCapabilities.loadSession=true` (`session/load` adopts the persisted vendor session id, AIP-66 §5).                                           |
 | `authenticate`         | No-op. Auth is the user's claude.ai login inside the claude CLI (keychain); preflighted per turn (`claude auth status` — api_key auth and not-logged-in are refused).          |
 | `session/new`          | Validates `cwd` per AIP-66 §3 BEFORE any vendor side effect: a git checkout, clean working tree, an `origin` remote, and a HEAD contained in some `origin/*` ref. Refuses `mcpServers` (AIP-66 §4). |
 | `session/prompt`       | First prompt → `claude --cloud "<prompt>"` under a PTY (start; answers the first-run folder-trust prompt), later prompts → `claude -p "<text>" --cloud <session id>` (send-only). Then polls `GET /v1/code/sessions/{id}/events` (2s, backing off to 10s) until a NEW `result` event arrives. |
@@ -41,6 +41,34 @@ a timer or on poll silence. Stop reason: `end_turn` for a success result,
 failures (HTTP 5xx, network) are retried with the poll backoff — a read
 failure never ends a turn — until 5 consecutive ones fail the prompt.
 
+## Event paging & ordering (Appendix)
+
+`GET /v1/code/sessions/{id}/events` does NOT page forward. Observed
+2026-10-14 against the live API:
+
+- **No `cursor` → the NEWEST page**, up to 50 events, newest first.
+- **`resume_cursor`** (alias `next_cursor`, present on the first/no-cursor
+  page only) is the `sequence_num` of the OLDEST event on that page. Passing
+  it back as `?cursor=<n>` returns the next **OLDER** page — the cursor
+  pages **BACKWARD in time**, not forward. (Real example: the newest page
+  held seq 60..11 with `next_cursor` `"11"`; `?cursor=11` returned seq
+  10..1 with `resume_cursor` `"1"`.)
+- **`sequence_num`** is a STRING of an integer, strictly increasing within a
+  session, and is the ordering key. Parse with `Number()`; skip an event
+  whose `sequence_num` is not finite. Every event also carries `event_id`,
+  `event_type`, `payload` (the stream-json message), `source`
+  (`"worker"`/`"client"`) and `created_at`.
+
+The relay therefore tracks progress by `sequence_num`, not by cursor: it
+keeps a per-session `lastSeq` (the highest seq projected or seeded), polls
+the newest page each tick, walks `cursor` backward only as far as needed to
+reach `lastSeq` (capped at 20 pages/tick), then projects the new events in
+ASCENDING seq order. `session/load` seeds `lastSeq` from ONE newest-page GET
+(its max seq is the history high-water — no backward paging needed). Before
+each prompt the relay records the current high-water seq; only a `result`
+with a seq ABOVE that baseline can end the turn, so a prior turn's result
+never ends a new one.
+
 ## Usage telemetry
 
 When the `result` event carries `total_cost_usd` and/or `usage`, it is
@@ -56,6 +84,44 @@ and kept for every later turn; the host is expected to persist it on the
 session descriptor (`meta.cloud = { vendor, sessionId, url }`) and re-attach
 rather than start a new vendor session after a restart.
 
+## Re-attach (AIP-66 §5)
+
+The vendor id only exists AFTER the first prompt reaches the vendor, so the
+handoff from relay to host is a side file plus a poll, and the re-attach
+itself rides the ordinary ACP `session/load` resume path:
+
+- **Meta-file handoff.** At spawn the host sets
+  `AGENTPROTO_CLOUD_SESSION_META_FILE` to a path inside the session's
+  isolated config dir. Whenever the relay learns the vendor id — after
+  `claude --cloud` prints it, or when `session/load` adopts an id handed
+  back by the host — it writes exactly the three §5 fields
+  `{ vendor, sessionId, url }` there (`src/meta-file.ts`, atomic
+  temp-file + rename, best-effort: a failed write never sinks the turn,
+  and a re-attach preserves an existing `url` for the same id). The file
+  is the ONLY channel: no credential, keychain material, or bearer token
+  ever enters it, the descriptor's `meta.cloud`, logs or events (AIP-66
+  §8) — it is byte-scoped to those three fields.
+- **The host's watch.** The runtime polls that file every 2s (timers
+  unref'd, NO fixed timeout) and stamps the learned mapping onto the
+  session's `meta.cloud` the moment it appears; the watch stops on learn
+  or when the session ends.
+- **`session/load`.** A restart or re-attach hands the relay the vendor id
+  persisted on `meta.cloud.sessionId` through the standard ACP
+  `session/load`. The relay validates it against the repo source first
+  (an id that isn't `session_`/`cse_`, or whose repo no longer matches,
+  fails closed), ADOPTS it — never starting a replacement vendor session —
+  pre-marks the vendor's existing events so only the next turn's own
+  `result` can end it, and resumes through `sendPrompt`
+  (`claude -p --cloud <id>`).
+- **The resume fallback.** The spawn-time watch dies with a daemon
+  restart, so every resume point first reads `meta.cloud.sessionId`; when
+  the descriptor never learned one, the runtime falls back to reading the
+  relay's meta file inside the row's own config dir
+  (`cloudSessionMetaFilePath`) and stamps the found mapping back onto the
+  descriptor before resuming. Only when both sources are empty does the
+  resume fall back to the ordinary ACP uuid, which fails closed at the
+  vendor.
+
 ## Repo source (AIP-66 §3)
 
 The cloud runs the user's REPO from its git remote — never an uploaded

package/README.md

@@ -25,8 +25,12 @@ zero — AIP-66 §7).
   from the `Claude Code-credentials` keychain entry (org uuid from
   `~/.claude.json`), or `CLAUDE_CLOUD_OAUTH_TOKEN` when injected. A CLI
   authenticated by API key, or not logged in, is refused with a pointer to
-  `claude auth login`. The token is only ever used as a request header — never
-  logged or persisted (AIP-66 §8).
+  `claude auth login`. When the token is expired (or within five minutes of
+  expiry) or the API answers 401, the adapter runs `claude -p "Reply OK"
+  --model haiku` once to let the CLI re-mint it, drops its cached credential,
+  and retries — a still-failing call reports `run \`claude auth login\``. The
+  token is only ever used as a request header — never logged or persisted
+  (AIP-66 §8).
 - **A clean, pushed git checkout as the session cwd.** The cloud runs the repo
   from its git remote, never an uploaded working tree, so `session/new`
   refuses (AIP-66 §3) a non-git cwd, a dirty working tree, a missing `origin`

package/dist/acp-server.mjs

@@ -1,3 +1,3 @@
-export { ClaudeCloudAcpAgent, MAX_LIST_EVENTS_FAILURES, POLL_INITIAL_MS, POLL_MAX_MS, SEEN_EVENT_IDS_LIMIT, isTransientListEventsError, main, promptText, resultEventUpdates, resultStopReason, runAcpOverStdio } from './chunk-KA4G4O2X.mjs';
+export { ClaudeCloudAcpAgent, MAX_LIST_EVENTS_FAILURES, OBSERVE_PAGES_LIMIT, POLL_INITIAL_MS, POLL_MAX_MS, isTransientListEventsError, main, promptText, resultEventUpdates, resultStopReason, runAcpOverStdio } from './chunk-LN5RJ5ZT.mjs';
 //# sourceMappingURL=acp-server.mjs.map
 //# sourceMappingURL=acp-server.mjs.map

package/dist/{chunk-KA4G4O2X.mjs → chunk-LN5RJ5ZT.mjs}

@@ -3,10 +3,10 @@ import { PROTOCOL_VERSION, ndJsonStream, AgentSideConnection } from '@agentclien
 import { sdkMessageToUpdates, promptText } from '@agentproto/adapter-claude-sdk';
 export { promptText } from '@agentproto/adapter-claude-sdk';
 import { execFile, spawn } from 'child_process';
+import { homedir, tmpdir } from 'os';
 import { ANTHROPIC_CORE_SCRUB_ENV } from '@agentproto/provider-presets';
-import { readFile } from 'fs/promises';
-import { homedir } from 'os';
-import { join } from 'path';
+import { readFile, mkdir, writeFile, rename } from 'fs/promises';
+import { join, dirname } from 'path';
 import { promisify } from 'util';
 
 /**
@@ -15,6 +15,7 @@ import { promisify } from 'util';
  */
 
 var execFileAsync = promisify(execFile);
+var EXPIRY_SKEW_MS = 5 * 6e4;
 var KEYCHAIN_SERVICE = "Claude Code-credentials";
 function keychainCredentialSource(deps = {}) {
   const execFileImpl = deps.execFileImpl ?? (async (cmd, args) => {
@@ -52,8 +53,16 @@ function keychainCredentialSource(deps = {}) {
         orgUuid = rc.oauthAccount?.organizationUuid;
       } catch {
       }
-      cached = { accessToken, ...orgUuid ? { orgUuid } : {} };
+      const expiresAt = keychain.claudeAiOauth?.expiresAt;
+      cached = {
+        accessToken,
+        ...orgUuid ? { orgUuid } : {},
+        ...typeof expiresAt === "number" ? { expiresAt } : {}
+      };
       return cached;
+    },
+    invalidate() {
+      cached = null;
     }
   };
 }
@@ -68,9 +77,17 @@ function envCredentialSource(env = process.env) {
       }
       const orgUuid = env.CLAUDE_CLOUD_ORG_UUID;
       return { accessToken, ...orgUuid ? { orgUuid } : {} };
+    },
+    invalidate() {
     }
   };
 }
+function eventSequence(event) {
+  const raw = event.sequence_num;
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
 function normalizeSessionId(id) {
   const trimmed = id.trim();
   if (trimmed.startsWith("session_")) return `cse_${trimmed.slice("session_".length)}`;
@@ -84,13 +101,18 @@ function toCliSessionId(id) {
   return `session_${normalized.slice("cse_".length)}`;
 }
 var UNAUTHORIZED_HINT = "run `claude auth login`";
+function isCredentialExpiring(credential, now = Date.now()) {
+  return credential.expiresAt !== void 0 && credential.expiresAt - now <= EXPIRY_SKEW_MS;
+}
 var SessionsApi = class {
   #credentials;
+  #refreshLogin;
   #fetch;
   #baseUrl;
   #credential = null;
   constructor(options) {
     this.#credentials = options.credentials;
+    this.#refreshLogin = options.refreshLogin;
     this.#fetch = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
     this.#baseUrl = (options.baseUrl ?? "https://api.anthropic.com").replace(/\/$/, "");
   }
@@ -102,8 +124,9 @@ var SessionsApi = class {
     );
   }
   /**
-   * GET /v1/code/sessions/{id}/events — newest first. Pass the previous
-   * page's `resume_cursor` as `cursor` to resume after it.
+   * GET /v1/code/sessions/{id}/events — newest first. With no `cursor` this
+   * returns the NEWEST page; pass the page's `resume_cursor` (the oldest
+   * event's `sequence_num`) as `cursor` to fetch the next OLDER page.
    */
   async listEvents(id, opts = {}) {
     const params = new URLSearchParams();
@@ -127,8 +150,26 @@ var SessionsApi = class {
     if (!this.#credential) this.#credential = await this.#credentials.get();
     return this.#credential;
   }
-  async #request(method, path, retriedAuth = false) {
+  /** Refresh the login (when injected), drop the source cache, and re-read.
+   *  A refresh failure is surfaced to the caller — better a clear "run
+   *  `claude auth login`" than a request with a known-stale token. */
+  async #refreshAndInvalidate() {
+    await this.#refreshLogin?.();
+    this.#credentials.invalidate();
+    this.#credential = null;
+  }
+  /** The credential for the next request: refresh first when it is expired
+   *  or expiring. Without an injected refresh the check is a no-op. */
+  async #freshCredential() {
     const credential = await this.#credentialNow();
+    if (this.#refreshLogin && isCredentialExpiring(credential)) {
+      await this.#refreshAndInvalidate();
+      return this.#credentialNow();
+    }
+    return credential;
+  }
+  async #request(method, path, retriedAuth = false) {
+    const credential = retriedAuth ? await this.#credentialNow() : await this.#freshCredential();
     const headers = {
       authorization: `Bearer ${credential.accessToken}`,
       "anthropic-version": "2023-06-01",
@@ -137,7 +178,7 @@ var SessionsApi = class {
     };
     const res = await this.#fetch(`${this.#baseUrl}${path}`, { method, headers });
     if (res.status === 401 && !retriedAuth) {
-      this.#credential = null;
+      await this.#refreshAndInvalidate();
       return this.#request(method, path, true);
     }
     if (res.status === 401) {
@@ -174,8 +215,18 @@ function cloudChildEnv(base = process.env) {
   }
   return out;
 }
+var ANSI_ESCAPE_RE = /\x1b\][\s\S]*?(?:\x07|\x1b\\)|\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b./g;
+function normalizePtyOutput(raw) {
+  return raw.replace(ANSI_ESCAPE_RE, " ").replace(/[^\S\n]+/g, " ").replace(/\n[ \t]*(?:\n[ \t]*)+/g, "\n").trim();
+}
+var TRUST_PROMPT_RE = /Yes,\s*I\s*trust\s*this\s*folder/i;
+var PTY_TAIL_CHARS = 300;
+function ptyOutputTail(raw, maxChars = PTY_TAIL_CHARS) {
+  const stripped = normalizePtyOutput(raw);
+  return stripped.length > maxChars ? stripped.slice(stripped.length - maxChars) : stripped;
+}
 var DEFAULT_RUN_TIMEOUT_MS = 6e4;
-function defaultCloudCliRunner() {
+function defaultCloudCliRunner(deps = {}) {
   return {
     run(cmd, args, opts) {
       return new Promise((resolve, reject) => {
@@ -216,10 +267,8 @@ function defaultCloudCliRunner() {
       });
       let proc = null;
       const pendingWrites = [];
-      void import('node-pty').then((mod) => {
-        const pty = mod.default ?? mod;
-        if (typeof pty.spawn !== "function") throw new Error("node-pty has no spawn");
-        const p = pty.spawn(cmd, args, {
+      const attach = (spawnFn) => {
+        const p = spawnFn(cmd, args, {
           name: "xterm-256color",
           cols: 120,
           rows: 40,
@@ -234,7 +283,7 @@ function defaultCloudCliRunner() {
         p.onData((chunk) => {
           output += chunk;
           opts.onData?.(chunk);
-          if (!answeredTrustPrompt && /Yes, I trust this folder/.test(output)) {
+          if (!answeredTrustPrompt && TRUST_PROMPT_RE.test(normalizePtyOutput(output))) {
             answeredTrustPrompt = true;
             p.write("\x1B[B\r");
           }
@@ -246,7 +295,7 @@ function defaultCloudCliRunner() {
           }
           rejectResult(
             new Error(
-              `claude code cloud: \`${cmd} ${args.join(" ")}\` timed out after ${opts.timeoutMs ?? 12e4}ms under the PTY`
+              `claude code cloud: \`${cmd} ${args.join(" ")}\` timed out after ${opts.timeoutMs ?? 12e4}ms under the PTY; last output: ${ptyOutputTail(output)}`
             )
           );
         }, opts.timeoutMs ?? 12e4);
@@ -255,13 +304,26 @@ function defaultCloudCliRunner() {
           clearTimeout(timer);
           resolveResult({ code: exitCode, output });
         });
-      }).catch((err) => {
-        rejectResult(
-          new Error(
-            `claude code cloud: \`claude --cloud\` needs a real PTY and node-pty is not available (${err instanceof Error ? err.message : String(err)}) \u2014 install it (npm i node-pty) to use managed cloud sessions`
-          )
-        );
-      });
+      };
+      if (deps.spawnPty) {
+        try {
+          attach(deps.spawnPty);
+        } catch (err) {
+          rejectResult(err);
+        }
+      } else {
+        void import('node-pty').then((mod) => {
+          const pty = mod.default ?? mod;
+          if (typeof pty.spawn !== "function") throw new Error("node-pty has no spawn");
+          attach(pty.spawn);
+        }).catch((err) => {
+          rejectResult(
+            new Error(
+              `claude code cloud: \`claude --cloud\` needs a real PTY and node-pty is not available (${err instanceof Error ? err.message : String(err)}) \u2014 install it (npm i node-pty) to use managed cloud sessions`
+            )
+          );
+        });
+      }
       return {
         write: (data) => {
           if (proc) proc.write(data);
@@ -272,6 +334,43 @@ function defaultCloudCliRunner() {
     }
   };
 }
+function createRefreshLogin(opts = {}) {
+  let inFlight = null;
+  return () => {
+    if (inFlight) return inFlight;
+    const run = (async () => {
+      const runner = opts.runner ?? defaultCloudCliRunner();
+      const env = cloudChildEnv(opts.env ?? process.env);
+      let result;
+      try {
+        result = await runner.run(
+          "claude",
+          ["-p", "Reply OK", "--model", "haiku"],
+          {
+            cwd: opts.cwd ?? tmpdir(),
+            env,
+            stdin: "ignore",
+            timeoutMs: opts.timeoutMs ?? 6e4
+          }
+        );
+      } catch (err) {
+        throw new Error(
+          `claude code cloud: could not refresh the claude.ai login \u2014 is the claude CLI installed and on PATH? (${err instanceof Error ? err.message : String(err)})`
+        );
+      }
+      if (result.code !== 0) {
+        throw new Error(
+          `claude code cloud: could not refresh the claude.ai login (exit ${result.code}) \u2014 run \`claude auth login\``
+        );
+      }
+    })();
+    const wrapped = run.finally(() => {
+      if (inFlight === wrapped) inFlight = null;
+    });
+    inFlight = wrapped;
+    return wrapped;
+  };
+}
 function parseAuthStatus(stdout) {
   const trimmed = stdout.trim();
   const start = trimmed.indexOf("{");
@@ -317,12 +416,13 @@ async function preflightAuth(runner, opts) {
   return status;
 }
 function parseCloudStartOutput(output) {
+  const transcript = normalizePtyOutput(output);
   let sessionId;
   let url;
   let title;
-  const resume = output.match(/Resume with:\s*claude\s+--teleport\s+(session_[A-Za-z0-9_-]+)/);
+  const resume = transcript.match(/Resume with:\s*claude\s+--teleport\s+(session_[A-Za-z0-9_-]+)/);
   if (resume?.[1]) sessionId = resume[1];
-  const view = output.match(/View:\s*(https?:\/\/\S+)/);
+  const view = transcript.match(/View:\s*(https?:\/\/\S+)/);
   if (view?.[1]) {
     url = view[1];
     if (!sessionId) {
@@ -330,7 +430,7 @@ function parseCloudStartOutput(output) {
       if (fromUrl?.[1]) sessionId = `session_${fromUrl[1]}`;
     }
   }
-  const created = output.match(/Created cloud session:\s*(.+)/);
+  const created = transcript.match(/Created cloud session:\s*(.+)/);
   if (created?.[1]) title = created[1].trim();
   if (!sessionId) return null;
   return {
@@ -383,6 +483,49 @@ async function sendPrompt(sessionId, text, opts) {
   }
   return { stdout: result.stdout };
 }
+var CLOUD_SESSION_META_FILE_ENV = "AGENTPROTO_CLOUD_SESSION_META_FILE";
+var CLOUD_VENDOR_SLUG = "anthropic";
+async function readExisting(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+    const p = parsed;
+    if (typeof p["vendor"] !== "string" || p["vendor"].length === 0) return void 0;
+    if (typeof p["sessionId"] !== "string" || p["sessionId"].length === 0) return void 0;
+    return {
+      vendor: p["vendor"],
+      sessionId: p["sessionId"],
+      ...typeof p["url"] === "string" && p["url"].length > 0 ? { url: p["url"] } : {}
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function writeCloudSessionMeta(meta, opts = {}) {
+  const env = opts.env ?? process.env;
+  const path = env[CLOUD_SESSION_META_FILE_ENV];
+  if (!path) return null;
+  try {
+    const existing = await readExisting(path);
+    const url = meta.url ?? (existing?.sessionId === meta.sessionId ? existing.url : void 0);
+    const payload = JSON.stringify({
+      vendor: meta.vendor,
+      sessionId: meta.sessionId,
+      ...url !== void 0 ? { url } : {}
+    });
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    await writeFile(tmp, payload, "utf8");
+    await rename(tmp, path);
+    return path;
+  } catch (err) {
+    process.stderr.write(
+      `[claude-code-cloud] could not write the cloud session meta file (${CLOUD_SESSION_META_FILE_ENV}): ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return null;
+  }
+}
 var execFileAsync2 = promisify(execFile);
 var defaultGitRunner = async (args, cwd) => {
   try {
@@ -439,6 +582,7 @@ async function validateRepoSource(cwd, git = defaultGitRunner) {
 var POLL_INITIAL_MS = 2e3;
 var POLL_MAX_MS = 1e4;
 var MAX_LIST_EVENTS_FAILURES = 5;
+var OBSERVE_PAGES_LIMIT = 20;
 var NETWORK_ERROR_CODES = /^(ECONNABORTED|ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ENETUNREACH|EAI_AGAIN|ENOTFOUND|EPIPE|ETIMEDOUT|UND_ERR)/;
 function isTransientListEventsError(err) {
   if (!(err instanceof Error)) return false;
@@ -452,16 +596,6 @@ function isTransientListEventsError(err) {
   }
   return false;
 }
-var SEEN_EVENT_IDS_LIMIT = 500;
-function rememberSeenEventId(session, id) {
-  const seen = session.seenEventIds;
-  seen.add(id);
-  while (seen.size > SEEN_EVENT_IDS_LIMIT) {
-    const oldest = seen.values().next();
-    if (oldest.done) break;
-    seen.delete(oldest.value);
-  }
-}
 function defaultSleep(ms) {
   return new Promise((resolve) => {
     const timer = setTimeout(resolve, ms);
@@ -471,8 +605,9 @@ function defaultSleep(ms) {
 function defaultDeps() {
   const runner = defaultCloudCliRunner();
   const credentials = keychainCredentialSource();
+  const refreshLogin = createRefreshLogin({ runner, env: process.env });
   return {
-    api: new SessionsApi({ credentials }),
+    api: new SessionsApi({ credentials, refreshLogin }),
     cli: {
       startCloudSession: (prompt, opts) => startCloudSession(prompt, {
         cwd: opts.cwd,
@@ -536,9 +671,10 @@ var ClaudeCloudAcpAgent = class {
     return {
       protocolVersion: PROTOCOL_VERSION,
       agentCapabilities: {
-        // Sessions live in the vendor's cloud; re-attach is via the vendor
-        // id, not an ACP session/load replay (AIP-66 §5).
-        loadSession: false
+        // Re-attach rides ACP `session/load` with the vendor session id the
+        // host persisted on `meta.cloud.sessionId` (AIP-66 §5) — that call
+        // ADOPTS the existing cloud session, it never starts a new one.
+        loadSession: true
       }
     };
   }
@@ -557,12 +693,117 @@ var ClaudeCloudAcpAgent = class {
       cwd: params.cwd,
       vendorSessionId: null,
       vendorUrl: null,
-      pollCursor: null,
-      seenEventIds: /* @__PURE__ */ new Set(),
+      lastSeq: 0,
+      turnBaseline: 0,
       promptInFlight: false
     });
     return { sessionId: id };
   }
+  /**
+   * AIP-66 §5 re-attach: ADOPT the vendor session id the host persisted on
+   * `meta.cloud.sessionId` as this ACP session's vendor session. No vendor
+   * side effect happens here — the next `session/prompt` goes through
+   * `sendPrompt` (`claude -p … --cloud <id>`), never `startCloudSession`,
+   * so a resumed relay can never replace the vendor's session with a new
+   * one. The adopted id is also reported back to the host's meta file so a
+   * re-attach against a fresh config dir still carries the §5 mapping.
+   *
+   * Fails closed on an id the vendor could never own (e.g. the ACP uuid of
+   * a spawn whose vendor id was never learned): no session is started in
+   * its place.
+   */
+  async loadSession(params) {
+    if (params.mcpServers && params.mcpServers.length > 0) {
+      throw new Error(
+        "claude code cloud: mcpServers is not supported for managed cloud agents (AIP-66 \xA74) \u2014 the vendor owns the harness"
+      );
+    }
+    let vendorSessionId;
+    try {
+      vendorSessionId = toCliSessionId(params.sessionId);
+    } catch {
+      throw new Error(
+        `claude code cloud: session/load needs the vendor session id, got ${JSON.stringify(params.sessionId)} \u2014 expected session_<id> or cse_<id> (AIP-66 \xA75). That id was never learned onto meta.cloud.sessionId, so there is no vendor session to re-attach to \u2014 and this relay will not start a replacement.`
+      );
+    }
+    await this.#validateRepo(params.cwd);
+    const session = {
+      id: vendorSessionId,
+      cwd: params.cwd,
+      vendorSessionId,
+      vendorUrl: null,
+      lastSeq: 0,
+      turnBaseline: 0,
+      promptInFlight: false
+    };
+    this.#sessions.set(vendorSessionId, session);
+    await this.#seedHistory(session, vendorSessionId);
+    await writeCloudSessionMeta({ vendor: CLOUD_VENDOR_SLUG, sessionId: vendorSessionId });
+    return {};
+  }
+  /** Seed `lastSeq` from the vendor's newest events page. Best effort: a
+   *  failed seed degrades to (at worst) an early end on an older `result` —
+   *  it must never turn a re-attach into a failed load, which AIP-66 §5
+   *  forbids replacing with a fresh start anyway.
+   *
+   *  ONE newest-page GET with no cursor: it returns the newest page (newest
+   *  first), so its max `sequence_num` is the history high-water. No
+   *  backward paging is needed — `lastSeq` only has to be high enough that
+   *  the first post-attach poll projects nothing already in the history. */
+  async #seedHistory(session, vendorSessionId) {
+    try {
+      session.lastSeq = await this.#highWaterSeq(vendorSessionId);
+    } catch (err) {
+      process.stderr.write(
+        `[claude-code-cloud] session/load: could not seed the vendor's existing event high-water (${err instanceof Error ? err.message : String(err)})
+`
+      );
+    }
+  }
+  /** Max `sequence_num` on the session's newest events page (0 when the
+   *  page is empty). One newest-page GET, no cursor. */
+  async #highWaterSeq(vendorSessionId) {
+    const res = await this.#api.listEvents(vendorSessionId, {});
+    let max = 0;
+    for (const event of res.data ?? []) {
+      const seq = eventSequence(event);
+      if (seq !== null && seq > max) max = seq;
+    }
+    return max;
+  }
+  /**
+   * Read every event newer than `lastSeq`, in ascending seq order, walking
+   * the API's cursor BACKWARD as far as needed. The API serves the NEWEST
+   * page with no cursor and pages toward OLDER events via `?cursor=<n>`
+   * (sessions-api.ts), so catching up across a >1-page gap means following
+   * `resume_cursor` and collecting the seqs above `lastSeq` until a page
+   * reaches already-projected history. Capped at {@link OBSERVE_PAGES_LIMIT}
+   * pages per call.
+   */
+  async #collectNewEvents(vendorSessionId, lastSeq) {
+    const collected = [];
+    let cursor;
+    for (let page = 0; page < OBSERVE_PAGES_LIMIT; page += 1) {
+      const res = await this.#api.listEvents(
+        vendorSessionId,
+        cursor ? { cursor } : {}
+      );
+      const events = res.data ?? [];
+      let oldest = null;
+      for (const event of events) {
+        const seq = eventSequence(event);
+        if (seq === null) continue;
+        if (oldest === null || seq < oldest) oldest = seq;
+        if (seq > lastSeq) collected.push({ seq, event });
+      }
+      if (events.length === 0 || oldest === null || oldest <= lastSeq + 1) break;
+      const next = res.resume_cursor ?? res.next_cursor;
+      if (!next || next === cursor) break;
+      cursor = next;
+    }
+    collected.sort((a, b) => a.seq - b.seq);
+    return collected;
+  }
   async prompt(params) {
     const session = this.#sessions.get(params.sessionId);
     if (!session) throw new Error(`unknown session ${params.sessionId}`);
@@ -580,6 +821,11 @@ var ClaudeCloudAcpAgent = class {
         });
         session.vendorSessionId = started.sessionId;
         session.vendorUrl = started.url;
+        await writeCloudSessionMeta({
+          vendor: CLOUD_VENDOR_SLUG,
+          sessionId: started.sessionId,
+          url: started.url
+        });
         await this.#conn.sessionUpdate({
           sessionId: session.id,
           update: {
@@ -590,7 +836,9 @@ var ClaudeCloudAcpAgent = class {
             }
           }
         });
+        session.turnBaseline = 0;
       } else {
+        session.turnBaseline = await this.#highWaterSeq(session.vendorSessionId);
         await this.#cli.sendPrompt(session.vendorSessionId, text, {
           cwd: session.cwd
         });
@@ -607,12 +855,9 @@ var ClaudeCloudAcpAgent = class {
     let delay = this.#pollInitialMs;
     let failures = 0;
     for (; ; ) {
-      let page;
+      let fresh;
       try {
-        page = await this.#api.listEvents(
-          vendorId,
-          session.pollCursor ? { cursor: session.pollCursor } : {}
-        );
+        fresh = await this.#collectNewEvents(vendorId, session.lastSeq);
       } catch (err) {
         if (!isTransientListEventsError(err) || failures + 1 >= MAX_LIST_EVENTS_FAILURES) {
           throw err;
@@ -623,16 +868,9 @@ var ClaudeCloudAcpAgent = class {
         continue;
       }
       failures = 0;
-      if (page.resume_cursor) session.pollCursor = page.resume_cursor;
-      const fresh = (page.data ?? []).filter((event) => !session.seenEventIds.has(event.event_id)).sort((a, b) => {
-        if (a.created_at !== b.created_at) {
-          return a.created_at < b.created_at ? -1 : 1;
-        }
-        return a.event_id < b.event_id ? -1 : 1;
-      });
       let stopReason = null;
-      for (const event of fresh) {
-        rememberSeenEventId(session, event.event_id);
+      for (const { seq, event } of fresh) {
+        session.lastSeq = Math.max(session.lastSeq, seq);
         if (event.event_type === "result") {
           if (resultStopReason(event.payload) === "refusal") {
             const errText = errorResultText(event.payload);
@@ -646,7 +884,9 @@ var ClaudeCloudAcpAgent = class {
           for (const update of resultEventUpdates(event.payload)) {
             await this.#send(session.id, update);
           }
-          stopReason = resultStopReason(event.payload);
+          if (seq > session.turnBaseline) {
+            stopReason = resultStopReason(event.payload);
+          }
         } else if (event.event_type === "user") {
           for (const update of sdkMessageToUpdates(
             event.payload
@@ -704,6 +944,6 @@ function main() {
   runAcpOverStdio();
 }
 
-export { CLAUDE_CODE_GATEWAY_ENV_UNSET, ClaudeCloudAcpAgent, MAX_LIST_EVENTS_FAILURES, POLL_INITIAL_MS, POLL_MAX_MS, SEEN_EVENT_IDS_LIMIT, SessionsApi, cloudChildEnv, defaultCloudCliRunner, defaultGitRunner, envCredentialSource, isTransientListEventsError, keychainCredentialSource, main, normalizeSessionId, parseAuthStatus, parseCloudStartOutput, preflightAuth, resultEventUpdates, resultStopReason, runAcpOverStdio, sendPrompt, startCloudSession, toCliSessionId, validateRepoSource };
-//# sourceMappingURL=chunk-KA4G4O2X.mjs.map
-//# sourceMappingURL=chunk-KA4G4O2X.mjs.map
+export { CLAUDE_CODE_GATEWAY_ENV_UNSET, CLOUD_SESSION_META_FILE_ENV, CLOUD_VENDOR_SLUG, ClaudeCloudAcpAgent, EXPIRY_SKEW_MS, MAX_LIST_EVENTS_FAILURES, OBSERVE_PAGES_LIMIT, POLL_INITIAL_MS, POLL_MAX_MS, SessionsApi, cloudChildEnv, createRefreshLogin, defaultCloudCliRunner, defaultGitRunner, envCredentialSource, isCredentialExpiring, isTransientListEventsError, keychainCredentialSource, main, normalizePtyOutput, normalizeSessionId, parseAuthStatus, parseCloudStartOutput, preflightAuth, ptyOutputTail, resultEventUpdates, resultStopReason, runAcpOverStdio, sendPrompt, startCloudSession, toCliSessionId, validateRepoSource, writeCloudSessionMeta };
+//# sourceMappingURL=chunk-LN5RJ5ZT.mjs.map
+//# sourceMappingURL=chunk-LN5RJ5ZT.mjs.map