@threahq/remote-session 0.1.0

package/index.js

@@ -0,0 +1,3683 @@
+// src/session.ts
+import { createHash as createHash2 } from "node:crypto";
+import { homedir, hostname } from "node:os";
+import { join as join2 } from "node:path";
+import {
+  ArchiveGraceController,
+  BotKeyring,
+  E2eKeyring,
+  e2eKeyAccount,
+  mintE2eKeyRecord,
+  readLegacyBikFile,
+  resolveKeyStore,
+  FileKeyStore,
+  WS_BACKSTOP_POLL_MS,
+  BotRuntimeTransport,
+  mintStreamKeyWraps,
+  openSealedAck,
+  openSealedDecisionNote,
+  openSealedTurnContext,
+  parseSealedAckContext,
+  parseSealedTurnContext,
+  scrubSealedError,
+  sealDecision,
+  sealReply,
+  sealStep
+} from "@threahq/bot-runtime-client";
+
+// src/attachments.ts
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import {
+  attachmentLocalPath,
+  decryptAttachmentBytes,
+  encryptAttachmentBytes
+} from "@threahq/bot-runtime-client";
+var ATTACH_DIRECTIVE_RE = /^THREA_ATTACH:\s*(.+?)\s*$/;
+var ATTACHMENT_DIR = ".threa-attachments";
+function extractAttachmentDirectives(markdown) {
+  const paths = [];
+  const lines = markdown.split(`
+`).filter((line) => {
+    const match = line.match(ATTACH_DIRECTIVE_RE);
+    if (!match)
+      return true;
+    paths.push(match[1]);
+    return false;
+  });
+  return { markdown: lines.join(`
+`).trim(), paths };
+}
+function guessMimeType(path) {
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".png"))
+    return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg"))
+    return "image/jpeg";
+  if (lower.endsWith(".gif"))
+    return "image/gif";
+  if (lower.endsWith(".webp"))
+    return "image/webp";
+  if (lower.endsWith(".svg"))
+    return "image/svg+xml";
+  if (lower.endsWith(".html"))
+    return "text/html";
+  if (lower.endsWith(".md"))
+    return "text/markdown";
+  if (lower.endsWith(".txt"))
+    return "text/plain";
+  if (lower.endsWith(".csv"))
+    return "text/csv";
+  if (lower.endsWith(".json"))
+    return "application/json";
+  if (lower.endsWith(".pdf"))
+    return "application/pdf";
+  return "application/octet-stream";
+}
+function selectInboundAttachments(messages, sourceMessageId, contextMessageIds) {
+  const inScope = new Set([sourceMessageId, ...contextMessageIds]);
+  const ordered = [...messages].sort((a, b) => Number(b.id === sourceMessageId) - Number(a.id === sourceMessageId));
+  const seen = new Set;
+  const selected = [];
+  for (const message of ordered) {
+    if (!inScope.has(message.id))
+      continue;
+    for (const attachment of message.attachments ?? []) {
+      if (seen.has(attachment.id))
+        continue;
+      seen.add(attachment.id);
+      selected.push({ attachment, messageId: message.id, isSource: message.id === sourceMessageId });
+    }
+  }
+  return selected;
+}
+function formatInboundAttachmentManifest(downloaded) {
+  if (downloaded.length === 0)
+    return "";
+  const lines = downloaded.map((entry) => {
+    const marker = entry.isSource ? " [attached to the message you just received]" : "";
+    const { filename, mimeType, sizeBytes } = entry.attachment;
+    return `- ${filename} (${mimeType}, ${sizeBytes} bytes) → ${entry.localPath}${marker}`;
+  });
+  return ["Attachments saved into this session's working directory — read them from these paths:", ...lines].join(`
+`);
+}
+function buildReplyAttachmentSection(uploaded, failed) {
+  const parts = [];
+  if (uploaded.length > 0) {
+    parts.push(["Attachments:", ...uploaded.map((a) => `- [${a.filename}](attachment:${a.id})`)].join(`
+`));
+  }
+  if (failed.length > 0) {
+    parts.push(["Attachment upload failed:", ...failed.map((f) => `- ${f}`)].join(`
+`));
+  }
+  return parts.join(`
+
+`);
+}
+var DOWNLOAD_TIMEOUT_MS = 60000;
+function throwIfAborted(signal) {
+  if (!signal?.aborted)
+    return;
+  throw signal.reason instanceof Error ? signal.reason : new Error("attachment hydration aborted");
+}
+async function fetchAttachmentBytes(url, timeoutMs = DOWNLOAD_TIMEOUT_MS, signal) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const response = await fetch(url, { signal: signal ? AbortSignal.any([timeout, signal]) : timeout });
+  if (!response.ok)
+    throw new Error(`download failed with ${response.status}`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  throwIfAborted(signal);
+  return bytes;
+}
+async function downloadInboundAttachments(client, params) {
+  throwIfAborted(params.signal);
+  const messages = await client.listStreamMessages(params.streamId, { limit: params.scanLimit });
+  throwIfAborted(params.signal);
+  const selected = selectInboundAttachments(messages, params.sourceMessageId, params.contextMessageIds);
+  if (selected.length === 0)
+    return [];
+  const dir = join(params.cwd, ATTACHMENT_DIR, params.invocationId);
+  const downloaded = [];
+  for (const item of selected) {
+    try {
+      throwIfAborted(params.signal);
+      const url = await client.getAttachmentDownloadUrl(item.attachment.id);
+      const bytes = await fetchAttachmentBytes(url, DOWNLOAD_TIMEOUT_MS, params.signal);
+      const localPath = attachmentLocalPath(dir, item.attachment.id, item.attachment.filename);
+      mkdirSync(dirname(localPath), { recursive: true });
+      writeFileSync(localPath, bytes);
+      throwIfAborted(params.signal);
+      downloaded.push({ ...item, localPath });
+    } catch (error) {
+      if (params.strict || params.signal?.aborted)
+        throw error;
+      params.log(`attachment ${item.attachment.id} download failed: ${String(error)}`);
+    }
+  }
+  return downloaded;
+}
+async function uploadFile(client, path, cwd) {
+  const absolute = resolve(cwd, path);
+  const stats = statSync(absolute);
+  if (!stats.isFile())
+    throw new Error(`${path} is not a file`);
+  const bytes = readFileSync(absolute);
+  const form = new FormData;
+  form.append("file", new Blob([bytes], { type: guessMimeType(absolute) }), basename(absolute));
+  return client.uploadAttachment(form);
+}
+async function uploadReplyAttachments(client, markdown, cwd) {
+  const { markdown: stripped, paths } = extractAttachmentDirectives(markdown);
+  const uploaded = [];
+  const failed = [];
+  for (const path of paths) {
+    try {
+      uploaded.push(await uploadFile(client, path, cwd));
+    } catch (error) {
+      failed.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const section = buildReplyAttachmentSection(uploaded, failed);
+  const finalMarkdown = [stripped, section].filter(Boolean).join(`
+
+`);
+  return { markdown: finalMarkdown, uploaded, failed };
+}
+var SEALED_UPLOAD_FILENAME = "encrypted";
+var SEALED_UPLOAD_MIME = "application/octet-stream";
+var MAX_SEALED_ATTACHMENTS_PER_MESSAGE = 16;
+async function uploadSealedFile(client, path, cwd) {
+  const absolute = resolve(cwd, path);
+  const stats = statSync(absolute);
+  if (!stats.isFile())
+    throw new Error(`${path} is not a file`);
+  const bytes = readFileSync(absolute);
+  const encrypted = await encryptAttachmentBytes(bytes);
+  const form = new FormData;
+  form.append("e2e", "true");
+  form.append("file", new Blob([encrypted.ciphertext], { type: SEALED_UPLOAD_MIME }), SEALED_UPLOAD_FILENAME);
+  const summary = await client.uploadAttachment(form);
+  return {
+    attachmentId: summary.id,
+    key: encrypted.key,
+    iv: encrypted.iv,
+    filename: basename(absolute),
+    mimeType: guessMimeType(absolute),
+    sizeBytes: bytes.length
+  };
+}
+async function uploadSealedReplyAttachments(client, markdown, cwd) {
+  const { markdown: stripped, paths } = extractAttachmentDirectives(markdown);
+  const refs = [];
+  const failed = [];
+  for (const path of paths.slice(MAX_SEALED_ATTACHMENTS_PER_MESSAGE)) {
+    failed.push(`${path}: over the ${MAX_SEALED_ATTACHMENTS_PER_MESSAGE}-attachment limit for one message`);
+  }
+  for (const path of paths.slice(0, MAX_SEALED_ATTACHMENTS_PER_MESSAGE)) {
+    try {
+      refs.push(await uploadSealedFile(client, path, cwd));
+    } catch (error) {
+      failed.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const failureNote = failed.length > 0 ? ["Attachment upload failed:", ...failed.map((f) => `- ${f}`)].join(`
+`) : "";
+  return {
+    markdown: [stripped, failureNote].filter(Boolean).join(`
+
+`),
+    refs,
+    attachmentIds: refs.map((ref) => ref.attachmentId)
+  };
+}
+function selectSealedInboundRefs(promptRefs, historyRefs) {
+  const seen = new Set;
+  const selected = [];
+  for (const { refs, isSource } of [
+    { refs: promptRefs, isSource: true },
+    { refs: historyRefs, isSource: false }
+  ]) {
+    for (const ref of refs) {
+      if (seen.has(ref.attachmentId))
+        continue;
+      seen.add(ref.attachmentId);
+      selected.push({ ref, isSource });
+    }
+  }
+  return selected;
+}
+async function downloadSealedInboundAttachments(client, params) {
+  throwIfAborted(params.signal);
+  if (params.refs.length === 0)
+    return [];
+  const dir = join(params.cwd, ATTACHMENT_DIR, params.invocationId);
+  const downloaded = [];
+  for (const { ref, isSource } of params.refs) {
+    try {
+      throwIfAborted(params.signal);
+      const url = await client.getAttachmentDownloadUrl(ref.attachmentId);
+      const ciphertext = await fetchAttachmentBytes(url, DOWNLOAD_TIMEOUT_MS, params.signal);
+      const plaintext = await decryptAttachmentBytes({ ciphertext, key: ref.key, iv: ref.iv });
+      throwIfAborted(params.signal);
+      const localPath = attachmentLocalPath(dir, ref.attachmentId, ref.filename);
+      mkdirSync(dirname(localPath), { recursive: true });
+      writeFileSync(localPath, plaintext);
+      downloaded.push({
+        attachment: { id: ref.attachmentId, filename: ref.filename, mimeType: ref.mimeType, sizeBytes: ref.sizeBytes },
+        messageId: "",
+        isSource,
+        localPath
+      });
+    } catch (error) {
+      if (params.strict || params.signal?.aborted)
+        throw error;
+      params.log(`sealed attachment ${ref.attachmentId} download failed: ${String(error)}`);
+    }
+  }
+  return downloaded;
+}
+
+// src/identity.ts
+import { createHash } from "node:crypto";
+import {
+  E2E_KEY_SCOPES,
+  E2E_KEY_STORE_KINDS
+} from "@threahq/bot-runtime-client";
+var TRACE_MODES = ["headline", "commands"];
+var TRACE_MODE_SET = new Set(TRACE_MODES);
+var UNSAFE_ID_CHARS = /[^A-Za-z0-9_-]+/g;
+function sanitizeId(raw) {
+  return raw.replace(UNSAFE_ID_CHARS, "-").replace(/^-+|-+$/g, "");
+}
+function deriveStableId(prefix, seed) {
+  const hash = createHash("sha256").update(seed).digest("hex").slice(0, 16);
+  return `${prefix}-${hash}`.slice(0, 64);
+}
+function defaultDisplayName(cwd, prefix, override) {
+  const effective = override?.trim() ? override.trim() : prefix;
+  const dir = cwd.split("/").filter(Boolean).pop() ?? "session";
+  const name = `${effective} - ${dir}`;
+  return name.length > 100 ? name.slice(0, 100) : name;
+}
+function parseConfigFile(text) {
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("config file must be a JSON object");
+  }
+  return parsed;
+}
+function str(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function parseColdStartIfArchived(value) {
+  return str(value)?.toLowerCase() === "wait" ? "wait" : "replace";
+}
+function parseColdStartIfMissing(value) {
+  return str(value)?.toLowerCase() === "error" ? "error" : "create";
+}
+function parseBool(value, fallback) {
+  if (typeof value === "boolean")
+    return value;
+  const s = str(value)?.toLowerCase();
+  if (s === undefined)
+    return fallback;
+  if (["0", "false", "no", "off"].includes(s))
+    return false;
+  if (["1", "true", "yes", "on"].includes(s))
+    return true;
+  return fallback;
+}
+function parseNum(value, fallback, min) {
+  const n = typeof value === "number" ? value : Number(str(value));
+  return Number.isFinite(n) ? Math.max(min, Math.floor(n)) : fallback;
+}
+function parseTraceMode(value) {
+  const mode = str(value)?.toLowerCase();
+  return mode && TRACE_MODE_SET.has(mode) ? mode : undefined;
+}
+var KEY_SCOPE_SET = new Set(E2E_KEY_SCOPES);
+var KEY_STORE_SET = new Set(E2E_KEY_STORE_KINDS);
+function loadConfig(input, identity) {
+  const { env, cwd, hostname, file = {} } = input;
+  const baseUrl = str(env.THREA_BASE_URL) ?? str(file.baseUrl) ?? "https://app.threa.io";
+  const workspaceId = str(env.THREA_WORKSPACE_ID) ?? str(file.workspaceId);
+  const apiKey = str(env.THREA_API_KEY) ?? str(file.apiKey);
+  const missing = [!workspaceId && "THREA_WORKSPACE_ID", !apiKey && "THREA_API_KEY"].filter(Boolean);
+  if (missing.length > 0) {
+    const hint = identity.configPathHint ? ` or ${identity.configPathHint}` : "";
+    return { error: `Missing required config: ${missing.join(", ")}. Set env vars${hint}.` };
+  }
+  const displayName = defaultDisplayName(cwd, identity.displayNamePrefix, str(env.THREA_DISPLAY_NAME) ?? str(file.displayName));
+  const defaultLabel = str(env.THREA_DEFAULT_LABEL) ?? str(file.defaultLabel);
+  const configuredTraceMode = str(env.THREA_TRACE_MODE) ?? file.traceMode;
+  const traceMode = configuredTraceMode === undefined ? "headline" : parseTraceMode(configuredTraceMode);
+  if (!traceMode) {
+    return { error: "Invalid traceMode: expected headline or commands." };
+  }
+  const seed = `${hostname}:${cwd}`;
+  const instanceId = sanitizeId(str(env.THREA_INSTANCE_ID) ?? str(file.instanceId) ?? deriveStableId(identity.idPrefix, seed)).slice(0, 64);
+  const runtimeSessionId = sanitizeId(str(env.THREA_RUNTIME_SESSION_ID) ?? str(file.runtimeSessionId) ?? deriveStableId(identity.sessionIdPrefix, seed)).slice(0, 64);
+  if (!instanceId || !runtimeSessionId) {
+    return { error: "Could not derive a valid instanceId/runtimeSessionId (empty after sanitization)." };
+  }
+  const configuredKeyScope = str(env.THREA_E2E_KEY_SCOPE) ?? str(file.keyScope);
+  if (configuredKeyScope !== undefined && !KEY_SCOPE_SET.has(configuredKeyScope.toLowerCase())) {
+    return { error: `Invalid keyScope: expected one of ${E2E_KEY_SCOPES.join(", ")}.` };
+  }
+  const keyScope = configuredKeyScope?.toLowerCase() ?? "host";
+  const configuredKeyStore = str(env.THREA_E2E_KEY_STORE) ?? str(file.keyStore);
+  if (configuredKeyStore !== undefined && !KEY_STORE_SET.has(configuredKeyStore.toLowerCase())) {
+    return { error: `Invalid keyStore: expected one of ${E2E_KEY_STORE_KINDS.join(", ")}.` };
+  }
+  const keyStore = configuredKeyStore?.toLowerCase();
+  return {
+    config: {
+      baseUrl: baseUrl.replace(/\/$/, ""),
+      workspaceId,
+      apiKey,
+      displayName,
+      defaultLabel,
+      coldStartIfArchived: parseColdStartIfArchived(str(env.THREA_COLD_START_IF_ARCHIVED) ?? file.coldStartIfArchived),
+      coldStartIfMissing: parseColdStartIfMissing(str(env.THREA_COLD_START_IF_MISSING) ?? file.coldStartIfMissing),
+      expectedRootStreamId: str(env.THREA_EXPECTED_ROOT_STREAM_ID) ?? str(file.expectedRootStreamId),
+      instanceId,
+      runtimeSessionId,
+      permissionRelay: parseBool(env.THREA_PERMISSION_RELAY ?? file.permissionRelay, true),
+      pollMs: parseNum(env.THREA_POLL_MS ?? file.pollMs, 3000, 1000),
+      idleTimeoutMs: parseNum(env.THREA_IDLE_TIMEOUT_MS ?? file.idleTimeoutMs, 3600000, 60000),
+      bikPath: str(env.THREA_BIK_PATH) ?? str(file.bikPath),
+      keyScope,
+      keyStore,
+      keyDir: str(env.THREA_E2E_KEY_DIR) ?? str(file.keyDir),
+      e2e: parseBool(env.THREA_E2E ?? file.e2e, false),
+      sealedFullTrace: parseBool(env.THREA_SEALED_FULL_TRACE ?? file.sealedFullTrace, true),
+      traceMode,
+      delegations: parseBool(env.THREA_DELEGATIONS ?? file.delegations, false)
+    }
+  };
+}
+
+// src/client.ts
+import {
+  THREA_CALLBACK_TOKEN_HEADER
+} from "@threahq/bot-runtime-client";
+var FETCH_TIMEOUT_MS = 30000;
+
+class ThreaApiError extends Error {
+  status;
+  code;
+  retryAfterMs;
+  constructor(message, status, code, retryAfterMs) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "ThreaApiError";
+  }
+}
+function retryDelayMs(headers) {
+  const retryAfter = headers.get("Retry-After")?.trim();
+  if (retryAfter) {
+    const delay = /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1000 : Date.parse(retryAfter) - Date.now();
+    if (Number.isFinite(delay))
+      return Math.max(0, delay);
+  }
+  const reset = headers.get("RateLimit-Reset")?.trim();
+  if (reset && /^\d+$/.test(reset)) {
+    const delay = Number(reset) * 1000;
+    if (Number.isFinite(delay))
+      return delay;
+  }
+  return;
+}
+
+class ThreaClient {
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  get base() {
+    return this.opts.baseUrl.replace(/\/$/, "");
+  }
+  async request(path, init) {
+    const controller = new AbortController;
+    const abortFromCaller = () => controller.abort(init?.signal?.reason);
+    if (init?.signal?.aborted)
+      abortFromCaller();
+    else
+      init?.signal?.addEventListener("abort", abortFromCaller, { once: true });
+    const timeout = setTimeout(() => controller.abort(), this.opts.fetchTimeoutMs ?? FETCH_TIMEOUT_MS);
+    try {
+      return await this.requestWithin(path, init, controller.signal);
+    } finally {
+      clearTimeout(timeout);
+      init?.signal?.removeEventListener("abort", abortFromCaller);
+    }
+  }
+  async requestWithin(path, init, signal) {
+    const isFormData = typeof FormData !== "undefined" && init?.body instanceof FormData;
+    const response = await fetch(`${this.base}${path}`, {
+      ...init,
+      signal,
+      headers: {
+        Authorization: `Bearer ${this.opts.apiKey}`,
+        ...isFormData ? {} : { "Content-Type": "application/json" },
+        ...init?.headers
+      }
+    });
+    if (!response.ok) {
+      let code;
+      let serverMessage;
+      if (response.headers.get("content-type")?.includes("application/json")) {
+        try {
+          const body = (await response.text()).slice(0, 2000);
+          const parsed = JSON.parse(body);
+          if (typeof parsed.code === "string")
+            code = parsed.code;
+          if (typeof parsed.error === "string")
+            serverMessage = parsed.error;
+        } catch {
+          code = undefined;
+        }
+      }
+      const detail = [code, serverMessage].filter(Boolean).join(" — ");
+      throw new ThreaApiError(`Threa API ${response.status}${detail ? ` (${detail})` : `: ${response.statusText}`}`, response.status, code, retryDelayMs(response.headers));
+    }
+    if (response.status === 204)
+      return;
+    return await response.json();
+  }
+  workspacePath(suffix) {
+    return `/api/v1/workspaces/${this.opts.workspaceId}${suffix}`;
+  }
+  async getMe() {
+    const body = await this.request(this.workspacePath("/me"));
+    return body.data;
+  }
+  async createSession(body) {
+    const result = await this.request(this.workspacePath("/bot-runtime/sessions"), {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    return result.data;
+  }
+  async claim(body) {
+    const result = await this.request(this.workspacePath("/bot-invocations/claim"), { method: "POST", body: JSON.stringify(body) });
+    return result.data;
+  }
+  async complete(invocationId, body, signal) {
+    await this.request(this.workspacePath(`/bot-invocations/${invocationId}/complete`), {
+      method: "POST",
+      body: JSON.stringify(body),
+      signal
+    });
+  }
+  async fail(invocationId, body) {
+    await this.request(this.workspacePath(`/bot-invocations/${invocationId}/fail`), {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async sendMessage(streamId, body) {
+    const result = await this.request(this.workspacePath(`/streams/${streamId}/messages`), {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    const id = result?.data?.id;
+    if (typeof id !== "string" || !id)
+      throw new Error(`Threa API returned no message id for stream ${streamId}`);
+    return { id };
+  }
+  async sendInvocationMessage(invocationId, body) {
+    await this.request(this.workspacePath(`/bot-invocations/${invocationId}/messages`), {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async sendSealedMessage(invocationId, callbackToken, body) {
+    await this.request(this.workspacePath(`/bot-invocations/${invocationId}/sealed-messages`), {
+      method: "POST",
+      headers: { [THREA_CALLBACK_TOKEN_HEADER]: callbackToken },
+      body: JSON.stringify(body)
+    });
+  }
+  async getOwnerE2eKey() {
+    const body = await this.request(this.workspacePath("/bot-runtime/owner-e2e-key"));
+    return body.data;
+  }
+  async provisionStreamKeyWraps(streamId, body) {
+    await this.request(this.workspacePath(`/streams/${streamId}/e2e/key-wraps`), {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async completeSealed(invocationId, callbackToken, body, signal) {
+    await this.request(this.workspacePath(`/bot-invocations/${invocationId}/sealed-complete`), {
+      method: "POST",
+      headers: { [THREA_CALLBACK_TOKEN_HEADER]: callbackToken },
+      body: JSON.stringify(body),
+      signal
+    });
+  }
+  async requestDecision(streamId, body) {
+    const result = await this.request(this.workspacePath(`/streams/${streamId}/decisions`), {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    return result.data;
+  }
+  async getDecision(decisionId) {
+    const result = await this.request(this.workspacePath(`/decisions/${decisionId}`));
+    return result.data;
+  }
+  async cancelDecision(decisionId) {
+    const result = await this.request(this.workspacePath(`/decisions/${decisionId}/cancel`), { method: "POST" });
+    return result.data;
+  }
+  async listStreamMessages(streamId, query = {}) {
+    const suffix = query.limit ? `?limit=${query.limit}` : "";
+    const body = await this.request(this.workspacePath(`/streams/${streamId}/messages${suffix}`));
+    return body.data;
+  }
+  async getStreamArchivedAt(streamId) {
+    const body = await this.request(this.workspacePath(`/streams/${streamId}`));
+    return body.data?.archivedAt ?? null;
+  }
+  async getAttachmentDownloadUrl(attachmentId) {
+    const body = await this.request(this.workspacePath(`/attachments/${attachmentId}/url`));
+    return body.data.url;
+  }
+  async uploadAttachment(form) {
+    const body = await this.request(this.workspacePath("/attachments"), {
+      method: "POST",
+      body: form
+    });
+    return body.data;
+  }
+}
+
+// src/turn-route.ts
+class RouteRevokedError extends Error {
+}
+
+class TurnRoute {
+  invocation;
+  order;
+  generation;
+  sentCount = 0;
+  replyText;
+  prepared;
+  closing;
+  deadline;
+  pending = new Map;
+  contributors;
+  execution = new AbortController;
+  tail = Promise.resolve();
+  reservedSeq = 0;
+  deadlineGeneration = 0;
+  stateValue = "open";
+  revokedFlag = false;
+  terminalFlag = false;
+  idleTimeoutMs;
+  onIdleDeadline;
+  constructor(options) {
+    this.invocation = options.invocation;
+    this.contributors = [...options.contributors ?? []];
+    this.order = options.order;
+    this.generation = options.generation;
+    this.idleTimeoutMs = options.idleTimeoutMs;
+    this.onIdleDeadline = options.onIdleDeadline;
+  }
+  get state() {
+    return this.stateValue;
+  }
+  get revoked() {
+    return this.revokedFlag;
+  }
+  get terminal() {
+    return this.terminalFlag;
+  }
+  isFenced(lifecycle) {
+    return this.revokedFlag || this.generation !== lifecycle;
+  }
+  enqueue(task) {
+    const run = this.tail.then(task, task);
+    this.tail = run.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return run;
+  }
+  snapshotIntent(text, retryKey) {
+    let retry;
+    for (const pending of this.pending.values()) {
+      if (pending.text === text && pending.retryKey === retryKey && (!retry || pending.seq < retry.seq)) {
+        retry = pending;
+      }
+    }
+    return {
+      text,
+      ...retryKey === undefined ? {} : { retryKey },
+      ...retry ? { retry } : {}
+    };
+  }
+  claimSeq(retry) {
+    return retry?.seq ?? (this.reservedSeq += 1);
+  }
+  rememberFailedPost(seq, prepared, lifecycle) {
+    if (!this.isFenced(lifecycle))
+      this.pending.set(seq, prepared);
+  }
+  recordLandedPost(seq, prepared) {
+    if (this.pending.get(seq) === prepared)
+      this.pending.delete(seq);
+    this.sentCount += 1;
+  }
+  discardPrepared() {
+    this.pending.clear();
+    this.prepared = undefined;
+  }
+  revoke() {
+    this.revokedFlag = true;
+    this.pending.clear();
+    this.prepared = undefined;
+    this.clearDeadline();
+  }
+  markTerminal() {
+    this.stateValue = "closed";
+    this.terminalFlag = true;
+    this.revokedFlag = true;
+    this.clearDeadline();
+    this.deadlineGeneration += 1;
+    this.closing = undefined;
+    this.pending.clear();
+    this.prepared = undefined;
+    this.invocation.claimToken = "";
+    this.invocation.sealing = undefined;
+    this.invocation.sealedAttachments = undefined;
+    this.invocation.sealedAck = undefined;
+  }
+  beginClosing() {
+    this.stateValue = "closing";
+    this.clearDeadline();
+  }
+  markClosed() {
+    this.stateValue = "closed";
+  }
+  settleClosed(replyText) {
+    this.stateValue = "closed";
+    this.prepared = undefined;
+    if (replyText === undefined)
+      delete this.replyText;
+    else
+      this.replyText = replyText;
+  }
+  reopen(prepared) {
+    this.stateValue = "open";
+    this.prepared = prepared;
+  }
+  trackClosing(task) {
+    this.closing = task;
+    return task.finally(() => {
+      if (this.closing === task)
+        this.closing = undefined;
+    });
+  }
+  armIdleTimeout() {
+    const generation = this.deadlineGeneration += 1;
+    this.deadline = setTimeout(() => this.onIdleDeadline(this, generation), this.idleTimeoutMs);
+  }
+  touchIdleTimeout() {
+    if (this.stateValue !== "open" || this.revokedFlag)
+      return;
+    this.clearDeadline();
+    this.armIdleTimeout();
+  }
+  isCurrentDeadline(deadlineGeneration) {
+    return this.deadlineGeneration === deadlineGeneration;
+  }
+  clearDeadline() {
+    clearTimeout(this.deadline);
+    this.deadline = undefined;
+  }
+}
+
+// src/session.ts
+var SUPPORTED_CAPABILITIES = ["active-scratchpad", "mentionable"];
+var SESSION_CONTROL_CAPABILITY = "session-control";
+var STEER_DRAIN_LIMIT = 10;
+var STEER_SETTLE_MS = 250;
+var CLAIM_TTL_SECONDS = 120;
+var NO_SOCKET_POLL_CAP_MS = 2 * 60 * 1000;
+var CLAIM_RETRY_CAP_MS = 2 * 60 * 1000;
+var RECONNECT_HANDOFF_FALLBACK_MS = 30000;
+var MAX_CLAIMS_PER_DRAIN = 20;
+var MAX_EXCLUDED_RESPONSE_STREAMS = 32;
+var MAX_CONCURRENT_TURNS = MAX_EXCLUDED_RESPONSE_STREAMS - MAX_CLAIMS_PER_DRAIN;
+var MAX_STEP_FRAMES_PER_CALL = 50;
+var MAX_CONTEXT_MESSAGES = 12;
+var MAX_MESSAGE_CHARS = 2000;
+var ATTACHMENT_SCAN_LIMIT = 30;
+var COMPLETED_TURN_MEMORY = 64;
+var RETRYABLE_POST_STATUSES = new Set([408, 425, 429]);
+function parseSessionControlCommand(invocation) {
+  const meta = invocation.metadata?.command;
+  if (meta && typeof meta === "object") {
+    const value = meta;
+    if (value.executionKind === "bot-runtime" && typeof value.name === "string") {
+      return { name: value.name.toLowerCase(), args: typeof value.args === "string" ? value.args.trim() : "" };
+    }
+  }
+  if (invocation.trigger !== SESSION_CONTROL_CAPABILITY)
+    return null;
+  const match = invocation.promptMarkdown.trim().match(/^\/([\w-]+)(?:\s+([\s\S]*))?$/);
+  if (!match)
+    return null;
+  return { name: match[1].toLowerCase(), args: (match[2] ?? "").trim() };
+}
+function isSessionControlInvocation(invocation) {
+  return invocation.trigger === SESSION_CONTROL_CAPABILITY && parseSessionControlCommand(invocation) !== null;
+}
+function formatInvocationContent(invocation) {
+  const prompt = invocation.promptMarkdown.trim() || "(empty message)";
+  const history = (invocation.context?.messages ?? []).filter((message) => message.messageId !== invocation.sourceMessageId).slice(-MAX_CONTEXT_MESSAGES).map((message) => {
+    const author = message.authorDisplayName?.trim() || message.role;
+    const content = message.contentMarkdown.trim().slice(0, MAX_MESSAGE_CHARS);
+    return `- ${author}: ${content}`;
+  });
+  if (history.length === 0)
+    return prompt;
+  return [prompt, "", "Earlier in this scratchpad (oldest first, for context):", ...history].join(`
+`);
+}
+function withInboundAttachments(content, manifest) {
+  return manifest ? `${content}
+
+${manifest}` : content;
+}
+function buildSteerContent(parts) {
+  if (parts.length === 1)
+    return parts[0];
+  return ["Handle all of the following together (most recent last):", "", parts.join(`
+
+---
+
+`)].join(`
+`);
+}
+function supportedCapabilitiesFor(sessionControlEnabled) {
+  return sessionControlEnabled ? [...SUPPORTED_CAPABILITIES, SESSION_CONTROL_CAPABILITY] : [...SUPPORTED_CAPABILITIES];
+}
+function effectiveRuntimeManifest(manifest, actuator) {
+  return {
+    output: { ...manifest?.output ?? {} },
+    input: { updates: actuator?.steer ? "live" : "restart" }
+  };
+}
+function claimCapabilitiesFor(busy, sessionControlEnabled) {
+  if (!busy)
+    return supportedCapabilitiesFor(sessionControlEnabled);
+  return sessionControlEnabled ? [SESSION_CONTROL_CAPABILITY] : [];
+}
+function runtimeCapabilitiesFor(runtimeSessionId, actuator) {
+  return {
+    runtimeSessionId,
+    supportsActiveScratchpad: true,
+    supportsPersistentSessions: true,
+    ...actuator ? {
+      supportsSessionControlCommands: true,
+      sessionControlCommands: [...actuator.commands],
+      ...actuator.modelSuggestions ? { modelSuggestions: [...actuator.modelSuggestions] } : {},
+      ...actuator.thinkingLevels ? { thinkingLevels: [...actuator.thinkingLevels] } : {},
+      ...actuator.spawnRuntimes ? { spawnRuntimes: [...actuator.spawnRuntimes] } : {},
+      ...actuator.spawnDefaultRuntime ? { spawnDefaultRuntime: actuator.spawnDefaultRuntime } : {}
+    } : {}
+  };
+}
+
+class StaleInputError extends Error {
+}
+
+class DecisionAbandonedError extends Error {
+  decisionId;
+  constructor(decisionId) {
+    super(`Decision ${decisionId} was abandoned: the remote session is shutting down.`);
+    this.decisionId = decisionId;
+    this.name = "DecisionAbandonedError";
+  }
+}
+function decisionAbortError(decisionId) {
+  const error = new Error(`Decision ${decisionId} was aborted by its caller.`);
+  error.name = "AbortError";
+  return error;
+}
+
+class RemoteSession {
+  config;
+  client;
+  delegate;
+  runtime;
+  transport;
+  log;
+  onPresence;
+  bik;
+  advertisedKeyIds = "";
+  hello;
+  botId;
+  link;
+  linkGeneration = 0;
+  claiming = false;
+  claimDrainTask;
+  claimRetryTimer;
+  claimFailures = 0;
+  reconnectHandoff = false;
+  onHandoffReset;
+  reconnectResetTimer;
+  reconnectFallbackTask;
+  stopped = false;
+  archive;
+  pollTimer;
+  emptyNoSocketPolls = 0;
+  inflight = new Map;
+  completed = new Map;
+  terminalReplies = new Map;
+  nextRouteOrder = 0;
+  lifecycle = 0;
+  presenceTail = Promise.resolve();
+  observedClaims = new Map;
+  cancelledInvocations = new WeakSet;
+  claimDrainRequested = false;
+  claimDrainScheduled = false;
+  activeTurnStream;
+  pendingDecisions = new Map;
+  decisionPollTimer;
+  maxConcurrentTurns;
+  constructor(options) {
+    const maxConcurrentTurns = options.runtime.maxConcurrentTurns ?? 1;
+    if (!Number.isInteger(maxConcurrentTurns) || maxConcurrentTurns < 1) {
+      throw new Error(`maxConcurrentTurns must be a positive integer, got ${maxConcurrentTurns}`);
+    }
+    if (maxConcurrentTurns > MAX_CONCURRENT_TURNS) {
+      throw new Error(`maxConcurrentTurns must be at most ${MAX_CONCURRENT_TURNS}, got ${maxConcurrentTurns}`);
+    }
+    this.maxConcurrentTurns = maxConcurrentTurns;
+    this.config = options.config;
+    this.client = options.client;
+    this.delegate = options.delegate;
+    this.runtime = options.runtime;
+    this.log = options.log ?? (() => {
+      return;
+    });
+    this.onPresence = options.onPresence;
+    this.archive = new ArchiveGraceController({
+      isArchived: async (rootStreamId) => Boolean(await this.client.getStreamArchivedAt(rootStreamId)),
+      reattach: () => this.relinkAfterRestore(),
+      onDetached: (rootStreamId) => this.detachForArchive(rootStreamId),
+      onReattached: async () => {
+        await this.syncPresence();
+        await this.claimDrain();
+      },
+      onWindDown: (rootStreamId) => this.windDownForArchive(rootStreamId),
+      log: this.log
+    }, options.archiveGraceMs === undefined ? {} : { graceMs: options.archiveGraceMs });
+    this.bik = new BotKeyring({ keyring: () => this.buildKeyring(), log: this.log });
+    this.hello = {
+      ...this.presenceBody("available"),
+      supportedCapabilities: supportedCapabilitiesFor(this.sessionControlEnabled)
+    };
+    this.transport = options.transport ?? new BotRuntimeTransport({
+      baseUrl: this.config.baseUrl,
+      workspaceId: this.config.workspaceId,
+      apiKey: this.config.apiKey,
+      hello: this.hello,
+      beforeHello: () => this.refreshHelloCapabilities(),
+      callbacks: {
+        onInvocationAvailable: () => void this.claimDrain(),
+        ...options.onDelegationAvailable ? { onDelegationAvailable: (payload) => options.onDelegationAvailable?.(payload) } : {},
+        onE2eGrant: (payload) => void this.keyGrantedStreams([payload.streamId]),
+        onE2eRevoke: (payload) => void this.keyRevokedStream(payload.streamId),
+        onBootstrap: (bootstrap) => {
+          if (bootstrap.botId)
+            this.botId = bootstrap.botId;
+          this.probeArchiveBackstop();
+          if (bootstrap.e2eGrantedStreamIds.length > 0)
+            this.keyGrantedStreams(bootstrap.e2eGrantedStreamIds);
+          if (bootstrap.availableInvocations.length > 0 || bootstrap.ownedClaims.length > 0)
+            this.claimDrain();
+          if (this.pendingDecisions.size > 0)
+            this.scheduleDecisionPoll(0);
+        },
+        onDisconnected: () => this.handleTransportDisconnected(),
+        onSessionArchived: (payload) => void this.handleSessionArchived(payload),
+        onSessionRestored: (payload) => void this.handleSessionRestored(payload),
+        onDecisionResolved: (payload) => this.handleDecisionPush(payload),
+        onDecisionCancelled: (payload) => this.handleDecisionPush(payload)
+      },
+      log: this.log
+    });
+  }
+  get sessionControlEnabled() {
+    return Boolean(this.delegate.sessionControl);
+  }
+  get parallel() {
+    return this.maxConcurrentTurns > 1;
+  }
+  inflightStreams() {
+    return new Set([...this.inflight.values()].map((route) => route.invocation.responseStreamId));
+  }
+  get atCapacity() {
+    return this.inflightStreams().size >= this.maxConcurrentTurns;
+  }
+  refreshHelloCapabilities() {
+    let status = "available";
+    if (this.stopped || this.archive.detached || !this.link)
+      status = "offline";
+    else if (this.reconnectHandoff || this.atCapacity)
+      status = "busy";
+    const body = this.presenceBody(status);
+    Object.assign(this.hello, body);
+    this.hello.supportedCapabilities = supportedCapabilitiesFor(this.sessionControlEnabled);
+    this.reportPresence(body);
+  }
+  get activeTurnStreamId() {
+    return this.activeTurnStream;
+  }
+  get rootStreamId() {
+    return this.link?.rootStreamId;
+  }
+  get statusSnapshot() {
+    const linkState = this.archive.detached ? "detached" : this.link ? "linked" : "unlinked";
+    return {
+      stopped: this.stopped,
+      linkGeneration: this.linkGeneration,
+      linkState,
+      rootStreamId: this.link?.rootStreamId ?? this.archive.pendingRootStreamId,
+      activeStreamId: this.link?.activeStreamId,
+      socketConnected: this.transport.socketConnected,
+      inflightCount: this.inflight.size,
+      activeTurnStreamId: this.activeTurnStream,
+      inflightStreamIds: [...this.inflightStreams()],
+      pendingDecisionCount: this.pendingDecisions.size
+    };
+  }
+  buildKeyring() {
+    const dir = this.config.keyDir ?? join2(homedir(), ".threa", "e2e-keys");
+    const account = e2eKeyAccount({
+      scope: this.config.keyScope,
+      hostname: hostname(),
+      instanceId: this.config.instanceId,
+      identitySeed: this.config.apiKey
+    });
+    const files = new FileKeyStore({ dir });
+    const legacyPath = this.config.bikPath ?? join2(homedir(), ".threa", `bik-${sanitizeId(this.runtime.kind)}.json`);
+    return new E2eKeyring({
+      store: resolveKeyStore({
+        requested: this.config.keyStore,
+        platform: process.platform,
+        dir,
+        hasExistingFileKey: account === null ? files.hasAny() : files.read(account) !== undefined
+      }),
+      account,
+      mint: mintE2eKeyRecord,
+      legacy: () => readLegacyBikFile(legacyPath),
+      log: this.log
+    });
+  }
+  async start() {
+    await this.bik.ensure();
+    this.advertisedKeyIds = this.bik.identities.map((identity) => identity.publicKeyId).join(",");
+    Object.assign(this.hello, this.bik.presenceFields());
+    await this.verifyPrincipal();
+    await this.ensureLink();
+    await this.transport.connect();
+    this.startPoll();
+    await this.claimDrain();
+  }
+  async ensureLink() {
+    if (this.link || this.stopped || this.archive.detached)
+      return;
+    try {
+      await this.createLink();
+    } catch (error) {
+      this.log(`could not link to Threa (will retry): ${this.summarize(error)}${this.linkErrorHint(error)}`);
+    }
+  }
+  async relinkAfterRestore() {
+    try {
+      return await this.createLink();
+    } catch (error) {
+      this.log(`reattach link failed: ${this.summarize(error)}${this.linkErrorHint(error)}`);
+      return false;
+    }
+  }
+  async createLink() {
+    const generation = this.archive.generation;
+    const link = await this.createSession();
+    if (this.stopped)
+      return false;
+    if (this.archive.generation !== generation) {
+      this.log("link response raced an archive state change — dropped; the next probe decides");
+      return false;
+    }
+    await this.delegate.onLinked?.(link);
+    if (this.stopped)
+      return false;
+    if (this.archive.generation !== generation) {
+      this.log("link response raced an archive state change — dropped; the next probe decides");
+      return false;
+    }
+    this.link = link;
+    this.linkGeneration += 1;
+    this.log(`linked to scratchpad ${this.config.baseUrl}${this.link.streamUrlPath}`);
+    if (!this.archive.detached)
+      await this.syncPresence();
+    return true;
+  }
+  linkErrorHint(error) {
+    if (!(error instanceof ThreaApiError))
+      return "";
+    if (error.status === 401 || error.status === 403) {
+      return " — check THREA_API_KEY (must be a bot key, threa_bk_…) and THREA_WORKSPACE_ID";
+    }
+    if (error.code === "SCRATCHPAD_ARCHIVED" && !this.archive.detached) {
+      return " — the server does not support ifArchived replace yet; unarchive the scratchpad in Threa to link";
+    }
+    return "";
+  }
+  async shutdown(options = {}) {
+    if (this.stopped)
+      return;
+    this.stopped = true;
+    if (this.pollTimer)
+      clearTimeout(this.pollTimer);
+    if (this.claimRetryTimer)
+      clearTimeout(this.claimRetryTimer);
+    this.claimRetryTimer = undefined;
+    this.archive.stop();
+    const withdrawals = this.abandonPendingDecisions();
+    this.resetReconnectHandoff();
+    await this.reconnectFallbackTask;
+    this.transport.disconnect();
+    const routes = this.revokeAllRoutes();
+    await this.waitForClaimDrain();
+    await Promise.all([this.enqueueOfflinePresence(() => this.stopped), withdrawals]);
+    if (options.hostGone && routes.length > 0) {
+      this.log(`host gone: leaving ${routes.length} in-flight claim(s) to lapse for the revived session`);
+      return;
+    }
+    await this.failUnansweredRoutes(routes);
+  }
+  revokeAllRoutes() {
+    this.lifecycle += 1;
+    const inflight = [...this.inflight.values()];
+    for (const route of inflight)
+      route.revoke();
+    for (const route of this.completed.values())
+      route.revoke();
+    for (const context of this.observedClaims.values())
+      this.fenceObservedClaim(context.invocation);
+    this.inflight.clear();
+    this.completed.clear();
+    this.terminalReplies.clear();
+    return inflight;
+  }
+  async failUnansweredRoutes(routes) {
+    await Promise.allSettled(routes.map((route) => Promise.resolve(route.closing).catch(() => {
+      return;
+    }).then(() => {
+      if (route.state === "closed")
+        return;
+      return Promise.allSettled([route.invocation, ...route.contributors].map((invocation) => this.client.fail(invocation.id, {
+        instanceId: this.config.instanceId,
+        claimToken: invocation.claimToken,
+        errorMessage: this.runtime.shutdownErrorMessage
+      })));
+    })));
+  }
+  async verifyPrincipal() {
+    try {
+      const me = await this.client.getMe();
+      if (me.kind !== "bot") {
+        this.log("WARNING: the configured API key is not a bot key (threa_bk_…). Bot-runtime endpoints will reject it.");
+      }
+    } catch (error) {
+      this.log(`could not verify principal (continuing): ${this.summarize(error)}`);
+    }
+  }
+  async createSession() {
+    const e2e = this.config.e2e ? await this.resolveE2eCreateBlock() : undefined;
+    const link = await this.client.createSession({
+      runtimeKind: this.runtime.kind,
+      instanceId: this.config.instanceId,
+      runtimeSessionId: this.config.runtimeSessionId,
+      displayName: this.config.displayName,
+      ...this.config.localCwd ? { localCwd: this.config.localCwd } : {},
+      ifArchived: this.archive.detached ? "wait" : this.config.coldStartIfArchived ?? "replace",
+      ifMissing: this.config.expectedRootStreamId ? "error" : this.config.coldStartIfMissing ?? "create",
+      ...this.config.defaultLabel && { labelName: this.config.defaultLabel },
+      ...e2e ? { e2e: { ownerKeyId: e2e.ownerKeyId } } : {}
+    });
+    if (this.config.expectedRootStreamId && link.rootStreamId !== this.config.expectedRootStreamId) {
+      throw new Error(`Session link root mismatch: expected ${this.config.expectedRootStreamId}, got ${link.rootStreamId}`);
+    }
+    if (this.config.e2e && link.e2eEnabled !== true) {
+      this.log(`WARNING: e2e is enabled but the resumed scratchpad ${link.rootStreamId} is plaintext ` + "(it predates the setting). Archive it to get a fresh encrypted scratchpad on the next start.");
+      return link;
+    }
+    if (e2e && link.e2eEnabled === true) {
+      await this.provisionE2eStreamKey(link, e2e);
+    }
+    return link;
+  }
+  async resolveE2eCreateBlock() {
+    let ownerKey;
+    try {
+      ownerKey = await this.client.getOwnerE2eKey();
+    } catch (error) {
+      if (error instanceof ThreaApiError && error.status === 404) {
+        throw new Error("e2e is enabled but the bot owner has not set up encryption in Threa yet — " + "set an encryption passphrase in the app, then this session will link encrypted.");
+      }
+      throw error;
+    }
+    return { ownerKeyId: ownerKey.keyId, ownerPublicKey: ownerKey.publicKey };
+  }
+  async provisionE2eStreamKey(link, e2e) {
+    const bik = await this.bik.identityForStream(link.rootStreamId);
+    if (!bik) {
+      throw new Error("e2e is enabled but this install could not create a bot identity key (see earlier log)");
+    }
+    await this.advertiseKeyring();
+    const { wraps } = await mintStreamKeyWraps({
+      streamId: link.rootStreamId,
+      keyGeneration: 0,
+      recipients: [
+        { recipientKind: "user", recipientKeyId: e2e.ownerKeyId, publicKeyBase64: e2e.ownerPublicKey },
+        { recipientKind: "bot", recipientKeyId: bik.publicKeyId, publicKeyBase64: bik.publicKeyBase64 }
+      ]
+    });
+    for (let attempt = 1;; attempt++) {
+      try {
+        await this.client.provisionStreamKeyWraps(link.rootStreamId, { keyGeneration: 0, wraps });
+        this.log(`provisioned encrypted scratchpad ${link.rootStreamId} (gen 0, owner + BIK wraps)`);
+        return;
+      } catch (error) {
+        if (error instanceof ThreaApiError && error.status === 409)
+          return;
+        if (attempt >= 3)
+          throw error;
+        await new Promise((resolve2) => setTimeout(resolve2, attempt * 1000));
+      }
+    }
+  }
+  claimDrain() {
+    if (this.stopped || this.claimRetryTimer || this.archive.detached || this.reconnectHandoff) {
+      return Promise.resolve(false);
+    }
+    if (this.claiming || this.claimDrainTask) {
+      this.claimDrainRequested = true;
+      return Promise.resolve(false);
+    }
+    this.claiming = true;
+    const task = this.runClaimDrain();
+    this.claimDrainTask = task;
+    const clear = () => {
+      if (this.claimDrainTask === task)
+        this.claimDrainTask = undefined;
+      this.scheduleRequestedClaimDrain();
+    };
+    task.then(clear, clear);
+    return task;
+  }
+  async runClaimDrain() {
+    let claimedAny = false;
+    const stoppedStreams = new Set;
+    try {
+      for (let i = 0;i < MAX_CLAIMS_PER_DRAIN; i++) {
+        if (this.reconnectHandoff || this.stopped || this.archive.detached)
+          break;
+        const busy = this.atCapacity;
+        if (busy && !this.sessionControlEnabled)
+          break;
+        const exclude = busy ? [] : [...new Set([...this.inflightStreams(), ...stoppedStreams])];
+        const invocation = await this.claimNext(busy, undefined, exclude);
+        if (!invocation)
+          break;
+        claimedAny = true;
+        this.markClaimProcessing(invocation);
+        if (this.isClaimCancelled(invocation))
+          continue;
+        if (isSessionControlInvocation(invocation)) {
+          const isStop = parseSessionControlCommand(invocation)?.name === "stop";
+          await this.handleSessionControl(invocation);
+          if (isStop) {
+            if (this.parallel) {
+              stoppedStreams.add(invocation.responseStreamId);
+              continue;
+            }
+            this.claimDrainRequested = false;
+            break;
+          }
+          continue;
+        }
+        if (this.routeForStream(invocation.responseStreamId)) {
+          this.log(`claimed ${invocation.id} for busy stream ${invocation.responseStreamId}: server ignored excludeResponseStreamIds`);
+          await this.failInvocation(invocation, "Threa server ignored excludeResponseStreamIds; resend the message");
+          continue;
+        }
+        const deferred = await this.startFoldedTurn(invocation);
+        for (const control of deferred) {
+          if (parseSessionControlCommand(control)?.name === "stop") {
+            await this.handleSessionControl(control);
+            if (this.parallel) {
+              stoppedStreams.add(control.responseStreamId);
+              continue;
+            }
+            this.claimDrainRequested = false;
+            return claimedAny;
+          }
+          await this.handleSessionControl(control);
+        }
+      }
+    } catch (error) {
+      this.log(`claim failed: ${this.summarize(error)}`);
+    } finally {
+      this.claiming = false;
+    }
+    return claimedAny;
+  }
+  async waitForClaimDrain() {
+    await this.claimDrainTask;
+  }
+  async claimAndHydrate(busy, responseStreamId, excludeResponseStreamIds = []) {
+    if (this.claimRetryTimer)
+      return null;
+    let invocation;
+    try {
+      invocation = await this.client.claim({
+        ...this.claimBody(busy, excludeResponseStreamIds),
+        ...responseStreamId ? { responseStreamId } : {}
+      });
+      this.claimFailures = 0;
+    } catch (error) {
+      this.scheduleClaimRetry(error);
+      throw error;
+    }
+    if (!invocation || invocation.sealedContext === undefined)
+      return invocation;
+    const fail = async (reason) => {
+      this.log(`sealed claim ${invocation.id} unusable: ${reason}`);
+      await this.client.fail(invocation.id, {
+        instanceId: this.config.instanceId,
+        claimToken: invocation.claimToken,
+        errorMessage: `Sealed turn failed: ${reason}`.slice(0, 200)
+      }).catch(() => {
+        return;
+      });
+      return null;
+    };
+    const sealed = parseSealedTurnContext(invocation.sealedContext);
+    if (!sealed)
+      return fail("malformed sealedContext");
+    const identities = await this.bik.ensureForStream(invocation.rootStreamId);
+    if (identities.length === 0)
+      return fail("no bot identity key");
+    try {
+      const opened = await openSealedTurnContext({ sealed, identities, streamId: invocation.rootStreamId });
+      const messages = opened.history.map((item) => ({
+        messageId: `sealed-${item.sequence}`,
+        role: item.role,
+        authorId: "",
+        authorType: item.role === "assistant" ? "bot" : "user",
+        contentMarkdown: item.contentMarkdown,
+        createdAt: ""
+      }));
+      const historyRefs = opened.history.flatMap((item) => item.attachmentRefs);
+      return {
+        ...invocation,
+        sealedContext: undefined,
+        promptMarkdown: opened.promptMarkdown,
+        sealing: opened.sealing,
+        ...opened.promptAttachmentRefs.length > 0 || historyRefs.length > 0 ? { sealedAttachments: { prompt: opened.promptAttachmentRefs, history: historyRefs } } : {},
+        ...messages.length > 0 ? { context: { kind: "inline", messages } } : {}
+      };
+    } catch (error) {
+      return fail(scrubSealedError(error));
+    }
+  }
+  scheduleClaimRetry(error) {
+    if (this.stopped || this.archive.detached || this.claimRetryTimer)
+      return;
+    if (error instanceof ThreaApiError && error.status < 500 && !RETRYABLE_POST_STATUSES.has(error.status))
+      return;
+    const backoff = Math.min(CLAIM_RETRY_CAP_MS, this.config.pollMs * 2 ** this.claimFailures);
+    this.claimFailures++;
+    const retryAfter = error instanceof ThreaApiError ? error.retryAfterMs ?? 0 : 0;
+    const delay = Math.min(2147483647, Math.max(backoff, retryAfter));
+    this.log(`claim failed; retrying in ${delay}ms: ${this.summarize(error)}`);
+    this.claimRetryTimer = setTimeout(() => {
+      this.claimRetryTimer = undefined;
+      this.claimDrainRequested = true;
+      this.scheduleRequestedClaimDrain();
+    }, delay);
+  }
+  async claimNext(busy, responseStreamId, excludeResponseStreamIds = []) {
+    const lifecycle = this.lifecycle;
+    const invocation = await this.claimAndHydrate(busy, responseStreamId, excludeResponseStreamIds);
+    if (!invocation || this.stopped || this.archive.detached || lifecycle !== this.lifecycle)
+      return null;
+    const identities = invocation.sealing ? this.bik.identities : [];
+    const handle = this.transport.observeClaim({
+      invocationId: invocation.id,
+      claimToken: invocation.claimToken,
+      sourceRevision: invocation.sourceRevision,
+      claimTtlSeconds: CLAIM_TTL_SECONDS,
+      instanceId: this.config.instanceId,
+      callbacks: {
+        onInputUpdated: (update, signal) => this.applyInputUpdate(invocation.id, update, signal),
+        onCancelled: () => this.terminalizeObservedClaim(invocation.id, "Folded input was cancelled while the turn was running."),
+        onClaimLost: () => this.terminalizeObservedClaim(invocation.id, "Folded claim ownership was lost while the turn was running.")
+      },
+      ...invocation.sealing && identities.length > 0 ? {
+        sealed: {
+          identities,
+          streamId: invocation.rootStreamId,
+          callbackToken: invocation.sealing.callbackToken
+        }
+      } : {}
+    });
+    this.observedClaims.set(invocation.id, {
+      invocation,
+      handle,
+      phase: "unstarted",
+      updateInProgress: false,
+      restartPending: false,
+      lifecycle: new AbortController
+    });
+    await handle.sync();
+    return this.isClaimCancelled(invocation) ? null : invocation;
+  }
+  markClaimProcessing(invocation) {
+    const context = this.observedClaims.get(invocation.id);
+    if (context && context.invocation === invocation && context.phase === "unstarted")
+      context.phase = "processing";
+  }
+  installInputUpdate(context, update) {
+    Object.assign(context.invocation, {
+      promptMarkdown: update.promptMarkdown,
+      sourceRevision: update.sourceRevision,
+      ...update.delivery === "sealed" ? {
+        sealing: update.sealing,
+        sealedAttachments: {
+          prompt: update.attachmentRefs,
+          history: context.invocation.sealedAttachments?.history ?? []
+        }
+      } : { sealing: undefined, sealedAttachments: undefined }
+    });
+    this.inflight.get(context.invocation.id)?.discardPrepared();
+  }
+  abortForInputRestart(context) {
+    context.restartPending = true;
+    context.updateInProgress = false;
+    this.cancelledInvocations.add(context.invocation);
+    this.abortRunningTurnForContext(context, "Folded input changed while the turn was running.");
+  }
+  abortRunningTurnForContext(context, ownerFailure) {
+    const ownerId = context.runningOwnerInvocationId;
+    const running = this.inflight.get(context.invocation.id) ?? (ownerId ? this.inflight.get(ownerId) : undefined);
+    if (!running)
+      return;
+    try {
+      this.delegate.sessionControl?.interrupt(running.invocation.responseStreamId);
+    } catch {}
+    running.execution.abort();
+    this.clearInflight(running.invocation.id);
+    if (this.activeTurnStream === running.invocation.responseStreamId)
+      this.activeTurnStream = undefined;
+    const affected = [running.invocation, ...running.contributors].filter((invocation) => invocation !== context.invocation);
+    for (const invocation of affected)
+      this.fenceObservedClaim(invocation);
+    Promise.all(affected.map((invocation) => this.failFencedInvocation(invocation, ownerFailure))).finally(() => {
+      this.syncPresence();
+    });
+  }
+  async applyInputUpdate(invocationId, update, signal) {
+    const context = this.observedClaims.get(invocationId);
+    if (signal.aborted || !context || context.phase === "terminal" || update.delivery === "sealed" && !update.sealing) {
+      return "restart-required";
+    }
+    if (context.phase === "unstarted") {
+      this.installInputUpdate(context, update);
+      return signal.aborted ? "restart-required" : "applied";
+    }
+    if (context.phase !== "running" || context.restartPending) {
+      this.abortForInputRestart(context);
+      return "restart-required";
+    }
+    const steer = this.delegate.sessionControl?.steer;
+    const route = this.inflight.get(invocationId);
+    if (!steer || !route || route.state !== "open" || route.revoked) {
+      this.abortForInputRestart(context);
+      return "restart-required";
+    }
+    context.updateInProgress = true;
+    this.installInputUpdate(context, update);
+    try {
+      if (signal.aborted)
+        throw signal.reason;
+      const content = await this.buildTurnContent(context.invocation, { strictAttachments: true, signal });
+      if (signal.aborted || this.isClaimCancelled(context.invocation))
+        throw signal.reason;
+      const interruptOnAbort = () => this.abortForInputRestart(context);
+      signal.addEventListener("abort", interruptOnAbort, { once: true });
+      let steered;
+      try {
+        if (signal.aborted)
+          throw signal.reason;
+        steered = await steer.call(this.delegate.sessionControl, content, context.invocation.responseStreamId);
+      } finally {
+        signal.removeEventListener("abort", interruptOnAbort);
+      }
+      if (signal.aborted || this.isClaimCancelled(context.invocation) || !steered) {
+        this.abortForInputRestart(context);
+        return "restart-required";
+      }
+      context.updateInProgress = false;
+      route.touchIdleTimeout();
+      return "applied";
+    } catch {
+      this.abortForInputRestart(context);
+      return "restart-required";
+    }
+  }
+  terminalizeObservedClaim(invocationId, ownerFailure) {
+    const context = this.observedClaims.get(invocationId);
+    if (!context || context.phase === "terminal")
+      return;
+    this.fenceObservedClaim(context.invocation);
+    this.abortRunningTurnForContext(context, ownerFailure);
+    if (!this.stopped && !this.archive.detached)
+      this.syncPresence();
+    this.claimDrainRequested = true;
+    this.scheduleRequestedClaimDrain();
+  }
+  scheduleRequestedClaimDrain() {
+    if (!this.claimDrainRequested || this.claimDrainScheduled || this.claiming || this.stopped || this.archive.detached)
+      return;
+    this.claimDrainScheduled = true;
+    setTimeout(() => {
+      this.claimDrainScheduled = false;
+      if (!this.claimDrainRequested || this.stopped || this.archive.detached)
+        return;
+      this.claimDrainRequested = false;
+      this.claimDrain().finally(() => this.scheduleRequestedClaimDrain());
+    }, 0);
+  }
+  isClaimCancelled(invocation) {
+    return this.cancelledInvocations.has(invocation);
+  }
+  isOutputCurrent(invocation, sourceRevision = invocation.sourceRevision) {
+    const context = this.observedClaims.get(invocation.id);
+    return !this.isClaimCancelled(invocation) && invocation.sourceRevision === sourceRevision && context?.phase !== "terminal" && context?.restartPending !== true && context?.updateInProgress !== true;
+  }
+  releaseObservation(invocationId) {
+    const context = this.observedClaims.get(invocationId);
+    if (!context)
+      return;
+    context.phase = "terminal";
+    context.handle.unregister();
+    this.observedClaims.delete(invocationId);
+  }
+  fenceObservedClaim(invocation) {
+    this.cancelledInvocations.add(invocation);
+    const context = this.observedClaims.get(invocation.id);
+    if (!context)
+      return;
+    context.lifecycle.abort();
+    context.handle.dispose();
+    this.observedClaims.delete(invocation.id);
+  }
+  async failFencedInvocation(invocation, errorMessage) {
+    const scrubbed = invocation.sealing ? "Sealed turn failed" : errorMessage.slice(0, 1000);
+    await this.client.fail(invocation.id, {
+      instanceId: this.config.instanceId,
+      claimToken: invocation.claimToken,
+      errorMessage: scrubbed
+    }).catch((error) => this.log(`invocation fail write failed: ${this.summarize(error)}`));
+  }
+  async startFoldedTurn(invocation) {
+    const primary = await this.buildTurnContent(invocation);
+    if (this.isClaimCancelled(invocation))
+      return [];
+    const folded = [];
+    const control = [];
+    try {
+      for (let i = 1;i < STEER_DRAIN_LIMIT; i++) {
+        const extra = await this.claimNext(false, invocation.responseStreamId).catch(() => null);
+        if (!extra)
+          break;
+        this.markClaimProcessing(extra);
+        if (this.isClaimCancelled(extra))
+          continue;
+        if (isSessionControlInvocation(extra)) {
+          control.push(extra);
+          break;
+        }
+        folded.push(extra);
+      }
+      const foldedParts = await this.foldedTurnParts(folded);
+      if (this.stopped || this.archive.detached) {
+        return control;
+      }
+      if (this.isClaimCancelled(invocation))
+        return control;
+      const liveFolded = foldedParts.map(({ invocation: item }) => item);
+      const content = buildSteerContent([primary, ...foldedParts.map((part) => part.content)]);
+      this.bindRunningOwner(invocation.id, liveFolded);
+      await this.deliverTurn(invocation, content, liveFolded);
+    } catch (error) {
+      const reason = `Could not start the turn: ${this.summarize(error)}`;
+      this.clearInflight(invocation.id);
+      await this.failInvocation(invocation, reason).catch(() => {
+        return;
+      });
+      await Promise.all(folded.map((item) => this.failInvocation(item, reason).catch(() => {
+        return;
+      })));
+    }
+    return control;
+  }
+  async foldedTurnParts(folded) {
+    const parts = [];
+    for (const item of folded) {
+      if (this.isClaimCancelled(item))
+        continue;
+      parts.push({ invocation: item, content: await this.buildTurnContent(item) });
+    }
+    return parts.filter((part) => !this.isClaimCancelled(part.invocation));
+  }
+  bindRunningOwner(ownerInvocationId, dependencies) {
+    const running = this.inflight.get(ownerInvocationId);
+    for (const dependency of dependencies) {
+      const context = this.observedClaims.get(dependency.id);
+      if (context && context.invocation === dependency) {
+        context.runningOwnerInvocationId = ownerInvocationId;
+        if (context.phase === "processing")
+          context.phase = "running";
+      }
+      if (running && !running.contributors.some((item) => item.id === dependency.id)) {
+        running.contributors.push(dependency);
+      }
+    }
+  }
+  unbindRunningOwner(ownerInvocationId, dependencies) {
+    const ids = new Set(dependencies.map((item) => item.id));
+    const running = this.inflight.get(ownerInvocationId);
+    if (running)
+      running.contributors = running.contributors.filter((item) => !ids.has(item.id));
+    for (const dependency of dependencies) {
+      const context = this.observedClaims.get(dependency.id);
+      if (context?.runningOwnerInvocationId === ownerInvocationId)
+        context.runningOwnerInvocationId = undefined;
+    }
+  }
+  async completeContributors(route) {
+    await Promise.all(route.contributors.map((invocation) => this.completeNoResponse(invocation)));
+  }
+  async failContributors(route, reason) {
+    await Promise.all(route.contributors.map((invocation) => this.failInvocation(invocation, reason)));
+  }
+  async deliverTurn(invocation, content, inputDependencies = []) {
+    if (this.isClaimCancelled(invocation))
+      throw new Error("invocation request is closed");
+    this.registerTurn(invocation, inputDependencies);
+    this.activeTurnStream = invocation.responseStreamId;
+    await this.syncPresence();
+    await this.recordForwardedStep(invocation).catch(() => {
+      return;
+    });
+    if (this.stopped || this.archive.detached || !this.inflight.has(invocation.id) || this.isClaimCancelled(invocation) || inputDependencies.some((item) => this.isClaimCancelled(item))) {
+      throw new Error("session went offline or its input changed before the turn could be delivered");
+    }
+    await this.delegate.deliverTurn({
+      invocationId: invocation.id,
+      streamId: invocation.responseStreamId,
+      rootStreamId: invocation.rootStreamId,
+      sourceMessageId: invocation.sourceMessageId,
+      content,
+      sealed: invocation.sealing !== undefined
+    });
+    const dependencyChanged = inputDependencies.some((item) => this.isClaimCancelled(item));
+    if (!this.inflight.has(invocation.id) || this.isClaimCancelled(invocation) || dependencyChanged) {
+      if (dependencyChanged) {
+        try {
+          this.delegate.sessionControl?.interrupt(invocation.responseStreamId);
+        } catch {}
+      }
+      throw new Error("invocation input changed while the runtime was accepting the turn");
+    }
+    const observed = this.observedClaims.get(invocation.id);
+    if (observed && observed.phase === "processing")
+      observed.phase = "running";
+  }
+  async recordForwardedStep(invocation) {
+    const forwardedNote = this.runtime.forwardedNote;
+    if (forwardedNote === undefined)
+      return;
+    const sourceRevision = invocation.sourceRevision;
+    if (invocation.sealing) {
+      const sealing = invocation.sealing;
+      const frame = await sealStep(sealing, "thinking", forwardedNote);
+      if (!this.isOutputCurrent(invocation, sourceRevision))
+        return;
+      await this.transport.recordSealedSteps(invocation.id, sealing.callbackToken, [frame]);
+      return;
+    }
+    if (!this.isOutputCurrent(invocation, sourceRevision))
+      return;
+    await this.transport.recordSteps(invocation.id, invocation.claimToken, [{ stepType: "thinking", content: forwardedNote }], this.runtime.busyStatusText);
+  }
+  async completeTurn(invocation, body) {
+    const signal = body.signal ?? this.observedClaims.get(invocation.id)?.lifecycle.signal;
+    if (signal?.aborted || this.isClaimCancelled(invocation))
+      throw new Error("invocation request is closed");
+    const sourceRevision = invocation.sourceRevision;
+    const assertCurrent = () => {
+      if (signal?.aborted || !this.isOutputCurrent(invocation, sourceRevision)) {
+        throw new Error("invocation request is closed");
+      }
+    };
+    if (invocation.sealing) {
+      const sealing = invocation.sealing;
+      const payload = body.markdown ? { sourceRevision, reply: await sealReply(sealing, body.markdown) } : { noResponse: true, sourceRevision };
+      assertCurrent();
+      await this.client.completeSealed(invocation.id, sealing.callbackToken, payload, signal);
+      assertCurrent();
+      this.releaseObservation(invocation.id);
+      return;
+    }
+    assertCurrent();
+    await this.client.complete(invocation.id, {
+      instanceId: this.config.instanceId,
+      claimToken: invocation.claimToken,
+      sourceRevision,
+      ...body.markdown ? { finalMessageMarkdown: body.markdown } : { noResponse: true },
+      ...body.metadata ? { metadata: body.metadata } : {}
+    }, signal);
+    assertCurrent();
+    this.releaseObservation(invocation.id);
+  }
+  async handleSessionControl(invocation) {
+    if (this.isClaimCancelled(invocation))
+      return;
+    const command = parseSessionControlCommand(invocation);
+    if (!command) {
+      await this.failInvocation(invocation, "Missing session-control command metadata");
+      return;
+    }
+    const actuator = this.delegate.sessionControl;
+    if (!actuator) {
+      await this.failInvocation(invocation, "Session control is not available for this runtime");
+      return;
+    }
+    try {
+      if (this.isClaimCancelled(invocation))
+        return;
+      switch (command.name) {
+        case "stop":
+          return await this.runStop(invocation, actuator);
+        case "steer":
+          return await this.runSteer(invocation, actuator, command.args);
+        default: {
+          if (!actuator.commands.includes(command.name)) {
+            await this.failInvocation(invocation, `Unsupported session-control command: ${command.name}`);
+            return;
+          }
+          const outcome = await actuator.runCommand(command.name, command.args, {
+            rootStreamId: invocation.rootStreamId,
+            sourceMessageId: invocation.sourceMessageId
+          });
+          if (this.isClaimCancelled(invocation))
+            return;
+          if (!outcome.ok) {
+            await this.failInvocation(invocation, outcome.message ?? "Command rejected.");
+            return;
+          }
+          const ackOutcome = () => {
+            if (outcome.message !== undefined)
+              return this.completeReply(invocation, outcome.message);
+            if (outcome.summary !== undefined)
+              return this.completeAck(invocation, outcome.summary);
+            return this.completeSilentAck(invocation);
+          };
+          if (outcome.handoff) {
+            const parks = !outcome.handoffKeepsSessionRunning;
+            if (parks) {
+              this.reconnectHandoff = true;
+              this.onHandoffReset = outcome.onHandoffReset;
+              await this.syncPresence();
+            }
+            if (this.stopped || !this.link || this.archive.detached || this.isClaimCancelled(invocation)) {
+              if (parks)
+                this.resetReconnectHandoff();
+              await this.failInvocation(invocation, "Remote session changed before the command was handed off.");
+              return;
+            }
+            try {
+              await outcome.handoff({
+                workspaceId: invocation.workspaceId,
+                invocationId: invocation.id,
+                instanceId: this.config.instanceId,
+                claimToken: invocation.claimToken
+              });
+            } catch (error) {
+              if (parks)
+                this.resetReconnectHandoff();
+              throw error;
+            }
+            this.releaseObservation(invocation.id);
+            if (parks) {
+              this.reconnectResetTimer = setTimeout(() => this.resetReconnectHandoff(), RECONNECT_HANDOFF_FALLBACK_MS);
+            }
+            return;
+          }
+          if (!outcome.afterAck) {
+            await ackOutcome();
+            return;
+          }
+          this.reconnectHandoff = true;
+          this.onHandoffReset = outcome.onHandoffReset;
+          await this.syncPresence();
+          const completed = await ackOutcome();
+          if (!completed || this.stopped || !this.link || this.archive.detached) {
+            this.resetReconnectHandoff();
+            return;
+          }
+          try {
+            await outcome.afterAck();
+            this.reconnectResetTimer = setTimeout(() => this.resetReconnectHandoff(), RECONNECT_HANDOFF_FALLBACK_MS);
+          } catch (error) {
+            this.log(`session-control post-ack action failed: ${this.summarize(error)}`);
+            this.resetReconnectHandoff();
+          }
+        }
+      }
+    } catch (error) {
+      await this.failInvocation(invocation, this.summarize(error));
+    }
+  }
+  async runStop(invocation, actuator) {
+    const streamId = invocation.responseStreamId;
+    if (this.parallel && !this.routeForStream(streamId)) {
+      if (streamId === this.link?.rootStreamId)
+        return await this.stopTurnsOutsideScratchpad(invocation, actuator);
+      await this.completeAck(invocation, "No turn is running in this stream.");
+      return;
+    }
+    if (!actuator.interrupt(streamId)) {
+      await this.completeAck(invocation, "Could not send the interrupt (runtime control unavailable).");
+      return;
+    }
+    const hadTurn = this.inflight.size > 0;
+    await this.completeInterruptedTurns(this.controlStream(streamId));
+    await this.completeAck(invocation, hadTurn ? "Stopped the current turn." : "Sent an interrupt to the session.");
+    await this.syncPresence();
+  }
+  async stopTurnsOutsideScratchpad(invocation, actuator) {
+    const root = this.link?.rootStreamId;
+    const streams = new Set([...this.inflight.values()].filter((route) => route.invocation.rootStreamId !== root).map((route) => route.invocation.responseStreamId));
+    if (streams.size === 0) {
+      await this.completeAck(invocation, "No turn is running in this stream.");
+      return;
+    }
+    const interrupted = [...streams].filter((streamId) => actuator.interrupt(streamId));
+    for (const streamId of interrupted)
+      await this.completeInterruptedTurns(streamId);
+    if (interrupted.length === 0) {
+      await this.completeAck(invocation, "Could not send the interrupt (runtime control unavailable).");
+      return;
+    }
+    await this.completeAck(invocation, interrupted.length === 1 ? "Stopped the turn running outside this scratchpad." : `Stopped ${interrupted.length} turns running outside this scratchpad.`);
+    await this.syncPresence();
+  }
+  async runSteer(invocation, actuator, text) {
+    const steer = actuator.steer?.bind(actuator);
+    const running = this.parallel ? this.routeForStream(invocation.responseStreamId) !== undefined : this.inflight.size > 0;
+    if (running && steer) {
+      return await this.steerRunningTurn(invocation, steer, text);
+    }
+    if (this.parallel && !running && this.atCapacity) {
+      await this.completeAck(invocation, "Every turn slot is busy; resend the steer when a turn finishes.");
+      return;
+    }
+    return await this.steerByInterrupt(invocation, actuator, text);
+  }
+  async steerRunningTurn(invocation, steer, text) {
+    const streamId = invocation.responseStreamId;
+    const { parts, swept, contents } = await this.sweepQueuedForSteer(text, streamId);
+    if (this.isClaimCancelled(invocation))
+      return;
+    if (parts.length === 0) {
+      await Promise.all(swept.map((item) => this.completeNoResponse(item)));
+      if (invocation.metadata?.steeredMessage === true) {
+        await this.completeTurn(invocation, {
+          noResponse: true,
+          metadata: {
+            "remote.invocationId": invocation.id,
+            "remote.sessionControl": "true",
+            "remote.steered": "true"
+          }
+        });
+        return;
+      }
+      await this.completeAck(invocation, "Nothing to steer with (no text, no queued messages); the turn continues.");
+      return;
+    }
+    let combined = buildSteerContent(parts);
+    for (const route of this.controlRoutes(streamId)) {
+      await this.recordSteps(route.invocation.id, [{ stepType: "steer", content: combined }]);
+      route.touchIdleTimeout();
+    }
+    if (this.isClaimCancelled(invocation))
+      return;
+    const liveSwept = swept.filter((item) => !this.isClaimCancelled(item));
+    const currentParts = this.steerParts(liveSwept, text, contents);
+    if (currentParts.length === 0) {
+      await Promise.all(liveSwept.map((item) => this.completeNoResponse(item)));
+      await this.completeAck(invocation, "Nothing to steer with; the turn continues.");
+      return;
+    }
+    combined = buildSteerContent(currentParts);
+    const owner = [...this.inflight.values()].find((entry) => entry.invocation.responseStreamId === invocation.responseStreamId)?.invocation;
+    if (owner)
+      this.bindRunningOwner(owner.id, [invocation, ...liveSwept]);
+    if (!await steer(combined, streamId)) {
+      if (owner)
+        this.unbindRunningOwner(owner.id, [invocation, ...liveSwept]);
+      await Promise.all(liveSwept.map((item) => this.failInvocation(item, "Steer not delivered (runtime control unavailable); resend.")));
+      await this.completeAck(invocation, "Could not steer the session (runtime control unavailable).");
+      return;
+    }
+    if (this.isClaimCancelled(invocation) || owner && !this.inflight.has(owner.id))
+      return;
+    if (owner)
+      this.unbindRunningOwner(owner.id, [invocation]);
+    await this.completeTurn(invocation, {
+      noResponse: true,
+      metadata: {
+        "remote.invocationId": invocation.id,
+        "remote.sessionControl": "true",
+        "remote.steered": "true"
+      }
+    }).catch((error) => this.failAfterTerminalWrite(invocation, error, "steer completion"));
+  }
+  async steerByInterrupt(invocation, actuator, text) {
+    const streamId = invocation.responseStreamId;
+    if (!actuator.interrupt(streamId)) {
+      await this.completeAck(invocation, "Could not interrupt the session (runtime control unavailable); steer not delivered.");
+      return;
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, STEER_SETTLE_MS));
+    if (this.isClaimCancelled(invocation))
+      return;
+    await this.completeInterruptedTurns(this.controlStream(streamId));
+    const { parts, swept } = await this.sweepQueuedForSteer(text, streamId);
+    if (this.isClaimCancelled(invocation))
+      return;
+    if (parts.length === 0) {
+      await this.completeAck(invocation, "Interrupted the session; nothing pending to steer with.");
+      await this.syncPresence();
+      return;
+    }
+    this.bindRunningOwner(invocation.id, swept);
+    await this.deliverTurn(invocation, buildSteerContent(parts), swept);
+  }
+  async sweepQueuedForSteer(text, streamId) {
+    const swept = [];
+    const running = this.parallel ? streamId : [...this.inflight.values()][0]?.invocation.responseStreamId;
+    for (let i = 0;i < STEER_DRAIN_LIMIT; i++) {
+      const extra = await this.claimNext(false, running).catch(() => null);
+      if (!extra)
+        break;
+      this.markClaimProcessing(extra);
+      if (this.isClaimCancelled(extra))
+        continue;
+      swept.push(extra);
+    }
+    const contents = new Map;
+    for (const item of swept) {
+      if (this.isClaimCancelled(item))
+        continue;
+      contents.set(item.id, await this.foldedSteerContent(item));
+    }
+    const liveSwept = swept.filter((item) => !this.isClaimCancelled(item));
+    return { parts: this.steerParts(liveSwept, text, contents), swept: liveSwept, contents };
+  }
+  steerParts(liveSwept, text, contents) {
+    const parts = liveSwept.map((item) => contents.get(item.id) ?? "");
+    if (text)
+      parts.push(text);
+    return parts.filter(Boolean);
+  }
+  async sealSessionControlAck(invocation, markdown) {
+    const ack = parseSealedAckContext(invocation.sealedAck);
+    if (!ack)
+      return;
+    const identities = await this.bik.ensureForStream(invocation.rootStreamId);
+    if (identities.length === 0)
+      return;
+    try {
+      const sealing = await openSealedAck({ ack, identities, streamId: invocation.rootStreamId });
+      return await sealReply(sealing, markdown);
+    } catch {
+      return;
+    }
+  }
+  async completeAck(invocation, summary) {
+    if (this.isClaimCancelled(invocation))
+      return false;
+    const signal = this.observedClaims.get(invocation.id)?.lifecycle.signal;
+    try {
+      await this.client.complete(invocation.id, {
+        instanceId: this.config.instanceId,
+        claimToken: invocation.claimToken,
+        sourceRevision: invocation.sourceRevision,
+        summary,
+        metadata: {
+          "remote.invocationId": invocation.id,
+          "remote.sessionControl": "true"
+        }
+      }, signal);
+      if (signal?.aborted || this.isClaimCancelled(invocation))
+        return false;
+    } catch (error) {
+      await this.failAfterTerminalWrite(invocation, error, "session-control acknowledgement");
+      return false;
+    }
+    this.releaseObservation(invocation.id);
+    return true;
+  }
+  async completeReply(invocation, markdown) {
+    if (this.isClaimCancelled(invocation))
+      return false;
+    const signal = this.observedClaims.get(invocation.id)?.lifecycle.signal;
+    const sealedReply = await this.sealSessionControlAck(invocation, markdown);
+    if (signal?.aborted || this.isClaimCancelled(invocation))
+      return false;
+    try {
+      await this.client.complete(invocation.id, {
+        instanceId: this.config.instanceId,
+        claimToken: invocation.claimToken,
+        sourceRevision: invocation.sourceRevision,
+        ...sealedReply ? { sealedReply } : { finalMessageMarkdown: markdown },
+        metadata: {
+          "remote.invocationId": invocation.id,
+          "remote.sessionControl": "true"
+        }
+      }, signal);
+      if (signal?.aborted || this.isClaimCancelled(invocation))
+        return false;
+    } catch (error) {
+      if (!sealedReply && error instanceof ThreaApiError && error.code === "E2E_STREAM_PLAINTEXT_UNSUPPORTED") {
+        try {
+          await this.completeTurn(invocation, { noResponse: true });
+          return false;
+        } catch (inner) {
+          await this.failAfterTerminalWrite(invocation, inner, "session-control silent acknowledgement");
+          return false;
+        }
+      }
+      await this.failAfterTerminalWrite(invocation, error, sealedReply ? "sealed session-control reply" : "session-control reply");
+      return false;
+    }
+    this.releaseObservation(invocation.id);
+    return true;
+  }
+  async completeSilentAck(invocation) {
+    if (this.isClaimCancelled(invocation))
+      return false;
+    try {
+      await this.completeTurn(invocation, {
+        noResponse: true,
+        metadata: { "remote.invocationId": invocation.id, "remote.sessionControl": "true" }
+      });
+    } catch (error) {
+      await this.failAfterTerminalWrite(invocation, error, "silent session-control acknowledgement");
+      return false;
+    }
+    return true;
+  }
+  async completeNoResponse(invocation) {
+    try {
+      await this.completeTurn(invocation, {
+        noResponse: true,
+        metadata: {
+          "remote.invocationId": invocation.id,
+          "remote.steered": "true"
+        }
+      });
+    } catch (error) {
+      await this.failAfterTerminalWrite(invocation, error, "no-response completion");
+    }
+  }
+  async failAfterTerminalWrite(invocation, error, operation) {
+    this.log(`${operation} failed: ${this.summarize(error)}`);
+    if (this.isClaimCancelled(invocation))
+      return;
+    if (error instanceof ThreaApiError && error.status === 409 && error.code === "INVOCATION_INPUT_STALE") {
+      this.releaseObservation(invocation.id);
+      return;
+    }
+    await this.failInvocation(invocation, `Could not persist ${operation}.`);
+  }
+  async failInvocation(invocation, errorMessage) {
+    if (this.isClaimCancelled(invocation))
+      return;
+    await this.failFencedInvocation(invocation, errorMessage);
+    this.releaseObservation(invocation.id);
+  }
+  async completeInterruptedTurns(streamId) {
+    const routes = this.controlRoutes(streamId);
+    const interrupted = new Set(routes.map((route) => route.invocation.id));
+    const withdrawals = this.abandonPendingDecisions((decision) => !!decision.requesterInvocationId && interrupted.has(decision.requesterInvocationId));
+    const closes = routes.map((route) => {
+      route.revoke();
+      if (route.state === "open")
+        route.beginClosing();
+      if (this.activeTurnStream === route.invocation.responseStreamId)
+        this.activeTurnStream = undefined;
+      const generation = route.generation;
+      const task = route.enqueue(async () => {
+        if (this.stopped || generation !== this.lifecycle || route.state === "closed")
+          return;
+        try {
+          await this.completeTurn(route.invocation, {
+            noResponse: true,
+            metadata: { "remote.invocationId": route.invocation.id, "remote.interrupted": "true" },
+            signal: route.execution.signal
+          });
+          route.markClosed();
+          await this.completeContributors(route);
+        } catch (error) {
+          await this.failAfterTerminalWrite(route.invocation, error, "interrupted-turn completion");
+          await this.failContributors(route, "The owning turn could not be closed after interruption.");
+        } finally {
+          if (generation === this.lifecycle && this.inflight.get(route.invocation.id) === route) {
+            this.inflight.delete(route.invocation.id);
+          }
+        }
+      });
+      return route.trackClosing(task);
+    });
+    await Promise.all([...closes, withdrawals]);
+  }
+  async buildTurnContent(invocation, options = {}) {
+    return withInboundAttachments(formatInvocationContent(invocation), await this.inboundAttachmentManifest(invocation, options));
+  }
+  async foldedSteerContent(invocation) {
+    if (isSessionControlInvocation(invocation)) {
+      const queued = parseSessionControlCommand(invocation);
+      return queued?.name === "steer" ? queued.args : "";
+    }
+    const prompt = invocation.promptMarkdown.trim() || "(empty message)";
+    return withInboundAttachments(prompt, await this.inboundAttachmentManifest(invocation, { sourceOnly: true }));
+  }
+  async inboundAttachmentManifest(invocation, options = {}) {
+    if (options.signal?.aborted)
+      throw options.signal.reason;
+    if (invocation.sealing) {
+      const refs = invocation.sealedAttachments;
+      if (!refs)
+        return "";
+      try {
+        const downloaded = await downloadSealedInboundAttachments(this.client, {
+          refs: selectSealedInboundRefs(refs.prompt, options.sourceOnly ? [] : refs.history),
+          invocationId: invocation.id,
+          cwd: process.cwd(),
+          log: this.log,
+          strict: options.strictAttachments,
+          signal: options.signal
+        });
+        if (options.signal?.aborted)
+          throw options.signal.reason;
+        return formatInboundAttachmentManifest(downloaded);
+      } catch (error) {
+        if (options.strictAttachments || options.signal?.aborted)
+          throw error;
+        this.log(`sealed inbound attachment fetch failed: ${this.summarize(error)}`);
+        return "";
+      }
+    }
+    try {
+      const downloaded = await downloadInboundAttachments(this.client, {
+        streamId: invocation.activeStreamId,
+        sourceMessageId: invocation.sourceMessageId,
+        contextMessageIds: options.sourceOnly ? [] : (invocation.context?.messages ?? []).map((message) => message.messageId),
+        invocationId: invocation.id,
+        cwd: process.cwd(),
+        scanLimit: ATTACHMENT_SCAN_LIMIT,
+        log: this.log,
+        strict: options.strictAttachments,
+        signal: options.signal
+      });
+      if (options.signal?.aborted)
+        throw options.signal.reason;
+      return formatInboundAttachmentManifest(downloaded);
+    } catch (error) {
+      if (options.strictAttachments || options.signal?.aborted)
+        throw error;
+      this.log(`inbound attachment scan failed: ${this.summarize(error)}`);
+      return "";
+    }
+  }
+  route(invocationId) {
+    return this.inflight.get(invocationId) ?? this.completed.get(invocationId);
+  }
+  registerTurn(invocation, contributors = []) {
+    const route = new TurnRoute({
+      invocation,
+      contributors,
+      order: this.nextRouteOrder += 1,
+      generation: this.lifecycle,
+      idleTimeoutMs: this.config.idleTimeoutMs,
+      onIdleDeadline: (target, generation) => void this.onReplyTimeout(target, generation)
+    });
+    route.armIdleTimeout();
+    this.inflight.set(invocation.id, route);
+    return route;
+  }
+  revokedResult(route) {
+    return {
+      ok: false,
+      retryable: false,
+      message: `Request ${route.invocation.id} is no longer routable — this session stopped speaking for its stream.`
+    };
+  }
+  async postTurnMessage(route, intent, metadata) {
+    const seq = route.claimSeq(intent.retry);
+    const sealing = route.invocation.sealing;
+    const sourceRevision = route.invocation.sourceRevision;
+    let prepared = intent.retry;
+    if (!prepared) {
+      if (sealing) {
+        const uploaded = await uploadSealedReplyAttachments(this.client, intent.text, process.cwd());
+        const body = await sealReply(sealing, uploaded.markdown.trim(), uploaded.refs.length > 0 ? { attachmentRefs: uploaded.refs } : undefined);
+        prepared = {
+          kind: "sealed",
+          seq,
+          text: intent.text,
+          ...intent.retryKey === undefined ? {} : { retryKey: intent.retryKey },
+          body,
+          attachmentIds: uploaded.attachmentIds
+        };
+      } else {
+        const { markdown } = await uploadReplyAttachments(this.client, intent.text, process.cwd());
+        prepared = {
+          kind: "plaintext",
+          seq,
+          text: intent.text,
+          ...intent.retryKey === undefined ? {} : { retryKey: intent.retryKey },
+          body: {
+            instanceId: this.config.instanceId,
+            claimToken: route.invocation.claimToken,
+            content: markdown,
+            clientMessageId: intent.retryKey ?? `remote-send-${route.invocation.id}-${seq}`,
+            metadata
+          }
+        };
+      }
+    }
+    if (!prepared)
+      throw new Error("post preparation produced no body");
+    if (route.isFenced(this.lifecycle)) {
+      throw new RouteRevokedError(this.revokedResult(route).message);
+    }
+    if (!this.isOutputCurrent(route.invocation, sourceRevision)) {
+      throw new StaleInputError("invocation input changed while the post was being prepared");
+    }
+    try {
+      if (prepared.kind === "sealed") {
+        await this.client.sendSealedMessage(route.invocation.id, sealing.callbackToken, {
+          ...prepared.body,
+          ...prepared.attachmentIds.length > 0 && { attachmentIds: prepared.attachmentIds }
+        });
+      } else {
+        await this.client.sendInvocationMessage(route.invocation.id, prepared.body);
+      }
+    } catch (error) {
+      route.rememberFailedPost(seq, prepared, this.lifecycle);
+      throw error;
+    }
+    route.recordLandedPost(seq, prepared);
+  }
+  async writeRouteMessage(route, intent, metadata) {
+    try {
+      await this.postTurnMessage(route, intent, metadata);
+    } catch (error) {
+      await this.terminalizeRouteWrite(route, error);
+      throw error;
+    }
+  }
+  async prepareReply(route, text) {
+    const sealing = route.invocation.sealing;
+    const sourceRevision = route.invocation.sourceRevision;
+    if (sealing) {
+      const { markdown: markdown2, refs, attachmentIds: attachmentIds2 } = await uploadSealedReplyAttachments(this.client, text, process.cwd());
+      const spoken = markdown2.trim();
+      const reply = spoken.length > 0 || refs.length > 0 ? await sealReply(sealing, spoken, refs.length > 0 ? { attachmentRefs: refs } : undefined) : undefined;
+      return {
+        reason: "reply",
+        sourceText: text,
+        wire: {
+          kind: "sealed",
+          callbackToken: sealing.callbackToken,
+          body: reply === undefined ? { noResponse: true, sourceRevision } : { sourceRevision, reply: { ...reply, ...attachmentIds2.length > 0 && { attachmentIds: attachmentIds2 } } }
+        }
+      };
+    }
+    const { markdown, uploaded } = await uploadReplyAttachments(this.client, text, process.cwd());
+    const attachmentIds = uploaded.map((attachment) => attachment.id);
+    return {
+      reason: "reply",
+      sourceText: text,
+      wire: {
+        kind: "plaintext",
+        body: {
+          instanceId: this.config.instanceId,
+          claimToken: route.invocation.claimToken,
+          sourceRevision,
+          ...markdown.trim().length > 0 ? { finalMessageMarkdown: markdown } : { noResponse: true },
+          metadata: {
+            "remote.invocationId": route.invocation.id,
+            "remote.instanceId": this.config.instanceId,
+            ...attachmentIds.length > 0 && { "remote.attachmentIds": attachmentIds.join(",") }
+          }
+        }
+      }
+    };
+  }
+  async prepareTimeout(route) {
+    const note = "_The session ended the turn without sending a reply._";
+    const noResponse = route.sentCount > 0;
+    const sealing = route.invocation.sealing;
+    const sourceRevision = route.invocation.sourceRevision;
+    if (sealing) {
+      return {
+        reason: "timeout",
+        wire: {
+          kind: "sealed",
+          callbackToken: sealing.callbackToken,
+          body: noResponse ? { noResponse: true, sourceRevision } : { sourceRevision, reply: await sealReply(sealing, note) }
+        }
+      };
+    }
+    return {
+      reason: "timeout",
+      wire: {
+        kind: "plaintext",
+        body: {
+          instanceId: this.config.instanceId,
+          claimToken: route.invocation.claimToken,
+          sourceRevision,
+          ...noResponse ? { noResponse: true } : { finalMessageMarkdown: note },
+          metadata: { "remote.invocationId": route.invocation.id, "remote.timedOut": "true" }
+        }
+      }
+    };
+  }
+  async postPreparedClose(route, prepared) {
+    if (route.isFenced(this.lifecycle))
+      throw new RouteRevokedError("route revoked");
+    if (prepared.wire.kind === "sealed") {
+      await this.client.completeSealed(route.invocation.id, prepared.wire.callbackToken, prepared.wire.body, route.execution.signal);
+      return;
+    }
+    await this.client.complete(route.invocation.id, prepared.wire.body, route.execution.signal);
+  }
+  async settleClosed(route, replyText) {
+    const invocationId = route.invocation.id;
+    route.settleClosed(replyText);
+    this.inflight.delete(invocationId);
+    if (route.isFenced(this.lifecycle))
+      return;
+    this.completed.delete(invocationId);
+    this.completed.set(invocationId, route);
+    for (const oldest of this.completed.keys()) {
+      if (this.completed.size <= COMPLETED_TURN_MEMORY)
+        break;
+      this.completed.delete(oldest);
+    }
+    if (this.activeTurnStream === route.invocation.responseStreamId)
+      this.activeTurnStream = undefined;
+    await this.syncPresence();
+    this.claimDrainRequested = true;
+    this.scheduleRequestedClaimDrain();
+  }
+  async reopenAfterFailedCompletion(route, prepared) {
+    if (route.isFenced(this.lifecycle)) {
+      route.reopen(undefined);
+      return;
+    }
+    route.reopen(prepared);
+    route.armIdleTimeout();
+    this.inflight.set(route.invocation.id, route);
+    await this.syncPresence();
+  }
+  touchCompleted(invocationId, record) {
+    if (!this.completed.delete(invocationId))
+      return;
+    this.completed.set(invocationId, record);
+  }
+  isTerminalPostError(error) {
+    return error instanceof ThreaApiError && error.status >= 400 && error.status < 500 && !RETRYABLE_POST_STATUSES.has(error.status);
+  }
+  async terminalizeRouteWrite(route, error) {
+    if (!this.isTerminalPostError(error))
+      return false;
+    if (!route.terminal)
+      await this.evictTerminalRoute(route);
+    return true;
+  }
+  terminalWriteResult(invocationId, kind, error) {
+    return {
+      ok: false,
+      retryable: false,
+      message: `Threa rejected the ${kind} for request ${invocationId}: ${this.summarize(error)}.`
+    };
+  }
+  terminalResult(invocationId, kind, text) {
+    const tombstone = this.terminalReplies.get(invocationId);
+    if (kind === "reply" && tombstone?.replyDigest === this.replyDigest(text))
+      return { ok: true, message: "sent" };
+    return {
+      ok: false,
+      retryable: false,
+      message: `Threa refused further messages for request ${invocationId} — it is closed and no longer accepts follow-ups.`
+    };
+  }
+  async evictTerminalRoute(route) {
+    const invocationId = route.invocation.id;
+    route.markTerminal();
+    this.releaseObservation(invocationId);
+    this.inflight.delete(invocationId);
+    this.completed.delete(invocationId);
+    const newerRouteOwnsStream = [...this.inflight.values()].some((candidate) => candidate.order > route.order && !candidate.revoked && candidate.invocation.responseStreamId === route.invocation.responseStreamId);
+    if (this.activeTurnStream === route.invocation.responseStreamId && !newerRouteOwnsStream) {
+      this.activeTurnStream = undefined;
+    }
+    this.terminalReplies.delete(invocationId);
+    this.terminalReplies.set(invocationId, {
+      ...route.replyText === undefined ? {} : { replyDigest: this.replyDigest(route.replyText) }
+    });
+    for (const oldest of this.terminalReplies.keys()) {
+      if (this.terminalReplies.size <= COMPLETED_TURN_MEMORY)
+        break;
+      this.terminalReplies.delete(oldest);
+    }
+    await this.syncPresence();
+  }
+  async postThroughClosed(route, kind, intent) {
+    const invocationId = route.invocation.id;
+    if (kind === "reply" && route.replyText === intent.text) {
+      this.touchCompleted(invocationId, route);
+      return { ok: true, message: "sent" };
+    }
+    if (route.terminal)
+      return this.terminalResult(invocationId, kind, intent.text);
+    if (intent.text.trim().length === 0) {
+      return {
+        ok: false,
+        retryable: false,
+        message: `Request ${invocationId} had already closed, and an empty ${kind} has nothing to post as a follow-up.`
+      };
+    }
+    try {
+      await this.writeRouteMessage(route, intent, {
+        "remote.invocationId": invocationId,
+        "remote.followUp": "true"
+      });
+    } catch (error) {
+      if (error instanceof RouteRevokedError)
+        return this.revokedResult(route);
+      if (this.isTerminalPostError(error))
+        return this.terminalWriteResult(invocationId, "message", error);
+      return { ok: false, message: `Failed to post message to Threa: ${this.summarize(error)}`, retryable: true };
+    }
+    if (kind === "reply")
+      route.replyText = intent.text;
+    this.touchCompleted(invocationId, route);
+    return {
+      ok: true,
+      message: `Posted as a follow-up message — request ${invocationId} had already closed, and stays closed.`
+    };
+  }
+  async sendInterim(invocationId, text) {
+    const route = this.route(invocationId);
+    if (!route) {
+      if (this.terminalReplies.has(invocationId))
+        return this.terminalResult(invocationId, "send", text);
+      return {
+        ok: false,
+        retryable: false,
+        message: `No open request with invocation_id ${invocationId} — interim messages need an open request (it may have been answered or closed).`
+      };
+    }
+    if (text.trim().length === 0) {
+      return { ok: false, retryable: false, message: "An interim message needs content — nothing was posted." };
+    }
+    const intent = route.snapshotIntent(text);
+    return route.enqueue(() => this.runSend(route, intent));
+  }
+  async runSend(route, intent) {
+    if (route.terminal)
+      return this.terminalResult(route.invocation.id, "send", intent.text);
+    if (route.revoked)
+      return this.revokedResult(route);
+    if (route.state === "closed")
+      return this.postThroughClosed(route, "send", intent);
+    if (this.observedClaims.get(route.invocation.id)?.updateInProgress) {
+      return { ok: false, message: "Input update is still in progress; retry this send.", retryable: true };
+    }
+    const sourceRevision = route.invocation.sourceRevision;
+    try {
+      await this.writeRouteMessage(route, intent, {
+        "remote.invocationId": route.invocation.id,
+        "remote.interim": "true"
+      });
+    } catch (error) {
+      if (error instanceof RouteRevokedError)
+        return this.revokedResult(route);
+      if (error instanceof StaleInputError) {
+        return {
+          ok: false,
+          message: "Input changed while preparing this send; retry on the current turn.",
+          retryable: true
+        };
+      }
+      if (this.isTerminalPostError(error))
+        return this.terminalWriteResult(route.invocation.id, "message", error);
+      return { ok: false, message: `Failed to post message to Threa: ${this.summarize(error)}`, retryable: true };
+    }
+    if (!this.isOutputCurrent(route.invocation, sourceRevision)) {
+      return {
+        ok: false,
+        message: `Message post raced a source update for ${route.invocation.id}; do not treat it as current-turn output.`
+      };
+    }
+    route.touchIdleTimeout();
+    return { ok: true, message: "sent" };
+  }
+  async reply(invocationId, text) {
+    const route = this.route(invocationId);
+    if (!route) {
+      if (this.terminalReplies.has(invocationId))
+        return this.terminalResult(invocationId, "reply", text);
+      return {
+        ok: false,
+        retryable: false,
+        message: `No open request with invocation_id ${invocationId} (already answered, expired, or unknown).`
+      };
+    }
+    const intent = route.snapshotIntent(text);
+    return route.enqueue(() => this.runReply(route, intent));
+  }
+  async runReply(route, intent) {
+    if (route.state === "closed" && route.replyText === intent.text)
+      return { ok: true, message: "sent" };
+    if (route.terminal)
+      return this.terminalResult(route.invocation.id, "reply", intent.text);
+    if (route.revoked)
+      return this.revokedResult(route);
+    if (route.state === "closed")
+      return this.postThroughClosed(route, "reply", intent);
+    if (this.observedClaims.get(route.invocation.id)?.updateInProgress) {
+      return { ok: false, message: "Input update is still in progress; retry this reply.", retryable: true };
+    }
+    if (route.prepared && (route.prepared.reason === "timeout" || route.prepared.sourceText !== intent.text)) {
+      const resolved = await this.closeWith(route, route.prepared);
+      if (!resolved.ok) {
+        return {
+          ok: false,
+          retryable: resolved.retryable ?? false,
+          message: `The earlier close for request ${route.invocation.id} has not landed yet, so it still owns the close: ${resolved.message}`
+        };
+      }
+      const followUp = await this.postThroughClosed(route, "reply", intent);
+      return resolved.closedTurn ? { ...followUp, closedTurn: true } : followUp;
+    }
+    return this.closeWith(route, route.prepared ?? { kind: "reply", text: intent.text });
+  }
+  closeWith(route, source) {
+    route.beginClosing();
+    return route.trackClosing(this.runCompletion(route, source));
+  }
+  async runCompletion(route, source) {
+    const sourceRevision = route.invocation.sourceRevision;
+    let prepared;
+    if ("wire" in source) {
+      prepared = source;
+    } else {
+      try {
+        prepared = source.kind === "reply" ? await this.prepareReply(route, source.text) : await this.prepareTimeout(route);
+      } catch (error) {
+        await this.reopenAfterFailedCompletion(route, undefined);
+        if (route.revoked)
+          return this.revokedResult(route);
+        return {
+          ok: false,
+          message: `Failed to post reply to Threa (will stay open for retry): ${this.summarize(error)}`,
+          retryable: true
+        };
+      }
+    }
+    if (!this.isOutputCurrent(route.invocation, sourceRevision))
+      return this.closeStaleReply(route);
+    route.prepared = prepared;
+    try {
+      await this.postPreparedClose(route, prepared);
+    } catch (error) {
+      if (this.isClaimCancelled(route.invocation))
+        return this.closeStaleReply(route);
+      if (error instanceof ThreaApiError && error.status === 409 && error.code === "INVOCATION_INPUT_STALE") {
+        this.releaseObservation(route.invocation.id);
+        await this.failContributors(route, "The owning turn input became stale during completion.");
+        return this.closeStaleReply(route);
+      }
+      if (await this.terminalizeRouteWrite(route, error)) {
+        return this.terminalWriteResult(route.invocation.id, "reply", error);
+      }
+      await this.reopenAfterFailedCompletion(route, prepared);
+      if (error instanceof RouteRevokedError || route.revoked)
+        return this.revokedResult(route);
+      return {
+        ok: false,
+        message: `Failed to post reply to Threa (will stay open for retry): ${this.summarize(error)}`,
+        retryable: true
+      };
+    }
+    this.releaseObservation(route.invocation.id);
+    await this.completeContributors(route);
+    await this.settleClosed(route, prepared.reason === "reply" ? prepared.sourceText : undefined);
+    return { ok: true, message: "sent", closedTurn: true };
+  }
+  async closeStaleReply(route) {
+    route.revoke();
+    if (this.inflight.get(route.invocation.id) === route)
+      this.inflight.delete(route.invocation.id);
+    if (this.activeTurnStream === route.invocation.responseStreamId)
+      this.activeTurnStream = undefined;
+    await this.syncPresence();
+    return { ok: false, message: `Request ${route.invocation.id} is closed; its source changed.` };
+  }
+  async failTurn(invocationId, errorMessage) {
+    const route = this.route(invocationId);
+    if (!route)
+      return false;
+    return route.enqueue(() => route.trackClosing((async () => {
+      if (route.state === "closed" || route.terminal)
+        return false;
+      route.beginClosing();
+      await this.failContributors(route, errorMessage);
+      await this.failInvocation(route.invocation, errorMessage);
+      route.markClosed();
+      this.clearInflight(invocationId);
+      if (this.activeTurnStream === route.invocation.responseStreamId)
+        this.activeTurnStream = undefined;
+      await this.syncPresence();
+      this.claimDrainRequested = true;
+      this.scheduleRequestedClaimDrain();
+      return true;
+    })()));
+  }
+  async recordSteps(invocationId, frames, statusText) {
+    const entry = this.openRoute(invocationId);
+    if (!entry)
+      return false;
+    if (this.observedClaims.get(invocationId)?.updateInProgress)
+      return true;
+    for (let start = 0;start < frames.length; start += MAX_STEP_FRAMES_PER_CALL) {
+      const chunk = frames.slice(start, start + MAX_STEP_FRAMES_PER_CALL);
+      const sourceRevision = entry.invocation.sourceRevision;
+      if (entry.invocation.sealing) {
+        const sealing = entry.invocation.sealing;
+        const finished = chunk.filter((frame) => frame.phase !== "started");
+        if (finished.length === 0)
+          continue;
+        try {
+          const sealedFrames = await Promise.all(finished.map((frame) => sealStep(sealing, frame.stepType, frame.content, frame.durationMs !== undefined ? { durationMs: frame.durationMs } : undefined)));
+          if (!this.isOutputCurrent(entry.invocation, sourceRevision))
+            return this.inflight.has(invocationId);
+          await this.transport.recordSealedSteps(invocationId, sealing.callbackToken, sealedFrames);
+        } catch (error) {
+          this.log(`recordSteps (sealed) failed: ${this.summarize(error)}`);
+        }
+      } else {
+        if (!this.isOutputCurrent(entry.invocation, sourceRevision))
+          return this.inflight.has(invocationId);
+        await this.transport.recordSteps(invocationId, entry.invocation.claimToken, chunk, statusText ?? this.runtime.busyStatusText).catch((error) => this.log(`recordSteps failed: ${this.summarize(error)}`));
+      }
+      if (!this.openRoute(invocationId))
+        return false;
+    }
+    return true;
+  }
+  async postToInvocation(invocationId, body) {
+    const route = this.route(invocationId);
+    if (!route)
+      throw this.routeUnavailableError(invocationId);
+    await this.postRouteOwnedMessage(route, body);
+  }
+  async postToStream(streamId, body) {
+    const route = this.routeForStream(streamId);
+    if (route) {
+      await this.postRouteOwnedMessage(route, body);
+      return;
+    }
+    await this.client.sendMessage(streamId, body);
+  }
+  async postRouteOwnedMessage(route, body) {
+    const intent = route.snapshotIntent(body.content, body.clientMessageId);
+    await route.enqueue(async () => {
+      if (route.terminal)
+        throw this.routeUnavailableError(route.invocation.id);
+      if (route.revoked)
+        throw new RouteRevokedError(this.revokedResult(route).message);
+      await this.writeRouteMessage(route, intent, {
+        "remote.invocationId": route.invocation.id,
+        ...body.metadata
+      });
+      if (route.state === "closed")
+        this.touchCompleted(route.invocation.id, route);
+    });
+  }
+  routeUnavailableError(invocationId) {
+    if (this.terminalReplies.has(invocationId)) {
+      return new Error(`Threa refused further messages for request ${invocationId}; its route is terminal.`);
+    }
+    return new Error(`No routable request with invocation_id ${invocationId} exists in this session.`);
+  }
+  controlStream(streamId) {
+    return this.parallel ? streamId : undefined;
+  }
+  controlRoutes(streamId) {
+    const routes = [...this.inflight.values()];
+    const scope = streamId === undefined ? undefined : this.controlStream(streamId);
+    return scope === undefined ? routes : routes.filter((route) => route.invocation.responseStreamId === scope);
+  }
+  routeForStream(streamId) {
+    let closing;
+    for (const route of this.inflight.values()) {
+      if (route.invocation.responseStreamId !== streamId)
+        continue;
+      if (route.state === "open")
+        return route;
+      closing ??= route;
+    }
+    return closing;
+  }
+  openRoute(invocationId) {
+    const route = this.inflight.get(invocationId);
+    return route?.state === "open" && !route.revoked ? route : undefined;
+  }
+  isInflight(invocationId) {
+    return this.openRoute(invocationId) !== undefined;
+  }
+  keepAlive(streamId) {
+    for (const entry of this.inflight.values()) {
+      if (entry.state === "open" && entry.invocation.responseStreamId === streamId)
+        entry.touchIdleTimeout();
+    }
+  }
+  async requestDecision(input, opts = {}) {
+    if (!input.streamId && this.parallel && this.inflightStreams().size > 1) {
+      throw new Error("Cannot open a decision: turns are running in several streams; pass streamId.");
+    }
+    const onlyStream = this.parallel ? [...this.inflightStreams()][0] : undefined;
+    const streamId = input.streamId ?? onlyStream ?? this.activeTurnStream ?? this.link?.rootStreamId;
+    if (!streamId)
+      throw new Error("Cannot open a decision: this session has no active turn and no linked scratchpad.");
+    const route = this.routeForStream(streamId);
+    const invocationId = input.invocationId ?? route?.invocation.id;
+    const sealing = route?.invocation.sealing;
+    const question = sealing ? await this.sealedDecisionQuestion(streamId, input, sealing) : {
+      title: input.title,
+      ...input.body ? { bodyMarkdown: input.body } : {},
+      options: input.options
+    };
+    const decision = await this.client.requestDecision(streamId, {
+      ...question,
+      ...input.allowNote === undefined ? {} : { allowNote: input.allowNote },
+      ...input.externalRef ? { externalRef: input.externalRef } : {},
+      ...input.expiresInMs === undefined ? {} : { expiresInMs: input.expiresInMs },
+      runtimeSessionId: this.config.runtimeSessionId,
+      ...invocationId ? { invocationId } : {}
+    });
+    if (decision.status !== "open") {
+      return this.outcomeFor(decision, await this.decisionNote(decision, sealing));
+    }
+    if (this.stopped) {
+      this.cancelDecision(decision.id).catch(() => {});
+      throw new DecisionAbandonedError(decision.id);
+    }
+    const promise = new Promise((resolve2, reject) => {
+      this.pendingDecisions.set(decision.id, { decision, ...sealing ? { sealing } : {}, resolve: resolve2, reject });
+    });
+    const abort = () => {
+      if (!this.pendingDecisions.has(decision.id))
+        return;
+      this.failDecision(decision.id, decisionAbortError(decision.id));
+      this.cancelDecision(decision.id).catch((error) => this.log(`decision ${decision.id} cancel-on-abort failed: ${this.summarize(error)}`));
+    };
+    if (opts.signal?.aborted)
+      abort();
+    else
+      opts.signal?.addEventListener("abort", abort, { once: true });
+    this.keepTurnAliveForDecisions();
+    this.scheduleDecisionPoll();
+    try {
+      return await promise;
+    } finally {
+      opts.signal?.removeEventListener("abort", abort);
+    }
+  }
+  async cancelDecision(decisionId) {
+    await this.client.cancelDecision(decisionId);
+  }
+  async sealedDecisionQuestion(streamId, input, sealing) {
+    if (!this.botId) {
+      throw new Error("Cannot seal a decision: the bot plane never said which bot this session speaks as.");
+    }
+    const sealed = await sealDecision(sealing, { streamId, requesterBotId: this.botId }, {
+      title: input.title,
+      ...input.body ? { bodyMarkdown: input.body } : {},
+      optionLabels: Object.fromEntries(input.options.map((option) => [option.id, option.label ?? option.id]))
+    });
+    return {
+      options: input.options.map((option) => ({ id: option.id, tone: option.tone })),
+      decisionId: sealed.decisionId,
+      sealed: { ciphertext: sealed.ciphertext, envelope: sealed.envelope }
+    };
+  }
+  async decisionNote(decision, sealing) {
+    const resolution = decision.resolution;
+    if (!resolution?.noteCiphertext || !resolution.noteEnvelope)
+      return resolution?.note ?? null;
+    if (!sealing || !resolution.decidedBy) {
+      this.log(`decision ${decision.id} carries a sealed note this session has no way to open`);
+      return null;
+    }
+    const opened = await openSealedDecisionNote(sealing, {
+      streamId: decision.streamId,
+      decisionId: decision.id,
+      decidedBy: resolution.decidedBy,
+      ciphertext: resolution.noteCiphertext,
+      envelope: resolution.noteEnvelope
+    });
+    if (opened === null)
+      this.log(`decision ${decision.id} sealed note did not open`);
+    return opened;
+  }
+  outcomeFor(decision, note) {
+    if (decision.status === "resolved") {
+      const optionId = decision.resolution?.optionId;
+      if (!optionId)
+        throw new Error(`Decision ${decision.id} resolved without an option id.`);
+      return { status: "resolved", optionId, note, decision };
+    }
+    return { status: decision.status === "expired" ? "expired" : "cancelled", decision };
+  }
+  handleDecisionPush(payload) {
+    if (!payload || typeof payload !== "object")
+      return;
+    const pending = this.pendingDecisions.get(payload.decisionId);
+    if (!pending)
+      return;
+    if (payload.runtimeSessionId !== this.config.runtimeSessionId)
+      return;
+    this.settleDecision({
+      ...pending.decision,
+      status: payload.status,
+      version: payload.version,
+      ...payload.status === "resolved" && payload.optionId ? {
+        resolution: {
+          optionId: payload.optionId,
+          ...payload.note === null ? {} : { note: payload.note },
+          ...payload.noteCiphertext && payload.noteEnvelope ? { noteCiphertext: payload.noteCiphertext, noteEnvelope: payload.noteEnvelope } : {},
+          ...payload.decidedBy === null ? {} : { decidedBy: payload.decidedBy }
+        }
+      } : {}
+    });
+  }
+  async settleDecision(decision) {
+    const pending = this.pendingDecisions.get(decision.id);
+    if (!pending)
+      return;
+    this.pendingDecisions.delete(decision.id);
+    this.stopDecisionPollWhenIdle();
+    try {
+      pending.resolve(this.outcomeFor(decision, await this.decisionNote(decision, pending.sealing)));
+    } catch (error) {
+      pending.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  failDecision(decisionId, error) {
+    const pending = this.pendingDecisions.get(decisionId);
+    if (!pending)
+      return;
+    this.pendingDecisions.delete(decisionId);
+    this.stopDecisionPollWhenIdle();
+    pending.reject(error);
+  }
+  keepTurnAliveForDecisions() {
+    for (const streamId of new Set([...this.pendingDecisions.values()].map((pending) => pending.decision.streamId))) {
+      this.keepAlive(streamId);
+    }
+  }
+  scheduleDecisionPoll(delayMs) {
+    if (this.decisionPollTimer)
+      clearTimeout(this.decisionPollTimer);
+    this.decisionPollTimer = undefined;
+    if (this.stopped || this.pendingDecisions.size === 0)
+      return;
+    const delay = delayMs ?? (this.transport.socketConnected ? Math.min(WS_BACKSTOP_POLL_MS, Math.floor(this.config.idleTimeoutMs / 2)) : this.config.pollMs);
+    this.decisionPollTimer = setTimeout(() => {
+      this.decisionPollTimer = undefined;
+      this.pollPendingDecisions();
+    }, delay);
+  }
+  stopDecisionPollWhenIdle() {
+    if (this.pendingDecisions.size > 0)
+      return;
+    if (this.decisionPollTimer)
+      clearTimeout(this.decisionPollTimer);
+    this.decisionPollTimer = undefined;
+  }
+  async pollPendingDecisions() {
+    if (this.stopped)
+      return;
+    this.keepTurnAliveForDecisions();
+    for (const decisionId of [...this.pendingDecisions.keys()]) {
+      try {
+        const decision = await this.client.getDecision(decisionId);
+        if (decision.status !== "open")
+          await this.settleDecision(decision);
+      } catch (error) {
+        if (error instanceof ThreaApiError && error.status === 404) {
+          this.failDecision(decisionId, error);
+          continue;
+        }
+        this.log(`decision ${decisionId} backstop poll failed: ${this.summarize(error)}`);
+      }
+    }
+    this.scheduleDecisionPoll();
+  }
+  async abandonPendingDecisions(matches = () => true) {
+    const abandoned = [...this.pendingDecisions.values()].map((pending) => pending.decision).filter(matches);
+    for (const decision of abandoned)
+      this.failDecision(decision.id, new DecisionAbandonedError(decision.id));
+    this.stopDecisionPollWhenIdle();
+    await Promise.all(abandoned.map((decision) => this.cancelDecision(decision.id).catch((error) => this.log(`decision ${decision.id} withdraw failed: ${this.summarize(error)}`))));
+  }
+  async onReplyTimeout(route, generation) {
+    if (!route.isCurrentDeadline(generation) || route.state !== "open")
+      return;
+    await route.enqueue(() => this.runIdleTimeout(route, generation));
+  }
+  async runIdleTimeout(route, generation) {
+    if (!route.isCurrentDeadline(generation) || route.state !== "open" || route.revoked)
+      return;
+    const result = await this.closeWith(route, route.prepared ?? { kind: "timeout" });
+    if (!result.ok)
+      this.log(`timeout close failed: ${result.message}`);
+  }
+  clearInflight(invocationId) {
+    const entry = this.inflight.get(invocationId);
+    if (!entry)
+      return;
+    entry.revoke();
+    this.inflight.delete(invocationId);
+  }
+  async handleSessionArchived(payload) {
+    const data = payload ?? {};
+    if (typeof data.runtimeSessionId === "string" && data.runtimeSessionId !== this.config.runtimeSessionId)
+      return;
+    const linked = this.link?.rootStreamId;
+    const rootStreamId = typeof data.rootStreamId === "string" ? data.rootStreamId : linked;
+    if (!rootStreamId || linked && rootStreamId !== linked)
+      return;
+    await this.archive.archived(rootStreamId);
+  }
+  async handleSessionRestored(payload) {
+    const data = payload ?? {};
+    if (typeof data.runtimeSessionId === "string" && data.runtimeSessionId !== this.config.runtimeSessionId)
+      return;
+    await this.archive.restored();
+  }
+  async probeArchiveBackstop() {
+    await this.archive.probe(this.link?.rootStreamId);
+  }
+  async detachForArchive(rootStreamId) {
+    const inflight = this.revokeAllRoutes();
+    this.activeTurnStream = undefined;
+    this.link = undefined;
+    this.linkGeneration += 1;
+    this.resetReconnectHandoff();
+    await this.reconnectFallbackTask;
+    this.reschedulePoll(this.archive.probeDelayMs);
+    await this.waitForClaimDrain();
+    const offline = this.enqueueOfflinePresence(() => !this.stopped && this.archive.pendingRootStreamId === rootStreamId);
+    await this.failUnansweredRoutes(inflight);
+    await offline;
+  }
+  async windDownForArchive(rootStreamId) {
+    await this.shutdown();
+    await this.delegate.onArchived?.({ rootStreamId });
+  }
+  startPoll() {
+    this.reschedulePoll(this.config.pollMs);
+  }
+  handleTransportDisconnected() {
+    this.emptyNoSocketPolls = 0;
+    this.reschedulePoll(this.config.pollMs);
+    if (this.pendingDecisions.size > 0)
+      this.scheduleDecisionPoll(this.config.pollMs);
+  }
+  reschedulePoll(delayMs) {
+    if (this.stopped)
+      return;
+    if (this.pollTimer)
+      clearTimeout(this.pollTimer);
+    this.pollTimer = setTimeout(() => void this.pollTick(), delayMs);
+  }
+  async pollTick() {
+    if (this.stopped)
+      return;
+    await this.probeArchiveBackstop();
+    if (!this.link)
+      await this.ensureLink();
+    if (!this.transport.socketConnected)
+      await this.transport.connect();
+    const claimed = await this.claimDrain();
+    if (!this.stopped)
+      this.reschedulePoll(this.nextPollDelay(claimed));
+  }
+  nextPollDelay(claimed) {
+    if (this.archive.detached)
+      return this.archive.probeDelayMs;
+    if (this.transport.socketConnected) {
+      this.emptyNoSocketPolls = 0;
+      return WS_BACKSTOP_POLL_MS;
+    }
+    if (claimed) {
+      this.emptyNoSocketPolls = 0;
+      return this.config.pollMs;
+    }
+    const delay = Math.min(NO_SOCKET_POLL_CAP_MS, this.config.pollMs * 2 ** this.emptyNoSocketPolls);
+    this.emptyNoSocketPolls = Math.min(this.emptyNoSocketPolls + 1, 30);
+    return delay;
+  }
+  resetReconnectHandoff() {
+    if (this.reconnectResetTimer)
+      clearTimeout(this.reconnectResetTimer);
+    this.reconnectResetTimer = undefined;
+    const wasHandoff = this.reconnectHandoff;
+    this.reconnectHandoff = false;
+    const onHandoffReset = this.onHandoffReset;
+    this.onHandoffReset = undefined;
+    if (!wasHandoff && !onHandoffReset)
+      return;
+    let callbackTask;
+    if (onHandoffReset) {
+      try {
+        callbackTask = Promise.resolve(onHandoffReset()).catch((error) => this.log(`session-control handoff reset failed: ${this.summarize(error)}`));
+      } catch (error) {
+        this.log(`session-control handoff reset failed: ${this.summarize(error)}`);
+      }
+    }
+    if (this.stopped || !this.link || this.archive.detached) {
+      if (callbackTask)
+        this.reconnectFallbackTask = callbackTask;
+      return;
+    }
+    let task;
+    const restoreIntake = () => this.syncPresence().then(() => this.claimDrain());
+    task = (callbackTask ? callbackTask.then(restoreIntake) : restoreIntake()).finally(() => {
+      if (this.reconnectFallbackTask === task)
+        this.reconnectFallbackTask = undefined;
+    });
+    this.reconnectFallbackTask = task;
+  }
+  async keyGrantedStreams(streamIds) {
+    for (const streamId of streamIds)
+      await this.bik.ensureForStream(streamId);
+    await this.advertiseKeyring();
+  }
+  async keyRevokedStream(streamId) {
+    await this.bik.dropStream(streamId);
+    await this.advertiseKeyring();
+  }
+  async advertiseKeyring() {
+    const advertised = this.bik.identities.map((identity) => identity.publicKeyId).join(",");
+    if (advertised === this.advertisedKeyIds)
+      return;
+    this.advertisedKeyIds = advertised;
+    Object.assign(this.hello, this.bik.presenceFields());
+    await this.syncPresence();
+  }
+  enqueuePresence(write) {
+    const queued = this.presenceTail.then(write);
+    this.presenceTail = queued.catch(() => {
+      return;
+    });
+    return this.presenceTail;
+  }
+  syncPresence() {
+    const lifecycle = this.lifecycle;
+    return this.enqueuePresence(async () => {
+      if (lifecycle !== this.lifecycle || this.stopped || this.archive.detached)
+        return;
+      const busy = this.reconnectHandoff || this.atCapacity;
+      await this.publishPresence(this.presenceBody(busy ? "busy" : "available", busy ? this.runtime.busyStatusText : undefined));
+    });
+  }
+  enqueueOfflinePresence(isCurrent) {
+    const lifecycle = this.lifecycle;
+    return this.enqueuePresence(async () => {
+      if (lifecycle !== this.lifecycle || !isCurrent())
+        return;
+      await this.publishPresence(this.presenceBody("offline"));
+    });
+  }
+  async publishPresence(body) {
+    await this.transport.updatePresence(body);
+    this.reportPresence(body);
+  }
+  reportPresence(body) {
+    if (!this.onPresence)
+      return;
+    try {
+      this.onPresence({
+        runtimeKind: body.runtimeKind,
+        instanceId: body.instanceId,
+        runtimeSessionId: body.runtimeSessionId,
+        displayName: body.displayName,
+        status: body.status,
+        capabilities: body.capabilities,
+        manifest: body.manifest
+      });
+    } catch (error) {
+      this.log(`presence report failed: ${this.summarize(error)}`);
+    }
+  }
+  presenceBody(status, statusText) {
+    return {
+      runtimeKind: this.runtime.kind,
+      instanceId: this.config.instanceId,
+      runtimeSessionId: this.config.runtimeSessionId,
+      displayName: this.config.displayName,
+      status,
+      acceptingInvocations: status === "available",
+      capabilities: runtimeCapabilitiesFor(this.config.runtimeSessionId, this.delegate.sessionControl),
+      manifest: effectiveRuntimeManifest(this.runtime.manifest, this.delegate.sessionControl),
+      ...statusText ? { statusText } : {},
+      ...this.bik.presenceFields()
+    };
+  }
+  claimBody(busy, excludeResponseStreamIds = []) {
+    return {
+      runtimeKind: this.runtime.kind,
+      instanceId: this.config.instanceId,
+      runtimeSessionId: this.config.runtimeSessionId,
+      supportedCapabilities: claimCapabilitiesFor(busy, this.sessionControlEnabled),
+      claimTtlSeconds: CLAIM_TTL_SECONDS,
+      ...!busy && excludeResponseStreamIds.length > 0 ? { excludeResponseStreamIds } : {}
+    };
+  }
+  replyDigest(text) {
+    return createHash2("sha256").update(text).digest("hex");
+  }
+  summarize(error) {
+    return (error instanceof Error ? error.message : String(error)).slice(0, 200);
+  }
+}
+// src/config-file.ts
+import { chmodSync, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+function readConfigFile(path, log) {
+  if (!existsSync(path))
+    return;
+  try {
+    return parseConfigFile(readFileSync2(path, "utf8"));
+  } catch (error) {
+    log(`ignoring ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+}
+function writeFileAtomic(path, content, mode = 384) {
+  mkdirSync2(dirname2(path), { recursive: true, mode: 448 });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync2(temp, content, { mode, flag: "wx" });
+  chmodSync(temp, mode);
+  renameSync(temp, path);
+}
+// src/lifecycle.ts
+function describeError(value) {
+  if (value instanceof Error)
+    return value.stack ?? value.message;
+  return String(value);
+}
+function defaultParentAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function wireLifecycle(server, host, options = {}) {
+  const logPrefix = options.logPrefix ?? "[threa-remote]";
+  const exitGuardMs = options.exitGuardMs ?? 4000;
+  const parentAlive = options.parentAlive ?? defaultParentAlive;
+  const parentProbeDelayMs = options.parentProbeDelayMs ?? 250;
+  const hostPid = host.ppid;
+  let shuttingDown = false;
+  const shutdownAndExit = async (code, reason, shutdown = {}) => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    host.stderr.write(`${logPrefix} shutting down (${reason})
+`);
+    const guard = setTimeout(() => host.exit(code), exitGuardMs);
+    if (guard && typeof guard === "object" && "unref" in guard)
+      guard.unref();
+    await server.shutdown(shutdown).catch(() => {
+      return;
+    });
+    clearTimeout(guard);
+    host.exit(code);
+  };
+  host.on("SIGINT", () => void shutdownAndExit(0, "SIGINT"));
+  host.on("SIGTERM", () => void shutdownAndExit(0, "SIGTERM"));
+  host.on("SIGHUP", () => void shutdownAndExit(0, "SIGHUP"));
+  const stdinClosed = () => {
+    if (shuttingDown)
+      return;
+    setTimeout(() => void shutdownAndExit(0, "stdin closed by parent", { hostGone: !parentAlive(hostPid) }), parentProbeDelayMs);
+  };
+  host.stdin.on("end", stdinClosed);
+  host.stdin.on("close", stdinClosed);
+  host.on("uncaughtException", (error) => {
+    host.stderr.write(`${logPrefix} uncaughtException: ${describeError(error)}
+`);
+    shutdownAndExit(1, "uncaughtException");
+  });
+  host.on("unhandledRejection", (reason) => {
+    host.stderr.write(`${logPrefix} unhandledRejection: ${describeError(reason)}
+`);
+    shutdownAndExit(1, "unhandledRejection");
+  });
+}
+// src/delegation-client.ts
+var FETCH_TIMEOUT_MS2 = 30000;
+var CALLBACK_TOKEN_HEADER = "X-Threa-Callback-Token";
+
+class DelegationClient {
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  get base() {
+    return this.opts.baseUrl.replace(/\/$/, "");
+  }
+  path(suffix) {
+    return `${this.base}/api/v1/workspaces/${this.opts.workspaceId}/delegations${suffix}`;
+  }
+  async request(url, init) {
+    const controller = new AbortController;
+    const timeout = setTimeout(() => controller.abort(), this.opts.fetchTimeoutMs ?? FETCH_TIMEOUT_MS2);
+    try {
+      return await this.requestWithin(url, init, controller.signal);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  async requestWithin(url, init, signal) {
+    const { claimToken, ...request } = init ?? {};
+    const response = await fetch(url, {
+      ...request,
+      signal,
+      headers: {
+        Authorization: `Bearer ${this.opts.apiKey}`,
+        "Content-Type": "application/json",
+        ...claimToken ? { [CALLBACK_TOKEN_HEADER]: claimToken } : {},
+        ...request.headers
+      }
+    });
+    if (!response.ok) {
+      let code;
+      if (response.headers.get("content-type")?.includes("application/json")) {
+        try {
+          const parsed = JSON.parse((await response.text()).slice(0, 2000));
+          if (typeof parsed.code === "string")
+            code = parsed.code;
+        } catch {
+          code = undefined;
+        }
+      }
+      throw new ThreaApiError(`Threa API ${response.status}: ${response.statusText}`, response.status, code);
+    }
+    const { data } = await response.json();
+    return data;
+  }
+  async get(id) {
+    return this.request(this.path(`/${encodeURIComponent(id)}`));
+  }
+  async listOpen(opts) {
+    const query = opts?.since ? `?since=${encodeURIComponent(opts.since)}` : "";
+    return this.request(this.path(query));
+  }
+  async claim(id, body) {
+    return this.request(this.path(`/${id}/claim`), {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async release(id, claimToken) {
+    return this.request(this.path(`/${encodeURIComponent(id)}/release`), {
+      method: "POST",
+      body: "{}",
+      claimToken
+    });
+  }
+  async heartbeat(id, claimToken) {
+    return this.request(this.path(`/${id}/heartbeat`), { method: "POST", body: "{}", claimToken });
+  }
+  async reportStatus(id, claimToken, statusNote) {
+    return this.request(this.path(`/${id}/status`), {
+      method: "POST",
+      body: JSON.stringify({ statusNote }),
+      claimToken
+    });
+  }
+  async complete(id, claimToken, body) {
+    return this.request(this.path(`/${id}/complete`), {
+      method: "POST",
+      body: JSON.stringify(body),
+      claimToken
+    });
+  }
+  async fail(id, claimToken, errorMessage) {
+    return this.request(this.path(`/${id}/fail`), {
+      method: "POST",
+      body: JSON.stringify({ errorMessage }),
+      claimToken
+    });
+  }
+  async requestAccess(delegationId, opts) {
+    return this.request(this.path(`/${delegationId}/request-access`), {
+      method: "POST",
+      body: JSON.stringify(opts?.requestedByLabel ? { requestedByLabel: opts.requestedByLabel } : {})
+    });
+  }
+}
+// src/delegation-runner.ts
+var DEFAULT_POLL_MS = 60000;
+var DEFAULT_HEARTBEAT_MS = 5 * 60 * 1000;
+var FAIL_MESSAGE_MAX = 1000;
+var STATUS_NOTE_MAX = 2000;
+var SHUTDOWN_WAIT_MS = 2000;
+var DELEGATION_STOP_REASON = "runner_shutdown";
+
+class DelegationRunner {
+  client;
+  executor;
+  claimedByLabel;
+  persistIdempotencyKey;
+  pollMs;
+  heartbeatMs;
+  shutdownWaitMs;
+  log;
+  stopped = true;
+  generation = 0;
+  current;
+  stopOperation;
+  pollTimer;
+  active;
+  pendingNudged = new Set;
+  accessRequested = new Set;
+  constructor(opts) {
+    this.client = opts.client;
+    this.executor = opts.executor;
+    this.claimedByLabel = opts.claimedByLabel;
+    this.persistIdempotencyKey = opts.persistIdempotencyKey;
+    this.pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    this.heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+    this.shutdownWaitMs = opts.shutdownWaitMs ?? SHUTDOWN_WAIT_MS;
+    this.log = opts.log ?? (() => {});
+  }
+  start() {
+    if (!this.stopped)
+      return;
+    this.stopped = false;
+    this.generation += 1;
+    const generation = this.generation;
+    this.pollTimer = setInterval(() => this.drain(generation), this.pollMs);
+    this.drain(generation);
+  }
+  async stop(_reason = DELEGATION_STOP_REASON, options) {
+    if (!this.stopped)
+      this.stopped = true;
+    const generation = this.generation;
+    if (this.pollTimer)
+      clearInterval(this.pollTimer);
+    this.pollTimer = undefined;
+    const active = this.active?.generation === generation ? this.active : undefined;
+    active?.cleanupHeartbeat?.();
+    active?.controller.abort();
+    let pending = this.stopOperation?.generation === generation ? this.stopOperation.promise : undefined;
+    if (!pending) {
+      const release = active && !active.lost ? this.releaseActive(active) : undefined;
+      pending = release ?? (this.current?.generation === generation ? this.current.promise : Promise.resolve());
+      this.stopOperation = { generation, promise: pending };
+    }
+    if (this.current?.generation === generation)
+      this.current = undefined;
+    if (this.active === active)
+      this.active = undefined;
+    const timeoutError = new Error(`delegation runner stop timed out after ${this.shutdownWaitMs}ms`);
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(timeoutError), this.shutdownWaitMs);
+    });
+    try {
+      if (options?.strict)
+        await Promise.race([pending, timeout]);
+      else
+        await Promise.race([pending.catch(() => {
+          return;
+        }), timeout.catch(() => {
+          return;
+        })]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
+  notifyAvailable(nudge) {
+    if (nudge?.delegationId)
+      this.pendingNudged.add(nudge.delegationId);
+    this.drain(this.generation);
+  }
+  isCurrent(generation) {
+    return !this.stopped && this.generation === generation;
+  }
+  drain(generation) {
+    if (!this.isCurrent(generation) || this.current?.generation === generation)
+      return;
+    const promise = this.runDrain(generation).finally(() => {
+      if (this.current?.promise === promise)
+        this.current = undefined;
+    });
+    this.current = { generation, promise };
+    promise.catch((error) => {
+      this.log(`delegation drain failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+  }
+  async runDrain(generation) {
+    let executed = true;
+    while (executed && this.isCurrent(generation)) {
+      executed = false;
+      const open = await this.client.listOpen();
+      if (!this.isCurrent(generation))
+        return;
+      for (const summary of open)
+        this.pendingNudged.delete(summary.id);
+      for (const summary of open) {
+        if (!this.isCurrent(generation))
+          return;
+        const claimed = await this.tryClaim(summary);
+        if (!claimed)
+          continue;
+        if (!this.isCurrent(generation)) {
+          await this.releaseStoppedClaim(claimed, generation);
+          return;
+        }
+        await this.execute(claimed, generation);
+        executed = true;
+        break;
+      }
+      if (executed)
+        continue;
+      for (const id of [...this.pendingNudged]) {
+        if (!this.isCurrent(generation))
+          return;
+        const claimed = await this.tryClaimNudged(id);
+        if (!claimed)
+          continue;
+        if (!this.isCurrent(generation)) {
+          await this.releaseStoppedClaim(claimed, generation);
+          return;
+        }
+        await this.execute(claimed, generation);
+        executed = true;
+        break;
+      }
+    }
+  }
+  async tryClaim(summary) {
+    const idempotencyKey = crypto.randomUUID();
+    await this.persistIdempotencyKey?.(summary.id, idempotencyKey);
+    try {
+      return await this.client.claim(summary.id, { claimedByLabel: this.claimedByLabel, idempotencyKey });
+    } catch (error) {
+      if (error instanceof ThreaApiError && (error.status === 409 || error.status === 404))
+        return null;
+      throw error;
+    }
+  }
+  async tryClaimNudged(id) {
+    const idempotencyKey = crypto.randomUUID();
+    await this.persistIdempotencyKey?.(id, idempotencyKey);
+    try {
+      const claimed = await this.client.claim(id, { claimedByLabel: this.claimedByLabel, idempotencyKey });
+      this.pendingNudged.delete(id);
+      return claimed;
+    } catch (error) {
+      if (error instanceof ThreaApiError && error.status === 409) {
+        this.pendingNudged.delete(id);
+        return null;
+      }
+      if (error instanceof ThreaApiError && error.status === 404) {
+        await this.requestAccessOnce(id);
+        this.pendingNudged.delete(id);
+        return null;
+      }
+      throw error;
+    }
+  }
+  async requestAccessOnce(id) {
+    if (this.accessRequested.has(id))
+      return;
+    try {
+      await this.client.requestAccess(id, { requestedByLabel: this.claimedByLabel });
+      this.accessRequested.add(id);
+      this.log(`delegation ${id} not claimable (no access) — filed an access request`);
+    } catch (error) {
+      this.log(`delegation ${id} access request failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async releaseStoppedClaim(task, generation) {
+    const active = this.createActiveClaim(task, generation);
+    await this.releaseActive(active);
+  }
+  createActiveClaim(task, generation) {
+    let settleLost;
+    const lostPromise = new Promise((resolve2) => settleLost = resolve2);
+    return { task, generation, controller: new AbortController, lost: false, settleLost, lostPromise };
+  }
+  releaseActive(active) {
+    if (active.release)
+      return active.release;
+    const release = this.client.release(active.task.id, active.task.claimToken).then(() => {
+      return;
+    });
+    active.release = release;
+    release.catch((error) => {
+      this.log(`delegation ${active.task.id} release failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return release;
+  }
+  async execute(task, generation) {
+    const { id, claimToken } = task;
+    const active = this.createActiveClaim(task, generation);
+    this.active = active;
+    let heartbeatBusy = false;
+    const cleanupHeartbeat = () => {
+      if (!active.cleanupHeartbeat)
+        return;
+      active.cleanupHeartbeat = undefined;
+      clearInterval(heartbeat);
+    };
+    const loseClaim = () => {
+      if (active.lost)
+        return;
+      active.lost = true;
+      cleanupHeartbeat();
+      active.controller.abort();
+      active.settleLost();
+    };
+    const handleLifecycleError = (kind, error) => {
+      if (error instanceof ThreaApiError && error.status === 404)
+        loseClaim();
+      this.log(`delegation ${id} ${kind} failed: ${error instanceof Error ? error.message : String(error)}`);
+    };
+    const heartbeat = setInterval(async () => {
+      if (heartbeatBusy || active.lost || active.controller.signal.aborted)
+        return;
+      heartbeatBusy = true;
+      try {
+        await this.client.heartbeat(id, claimToken);
+      } catch (error) {
+        handleLifecycleError("heartbeat", error);
+      } finally {
+        heartbeatBusy = false;
+      }
+    }, this.heartbeatMs);
+    active.cleanupHeartbeat = cleanupHeartbeat;
+    const ctx = {
+      signal: active.controller.signal,
+      reportStatus: async (note) => {
+        if (active.lost || active.controller.signal.aborted)
+          return;
+        try {
+          await this.client.reportStatus(id, claimToken, note.slice(0, STATUS_NOTE_MAX));
+        } catch (error) {
+          handleLifecycleError("status report", error);
+        }
+      }
+    };
+    const execution = Promise.resolve().then(() => this.executor(task, ctx)).then((result) => ({ kind: "result", result }), (error) => ({ kind: "error", error }));
+    try {
+      const outcome = await Promise.race([execution, active.lostPromise.then(() => ({ kind: "lost" }))]);
+      if (outcome.kind === "lost")
+        return;
+      if (active.lost || active.controller.signal.aborted || !this.isCurrent(generation) || this.active !== active)
+        return;
+      if (outcome.kind === "error")
+        throw outcome.error;
+      await this.client.complete(id, claimToken, {
+        resultMarkdown: outcome.result?.resultMarkdown,
+        metadata: outcome.result?.metadata
+      });
+      this.log(`delegation ${id} completed`);
+    } catch (error) {
+      if (active.lost || active.controller.signal.aborted || !this.isCurrent(generation) || this.active !== active)
+        return;
+      const message = (error instanceof Error ? error.message : String(error)).slice(0, FAIL_MESSAGE_MAX);
+      try {
+        await this.client.fail(id, claimToken, message || "Delegation runner failed without a message");
+      } catch (failError) {
+        this.log(`delegation ${id} failed AND the fail report failed: ${failError instanceof Error ? failError.message : String(failError)}`);
+      }
+    } finally {
+      cleanupHeartbeat();
+      if (this.active === active)
+        this.active = undefined;
+    }
+  }
+}
+// src/tool-trace.ts
+var TOOL_TRACE_FORMAT = "pi_tool_trace";
+var TOOL_TRACE_MAX_CHARS = 9500;
+var HEADLINE_MAX_CHARS = 500;
+var TRUNCATION_MARKER = `
+
+…[section truncated;`;
+function toolTraceContent(params) {
+  const headline = params.headline.length <= HEADLINE_MAX_CHARS ? params.headline : `${params.headline.slice(0, HEADLINE_MAX_CHARS)}…`;
+  const sections = params.sections.map((section) => ({ ...section, originalBody: section.body }));
+  for (let attempt = 0;attempt < 24; attempt++) {
+    const payload = JSON.stringify({
+      format: TOOL_TRACE_FORMAT,
+      headline,
+      sections: sections.map(({ originalBody: _originalBody, ...section }) => section)
+    });
+    if (payload.length <= TOOL_TRACE_MAX_CHARS)
+      return payload;
+    const largestIndex = sections.reduce((largest2, section, index) => section.body.length > sections[largest2].body.length ? index : largest2, 0);
+    const largest = sections[largestIndex];
+    if (!largest || largest.originalBody.length === 0)
+      break;
+    const overflow = payload.length - TOOL_TRACE_MAX_CHARS;
+    const currentVisibleLength = largest.body.includes(TRUNCATION_MARKER) ? largest.body.indexOf(TRUNCATION_MARKER) : largest.body.length;
+    const nextVisibleLength = Math.max(0, currentVisibleLength - Math.max(overflow + 256, 512));
+    const omitted = largest.originalBody.length - nextVisibleLength;
+    largest.body = `${largest.originalBody.slice(0, nextVisibleLength).trimEnd()}${TRUNCATION_MARKER} ${omitted} more characters]`;
+  }
+  return JSON.stringify({
+    format: TOOL_TRACE_FORMAT,
+    headline,
+    sections: [{ label: "Details", body: "Trace content was too large to serialize safely.", lang: null }]
+  });
+}
+export {
+  writeFileAtomic,
+  wireLifecycle,
+  uploadReplyAttachments,
+  toolTraceContent,
+  supportedCapabilitiesFor,
+  sanitizeId,
+  runtimeCapabilitiesFor,
+  readConfigFile,
+  parseSessionControlCommand,
+  parseConfigFile,
+  loadConfig,
+  isSessionControlInvocation,
+  guessMimeType,
+  formatInvocationContent,
+  formatInboundAttachmentManifest,
+  extractAttachmentDirectives,
+  effectiveRuntimeManifest,
+  downloadInboundAttachments,
+  deriveStableId,
+  defaultDisplayName,
+  claimCapabilitiesFor,
+  buildSteerContent,
+  ThreaClient,
+  ThreaApiError,
+  TRACE_MODES,
+  STEER_SETTLE_MS,
+  SESSION_CONTROL_CAPABILITY,
+  RemoteSession,
+  DelegationRunner,
+  DelegationClient,
+  DecisionAbandonedError,
+  COMPLETED_TURN_MEMORY,
+  ATTACH_DIRECTIVE_RE,
+  ATTACHMENT_DIR
+};
+
+//# debugId=EE71C0ED22C7B43264756E2164756E21
+//# sourceMappingURL=index.js.map