Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
32.4 KB
Raw Blame
/**
 * The archive upload client (sections 7 and 13.5): JSON calls to the
 * omnirush.ai archive routes, and part PUTs straight to S3 through presigned
 * URLs, each part read from the sealed file when it is sent. Presigned URLs
 * and bearer tokens are credentials and are never logged.
 */
import { open, type FileHandle } from "node:fs/promises";
import { z } from "zod";

import { parseArchivePolicy, type ArchivePolicy } from "./policy.js";
import { SEAL_ALG, sealKid, type SealContent } from "./seal.js";
import { gatewayUrlAllowed } from "../release-guard.js";

export type ArchiveFetch = (input: string, init?: RequestInit) => Promise<Response>;
/**
 * An authenticated request to the omnirush.ai API, relative to its root
 * (`archives/key`, `archives`, `archives/<id>/parts`, ...). The owner of the
 * device session (the gateway broker) attaches the bearer and handles its own
 * rotation, as it does for the session uploader's `upload` hook.
 */
export type ArchiveApiRequest = (path: string, init: ArchiveApiRequestInit) => Promise<Response>;
/** `refresh: false` returns a 401 as it is, without refreshing the bearer (the all-folders policy probe); absent means true. */
export type ArchiveApiRequestInit = { method: "GET" | "POST"; body?: string; signal?: AbortSignal; refresh?: false };
export type ArchiveLog = (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;

export type RetryPolicy = {
  /** First backoff; doubles per attempt (1 s). */
  baseMs: number;
  /** Backoff cap (5 min). */
  maxMs: number;
  /** Attempts per request before it is left to the next drain (8). */
  attempts: number;
  sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
  random: () => number;
};

export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  return new Promise((resolvePromise) => {
    if (signal?.aborted) {
      resolvePromise();
      return;
    }
    const timer = setTimeout(done, ms);
    function done() {
      clearTimeout(timer);
      signal?.removeEventListener("abort", done);
      resolvePromise();
    }
    signal?.addEventListener("abort", done, { once: true });
  });
}

export const DEFAULT_RETRY_POLICY: RetryPolicy = { baseMs: 1_000, maxMs: 5 * 60_000, attempts: 8, sleep, random: Math.random };

/** Exponential backoff with plus or minus 20% jitter. */
export function backoffMs(policy: RetryPolicy, attempt: number): number {
  const exact = Math.min(policy.maxMs, policy.baseMs * 2 ** Math.max(0, attempt - 1));
  return Math.round(exact * (0.8 + 0.4 * policy.random()));
}

const REQUEST_TIMEOUT_MS = 30_000;
/** The all-folders policy probe: one attempt this long at most, no backoff and no bearer refresh. */
export const POLICY_PROBE_TIMEOUT_MS = 5_000;
/** A part PUT may take this long at least, and longer for big parts on slow links (32 KB/s floor). */
const PART_MIN_TIMEOUT_MS = 10 * 60_000;
const PART_MIN_BYTES_PER_MS = 32;
/** A part is read from the sealed file in slices this big, checking for an abort between them. */
const PART_READ_SLICE_BYTES = 1024 * 1024;
const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);

/**
 * An API answer worth trying again later (the job stays queued, also for the
 * next start): the statuses above, any other 5xx but 501/505 (507: the
 * server's disk is full), and a 413 that carries a Retry-After (load
 * shedding, not a too-large archive). `soon` is false when another attempt
 * within this drain is pointless (507, or the server said when to return).
 */
function retryableApiStatus(response: Response): { retry: boolean; soon: boolean } {
  const retryAfter = response.headers?.get?.("retry-after")?.trim() || null;
  if (RETRYABLE_STATUSES.has(response.status)) return { retry: true, soon: retryAfter === null };
  if (response.status >= 500 && response.status <= 599 && response.status !== 501 && response.status !== 505) {
    return { retry: true, soon: retryAfter === null && response.status !== 507 };
  }
  return { retry: response.status === 413 && retryAfter !== null, soon: false };
}
const PART_RETRYABLE_STATUSES = new Set([400, 408, 429, 500, 502, 503, 504]);
const MAX_PARTS_PER_REQUEST = 100;
const MAX_UPLOAD_ROUNDS = 6;
/** 422 on create for a marker whose policy is off (`folder`, `touched`). */
export const ARCHIVE_MARKER_NOT_ALLOWED = "archive_marker_not_allowed";
/** Create conflicts that end the session's chain (section 7.9). */
const CHAIN_ENDING_CODES = new Set(["archive_id_conflict", "archive_sequence_conflict", "archive_parent_mismatch", "archive_deleted"]);

/**
 * The omnirush.ai API root derived from the gateway URL exactly like the
 * session upload URL: trailing `/` and `/v1` stripped; HTTPS unless loopback.
 */
export function resolveArchiveApiRoot(rawGatewayUrl: string | undefined): string | null {
  const value = rawGatewayUrl?.trim();
  if (!value) return null;
  // A release build sends to omnirush.ai only (release-guard.ts).
  if (!gatewayUrlAllowed(value)) return null;
  try {
    const url = new URL(value);
    if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]", "::1"].includes(url.hostname))) return null;
    url.pathname = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "");
    url.search = "";
    url.hash = "";
    return url.toString().replace(/\/+$/, "");
  } catch {
    return null;
  }
}

export type ArchiveCreateRequest<Content extends SealContent = "tar+zstd"> = {
  archive_id: string;
  session_id: string;
  kind: "base" | "delta";
  sequence: number;
  turn: number;
  parent_archive_id: string | null;
  size: number;
  sha256: string;
  kid: string;
  content: Content;
  marker: string;
  /** Native harness evidence uses the same sealed multipart archive protocol. */
  payload?: "project" | "claude_native" | "claude_checkpoint";
  harness?: "claude-code";
  engine_version?: string;
  binding_id?: string;
  contract_hash?: string;
  plain_sha256?: string;
  plain_size?: number;
  manifest_sha256?: string;
  box_image?: string;
  /** Bytes of the `__media__/` files in this archive (media-store.ts): the server counts them apart from the project's. */
  media_bytes?: number;
};

export type ArchiveUploadState = {
  upload_id: string;
  object_key: string;
  part_size: number;
  part_count: number;
  /** part number -> ETag exactly as S3 returned it (quotes included). */
  etags: Record<string, string>;
};

/** What the uploader needs from a queued job; it mutates `upload` and `recreates` and persists through the callback. */
export type ArchiveUploadJob = {
  request: ArchiveCreateRequest<SealContent>;
  sealedPath: string;
  upload: ArchiveUploadState | null;
  recreates: number;
};

export type ArchiveKey = { kid: string; publicKey: Buffer; alg: string };

export type KeyResult =
  /** The policy comes with the key, in the same response. */
  | { status: "ok"; key: ArchiveKey; policy: ArchivePolicy }
  | { status: "disabled"; code: string }
  | { status: "unavailable"; reason: string };

export type UploadOutcome =
  | { status: "uploaded" }
  /** 428 / 503 archive_disabled: archiving is off for the user, without error. */
  | { status: "disabled"; code: string }
  /** 401 after a refresh, or 403: stop draining and keep the queue. */
  | { status: "blocked"; reason: string }
  /** A chain-ending conflict, 413 or 422 (archive_marker_not_allowed, else archive_request_invalid): drop the session's jobs and stop archiving it. */
  | { status: "stop_session"; code: string }
  /** 409 archive_kid_unknown: the archive was sealed to a key the server no longer has. */
  | { status: "rekey"; code: string }
  /** Transient failure after the retries: leave the job to a later drain. */
  | { status: "retry_later"; reason: string }
  | { status: "aborted" };

/** Where the server's archive chain of a session goes on (GET /me/sessions/{id}/integrity, `archive.chain`). */
export type ServerChainTip = { archiveId: string; sequence: number; turn: number; kind: string; marker: string | null; status: string; deleted: boolean };
export type ServerChain =
  | { status: "ok"; nextSequence: number; tip: ServerChainTip | null }
  /** A server that does not say where the chain is (no `archive.chain`): nothing can be continued. */
  | { status: "unsupported" }
  | { status: "unavailable"; reason: string };

const chainSchema = z.object({
  archive: z.object({
    chain: z.object({
      next_sequence: z.number().int().nonnegative(),
      tip: z.object({
        archive_id: z.string().regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/),
        sequence: z.number().int().nonnegative(),
        turn: z.number().int().nonnegative(),
        kind: z.string(),
        marker: z.string().nullable(),
        status: z.string(),
        deleted: z.boolean(),
      }).nullable(),
    }),
  }),
});

const keySchema = z.object({ kid: z.string().regex(/^[0-9a-f]{16}$/), public_key: z.string(), alg: z.string() });
const partUrlSchema = z.object({ part_number: z.number().int().min(1), url: z.string().min(1) });
const createSchema = z.object({
  archive_id: z.string(),
  status: z.string(),
  upload_id: z.string().nullish(),
  object_key: z.string().nullish(),
  part_size: z.number().int().positive().nullish(),
  part_count: z.number().int().positive().nullish(),
  parts: z.array(partUrlSchema).nullish(),
});
const partsSchema = z.object({
  parts: z.array(partUrlSchema),
  uploaded: z.array(z.object({ part_number: z.number().int().min(1), etag: z.string().min(1), size: z.number().int().nonnegative() })).nullish(),
});

type ApiResult =
  | { kind: "ok"; status: number; body: unknown }
  | { kind: "error"; status: number; code: string | null }
  | { kind: "unavailable"; reason: string }
  | { kind: "aborted" };

async function errorCode(response: Response): Promise<string | null> {
  try {
    const body: unknown = await response.json();
    if (typeof body !== "object" || body === null) return null;
    if ("detail" in body && typeof body.detail === "string") return body.detail;
    if ("error" in body && typeof body.error === "string") return body.error;
  } catch {
    // Not JSON: the status alone decides.
  }
  return null;
}

function timeoutSignal(ms: number, signal?: AbortSignal): AbortSignal {
  const timeout = AbortSignal.timeout(ms);
  return signal ? AbortSignal.any([signal, timeout]) : timeout;
}

export type ArchiveUploaderOptions = {
  gatewayUrl?: string;
  accessToken?: string;
  refreshAccessToken?: () => Promise<string | null>;
  /** External egress (S3 PUTs, and API calls without `request`). */
  fetch: ArchiveFetch;
  request?: ArchiveApiRequest;
  retry?: Partial<RetryPolicy>;
  log?: ArchiveLog;
};

type PartsResult = { urls: Map<number, string>; uploaded: Array<{ part_number: number; etag: string; size: number }> };

/**
 * One part of the sealed file, read into a single buffer (null once `signal`
 * aborted: nothing more is read). A single-chunk body gets a Content-Length
 * from every fetch and is copied once by Electron's net.fetch, which collects
 * a streamed body with one Buffer.concat per chunk before sending it; a 64 MiB
 * part streamed in 64 KiB Blob chunks costs seconds of main-process copying.
 */
async function readPart(file: FileHandle, start: number, length: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer> | null> {
  const bytes = new Uint8Array(new ArrayBuffer(length));
  let offset = 0;
  while (offset < length) {
    if (signal?.aborted) return null;
    const { bytesRead } = await file.read(bytes, offset, Math.min(PART_READ_SLICE_BYTES, length - offset), start + offset);
    if (bytesRead === 0) throw new Error("archive file ended early");
    offset += bytesRead;
  }
  return signal?.aborted ? null : bytes;
}

export class ArchiveUploader {
  private token: string | null;
  private readonly apiRoot: string | null;
  private readonly retry: RetryPolicy;
  private readonly log: ArchiveLog;

  constructor(private readonly options: ArchiveUploaderOptions) {
    this.token = options.accessToken?.trim() || null;
    this.apiRoot = resolveArchiveApiRoot(options.gatewayUrl);
    this.retry = { ...DEFAULT_RETRY_POLICY, ...options.retry };
    this.log = options.log ?? (() => undefined);
  }

  /** Whether the API can be reached at all: a request hook, or a gateway URL plus a bearer. */
  get configured(): boolean {
    return Boolean(this.options.request) || (this.apiRoot !== null && this.token !== null);
  }

  setAccessToken(token: string | null): void {
    this.token = token?.trim() || null;
  }

  private send(method: "GET" | "POST", path: string, body: unknown, signal?: AbortSignal, probe = false): Promise<Response> {
    const payload = body === undefined ? undefined : JSON.stringify(body);
    const timeout = timeoutSignal(probe ? POLICY_PROBE_TIMEOUT_MS : REQUEST_TIMEOUT_MS, signal);
    if (this.options.request) return this.options.request(path, { method, ...(payload === undefined ? {} : { body: payload }), signal: timeout, ...(probe ? { refresh: false as const } : {}) });
    if (!this.apiRoot || !this.token) return Promise.reject(new Error("archive API not configured"));
    return this.options.fetch(`${this.apiRoot}/${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${this.token}`,
        Accept: "application/json",
        ...(payload === undefined ? {} : { "Content-Type": "application/json" }),
      },
      ...(payload === undefined ? {} : { body: payload }),
      signal: timeout,
    });
  }

  private async refresh(): Promise<boolean> {
    if (!this.options.refreshAccessToken) return false;
    try {
      const token = (await this.options.refreshAccessToken())?.trim() ?? "";
      if (!token) return false;
      this.token = token;
      return true;
    } catch {
      return false;
    }
  }

  /** One API call: 401 refreshes the bearer once; network errors and retryable statuses back off. */
  private async call(method: "GET" | "POST", path: string, body: unknown, signal?: AbortSignal): Promise<ApiResult> {
    let refreshed = false;
    let attempt = 0;
    for (;;) {
      if (signal?.aborted) return { kind: "aborted" };
      let response: Response;
      let failure: string;
      try {
        response = await this.send(method, path, body, signal);
        if (response.ok) {
          const parsed: unknown = await response.json().catch(() => null);
          return { kind: "ok", status: response.status, body: parsed };
        }
        const code = await errorCode(response);
        if (response.status === 401 && !refreshed) {
          refreshed = true;
          if (await this.refresh()) continue;
        }
        const retryable = retryableApiStatus(response);
        if (!retryable.retry || (response.status === 503 && code === "archive_disabled")) {
          return { kind: "error", status: response.status, code };
        }
        failure = `status ${response.status}`;
        // The job waits in the queue for a later drain (or the next start).
        if (!retryable.soon) return { kind: "unavailable", reason: failure };
      } catch (error) {
        if (signal?.aborted) return { kind: "aborted" };
        failure = error instanceof Error ? error.name : "network error";
      }
      attempt += 1;
      if (attempt >= this.retry.attempts) return { kind: "unavailable", reason: failure };
      await this.retry.sleep(backoffMs(this.retry, attempt), signal);
    }
  }

  /** The outcome for failures every route shares (7.1, 7.9); null when the caller decides. */
  private common(result: ApiResult): UploadOutcome | null {
    if (result.kind === "aborted") return { status: "aborted" };
    if (result.kind === "unavailable") return { status: "retry_later", reason: result.reason };
    if (result.kind === "ok") return null;
    if (result.status === 401) return { status: "blocked", reason: "unauthorized" };
    if (result.status === 403) return { status: "blocked", reason: result.code ?? "forbidden" };
    if (result.status === 409 && result.code === "archive_payload_disabled") return { status: "disabled", code: result.code };
    if (result.status === 428) return { status: "disabled", code: result.code ?? "archive_consent_required" };
    if (result.status === 503) return { status: "disabled", code: result.code ?? "archive_disabled" };
    if (result.status === 413) return { status: "stop_session", code: result.code ?? "archive_too_large" };
    // The server does not take this marker (a folder policy that is off): the chain goes, with no retry.
    if (result.status === 422) return { status: "stop_session", code: result.code === ARCHIVE_MARKER_NOT_ALLOWED ? result.code : "archive_request_invalid" };
    return null;
  }

  /** One GET with a single attempt: no bearer refresh on a 401, no backoff; a retryable failure is `unavailable`. */
  private async getOnce(path: string, signal?: AbortSignal): Promise<ApiResult> {
    if (signal?.aborted) return { kind: "aborted" };
    try {
      const response = await this.send("GET", path, undefined, signal, true);
      if (response.ok) return { kind: "ok", status: response.status, body: await response.json().catch(() => null) };
      const code = await errorCode(response);
      if (!retryableApiStatus(response).retry || (response.status === 503 && code === "archive_disabled")) return { kind: "error", status: response.status, code };
      return { kind: "unavailable", reason: `status ${response.status}` };
    } catch (error) {
      if (signal?.aborted) return { kind: "aborted" };
      return { kind: "unavailable", reason: error instanceof Error ? error.name : "network error" };
    }
  }

  /** GET /archives/key (7.2). 428, 503 and a server without the route all mean archiving is off. */
  async fetchKey(signal?: AbortSignal): Promise<KeyResult> {
    if (!this.configured) return { status: "disabled", code: "not_configured" };
    return this.keyResult(await this.call("GET", "archives/key", undefined, signal));
  }

  /**
   * GET /archives/key as the all-folders policy probe (4.4): one attempt
   * within POLICY_PROBE_TIMEOUT_MS, no backoff, and a 401 is not answered
   * with a bearer refresh. The caller counts anything but `ok` with
   * `policy.allFolders` as the policy off.
   */
  async probeKey(signal?: AbortSignal): Promise<KeyResult> {
    if (!this.configured) return { status: "disabled", code: "not_configured" };
    return this.keyResult(await this.getOnce("archives/key", signal));
  }

  private keyResult(result: ApiResult): KeyResult {
    if (result.kind === "ok") {
      const parsed = keySchema.safeParse(result.body);
      if (!parsed.success) return { status: "unavailable", reason: "invalid key response" };
      const publicKey = Buffer.from(parsed.data.public_key, "base64");
      if (publicKey.length !== 32 || publicKey.toString("base64") !== parsed.data.public_key || sealKid(publicKey) !== parsed.data.kid || parsed.data.alg !== SEAL_ALG) {
        return { status: "unavailable", reason: "invalid key response" };
      }
      return { status: "ok", key: { kid: parsed.data.kid, publicKey, alg: parsed.data.alg }, policy: parseArchivePolicy(result.body) };
    }
    if (result.kind === "error" && result.status === 404) return { status: "disabled", code: "archive_routes_missing" };
    const outcome = this.common(result);
    if (outcome?.status === "disabled") return { status: "disabled", code: outcome.code };
    if (result.kind === "error") return { status: "unavailable", reason: `status ${result.status}` };
    return { status: "unavailable", reason: result.kind === "unavailable" ? result.reason : result.kind };
  }

  /**
   * Where the server's chain of a session goes on: its next sequence and the
   * archive below it (GET /me/sessions/{id}/integrity?summary=1, `archive.chain`).
   * For a client that lost its own record of the chain (a sign-out, a
   * reinstall, another machine), whose base would end in 409
   * archive_sequence_conflict.
   */
  async serverChain(sessionId: string, signal?: AbortSignal): Promise<ServerChain> {
    if (!this.configured) return { status: "unavailable", reason: "not_configured" };
    const result = await this.call("GET", `me/sessions/${encodeURIComponent(sessionId)}/integrity?summary=1`, undefined, signal);
    if (result.kind === "ok") {
      const parsed = chainSchema.safeParse(result.body);
      if (!parsed.success) return { status: "unsupported" };
      const { next_sequence: nextSequence, tip } = parsed.data.archive.chain;
      return {
        status: "ok",
        nextSequence,
        tip: tip ? { archiveId: tip.archive_id, sequence: tip.sequence, turn: tip.turn, kind: tip.kind, marker: tip.marker, status: tip.status, deleted: tip.deleted } : null,
      };
    }
    if (result.kind === "error" && (result.status === 404 || result.status === 405)) return { status: "unsupported" };
    if (result.kind === "error") return { status: "unavailable", reason: `status ${result.status}` };
    return { status: "unavailable", reason: result.kind === "unavailable" ? result.reason : result.kind };
  }

  /** Best-effort POST /archives/{id}/abort (7.7); one attempt, result ignored. */
  async abort(archiveId: string, signal?: AbortSignal): Promise<void> {
    try {
      const response = await this.send("POST", `archives/${archiveId}/abort`, {}, signal);
      await response.body?.cancel().catch(() => undefined);
    } catch {
      // The server's stale-upload maintenance aborts it within a day.
    }
  }

  private async create(job: ArchiveUploadJob, signal?: AbortSignal): Promise<UploadOutcome | { uploaded: true } | { upload: ArchiveUploadState; urls: Map<number, string> }> {
    const result = await this.call("POST", "archives", job.request, signal);
    if (result.kind === "ok") {
      const parsed = createSchema.safeParse(result.body);
      if (!parsed.success || parsed.data.archive_id !== job.request.archive_id) return { status: "retry_later", reason: "invalid create response" };
      if (parsed.data.status === "uploaded") return { uploaded: true };
      const { upload_id: uploadId, object_key: objectKey, part_size: partSize, part_count: partCount } = parsed.data;
      if (!uploadId || !objectKey || !partSize || !partCount || partCount !== Math.ceil(job.request.size / partSize)) {
        return { status: "retry_later", reason: "invalid create response" };
      }
      const urls = new Map((parsed.data.parts ?? []).map((part) => [part.part_number, part.url]));
      return { upload: { upload_id: uploadId, object_key: objectKey, part_size: partSize, part_count: partCount, etags: {} }, urls };
    }
    const outcome = this.common(result);
    if (outcome) return outcome;
    if (result.kind !== "error") return { status: "retry_later", reason: "create failed" };
    if (result.status === 409 && result.code === "archive_kid_unknown") return { status: "rekey", code: result.code };
    if (result.status === 409 && result.code && CHAIN_ENDING_CODES.has(result.code)) return { status: "stop_session", code: result.code };
    return { status: "retry_later", reason: `create status ${result.status}` };
  }

  private async listParts(job: ArchiveUploadJob, partNumbers: number[], signal?: AbortSignal): Promise<UploadOutcome | "recreate" | PartsResult> {
    const result = await this.call("POST", `archives/${job.request.archive_id}/parts`, { part_numbers: partNumbers }, signal);
    if (result.kind === "ok") {
      const parsed = partsSchema.safeParse(result.body);
      if (!parsed.success) return { status: "retry_later", reason: "invalid parts response" };
      return { urls: new Map(parsed.data.parts.map((part) => [part.part_number, part.url])), uploaded: parsed.data.uploaded ?? [] };
    }
    const outcome = this.common(result);
    if (outcome) return outcome;
    if (result.kind === "error" && (result.status === 404 || (result.status === 409 && result.code === "archive_not_uploading"))) return "recreate";
    return { status: "retry_later", reason: result.kind === "error" ? `parts status ${result.status}` : "parts failed" };
  }

  private async complete(job: ArchiveUploadJob, upload: ArchiveUploadState, signal?: AbortSignal): Promise<UploadOutcome | "recreate" | "relist" | { reupload: string }> {
    const parts = Array.from({ length: upload.part_count }, (_, index) => ({ part_number: index + 1, etag: upload.etags[String(index + 1)] ?? "" }));
    const result = await this.call("POST", `archives/${job.request.archive_id}/complete`, { parts }, signal);
    if (result.kind === "ok") {
      if (job.request.payload === "claude_native" || job.request.payload === "claude_checkpoint") {
        const receipt = z.object({archive_id: z.string(), status: z.literal("uploaded"), size: z.number().int().positive()}).safeParse(result.body);
        if (!receipt.success || receipt.data.archive_id !== job.request.archive_id || receipt.data.size !== job.request.size) return { status: "retry_later", reason: "invalid completion receipt" };
      }
      return { status: "uploaded" };
    }
    const outcome = this.common(result);
    if (outcome) return outcome;
    if (result.kind === "error") {
      if (result.status === 404 || (result.status === 409 && result.code === "archive_not_uploading")) return "recreate";
      if (result.status === 409 && result.code === "archive_parts_invalid") return "relist";
      if (result.status === 409 && (result.code === "archive_size_mismatch" || result.code === "archive_seal_invalid")) return { reupload: result.code };
      return { status: "retry_later", reason: `complete status ${result.status}` };
    }
    return { status: "retry_later", reason: "complete failed" };
  }

  /** PUT one part to its presigned URL; an abort of `signal` cancels the request at once. */
  private async putPart(url: string, body: Uint8Array<ArrayBuffer>, signal?: AbortSignal): Promise<{ etag: string } | "forbidden" | "gone" | { failed: string }> {
    let attempt = 0;
    for (;;) {
      if (signal?.aborted) return { failed: "aborted" };
      let failure: string;
      try {
        const timeout = Math.max(PART_MIN_TIMEOUT_MS, Math.ceil(body.byteLength / PART_MIN_BYTES_PER_MS));
        const response = await this.options.fetch(url, { method: "PUT", body, signal: timeoutSignal(timeout, signal) });
        await response.body?.cancel().catch(() => undefined);
        if (response.ok) {
          const etag = response.headers.get("etag");
          if (etag) return { etag };
          failure = "missing etag";
        } else if (response.status === 403) {
          return "forbidden";
        } else if (response.status === 404) {
          return "gone";
        } else if (!PART_RETRYABLE_STATUSES.has(response.status)) {
          return { failed: `part status ${response.status}` };
        } else {
          failure = `part status ${response.status}`;
        }
      } catch (error) {
        if (signal?.aborted) return { failed: "aborted" };
        failure = error instanceof Error ? error.name : "network error";
      }
      attempt += 1;
      if (attempt >= this.retry.attempts) return { failed: failure };
      await this.retry.sleep(backoffMs(this.retry, attempt), signal);
    }
  }

  /** PUTs every part S3 does not hold yet; "recreate" when the multipart upload is gone. */
  private async putMissingParts(
    job: ArchiveUploadJob,
    upload: ArchiveUploadState,
    file: FileHandle,
    initialUrls: Map<number, string>,
    persist: () => Promise<void>,
    signal?: AbortSignal,
  ): Promise<UploadOutcome | "recreate" | "done"> {
    const urls = new Map(initialUrls);
    const size = job.request.size;
    const partBytes = (part: number) => Math.min(upload.part_size, size - (part - 1) * upload.part_size);
    const missing = () => {
      const parts: number[] = [];
      for (let part = 1; part <= upload.part_count; part += 1) if (!upload.etags[String(part)]) parts.push(part);
      return parts;
    };
    let forbiddenInRow = 0;
    for (;;) {
      if (signal?.aborted) return { status: "aborted" };
      const todo = missing();
      const part = todo[0];
      if (part === undefined) return "done";
      const url = urls.get(part);
      if (!url) {
        const listed = await this.listParts(job, todo.slice(0, MAX_PARTS_PER_REQUEST), signal);
        if (listed === "recreate" || "status" in listed) return listed;
        let learned = false;
        for (const held of listed.uploaded) {
          if (held.part_number <= upload.part_count && held.size === partBytes(held.part_number) && upload.etags[String(held.part_number)] !== held.etag) {
            upload.etags[String(held.part_number)] = held.etag;
            learned = true;
          }
        }
        if (learned) await persist();
        for (const [number, partUrl] of listed.urls) urls.set(number, partUrl);
        if (!urls.has(part) && !upload.etags[String(part)]) return { status: "retry_later", reason: "no part url" };
        continue;
      }
      let body: Uint8Array<ArrayBuffer> | null;
      try {
        body = await readPart(file, (part - 1) * upload.part_size, partBytes(part), signal);
      } catch (error) {
        // The next drain checks the file again (a truncated one stops the session).
        return { status: "retry_later", reason: `archive file read failed: ${error instanceof Error ? error.message : "unknown"}` };
      }
      if (!body) return { status: "aborted" };
      const result = await this.putPart(url, body, signal);
      if (result === "forbidden") {
        // An expired URL, or expired signing credentials: fetch fresh URLs and retry.
        forbiddenInRow += 1;
        if (forbiddenInRow > 2) return { status: "retry_later", reason: "part forbidden" };
        urls.clear();
        continue;
      }
      if (result === "gone") {
        // NoSuchUpload: /parts answers archive_not_uploading, then the upload is re-created.
        urls.clear();
        const listed = await this.listParts(job, [part], signal);
        if (listed === "recreate" || "status" in listed) return listed;
        for (const [number, partUrl] of listed.urls) urls.set(number, partUrl);
        forbiddenInRow += 1;
        if (forbiddenInRow > 2) return { status: "retry_later", reason: "part not found" };
        continue;
      }
      if ("failed" in result) {
        if (signal?.aborted) return { status: "aborted" };
        this.log("warn", "OmniRush archive part upload failed", { archiveId: job.request.archive_id, part, reason: result.failed });
        return { status: "retry_later", reason: result.failed };
      }
      forbiddenInRow = 0;
      upload.etags[String(part)] = result.etag;
      urls.delete(part);
      await persist();
    }
  }

  /**
   * Uploads one sealed archive: create (or resume), PUT the parts S3 lacks,
   * complete. Never throws; the job's upload state is persisted after every
   * part so a restart resumes where it stopped.
   */
  async upload(job: ArchiveUploadJob, persist: () => Promise<void>, signal?: AbortSignal): Promise<UploadOutcome> {
    if (signal?.aborted) return { status: "aborted" };
    let file: FileHandle;
    try {
      file = await open(job.sealedPath, "r");
    } catch {
      return { status: "stop_session", code: "archive_file_missing" };
    }
    try {
      if ((await file.stat()).size !== job.request.size) return { status: "stop_session", code: "archive_file_corrupt" };
      return await this.uploadFrom(file, job, persist, signal);
    } finally {
      await file.close().catch(() => undefined);
    }
  }

  private async uploadFrom(file: FileHandle, job: ArchiveUploadJob, persist: () => Promise<void>, signal?: AbortSignal): Promise<UploadOutcome> {
    for (let round = 0; round < MAX_UPLOAD_ROUNDS; round += 1) {
      if (signal?.aborted) return { status: "aborted" };
      let urls = new Map<number, string>();
      if (!job.upload) {
        const created = await this.create(job, signal);
        if ("status" in created) return created;
        if ("uploaded" in created) return { status: "uploaded" };
        job.upload = created.upload;
        urls = created.urls;
        await persist();
      }
      const upload = job.upload;
      const put = await this.putMissingParts(job, upload, file, urls, persist, signal);
      if (put === "recreate") {
        job.upload = null;
        await persist();
        continue;
      }
      if (put !== "done") return put;
      const completed = await this.complete(job, upload, signal);
      if (completed === "recreate") {
        job.upload = null;
        await persist();
        continue;
      }
      if (completed === "relist") {
        // Trust S3's own part list: /parts reports what it holds and the rest is sent again.
        upload.etags = {};
        await persist();
        continue;
      }
      if ("reupload" in completed) {
        if (job.recreates >= 1) return { status: "stop_session", code: completed.reupload };
        job.recreates += 1;
        job.upload = null;
        await persist();
        continue;
      }
      return completed;
    }
    return { status: "retry_later", reason: "upload rounds exhausted" };
  }
}