@intentic/sandbox-contract 1.230.3 → 1.232.0

package/src/events.ts

@@ -434,6 +434,30 @@ export const SharePayloadSchema = z.object({
 });
 export type SharePayload = z.infer<typeof SharePayloadSchema>;
 
+/* WHAT A PARKED CARD IS ABOUT: the document the turn wrote and is now asking a question against.
+ *
+ * A card asks for a decision; until this it carried no SUBJECT. The commonest shape of a real decision is "I
+ * analysed this and wrote it up, now choose", and the write-up went into a file whose card had already folded
+ * itself into `Write · +135 −0` twenty tool calls back. So the reader was asked to choose between options
+ * describing a document the chat had never shown them.
+ *
+ * Carried BY VALUE rather than as a path, for the same reason the diff on a tool call is: the bytes are already
+ * in hand when the card is raised, a path would make the card's meaning depend on a file that keeps changing
+ * under it, and a restored or published transcript has no workspace to go read. The path rides along anyway, so
+ * a document past the wire cap still has somewhere to send the reader.
+ *
+ * Nothing is asked of the MODEL for this. It calls `ask` exactly as before; the daemon knows what the turn
+ * wrote, because every write came past it as a frame (documents.ts decides which of them is a document). A
+ * harness that can see the answer must not spend prompt on asking the model to repeat it. */
+export const CardDocumentSchema = z.object({
+    path: z.string().describe("Where it lives, as a workspace path."),
+    title: z.string().describe("What it is called: its opening heading, or its file name."),
+    markdown: z.string().describe("The document itself."),
+    truncated: z.boolean().optional().describe("It was clipped at the wire cap; the file on disk has more."),
+    plan: z.boolean().optional().describe("It is one of the CLI's plan files, written to be approved rather than merely read."),
+});
+export type CardDocument = z.infer<typeof CardDocumentSchema>;
+
 /* THE THREE RESTORABLE CARDS, named so the turn journal can hold them verbatim: a parked turn's raised cards
  * are written down beside its prompt (sandbox turn-journal.ts), and a daemon death under the park restores the
  * very same frames instead of ending the turn `interrupted`, the card the user was about to answer survives
@@ -444,11 +468,15 @@ const PlanCardSchema = z.object({
     kind: z.literal("plan").describe("The agent has written a plan and is waiting for a yes."),
     requestId: z.string().describe("What to send back when you answer."),
     text: z.string().describe("The plan itself."),
+    // Present when the plan text POINTS at a document instead of being one: the model wrote the real plan to a
+    // file and summarised it here. Absent when the text already is the whole plan, which is the ordinary case.
+    document: CardDocumentSchema.optional().describe("The write-up this plan refers to, when the plan itself is a pointer to one."),
 });
 const QuestionCardSchema = z.object({
     kind: z.literal("question").describe("The agent has asked you something and is waiting."),
     requestId: z.string().describe("What to send back when you answer."),
     questions: z.array(AskQuestionSchema).describe("What it wants to know."),
+    document: CardDocumentSchema.optional().describe("The document this turn wrote and is asking about, so the choice can be read beside it."),
 });
 const PermissionCardSchema = PermissionAskSchema.extend({
     kind: z.literal("permission").describe("The agent wants to use a tool it needs permission for."),
@@ -493,6 +521,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         base: z.string(),
         unenforced: z.boolean().optional(),
         sync: z.object({ commits: z.number(), blocked: z.array(z.string()) }).optional(),
+        // The runner this turn executes on, when the conversation is placed remotely (runners/): the
+        // transcript's own statement of where the work is happening. Absent ⇒ this sandbox.
+        remote: z.string().optional(),
     }),
     // Emitted after a clean isolated turn whose delta auto-landed (or failed to): landed ⇒ the work is now
     // UNCOMMITTED changes in the main tree (the Changes panel is the review); conflicts ⇒ it stayed safely in
@@ -621,9 +652,10 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         agentType: z.string().optional(),
         description: z.string().optional(),
         model: z.string().optional(),
+        // Which provider serves a `spawned` child (SubagentSessionSchema.provider), absent for an SDK
+        // subagent, whose provider is its parent's.
+        provider: z.string().optional(),
         background: z.boolean().optional(),
-        // A delegation's tmux session, the one live view a subagent doesn't have (SubagentSessionSchema).
-        terminal: z.string().optional(),
     }),
     z.object({
         kind: z.literal("subagent_update"),
@@ -913,6 +945,16 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 "context-window-too-small",
                 "subscription-required",
                 "agent-busy",
+                /* THE SANDBOX HAS NO MEMORY LEFT TO RUN THIS TURN, refused before anything was spawned
+                 * (platform/memory-admission.ts). Its own code because it is the only refusal here that is
+                 * about the BOX rather than the request: the prompt, the model and the credential are all
+                 * fine, and the identical request succeeds once something inside frees room, which is the
+                 * opposite of context-window-too-small next door. Transient without being on a clock, so
+                 * there is no resetsAt to offer — what changes the outcome is a turn finishing or a session
+                 * closing, and the message says so. The client HOLDS the words for the same reason
+                 * context-window-too-small does: they never reached a provider, and losing them to a
+                 * capacity fact the user did not cause would be ours to answer for. */
+                "sandbox-memory-low",
             ])
             .optional(),
         // rate_limit only: when the exhausted window reopens (epoch seconds, from the stream's own
@@ -929,6 +971,25 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         // Absent means there is nothing automatic to resume: a spent usage limit never has one,
         // and a refused credential has none once re-minting it has already been tried and failed.
         autoResume: z.enum(["scheduled", "available"]).optional(),
+        /* THE DAEMON IS STILL HOLDING THIS EXACT TURN, so the way on is to RE-RUN it rather than to send
+         * something after it. rate_limit only, and the counterpart to `autoResume` rather than a member of it:
+         * that field answers "is a machine bringing this back", and a spent allowance is the one failure where
+         * the answer is deliberately no (the allowance is the user's own budget to spend, turn-resume.ts). This
+         * answers the question that was never asked, "and if the user says go, what happens", which had exactly
+         * one possible answer for as long as it went unasked: a new user message reading "Continue".
+         *
+         * That answer was wrong in a way the chat could not show. The press is not a new instruction, it is the
+         * same one again, and appending it said otherwise to the only reader that matters: the provider session
+         * grew one "Continue" per press, each with a synthetic "No response requested." above it, so a chat that
+         * bounced four times handed the model four turns in which it appeared to have declined to answer. With
+         * this field the press re-runs the held turn instead, which is idempotent by construction (a second press
+         * finds a live turn and supersedes nothing) and leaves the transcript one row for one press.
+         *
+         * `ran` is whether the held turn got anywhere before it was refused, and it changes both what the model
+         * is told (RESUME_NOTES.limit vs .refused, and telling a model to carry on from work that never happened
+         * is how it comes to invent some) and what the strip can honestly say. A spent allowance refuses the
+         * FIRST request most of the time, so false is the common case, not the corner. */
+        held: z.object({ ran: z.boolean() }).optional(),
         /* provider-outage only: the shape of the wait. `retryAt` (epoch seconds) is when the next attempt is
          * due, not a fixed cadence, because an outage has no reset instant to aim at and hammering a provider
          * that is down only spends tokens on refusals, so each attempt waits longer than the last
@@ -993,6 +1054,23 @@ export const RESUME_NOTES = {
     auth: `The Claude credential that interrupted this conversation has been renewed, and this turn resumed automatically. ${REPEATED}`,
     outage: `The model provider was briefly unavailable and interrupted this conversation; this turn resumed automatically. ${REPEATED}`,
     restart: `The sandbox restarted while this turn was running, which stopped it, and this turn resumed automatically once it came back. ${REPEATED}`,
+    /* A SPENT ALLOWANCE STRANDS A TURN IN TWO SHAPES, and they must not share a note.
+     *
+     * `limit` is the mid-turn one and reads like its three neighbours above: the session holds real work, and
+     * carrying on from it is exactly right.
+     *
+     * `refused` is the turn the provider turned away at the door, before the model read one word of it, and it
+     * is the COMMONER of the two, because an allowance that is already spent refuses the first request it is
+     * asked. REPEATED is actively wrong for it: "part of it was already completed in this session, continue from
+     * that point instead of starting over" is an instruction to continue from work that does not exist, and a
+     * model handed that instruction answers it by inventing the work. So it says the opposite, plainly.
+     *
+     * Both are unlike their neighbours in one way worth stating: nothing resumed automatically. A spent
+     * allowance is the user's own budget and stays their call to spend (turn-resume.ts), so what re-ran this
+     * turn was a person pressing Continue. */
+    limit: `The model provider's usage allowance ran out while this turn was running, which stopped it, and it has been sent again. ${REPEATED}`,
+    refused:
+        "The model provider refused the previous attempt at this request outright, because its usage allowance was spent: no part of the request below was read or acted on, and nothing has been done towards it. It has been sent again, and starts from the beginning.",
     // A turn that was PARKED on the user when the daemon died: nothing re-runs at boot, the card is restored
     // instead, and this is the turn their answer starts (turn-resume.ts). What rides below the note is the
     // answer itself, so the model picks the session back up at exactly the decision it had handed over.
@@ -1038,6 +1116,14 @@ const RESUME_DISCLOSURES: Record<ResumeReason, ResumeDisclosure> = {
     auth: { kind: "notice", text: "Claude sign-in renewed, this turn picked up where it left off." },
     outage: { kind: "notice", text: "The model provider came back, this turn picked up where it left off." },
     restart: { kind: "notice", text: "The sandbox came back, this turn picked up where it left off." },
+    /* THE ONE PAIR NOBODY AUTOMATED, said in the passive voice the other three earn honestly and these two do
+     * not: a person pressed Continue. Which is the whole reason these rows exist at all. A press used to append
+     * the word "Continue" as a message of its own, so a chat that bounced off a spent allowance four times read
+     * back as the user saying "Continue" four times to an agent that had answered none of them, and the provider
+     * session the model actually reads accumulated all four (plus a synthetic "No response requested." per
+     * press). One row for one press was never the problem; a row that claims the user said something new is. */
+    limit: { kind: "notice", text: "Sent again after the allowance ran out mid-turn, picking up where it left off." },
+    refused: { kind: "notice", text: "Sent again after the allowance refused it: nothing had run." },
     answered: { kind: "note", note: { title: "Picked back up after a sandbox restart", text: RESUME_NOTES.answered } },
 };
 

package/src/history-state.ts

@@ -131,5 +131,12 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // The burn list for setup-time computer 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/runners-store.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/index.ts

@@ -59,6 +59,8 @@ export { historyContract } from "./contracts/history.contract.js";
 /* Deliberately NOT part of `sandboxContract` below: that map is the daemon's own HTTP surface, and this one is
  * spoken the other way round, over a connected computer's WebSocket, with the MACHINE implementing it. */
 export { hostContract } from "./contracts/host.contract.js";
+// Same inversion, other direction of trust: spoken over a RUNNER's WebSocket, with the runner implementing it.
+export { runnerContract } from "./contracts/runner.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
@@ -104,8 +106,10 @@ export * from "./agent-run-model.js";
 export * from "./capability-env.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
+export * from "./documents.js";
 export * from "./fast-tier.js";
 export * from "./host-protocol.js";
+export * from "./runner-protocol.js";
 export * from "./listener-protocol.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";
@@ -115,6 +119,7 @@ export * from "./quick-model.js";
 export * from "./output-fields.js";
 export * from "./publish-drafts.js";
 export * from "./schemas.js";
+export * from "./definition.js";
 export * from "./search-globs.js";
 export * from "./starter.js";
 export * from "./terminal-protocol.js";

package/src/runner-protocol.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+
+/* THE RUNNER LINK'S EDGES: the handshake on /system/runners/connect, the env a runner boots with, and the
+ * placement value a turn request carries. The procedures spoken over the link once it exists live in
+ * contracts/runner.contract.ts; the design is docs/remote-runners-plan.md (workspace root).
+ *
+ * A runner is the sandbox image booted in runner mode: no browser owner, no tunnel, no public name. It dials
+ * its PARENT sandbox and executes turns the parent dispatches; the parent keeps owning the conversation. The
+ * host link (host-protocol.ts) is the pattern for everything here, one outbound socket that authenticates in
+ * its first frame, because a runner sits behind the same NATs and private networks a laptop does. */
+
+// The env the runner container boots with: who to dial, and the single-use pairing that gets it enrolled.
+// Named here so `ic runner up`, the Fly provisioner and the daemon's boot detection spell them identically.
+export const RUNNER_PARENT_URL_ENV = "RUNNER_PARENT_URL";
+export const RUNNER_PAIR_TOKEN_ENV = "RUNNER_PAIR_TOKEN";
+
+/* The first frame on /system/runners/connect, plain JSON, never oRPC, for host-protocol.ts's reason: a socket
+ * must prove whose it is before a typed link attaches, and the proof cannot be a call on a link that does not
+ * exist yet. The token rides the FRAME, never the URL (edge logs). */
+export const RunnerHelloSchema = z.object({
+    type: z.literal("runner-hello"),
+    // The runner's durable token, redeemed once from the pairing over /system/runners/enroll.
+    token: z.string(),
+    // The daemon build the runner runs, surfaced per runner so an old image is visible rather than
+    // mysteriously wrong.
+    version: z.string(),
+    /* Parity, reported rather than enforced: the parent knows what IT runs (image, channel, overlay hash) and
+     * shows a runner that drifted as "outdated" with a rebuild action. An outdated runner still runs turns, a
+     * stale toolchain is a fact the user can weigh, where a refusal would strand work. */
+    image: z.string(),
+    channel: z.string().optional(),
+    overlayHash: z.string().optional(),
+});
+export type RunnerHello = z.infer<typeof RunnerHelloSchema>;
+
+// The URL a runner dials, given its parent's public URL. One builder, so `ic`, the Fly provisioner and the
+// daemon route cannot disagree about where the door is (hostConnectUrl's rule).
+export const runnerConnectUrl = (parentUrl: string): string => `${parentUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/runners/connect`;
+
+// Where a runner redeems its pairing for the durable token, once, over plain HTTPS.
+export const runnerEnrollUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/enroll`;
+
+/* The parent's git door for ONE repository: stock `git fetch`/`git push` against the smart-HTTP pair the
+ * parent serves from its real git dirs (<historyRoot>/gits/<encoded id>), authenticated by the runner's own
+ * token as a bearer. One builder because three parties spell it: the parent's route, the runner's sync, and
+ * anyone debugging with a hand-typed clone. */
+export const runnerGitUrl = (parentUrl: string, repo: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/git/${encodeURIComponent(repo)}`;
+
+/* Where a runner's push LANDS in the parent's git dirs. Never refs/heads/agent/<id> directly: that branch is
+ * checked out in the parent's mirror worktree, and git itself refuses updating a checked-out ref, which is a
+ * safety property worth keeping rather than configuring away. The parent moves the branch by hard-resetting
+ * the mirror worktree to this ref, which advances the checked-out branch through the door git sanctions. */
+export const runnerIncomingRef = (conversationId: string): string => `refs/runner-incoming/${conversationId}`;
+
+/* THE CREDENTIAL DOORS: a runner's turns spend the ORIGIN sandbox's model providers, never accounts of their
+ * own. The shape is a service, not a sync: the parent resolves each turn's credential with the same code its
+ * local turns use and answers with the least that travels — an access token minted for the turn, or a route.
+ * Refresh tokens never leave the parent, which is what closes the rotation race two daemons refreshing one
+ * account would otherwise run. Design: docs/remote-runners-plan.md §8 (workspace root). */
+export const runnerCredentialsUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/credentials`;
+export const runnerCredentialRefreshUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/credentials/refresh`;
+
+/* The parent's model translator, re-served to runners: subscription-routed turns (codex/grok/kimi under the
+ * Claude Code harness, OpenAI-protocol endpoints, the trial) authenticate against a translator whose auth
+ * files live on the PARENT's /history. Rather than syncing those (the same rotation race), the runner's
+ * harness dials this authenticated proxy and the parent forwards to its loopback translator. The bearer is
+ * the runner's own token. */
+export const runnerTranslatorPath = "/system/runners/translator";
+export const runnerTranslatorUrl = (parentUrl: string): string => `${parentUrl.replace(/\/$/, "")}${runnerTranslatorPath}`;
+
+export const RunnerCredentialRequestSchema = z.object({
+    // The provider as the turn names it (absent = claude), an open vocabulary: endpoint/<id> included.
+    agent: z.string().optional(),
+    account: z.string().optional(),
+    model: z.string().optional(),
+});
+export type RunnerCredentialRequest = z.infer<typeof RunnerCredentialRequestSchema>;
+
+/* What travels back, by kind:
+ *   oauth             — a native-Claude access token minted for this turn; `account` present when it is a
+ *                       stored account (then the refresh door re-mints mid-turn), absent for the parent's
+ *                       container-env fallback, which has nothing to rotate.
+ *   parent-translator — run against the parent's translator through the proxy above; the runner supplies its
+ *                       own token as the bearer (the parent never echoes a credential it only holds hashed).
+ *   endpoint          — a foreign endpoint the runner can dial directly (an anthropic-protocol Endpoint
+ *                       capability), with the bearer that endpoint wants.
+ * A refusal is a value with the same codes local resolution uses, so the composer's connect gates read a
+ * remote refusal exactly as a local one. */
+export const RunnerCredentialSchema = z.union([
+    z.object({ ok: z.literal(true), kind: z.literal("oauth"), accessToken: z.string(), account: z.string().optional() }),
+    z.object({ ok: z.literal(true), kind: z.literal("parent-translator"), model: z.string(), trial: z.boolean().optional() }),
+    z.object({
+        ok: z.literal(true),
+        kind: z.literal("endpoint"),
+        baseUrl: z.string(),
+        authToken: z.string(),
+        model: z.string(),
+        trial: z.boolean().optional(),
+    }),
+    z.object({
+        ok: z.literal(false),
+        code: z.enum(["subscription-required", "claude-reauth", "trial-unavailable"]).optional(),
+        message: z.string(),
+    }),
+]);
+export type RunnerCredential = z.infer<typeof RunnerCredentialSchema>;
+
+export const RunnerCredentialRefreshRequestSchema = z.object({
+    account: z.string().min(1),
+    // The token the harness was refused with, so the parent's rotation supersedes exactly that one and a
+    // token another turn already rotated is adopted, never re-refreshed (claude-credentials' own rule).
+    rejected: z.string().min(1),
+});
+export type RunnerCredentialRefreshRequest = z.infer<typeof RunnerCredentialRefreshRequestSchema>;
+
+// `accessToken` absent ⇒ the parent could not re-mint (a revoked account); the harness gives up exactly as a
+// local turn whose refresh returned nothing does.
+export const RunnerCredentialRefreshSchema = z.object({ accessToken: z.string().optional() });
+export type RunnerCredentialRefresh = z.infer<typeof RunnerCredentialRefreshSchema>;
+
+// What a runner is, hardware-wise: what the placement picker shows and what a future scheduler weighs.
+export const RunnerFactsSchema = z.object({
+    cpus: z.number().int().positive(),
+    memoryMb: z.number().int().positive(),
+    freeDiskMb: z.number().int().nonnegative(),
+    // 0..1 of the last minute, the coarse "is it busy" a picker needs, not a metrics feed.
+    load: z.number().nonnegative(),
+});
+export type RunnerFacts = z.infer<typeof RunnerFactsSchema>;
+
+// One runner as the owner's views list it: enrolled state plus whatever the hub knows right now, the
+// HostSummary shape retold for a runner (no platform/scopes, parity instead).
+export const RunnerSummarySchema = z.object({
+    id: z.string(),
+    online: z.boolean(),
+    version: z.string().optional(),
+    image: z.string().optional(),
+    channel: z.string().optional(),
+    overlayHash: z.string().optional(),
+    facts: RunnerFactsSchema.optional(),
+    lastSeen: z.number().optional(),
+});
+export type RunnerSummary = z.infer<typeof RunnerSummarySchema>;
+
+/* A workspace sync, narrated as it happens: a first contact clones whole repositories, and a person may be
+ * watching the "preparing runner" state, so the lines travel while they are produced (runSandboxFlow's
+ * argument). `op` says which direction: `pull` brings the runner's checkout of the conversation's branch (and
+ * each repo's main line) up to date before a turn, `push` returns the branch after one.
+ *
+ * `repos` is the conversation's composition as the parent recorded it, because only the parent can know it:
+ * the runner's own discovery would see whatever its mirror held from LAST time, and a repo added to the
+ * workspace since would silently fall out of the conversation. Each entry names the repo id (the git-door
+ * address), the workspace-relative dir the checkout lives at, and the repo's own main branch name. */
+export const RunnerSyncSchema = z.object({
+    op: z.enum(["pull", "push"]),
+    conversationId: z.string().min(1),
+    branch: z.string().min(1),
+    repos: z.array(
+        z.object({
+            repo: z.string().min(1),
+            // "" for the workspace root itself; every other repo sits at its root-relative dir.
+            dir: z.string(),
+            mainBranch: z.string().min(1),
+        }),
+    ),
+});
+export type RunnerSync = z.infer<typeof RunnerSyncSchema>;
+
+export const RunnerSyncLineSchema = z.union([
+    z.object({ kind: z.literal("line"), text: z.string() }),
+    z.object({ kind: z.literal("done"), ok: z.boolean(), detail: z.string().optional() }),
+]);
+export type RunnerSyncLine = z.infer<typeof RunnerSyncLineSchema>;
+
+/* One turn, as dispatched. Deliberately NOT AgentTurnSchema: that schema is the browser's request to the
+ * parent, full of fields the parent resolves before anything executes (persona, account, title, forks). What
+ * crosses the link is the residue after resolution, what the runner's harness spawn actually needs, plus the
+ * attachments inline, because the runner has no route onto the parent's attachment store. */
+export const RunnerTurnSchema = z.object({
+    conversationId: z.string().min(1),
+    branch: z.string().min(1),
+    prompt: z.string(),
+    provider: z.string(),
+    harness: z.string(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+    thinking: z.boolean().optional(),
+    fast: z.boolean().optional(),
+    // Which of the ORIGIN sandbox's connected accounts pays for the turn: the runner resolves credentials
+    // against the parent (the credential doors below), so this names an account THERE.
+    account: z.string().optional(),
+    sessionId: z.string().optional(),
+    // Base64 because frames are JSON: small by policy (the request schema already caps attachment count), and
+    // a turn's attachments are the one payload with no git road to travel. `path` is the workspace-relative
+    // path the prompt already names; the runner writes the bytes there so the words and the file agree.
+    attachments: z.array(z.object({ path: z.string().min(1), bytesBase64: z.string() })).optional(),
+});
+export type RunnerTurn = z.infer<typeof RunnerTurnSchema>;
+
+/* WHERE A CONVERSATION RUNS, decided on its first turn and owned by the conversation from then on, exactly as
+ * `isolated` placement already works (agent.routes.ts): later turns follow the registry entry, not whichever
+ * client sends them. `runner` implies isolation, a remote conversation is always branch-anchored, because its
+ * branch is the unit that moves between machines. Absent means local, which is why this is optional
+ * everywhere: the default costs nothing to anyone who never uses it. */
+export const AgentPlacementSchema = z.union([
+    z.object({ kind: z.literal("local") }),
+    z.object({ kind: z.literal("runner"), id: z.string().min(1) }),
+]);
+export type AgentPlacement = z.infer<typeof AgentPlacementSchema>;