@pome-sh/cli 0.1.1 → 0.2.0

package/dist/src/hosted/client.js

@@ -1,8 +1,108 @@
 // SPDX-License-Identifier: Apache-2.0
 import { createEvalSessionResponseSchema, createSessionResponseSchema, finalizeResponseSchema, sessionPublicSchema, submitResultResponseSchema, } from "../types/shared.js";
+import { z } from "zod";
 import { HostedAuthError, HostedOrchError, HostedQuotaError, } from "./errors.js";
+// Multi-twin (M3): provenance marker for `per_twin`. A single-twin OLD cloud
+// ships NO `per_twin` key; `createSessionResponseSchema` then SYNTHESIZES one
+// (host-rewrites api.pome.sh→mcp.pome.sh with no `/mcp` suffix). Consumers that
+// build agent env from `per_twin[twin].mcp_url` must NOT trust that synthesized
+// value — it would drift POME_*_MCP_URL off origin/main's `${twin_url}/mcp`. We
+// record, on the parsed object as a NON-ENUMERABLE symbol (never serialized,
+// never spread), whether the raw wire body actually carried a `per_twin` key.
+const PER_TWIN_PROVENANCE = Symbol("pome.perTwinFromCloud");
+function markPerTwinProvenance(session, fromCloud) {
+    Object.defineProperty(session, PER_TWIN_PROVENANCE, {
+        value: fromCloud,
+        enumerable: false,
+        configurable: true,
+    });
+    return session;
+}
+/** True when the cloud's create-session body actually returned a `per_twin`
+ *  key (empty `{}` counts) — i.e. `per_twin` was NOT synthesized by the schema
+ *  from a legacy `twin_url`-only response. Consumers use this to decide whether
+ *  `per_twin[twin].mcp_url` is trustworthy. */
+export function perTwinReturnedByCloud(session) {
+    return (session[PER_TWIN_PROVENANCE] === true);
+}
+/** Whether a raw create-session wire body carried a usable `per_twin` map
+ *  (before schema synthesis). A `per_twin: null` counts as absent — the schema
+ *  would synthesize entries for it, and synthesized URLs must not be trusted.
+ *  Exported so the runner's env unit test can model the exact provenance the
+ *  client stamps. */
+export function rawBodyHadPerTwin(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return false;
+    const pt = raw.per_twin;
+    return typeof pt === "object" && pt !== null;
+}
+// Keep these readers wire-identical to the additive exports in
+// @pome-sh/shared-types 0.6.1. The CLI intentionally remains installable
+// against 0.6.0 until that package batch has published.
+// Scored finalize responses stay non-strict so additive M7 keys strip.
+const finalizeScoredResponseSchema = finalizeResponseSchema.strip();
+const finalizeStatusUrlSchema = z
+    .string()
+    .min(1)
+    .refine((value) => {
+    if (value.startsWith("/") && !value.startsWith("//"))
+        return true;
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "Invalid status_url" });
+const finalizeAcceptedResponseSchema = z.object({
+    evaluation_id: z.string().min(1),
+    run_id: z.string().min(1),
+    status: z.literal("queued"),
+    status_url: finalizeStatusUrlSchema,
+}).strict();
+const finalizeStatusIdentitySchema = {
+    evaluation_id: z.string().min(1),
+    run_id: z.string().min(1),
+};
+const finalizeFailureErrorSchema = z.object({
+    type: z.string().min(1),
+    message: z.string().min(1),
+    details: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+const finalizeStatusResponseSchema = z.discriminatedUnion("status", [
+    z.object({
+        ...finalizeStatusIdentitySchema,
+        status: z.literal("queued"),
+    }).strict(),
+    z.object({
+        ...finalizeStatusIdentitySchema,
+        status: z.literal("running"),
+    }).strict(),
+    z.object({
+        ...finalizeStatusIdentitySchema,
+        status: z.literal("failed"),
+        error: finalizeFailureErrorSchema,
+    }).strict(),
+    z.object({
+        ...finalizeStatusIdentitySchema,
+        status: z.literal("completed"),
+        result: finalizeScoredResponseSchema,
+    }).strict(),
+]);
+class RetryableFinalizeStatusError extends HostedOrchError {
+    retryAfterMs;
+    constructor(error, retryAfterMs) {
+        super(error.message, error.requestId, error.status);
+        this.retryAfterMs = retryAfterMs;
+        this.name = "RetryableFinalizeStatusError";
+    }
+}
 export function createHostedClient(config) {
     const timeoutMs = config.timeoutMs ?? 30_000;
+    const finalizeTimeoutMs = config.finalizeTimeoutMs ?? 5 * 60_000;
+    const finalizePollInitialDelayMs = Math.max(1, config.finalizePollInitialDelayMs ?? 500);
+    const finalizePollMaxDelayMs = Math.max(finalizePollInitialDelayMs, config.finalizePollMaxDelayMs ?? 5_000);
     const authHeaders = config.authScheme === "bearer"
         ? { authorization: `Bearer ${config.apiKey}` }
         : { "x-api-key": config.apiKey };
@@ -13,7 +113,7 @@ export function createHostedClient(config) {
             json = text.length ? JSON.parse(text) : {};
         }
         catch {
-            throw new HostedOrchError(`non-JSON response (status ${res.status})`);
+            throw new HostedOrchError(`non-JSON response (status ${res.status})`, undefined, res.status);
         }
         if (!res.ok) {
             // Cloud's REST envelope is `{ error: { type, message, request_id } }`.
@@ -33,37 +133,56 @@ export function createHostedClient(config) {
                 // labeled at-capacity state instead of a generic quota message.
                 throw new HostedQuotaError(msg, reqId, cloudDetails);
             }
-            throw new HostedOrchError(msg, reqId, res.status);
+            // Carry the envelope `error.type` (e.g. `multi_twin_unsupported`) so
+            // callers can map specific rejections to friendly hints.
+            throw new HostedOrchError(msg, reqId, res.status, cloudErr?.type);
         }
         try {
-            return parse(json);
+            return parse(json, res);
         }
         catch (err) {
-            throw new HostedOrchError(`unexpected response shape: ${err instanceof Error ? err.message : String(err)}`);
+            throw new HostedOrchError(`unexpected response shape: ${err instanceof Error ? err.message : String(err)}`, undefined, res.status);
         }
     }
-    async function postJson(path, body, parse) {
+    async function postJson(path, body, parse, options) {
         const ctrl = new AbortController();
-        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-        let res;
+        const timer = setTimeout(() => ctrl.abort(), options?.requestTimeoutMs ?? timeoutMs);
+        const abortFromCaller = () => ctrl.abort(options?.signal?.reason);
+        options?.signal?.addEventListener("abort", abortFromCaller, { once: true });
+        if (options?.signal?.aborted)
+            abortFromCaller();
         try {
-            res = await fetch(`${config.baseUrl}${path}`, {
+            const res = await fetch(`${config.baseUrl}${path}`, {
                 method: "POST",
                 headers: {
                     ...authHeaders,
                     "content-type": "application/json",
+                    ...options?.headers,
                 },
                 body: JSON.stringify(body),
                 signal: ctrl.signal,
             });
+            if (res.ok &&
+                options?.acceptedStatuses &&
+                !options.acceptedStatuses.includes(res.status)) {
+                throw new HostedOrchError(`unexpected HTTP status ${res.status}`, undefined, res.status);
+            }
+            // Keep the timeout and caller cancellation active while consuming the
+            // body. fetch() resolves after headers, before a streamed body finishes.
+            return await readResponse(res, parse);
         }
         catch (err) {
+            if (err instanceof HostedAuthError ||
+                err instanceof HostedQuotaError ||
+                err instanceof HostedOrchError) {
+                throw err;
+            }
             throw new HostedOrchError(err instanceof Error ? err.message : "network error");
         }
         finally {
             clearTimeout(timer);
+            options?.signal?.removeEventListener("abort", abortFromCaller);
         }
-        return readResponse(res, parse);
     }
     async function getJsonBearer(url, bearer, parse) {
         const ctrl = new AbortController();
@@ -103,6 +222,170 @@ export function createHostedClient(config) {
         }
         return readResponse(res, parse);
     }
+    function retryAfterMs(value) {
+        if (value === null)
+            return null;
+        const seconds = Number(value);
+        if (Number.isFinite(seconds) && seconds >= 0) {
+            return seconds * 1_000;
+        }
+        const at = Date.parse(value);
+        return Number.isNaN(at) ? null : Math.max(0, at - Date.now());
+    }
+    function nextFinalizePollDelayMs(currentDelayMs, serverDelayMs) {
+        if (serverDelayMs !== null) {
+            // Retry-After: 0 is legal, but accepting it literally on every response
+            // creates a hot authenticated loop. The configured initial delay is the
+            // lower bound for server hints.
+            return Math.max(serverDelayMs, finalizePollInitialDelayMs);
+        }
+        return Math.min(Math.max(currentDelayMs * 2, finalizePollInitialDelayMs), finalizePollMaxDelayMs);
+    }
+    async function sleepForPoll(ms, signal) {
+        if (signal?.aborted) {
+            throw new HostedOrchError("finalize aborted");
+        }
+        if (ms <= 0)
+            return;
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                reject(new HostedOrchError("finalize aborted"));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            // Re-check after subscribe — abort between the early check and
+            // addEventListener would otherwise hang until the delay elapses.
+            if (signal?.aborted)
+                onAbort();
+        });
+    }
+    function resolveFinalizeStatusUrl(statusUrl) {
+        const apiOrigin = new URL(config.baseUrl).origin;
+        let resolved;
+        try {
+            resolved = new URL(statusUrl, apiOrigin);
+        }
+        catch {
+            throw new HostedOrchError("finalize status_url is not a valid URL");
+        }
+        if (resolved.origin !== apiOrigin) {
+            throw new HostedOrchError("finalize status_url must use the configured API origin");
+        }
+        return resolved;
+    }
+    async function getFinalizeStatus(url, signal, requestTimeoutMs) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), requestTimeoutMs);
+        const abortFromCaller = () => ctrl.abort(signal?.reason);
+        signal?.addEventListener("abort", abortFromCaller, { once: true });
+        if (signal?.aborted)
+            abortFromCaller();
+        try {
+            const res = await fetch(url, {
+                method: "GET",
+                headers: authHeaders,
+                signal: ctrl.signal,
+                // Node fetch preserves custom x-api-key headers across a cross-origin
+                // redirect. Refuse redirects so same-origin validation remains true
+                // for the server that actually receives tenant credentials.
+                redirect: "manual",
+            });
+            if (res.status >= 300 && res.status < 400) {
+                throw new HostedOrchError("finalize status request must not redirect", undefined, res.status);
+            }
+            const delay = retryAfterMs(res.headers.get("retry-after"));
+            // Keep both timeout signals active until the full body is consumed.
+            let status;
+            try {
+                status = await readResponse(res, (raw) => finalizeStatusResponseSchema.parse(raw));
+            }
+            catch (err) {
+                if (err instanceof HostedOrchError &&
+                    err.status !== undefined &&
+                    err.status >= 500) {
+                    throw new RetryableFinalizeStatusError(err, delay);
+                }
+                throw err;
+            }
+            return { status, retryAfterMs: delay };
+        }
+        catch (err) {
+            if (signal?.aborted) {
+                throw new HostedOrchError("finalize aborted");
+            }
+            if (err instanceof HostedAuthError ||
+                err instanceof HostedQuotaError ||
+                err instanceof HostedOrchError) {
+                throw err;
+            }
+            throw new HostedOrchError(err instanceof Error ? err.message : "network error");
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abortFromCaller);
+        }
+    }
+    async function pollFinalize(accepted, deadline, signal) {
+        const statusUrl = resolveFinalizeStatusUrl(accepted.status_url);
+        let delayMs = finalizePollInitialDelayMs;
+        while (true) {
+            const remainingBeforeDelay = deadline - Date.now();
+            if (remainingBeforeDelay <= 0) {
+                throw new HostedOrchError("asynchronous finalize timed out");
+            }
+            await sleepForPoll(Math.min(delayMs, remainingBeforeDelay), signal);
+            const remainingBeforeRequest = deadline - Date.now();
+            if (remainingBeforeRequest <= 0) {
+                throw new HostedOrchError("asynchronous finalize timed out");
+            }
+            let polled;
+            try {
+                polled = await getFinalizeStatus(statusUrl, signal, Math.min(timeoutMs, remainingBeforeRequest));
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw err;
+                if (err instanceof HostedOrchError &&
+                    (err.status === undefined || err.status >= 500)) {
+                    // The evaluation is durable. A transient status transport failure
+                    // must not turn a still-running evaluation into a CLI failure.
+                    delayMs = nextFinalizePollDelayMs(delayMs, err instanceof RetryableFinalizeStatusError
+                        ? err.retryAfterMs
+                        : null);
+                    continue;
+                }
+                throw err;
+            }
+            if (polled.status.evaluation_id !== accepted.evaluation_id ||
+                polled.status.run_id !== accepted.run_id) {
+                throw new HostedOrchError("finalize status identifiers do not match the accepted evaluation");
+            }
+            if (polled.status.status === "completed") {
+                if (polled.status.result.run_id !== accepted.run_id) {
+                    throw new HostedOrchError("finalize result run_id does not match the accepted evaluation");
+                }
+                return polled.status.result;
+            }
+            if (polled.status.status === "failed") {
+                const { type, message, details } = polled.status.error;
+                if (type === "quota_exceeded") {
+                    throw new HostedQuotaError(message, undefined, details);
+                }
+                throw new HostedOrchError(`${type}: ${message}`);
+            }
+            delayMs = nextFinalizePollDelayMs(delayMs, polled.retryAfterMs);
+        }
+    }
     return {
         async createSession(input) {
             const body = {
@@ -121,7 +404,7 @@ export function createHostedClient(config) {
             if (input.groupId) {
                 body.group_id = input.groupId;
             }
-            return postJson("/v1/sessions", body, (raw) => createSessionResponseSchema.parse(raw));
+            return postJson("/v1/sessions", body, (raw) => markPerTwinProvenance(createSessionResponseSchema.parse(raw), rawBodyHadPerTwin(raw)));
         },
         async abandonSession(sessionId, input) {
             const body = {};
@@ -210,22 +493,39 @@ export function createHostedClient(config) {
                 throw new HostedOrchError("POST /v1/sessions/:id/meta-upload-url returned unexpected shape");
             });
         },
-        async requestStateUploadUrl(sessionId) {
-            return postJson(`/v1/sessions/${encodeURIComponent(sessionId)}/state-upload-url`, {}, (raw) => {
+        async requestStateUploadUrl(sessionId, twins) {
+            // Multi-twin (M3): a `{ twins }` body asks the cloud to sign a per-twin
+            // pair for each twin (returned under `per_twin`). Single-twin callers
+            // pass nothing and the body stays `{}` — byte-identical to pre-M3.
+            const body = twins && twins.length > 0 ? { twins } : {};
+            return postJson(`/v1/sessions/${encodeURIComponent(sessionId)}/state-upload-url`, body, (raw) => {
                 const isEntry = (x) => typeof x === "object" &&
                     x !== null &&
                     typeof x.url === "string" &&
                     typeof x.key === "string";
-                if (typeof raw === "object" &&
-                    raw !== null &&
-                    isEntry(raw.state_initial) &&
-                    isEntry(raw.state_final)) {
-                    return raw;
+                const isPair = (x) => typeof x === "object" &&
+                    x !== null &&
+                    isEntry(x.state_initial) &&
+                    isEntry(x.state_final);
+                if (isPair(raw)) {
+                    // Validate `per_twin` when present; drop it silently if malformed
+                    // rather than failing the whole request (best-effort, like the
+                    // rest of the upload surface).
+                    const perTwinRaw = raw.per_twin;
+                    let perTwin;
+                    if (typeof perTwinRaw === "object" &&
+                        perTwinRaw !== null &&
+                        !Array.isArray(perTwinRaw) &&
+                        Object.values(perTwinRaw).every(isPair)) {
+                        perTwin = perTwinRaw;
+                    }
+                    return { ...raw, per_twin: perTwin };
                 }
                 throw new HostedOrchError("POST /v1/sessions/:id/state-upload-url returned unexpected shape");
             });
         },
-        async finalize(sessionId, input) {
+        async finalize(sessionId, input, options) {
+            const deadline = Date.now() + finalizeTimeoutMs;
             const body = {
                 stop_reason: input.stopReason,
                 exit_code: input.exitCode,
@@ -250,7 +550,21 @@ export function createHostedClient(config) {
             if (input.signalsStorageKey !== undefined) {
                 body.signals_storage_key = input.signalsStorageKey;
             }
-            return postJson(`/v1/sessions/${encodeURIComponent(sessionId)}/finalize`, body, (raw) => finalizeResponseSchema.parse(raw));
+            if (input.perTwinStateKeys !== undefined &&
+                Object.keys(input.perTwinStateKeys).length > 0) {
+                body.per_twin_state_keys = input.perTwinStateKeys;
+            }
+            const initial = await postJson(`/v1/sessions/${encodeURIComponent(sessionId)}/finalize`, body, (raw, response) => response.status === 202
+                ? finalizeAcceptedResponseSchema.parse(raw)
+                : finalizeScoredResponseSchema.parse(raw), {
+                headers: { prefer: "respond-async" },
+                signal: options?.signal,
+                acceptedStatuses: [200, 201, 202],
+                requestTimeoutMs: Math.min(timeoutMs, finalizeTimeoutMs),
+            });
+            return "status_url" in initial
+                ? pollFinalize(initial, deadline, options?.signal)
+                : initial;
         },
         async submitResult(sessionId, input) {
             return postJson(`/v1/sessions/${encodeURIComponent(sessionId)}/result`, {

package/dist/src/hosted/errors.d.ts

@@ -14,10 +14,20 @@ export declare class HostedQuotaError extends Error {
 export declare class HostedOrchError extends Error {
     readonly requestId?: string | undefined;
     readonly status?: number | undefined;
+    /** Machine-readable `error.type` from the cloud envelope, when present
+     *  (e.g. `multi_twin_unsupported` so the CLI can map an old-cloud
+     *  multi-twin rejection to a friendly hint). Undefined for
+     *  network/parse failures and the twin-pod 401 shape. */
+    readonly type?: string | undefined;
     /** `status` is the HTTP status that produced this error, when one exists
      *  (network/parse failures leave it undefined). `pome eval` uses it to
      *  scope its reaped-session retry to 404/410 only (FDRS-656 review). */
-    constructor(message: string, requestId?: string | undefined, status?: number | undefined);
+    constructor(message: string, requestId?: string | undefined, status?: number | undefined, 
+    /** Machine-readable `error.type` from the cloud envelope, when present
+     *  (e.g. `multi_twin_unsupported` so the CLI can map an old-cloud
+     *  multi-twin rejection to a friendly hint). Undefined for
+     *  network/parse failures and the twin-pod 401 shape. */
+    type?: string | undefined);
 }
 /** Bad invocation — missing scenario file, unknown flag value, etc. Maps
  *  to documented exit code 5 ("usage error"). F0-5a. */

package/dist/src/hosted/errors.js

@@ -49,13 +49,20 @@ export class HostedQuotaError extends Error {
 export class HostedOrchError extends Error {
     requestId;
     status;
+    type;
     /** `status` is the HTTP status that produced this error, when one exists
      *  (network/parse failures leave it undefined). `pome eval` uses it to
      *  scope its reaped-session retry to 404/410 only (FDRS-656 review). */
-    constructor(message, requestId, status) {
+    constructor(message, requestId, status, 
+    /** Machine-readable `error.type` from the cloud envelope, when present
+     *  (e.g. `multi_twin_unsupported` so the CLI can map an old-cloud
+     *  multi-twin rejection to a friendly hint). Undefined for
+     *  network/parse failures and the twin-pod 401 shape. */
+    type) {
         super(message);
         this.requestId = requestId;
         this.status = status;
+        this.type = type;
         this.name = "HostedOrchError";
     }
 }

package/dist/src/hosted/evalResultView.d.ts

@@ -33,6 +33,8 @@ export type ScoreStatus = "pass" | "fail" | "unevaluated";
 export declare function scoreStatus(score: Score, passThreshold: number): ScoreStatus;
 export declare function scenarioPassed(score: Score, passThreshold: number): boolean;
 export declare function markerFor(outcome: CriterionOutcome): string;
+export declare function criterionMarkerLabel(criterion: WireCriterion): string;
+export declare function twinSkipSuffix(result: CriterionResult): string;
 export declare function scoreCountsSummary(score: Score): string;
 export declare function runScoreLine(score: Score, passThreshold: number, unevaluatedNumericLabel: string): string;
 export {};

package/dist/src/hosted/evalResultView.js

@@ -52,6 +52,28 @@ export function markerFor(outcome) {
             return "-";
     }
 }
+// Multi-twin (M3): the per-criterion bracket for terminal display —
+// `[code]` / `[model]`, plus the `:<twin>` suffix when the criterion attributes
+// to a specific twin (so a `[D:slack]`/`[P:github]` marker survives into the
+// UNEVAL / criteria list). A bare (primary-twin) criterion renders `[code]`
+// unchanged.
+export function criterionMarkerLabel(criterion) {
+    return criterion.twin ? `[${criterion.type}:${criterion.twin}]` : `[${criterion.type}]`;
+}
+// Multi-twin (M3): when the cloud could not evaluate a criterion for a
+// twin-related reason (a twin-tagged criterion, or a `no_matching_predicate`
+// skip), name the twin inline so the UNEVAL line explains WHICH twin's timeline
+// came up empty. Returns "" when there's nothing twin-specific to add.
+export function twinSkipSuffix(result) {
+    const twin = result.criterion.twin;
+    if (!twin)
+        return "";
+    const outcome = outcomeOf(result);
+    const twinRelated = outcome === "skipped" ||
+        outcome === "errored" ||
+        /no_matching_predicate|no matching predicate/i.test(result.reason);
+    return twinRelated ? ` (twin: ${twin})` : "";
+}
 export function scoreCountsSummary(score) {
     return `${score.passed ?? 0} passed, ${score.failed ?? 0} failed, ${score.skipped ?? 0} skipped, ${score.errored ?? 0} errored`;
 }

package/dist/src/hosted/uploadAndFinalize.d.ts

@@ -1,5 +1,5 @@
 import type { HostedClient } from "./client.js";
-import type { FinalizeResponse } from "../types/shared.js";
+import type { FinalizeResponse, PerTwinStateKeys } from "../types/shared.js";
 import type { Score } from "./evalResultView.js";
 /** The narrow client surface the upload orchestration needs. `pome eval`
  *  mocks exactly this in tests instead of the full HostedClient. */
@@ -14,12 +14,29 @@ export interface RunBlobs {
     /** D18.1 — the run's meta.json (spec_version + twin_versions + the rest of
      *  writeRunArtifactsCore's payload), as written to / read from disk. */
     metaJson: string;
+    /** Multi-twin (M3): the session's twins. When >1, per-twin state upload URLs
+     *  are requested and each twin's state blobs are uploaded under its own
+     *  storage prefix. Absent / length ≤1 keeps the single-twin path unchanged. */
+    twins?: string[];
+    /** Multi-twin (M3): per-twin initial/final state JSON, keyed by twin id.
+     *  Includes the primary twin (whose blobs also go to the legacy top-level
+     *  pair). Only consumed when `twins.length > 1` and the cloud returns a
+     *  `per_twin` upload block. */
+    perTwinState?: Record<string, {
+        initialJson: string;
+        finalJson: string;
+    }>;
 }
 export interface UploadedBlobKeys {
     eventsKey: string | null;
     stateInitialKey: string | null;
     stateFinalKey: string | null;
     signalsKey: string | null;
+    /** Multi-twin (M3): per-twin state storage keys, keyed by twin id. Each entry
+     *  carries at least one uploaded key (empty entries are dropped so the
+     *  finalize contract's ">=1 key per entry" invariant holds). Undefined when
+     *  the session is single-twin or the cloud returned no `per_twin` block. */
+    perTwinStateKeys?: PerTwinStateKeys;
     /** D18.1 — the storage key the presigned PUT landed at, or null whenever
      *  the upload didn't happen, INCLUDING the feature-detection case (older
      *  control plane 404s meta-upload-url). Never distinguished from any other

package/dist/src/hosted/uploadAndFinalize.js

@@ -6,16 +6,29 @@
 // without duplicating them. Behavior-preserving for the hosted run path:
 // warning text, the 30s PUT timeout, and the null-key fallbacks all match
 // the pre-extraction runner.
+import { gzipSync } from "node:zlib";
 import { outcomeOf } from "./evalResultView.js";
 import { redactSecrets } from "../recorder/redaction.js";
+// Gzip EVERY blob before PUT. The storage edge (Cloudflare in front of
+// Supabase) runs a WAF managed rule that 403-blocks any PUT whose plaintext
+// body contains certain literal keys (e.g. an admin-flag key present in slack
+// twin state exports), which silently drops per-twin state uploads and makes
+// their criteria skip as state_missing. Gzipped bodies sail past the rule.
+// One code path here so every caller (events, per-twin state, signals,
+// meta.json) inherits it; the cloud's blob readers transparently gunzip via
+// the content-encoding header (shipped in the paired reader release before
+// this CLI change is released).
 async function putBlob(url, body, contentType, label) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), 30_000);
     try {
         const putRes = await fetch(url, {
             method: "PUT",
-            headers: { "content-type": contentType },
-            body,
+            headers: {
+                "content-type": contentType,
+                "content-encoding": "gzip",
+            },
+            body: gzipSync(Buffer.from(body, "utf8")),
             signal: ctrl.signal,
         });
         if (!putRes.ok) {
@@ -72,15 +85,49 @@ export async function uploadRunBlobs(client, sessionId, blobs) {
         }
     }
     async function uploadStates() {
+        const multiTwin = (blobs.twins?.length ?? 0) > 1;
         try {
-            const upload = await client.requestStateUploadUrl(sessionId);
+            // Multi-twin (M3): ask for a per-twin URL block; single-twin passes
+            // nothing so the request body stays `{}` (byte-identical to pre-M3).
+            const upload = await client.requestStateUploadUrl(sessionId, multiTwin ? blobs.twins : undefined);
+            // Top-level (primary-twin) pair — always uploaded, legacy state_*_storage_key.
             const [initialOk, finalOk] = await Promise.all([
                 putBlob(upload.state_initial.url, blobs.stateInitialJson, "application/json", "state_initial.json"),
                 putBlob(upload.state_final.url, blobs.stateFinalJson, "application/json", "state_final.json"),
             ]);
+            // Multi-twin: upload each twin's blobs to its own storage prefix and
+            // collect the keys. Only when the cloud actually returned a `per_twin`
+            // block (an older cloud omits it → we fall back to the primary-only
+            // top-level keys, degrading gracefully). Entries with no uploaded key are
+            // dropped so the finalize contract's ">=1 key per entry" holds.
+            let perTwinStateKeys;
+            if (multiTwin && upload.per_twin) {
+                const collected = {};
+                for (const twin of blobs.twins ?? []) {
+                    const pair = upload.per_twin[twin];
+                    const state = blobs.perTwinState?.[twin];
+                    if (!pair || !state)
+                        continue;
+                    const [iOk, fOk] = await Promise.all([
+                        putBlob(pair.state_initial.url, state.initialJson, "application/json", `state_initial.${twin}.json`),
+                        putBlob(pair.state_final.url, state.finalJson, "application/json", `state_final.${twin}.json`),
+                    ]);
+                    const entry = {};
+                    if (iOk)
+                        entry.state_initial_key = pair.state_initial.key;
+                    if (fOk)
+                        entry.state_final_key = pair.state_final.key;
+                    if (entry.state_initial_key !== undefined || entry.state_final_key !== undefined) {
+                        collected[twin] = entry;
+                    }
+                }
+                if (Object.keys(collected).length > 0)
+                    perTwinStateKeys = collected;
+            }
             return {
                 initialKey: initialOk ? upload.state_initial.key : null,
                 finalKey: finalOk ? upload.state_final.key : null,
+                perTwinStateKeys,
             };
         }
         catch (err) {
@@ -124,6 +171,7 @@ export async function uploadRunBlobs(client, sessionId, blobs) {
         eventsKey,
         stateInitialKey: stateKeys.initialKey,
         stateFinalKey: stateKeys.finalKey,
+        perTwinStateKeys: stateKeys.perTwinStateKeys,
         metaKey,
         signalsKey,
     };