@intentic/sandbox-contract 1.248.0 → 1.250.0

package/src/schemas/engines.ts

@@ -1,45 +1,26 @@
 // engines: the upstream agent programs this sandbox spawns, and which version of each it runs
 import { z } from "zod";
 
-/* AN ENGINE IS THE PROGRAM A RUNTIME RIDES ON, which is a different noun from `runtime` and has to stay one.
- *
- * `runtime` (agent-catalog.ts) is the LOOP: claude-code, codex, opencode, acp, pi, cursor — what shape a turn
- * has. An engine is the installed PROGRAM that loop spawns or imports: the `claude` binary and its SDK, the
- * `codex` wrapper, `@cursor/sdk`, the `opencode` binary, the `cli-proxy-api` translator. One engine can back
- * several runtimes (the translator serves Gemini, Kimi and ChatGPT; Kimi runs under the Claude Code loop), so
- * the two lists are neither the same set nor the same question.
- *
- * The distinction earns its keep because engines have a lifecycle runtimes do not: they are published upstream,
- * on somebody else's schedule, and until this existed the only way to move one was to ship a sandbox image.
- * That made an ordinary upstream event — Anthropic raising the version floor a model requires — into a support
- * problem: every sandbox in the fleet failed every Claude turn until a new image reached it.
- *
- * So an engine version now comes from a STORE on the daemon volume, and the image's copy is the floor beneath
- * it. The blessed list says which version this project has actually run its suite against; an owner who wants
- * upstream's newest without waiting for that says so per engine. */
+// An engine is the installed program a runtime (agent-catalog.ts) spawns or imports — the `claude` binary, `codex`
+// wrapper, `@cursor/sdk`, `opencode`, `cli-proxy-api` — not the loop itself; one engine can back several runtimes.
 
 export const ENGINE_IDS = ["claude", "codex", "cursor", "opencode", "translator"] as const;
 export type EngineId = (typeof ENGINE_IDS)[number];
 export const EngineIdSchema = z.enum(ENGINE_IDS);
 
-/* THE OWNER'S STANDING ANSWER for one engine, and the whole of the version policy.
- *
- *   blessed , the default: whatever the blessed list names, which is a version this project's CI has run
- *              against. Data, not an image, so blessing a version reaches a running sandbox in seconds.
- *   latest  , upstream's newest published version, taken without waiting for anyone to bless it. The opt-in
- *              for an owner who would rather have the fix than the assurance.
- *   pinned  , exactly this version, until they say otherwise. What a revert leaves behind, and what somebody
- *              debugging a regression wants.
- *   image   , do not use the store at all: run what the image bakes. The way back to a stock sandbox. */
+// The owner's standing answer for one engine, the whole version policy:
+// blessed (default): whatever the blessed list names, a version this project's CI has run against.
+// latest: upstream's newest published version, without waiting for it to be blessed.
+// pinned: exactly this version until changed.
+// image: ignore the store; run what the image bakes.
 export const EngineChannelSchema = z.object({
     kind: z.enum(["blessed", "latest", "pinned", "image"]).describe("Where this engine's version comes from."),
     version: z.string().optional().describe("Which version, when it is pinned to one."),
 });
 export type EngineChannel = z.infer<typeof EngineChannelSchema>;
 
-// A version the store installed and then refused, with the reason it was refused. Kept per engine so a bad
-// publish is not retried on a timer forever, and so the card can say why the sandbox is back on the image's
-// copy rather than leaving that as an unexplained downgrade.
+// A version the store installed and then refused; kept per engine so a bad publish is not retried forever and the card
+// can explain a downgrade.
 export const EngineQuarantineSchema = z.object({
     version: z.string().describe("Which version was refused."),
     reason: z.string().describe("What was wrong with it: it would not launch, or it did not export what the daemon calls."),
@@ -53,9 +34,7 @@ export const EngineRowSchema = z.object({
     label: z.string().describe("What it is called on screen."),
     running: z
         .object({
-            // Absent means this sandbox has no copy of the engine at all: a core image bakes no provider packs,
-            // and until the store installs one, a turn on that provider cannot start. Different from "running
-            // the image's copy", and the card says so rather than drawing a blank version.
+            // Different from running the image's copy: absent means no copy of the engine exists here at all.
             version: z.string().optional().describe("The version a turn would use right now. Absent means there is no copy of this engine here yet."),
             source: z
                 .enum(["image", "store"])
@@ -67,8 +46,7 @@ export const EngineRowSchema = z.object({
         .optional()
         .describe("The version the image bakes, which is the floor everything else falls back to. Absent on an image that carries no copy of it."),
     channel: EngineChannelSchema.describe("The owner's standing answer for this engine."),
-    // What the channel would move to, absent when the running version is already it. Carries whether the
-    // blessed list names it, because on `latest` the answer is routinely no and the row has to say so.
+    // On the `latest` channel, `blessed` is routinely false; the row must still say so.
     offered: z
         .object({
             version: z.string().describe("The version this engine would move to."),
@@ -77,8 +55,7 @@ export const EngineRowSchema = z.object({
         .optional()
         .describe("A newer version waiting, absent when the running one is already what the channel asks for."),
     blessed: z.string().optional().describe("What the blessed list names for this engine, when the list has been read."),
-    // The store keeps one version back so a revert is a pointer move rather than a download. Absent on an
-    // engine that has only ever run the image's copy.
+    // Store keeps one version back so a revert is a pointer move; absent if only the image's copy ever ran.
     previous: z.string().optional().describe("The version kept one step back, which is what going back means."),
     quarantined: z.array(EngineQuarantineSchema).describe("Versions the store installed and then refused, with the reason."),
     diskBytes: z.number().int().nonnegative().describe("What this engine's kept versions cost on the daemon's volume."),
@@ -100,19 +77,15 @@ export const EngineChannelInputSchema = z.object({
     version: z.string().optional().describe("Which version, required when pinning and ignored otherwise."),
 });
 
-/* Install and activate a version now. `version` absent means what the channel offers, which is the button on
- * the row. Naming one explicitly is the "update anyway" path: it installs a version the blessed list does not
- * name, which is how a sandbox gets past an upstream version floor that the list has not caught up with. */
+// Install and activate a version now; absent `version` means whatever the channel offers. Naming one explicitly is
+// "update anyway": a version the blessed list does not (yet) name.
 export const EngineUpdateInputSchema = z.object({
     id: EngineIdSchema.describe("Which engine."),
     version: z
         .string()
         .optional()
         .describe("Which version. Leave it out for whatever the channel offers; naming one takes a version nobody has blessed, deliberately."),
-    /* The other half of the update-anyway path: a turn that died on an upstream version floor knows the floor
-     * and not which published version satisfies it. Sending the floor lets the daemon answer that — it takes
-     * the LOWEST version at or above it, the smallest step that works — rather than making a browser walk a
-     * registry to fill in a version number. */
+    // Daemon installs the lowest published version at or above this floor, the smallest step that satisfies it.
     floor: z
         .string()
         .optional()
@@ -124,7 +97,6 @@ export const EngineAppliedSchema = z.object({
     ok: z.literal(true).describe("It went through."),
     version: z.string().describe("Which version is now active."),
     source: z.enum(["image", "store"]).describe("Whether that is the image's copy or the store's."),
-    // An engine loaded in-process (the Claude SDK's JavaScript half, @cursor/sdk) is picked up by the NEXT
-    // turn rather than by the one that pressed the button: a turn already running holds the module it loaded.
+    // An in-process engine (`@cursor/sdk`) is picked up by the next turn; a running turn keeps its module.
     fromNextTurn: z.boolean().describe("Whether the change reaches turns already in flight, or only the next one."),
 });

package/src/schemas/environment.ts

@@ -1,27 +1,16 @@
 // environment: the overlay Dockerfile extending the sandbox image
 import { z } from "zod";
-// The approved file is DAEMON-COMPOSED: pinned FROM + capability fragments + the owner-approved custom section.
-// The agent drafts one file per thing it needs (.intentic/config/environment.d/<tool>.Dockerfile, custom-section
-// content only, no FROM) with its normal file tools, and the daemon folds those into the single proposal file
-// (.intentic/config/environment.Dockerfile) the owner reads. The owner approves it in the browser, which stores it as
-// the custom file and recomposes the approved artifact whose sha256 the rebuild executor pins. Both composed
-// files are written only when the composition CHANGES, see writeComposed, and the read loop it exists to end.
-// Status is derived, never stored:
-// applied = sha256(approved) === appliedHash; pending rebuild = approved present but hashes differ; proposed =
-// proposal present with a hash different from custom's.
+// The approved file is daemon-composed (pinned FROM + capability fragments + the owner-approved custom section). Status
+// is derived, never stored:
+// applied: sha256(approved) === appliedHash.
+// pending rebuild: approved present but hashes differ.
+// proposed: proposal present with a hash different from custom's.
 
 const environmentFileSchema = z.object({ content: z.string(), hash: z.string() });
-/* ---- environment DRIFT: what the live container has that the image did not put there ----
- *
- * Anything installed outside /work dies with the container, and transcript mining showed the same tools being
- * reinstalled session after session (cargo-xwin six times, a Windows rustup target eight) before anyone thought
- * to bake them. Drift is the daemon OBSERVING that gap rather than trusting the model to report it: apt installs
- * read from dpkg's own log, everything else from system paths newer than the container itself. Two channels
- * because they are disjoint by construction — dpkg unpacks files with their archive mtimes, so an mtime sweep
- * cannot see apt, and nothing apt does lands under the swept prefixes' hand-installed corners. */
+// What the live container has that the image did not put there; anything outside /work dies with the container. Two
+// channels, apt's own log and an mtime sweep, because dpkg-unpacked files keep archive mtimes invisible to the sweep.
 export const EnvironmentDriftSchema = z.object({
-    // When this container was created (PID 1's start). A snapshot whose bornAt is not the running container's
-    // describes a container that no longer exists, and every reader must treat it as no drift at all.
+    // PID 1's start; a snapshot whose bornAt differs from the running container's means no drift, not stale drift.
     bornAt: z.number(),
     // When the probe ran.
     at: z.number(),
@@ -31,15 +20,12 @@ export const EnvironmentDriftSchema = z.object({
     paths: z.array(z.string()),
 });
 export type EnvironmentDrift = z.infer<typeof EnvironmentDriftSchema>;
-// How a runtime install was made, which decides whether the daemon can draft a Dockerfile step for it
-// mechanically (apt/cargo/npm/rustup-target) or only surface it for a person to route (pip belongs in a venv or
-// a Debian package, "other" is a curl|sh whose replay could embed anything).
+// How a runtime install was made; decides whether the daemon can draft a Dockerfile step mechanically
+// (apt/cargo/npm/rustup-target) or must surface it for a person (pip, or "other": a curl|sh that could embed anything).
 export const RuntimeInstallKindSchema = z.enum(["apt", "pip", "cargo", "npm", "rustup-target", "playwright", "gem", "pipx", "go", "other"]);
 export type RuntimeInstallKind = z.infer<typeof RuntimeInstallKindSchema>;
-/* One tool's runtime-install history across sessions: the ledger entry behind the recurrence signal. Sessions
- * are the unit of recurrence — a session that retries an install five times needed it once — and the entry
- * survives container recreates (the file lives under /work), which is exactly what makes "installed again in a
- * fresh container" observable at all. */
+// One tool's install history across sessions: a session that retries an install needed it once (the unit of
+// recurrence). Persisted under /work so it survives container recreates.
 export const RuntimeInstallSchema = z.object({
     tool: z.string(),
     kind: RuntimeInstallKindSchema,
@@ -60,8 +46,8 @@ export const RuntimeInstallsFileSchema = z.object({
     drift: EnvironmentDriftSchema.optional(),
 });
 export type RuntimeInstallsFile = z.infer<typeof RuntimeInstallsFileSchema>;
-// A ledger entry as the Environment card shows it: recurrence joined with whether the install is present in the
-// LIVE container (drift-corroborated), already drafted for approval, or previously declined.
+// Ledger entry as the Environment card shows it: recurrence joined with whether it's present in the live container
+// (drift-corroborated), drafted, or declined.
 export const EnvironmentRecurringSchema = z.object({
     tool: z.string(),
     kind: RuntimeInstallKindSchema,
@@ -70,17 +56,14 @@ export const EnvironmentRecurringSchema = z.object({
     live: z.boolean(),
     drafted: z.boolean().optional(),
     declined: z.boolean().optional(),
-    /* The Dockerfile step that would bake this tool, when its ecosystem has one that follows from the name
-     * alone (auto-drafts.ts `stepFor`). Sent rather than re-derived in the browser because it is the SAME string
-     * the owner would approve, and because its presence is the honest answer to "can this be fixed by pressing a
-     * button?": absent means the fix is a judgement call (which pip package, replaying which installer) and the
-     * card offers an agent instead. */
+    // Step that would bake this tool; absent means the fix needs judgement and the card offers an agent instead.
     step: z.string().optional(),
 });
 export type EnvironmentRecurring = z.infer<typeof EnvironmentRecurringSchema>;
-/* The owner's answer to ONE line of that list. `adopt` writes the tool's overlay draft now, without waiting for
- * the sweep to re-earn it; `dismiss` tombstones it so nothing proposes it again; `restore` undoes a dismissal.
- * One route rather than three because it is one decision surface about one ledger entry. */
+// Owner's decision on one recurring-install entry:
+// adopt: writes the tool's overlay draft now.
+// dismiss: tombstones it so nothing proposes it again.
+// restore: undoes a dismissal.
 export const EnvironmentRuntimeDecisionSchema = z.object({
     tool: z.string().min(1),
     decision: z.enum(["adopt", "dismiss", "restore"]),
@@ -95,28 +78,15 @@ export const EnvironmentSchema = z.object({
     appliedHash: z.string().optional(),
     // config.sandbox.name, the UI derives the rebuild one-liner's slug from it.
     container: z.string().optional(),
-    // What the live container has that the image did not put there; absent until the first sweep of this container.
+    // What the live container has beyond the image; absent until this container's first sweep.
     drift: EnvironmentDriftSchema.optional(),
     // Runtime installs worth the owner's attention: recurring across sessions, or present-and-doomed right now.
     recurring: z.array(EnvironmentRecurringSchema).optional(),
 });
 export type Environment = z.infer<typeof EnvironmentSchema>;
 export const EnvironmentApproveSchema = z.object({ hash: z.string().min(1) });
-/* ---- environment CONTENTS: what the sandbox has, as opposed to how it was built ----
- *
- * The overlay above answers "what was added on top, and do you approve it?". Nobody opens the Environment tab
- * asking that, they ask "can this sandbox compile my Rust app / transcode a video / drive a browser?", and a
- * build recipe is a bad answer to it: it is install plumbing, it names packages rather than abilities, and it is
- * only the DELTA, so an inventory read off it alone would claim a sandbox has ffmpeg and no Node.
- *
- * So this is a second read of the same sandbox, and its authority is different in a way that matters: NAMES,
- * GROUPING and RATIONALE come from the recipe (which is where the agent wrote them), while PRESENCE and VERSION
- * come from asking the environment itself. That split is what makes it honest. A version is never parsed out of
- * an install line, half the entries pin nothing, and a pinned number is a lie the moment something is approved
- * but not yet rebuilt, so an item whose tools cannot be probed carries no version at all rather than a guess.
- * And presence is OBSERVED, which is what makes per-item state exact without diffing anything: an item the
- * recipe contains and the probe cannot find is precisely one that arrives with the next rebuild.
- */
+// What the sandbox has, not how it was built. Names, grouping and rationale come from the recipe; presence and version
+// come from probing the sandbox itself, so a version is never guessed, only reported when probed.
 
 const environmentToolSchema = z.object({
     // The binary as it is invoked (`rustc`, `ffmpeg`), because that is what somebody types next.
@@ -128,27 +98,25 @@ export const EnvironmentItemSchema = z.object({
     id: z.string(),
     // The block's own name, how the thing is referred to, not the packages it happens to install.
     name: z.string(),
-    /* WHY IT IS HERE, which is also whether the reader may remove it: `custom` is what an agent asked for and the
-     * owner approved for this workspace, `capability` is the cost of a capability they turned on, `base` comes
-     * with every sandbox and is nobody's decision. */
+    // Why it is here, and whether the reader may remove it:
+    // custom: an agent asked for it and the owner approved it for this workspace.
+    // capability: the cost of a capability the owner turned on.
+    // base: comes with every sandbox; nobody's decision.
     origin: z.enum(["custom", "capability", "base"]),
-    // Which capability/extension/pack pulled it in, the answer to "why do I have this?" for an origin the
-    // reader did not choose item by item.
+    // Which capability/extension/pack pulled it in, for an origin the reader did not choose item by item.
     originLabel: z.string().optional(),
-    // Observed, not inferred: `active` means the probe found it, `after-rebuild` that the recipe has it and the
-    // container does not, `awaiting-approval` that it is in a proposal nobody has approved yet.
+    // Observed, not inferred:
+    // active: the probe found it.
+    // after-rebuild: the recipe has it, the container does not yet.
+    // awaiting-approval: it is in a proposal nobody has approved yet.
     state: z.enum(["active", "after-rebuild", "awaiting-approval"]),
-    // Every binary this one block puts on PATH, with the version each reports. Usually one; a toolchain is several.
+    // Every binary this block puts on PATH, with its version. Usually one; a toolchain is several.
     tools: z.array(environmentToolSchema),
-    // How many further packages the block installs that are not commands anyone runs (libraries, headers). A
-    // count rather than a list: eleven rows of `libssl-dev` is noise, "+11 packages" is the same fact.
+    // Further packages the block installs with no command (libraries, headers); a count, not a list.
     extras: z.number().optional(),
     // One standalone line, from the block's opening comment, the part everyone reads.
     purpose: z.string().optional(),
-    /* That comment in full, as prose, absent when the line above already is the whole of it. NOT the remainder
-     * after the line: `purpose` is a summary of this (a parenthetical dropped, an over-long sentence cut back to
-     * its claim), so the two overlap by design and it is the reader's view that picks one. Long, the rationale
-     * for a toolchain runs to paragraphs, so it lives behind a disclosure rather than on the row. */
+    // Full comment as prose, overlapping `purpose` by design rather than continuing past it.
     detail: z.string().optional(),
     // The block's own instruction lines, for the reader who wants to see exactly what runs.
     commands: z.string().optional(),
@@ -156,33 +124,15 @@ export const EnvironmentItemSchema = z.object({
 export type EnvironmentItem = z.infer<typeof EnvironmentItemSchema>;
 export const EnvironmentContentsSchema = z.object({ items: z.array(EnvironmentItemSchema) });
 export type EnvironmentContents = z.infer<typeof EnvironmentContentsSchema>;
-/* ---- portability: exporting a sandbox's environment ----
- *
- * A sandbox is four stores, not one: `/work` (the workspace and the daemon's manifests), `/history` (every
- * repo's real git dir, the fleet registry, the ledgers), the CONTAINER (the built overlay image plus the env
- * the run contract replays) and the AI-provider credential root. A bundle carries the first two, declared entry
- * by entry in WORKSPACE_STATE_FILES / HISTORY_STATE_FILES. It cannot carry the other two, and the honest
- * consequence is that taking one in ends in a REPORT rather than a claim of equivalence, the container has no
- * docker socket, so only the host can rebuild the image the overlay describes.
- *
- * The bundle's manifest (BundleManifestSchema) lives in definition.ts beside the sandbox DEFINITION it embeds:
- * a bundle is definition + state, and keeping the two schemas together is what keeps the two export doors from
- * drifting into different answers about what an environment is.
- *
- * ONLY THE OUTBOUND HALF IS HERE. Taking a bundle IN is not a surface of its own any more: it is one of the
- * four sources the arrival pipeline reads (arrival.ts), beside a definition and the two foreign assistants,
- * because all four answer the same question and used to answer it three different ways. */
+// A sandbox is four stores: /work, /history, the container, and the AI-provider credential root. A bundle carries only
+// the first two (WORKSPACE_STATE_FILES/HISTORY_STATE_FILES); it cannot rebuild the container or credentials, so
+// importing one is a report, not a claim of equivalence. Only the outbound half is here; inbound is one of arrival.ts's
+// four sources.
 
-/* One export sitting in the daemon's export directory, the ARTIFACT a bundle is, rather than the request that
- * produced it. Packing takes minutes over a real workspace, so tying it to a response made it a property of one
- * browser tab: a refresh abandoned the work and left nothing to come back to. It is a file now, and every field
- * below is read off that file rather than remembered anywhere.
- *
- * `status` is derived from the extension (.part / .tar.gz / .failed) and `bytes` is the file's own size, which
- * is what makes a live pack's progress free to report. */
+// One export in the daemon's export directory, the artifact a bundle is, not the request that made it; every field is
+// read off that file. `status` comes from its extension (.part/.tar.gz/.failed), `bytes` from its own size.
 export const BundleExportSchema = z.object({
-    // The finished bundle's filename, which is the id in every route, and, once downloaded, the name the owner
-    // sees on disk. Carries its own timestamp and a `-with-secrets` marker so it stays self-describing there.
+    // Finished filename: the id in every route, timestamped, marked `-with-secrets` when relevant.
     name: z.string(),
     status: z.enum(["packing", "ready", "failed"]),
     // Bytes written so far while packing; the finished size once ready.

package/src/schemas/exit.ts

@@ -1,44 +1,22 @@
-// Geo exits: somewhere the agent's traffic can LEAVE from, so a page fetches as if read elsewhere. Its own
-// capability kind rather than a fourth `vpn` provider — an exit routes NOTHING into the main table.
+// Geo exits: somewhere the agent's traffic can leave from, so a page fetches as if read elsewhere.
 import { z } from "zod";
 import { autoStart } from "./internal.js";
-/* A GEO EXIT: somewhere the agent's traffic can LEAVE from, so a page fetches as if read in Berlin or Osaka.
- * Its own kind rather than a fourth `vpn` provider, and the distinction is the whole reason this works:
- *
- *   a `vpn` REACHES a private network , one stored gateway, dialled, pushing its routes into the main table.
- *   an `exit` LEAVES from somewhere else, a POOL with a catalog, switched at runtime, routing NOTHING into
- *     the main table.
- *
- * That last clause is load-bearing. An exit is a full tunnel by definition, and a full tunnel on the main
- * table swallows the sandbox's own uplink, the model endpoint and the tunnel that makes this sandbox
- * reachable, which reads to a user as the agent breaking mid-turn (see IpsecVpnConfigSchema.routedNetworks
- * for the same trap on the vpn kind). So an exit never touches the default route. It publishes a local SOCKS
- * proxy and callers opt in: a browser account naming it, `curl --proxy`, and nothing else. The side benefit
- * is trust, a volunteer relay carries only what was pointed at it, never the agent's own working traffic.
- *
- * Three providers, chosen because each is reachable with no paid account:
- *   tor      , the Tor network. ~52 exit countries, no account, no credentials, no privileges: it is a SOCKS
- *              proxy already. Country is a torrc line, a new IP is a control-port signal. The free default.
- *   vpngate  , the University of Tsukuba's volunteer relay pool. No account; its public CSV IS the catalog,
- *              so servers auto-fill. Overwhelmingly Japan/Korea in practice, which is the half of the map Tor
- *              covers worst, so the two complement rather than duplicate.
- *   wireguard, bring your own .conf files, one per country, from a provider's dashboard (Proton VPN's free
- *              tier, Mullvad, anything). The catalog is built by parsing what was pasted.
- * Starting, switching country and rotating are LIVE operations (see exit.contract.ts), never config, so an
- * exit's real state is read off the machine. `country` is the resting preference and `autoStart` the only
- * other persisted intent. */
+// An exit never touches the default route: it publishes a local SOCKS proxy callers opt into (a browser account, `curl
+// --proxy`); a `vpn` capability instead pushes routes into the main table.
+// tor: the Tor network, already a SOCKS proxy, no account needed.
+// vpngate: University of Tsukuba's volunteer pool; its public CSV is the catalog.
+// wireguard: user-supplied .conf files from any provider, one pool per country.
 export const ExitProviderSchema = z.enum(["tor", "vpngate", "wireguard"]);
 export type ExitProvider = z.infer<typeof ExitProviderSchema>;
-// An ISO 3166-1 alpha-2 code, normalised up so "de", "DE" and "De" are one country rather than three. The
-// catalogs, the CLI and the manifest all speak this one spelling.
+// ISO 3166-1 alpha-2 code, normalised to uppercase so "de"/"DE"/"De" are one country; catalogs, CLI and manifest all
+// speak this spelling.
 export const CountryCodeSchema = z
     .string()
     .regex(/^[A-Za-z]{2}$/, "A country is its two-letter code, like DE, US or JP.")
     .transform((value) => value.toUpperCase());
 export const TorExitConfigSchema = z.object({
     provider: z.literal("tor"),
-    // Where to come out, when nothing has asked for somewhere else. Absent ⇒ let Tor choose, which is both
-    // faster and kinder to the network.
+    // Absent means let Tor choose its own exit, which is faster and kinder to the network.
     country: CountryCodeSchema.optional(),
     autoStart,
 });
@@ -48,14 +26,7 @@ export const VpngateExitConfigSchema = z.object({
     autoStart,
 });
 export const WireguardExitConfigSchema = z.object({
-    /* One or more WireGuard .conf files in one field, pasted back to back. One field rather than one
-     * capability per country because they are one POOL: the whole point is switching between them under a
-     * proxy port that never moves, and a user with five Proton free countries should not add five capabilities
-     * to get five countries out of one account.
-     *
-     * Country per conf comes from an optional `# country: DE` line, else from the provider's own naming
-     * convention in the Endpoint host (Proton's `de-free-01.protonvpn.net`, Mullvad's `de-ber-wg-001`), else
-     * from a lookup through the tunnel once it is up. Whole thing is the secret: each conf holds a private key. */
+    // One or more WireGuard .conf files pasted back to back; each holds a private key, so the field is a secret.
     provider: z.literal("wireguard"),
     config: z.string().min(1),
     country: CountryCodeSchema.optional(),
@@ -66,9 +37,8 @@ export type TorExitConfig = z.infer<typeof TorExitConfigSchema>;
 export type VpngateExitConfig = z.infer<typeof VpngateExitConfigSchema>;
 export type WireguardExitConfig = z.infer<typeof WireguardExitConfigSchema>;
 export type ExitConfig = z.infer<typeof ExitConfigSchema>;
-// The manifest says which exits EXIST; this says which are up, where they come out, and what the world sees.
-// Read off the machine and off the wire, never remembered: an exit the agent stopped from a shell and one the
-// UI stopped read identically, and a daemon restart observes the truth rather than a stale guess.
+// Manifest says which exits exist; this says which are up, where, and what the world sees — read off the machine and
+// wire, never remembered, so a restart observes the truth rather than a stale guess.
 
 export const ExitStateSchema = z.enum([
     // Carrying traffic: the proxy is listening and the last check came out where it was asked to.
@@ -83,14 +53,10 @@ export const ExitStateSchema = z.enum([
     "failed",
 ]);
 export type ExitState = z.infer<typeof ExitStateSchema>;
-/* WHAT THE WORLD SEES, fetched THROUGH the exit's own proxy. This is the load-bearing type of the whole
- * feature: "switch to Germany" is worth nothing as a report that a tunnel came up, and worth everything as a
- * report that the egress address is now German. Every start, use and rotate ends by producing one of these,
- * and a switch that cannot produce one fails instead of quietly leaving traffic where it was. */
+// What the world sees, fetched through the exit's own proxy. Every start, use and rotate ends by producing one; a
+// switch that cannot produce one fails rather than silently leaving traffic where it was.
 export const ExitObservationSchema = z.object({
     ip: z.string().describe("The address the world sees, looked up through the exit's own proxy rather than assumed."),
-    // Absent when the lookup answered with an address but no country: a switch is judged on the country when
-    // one is known, and on the address having CHANGED when it is not.
     country: z
         .string()
         .optional()
@@ -100,16 +66,13 @@ export const ExitObservationSchema = z.object({
     countryName: z.string().optional().describe("That country's name, spelled out."),
 });
 export type ExitObservation = z.infer<typeof ExitObservationSchema>;
-/* One country an exit can come out of, as the picker and `exit countries` render it. `servers` and `share`
- * are what stop a country list being a lie: Tor lists 52 countries and a third of them are one underpowered
- * relay, so the ranking has to carry how much is actually there, not just that the flag exists. */
+// One country an exit can come out of. `servers` and `share` keep the list honest: many listed countries are one
+// underpowered relay, not real capacity.
 export const ExitPointSchema = z.object({
     country: z.string().describe("The country's code."),
     countryName: z.string().describe("Its name, spelled out."),
-    // How many relays/servers this provider has there right now.
     servers: z.number().describe("How many servers this provider has there."),
-    // This country's share of the provider's total exit capacity, 0..1. Used to sort and to grey out the
-    // countries that technically exist and practically do not.
+    // Also used to grey out countries that technically exist but carry no real capacity.
     share: z
         .number()
         .optional()
@@ -120,8 +83,7 @@ export const ExitPointSchema = z.object({
 export type ExitPoint = z.infer<typeof ExitPointSchema>;
 export const ExitCountriesSchema = z.object({
     countries: z.array(ExitPointSchema).describe("Where this exit can put you, best-supplied first."),
-    // Whether this list came off the provider live or out of the baked fallback (no network, or the provider
-    // is down). The picker says so rather than presenting a stale list as current.
+    // True from a live fetch, false from the baked fallback (no network, or the provider is down).
     live: z
         .boolean()
         .describe("Whether the provider answered, or this came from a built-in list. Said out loud rather than presenting an old list as current."),
@@ -132,17 +94,13 @@ export const ExitLinkSchema = z.object({
     state: ExitStateSchema.describe(
         "Whether it is carrying traffic, coming up, resting, failed, or not installable yet because its client needs a rebuild to arrive.",
     ),
-    // The SOCKS endpoint callers point at. Fixed per exit and stable across country switches, which is what
-    // lets a long task change country halfway without reconfiguring anything downstream.
     proxy: z
         .string()
         .describe(
             "Where to point traffic that should go through it. Fixed per exit and unchanged by a country switch, which is what lets a long job move country halfway through without reconfiguring anything.",
         ),
-    // The country ASKED for (manifest preference, or the last `use`). Absent = provider's choice.
+    // Manifest preference, or the last `use` call.
     country: z.string().optional().describe("Where it was asked to come out. Absent means the provider chose."),
-    // The country actually OBSERVED at the last check, and the address behind it. These two disagreeing is
-    // the single most useful fault signal this feature has, so they are separate fields, never merged.
     observedCountry: z
         .string()
         .optional()
@@ -150,9 +108,8 @@ export const ExitLinkSchema = z.object({
             "Where it actually comes out, as last checked. Kept separate from what was asked for, because those two disagreeing is the most useful fault signal this whole feature has.",
         ),
     ip: z.string().optional().describe("The address behind that observation."),
-    // Epoch ms of the observation above, so a stale reading can be rendered as stale.
     checkedAt: z.number().optional().describe("When that was checked, in milliseconds, so an old reading can be shown as old."),
-    // The tunnel interface, for the providers that have one (vpngate, wireguard). Tor has none by design.
+    // vpngate and wireguard have one; Tor has none by design.
     interface: z.string().optional().describe("The network interface, for the kinds that have one."),
     since: z.number().optional().describe("When it came up, in milliseconds."),
     autoStart: z.boolean().describe("Whether it starts itself when the sandbox does."),
@@ -162,19 +119,8 @@ export type ExitLink = z.infer<typeof ExitLinkSchema>;
 export const ExitListSchema = z.object({
     links: z.array(ExitLinkSchema).describe("Every configured exit, with where it was asked to come out and where it actually does."),
 });
-/* WHERE EACH FREE PROVIDER CAN ACTUALLY COME OUT, as measured, and the reason it lives in the contract rather
- * than in the daemon: two consumers need the same answer and must not drift. The daemon uses it as the
- * FALLBACK catalog when a provider's own list cannot be fetched; the add form uses it to fill the country
- * picker, so a user chooses from a list instead of guessing a code and finding out later that nothing serves
- * it. A second copy of these numbers would let the picker offer a country the driver cannot dial.
- *
- * `share` is the country's slice of the provider's exit capacity, and it is the number that matters. A third
- * of Tor's fifty-two countries are one overloaded relay behind a flag; ranking by relay COUNT alone would put
- * the United States first on 1,171 slow relays when the Netherlands carries three times the traffic on half as
- * many. Both surfaces sort on this so the top of the list is the part that works.
- *
- * Measured 2026-08-21 from onionoo.torproject.org and vpngate.net's public CSV. Stale by construction, which
- * is exactly why the daemon prefers a live fetch and labels this one as not-live when it falls back to it. */
+// Shared fallback catalog for the daemon and the add-form picker, so the two cannot drift. Ranked by `share`, not
+// server count, since count alone misrepresents real capacity; stale by construction, always marked not-live when used.
 export const TOR_EXIT_COUNTRIES: readonly ExitPoint[] = [
     { country: "NL", countryName: "Netherlands", servers: 607, share: 0.304 },
     { country: "DE", countryName: "Germany", servers: 415, share: 0.242 },
@@ -196,9 +142,7 @@ export const TOR_EXIT_COUNTRIES: readonly ExitPoint[] = [
     { country: "GB", countryName: "United Kingdom", servers: 8, share: 0.002 },
     { country: "FI", countryName: "Finland", servers: 13, share: 0.002 },
 ];
-// VPN Gate, and its shape is the honest headline: 87% of its pool is Japan and Korea. That is not a defect to
-// hide behind a long country list, it is the reason to have it, Tor's Asian exit capacity is close to nothing,
-// so the two providers cover each other rather than overlapping.
+// Skewed to Japan/Korea by design, complementing Tor's weak Asian coverage rather than duplicating it.
 export const VPNGATE_EXIT_COUNTRIES: readonly ExitPoint[] = [
     { country: "JP", countryName: "Japan", servers: 46, share: 0.48 },
     { country: "KR", countryName: "Korea, South", servers: 37, share: 0.39 },
@@ -212,8 +156,7 @@ export const VPNGATE_EXIT_COUNTRIES: readonly ExitPoint[] = [
     { country: "BY", countryName: "Belarus", servers: 1, share: 0.01 },
 ];
 export const ExitIdParamSchema = z.object({ id: z.string().describe("Which exit.") });
-// POST /exit/{id}/use body. An absent country means "let the provider choose", the same thing an absent
-// `country` in the manifest means, so clearing a country is expressible rather than only setting one.
+// POST /exit/{id}/use body; absent `country` matches what an absent one means in the manifest.
 export const ExitUseInputSchema = z.object({
     id: z.string().describe("Which exit."),
     country: CountryCodeSchema.optional().describe(