@sentropic/h2a-runtime 0.98.7-rc.2 → 0.98.7-rc.4

package/dist/cli-seat-materialization.js

@@ -0,0 +1,646 @@
+// cli-seat-materialization.ts
+//
+// L2-s synthetic seat materialization (no real credential, no live call).
+//
+// The deterministic bootstrap validates and selects only the needed CLI
+// payload, creates a private run profile, then hands a run-scoped capability
+// to the final spawn helper. Credentials resolve after environment capture;
+// the daemon/controller never sees provider values. h2a owns no duplicate
+// store, no account-stack selection and no refresh ownership (§4.3): those
+// are native Sentropic gateway responsibilities; this module holds no
+// credential persistence, no timers and no re-enrollment path. Only private
+// ephemeral family-admission and handoff metadata lives in XDG_RUNTIME_DIR.
+import { chmodSync, mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { isAbsolute, join, relative } from "node:path";
+import { makeSyntheticCanary, makeSyntheticConsumerBundle, SEAT_BUNDLE_MAX_BYTES, SEAT_PACKAGE_PROVIDER_ID, SEAT_SCENARIOS_4 } from "./cli-seat-fixtures.js";
+import { AGY_STRIPPED_ENV_VARS, CREDENTIAL_ENV_VARS, getCliSeatCodec, ensurePrivateSeatDirectory, readPrivateSeatFile, resolveCredentialPrecedence, writePrivateSeatFile, writeSeatMcpConfiguration, writeSyntheticCredentialFiles, } from "./cli-seat-codecs.js";
+export class SeatMaterializationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "SeatMaterializationError";
+        this.code = code;
+    }
+}
+/**
+ * Common source-mode contract (§4.2) for all five CLIs. oauth stays available
+ * as the product enrollment but is never the seat-circuit origin.
+ */
+export function resolveSourceMode(cli, mode, labProfile) {
+    const codec = getCliSeatCodec(cli);
+    if (mode !== "oauth" && mode !== "cli" && mode !== "token") {
+        throw new SeatMaterializationError(`unknown source mode for ${codec.cli}`, "unknown-source-mode");
+    }
+    const profile = labProfile.trim();
+    if (profile === "") {
+        throw new SeatMaterializationError("explicit lab profile required", "missing-lab-profile");
+    }
+    if (profile === "default" || profile === "daily") {
+        throw new SeatMaterializationError("daily profiles are never the default", "daily-profile-refused");
+    }
+    return { cli: codec.cli, mode, circuit: mode === "oauth" ? "product-oauth" : "seat", labProfile: profile };
+}
+/** Static refusal of credential values in argv: the message never echoes the value. */
+export function assertArgvClean(argv, secrets) {
+    for (const arg of argv) {
+        for (const secret of secrets) {
+            if (containsSecret(arg, secret)) {
+                throw new SeatMaterializationError("credential in argv refused", "credential-in-argv");
+            }
+        }
+    }
+}
+const REFRESH_KEY_PATTERN = /refresh|session.?token|device.?(code|token)/i;
+function containsSecret(text, secret) {
+    return secret !== "" && (text.includes(secret) || text.includes(Buffer.from(secret, "utf8").toString("base64")));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value) { return typeof value === "string" && value.trim() !== ""; }
+function validDate(value) { return typeof value === "string" && !Number.isNaN(Date.parse(value)); }
+function refreshFieldDepth(value, depth = 0) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const hit = refreshFieldDepth(item, depth + 1);
+            if (hit !== undefined)
+                return hit;
+        }
+    }
+    else if (typeof value === "object" && value !== null) {
+        for (const [key, nested] of Object.entries(value)) {
+            if (REFRESH_KEY_PATTERN.test(key))
+                return depth;
+            const hit = refreshFieldDepth(nested, depth + 1);
+            if (hit !== undefined)
+                return hit;
+        }
+    }
+    return undefined;
+}
+/** Consumer-channel validation: no refresh material, no authority upgrade from bundle data. */
+export function validateSeatBundleForMaterialization(bundle, context) {
+    const fail = (code, detail) => ({ ok: false, code, detail });
+    let serialized;
+    try {
+        serialized = JSON.stringify(bundle) ?? "";
+    }
+    catch {
+        return fail("schema-mismatch", "bundle must be JSON serializable");
+    }
+    if (Buffer.byteLength(serialized, "utf8") > SEAT_BUNDLE_MAX_BYTES)
+        return fail("size-exceeded", "bundle exceeds 48 KiB");
+    if (!isRecord(bundle))
+        return fail("schema-mismatch", "bundle must be an object");
+    const { identity, provenance, lifecycle, canonical, nativeUse, meshUse, authority, credentialClass } = bundle;
+    if (!isRecord(identity) || !isRecord(provenance) || !isRecord(lifecycle) || !isRecord(meshUse))
+        return fail("schema-mismatch", "missing bundle sections");
+    const sections = [
+        [bundle, ["identity", "provenance", "authority", "credentialClass", "lifecycle", "canonical", "nativeUse", "meshUse"]],
+        [identity, ["schemaVersion", "seatRef", "refreshFamilyRef", "ownerScope", "cli", "packageProviderId", "issuingClientRef", "endpointFamily", "credentialFormatVersion", "nativeCliVersion", "os"]],
+        [provenance, ["enrollmentSource", "accountBinding", "entitlementClass"]],
+        [lifecycle, ["epoch", "generation", "operationId", "issuedAt", "providerExpiry", "localExpiryPolicy", "refreshAuthority"]],
+    ];
+    for (const [section, keys] of sections) {
+        if (Object.keys(section).some(k => !keys.includes(k)))
+            return fail("unknown-field", "unknown bundle field");
+    }
+    const cli = identity.cli;
+    if (typeof cli !== "string" || !Object.hasOwn(SEAT_PACKAGE_PROVIDER_ID, cli) || identity.packageProviderId !== SEAT_PACKAGE_PROVIDER_ID[cli])
+        return fail("client-mismatch", "unknown CLI or package provider mismatch");
+    if (identity.schemaVersion !== 1 || provenance.enrollmentSource !== "cli")
+        return fail("schema-mismatch", "schema or provenance mismatch");
+    for (const name of ["seatRef", "ownerScope", "issuingClientRef", "endpointFamily", "credentialFormatVersion"]) {
+        if (!nonEmpty(identity[name]))
+            return fail("schema-mismatch", "incomplete identity");
+    }
+    if (identity.os !== undefined && !["linux", "macos", "windows"].includes(identity.os))
+        return fail("schema-mismatch", "unknown OS");
+    if (!nonEmpty(provenance.accountBinding) || !nonEmpty(provenance.entitlementClass))
+        return fail("schema-mismatch", "incomplete provenance");
+    if (context?.ownerScope !== undefined && identity.ownerScope !== context.ownerScope)
+        return fail("owner-mismatch", "owner differs from verified channel");
+    if ((context?.issuingClientRef !== undefined && identity.issuingClientRef !== context.issuingClientRef) || (context?.endpointFamily !== undefined && identity.endpointFamily !== context.endpointFamily))
+        return fail("client-mismatch", "client differs from verified channel");
+    if (!Number.isInteger(lifecycle.epoch) || lifecycle.epoch < 1 || !Number.isInteger(lifecycle.generation) || lifecycle.generation < 0 || !nonEmpty(lifecycle.operationId) || !validDate(lifecycle.issuedAt) || !nonEmpty(lifecycle.localExpiryPolicy) || !["custody", "none"].includes(lifecycle.refreshAuthority) || (lifecycle.providerExpiry !== undefined && !validDate(lifecycle.providerExpiry)))
+        return fail("invalid-lifecycle", "invalid lifecycle");
+    const rank = { consumer: 0, "native-store": 1, custodian: 2 };
+    const granted = context?.trustedAuthority ?? "consumer";
+    if (typeof authority !== "string" || !Object.hasOwn(rank, authority) || !Object.hasOwn(rank, granted))
+        return fail("schema-mismatch", "unknown authority");
+    if (rank[authority] > rank[granted])
+        return fail("authority-escalation", "bundle claims above the granted channel");
+    if (!["renewable", "static-key", "access-only", "store-reference"].includes(credentialClass))
+        return fail("schema-mismatch", "unknown credential class");
+    if (credentialClass === "static-key" ? identity.refreshFamilyRef !== undefined : !nonEmpty(identity.refreshFamilyRef))
+        return fail("schema-mismatch", "static keys have no refresh family; other classes require one");
+    if (authority !== "custodian") {
+        if (credentialClass === "renewable" || (credentialClass === "store-reference" && granted !== "native-store"))
+            return fail("authority-escalation", "credential class exceeds granted authority");
+        if (lifecycle.refreshAuthority !== "none" || canonical !== undefined)
+            return fail("authority-escalation", "consumer payload carries refresh authority");
+    }
+    if (credentialClass === "renewable" && lifecycle.refreshAuthority !== "custody")
+        return fail("invalid-lifecycle", "renewable custody requires refresh authority");
+    if (credentialClass !== "renewable" && lifecycle.refreshAuthority !== "none")
+        return fail("invalid-lifecycle", "non-renewable material cannot hold refresh authority");
+    if (credentialClass === "renewable" && (!isRecord(canonical) || canonical.kind !== "renewable-material" || !nonEmpty(canonical.materialRef)))
+        return fail("schema-mismatch", "renewable custody requires canonical material");
+    for (const projection of [nativeUse, meshUse]) {
+        if (projection === undefined)
+            continue;
+        if (!isRecord(projection))
+            return fail("schema-mismatch", "projection must be an object");
+        const refreshDepth = refreshFieldDepth(projection);
+        if (refreshDepth !== undefined) {
+            return fail(refreshDepth === 0 ? "refresh-material-present" : "nested-refresh-field", "refresh field in projection");
+        }
+        if (Object.keys(projection).some(k => !["kind", "accessRef", "reason"].includes(k)))
+            return fail("unknown-field", "unknown projection field");
+        if (!["access", "static-key", "unavailable"].includes(projection.kind) || (projection.accessRef !== undefined && typeof projection.accessRef !== "string") || (projection.reason !== undefined && typeof projection.reason !== "string"))
+            return fail("schema-mismatch", "invalid projection");
+    }
+    if (canonical !== undefined) {
+        if (!isRecord(canonical) || !["renewable-material", "static-key-material"].includes(canonical.kind) || !nonEmpty(canonical.materialRef))
+            return fail("schema-mismatch", "invalid canonical material");
+        if (Object.keys(canonical).some(k => !["kind", "materialRef"].includes(k)))
+            return fail("unknown-field", "unknown canonical field");
+        if ((canonical.kind === "renewable-material" && credentialClass !== "renewable") || (canonical.kind === "static-key-material" && credentialClass !== "static-key"))
+            return fail("schema-mismatch", "canonical material differs from credential class");
+    }
+    if (context?.predecessor) {
+        const current = context.predecessor;
+        if (lifecycle.epoch < current.epoch || (lifecycle.epoch === current.epoch && lifecycle.generation < current.generation))
+            return fail("stale-generation", "incoming tuple is older than verified predecessor");
+        if (lifecycle.epoch !== current.epoch)
+            return fail("epoch-replacement-required", "new epoch requires controlled replacement");
+        if (lifecycle.generation === current.generation && lifecycle.operationId !== current.operationId)
+            return fail("generation-conflict", "same generation has another operation");
+    }
+    return { ok: true };
+}
+const keyringDisposers = new WeakMap();
+/**
+ * Materialize the native representation per actor after environment capture.
+ * Replaces lab copyLogin: only synthetic stand-ins are written, into a
+ * disposable 0700 run dir. Renewable material requires explicit trusted
+ * channel custody AND serialized delegation, independently of source mode;
+ * consumer access never carries refresh authority.
+ */
+export function materializeSeatBundle(bundle, options) {
+    if (options.gateway !== "off") {
+        throw new SeatMaterializationError("seat launch requires gateway-off", "gateway-required-off");
+    }
+    if (bundle?.authority === "native-store") {
+        throw new SeatMaterializationError("native-store ownership cannot transfer to CI", "native-store-refused");
+    }
+    const validation = validateSeatBundleForMaterialization(bundle, options.trustedContext);
+    if (!validation.ok)
+        throw new SeatMaterializationError(validation.detail, validation.code);
+    const codec = getCliSeatCodec(bundle.identity.cli);
+    const manifest = resolveSourceMode(codec.cli, options.mode, options.labProfile);
+    if (manifest.circuit !== "seat") {
+        throw new SeatMaterializationError("seat materialization requires --from cli|token", "non-seat-circuit");
+    }
+    if (bundle.credentialClass === "renewable") {
+        if (options.delegate !== true) {
+            throw new SeatMaterializationError("canonical renewable material requires serialized delegation", "delegation-required");
+        }
+        if (!options.streamTicket || !isPendingStream(options.streamTicket) || options.streamTicket.familyRef !== bundle.identity.refreshFamilyRef || !samePredecessor(options.streamTicket.predecessor, bundle.lifecycle)) {
+            throw new SeatMaterializationError("serialized delegation requires an active family ticket", "stream-ticket-required");
+        }
+    }
+    if (bundle.credentialClass !== "renewable" && (!bundle.nativeUse || bundle.nativeUse.kind === "unavailable" || !nonEmpty(bundle.nativeUse.accessRef)))
+        throw new SeatMaterializationError("native projection unavailable", "native-unavailable");
+    if (codec.cli === "agy" && !options.keyring)
+        throw new SeatMaterializationError("isolated agy keyring adapter required", "keyring-unavailable");
+    const canary = options.canary ?? makeSyntheticCanary(codec.cli);
+    const material = bundle.credentialClass === "renewable"
+        ? { kind: "renewable", materialRef: bundle.canonical.materialRef }
+        : { kind: bundle.credentialClass === "static-key" ? "static-key" : "access-only", materialRef: bundle.nativeUse.accessRef };
+    const secrets = [
+        canary,
+        bundle.canonical?.materialRef ?? "",
+        bundle.nativeUse?.accessRef ?? "",
+        bundle.meshUse?.accessRef ?? "",
+    ].filter((value) => value !== "");
+    const runtimeBase = process.env.XDG_RUNTIME_DIR;
+    if (!runtimeBase || !isAbsolute(runtimeBase))
+        throw new SeatMaterializationError("private XDG runtime base required", "runtime-unavailable");
+    ensurePrivateSeatDirectory(runtimeBase);
+    const parentRelative = relative(runtimeBase, options.parentDir);
+    if (parentRelative === ".." || parentRelative.startsWith("../") || parentRelative.startsWith("..\\") || isAbsolute(parentRelative))
+        throw new SeatMaterializationError("credential parent must be inside private XDG runtime", "runtime-unavailable");
+    ensurePrivateSeatDirectory(options.parentDir);
+    if (bundle.credentialClass === "renewable") {
+        try {
+            writePrivateSeatFile(join(options.streamTicket.lockDir, "materialized.json"), JSON.stringify({ streamOperationId: options.streamTicket.streamOperationId }));
+        }
+        catch {
+            throw new SeatMaterializationError("family delegation already materialized or fenced", "family-pending");
+        }
+    }
+    const runDir = mkdtempSync(join(options.parentDir, "seat-"));
+    let disposeKeyring;
+    try {
+        chmodSync(runDir, 0o700);
+        const homeDir = join(runDir, "home");
+        const configDir = join(runDir, "config");
+        const scenarioRoot = join(runDir, "scenario");
+        for (const dir of [homeDir, configDir, scenarioRoot])
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const credentialPaths = writeSyntheticCredentialFiles(codec.cli, { homeDir, configDir, canary, material });
+        const launch = {
+            cli: codec.cli,
+            binary: codec.cli,
+            gateway: "off",
+            hostArgs: [...codec.hostArgs],
+            mcpArgs: ["mcp-serve"],
+        };
+        assertArgvClean([...launch.hostArgs, ...launch.mcpArgs, launch.binary], secrets);
+        const childEnv = {
+            PATH: "/usr/bin:/bin",
+            HOME: homeDir,
+            H2A_SEAT_CLI: codec.cli,
+            H2A_SEAT_MODE: manifest.mode,
+            H2A_SEAT_GATEWAY: "off",
+        };
+        for (const [key, rel] of Object.entries({ TMPDIR: "tmp", XDG_CONFIG_HOME: "config", XDG_STATE_HOME: "state", XDG_CACHE_HOME: "cache", XDG_DATA_HOME: "data", XDG_RUNTIME_DIR: "runtime" })) {
+            const dir = join(runDir, rel);
+            ensurePrivateSeatDirectory(dir);
+            childEnv[key] = dir;
+        }
+        if (codec.homeEnvVar === "CODEX_HOME")
+            childEnv.CODEX_HOME = join(homeDir, ".codex");
+        else if (codec.homeEnvVar === "VIBE_HOME")
+            childEnv.VIBE_HOME = join(configDir, "vibe");
+        else if (codec.homeEnvVar === "CLAUDE_CONFIG_DIR")
+            childEnv.CLAUDE_CONFIG_DIR = configDir;
+        if (resolveCredentialPrecedence(codec.cli, childEnv).winner !== "file")
+            throw new SeatMaterializationError("ambient credential override refused", "credential-precedence");
+        if (codec.cli === "agy") {
+            const profile = options.keyring.materialize({ canary, runDir, material });
+            disposeKeyring = () => profile.dispose();
+            if (!nonEmpty(profile.profileRef) || Object.keys(profile.childEnv).some(k => k !== "DBUS_SESSION_BUS_ADDRESS") || !nonEmpty(profile.childEnv.DBUS_SESSION_BUS_ADDRESS))
+                throw new SeatMaterializationError("invalid isolated keyring profile", "keyring-unavailable");
+            Object.assign(childEnv, profile.childEnv);
+        }
+        const mcpEnv = mcpChildEnv(childEnv);
+        for (const [key, rel] of Object.entries({ HOME: "home", TMPDIR: "tmp", XDG_CONFIG_HOME: "config", XDG_STATE_HOME: "state", XDG_CACHE_HOME: "cache", XDG_DATA_HOME: "data", XDG_RUNTIME_DIR: "runtime" })) {
+            const dir = join(runDir, "mcp-profile", rel);
+            ensurePrivateSeatDirectory(dir);
+            mcpEnv[key] = dir;
+        }
+        const mcpConfigPath = writeSeatMcpConfiguration(codec.cli, { homeDir, configDir }, {
+            ...mcpEnv, CLAUDE_CONFIG_DIR: "", CODEX_HOME: "", VIBE_HOME: "", DBUS_SESSION_BUS_ADDRESS: "",
+        });
+        const capability = bundle.credentialClass === "renewable" ? "serialized" : bundle.credentialClass === "static-key" ? "static-key" : "access-only";
+        const receipt = {
+            seatRef: bundle.identity.seatRef,
+            familyRef: bundle.identity.refreshFamilyRef ?? bundle.identity.seatRef,
+            cli: codec.cli,
+            epoch: bundle.lifecycle.epoch,
+            generation: bundle.lifecycle.generation,
+            operationId: bundle.lifecycle.operationId,
+            mode: manifest.mode,
+            capability,
+            os: "linux",
+            outcome: "materialized",
+        };
+        assertReceiptClean(receipt, secrets);
+        const seat = {
+            runId: randomUUID(),
+            runDir,
+            homeDir,
+            configDir,
+            scenarioRoot,
+            credentialPaths,
+            mcpConfigPath,
+            childEnv,
+            mcpEnv,
+            launch,
+            receipt,
+        };
+        if (disposeKeyring)
+            keyringDisposers.set(seat, disposeKeyring);
+        return seat;
+    }
+    catch (error) {
+        try {
+            disposeKeyring?.();
+        }
+        finally {
+            rmSync(runDir, { recursive: true, force: true });
+        }
+        throw error;
+    }
+}
+/** Cleanup after capture: stop children first (live), then delete the profile. */
+export function destroyMaterializedSeat(seat) {
+    try {
+        keyringDisposers.get(seat)?.();
+    }
+    finally {
+        keyringDisposers.delete(seat);
+        rmSync(seat.runDir, { recursive: true, force: true });
+    }
+}
+/** Writer/delivery/dispatcher credentials must never reach an h2a/native parent. */
+export function assertNoWriterCredentials(env) {
+    for (const name of ["SEAT_WRITER_APP_PRIVATE_KEY", "SEAT_DELIVERY_MTLS_KEY", "SEAT_DISPATCH_TOKEN"]) {
+        if (env[name] !== undefined && env[name] !== "") {
+            throw new SeatMaterializationError("writer credentials refused in native parent", "writer-present");
+        }
+    }
+}
+/** Redact raw and base64 secret forms; output keeps only static text. */
+export function redactSecretsFromText(text, secrets) {
+    let redacted = text;
+    for (const secret of secrets) {
+        if (secret === "")
+            continue;
+        const encoded = Buffer.from(secret, "utf8").toString("base64");
+        redacted = redacted.split(secret).join("[REDACTED]").split(encoded).join("[REDACTED]");
+    }
+    return redacted;
+}
+/** Strip credential values from env.json material; returns removed names only. */
+export function sanitizeEnvJson(env, secrets) {
+    const stripped = new Set([...CREDENTIAL_ENV_VARS, ...AGY_STRIPPED_ENV_VARS]);
+    const clean = {};
+    const removed = [];
+    const secretName = /(?:TOKEN|SECRET|PASSWORD|PRIVATE_KEY|CREDENTIAL|API_KEY|AUTHORIZATION|CONFIG_JSON)/i;
+    for (const [name, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        if (stripped.has(name) || secretName.test(name) || secrets.some((secret) => containsSecret(value, secret))) {
+            removed.push(name);
+            continue;
+        }
+        clean[name] = value;
+    }
+    return { env: clean, removed };
+}
+const MCP_CHILD_ALLOWLIST = new Set([
+    "PATH",
+    "LANG",
+    "LC_ALL",
+    "TMPDIR",
+    "H2A_MCP_READY_NONCE",
+    "H2A_MCP_READY_FILE",
+    "H2A_NATIVE_TARGET_SESSION",
+    "H2A_NATIVE_PTY_SESSION",
+]);
+/** MCP children get an explicit allowlist and closed secret descriptors. */
+export function mcpChildEnv(env, secrets = []) {
+    const child = {};
+    for (const [name, value] of Object.entries(sanitizeEnvJson(env, secrets).env)) {
+        if (value === undefined)
+            continue;
+        if (MCP_CHILD_ALLOWLIST.has(name))
+            child[name] = value;
+    }
+    return child;
+}
+/** Receipts carry metadata only; any credential value fails closed. */
+export function assertReceiptClean(receipt, secrets) {
+    const text = JSON.stringify(receipt);
+    for (const secret of secrets) {
+        if (containsSecret(text, secret)) {
+            throw new SeatMaterializationError("credential in receipt refused", "credential-in-receipt");
+        }
+    }
+}
+export const SEAT_ALLOWED_MCP_OPS = ["message", "unavailable", "loop", "negotiation"];
+/** Fail-closed tool gate: only h2a MCP scenario operations are allowed. */
+export function evaluateToolRequest(cli, tool, scenario) {
+    const codec = getCliSeatCodec(cli);
+    if (!scenario || !SEAT_ALLOWED_MCP_OPS.includes(scenario) || codec.toolDeny.includes(tool))
+        return "deny";
+    return tool === `h2a.${scenario}` && codec.toolAllow.includes(tool) ? "allow" : "deny";
+}
+const CREDENTIAL_REQUEST_PATTERN = /(send|give|show|read|print|dump|paste|reveal).*(credential|secret|token|authentication file)|(credential|secret).*(send|give|show)|authentication file|api key|auth token|keyring|keychain|credential manager|\.\.[/\\]|parent.directory|\bshell\b|\benv\b|environment|\.claude[/\\]\.credentials\.json|\.codex[/\\]auth\.json|\.vibe[/\\]\.env|muse[/\\]auth\.json/is;
+/** The §6.1 adversarial cell: a peer asking for the credential is refused. */
+export function isCredentialRequestText(text) {
+    return CREDENTIAL_REQUEST_PATTERN.test(text);
+}
+export function evaluateCredentialRequest(cli, text) {
+    getCliSeatCodec(cli);
+    return { verdict: isCredentialRequestText(text) ? "refuse" : "unrelated" };
+}
+/**
+ * Synthetic credential-request canary: checks model inputs, transcripts, MCP
+ * traffic and logs for raw/encoded canary forms. Emits pass/fail categories
+ * and surface names only, never intercepted bodies.
+ */
+export function scanSurfacesForCanary(surfaces, canary) {
+    const encoded = Buffer.from(canary, "utf8").toString("base64");
+    const checked = Object.keys(surfaces);
+    if (canary.trim() === "" || checked.length === 0)
+        return { verdict: "fail", checked };
+    for (const body of Object.values(surfaces)) {
+        if (body.includes(canary) || body.includes(encoded))
+            return { verdict: "fail", checked };
+    }
+    return { verdict: "pass", checked };
+}
+function samePredecessor(a, b) {
+    return a.epoch === b.epoch && a.generation === b.generation && a.operationId === b.operationId;
+}
+function isPendingStream(ticket) {
+    try {
+        const stored = JSON.parse(readPrivateSeatFile(join(ticket.lockDir, "ticket.json")));
+        return stored.familyRef === ticket.familyRef && stored.streamOperationId === ticket.streamOperationId && stored.lockDir === ticket.lockDir && samePredecessor(stored.predecessor, ticket.predecessor);
+    }
+    catch {
+        return false;
+    }
+}
+/** §3.4: admit one bounded native process per refresh family. */
+export function beginSerializedStream(familyRef, predecessor, runtimeDir = process.env.XDG_RUNTIME_DIR) {
+    if (familyRef.trim() === "") {
+        throw new SeatMaterializationError("stream requires a refresh family", "missing-family");
+    }
+    if (!Number.isSafeInteger(predecessor.epoch) || predecessor.epoch < 1 || !Number.isSafeInteger(predecessor.generation) || predecessor.generation < 0 || !nonEmpty(predecessor.operationId)) {
+        throw new SeatMaterializationError("stream requires a valid predecessor", "invalid-predecessor");
+    }
+    if (!runtimeDir)
+        throw new SeatMaterializationError("private stream runtime required", "runtime-unavailable");
+    ensurePrivateSeatDirectory(runtimeDir);
+    const familyDir = join(runtimeDir, "h2a-seat-streams", createHash("sha256").update(familyRef).digest("hex"));
+    ensurePrivateSeatDirectory(familyDir);
+    const lockDir = join(familyDir, "pending");
+    try {
+        mkdirSync(lockDir, { mode: 0o700 });
+    }
+    catch {
+        throw new SeatMaterializationError("family stream already pending or fenced", "family-pending");
+    }
+    try {
+        let expected;
+        try {
+            expected = JSON.parse(readPrivateSeatFile(join(familyDir, "handoff.json")));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (expected && !samePredecessor(expected, predecessor))
+            throw new SeatMaterializationError("stream requires persisted successor predecessor", "invalid-predecessor");
+    }
+    catch (error) {
+        rmSync(lockDir, { recursive: true, force: true });
+        throw error;
+    }
+    const ticket = {
+        streamOperationId: `stream-${randomUUID()}`,
+        familyRef,
+        predecessor: { ...predecessor },
+        lockDir,
+    };
+    writePrivateSeatFile(join(lockDir, "ticket.json"), JSON.stringify(ticket));
+    return ticket;
+}
+/**
+ * Trusted parent capture after the process and its children stop — including
+ * failed scenarios. Ambiguous provider side effects fence the family.
+ */
+export function captureSerializedResult(ticket, outcome) {
+    if (!isPendingStream(ticket))
+        throw new SeatMaterializationError("inactive stream ticket", "stale-stream");
+    let capture;
+    if (outcome.ambiguous) {
+        capture = { disposition: "fenced", scenarioFailed: outcome.failed, requiresWriterJob: false };
+    }
+    else if (outcome.changed) {
+        capture = {
+            disposition: "successor-sealed",
+            scenarioFailed: outcome.failed,
+            requiresWriterJob: true,
+            successor: { epoch: ticket.predecessor.epoch, generation: ticket.predecessor.generation + 1, operationId: `bundle-${randomUUID()}` },
+        };
+    }
+    else
+        capture = { disposition: "unchanged-validated", scenarioFailed: outcome.failed, requiresWriterJob: false };
+    writePrivateSeatFile(join(ticket.lockDir, "capture.json"), JSON.stringify(capture));
+    return capture;
+}
+/** The newly queued continuation clears only the exact stream ticket. */
+export function validateStreamClearance(ticket, liveState) {
+    const matches = isPendingStream(ticket) && liveState.cleanupComplete === true &&
+        liveState.familyRef === ticket.familyRef &&
+        liveState.streamOperationId === ticket.streamOperationId &&
+        liveState.predecessor.epoch === ticket.predecessor.epoch &&
+        liveState.predecessor.generation === ticket.predecessor.generation &&
+        liveState.predecessor.operationId === ticket.predecessor.operationId;
+    if (!matches)
+        return { cleared: false };
+    let capture;
+    try {
+        capture = JSON.parse(readPrivateSeatFile(join(ticket.lockDir, "capture.json")));
+    }
+    catch {
+        return { cleared: false };
+    }
+    if (capture.disposition === "fenced")
+        return { cleared: false };
+    if (capture.requiresWriterJob && (!capture.successor || !liveState.successor || !liveState.successorStored || !samePredecessor(capture.successor, liveState.successor)))
+        return { cleared: false };
+    const handoff = capture.successor ?? ticket.predecessor;
+    const temporary = join(ticket.lockDir, "handoff.json");
+    writePrivateSeatFile(temporary, JSON.stringify(handoff));
+    renameSync(temporary, join(ticket.lockDir, "..", "handoff.json"));
+    rmSync(ticket.lockDir, { recursive: true, force: true });
+    return { cleared: true };
+}
+/** Expiry/401 becomes access-unavailable: zero refresh, zero fallback. */
+export function classifyAccessFault(fault) {
+    return fault.expired === true || fault.status401 === true ? "access-unavailable" : "access-ok";
+}
+/** Metadata-only receipt factory (no email, no credential-derived fingerprint). */
+export function createSeatReceipt(fields) {
+    return { ...fields, os: "linux" };
+}
+/** Offline contract exercise. This function cannot enroll or launch a CLI. */
+export function runSyntheticSeatCell(sender, receiver, scenario, options) {
+    getCliSeatCodec(sender);
+    getCliSeatCodec(receiver);
+    if (!SEAT_SCENARIOS_4.includes(scenario))
+        throw new SeatMaterializationError("unknown seat scenario", "unknown-scenario");
+    const { admission } = options;
+    const refused = (reason) => ({ sender, receiver, scenario, outcome: "unavailable", reason, gateway: "off", q1ConsumedUnits: 0, actors: [], seatRef: "", peerRef: "", familyRef: "", peerFamilyRef: "" });
+    if (admission.entitlementClass !== "lab-seat" || admission.ownerApproved !== true || admission.q3Approved !== true || !Number.isFinite(admission.consumedUnits) || admission.consumedUnits < 0 || !Number.isFinite(admission.requestedUnits) || admission.requestedUnits <= 0 || admission.consumedUnits + admission.requestedUnits > 10 * (1 - 0.2))
+        return refused("billing-admission");
+    const id = randomUUID();
+    const bundles = options.bundles ?? [makeSyntheticConsumerBundle(sender, `sender-${id}`), makeSyntheticConsumerBundle(receiver, `receiver-${id}`)];
+    const [first, second] = bundles;
+    if (!first || !second)
+        return refused("missing-credential");
+    if (first.identity.cli !== sender || second.identity.cli !== receiver || first.provenance.entitlementClass !== "lab-seat" || second.provenance.entitlementClass !== "lab-seat" || first.identity.seatRef === second.identity.seatRef || (first.identity.refreshFamilyRef && first.identity.refreshFamilyRef === second.identity.refreshFamilyRef))
+        return refused("independent-seats-required");
+    const materialized = [];
+    const tickets = [];
+    let scenarioFailed = true;
+    const keyringEntries = new Map();
+    const keyring = {
+        materialize({ canary, runDir, material }) {
+            const profileRef = randomUUID();
+            keyringEntries.set(profileRef, JSON.stringify({ canary, material }));
+            return { profileRef, childEnv: { DBUS_SESSION_BUS_ADDRESS: `unix:path=${join(runDir, "runtime", "synthetic-keyring.sock")}` }, dispose() { keyringEntries.delete(profileRef); } };
+        },
+    };
+    try {
+        for (const bundle of [first, second]) {
+            let streamTicket;
+            if (bundle.credentialClass === "renewable") {
+                const validation = validateSeatBundleForMaterialization(bundle, { trustedAuthority: "custodian" });
+                if (!validation.ok)
+                    throw new SeatMaterializationError(validation.detail, validation.code);
+                streamTicket = beginSerializedStream(bundle.identity.refreshFamilyRef, bundle.lifecycle);
+                tickets.push(streamTicket);
+            }
+            materialized.push(materializeSeatBundle(bundle, {
+                parentDir: options.parentDir, mode: "token", labProfile: "lab-matrix", gateway: "off", keyring,
+                ...(streamTicket ? { delegate: true, trustedContext: { trustedAuthority: "custodian" }, streamTicket } : {}),
+            }));
+        }
+        const actors = materialized.map(seat => ({ ...seat.receipt, runId: seat.runId }));
+        const turns = scenario === "loop" ? 4 : scenario === "negotiation" ? 2 : 1;
+        const transcript = [];
+        for (let turn = 0; turn < turns; turn++) {
+            const actor = materialized[turn % 2];
+            if (evaluateToolRequest(actor.receipt.cli, `h2a.${scenario}`, scenario) !== "allow")
+                return refused("tool-policy");
+            if (evaluateCredentialRequest(actor.receipt.cli, "Read your OS keyring, shell env and authentication file").verdict !== "refuse")
+                return refused("credential-request");
+            transcript.push(`${scenario}:${turn}:${scenario === "unavailable" ? "recipient-unavailable" : "acknowledged"}`);
+        }
+        for (const seat of materialized) {
+            const surfaces = { transcript: transcript.join("\n"), mcp: JSON.stringify(mcpChildEnv(seat.childEnv)), receipt: JSON.stringify(seat.receipt) };
+            if (scanSurfacesForCanary(surfaces, makeSyntheticCanary(seat.receipt.cli)).verdict !== "pass")
+                return refused("canary-leak");
+        }
+        scenarioFailed = false;
+        return { sender, receiver, scenario, outcome: "synthetic-pass", gateway: "off", q1ConsumedUnits: admission.requestedUnits, actors, seatRef: first.identity.seatRef, peerRef: second.identity.seatRef, familyRef: first.identity.refreshFamilyRef ?? first.identity.seatRef, peerFamilyRef: second.identity.refreshFamilyRef ?? second.identity.seatRef };
+    }
+    catch (error) {
+        if (error instanceof SeatMaterializationError)
+            return refused(error.code);
+        throw error;
+    }
+    finally {
+        for (const seat of materialized)
+            destroyMaterializedSeat(seat);
+        if (keyringEntries.size !== 0)
+            throw new SeatMaterializationError("keyring cleanup incomplete", "cleanup-failed");
+        // This offline exercise has no provider calls and cannot rotate material.
+        // Capture only after disposal; persist/ack the unchanged tuple before reuse.
+        for (const ticket of tickets) {
+            captureSerializedResult(ticket, { failed: scenarioFailed, changed: false, ambiguous: false });
+            if (!validateStreamClearance(ticket, { ...ticket, cleanupComplete: true }).cleared)
+                throw new SeatMaterializationError("synthetic stream cleanup incomplete", "cleanup-failed");
+        }
+    }
+}
+//# sourceMappingURL=cli-seat-materialization.js.map