@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/fast-tier.ts

@@ -1,72 +0,0 @@
-import { compareCheapestFirst, isCheaperRung } from "./model-order.js";
-import { parsePinned } from "./model-pins.js";
-import type { AgentProvider } from "./schemas/agent.js";
-
-/* WHICH MODEL A DOWNGRADED TURN ACTUALLY RUNS ON, the second half of automatic tier selection.
- * prompt-complexity.ts decides a turn COULD be cheaper; this decides whether there is anything cheaper to put
- * it on, and names it.
- *
- * THERE IS NO "STANDARD TIER" SETTING, and its absence is the design rather than an omission. The standard tier
- * is whatever the user already picked for this conversation. So this mechanism can only ever route DOWN, from a
- * model somebody chose to a cheaper rung of the same catalog, which means the worst case of a wrong answer is
- * one turn's quality on a model the user can see and correct, never a bill they did not ask for. Every
- * ambiguous case in this file therefore resolves to `undefined`, which the caller reads as "run what they
- * asked for".
- *
- * THE PROVIDER IS NEVER CROSSED, and this is the constraint the rest of the app imposes rather than one this
- * file would have chosen. A conversation's provider session is resumed only while the selection still matches
- * the runtime and account that minted it (turnRequest.ts `resumes`, which compares provider, account and
- * harness, and pointedly NOT model). A model swap inside one provider is free, and the session carries on. A
- * provider swap RETIRES the session and cuts a new segment, which throws away the very context that made the
- * follow-up cheap to answer. So a cross-provider pin here is dropped rather than honoured: saving a fraction of
- * a cent by starting the conversation over is not a saving.
- *
- * THE ORDER IS A LADDER, for the reason model-pins.ts is one, but a shorter one: the caller spends the head
- * and falls back to the user's own pick, rather than walking rungs. A downgrade that cannot be started is not
- * worth a second attempt when the honest answer (their model) is sitting right there. */
-
-export interface FastTierInput {
-    // The provider this turn is on. Both the pick and every candidate belong to it; see above.
-    readonly provider: AgentProvider;
-    // The model the user picked, i.e. the standard tier and the ceiling. Empty when the composer has not
-    // resolved one yet, which resolves to no downgrade: there is nothing to be cheaper THAN.
-    readonly model: string;
-    // That provider's catalog as the caller can see it. Empty is a real state (a catalog that has not loaded),
-    // and it resolves to no downgrade rather than to a guess.
-    readonly models: readonly string[];
-    // settings.autoFastModels: an ordered list of `${provider}:${modelId}` keys (modelPinKey), or empty for
-    // Auto. Entries naming another provider are dropped, not honoured.
-    readonly pinned: readonly string[];
-}
-
-/* THE CHEAPER MODEL TO RUN THIS TURN ON, or undefined for "there isn't one, use their pick".
- *
- * A PIN IS TAKEN VERBATIM against the catalog, the same call resolveRoleModels makes and for the same reason:
- * the model picker offers a custom-id escape hatch for a model the static catalog has not caught up with, and
- * second-guessing the id here would run a different model than the settings row names. It is still checked for
- * being CHEAPER, because that is not a fact about the catalog, it is a fact about the id, and a pin that is not
- * cheaper than the pick is not a downgrade at all.
- *
- * AUTO IS THE CHEAPEST ROW THE PROVIDER PUBLISHES, read through the same cheap-end order the quick model uses,
- * so the two features cannot disagree about which rung is the cheap one. Derived, never stored: connect an
- * account tomorrow and the answer improves by itself, exactly as a one-shot role's empty list does.
- *
- * NOTHING CHEAPER THAN THE PICK ⇒ UNDEFINED, and that is the common case worth being exact about rather than
- * the edge case: a user already working on the cheap rung has nowhere to be sent, and a user on a model whose
- * family this build does not recognize is not going to be downgraded on a guess (isCheaperRung). */
-export const fastTierModel = (input: FastTierInput): string | undefined => {
-    if (input.model === "") {
-        return undefined;
-    }
-    const pinned = input.pinned
-        .flatMap((key) => {
-            const choice = parsePinned(key);
-            return choice === undefined || choice.provider !== input.provider ? [] : [choice.model];
-        })
-        .find((model) => isCheaperRung(model, input.model));
-    if (pinned !== undefined) {
-        return pinned;
-    }
-    const cheapest = input.models.toSorted(compareCheapestFirst)[0];
-    return cheapest !== undefined && isCheaperRung(cheapest, input.model) ? cheapest : undefined;
-};

package/src/history-state.ts

@@ -1,174 +0,0 @@
-import type { StateFile } from "./state-portability.js";
-
-/* WHAT LIVES ON /history, the second half of the daemon's state, and the half nothing declared until an
- * export had to reason about it.
- *
- * `WORKSPACE_STATE_FILES` covers `<workspace>/.intentic/`, which is where the manifests live. It is not where
- * the machinery lives. Every repo's REAL git dir is here (a repo's in-tree `.git` is a pointer file, see
- * git/repo-git-dirs.ts for the invariant that forces it), and so are the fleet registry, the turn journal, the
- * ledgers, the checkpoint scopes and the isolated agents' checkouts. A "workspace export" that took `/work`
- * alone would carry a tree of repos with dangling gitdir pointers, every git command in the restored sandbox
- * answering `fatal: not a git repository`, and an empty agent board.
- *
- * The two tables stay separate rather than becoming one keyed by volume, because they answer different
- * questions. A `.intentic` entry also declares which browser QUERY it makes stale, since the file watcher
- * reports it; nothing here is watched at all (that is the point of the volume), so an `invalidates` field on
- * these entries would be a column of empty arrays. What they share is the portability class, and that is
- * imported rather than duplicated.
- *
- * `history-state-coverage.test.ts` fails when a daemon store builds a `/history` path this list doesn't carry, in both
- * directions, the same shape-recognizing guard that covers the workspace table.
- */
-
-// Paths are historyRoot-relative, forward-slash, matched by PREFIX; a directory entry keeps its trailing slash
-// so it cannot prefix-match a sibling file. See stateFileFor for how nesting resolves.
-export const HISTORY_STATE_FILES: readonly StateFile[] = [
-    /* ---- the machinery a restored workspace is inert without ---- */
-
-    /* THE ONE THAT MAKES A BUNDLE A WORKSPACE. Every repo's real git dir, including the /work root's own
-     * ("root"), keyed by URI-encoded repo id. Carrying the working tree without this hands the target files
-     * whose `.git` points at a path that does not exist there, which is not a degraded repo but a broken one,
-     * and it takes the Changes review, the diff, land and every agent branch with it. The agent BRANCHES live
-     * in here too, which is what lets the checkouts below be left out. */
-    { path: "gits/", portability: "carry" },
-    // The checkpoint timeline (one bare repo per scope, snapshots on refs/snapshots/head). Restoring it is what
-    // makes "restore to before that turn" still reach back past the move.
-    { path: "scopes/", portability: "carry" },
-    // The fleet: every conversation card, its branch, its session ids, its standing.
-    { path: "agents.json", portability: "carry" },
-    { path: "turns/", portability: "carry" },
-    /* THE ARMED CONDITION WATCHES, one file per watch, put back at boot (agent/watchers.ts `restoreWatchers`).
-     *
-     * Carried for the reason loops.json is: an arrangement the agent entered into on the user's behalf and
-     * that is still outstanding travels with the conversation that is waiting on it, or a restored sandbox
-     * shows a card parked on a condition nothing will ever check. It can be carried safely because the journal
-     * holds no credential, only the NAMES of the environment its check ran with (agent/watch-journal.ts); the
-     * values are re-derived on the target from whatever capabilities it actually has, so a watch landing
-     * somewhere without them fails its check honestly and ends in a wake that says so, rather than arriving
-     * with a working copy of a token the bundle was never supposed to carry. A watch whose isolated checkout
-     * did not travel (those are `derived`) is dropped by the restore rather than re-armed against a tree that
-     * is not there. */
-    { path: "watches/", portability: "carry" },
-    { path: "transcripts/", portability: "carry" },
-    // What each message can be put back to, a workspace checkpoint, or an isolated conversation's own commits.
-    // Carried WITH the transcripts and the scopes above, because it is the join between them: without it a
-    // restored conversation reads back whole and offers no way back into it, even though both the messages and
-    // the states they name travelled.
-    { path: "turn-anchors.json", portability: "carry" },
-    /* WHICH CONVERSATIONS ARE PUBLISHED AS PAGES ANYONE WITH THE LINK CAN READ.
-     *
-     * Carried, and it is the entry with the most to say for itself: the PAGES live in the workspace's outbox
-     * (`public/`), so they travel with `/work` whatever this says. Leaving the index behind would restore a
-     * sandbox that is still serving somebody's conversation on the internet with nothing in the app that knows
-     * it, no row, no link, and no way to stop sharing short of deleting files by hand. The index is what makes
-     * a published page withdrawable, so it goes wherever the pages go. */
-    { path: "shares.json", portability: "carry" },
-    { path: "activity.jsonl", portability: "carry" },
-    { path: "usage.jsonl", portability: "carry" },
-    { path: "account-usage.json", portability: "carry" },
-    { path: "provider-refusals.json", portability: "carry" },
-    /* Which MODELS this sandbox's credentials were refused (usage/model-refusals.ts), the per-model half of the
-     * entry above and carried for the same reason: a bundle is this owner's sandbox on another machine, signing
-     * the same subscriptions back in, so a plan that does not cover a model there does not cover it here
-     * either, and the picker should arrive already clean. Cheap to be wrong about in the one case it can be
-     * (the target signs in a bigger plan): every entry is forgotten a day after it was written. */
-    { path: "model-refusals.json", portability: "carry" },
-    // Explicit first-time dependency setup requests. Carrying the worklist preserves the owner's decision when
-    // an export interrupts the queue before its terminal starts; fulfilled entries remove themselves.
-    { path: "dependency-requests.json", portability: "carry" },
-    // The deploy engine's own ledgers, a run's events and the check results the Pipelines view reads back.
-    { path: "apply-events.ndjson", portability: "carry" },
-    { path: "check-events/", portability: "carry" },
-
-    /* ---- regenerated by the target ---- */
-
-    /* THE DELIBERATE OMISSION, and the difference between a bundle of gigabytes and one of hundreds.
-     *
-     * A conversation's worktree is a full checkout of the monorepo per agent (plus its overlay upper dir), and
-     * there can be a hundred of them. None of it is unique: the branch it holds is in `gits/` above, and the
-     * registry entry naming it travels in agents.json, so an imported conversation arrives in exactly the
-     * shape the system already has a name for. `attached()` reports its checkout as absent, the board renders
-     * it, and the next turn's `ensure()` re-creates it from the recorded composition, which is the same path an
-     * archived agent takes when it runs again. The boot sweep's `git worktree prune` clears the stale admin
-     * entries the restored git dirs still carry. */
-    {
-        path: "worktrees/",
-        portability: "derived",
-        note: "Each conversation re-attaches its checkout from its branch on its next turn.",
-    },
-    /* The phrase index over what every conversation said, which both search boxes read (sessions/search-index.ts).
-     * Derived in the strict sense: every row in it was extracted from `transcripts/`, which travels, so a
-     * restored sandbox rebuilds it on its first boot rather than carrying tens of megabytes of index that its
-     * own backfill would produce anyway. Until that pass finishes the searches answer from what is indexed so
-     * far and say so, which is the behaviour they already have on any first run. */
-    { path: "said-index/", portability: "derived", note: "Rebuilt from the carried transcripts by the first boot's backfill." },
-    { path: "overlays/", portability: "derived" },
-    { path: "logs/", portability: "derived" },
-    { path: "trash/", portability: "derived" },
-    { path: ".isolation-probe", portability: "derived" },
-    /* The finished bundles themselves. `derived` is doing real work here rather than describing leftovers: an
-     * export that carried the export directory would pack every previous bundle into the new one, and the next
-     * 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 ---- */
-
-    // The ssh alias dir ~/.ssh/intentic-hosts symlinks to: per-host config, private keys and passphrases for
-    // every host capability and git remote the sandbox reaches.
-    {
-        path: "ssh-hosts/",
-        portability: "secret",
-        note: "Re-add each ssh host on the Capabilities view, its key does not travel.",
-    },
-    // The cli-proxy's config, which holds the routed subscriptions' provider tokens.
-    {
-        path: "translator/",
-        portability: "secret",
-        note: "Sign the routed AI subscriptions in again on the Agent tab.",
-    },
-
-    /* ---- identity: what binds this sandbox to its owner, its browsers and its host ---- */
-
-    /* Signs every browser session cookie. Carrying it would let a bundle's holder mint sessions against the
-     * target, an export becomes a credential, and the target minting its own costs exactly one sign-in. */
-    { path: "session-secret", portability: "identity", note: "Sign in again, the target signs its own sessions." },
-    {
-        path: "browser-access-disabled",
-        portability: "identity",
-        note: "Account-deletion retirement belongs to the source sandbox; the imported copy starts with fresh browser access.",
-    },
-    {
-        path: "push.json",
-        portability: "identity",
-        note: "Re-enable notifications in the browsers you use, a push subscription is bound to the sandbox that minted it.",
-    },
-    { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
-    { path: "sync-pair-consumed.json", portability: "identity" },
-    { path: "host-enrollments.json", portability: "identity" },
-    /* A connected BROWSER's enrollment (webext/webext-peer.ts). Identity for the hosts file's reason and one
-     * more of its own: the token admits a socket into somebody's signed-in browser, and that browser was paired
-     * with THIS sandbox — carried into another one it would either be dead weight or, worse, a second sandbox
-     * holding a live key to a browser its owner never connected it to. Re-pairing is a code and one click. */
-    { path: "webext-enrollments.json", portability: "identity", note: "Pair your browser again from its card: the extension is still installed." },
-    // The browser door's burn list: every peer door keeps one (peers/peer-store.ts), and a browser pairing
-    // redeemed here must not read as fresh in a sandbox this file travelled to. Identity, hosts' reason.
-    { path: "webext-pair-consumed.json", portability: "identity" },
-    // The burn list for setup-time device pairings. Identity, like sync's beside it, and for a sharper reason:
-    // carrying it into another sandbox would mark that sandbox's own fresh pairing as already spent.
-    { path: "host-pair-consumed.json", portability: "identity" },
-    // A runner's enrollment names THIS sandbox as its parent (runners/runner-peer.ts): in another sandbox the
-    // digest would admit a socket whose runner still dials the old parent. Identity, both files, hosts' reasons.
-    { path: "runner-enrollments.json", portability: "identity" },
-    { path: "runner-pair-consumed.json", portability: "identity" },
-    // The runner-SIDE half: who this container belongs to and the token its reconnects present
-    // (runners/runner-identity.ts). Carried into another box it would dial the parent as this runner.
-    { path: "runner-identity.json", portability: "identity" },
-    { path: "local-cert/", portability: "identity" },
-];

package/src/host-protocol.ts

@@ -1,36 +0,0 @@
-import { z } from "zod";
-
-/* The handshake on /system/hosts/connect, the ONE message that is not oRPC.
- *
- * Everything a connected device is asked lives in `hostContract` (contracts/host.contract.ts), spoken over
- * this socket by oRPC's websocket adapter: the machine hosts the server, the daemon holds the client. But a
- * socket has to prove whose it is before it can be given a typed client, and that proof cannot itself be an
- * oRPC call, the daemon has nothing to call yet, and would be attaching a link to a stranger.
- *
- * So the machine's first act is this frame, in plain JSON. The daemon verifies the token, learns which
- * capability the socket belongs to, and only then attaches the link; from that message on, every byte on the
- * wire is oRPC. Anything arriving before the link exists is either this frame or a closed socket. */
-
-// The MCP protocol revision the machine's tool server implements. Shared because the daemon answers the
-// handshake ITSELF when the machine is asleep (the daemon's peer bridge), two spellings of this would mean an
-// offline machine negotiating a different protocol than the same machine awake.
-export const MCP_PROTOCOL_VERSION = "2025-06-18";
-
-export const HostHelloSchema = z.object({
-    type: z.literal("hello"),
-    /* The machine's enrollment token, in the FIRST FRAME, never in the URL. A WebSocket has no headers to put
-     * it in, and the obvious `?token=` would write a durable key to somebody's laptop into Cloudflare's edge
-     * logs, the connector's logs and every proxy in between (the reasoning that moved the browser's upgrades
-     * onto one-shot tickets, auth/ws-tickets.ts). A frame is body, not URL, so it is logged nowhere. Until this
-     * arrives the socket is anonymous and short-lived: the daemon closes it in seconds if it never does. */
-    token: z.string(),
-    // The @intentic/machine build the machine is running, surfaced per machine so an old binary is visible rather
-    // than mysteriously missing a tool. What the machine IS (`describe`) is not here: it is pulled over the
-    // typed link a moment later, so there is one definition of those facts rather than two.
-    version: z.string(),
-});
-export type HostHello = z.infer<typeof HostHelloSchema>;
-
-// The URL the machine's agent dials, given the sandbox's public URL. Carries no credential, the token rides
-// the hello frame. One place builds it, so the agent and the daemon route can't disagree about where it lives.
-export const hostConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/hosts/connect`;

package/src/hostnames.ts

@@ -1,180 +0,0 @@
-// The single source for the tunnel/preview hostname + ingress scheme, shared by the CLI, platform API, daemon,
-// AND the browser. Pure string builders/parsers with NO node imports (unlike ./tunnel-ids, which needs
-// node:crypto for the digest), so the web bundle can import them and derive identical names. The caller supplies
-// the 12-hex id (sandboxIdFromToken/hostSshIdFromToken in node; WebCrypto in the browser).
-//
-// All four apps MUST agree on these strings: a divergence resolves to NXDOMAIN that resolvers negative-cache for
-// the zone's SOA TTL. This module is that agreement.
-
-// The sandbox daemon's subdomain + hostname: `sandbox-<id>` / `sandbox-<id>.<zone>`.
-const SANDBOX_PREFIX = "sandbox-";
-export const sandboxSubdomain = (id: string): string => `${SANDBOX_PREFIX}${id}`;
-export const sandboxHostname = (id: string, zone: string): string => `${sandboxSubdomain(id)}.${zone}`;
-
-// The container sshd hostname the desktop-sync (Mutagen) reaches over the sandbox tunnel: `ssh-<id>.<zone>`.
-export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zone}`;
-
-/* The LOOPBACK name: `<id>.local.<zone>`, resolving to 127.0.0.1 under ONE wildcard record for the whole zone.
- *
- * A public DNS name for a private address looks odd until you ask what the alternative is. A browser on the
- * same machine as the sandbox can reach its daemon in microseconds instead of crossing to a Cloudflare edge
- * and back, but only over HTTPS, because Safari refuses http://127.0.0.1 from an HTTPS page as mixed content
- * (WebKit 171934, open since 2017), and HTTPS needs a name a public CA will certify. An IP literal cannot have
- * one; this can. The daemon holds the key and gets the certificate by proving control of the zone over
- * DNS-01 (there is nothing on the public internet for a CA to connect to).
- *
- * IT IS A LABEL DEEPER THAN THE OTHER NAMES, and that is the entire point rather than a naming preference. A
- * DNS wildcard matches ONE label, so `*.<zone>` cannot cover `<id>.local.<zone>` and `*.local.<zone>` covers
- * every sandbox that will ever exist: one record for the platform, not one per sandbox. The shape it replaced,
- * `local-<id>.<zone>`, needed a record each, and a zone has a hard per-record quota (Cloudflare 81045). Every
- * OTHER per-sandbox record went away with the move to the zrok hub, so this was the last thing consuming that
- * quota, and when the zone filled the platform could no longer write the record OR the ACME challenge beside
- * it: the certified shortcut stopped resolving, every browser fell back to the plain-http loopback, and that
- * transport is HTTP/1.1 with six connections per origin (see the editor's streamBudget.ts for what that cost).
- * A quota nothing can exhaust is the fix that keeps working.
- *
- * It discloses nothing: the id is already the leading label of the sandbox's public hostname, and the address
- * it resolves to is every machine's own loopback. */
-export const localHostname = (id: string, zone: string): string => `${id}.${LOCAL_LABEL}.${zone}`;
-
-// The label the loopback names live under, so the wildcard has something to be a wildcard OF.
-export const LOCAL_LABEL = "local";
-
-// The single record that answers for all of them. Never per-sandbox, never reaped.
-export const localWildcardHostname = (zone: string): string => `*.${LOCAL_LABEL}.${zone}`;
-
-// What that record points at, and the reason it is safe to publish: every resolver on earth gets 127.0.0.1.
-export const LOCAL_ADDRESS = "127.0.0.1";
-
-// A per-host SSH tunnel's Cloudflare tunnel NAME (its hostname reuses sshHostname with the host-ssh id).
-export const hostSshTunnelName = (id: string): string => `host-ssh-${id}`;
-
-// The proxied-CNAME target every tunnel points its DNS record at.
-export const cfargotunnelCname = (tunnelId: string): string => `${tunnelId}.cfargotunnel.com`;
-
-// The cloudflared ingress catch-all, must be the LAST rule.
-export const CATCH_ALL = { service: "http_status:404" } as const;
-
-// Preview scheme: `preview-<panel>-<sandboxId>.<zone>`, one DNS label (the free Universal SSL `*.<zone>` cert
-// covers exactly one level), where <panel> is `<repo>` or `<repo>--<app>` and <sandboxId> pins the hostname to
-// this sandbox (the shared intentic zone hosts many sandboxes; without the id two users' panels would collide).
-// Port-forward scheme: `port-<slot>-<sandboxId>.<zone>`, the same shape with a `port-` prefix, where <slot>
-// is one of the sandbox's forward slots (portSlotsFromToken in ./tunnel-ids), not the port number itself:
-// slots keep the intentic-provided path's minted routes bounded and warm while dev servers churn ephemeral
-// ports. The slot labels are salted with the connect token rather than being the letters a…h, so a forwarded
-// port's hostname is not derivable from the (public) sandbox id alone, see tunnel-ids for why that matters.
-//
-// Outbox scheme: `public-<slot>-<sandboxId>.<zone>`, the same shape again, serving the workspace's `public/`
-// directory as static files. <slot> is publicSlotFromToken (./tunnel-ids), salted for the same reason the port
-// slots are, and one record per sandbox rather than a pool: there is one outbox, and its link has to stay good
-// for as long as the file does.
-//
-// A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>` /
-// `public-<slot>`), the unit reachability is expressed in, so one rule covers all three.
-export const previewLabel = (panel: string): string => `preview-${panel}`;
-export const portLabel = (slot: string): string => `port-${slot}`;
-export const publicLabel = (slot: string): string => `public-${slot}`;
-
-// The hostname a label resolves to. Nothing mints it: the edge parses the sandbox id back out of the name.
-export const labelHostname = (label: string, id: string, zone: string): string => `${label}-${id}.${zone}`;
-export const previewHostname = (panel: string, id: string, zone: string): string => labelHostname(previewLabel(panel), id, zone);
-export const portHostname = (slot: string, id: string, zone: string): string => labelHostname(portLabel(slot), id, zone);
-export const publicHostname = (slot: string, id: string, zone: string): string => labelHostname(publicLabel(slot), id, zone);
-
-// A label's public URL, undefined unless the sandbox has both a zone and an id (headless/loopback sandboxes
-// have neither and advertise nothing). One builder, three vocabularies: a panel's preview, a forwarded port's,
-// and the outbox's.
-const labelUrl = (label: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
-    zone !== undefined && zone !== "" && sandboxId !== undefined ? `https://${labelHostname(label, sandboxId, zone)}` : undefined;
-export const previewUrl = (panel: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
-    labelUrl(previewLabel(panel), zone, sandboxId);
-export const portUrl = (slot: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
-    labelUrl(portLabel(slot), zone, sandboxId);
-export const publicUrl = (slot: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
-    labelUrl(publicLabel(slot), zone, sandboxId);
-
-// The key after `<prefix>` from a request's Host header. The first DNS label must carry the prefix (the
-// own-Cloudflare wildcard also catches stray subdomains → undefined → the caller's 404) and, when the sandbox
-// has an id, the exact `-<sandboxId>` suffix, a fixed-length match, so keys containing `-` stay unambiguous.
-// Without an id the bare label is the key (loopback tests and provider-deployed workspaces, which front the
-// proxy themselves).
-const keyFromHost = (prefix: string, hostHeader: string | undefined, sandboxId: string | undefined): string | undefined => {
-    const label = hostHeader?.split(":")[0]?.split(".")[0] ?? "";
-    if (!label.startsWith(prefix)) {
-        return undefined;
-    }
-    const key = label.slice(prefix.length);
-    if (sandboxId === undefined) {
-        return key === "" ? undefined : key;
-    }
-    const suffix = `-${sandboxId}`;
-    return key.length > suffix.length && key.endsWith(suffix) ? key.slice(0, -suffix.length) : undefined;
-};
-
-export const panelFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
-    keyFromHost("preview-", hostHeader, sandboxId);
-export const portSlotFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
-    keyFromHost("port-", hostHeader, sandboxId);
-export const publicSlotFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
-    keyFromHost("public-", hostHeader, sandboxId);
-
-// The sandbox's identity AS THE USER SEES IT: the leading DNS label of its public URL, minus the `sandbox-`
-// prefix, `https://sandbox-0f310c3c4db4.intentic.dev` → `0f310c3c4db4`, i.e. sandboxIdFromToken's digest read
-// back off the wire by anyone holding only the URL. On the own-Cloudflare path the label is whatever subdomain
-// the owner chose, so that is the id there. undefined until the sandbox has a URL at all.
-export const sandboxIdFromUrl = (url: string | undefined): string | undefined => {
-    if (url === undefined || url === "") {
-        return undefined;
-    }
-    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
-    let label: string;
-    try {
-        label = new URL(withScheme).hostname.split(".")[0] ?? "";
-    } catch {
-        return undefined;
-    }
-    if (label === "" || label === SANDBOX_PREFIX) {
-        return undefined;
-    }
-    return label.startsWith(SANDBOX_PREFIX) ? label.slice(SANDBOX_PREFIX.length) : label;
-};
-
-// The LOCAL folder desktop sync mirrors /work into: `~/intentic/<sandbox name>-<sandboxIdFromUrl>`. Both halves
-// are strings the user already has in front of them, the name in the sandbox switcher, the id in the address
-// bar, so the folder on disk and the sandbox it mirrors read as ONE identity: `~/intentic/shop-0f310c3c4db4`
-// belongs to `https://sandbox-0f310c3c4db4.intentic.dev` and nothing else. Keyed on the URL rather than the
-// name alone for the same reason the hostname is: a torn-down sandbox recreated under the same name gets a new
-// id, hence its own fresh folder instead of reusing the dead one's (which cleanup never deletes) and colliding
-// on the two-way sync. Lives here, beside the hostname builders, because that match IS the contract.
-export const syncFolder = (name: string, url: string | undefined): string => {
-    const slug =
-        name
-            .replace(/[^a-zA-Z0-9]+/g, "-")
-            .replace(/^-+|-+$/g, "")
-            .toLowerCase() || "sandbox";
-    const id = sandboxIdFromUrl(url);
-    return `~/intentic/${slug}${id === undefined ? "" : `-${id}`}`;
-};
-
-// The Cloudflare zone from a sandbox public URL (https://sandbox-<id>.<zone> → <zone>): the hostname minus its
-// first DNS label. undefined when the URL is unparsable OR the hostname has fewer than three labels (no zone
-// suffix to strip, e.g. a 2-label host would otherwise yield a bare TLD). Accepts scheme-less input too, so it
-// works whether the caller passes `https://…` (daemon/CLI) or a bare host. This is the single reconciled
-// implementation of what used to be the daemon's `zoneFromPublicUrl` and the web's `zoneFromDaemonUrl`.
-export const zoneFromUrl = (url: string | undefined): string | undefined => {
-    if (url === undefined || url === "") {
-        return undefined;
-    }
-    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
-    let hostname: string;
-    try {
-        hostname = new URL(withScheme).hostname;
-    } catch {
-        return undefined;
-    }
-    const labels = hostname.split(".");
-    if (labels.length < 3) {
-        return undefined;
-    }
-    return labels.slice(1).join(".");
-};

package/src/ingress-contract.ts

@@ -1,157 +0,0 @@
-import { createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
-
-/* THE INGRESS CONTRACT: how a sandbox is reached now that the reachability fabric is the platform's OWN edge
- * (the `@intentic/ingress` app on Fly) instead of a zrok hub. Node-only (crypto), like ./tunnel-ids beside it;
- * shared by the platform (mints grants), the ingress (verifies grants, routes hosts), and the daemon (dials
- * the tunnel). The three MUST agree on every string in this file, which is why it exists.
- *
- * WHAT REPLACED WHAT. Under zrok, reachability was STATE: an account minted per sandbox over the hub's admin
- * API, names claimed one by one, shares bound to them, and a reaper collecting what the soft-deletes leaked.
- * Every piece of that state existed to answer one question — "which sandbox may serve this hostname?" — that
- * the hostnames ALREADY answer by construction: every public name a sandbox serves ends in its own 12-hex id
- * (`sandbox-<id>`, `preview-<panel>-<id>`, `port-<slot>-<id>`, `public-<slot>-<id>`; hostnames.ts is the
- * single source). So ownership is a PARSE, not a registry, and the only thing that has to be minted is proof
- * of identity: a grant, signed by the platform, saying "the bearer is sandbox <id>". Provisioning reachability
- * becomes a pure function — no hub round trip, no row to cache a token on, no orphan to reconcile, and
- * revoking it is deleting the sandbox row (the ingress asks the platform on register, below).
- *
- * THE FLOW. The daemon dials ONE outbound WebSocket to the ingress (INGRESS_TUNNEL_PATH) presenting its grant
- * in INGRESS_GRANT_HEADER. The ingress verifies the signature offline, registers the tunnel under grant.sub,
- * and from then on routes every edge request whose Host's leftmost label ends in `-<that id>` (or is exactly
- * `sandbox-<id>`) down that tunnel. A second tunnel for the same id DISPLACES the first — the new container is
- * by definition the live one, which is what buries the zrok-era stale-share reclaim dance (a recreated box
- * used to fight the hub over names its dead predecessor still held; here the fight cannot exist).
- *
- * THE DATA PLANE over the tunnel is an HTTP/2 cleartext session runs over the WebSocket's binary stream:
- * the ingress side opens an http2 CLIENT session over the duplex (node's http2.connect with createConnection),
- * the daemon side feeds the duplex to an http2 SERVER session, and each edge request becomes one h2 stream
- * with the original :authority preserved, which the daemon's client forwards to its own loopback listener
- * (the Hono app already dispatches previews by Host). WebSocket upgrades ride CONNECT-method streams carrying
- * the raw upgraded bytes. All of it is node core — the mux, flow control and per-stream backpressure are
- * h2's own, not ours to reimplement. The implementation lives in ./ingress-protocol.ts (both halves, one
- * owner); this file pins only what every party must agree on.
- *
- * WHY PER-REQUEST ROUTING IS NOT OPTIONAL: the edge terminates TLS under ONE wildcard certificate, and h2
- * browsers coalesce connections across every hostname a certificate covers — one TCP connection can carry
- * `sandbox-a…` and `preview-x-b…` interleaved. Routing a CONNECTION by its first Host would send one
- * sandbox's requests to another. The unit of routing is the request (h2 stream), never the connection. */
-
-// ── The reachability grant ──────────────────────────────────────────────────────────────────────────────
-
-/* Version prefix, so a future shape can coexist during a key rotation. Not a negotiation: an ingress that
- * does not know a prefix refuses the tunnel, and the box retries until its operator updates something. */
-const GRANT_PREFIX = "ig1";
-
-const base64url = (bytes: Buffer): string => bytes.toString("base64url");
-
-// The signed claim. `sub` is the sandbox's 12-hex id (sandboxIdFromToken in ./tunnel-ids); `iat` is seconds.
-// Deliberately no expiry: the grant lives in a container's env for the container's whole life, and the
-// revocation that matters (the sandbox being deleted) is answered by the platform on register, not by time.
-export interface ReachabilityGrant {
-    readonly sandboxId: string;
-    readonly issuedAt: number;
-}
-
-const SANDBOX_ID = /^[0-9a-f]{12}$/;
-
-/* Mint a grant: Ed25519 over the canonical payload bytes. Ed25519 because node signs/verifies it with key
- * objects alone (no hash negotiation, no padding modes), signatures are 64 bytes, and the platform already
- * depends on nothing for it — the private key is config (PEM, PKCS8), the public key rides the ingress env. */
-export const mintReachabilityGrant = (privateKeyPem: string, sandboxId: string, issuedAtMs: number): string => {
-    if (!SANDBOX_ID.test(sandboxId)) {
-        throw new Error(`a reachability grant names a 12-hex sandbox id, got "${sandboxId}"`);
-    }
-    const payload = Buffer.from(JSON.stringify({ sub: sandboxId, iat: Math.floor(issuedAtMs / 1000) }), "utf8");
-    const signature = edSign(null, payload, createPrivateKey(privateKeyPem));
-    return `${GRANT_PREFIX}.${base64url(payload)}.${base64url(signature)}`;
-};
-
-/* Verify a grant against the platform's public key. Every malformed shape answers undefined rather than
- * throwing: this runs on the ingress's unauthenticated door, where a garbage token is weather, not a fault. */
-export const verifyReachabilityGrant = (publicKeyPem: string, token: string): ReachabilityGrant | undefined => {
-    const parts = token.split(".");
-    if (parts.length !== 3 || parts[0] !== GRANT_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; iat?: unknown };
-        if (typeof parsed.sub !== "string" || !SANDBOX_ID.test(parsed.sub) || typeof parsed.iat !== "number") {
-            return undefined;
-        }
-        return { sandboxId: parsed.sub, issuedAt: parsed.iat };
-    } catch {
-        return undefined;
-    }
-};
-
-// ── Host → owner routing ────────────────────────────────────────────────────────────────────────────────
-
-/* Which sandbox may serve this Host. The leftmost DNS label either IS `sandbox-<id>` or ends in `-<id>`
- * (preview/port/public labels, hostnames.ts) — a fixed-length tail, so label keys containing `-` stay
- * unambiguous. Anything else (the ingress's own name, the zone apex, a stray subdomain) answers undefined,
- * which the ingress turns into its 404. The loopback name (`<id>.local.<zone>`) never reaches the ingress —
- * it resolves to 127.0.0.1 — and its bare-id label deliberately does not match here. */
-export const hostOwnerId = (host: string): string | undefined => {
-    const label = host.split(":")[0]?.split(".")[0] ?? "";
-    const match = /-([0-9a-f]{12})$/.exec(label);
-    return match === null ? undefined : match[1];
-};
-
-// ── Wire constants ──────────────────────────────────────────────────────────────────────────────────────
-
-/* The tunnel door on the ingress. Versioned in the path so a v2 session shape is a new door, not a flag day:
- * the ingress serves both for as long as old containers exist. Checked BEFORE host routing — the ingress's own
- * hostname carries no sandbox id on purpose. */
-export const INGRESS_TUNNEL_PATH = "/tunnel/v1";
-
-// The grant rides a header on the tunnel upgrade (a Node client can set one; this is never a browser).
-export const INGRESS_GRANT_HEADER = "x-intentic-grant";
-
-/* The env vocabulary, every lane (connect one-liner, compose file, hosted machine env) hands the same pair
- * down and the DAEMON reads exactly these names — the entrypoint reads neither, and that is the shape of the
- * change: reachability stopped being something a shell script arranges before the daemon starts and became
- * one outbound dial the daemon makes for itself. SANDBOX_PUBLIC_URL is unchanged from the fabric before this
- * one and stays beside them. */
-export const ENV_INGRESS_URL = "INGRESS_URL";
-export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";
-
-// ── The daemon-side surface (pinned for the boot wiring) ────────────────────────────────────────────────
-
-/* The daemon-side tunnel behavior this contract requires. Dial, register, forward to the loopback listener,
- * reconnect forever with backoff —
- * the tunnel is the sandbox's reachability, so like the zrok agent's restart loop it never gives up, it only
- * ever waits longer. close() is for shutdown and tests. */
-export interface IngressTunnelOptions {
-    // e.g. https://ingress.<zone>. The daemon derives the wss:// door itself (INGRESS_TUNNEL_PATH).
-    readonly url: string;
-    readonly grant: string;
-    // The daemon's own loopback listener; every h2 stream lands there as a plain HTTP/1.1 request or upgrade.
-    readonly targetPort: number;
-    readonly log: (message: string, error?: unknown) => void;
-}
-
-export interface IngressTunnelHandle {
-    readonly close: () => Promise<void>;
-    // For /health and the boot log: whether the tunnel currently holds a registered session.
-    readonly connected: () => boolean;
-}
-
-export type StartIngressTunnel = (options: IngressTunnelOptions) => IngressTunnelHandle;
-
-/* ── What the INGRESS side must also honor (spec, enforced by ingress-protocol tests) ──────────────────────
- *
- *  • Register: verify the grant offline; then, when PLATFORM_URL is configured, ask the platform whether the
- *    sandbox still exists (GET /api/reachability/<id>, 200/404, answer cached; fail-OPEN on a platform that
- *    does not answer — reachability must not depend on the platform being up, that is the whole point of the
- *    platform being off the hot path). A 404 refuses the tunnel: that is revocation.
- *  • Displacement: a new tunnel for an id closes the old session (code 4001) and takes the registration.
- *  • Liveness: WebSocket ping every 15s; a peer silent for 45s is dead and unregistered.
- *  • Routing: request host → hostOwnerId → registered tunnel; no tunnel answers 502 with a body naming the
- *    sandbox label (the browser's availability flow reads any 5xx as "sandbox unreachable" and drives wake).
- *  • The tunnel door itself (INGRESS_TUNNEL_PATH) and anything not carrying a sandbox-id host answer on the
- *    ingress directly; they are never routed. */