@intentic/sandbox-contract 1.240.0 → 1.242.0

package/src/history-state.ts

@@ -105,6 +105,12 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
      * export would pack THAT, each one a multiple of the last. Living on this volume is the other half of the
      * same guard; under `/work` the file would also be watched, indexed by iq, and snapshotted into history. */
     { path: "exports/", portability: "derived" },
+    /* The other end of the same volume: a bundle being taken IN, spooled here while its owner reads the plan
+     * it produced. `derived` for the export directory's reason and one more — this is somebody else's bundle,
+     * mid-review, and packing a half-reviewed arrival into an export would carry a sandbox that was never
+     * this one. The pipeline deletes each spool on apply or abandon, and boot sweeps whatever a crash left
+     * (portability/bundle-arrival.ts). */
+    { path: "arrivals/", portability: "derived" },
 
     /* ---- credentials ---- */
 

package/src/index.ts

@@ -3,13 +3,13 @@ import { contractRoutes, requestPathFor, routeForProcedure, routeNameForRequest,
 import { activityContract } from "./contracts/activity.contract.js";
 import { agentContract } from "./contracts/agent.contract.js";
 import { agentsContract } from "./contracts/agents.contract.js";
+import { approvalsContract } from "./contracts/approvals.contract.js";
 import { automationsContract } from "./contracts/automations.contract.js";
 import { capabilitiesContract } from "./contracts/capabilities.contract.js";
 import { choresContract } from "./contracts/chores.contract.js";
 import { ciContract } from "./contracts/ci.contract.js";
 import { claudeContract } from "./contracts/claude.contract.js";
 import { cursorContract } from "./contracts/cursor.contract.js";
-import { draftsContract } from "./contracts/drafts.contract.js";
 import { endpointsContract } from "./contracts/endpoints.contract.js";
 import { exitContract } from "./contracts/exit.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
@@ -26,8 +26,10 @@ import { panelsContract } from "./contracts/panels.contract.js";
 import { portsContract } from "./contracts/ports.contract.js";
 import { publicContract } from "./contracts/public.contract.js";
 import { prepushContract } from "./contracts/prepush.contract.js";
+import { keysContract } from "./contracts/keys.contract.js";
 import { providersContract } from "./contracts/providers.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
+import { safetyContract } from "./contracts/safety.contract.js";
 import { secretsContract } from "./contracts/secrets.contract.js";
 import { sessionsContract } from "./contracts/sessions.contract.js";
 import { settingsContract } from "./contracts/settings.contract.js";
@@ -43,13 +45,13 @@ import { workspaceContract } from "./contracts/workspace.contract.js";
 export { activityContract } from "./contracts/activity.contract.js";
 export { agentContract } from "./contracts/agent.contract.js";
 export { agentsContract } from "./contracts/agents.contract.js";
+export { approvalsContract } from "./contracts/approvals.contract.js";
 export { automationsContract } from "./contracts/automations.contract.js";
 export { capabilitiesContract } from "./contracts/capabilities.contract.js";
 export { choresContract } from "./contracts/chores.contract.js";
 export { ciContract } from "./contracts/ci.contract.js";
 export { claudeContract } from "./contracts/claude.contract.js";
 export { cursorContract } from "./contracts/cursor.contract.js";
-export { draftsContract } from "./contracts/drafts.contract.js";
 export { endpointsContract, type TrialHealth, TrialStatusSchema, type TrialStatusResponse } from "./contracts/endpoints.contract.js";
 export { exitContract } from "./contracts/exit.contract.js";
 export { extensionsContract } from "./contracts/extensions.contract.js";
@@ -75,8 +77,10 @@ export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";
 export { publicContract } from "./contracts/public.contract.js";
 export { prepushContract } from "./contracts/prepush.contract.js";
+export { keysContract } from "./contracts/keys.contract.js";
 export { providersContract } from "./contracts/providers.contract.js";
 export { pushContract } from "./contracts/push.contract.js";
+export { safetyContract } from "./contracts/safety.contract.js";
 export { secretsContract } from "./contracts/secrets.contract.js";
 export { sessionsContract } from "./contracts/sessions.contract.js";
 export { settingsContract } from "./contracts/settings.contract.js";
@@ -89,6 +93,8 @@ export { vpnContract } from "./contracts/vpn.contract.js";
 export { workflowsContract } from "./contracts/workflows.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
 export * from "./events.js";
+export * from "./card-status.js";
+export * from "./mentions.js";
 export * from "./sse.js";
 export * from "./routes.js";
 /* THE CONTAINER'S FIXED DIRECTORY LAYOUT, re-exported so extensions can reach it.
@@ -106,10 +112,18 @@ export * from "./workspace-state.js";
 export * from "./runtime-state.js";
 export * from "./state-portability.js";
 export * from "./history-state.js";
+/* THE PROVIDER VOCABULARY, bottom-up: what each agentic loop can do (agent-runtimes), the one row-per-provider
+ * table built on those records (provider-specs), and the shapes each surface reads that table in
+ * (agent-catalog). Exported as three modules rather than folded into one, because the arrow between them only
+ * points one way and saying so here is what stops it curling back. */
+export * from "./agent-runtimes.js";
+export * from "./provider-specs.js";
 export * from "./agent-catalog.js";
 export * from "./agent-run-model.js";
 export * from "./capability-env.js";
 export * from "./command-classes.js";
+export * from "./command-run.js";
+export * from "./safety-policy.js";
 export * from "./credential-material.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
@@ -121,12 +135,14 @@ export * from "./webext-links.js";
 export * from "./runner-protocol.js";
 export * from "./listener-protocol.js";
 export * from "./hostnames.js";
+export * from "./overlay-lint.js";
 export * from "./model-order.js";
+export * from "./plan-pools.js";
 export * from "./path-refs.js";
 export * from "./prompt-complexity.js";
 export * from "./quick-model.js";
 export * from "./output-fields.js";
-export * from "./publish-drafts.js";
+export * from "./approvals-execution.js";
 /* The wire shapes, one module per subject area, mirroring `contracts/` above: every request and response the
  * daemon speaks is declared in exactly one of them. Inputs that carry a `{param}` in their route path (repo /
  * id / name) merge the path param into the same flat object, oRPC fills the path placeholder from the matching
@@ -137,13 +153,13 @@ export * from "./publish-drafts.js";
 export * from "./schemas/activity.js";
 export * from "./schemas/agent.js";
 export * from "./schemas/agents.js";
+export * from "./schemas/approvals.js";
 export * from "./schemas/automations.js";
 export * from "./schemas/capabilities.js";
 export * from "./schemas/ci.js";
 export * from "./schemas/claude-gate.js";
 export * from "./schemas/codebase-health.js";
 export * from "./schemas/computers.js";
-export * from "./schemas/drafts.js";
 export * from "./schemas/engines.js";
 export * from "./schemas/environment.js";
 export * from "./schemas/exit.js";
@@ -183,6 +199,7 @@ export * from "./schemas/workspace-repos.js";
 export * from "./schemas/workspace-search.js";
 export * from "./schemas/workspace-setup.js";
 export * from "./schemas/workspace-tree.js";
+export * from "./arrival.js";
 export * from "./definition.js";
 export * from "./search-globs.js";
 export * from "./starter.js";
@@ -198,16 +215,17 @@ export const sandboxContract = {
     activity: activityContract,
     agent: agentContract,
     agents: agentsContract,
+    approvals: approvalsContract,
     automations: automationsContract,
     capabilities: capabilitiesContract,
     chores: choresContract,
     ci: ciContract,
     claude: claudeContract,
     cursor: cursorContract,
-    drafts: draftsContract,
     endpoints: endpointsContract,
     extensions: extensionsContract,
     personas: personasContract,
+    safety: safetyContract,
     sessions: sessionsContract,
     settings: settingsContract,
     share: shareContract,
@@ -225,6 +243,7 @@ export const sandboxContract = {
     ports: portsContract,
     public: publicContract,
     prepush: prepushContract,
+    keys: keysContract,
     providers: providersContract,
     push: pushContract,
     secrets: secretsContract,

package/src/ingress-protocol.ts

@@ -8,7 +8,7 @@ import {
     type ServerHttp2Stream,
 } from "node:http2";
 import { type AddressInfo, createServer as createNetServer, connect as netConnect, type Socket } from "node:net";
-import type { Duplex } from "node:stream";
+import { Duplex } from "node:stream";
 
 /* THE DATA PLANE OF THE INGRESS TUNNEL: both halves of it, over any node Duplex, in node core alone.
  *
@@ -572,3 +572,54 @@ export const serveIngressSession = async (duplex: Duplex, options: ServeIngressS
         },
     };
 };
+
+/* ── THE WEBSOCKET, AS A DUPLEX ──────────────────────────────────────────────────────────────────────────
+ *
+ * `ws` ships this as `createWebSocketStream`, and BUN DOES NOT IMPLEMENT IT: the call throws
+ * `Error("Not supported yet in Bun")` out of ws's `Receiver` constructor (verified on 1.3.14, on 1.4.0, and on
+ * 1.4.1). The edge runs on Bun, and the throw landed inside its `upgrade` handler with no
+ * `try` of ours on the stack — so the FIRST sandbox to register a tunnel killed the process, taking every
+ * other sandbox's tunnel with it, and the container restarted straight into the same crash when that
+ * sandbox retried. It is the reason a hosted sandbox could be provisioned and then never come up.
+ *
+ * Reimplementing it is a dozen lines and buys more than the fix: both halves of the tunnel now get the same
+ * bytes on Bun and on node, so the runtime stops being a variable on the hot path. It belongs in this file
+ * because this file already owns both halves and the property below is one of its stated invariants.
+ *
+ * THE PROPERTY TO PRESERVE is the BYTE SAFETY note at the top: the write callback fires only once the socket
+ * has taken the frame (`send(chunk, …, callback)`), so the stream owns each chunk until it is out and no
+ * pooled Buffer is ever handed to an asynchronous writer. `read()` is a no-op because the socket pushes —
+ * there is nothing to pull — and a closed socket ends the readable side with `push(null)` so an h2 session
+ * over it sees a clean EOF rather than a hang. */
+export interface TunnelWebSocket {
+    readonly send: (data: Buffer, options: { binary: boolean }, callback: (error?: Error) => void) => void;
+    readonly close: () => void;
+    readonly on: {
+        (event: `message`, listener: (data: unknown) => void): unknown;
+        (event: `close`, listener: () => void): unknown;
+        (event: `error`, listener: (error: Error) => void): unknown;
+    };
+}
+
+export const webSocketDuplex = (socket: TunnelWebSocket): Duplex => {
+    const duplex = new Duplex({
+        read: () => {},
+        write: (chunk: Buffer, _encoding, callback) => {
+            socket.send(chunk, { binary: true }, (error) => callback(error ?? null));
+        },
+        // Half-closing a WebSocket is not a thing: ending the writable side ends the socket, which is what
+        // every caller here means by it (a session that has written its GOAWAY is done with the transport).
+        final: (callback) => {
+            socket.close();
+            callback();
+        },
+    });
+    // `message` carries a Buffer for binary frames under both ws and Bun; a text frame (nothing on this
+    // protocol sends one) would arrive as a string, and coercing it is cheaper than dropping bytes silently.
+    socket.on(`message`, (data: unknown) => {
+        duplex.push(Buffer.isBuffer(data) ? data : Buffer.from(data as string));
+    });
+    socket.on(`close`, () => duplex.push(null));
+    socket.on(`error`, (error: Error) => duplex.destroy(error));
+    return duplex;
+};

package/src/mentions.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { mentionedPathTokens, mentionPaths } from "./mentions.js";
+
+describe(`mentionPaths`, () => {
+    it(`extracts path-looking tokens, deduped, with trailing punctuation stripped`, () => {
+        expect(mentionPaths(`see @src/app.ts and @readme.md, plus @src/app.ts again`)).toEqual([`src/app.ts`, `readme.md`]);
+    });
+
+    it(`skips prose handles and mid-word @`, () => {
+        expect(mentionPaths(`thanks @radarsu — mail me@example.com`)).toEqual([]);
+    });
+
+    it(`skips scoped package script prefixes in copied pnpm output`, () => {
+        expect(mentionPaths(`@intentic/iq-engine:test: failed\nsee @src/app.ts`)).toEqual([`src/app.ts`]);
+    });
+});
+
+describe(`mentionedPathTokens`, () => {
+    it(`keeps the package-script shape the composer refuses, so a transcript can still recognise it inline`, () => {
+        expect(mentionedPathTokens(`@intentic/iq-engine:test: failed\nsee @src/app.ts`)).toEqual([`intentic/iq-engine:test`, `src/app.ts`]);
+    });
+});

package/src/mentions.ts

@@ -0,0 +1,25 @@
+/* @-FILE MENTIONS, the two readers of the same text: the composer, which sends every path a message names as
+ * an attachment (the daemon resolves workspace-relative paths and folds them into the prompt as a Read-tool
+ * note, no upload involved), and the fold, which draws a message's UPLOADED files as chips and its inline
+ * mentions as nothing at all, because they are already visible in the words. One tokenizer, so what the
+ * composer counts as a mention is what the transcript declines to redraw. */
+
+// Every path-looking @ token in text, including tokens that are not valid composer mentions. Broad on purpose:
+// old turns persisted these candidates in the shared attachment field, and the fold needs the broad set to
+// recognise and hide those inline paths rather than redraw them as file chips.
+export const mentionedPathTokens = (text: string): string[] => {
+    const paths = new Set<string>();
+    for (const match of text.matchAll(/(?:^|\s)@([^\s@]+)/g)) {
+        const token = (match[1] as string).replace(/[.,;:!?)]+$/, ``);
+        if (token.includes(`/`) || token.includes(`.`)) {
+            paths.add(token);
+        }
+    }
+    return [...paths];
+};
+
+// Workspace paths referenced as @-mentions in a prompt, deduped. A scoped package script prefix from copied
+// pnpm output has the same opening shape (`@scope/package:test:`) but is not a file; accepting it hands the
+// daemon a phantom attachment which only becomes visible when a transcript redraws the wire fields.
+const PACKAGE_SCRIPT = /^[^/]+\/[^/]+:[^/]+$/u;
+export const mentionPaths = (text: string): string[] => mentionedPathTokens(text).filter((token) => !PACKAGE_SCRIPT.test(token));

package/src/needs-action.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+/* ONE "DO THIS BY HAND" LINE, the honesty unit three surfaces share: what an arrival could not do for the
+ * owner (arrival.ts), what a derived definition could not express (definition.ts), and where a runner has
+ * drifted from its parent (runner-protocol.ts). A subject the UI bolds, a detail written as an instruction.
+ *
+ * It lives in its own leaf module because runner-protocol.ts speaks it, and THAT file is imported by
+ * schemas/agent.ts, which definition.ts imports — the schema living in definition.ts made a cycle that left
+ * schemas half-initialized under module-eval.
+ *
+ * The name says the FIELD it fills (`needsAction`) rather than any one surface, because naming it for the
+ * definition is what let the arrival surfaces drift apart in the first place. */
+export const NeedsActionSchema = z.object({ subject: z.string(), detail: z.string() });
+export type NeedsAction = z.infer<typeof NeedsActionSchema>;

package/src/overlay-lint.test.ts

@@ -0,0 +1,89 @@
+import { expect, test } from "vitest";
+import { hasOfficialBase, invalidExtensionFragment, isOfficialSandboxImage, lintOverlay, overlayBase, rewriteOverlayBase } from "./overlay-lint.js";
+
+test("accepts a RUN/ENV-only fragment, comments and blank lines included", () => {
+    const fragment = `# install the postgres client\nRUN apt-get update && apt-get install -y postgresql-client\nENV PGCLIENT=1\n`;
+    expect(invalidExtensionFragment(fragment)).toBeUndefined();
+});
+
+test("accepts a line-continued RUN body", () => {
+    const fragment = `RUN set -eux; \\\n    apt-get update; \\\n    apt-get install -y whisper\n`;
+    expect(invalidExtensionFragment(fragment)).toBeUndefined();
+});
+
+test("rejects FROM in a fragment (the daemon owns the base pin)", () => {
+    expect(invalidExtensionFragment(`FROM ubuntu:24.04\nRUN echo hi`)).toBe(`FROM ubuntu:24.04`);
+});
+
+test("rejects a non-RUN/ENV instruction in a fragment", () => {
+    expect(invalidExtensionFragment(`RUN echo ok\nCOPY x /x`)).toBe(`COPY x /x`);
+    expect(invalidExtensionFragment(`USER root`)).toBe(`USER root`);
+});
+
+test("rejects a privileged runtime directive, even hidden in a comment or a continued body", () => {
+    expect(invalidExtensionFragment(`# intentic:runtime --privileged`)).toBe(`# intentic:runtime --privileged`);
+    expect(invalidExtensionFragment(`RUN true \\\n    # intentic:runtime --cap-add=NET_ADMIN`)).toBe(`    # intentic:runtime --cap-add=NET_ADMIN`);
+});
+
+test("the official image is the published sandbox under any tag", () => {
+    expect(isOfficialSandboxImage(`ghcr.io/intentic/sandbox:stable`)).toBe(true);
+    expect(isOfficialSandboxImage(`ghcr.io/intentic/sandbox:1.52.0`)).toBe(true);
+    expect(isOfficialSandboxImage(`ghcr.io/intentic/sandbox:`)).toBe(false);
+    expect(isOfficialSandboxImage(`intentic-sandbox:dev`)).toBe(false);
+    expect(isOfficialSandboxImage(`ghcr.io/intentic/sandbox:stable extra`)).toBe(false);
+});
+
+test("overlayBase reads the first instruction's FROM and nothing else", () => {
+    expect(overlayBase(`# composed\n\nFROM ghcr.io/intentic/sandbox:stable\nRUN true\n`)).toBe(`ghcr.io/intentic/sandbox:stable`);
+    expect(overlayBase(`RUN true\nFROM ghcr.io/intentic/sandbox:stable\n`)).toBeUndefined();
+    expect(overlayBase(``)).toBeUndefined();
+});
+
+test("hasOfficialBase pins the first instruction to the official sandbox image", () => {
+    expect(hasOfficialBase("FROM ghcr.io/intentic/sandbox:stable\nRUN true\n")).toBe(true);
+    expect(hasOfficialBase("# comment\n\nFROM ghcr.io/intentic/sandbox:1.52.0\nRUN true\n")).toBe(true);
+    expect(hasOfficialBase("FROM alpine:latest\n")).toBe(false);
+    expect(hasOfficialBase("FROM ghcr.io/intentic/sandbox:\n")).toBe(false);
+    expect(hasOfficialBase("RUN true\nFROM ghcr.io/intentic/sandbox:stable\n")).toBe(false);
+    expect(hasOfficialBase("")).toBe(false);
+});
+
+const COMPOSED =
+    `# Composed by the intentic sandbox daemon: do not edit by hand.\n\n` +
+    `FROM ghcr.io/intentic/sandbox:stable\n\n` +
+    `# docker capability: this directive grants dockerd the privileges it needs\n` +
+    `# intentic:runtime --privileged\n\n` +
+    `# ---- custom (owner-approved) ----\n` +
+    `RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\\n` +
+    `    apt-get update && apt-get install -y --no-install-recommends gnucobol\n` +
+    `ENV COBOL=1\n`;
+
+test("lintOverlay accepts a composed overlay: official FROM, runtime directive comments, RUN/ENV", () => {
+    expect(lintOverlay(COMPOSED)).toBeUndefined();
+});
+
+test("lintOverlay names the line that breaks the grammar", () => {
+    expect(lintOverlay(`FROM alpine:3.20\nRUN true\n`)).toBe(`FROM alpine:3.20`);
+    expect(lintOverlay(`RUN true\nFROM ghcr.io/intentic/sandbox:stable\n`)).toBe(`RUN true`);
+    expect(lintOverlay(`FROM ghcr.io/intentic/sandbox:stable\nCOPY . /work\n`)).toBe(`COPY . /work`);
+    expect(lintOverlay(`FROM ghcr.io/intentic/sandbox:stable\nRUN true\nFROM ghcr.io/intentic/sandbox:beta\n`)).toBe(
+        `FROM ghcr.io/intentic/sandbox:beta`,
+    );
+    expect(lintOverlay(`FROM ghcr.io/intentic/sandbox:stable\nUSER nobody\n`)).toBe(`USER nobody`);
+});
+
+test("lintOverlay refuses an overlay with nothing to build", () => {
+    expect(lintOverlay(``)).toBe(``);
+    expect(lintOverlay(`# only a comment\n`)).toBe(``);
+});
+
+test("rewriteOverlayBase changes the first FROM and nothing else", () => {
+    const rewritten = rewriteOverlayBase(COMPOSED, `ghcr.io/intentic/sandbox:1.53.0`);
+    expect(overlayBase(rewritten)).toBe(`ghcr.io/intentic/sandbox:1.53.0`);
+    expect(rewritten.replace(`FROM ghcr.io/intentic/sandbox:1.53.0`, `FROM ghcr.io/intentic/sandbox:stable`)).toBe(COMPOSED);
+});
+
+test("rewriteOverlayBase leaves content alone when the first instruction is not a FROM", () => {
+    expect(rewriteOverlayBase(`RUN true\n`, `ghcr.io/intentic/sandbox:stable`)).toBe(`RUN true\n`);
+    expect(rewriteOverlayBase(``, `ghcr.io/intentic/sandbox:stable`)).toBe(``);
+});

package/src/overlay-lint.ts

@@ -0,0 +1,116 @@
+/* WHAT AN ENVIRONMENT OVERLAY MAY SAY, read the same way by everyone who handles one.
+ *
+ * An overlay is the Dockerfile that extends the sandbox image for one sandbox: a pinned FROM, the enabled
+ * capabilities' fragments, and the custom section the owner approved. Three readers apply the same grammar
+ * at three trust levels, and none of them may trust the one before:
+ *   • the daemon admits an EXTENSION's fragment only if it is RUN/ENV (capabilities/handlers/extension.ts at
+ *     install, environment/fragment-sources.ts again at compose, in case the checkout changed);
+ *   • the daemon pins the composed file's first instruction to the official image (environment.ts);
+ *   • the platform builds a HOSTED sandbox's overlay on a machine of its own, from content that reached it
+ *     through an agent-writable volume and a browser, so it re-checks all of it before any machine exists.
+ * Text in, verdict out. No filesystem and no services, so the platform imports this the way it imports
+ * tunnel-ids, and the ic binary's Rust twin (recreate.rs `overlay_base`, runner.rs) reads the same shape. */
+
+// The marker the rebuild executors read runtime privileges from (`# intentic:runtime --privileged`, the
+// docker run flag it becomes is allowlisted there). A fragment that can be written by anything but the
+// daemon's own code must not carry it, in a comment or anywhere else.
+const RUNTIME_DIRECTIVE = "intentic:runtime";
+
+const OFFICIAL_SANDBOX_IMAGE = /^ghcr\.io\/intentic\/sandbox:\S+$/;
+
+// The published sandbox image under any tag, the only base an overlay may extend.
+export const isOfficialSandboxImage = (ref: string): boolean => OFFICIAL_SANDBOX_IMAGE.test(ref);
+
+interface OverlayLine {
+    readonly raw: string;
+    // `body` is a line inside a `\`-continued instruction, which carries no keyword of its own.
+    readonly kind: "blank" | "comment" | "instruction" | "body";
+}
+
+// Continuation-aware: a `\` at the end of any line, comments included, makes the next line a body line.
+const overlayLines = (content: string): OverlayLine[] => {
+    let continued = false;
+    return content.split("\n").map((raw) => {
+        const line = raw.trim();
+        const wasContinued = continued;
+        continued = line.endsWith("\\");
+        const kind = line === "" ? "blank" : line.startsWith("#") ? "comment" : wasContinued ? "body" : "instruction";
+        return { raw, kind };
+    });
+};
+
+const FROM = /^from\s+(\S+)/i;
+const RUN_OR_ENV = /^(run|env)\s/i;
+
+/* An extension fragment may install and set variables, and nothing else. FROM is refused because the daemon
+ * owns the base pin; every other instruction because there is no build context to COPY from and nothing an
+ * extension has any business doing to USER, ENTRYPOINT or EXPOSE; and the runtime directive anywhere,
+ * because an out-of-band executor greps for it and a comment is exactly where it would hide. Answers the
+ * offending line, or undefined when the fragment is clean. */
+export const invalidExtensionFragment = (content: string): string | undefined => {
+    for (const { raw, kind } of overlayLines(content)) {
+        if (raw.includes(RUNTIME_DIRECTIVE)) {
+            return raw;
+        }
+        if (kind === "instruction" && !RUN_OR_ENV.test(raw.trim())) {
+            return raw;
+        }
+    }
+    return undefined;
+};
+
+// The image a composed overlay extends: the first instruction, when it is a FROM.
+export const overlayBase = (content: string): string | undefined => {
+    const first = overlayLines(content).find((line) => line.kind === "instruction");
+    return first === undefined ? undefined : FROM.exec(first.raw.trim())?.[1];
+};
+
+// Whether the overlay's first instruction pins it to the official sandbox image.
+export const hasOfficialBase = (content: string): boolean => {
+    const base = overlayBase(content);
+    return base !== undefined && isOfficialSandboxImage(base);
+};
+
+/* A whole composed overlay, as an executor that did not compose it must read it: one leading FROM on the
+ * official image, then RUN and ENV only. Comments pass, the runtime directive included, since a composed
+ * overlay is where the daemon's own capability fragments put it and the executor that honours it (ic) reads
+ * it from there; an executor that cannot honour it (a VM is already privileged) ignores it. Answers the
+ * offending line, or undefined. An overlay with no instruction at all is refused: there is nothing to build. */
+export const lintOverlay = (content: string): string | undefined => {
+    let first = true;
+    for (const { raw, kind } of overlayLines(content)) {
+        if (kind !== "instruction") {
+            continue;
+        }
+        const line = raw.trim();
+        if (first) {
+            first = false;
+            const base = FROM.exec(line)?.[1];
+            if (base === undefined || !isOfficialSandboxImage(base)) {
+                return raw;
+            }
+            continue;
+        }
+        if (!RUN_OR_ENV.test(line)) {
+            return raw;
+        }
+    }
+    return first ? "" : undefined;
+};
+
+/* The same overlay on a different base: the first FROM rewritten, everything else byte-identical. An
+ * executor applies an approved recipe on the base IT runs (a newer release than the one the daemon composed
+ * against, a rollback pin), and hashes the content the owner approved rather than this rewrite, so the
+ * environment hash stays the reviewed one. Content whose first instruction is not a FROM is returned as is. */
+export const rewriteOverlayBase = (content: string, base: string): string => {
+    let done = false;
+    return overlayLines(content)
+        .map(({ raw, kind }) => {
+            if (done || kind !== "instruction") {
+                return raw;
+            }
+            done = true;
+            return FROM.test(raw.trim()) ? raw.replace(FROM, `FROM ${base}`) : raw;
+        })
+        .join("\n");
+};

package/src/owner-ticket.test.ts

@@ -0,0 +1,54 @@
+import { generateKeyPairSync } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { mintReachabilityGrant, verifyReachabilityGrant } from "./ingress-contract.js";
+import { isOwnerTicket, mintOwnerTicket, OWNER_TICKET_TTL_MS, publicKeyPemOf, verifyOwnerTicket } from "./owner-ticket.js";
+
+const pair = generateKeyPairSync("ed25519");
+const privatePem = pair.privateKey.export({ type: "pkcs8", format: "pem" }) as string;
+const publicPem = pair.publicKey.export({ type: "spki", format: "pem" }) as string;
+const NOW = 1_800_000_000_000;
+
+describe("owner ticket", () => {
+    it("round-trips the claim and expires when it says", () => {
+        const ticket = mintOwnerTicket(privatePem, { sandboxId: "0123456789ab", email: "Owner@Example.com", issuedAtMs: NOW });
+        expect(isOwnerTicket(ticket)).toBe(true);
+        expect(verifyOwnerTicket(publicPem, ticket, NOW + 1_000)).toEqual({
+            sandboxId: "0123456789ab",
+            // Lowercased at mint, the way the daemon's owner store and the platform's rows spell an address.
+            email: "owner@example.com",
+            issuedAt: Math.floor(NOW / 1000),
+            expiresAt: Math.floor((NOW + OWNER_TICKET_TTL_MS) / 1000),
+        });
+        expect(verifyOwnerTicket(publicPem, ticket, NOW + OWNER_TICKET_TTL_MS + 1_000)).toBeUndefined();
+    });
+
+    it("derives the public half the machine env carries from the platform's private key", () => {
+        const ticket = mintOwnerTicket(privatePem, { sandboxId: "0123456789ab", email: "o@x.dev", issuedAtMs: NOW });
+        expect(verifyOwnerTicket(publicKeyPemOf(privatePem), ticket, NOW)).toMatchObject({ sandboxId: "0123456789ab", email: "o@x.dev" });
+    });
+
+    it("refuses another key's signature, a tampered claim, and garbage", () => {
+        const other = generateKeyPairSync("ed25519").publicKey.export({ type: "spki", format: "pem" }) as string;
+        const ticket = mintOwnerTicket(privatePem, { sandboxId: "0123456789ab", email: "o@x.dev", issuedAtMs: NOW });
+        expect(verifyOwnerTicket(other, ticket, NOW)).toBeUndefined();
+        const [prefix, , signature] = ticket.split(".");
+        const forged = Buffer.from(JSON.stringify({ sub: "0123456789ab", email: "thief@x.dev", iat: 1, exp: 9e9 })).toString("base64url");
+        expect(verifyOwnerTicket(publicPem, `${prefix}.${forged}.${signature}`, NOW)).toBeUndefined();
+        expect(verifyOwnerTicket(publicPem, "not a ticket", NOW)).toBeUndefined();
+        expect(isOwnerTicket("ig1.x.y")).toBe(false);
+    });
+
+    /* One key signs both the reachability grant and the owner ticket, and neither may ever pass as the other:
+     * a grant is a sandbox's right to serve its hostnames, a ticket is a person's right to drive it. */
+    it("is never a reachability grant, and a grant is never a ticket", () => {
+        const ticket = mintOwnerTicket(privatePem, { sandboxId: "0123456789ab", email: "o@x.dev", issuedAtMs: NOW });
+        const grant = mintReachabilityGrant(privatePem, "0123456789ab", NOW);
+        expect(verifyReachabilityGrant(publicPem, ticket)).toBeUndefined();
+        expect(verifyOwnerTicket(publicPem, grant, NOW)).toBeUndefined();
+    });
+
+    it("refuses to mint for anything but a real sandbox id and an owner", () => {
+        expect(() => mintOwnerTicket(privatePem, { sandboxId: "nope", email: "o@x.dev", issuedAtMs: NOW })).toThrow();
+        expect(() => mintOwnerTicket(privatePem, { sandboxId: "0123456789ab", email: "", issuedAtMs: NOW })).toThrow();
+    });
+});

package/src/owner-ticket.ts

@@ -0,0 +1,102 @@
+import { createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
+
+/* THE OWNER TICKET: the platform's signed word for who owns a HOSTED sandbox, so the browser that just signed in
+ * to the platform can sign in to that sandbox's daemon without being asked for Google a second time.
+ *
+ * THE RULE IT BENDS, AND WHY THAT IS ALLOWED HERE. Every sandbox authenticates its owner against Google itself
+ * (the daemon's auth/auth.ts): the platform never holds or forges a daemon credential, so a platform breach can
+ * read a sandbox's address and drive nothing. That rule stands for every lane but one. On the HOSTED lane the
+ * platform already creates the machine, holds its power and its disk, and injects its owner's email into its
+ * env before the daemon ever runs (ARCHITECTURE.md names this the stated exception). A platform that can already
+ * open the machine gains no new power from being able to say "this browser is the owner" to it, and the user
+ * gains the one thing the second Google prompt was costing: a sign-in that is one sign-in.
+ *
+ * So a hosted daemon, and only a hosted daemon, accepts a ticket the platform signs with the SAME Ed25519 key
+ * that signs reachability grants (ingress-contract.ts), verified offline against the public half the machine's
+ * env carries (ENV_PLATFORM_PUBLIC_KEY, set by the provisioner and by nothing else). The ticket names the
+ * sandbox (its 12-hex id, which the daemon checks against its own) and the owner's email (which the daemon
+ * checks against OWNER_EMAIL on first-bind, exactly as it checks a Google proof), and it expires in minutes:
+ * it is spent once, on the daemon's /system/session, for the same daemon-minted session a Google proof buys.
+ *
+ * A different prefix from the grant's, so neither can ever be presented as the other: a grant verifies only as
+ * a grant, a ticket only as a ticket, under one key. */
+
+const TICKET_PREFIX = "ot1";
+
+// Long enough for the exchange it exists for (one round trip to the daemon after the platform answers), short
+// enough that a ticket lifted from a network log is worthless by the time anyone reads it.
+export const OWNER_TICKET_TTL_MS = 5 * 60_000;
+
+// The env var a hosted machine carries the platform's public key in (PEM, SPKI). Absent on every other lane,
+// which is what keeps the ticket a hosted-only credential: a daemon with no key verifies no ticket.
+export const ENV_PLATFORM_PUBLIC_KEY = "PLATFORM_PUBLIC_KEY";
+
+const base64url = (bytes: Buffer): string => bytes.toString("base64url");
+const SANDBOX_ID = /^[0-9a-f]{12}$/;
+
+// The signed claim, times in seconds like the grant's.
+export interface OwnerTicket {
+    readonly sandboxId: string;
+    readonly email: string;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+}
+
+export const isOwnerTicket = (bearer: string): boolean => bearer.startsWith(`${TICKET_PREFIX}.`);
+
+export const mintOwnerTicket = (
+    privateKeyPem: string,
+    claim: { readonly sandboxId: string; readonly email: string; readonly issuedAtMs: number; readonly ttlMs?: number },
+): string => {
+    if (!SANDBOX_ID.test(claim.sandboxId)) {
+        throw new Error(`an owner ticket names a 12-hex sandbox id, got "${claim.sandboxId}"`);
+    }
+    if (claim.email === "") {
+        throw new Error("an owner ticket names an owner");
+    }
+    const iat = Math.floor(claim.issuedAtMs / 1000);
+    const exp = Math.floor((claim.issuedAtMs + (claim.ttlMs ?? OWNER_TICKET_TTL_MS)) / 1000);
+    const payload = Buffer.from(JSON.stringify({ sub: claim.sandboxId, email: claim.email.toLowerCase(), iat, exp }), "utf8");
+    const signature = edSign(null, payload, createPrivateKey(privateKeyPem));
+    return `${TICKET_PREFIX}.${base64url(payload)}.${base64url(signature)}`;
+};
+
+/* Verify a ticket against the platform's public key, at `nowMs`. Undefined for every way of not being a valid
+ * ticket: the wrong prefix, a bad signature, a malformed claim, or one past its expiry. The CALLER checks that
+ * `sandboxId` is its own and that `email` is the owner it expects: those are the daemon's facts, not this
+ * function's. */
+export const verifyOwnerTicket = (publicKeyPem: string, token: string, nowMs: number): OwnerTicket | undefined => {
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts[0] !== TICKET_PREFIX) {
+        return undefined;
+    }
+    try {
+        const payload = Buffer.from(parts[1] as string, "base64url");
+        const signature = Buffer.from(parts[2] as string, "base64url");
+        if (!edVerify(null, payload, createPublicKey(publicKeyPem), signature)) {
+            return undefined;
+        }
+        const parsed = JSON.parse(payload.toString("utf8")) as { sub?: unknown; email?: unknown; iat?: unknown; exp?: unknown };
+        if (
+            typeof parsed.sub !== "string" ||
+            !SANDBOX_ID.test(parsed.sub) ||
+            typeof parsed.email !== "string" ||
+            parsed.email === "" ||
+            typeof parsed.iat !== "number" ||
+            typeof parsed.exp !== "number"
+        ) {
+            return undefined;
+        }
+        if (parsed.exp * 1000 <= nowMs) {
+            return undefined;
+        }
+        return { sandboxId: parsed.sub, email: parsed.email, issuedAt: parsed.iat, expiresAt: parsed.exp };
+    } catch {
+        return undefined;
+    }
+};
+
+// The public half of the platform's signing key, in the PEM the daemon's env carries. Derived rather than
+// configured: one key, two readers (the ingress and every hosted daemon), no second value to keep in step.
+export const publicKeyPemOf = (privateKeyPem: string): string =>
+    createPublicKey(createPrivateKey(privateKeyPem)).export({ type: "spki", format: "pem" }) as string;