@pome-sh/cli 0.1.1 → 0.3.0

package/dist/src/runner/runScenarioHosted.js

@@ -8,10 +8,97 @@ import { toTwinHttpEvent, writeRunArtifactsCore } from "../recorder/artifacts.js
 import { VERDICT_ARTIFACT_VERSION, writeVerdictArtifact, } from "../hosted/evalResultCache.js";
 import { redactEvent, redactSecrets } from "../recorder/redaction.js";
 import { parseScenarioFile } from "../scenario/parseScenario.js";
-import { createHostedClient } from "../hosted/client.js";
+import { createHostedClient, perTwinReturnedByCloud, } from "../hosted/client.js";
+import { ensureMcpSuffix } from "../cli/session.js";
 import { redactJsonl, scoreFromFinalizeResponse, uploadRunBlobs, } from "../hosted/uploadAndFinalize.js";
 import { normalizeConfigAgentId, normalizeConfigAgentSdk, readProjectConfig, } from "../cli/project-config.js";
-import { HostedTrialError } from "../hosted/errors.js";
+import { HostedOrchError, HostedTrialError } from "../hosted/errors.js";
+/** Build the agent subprocess env for a hosted run.
+ *
+ * Two layers, in this order:
+ *
+ *  1. The LEGACY block (origin/main parity). Every hosted run — regardless of
+ *     which twins the session mounts — ALWAYS injected github + stripe vars
+ *     pointing at the primary/bare `twin_url`, plus POME_TWIN_BASE_URL and the
+ *     OTEL/task/run scaffolding. Byte-identical single-twin env is the bar, so
+ *     this block reproduces main's exact keys, values, AND insertion order.
+ *
+ *  2. The per-twin fan-out OVERLAY (M3). For each twin actually in the session,
+ *     set POME_<T>_REST_URL / POME_<T>_MCP_URL from `per_twin[T]` (distinct URLs
+ *     per twin) plus its provider bearer. For github/stripe this overwrites the
+ *     legacy values IN PLACE (same key → insertion order preserved); other twins
+ *     append new keys.
+ *
+ * MCP URL rule (regression guard): only trust `per_twin[T].mcp_url` when the
+ * cloud ACTUALLY RETURNED `per_twin` (`perTwinFromCloud`). A single-twin OLD
+ * cloud returns no `per_twin`; the schema synthesizes one whose `mcp_url`
+ * host-rewrites api.pome.sh→mcp.pome.sh with NO `/mcp` suffix. Trusting it would
+ * drift POME_*_MCP_URL off main's `${twin_url}/mcp`. So for a synthesized entry
+ * we construct `${api_url}/mcp`; only a cloud-returned value gets ensureMcpSuffix
+ * (the same normalization `pome session create` applies). */
+export function buildAgentEnv(params) {
+    const { session, twins, perTwinFromCloud, prompt, otlpEndpoint, apiKey, agentId, runId, artifactsDir, slug, signalsPath, } = params;
+    const env = {
+        POME_TASK: prompt,
+        POME_TWIN_NAMES: twins.join(","),
+        POME_OTEL_EXPORTER_OTLP_ENDPOINT: otlpEndpoint,
+        POME_OTEL_EXPORTER_OTLP_HEADERS: `x-api-key=${apiKey}`,
+        OTEL_SERVICE_NAME: agentId ?? "pome-agent",
+        OTEL_RESOURCE_ATTRIBUTES: `pome.session_id=${session.session_id},pome.run_id=${runId}${agentId ? `,pome.agent_id=${agentId}` : ""}`,
+        // The twin base URL, same value the self-host docs teach agents to fall
+        // back on. Agent code written against the standalone docker twin
+        // reads POME_TWIN_BASE_URL with a 127.0.0.1:3333 fallback; without this
+        // injection that fallback fires on hosted runs and the agent probes a
+        // loopback port nothing listens on. Legacy = the primary twin's bare url.
+        POME_TWIN_BASE_URL: session.twin_url,
+        // Legacy unconditional block (origin/main parity). Injected on EVERY hosted
+        // run regardless of twin; the per-twin overlay below overwrites these in
+        // place for github/stripe when those twins are in the session.
+        POME_GITHUB_REST_URL: session.twin_url,
+        POME_GITHUB_MCP_URL: `${session.twin_url}/mcp`,
+        POME_GITHUB_TOKEN: session.provider_credentials.github?.token ?? session.agent_token,
+        POME_STRIPE_API_BASE: session.twin_url,
+        // Always use the JWT agent_token as the Stripe SDK's Bearer in hosted mode.
+        // The cloud also returns `provider_credentials.stripe.api_key` (an
+        // HMAC-signed `sk_test_pome_*`), but the pome-cloud proxy only accepts
+        // JWTs — it routes by verifying the bearer against `agent_token`. A
+        // stripe-style key short-circuits to the proxy's opaque 404 before the
+        // request reaches the twin pod. The Stripe SDK sends any opaque string as
+        // `Authorization: Bearer …`, and twin-stripe's dual-auth accepts JWTs
+        // natively, so the JWT round-trips cleanly end-to-end.
+        POME_STRIPE_API_KEY: session.agent_token,
+        POME_AUTH_TOKEN: session.agent_token,
+        POME_RUN_ID: runId,
+        POME_ARTIFACTS_DIR: join(artifactsDir, slug, runId),
+        POME_ADAPTER_SIGNALS_PATH: signalsPath,
+    };
+    for (const twin of twins) {
+        const upper = twin.toUpperCase();
+        const pt = session.per_twin?.[twin];
+        const apiUrl = pt?.api_url ?? session.twin_url;
+        const mcpUrl = perTwinFromCloud && pt?.mcp_url
+            ? ensureMcpSuffix(pt.mcp_url)
+            : `${apiUrl.replace(/\/$/, "")}/mcp`;
+        env[`POME_${upper}_REST_URL`] = apiUrl;
+        env[`POME_${upper}_MCP_URL`] = mcpUrl;
+        if (twin === "github") {
+            env.POME_GITHUB_TOKEN =
+                session.provider_credentials.github?.token ?? session.agent_token;
+        }
+        else if (twin === "stripe") {
+            env.POME_STRIPE_API_BASE = apiUrl;
+            env.POME_STRIPE_API_KEY = session.agent_token;
+        }
+        else if (twin === "slack") {
+            // Same rationale as the Stripe api-key line: the twin proxy verifies only
+            // the session JWT as bearer, so the agent's Slack bearer is the
+            // agent_token — NOT provider_credentials.slack.token, which the proxy
+            // would reject.
+            env.POME_SLACK_TOKEN = session.agent_token;
+        }
+    }
+    return env;
+}
 export async function runScenarioHosted(options) {
     const scenario = await parseScenarioFile(options.scenarioPath);
     const scenarioSource = await readFile(options.scenarioPath, "utf8");
@@ -47,22 +134,31 @@ export async function runScenarioHosted(options) {
     // precedence; see parseScenario.resolveSeedState) so the cloud doesn't need
     // to re-extract it from the markdown. Prose `## Seed State` sections have no
     // fenced JSON to extract — cloud would 422 with "no fenced code block".
-    const session = options.premintedSession ??
-        (await client.createSession({
-            scenarioSource,
-            twins: scenario.config.twins,
-            agentId,
-            seed: scenario.seedState,
-        }));
+    const session = await createSessionOrExplain(client, options.premintedSession, {
+        scenarioSource,
+        twins: scenario.config.twins,
+        agentId,
+        seed: scenario.seedState,
+    });
+    // Multi-twin (M3) locals. `twins[0]` is the primary twin: the source of the
+    // legacy top-level state blobs / URLs / criterion attribution.
+    const twins = scenario.config.twins;
+    const primaryTwin = twins[0];
+    const isMultiTwin = twins.length > 1;
+    // Each twin's own api base. Prefer the per-twin URL; fall back to the legacy
+    // bare `twin_url` (the primary) when the cloud didn't disambiguate per twin
+    // (older cloud, or the empty `per_twin` in tests). Keeps single-twin runs
+    // fetching from the same URL they always did.
+    const twinApiUrl = (twin) => session.per_twin?.[twin]?.api_url ?? session.twin_url;
     // Use session_id as the local artifact-dir id. The cloud's run_id (assigned
     // at /result time) is reported separately to the caller.
     const runId = session.session_id;
     try {
-        // 2. Capture initial twin state via bearer-protected /_pome/state.
-        const stateInitial = await client.fetchState({
-            twinUrl: session.twin_url,
-            agentToken: session.agent_token,
-        });
+        // 2. Capture initial twin state via bearer-protected /_pome/state — one
+        //    fetch per twin (each from its own api base). The primary twin's state
+        //    stays the legacy `stateInitial`.
+        const stateInitialByTwin = await fetchStateForTwins(client, twins, twinApiUrl, session.agent_token);
+        const stateInitial = stateInitialByTwin[primaryTwin];
         // Agent telemetry → pome-cloud. The agent runs as a LOCAL subprocess even on
         // hosted runs, and its LLM calls happen inside the SDK (they never traverse
         // pome's capture-server proxy), so the agent emits its OWN `gen_ai` OTLP
@@ -84,40 +180,21 @@ export async function runScenarioHosted(options) {
         const otlpEndpoint = process.env.POME_OTEL_COLLECTOR_URL?.trim() ||
             new URL(`/v1/sessions/${session.session_id}/traces`, options.hosted.baseUrl).toString();
         // 3. Run the agent. Env mirrors self-host so a customer's agent code
-        //    is twin-mode-agnostic.
-        const env = {
-            POME_TASK: scenario.prompt,
-            POME_TWIN_NAMES: scenario.config.twins.join(","),
-            POME_OTEL_EXPORTER_OTLP_ENDPOINT: otlpEndpoint,
-            POME_OTEL_EXPORTER_OTLP_HEADERS: `x-api-key=${options.hosted.apiKey}`,
-            OTEL_SERVICE_NAME: agentId ?? "pome-agent",
-            OTEL_RESOURCE_ATTRIBUTES: `pome.session_id=${session.session_id},pome.run_id=${runId}${agentId ? `,pome.agent_id=${agentId}` : ""}`,
-            // FDRS-667 — the twin base URL, same value the self-host docs teach
-            // agents to fall back on. Agent code written against the standalone
-            // docker twin reads POME_TWIN_BASE_URL with a 127.0.0.1:3333 fallback;
-            // without this injection that fallback fires on hosted runs and the
-            // agent probes a loopback port nothing listens on.
-            POME_TWIN_BASE_URL: session.twin_url,
-            POME_GITHUB_REST_URL: session.twin_url,
-            POME_GITHUB_MCP_URL: `${session.twin_url}/mcp`,
-            POME_GITHUB_TOKEN: session.provider_credentials.github?.token ?? session.agent_token,
-            POME_STRIPE_API_BASE: session.twin_url,
-            // Always use the JWT agent_token as the Stripe SDK's Bearer in
-            // hosted mode (FDRS-369). The cloud also returns
-            // `provider_credentials.stripe.api_key` (an HMAC-signed
-            // `sk_test_pome_*`), but the pome-cloud proxy at
-            // `/s/:sid/*` only accepts JWTs — it routes by verifying the
-            // bearer against `agent_token`. A stripe-style key short-circuits
-            // to the proxy's opaque 404 before the request ever reaches the
-            // twin pod. The Stripe SDK is happy to send any opaque string as
-            // `Authorization: Bearer …`, and twin-stripe's dual-auth accepts
-            // JWTs natively, so the JWT round-trips cleanly end-to-end.
-            POME_STRIPE_API_KEY: session.agent_token,
-            POME_AUTH_TOKEN: session.agent_token,
-            POME_RUN_ID: runId,
-            POME_ARTIFACTS_DIR: join(artifactsDir, scenario.slug, runId),
-            POME_ADAPTER_SIGNALS_PATH: signalsPath,
-        };
+        //    is twin-mode-agnostic. See `buildAgentEnv` for the origin/main legacy
+        //    block + per-twin fan-out overlay.
+        const env = buildAgentEnv({
+            session,
+            twins,
+            perTwinFromCloud: perTwinReturnedByCloud(session),
+            prompt: scenario.prompt,
+            otlpEndpoint,
+            apiKey: options.hosted.apiKey,
+            agentId,
+            runId,
+            artifactsDir,
+            slug: scenario.slug,
+            signalsPath,
+        });
         const preflightTimeoutSeconds = Math.min(10, scenario.config.timeout);
         const preflight = await runAgentCommand({
             command: options.agentCommand,
@@ -189,16 +266,34 @@ export async function runScenarioHosted(options) {
             await abandonBestEffort(client, session.session_id, failure.errorCode);
             throw new HostedTrialError(failure.reason, failure.errorCode);
         }
-        // 4. Capture final state + recorder events. Run in parallel for
-        //    latency. If either rejects (e.g., twin pod restarted between
-        //    preflight and now), the run fails before finalize fires —
-        //    the cloud has no record. Recovery is "user reruns"; V1 doesn't
-        //    retry transient twin failures.
-        const [stateFinal, eventsRaw] = await Promise.all([
-            client.fetchState({ twinUrl: session.twin_url, agentToken: session.agent_token }),
-            client.fetchEvents({ twinUrl: session.twin_url, agentToken: session.agent_token }),
-        ]);
-        const events = eventsRaw;
+        // 4. Capture final state + recorder events — one fetch per twin, all in
+        //    parallel for latency. If any rejects (e.g., a twin pod restarted
+        //    between preflight and now), the run fails before finalize fires — the
+        //    cloud has no record. Recovery is "user reruns"; V1 doesn't retry
+        //    transient twin failures. Events from every twin are merged into one
+        //    ts-ordered stream (each line already carries its twin id from the
+        //    recorder; we only stamp it when a line lacks one).
+        const stateFinalByTwin = {};
+        const eventsByTwin = {};
+        await Promise.all(twins.map(async (twin) => {
+            const [sf, ev] = await Promise.all([
+                client.fetchState({ twinUrl: twinApiUrl(twin), agentToken: session.agent_token }),
+                client.fetchEvents({ twinUrl: twinApiUrl(twin), agentToken: session.agent_token }),
+            ]);
+            stateFinalByTwin[twin] = sf;
+            // Single-twin keeps the twin's events byte-identical to origin/main —
+            // no `twin` field is stamped. Only the multi-twin merge needs each line
+            // tagged so the interleaved stream stays attributable.
+            eventsByTwin[twin] = isMultiTwin
+                ? ev.map((e) => tagEventTwin(e, twin))
+                : ev;
+        }));
+        const stateFinal = stateFinalByTwin[primaryTwin];
+        // Single-twin keeps the twin's own event order untouched (byte-identical);
+        // multi-twin interleaves all twins' events by timestamp.
+        const events = isMultiTwin
+            ? mergeEventsByTimestamp(twins.flatMap((t) => eventsByTwin[t] ?? []))
+            : eventsByTwin[primaryTwin] ?? [];
         // artifacts.ts still types `events` as the legacy twin/github RecorderEvent
         // (no step_id / tool_call_id / state_delta fields). Runtime data is the
         // same shape — cast to keep writeRunArtifactsCore happy without churning
@@ -225,6 +320,23 @@ export async function runScenarioHosted(options) {
             stateInitial,
             stateFinal,
         });
+        // Multi-twin (M3): writeRunArtifactsCore writes the primary twin's final
+        // state as the legacy `state_final.json`. Write each NON-primary twin's
+        // final state alongside it as `state_final.<twin>.json` so local inspection
+        // sees every twin's world. Best-effort — a disk failure here must not fail
+        // an otherwise-complete run.
+        if (isMultiTwin) {
+            for (const twin of twins) {
+                if (twin === primaryTwin)
+                    continue;
+                try {
+                    await writeFile(join(artifacts.runDir, `state_final.${twin}.json`), `${JSON.stringify(redactSecrets(stateFinalByTwin[twin]), null, 2)}\n`);
+                }
+                catch (err) {
+                    console.warn(`[pome] state_final.${twin}.json not written (${err instanceof Error ? err.message : String(err)})`);
+                }
+            }
+        }
         // 6. FDRS-657 — NO local correlation. Correlation (like scoring/judging)
         //    is a cloud responsibility; the OSS CLI only captures the raw trace.
         //    Cloud correlates the uploaded events/signals server-side. The events
@@ -267,12 +379,26 @@ export async function runScenarioHosted(options) {
         // run — meta.json is a best-effort sidecar, never load-bearing for the
         // score.
         const metaJson = await readFile(join(artifacts.runDir, "meta.json"), "utf8").catch(() => "{}");
+        // Multi-twin (M3): per-twin state blobs, keyed by twin id (includes the
+        // primary, whose blobs also land at the legacy top-level path). Undefined
+        // for single-twin, which keeps the flat state upload path unchanged.
+        const perTwinState = isMultiTwin
+            ? Object.fromEntries(twins.map((twin) => [
+                twin,
+                {
+                    initialJson: JSON.stringify(redactSecrets(stateInitialByTwin[twin])),
+                    finalJson: JSON.stringify(redactSecrets(stateFinalByTwin[twin])),
+                },
+            ]))
+            : undefined;
         const uploaded = await uploadRunBlobs(client, session.session_id, {
             eventsJsonl,
             stateInitialJson,
             stateFinalJson,
             signalsJsonl,
             metaJson,
+            twins: isMultiTwin ? twins : undefined,
+            perTwinState,
         });
         const eventsJsonlUrl = uploaded.eventsKey;
         const stateKeys = {
@@ -284,12 +410,17 @@ export async function runScenarioHosted(options) {
         //    storage, calls the managed judge via AI Gateway, persists the run
         //    row, and returns the authoritative score the dashboard records.
         //    The CLI prints this score on the `score:` line.
-        // `CriterionDef.kind` on the finalize request is still the legacy `D`/`P`
-        // wire vocabulary; map the canonical `code`/`model` kind back for the wire.
+        // The finalize wire carries the canonical `code`/`model` kinds (F-778;
+        // needs shared-types >= 0.10.0 cloud-side, whose tolerant reader also
+        // still accepts the legacy `D`/`P` spellings from older released CLIs).
+        // Multi-twin (M3): carry the per-criterion twin attribution so the cloud
+        // judge checks each criterion against its twin's state. Absent = the
+        // primary twin (single-twin scenarios omit it entirely).
         const criteriaDefs = scenario.criteria.map((c, idx) => ({
             id: `crit_${idx}`,
             text: c.text,
-            kind: c.type === "code" ? "D" : "P",
+            kind: c.type,
+            ...(c.twin ? { twin: c.twin } : {}),
         }));
         const stopReason = agentResult.timedOut
             ? "agent_timeout"
@@ -317,6 +448,10 @@ export async function runScenarioHosted(options) {
             stateInitialStorageKey: stateKeys.initialKey ?? undefined,
             stateFinalStorageKey: stateKeys.finalKey ?? undefined,
             signalsStorageKey: signalsKey ?? undefined,
+            // Multi-twin (M3): per-twin state storage keys (>=1 key per entry).
+            // Undefined for single-twin / an older cloud that returned no per_twin
+            // upload block — the cloud then scores the primary twin from the flat keys.
+            perTwinStateKeys: uploaded.perTwinStateKeys,
         });
         // 9. Synthesize the cloud verdict for terminal display + the exit code.
         //    FDRS-657: the CLI never computes a verdict — this is the CLOUD's,
@@ -401,6 +536,71 @@ export async function runScenarioHosted(options) {
         await rm(signalsDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
+/** Mint the session unless one was pre-minted, mapping an old-cloud multi-twin
+ *  rejection (422 `multi_twin_unsupported`) to a friendly hint. Every other
+ *  error propagates unchanged so the existing auth/quota/orch mapping stands. */
+async function createSessionOrExplain(client, preminted, input) {
+    if (preminted)
+        return preminted;
+    try {
+        return await client.createSession(input);
+    }
+    catch (err) {
+        if (err instanceof HostedOrchError &&
+            err.status === 422 &&
+            (err.type === "multi_twin_unsupported" ||
+                /multi_twin_unsupported/i.test(err.message))) {
+            throw new HostedOrchError("this pome cloud does not support multi-twin sessions yet", err.requestId, err.status, err.type);
+        }
+        throw err;
+    }
+}
+/** Fetch `/_pome/state` for every twin (each from its own api base), keyed by
+ *  twin id. */
+async function fetchStateForTwins(client, twins, twinApiUrl, agentToken) {
+    const byTwin = {};
+    await Promise.all(twins.map(async (twin) => {
+        byTwin[twin] = await client.fetchState({
+            twinUrl: twinApiUrl(twin),
+            agentToken,
+        });
+    }));
+    return byTwin;
+}
+/** Stamp a recorder event with its twin id ONLY when the line doesn't already
+ *  carry one (the twin recorders set `twin` themselves; this is the merge-time
+ *  backfill for any that don't). Returns the input untouched when it already
+ *  carries a non-empty twin. */
+function tagEventTwin(event, twin) {
+    if (event && typeof event === "object") {
+        const existing = event.twin;
+        if (existing === undefined || existing === null || existing === "") {
+            return { ...event, twin };
+        }
+    }
+    return event;
+}
+/** Merge multiple twins' event streams into one timestamp-ordered stream.
+ *  Stable: events with equal (or unparseable) `ts` keep their concatenation
+ *  order, so per-twin ordering is preserved within a timestamp. */
+function mergeEventsByTimestamp(events) {
+    const tsOf = (e) => {
+        const ts = e.ts;
+        return typeof ts === "string" ? ts : "";
+    };
+    return events
+        .map((event, index) => ({ event, index }))
+        .sort((a, b) => {
+        const ta = tsOf(a.event);
+        const tb = tsOf(b.event);
+        if (ta < tb)
+            return -1;
+        if (ta > tb)
+            return 1;
+        return a.index - b.index;
+    })
+        .map(({ event }) => event);
+}
 /** FDRS-667 — the last non-empty stderr line, flattened and bounded, as the
  *  one named cause an errored trial row can render inline. Redacted with the
  *  same rules as the on-disk stderr.log copy. */

package/dist/src/runner/runTrialGroup.d.ts

@@ -1,9 +1,7 @@
 import { type HostedClient } from "../hosted/client.js";
 import { runScenarioHosted } from "./runScenarioHosted.js";
 import { type TrialRow } from "./groupRender.js";
-/** Explicit finalize timeout for -n runs ([DECISION]) — the hosted client
- *  defaults to 30s; the judge measured 5-8s, 60s is belt-and-braces (same
- *  constant `pome demo` locked for its trial finalizes). */
+/** Per-request transport timeout. Durable evaluation has a separate budget. */
 export declare const GROUP_FINALIZE_TIMEOUT_MS = 60000;
 /** FDRS-663 — a lazy mint can quota-fail even though a trial just finished:
  *  the finished trial's DELETE propagates asynchronously. Pause and retry a

package/dist/src/runner/runTrialGroup.js

@@ -45,9 +45,7 @@ import { outcomeOf } from "../hosted/evalResultView.js";
 import { normalizeConfigAgentId, normalizeConfigAgentSlug, readProjectConfig, } from "../cli/project-config.js";
 import { runScenarioHosted } from "./runScenarioHosted.js";
 import { fixHandoffLines, flagHintLine, groupExitCode, groupSummaryLines, mostCommonFailedCriterion, provisioningLine, shortReason, spawningAgentLine, trialRowLine, } from "./groupRender.js";
-/** Explicit finalize timeout for -n runs ([DECISION]) — the hosted client
- *  defaults to 30s; the judge measured 5-8s, 60s is belt-and-braces (same
- *  constant `pome demo` locked for its trial finalizes). */
+/** Per-request transport timeout. Durable evaluation has a separate budget. */
 export const GROUP_FINALIZE_TIMEOUT_MS = 60_000;
 /** FDRS-663 — a lazy mint can quota-fail even though a trial just finished:
  *  the finished trial's DELETE propagates asynchronously. Pause and retry a

package/dist/src/scenario/parseScenario.d.ts

@@ -1,4 +1,9 @@
 import { type Scenario } from "./scenarioSchema.js";
 export declare function parseScenarioFile(path: string): Promise<Scenario>;
 export declare function parseScenario(markdown: string, slug?: string, sidecarSeed?: unknown, scenarioPath?: string): Scenario;
+/** The flat seed a single twin boots from. Single-twin scenarios return the
+ *  flat `seedState` as-is; multi-twin scenarios return that twin's slice of the
+ *  per-twin envelope (decided from `config.twins`, per the envelope-iff-multi-twin
+ *  rule). Used by the local runner to seed each twin harness. */
+export declare function seedStateForTwin(scenario: Scenario, twin: string): unknown;
 export declare function formatScenarioError(error: unknown, filePath: string): string;

package/dist/src/scenario/parseScenario.js

@@ -20,7 +20,7 @@ export function parseScenario(markdown, slug = "scenario", sidecarSeed, scenario
     const configText = sections.get("config") ?? "";
     const seedText = sections.get("seed state") ?? "";
     const config = configText.trim() ? scenarioConfigSchema.parse(parseFencedYaml(configText)) : scenarioConfigSchema.parse({});
-    const criteria = parseCriteria(criteriaText);
+    const criteria = parseCriteria(criteriaText, config.twins);
     const seedState = resolveSeedState({ sidecarSeed, seedText, config, scenarioPath });
     return scenarioSchema.parse({
         slug,
@@ -34,6 +34,12 @@ export function parseScenario(markdown, slug = "scenario", sidecarSeed, scenario
     });
 }
 function resolveSeedState(args) {
+    // Multi-twin (M3): the seed is a per-twin envelope, decided from `config.twins`
+    // alone (envelope-iff-multi-twin — never by sniffing the seed shape).
+    if (args.config.twins.length > 1) {
+        return resolveMultiTwinSeedState(args);
+    }
+    // ── Single-twin: unchanged (byte-identical flat path). ──
     // Sidecar wins when present — it's the compile-seeds output, already
     // validated against the in-memory twin. The `_meta` key (source hash,
     // model, etc.) is stripped before schema parsing.
@@ -61,6 +67,82 @@ function resolveSeedState(args) {
     }
     return defaultSeedStateForConfig(args.config.twins);
 }
+// Multi-twin (M3): the seed (sidecar OR inline) MUST be the per-twin envelope
+// `{ <twin>: <flat seed> }`. Envelope keys are a subset of the scenario's twins;
+// each present value is parsed with THAT twin's own flat schema, and a twin with
+// no envelope key falls back to its default seed. A key that is not one of the
+// scenario's twins is a loud error. When no seed is provided at all, every twin
+// gets its default.
+function resolveMultiTwinSeedState(args) {
+    const twins = args.config.twins;
+    let raw;
+    if (args.sidecarSeed !== undefined) {
+        raw = stripSidecarMeta(args.sidecarSeed);
+    }
+    else if (args.seedText.trim()) {
+        const text = stripFence(args.seedText);
+        if (!/^[\[{]/.test(text)) {
+            throw new Error(missingSidecarMessage(args.scenarioPath));
+        }
+        try {
+            raw = JSON.parse(text);
+        }
+        catch (err) {
+            if (err instanceof SyntaxError) {
+                throw new Error(`Inline JSON seed in ## Seed State is malformed: ${err.message}`);
+            }
+            throw err;
+        }
+    }
+    else {
+        raw = undefined;
+    }
+    return buildSeedEnvelope(raw, twins);
+}
+function buildSeedEnvelope(raw, twins) {
+    const envelope = {};
+    if (raw === undefined) {
+        for (const twin of twins)
+            envelope[twin] = defaultSeedForTwin(twin);
+        return envelope;
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Multi-twin scenarios need a per-twin seed envelope { <twin>: <seed> } for twins [${twins.join(", ")}], not a bare seed object.`);
+    }
+    const allowed = new Set(twins);
+    const provided = raw;
+    for (const key of Object.keys(provided)) {
+        if (!allowed.has(key)) {
+            throw new Error(`Seed envelope key "${key}" is not one of the scenario's twins [${twins.join(", ")}].`);
+        }
+    }
+    for (const twin of twins) {
+        envelope[twin] =
+            twin in provided ? parseSeedForTwin(twin, provided[twin]) : defaultSeedForTwin(twin);
+    }
+    return envelope;
+}
+// Parse one twin's flat seed with its own schema — the same schemas the
+// single-twin flat path uses, keyed by twin id. Unknown twins fall back to the
+// GitHub parse (mirrors the single-twin default).
+function parseSeedForTwin(twin, input) {
+    if (twin === "stripe")
+        return stripeSeedStateSchema.parse(input);
+    if (twin === "slack")
+        return slackSeedStateSchema.parse(input);
+    return parseGitHubSeedState(input);
+}
+function defaultSeedForTwin(twin) {
+    if (twin === "stripe") {
+        return stripeSeedStateSchema.parse({
+            api_keys: [{ key: "sk_test_pome_default", sid: "default", account_id: "acct_default" }]
+        });
+    }
+    if (twin === "slack") {
+        return slackSeedStateSchema.parse({});
+    }
+    return seedSchema.parse(defaultSeedState());
+}
 function missingSidecarMessage(scenarioPath) {
     const pathLabel = scenarioPath ?? "<scenario>.md";
     const sidecarLabel = scenarioPath
@@ -109,15 +191,72 @@ function splitSections(markdown) {
     }
     return sections;
 }
-function parseCriteria(input) {
-    return input
-        .split("\n")
-        .map((line) => line.trim())
-        .map((line) => line.match(/^[-*]\s+\[([DP])\]\s+(.+)$/))
-        .filter((match) => Boolean(match))
-        // Authors still write `[D]`/`[P]` in markdown; the published contract's
-        // tolerant reader normalizes those to the canonical `code`/`model` kinds.
-        .map((match) => criterionSchema.parse({ type: match[1], text: match[2].trim() }));
+// Criterion marker grammar (F-778): `[code]` / `[model]` optionally carrying a
+// twin tag, `[code:<twin>]` / `[model:<twin>]`, where <twin> is
+// `[a-z][a-z0-9_-]*`. The marker spells the canonical criterion kind directly.
+// The tag lands on `criterion.twin`; a bare marker leaves it undefined
+// (attributes to the session's primary twin, `twins[0]`).
+const CRITERION_LINE_RE = /^[-*]\s+\[(code|model)(?::([a-z][a-z0-9_-]*))?\]\s+(.+)$/;
+// The retired pre-F-778 marker spelling, matched ONLY to fail loudly. Without
+// this guard a legacy `[D]`/`[P]` line would fall through the silent
+// skip-non-criterion path below and the scenario would "pass" with fewer
+// criteria than its author wrote.
+const LEGACY_CRITERION_LINE_RE = /^[-*]\s+\[([DP])(?::([a-z][a-z0-9_-]*))?\]\s+(.+)$/;
+function parseCriteria(input, twins) {
+    const multiTwin = twins.length > 1;
+    const allowed = new Set(twins);
+    const primary = twins[0];
+    const criteria = [];
+    for (const rawLine of input.split("\n")) {
+        const line = rawLine.trim();
+        const legacy = line.match(LEGACY_CRITERION_LINE_RE);
+        if (legacy) {
+            const legacyMarker = `[${legacy[1]}${legacy[2] ? `:${legacy[2]}` : ""}]`;
+            throw new Error(`Criterion "${legacyMarker} ${legacy[3].trim()}" uses a retired marker — markers were renamed [D]→[code] and [P]→[model] (tags carry over: [D:github]→[code:github]).`);
+        }
+        const match = line.match(CRITERION_LINE_RE);
+        if (!match)
+            continue;
+        const kind = match[1]; // "code" | "model"
+        const tag = match[2]; // twin tag or undefined
+        const text = match[3].trim();
+        // Reconstruct the human-facing marker for error messages.
+        const marker = `[${kind}${tag ? `:${tag}` : ""}]`;
+        if (tag !== undefined) {
+            if (!multiTwin) {
+                // Single-twin: an explicit tag is allowed but must equal the sole twin.
+                if (tag !== primary) {
+                    throw new Error(`Criterion "${marker} ${text}" tags twin "${tag}", but this single-twin scenario runs "${primary}". Drop the tag or set config.twins to include "${tag}".`);
+                }
+            }
+            else if (!allowed.has(tag)) {
+                // Multi-twin: an explicit tag must name one of the scenario's twins.
+                throw new Error(`Criterion "${marker} ${text}" tags twin "${tag}", which is not in the scenario's twins [${twins.join(", ")}].`);
+            }
+        }
+        else if (multiTwin && kind === "code") {
+            // Multi-twin: every [code] criterion MUST carry a tag so the cloud knows
+            // which twin's state to check it against. [model] may stay bare
+            // (attributes to the primary twin).
+            throw new Error(`Criterion "${marker} ${text}" needs a twin tag ([code:<twin>]) in a multi-twin scenario (twins [${twins.join(", ")}]).`);
+        }
+        // The marker spells the canonical kind; `criterionSchema` keeps accepting
+        // the legacy `D`/`P` enum values only for 0.3.0-era persisted artifacts
+        // (the published contract's tolerant reader), never from markdown.
+        // The optional `twin` rides through untouched.
+        criteria.push(criterionSchema.parse(tag !== undefined ? { type: kind, text, twin: tag } : { type: kind, text }));
+    }
+    return criteria;
+}
+/** The flat seed a single twin boots from. Single-twin scenarios return the
+ *  flat `seedState` as-is; multi-twin scenarios return that twin's slice of the
+ *  per-twin envelope (decided from `config.twins`, per the envelope-iff-multi-twin
+ *  rule). Used by the local runner to seed each twin harness. */
+export function seedStateForTwin(scenario, twin) {
+    if (scenario.config.twins.length > 1) {
+        return scenario.seedState[twin];
+    }
+    return scenario.seedState;
 }
 function parseFencedYaml(input) {
     return parseYaml(stripFence(input));