@intentic/sandbox-contract 1.312.0 → 1.314.0

package/src/schemas/agent.ts

@@ -1,3 +1,4 @@
+import { TurnErrandSchema } from "./speaker.js";
 import { z } from "zod";
 import { CONVERSATION_ID } from "../ids/conversation-ids.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
@@ -129,6 +130,9 @@ export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
 // The turn's fields before the cross-field refinements below, so a subset (TurnProfileSchema) can be picked from them.
 const AgentTurnFieldsSchema = z.object({
     prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
+    errand: TurnErrandSchema.optional().describe(
+        "What the words are for, when the app or the sandbox composed them rather than a person typing them: a land conflict to resolve, a red main line to fix. Shown as the sandbox's words, not yours. Leave it out for your own words.",
+    ),
     // Minted by the sender so a send whose answer was lost can be sent again without being delivered twice.
     messageId: z
         .string()
@@ -164,8 +168,14 @@ const AgentTurnFieldsSchema = z.object({
     // Which agentic loop runs the turn, absent = provider's own; "claude-code" forces the SDK loop for any
     // provider.
     harness: AgentHarnessSchema.optional().describe("Which agentic loop runs the turn. Leave it out to use each provider's own."),
-    // Which connected account of that provider serves the turn; absent = the provider's first account.
-    account: z.string().optional().describe("Which of that provider's connected accounts pays for the turn. Leave it out for the first one."),
+    // Intent, not a guess: absent continues on the conversation's own account, or picks by serviceability where there is
+    // none on this provider yet (agent/providers/accounts/routing.ts).
+    account: z
+        .string()
+        .optional()
+        .describe(
+            "Which of that provider's connected accounts pays for the turn. Leave it out to continue on the account the conversation runs on, or, for its first turn on this provider, to take whichever account can serve with the most room. To move a running conversation, use `switchAccount`.",
+        ),
     // Distinct from `account` (who pays): whose name the turn posts as; absent means something different for each
     // mode.
     actsAs: entryId.optional().describe("Which persona the turn speaks as out in the world. Not the same as which account pays for it."),
@@ -317,6 +327,19 @@ export const AgentTurnSchema = AgentTurnFieldsSchema
         message: 'forkOf.files "then" requires isolated',
     });
 export type AgentTurn = z.infer<typeof AgentTurnSchema>;
+// What a turn naming no provider or loop runs on, stated once. Applied where a request comes in (the daemon's turn port),
+// so nothing downstream defaults them again: the engine takes a turn with both named (withRuntimeDefaults).
+/** A turn with its provider and loop named, as the engine takes it past the door. */
+export type RoutedAgentTurn = AgentTurn & { readonly agent: AgentProvider; readonly harness: AgentHarness };
+export const DEFAULT_PROVIDER: AgentProvider = "claude";
+export const DEFAULT_HARNESS: AgentHarness = "native";
+export const withRuntimeDefaults = <T extends { readonly agent?: AgentProvider | undefined; readonly harness?: AgentHarness | undefined }>(
+    turn: T,
+): T & { readonly agent: AgentProvider; readonly harness: AgentHarness } => ({
+    ...turn,
+    agent: turn.agent ?? DEFAULT_PROVIDER,
+    harness: turn.harness ?? DEFAULT_HARNESS,
+});
 // Which turn this is, as opposed to what it says: who serves it and how (agent, harness, account, model and its knobs),
 // as whom (actsAs), where (isolated), whether anyone watches (unattended) and for which job (runRole). A turn that
 // continues another (a resume, a wake, a nudge, a child's follow-up) carries this whole, never a hand-picked part.
@@ -357,7 +380,9 @@ export const AgentRunPickSchema = z
         account: z
             .string()
             .optional()
-            .describe("Which connected account of that provider pays, by its daemon-minted id. Leave it out for whichever has headroom."),
+            .describe(
+                "Which connected account of that provider pays, by its daemon-minted id. Leave it out to take whichever account can serve with the most room.",
+            ),
         harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Leave it out to use the provider's own."),
         effort: z
             .string()

package/src/schemas/agents.ts

@@ -56,7 +56,7 @@ export const AgentAttentionSchema = z.object({
     plan: z.boolean().describe("It has proposed a plan and is waiting for a yes."),
     question: z.boolean().describe("It has asked you something."),
     permission: z.boolean().describe("It wants to use a tool it needs permission for."),
-    // A missing capability (capabilities/capability-offer.ts); lets the lane say "setup needed" rather than a generic
+    // A missing capability (capabilities/offers/capability-offer.ts); lets the lane say "setup needed" rather than a generic
     // pause.
     capability: z.boolean().describe("It needs something connected that is not connected yet."),
     // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear
@@ -136,6 +136,12 @@ export const LandedMessageSchema = z.object({
         .string()
         .optional()
         .describe("Why a test this change weakened is meant to be weaker, in the conversation's own words. Nearly always absent."),
+    // Present only when the conversation declared an exception a check should grant this change (`Allow: <check> — <reason>`);
+    // the check after the land and the push read it off the commit.
+    allows: z
+        .array(z.string())
+        .optional()
+        .describe("Exceptions the conversation declared for this change, each `<check> — <reason>` in its own words. Nearly always absent."),
 });
 export type LandedMessage = z.infer<typeof LandedMessageSchema>;
 // One model's turn in the drafting walk (agent/role-model.ts tries connected models in order), in spend order:
@@ -258,6 +264,12 @@ export const AgentSummarySchema = z.object({
     // Both latched at the first turn, so a board scoped to one project can say which conversations are its own.
     startIn: z.string().optional().describe("Which folder it opened in, relative to the workspace root. Absent means the root."),
     actsAs: z.string().optional().describe("Which persona its first turn acted as. Absent for an ordinary chat."),
+    lastActsAs: z
+        .string()
+        .optional()
+        .describe(
+            "Which persona its last turn acted as: each turn runs as the persona it names, so this is who the conversation speaks as now, and what a view groups it under. Absent for an ordinary chat.",
+        ),
     // Per-conversation, so opening it restores its own choices rather than another tab's; `fast` here is what was asked
     // for, not what was served.
     model: z
@@ -356,10 +368,12 @@ export const AgentSummarySchema = z.object({
                 .describe(
                     "When the date written into the agent's prompt next changes, in milliseconds (midnight where the agent runs). Past it the next turn sends a different prompt, so nothing kept before it is read again.",
                 ),
-            keepable: z
-                .boolean()
+            keepableUntil: z
+                .number()
                 .optional()
-                .describe("Whether this sandbox can keep this cache warm: it holds the last turn's exact request to replay, on a Claude subscription account."),
+                .describe(
+                    "Present when this sandbox can keep this cache warm (its provider can replay the last turn's prefix): the furthest instant a hold can reach, in milliseconds, where refreshing would cost more than the cold resume it saves or the date in the prompt changes, whichever comes first.",
+                ),
         })
         .optional()
         .describe(
@@ -405,7 +419,7 @@ export const AgentSummarySchema = z.object({
             "When somebody last opened it, in milliseconds. Newer activity than this is what makes it unread. Kept by the sandbox rather than by a browser, so clearing site data or picking up a phone does not resurrect every badge.",
         ),
     attention: AgentAttentionSchema.describe("Which kinds of waiting-for-you it is doing."),
-    // Only the causes that still hold, re-read live (agents/land/standing.ts), never the stored report's own list: a
+    // Only the causes that still hold, re-read live (conversations/land/standing.ts), never the stored report's own list: a
     // blocker the user has since cleared is not something to offer them an action about.
     conflictCauses: z
         .array(LandConflictReasonSchema)
@@ -482,6 +496,14 @@ export const AgentSummarySchema = z.object({
         .describe(
             "The workflow run this conversation is a step of. Without it, a four-step run reads as four unrelated conversations that happen to have started together.",
         ),
+    // The one reading of "runs again by itself" (the daemon's awaitingWake, conversation-state.ts): status, fixStance and
+    // the card read it, never the watch list, which is only what the card lists. Absent from a daemon older than it.
+    awaitingWake: z
+        .boolean()
+        .optional()
+        .describe(
+            "Whether this conversation runs again by itself with nobody pressing anything: a watch is armed on it, or words the sandbox or another agent sent wait for it. A finished-looking card that is awaiting a wake is not finished yet.",
+        ),
     // Outside conditions a conversation is parked on; a finished-looking card can restart itself when one fires, and an
     // armed watch keeps a hosted machine (and its bill) awake. The check command itself never rides the wire, since it
     // may hold a secret.
@@ -508,7 +530,7 @@ export const AgentSummarySchema = z.object({
                 startedAt: z.number().describe("When it started, in milliseconds."),
                 endedAt: z.number().optional().describe("When the command exited, in milliseconds. Absent while it runs."),
                 exitCode: z.number().int().optional().describe("The code it exited with. Absent while it runs, or when its exit left none."),
-                // What the turn that left it running decided about it (agent/tools/job-fates.ts): one of these, or none
+                // What the turn that left it running decided about it (agent/tools/jobs/job-fates.ts): one of these, or none
                 // while its turn is still going.
                 watch: z
                     .string()
@@ -520,7 +542,7 @@ export const AgentSummarySchema = z.object({
                     .boolean()
                     .optional()
                     .describe(
-                        "Left running for the person: the turn's reply gave its address, so it outlives the turn, wakes nothing and is theirs to stop.",
+                        "Left running for the person: the agent kept it for them with the `keep` tool (or it holds a port this conversation already left them), so it outlives the turn, wakes nothing and is theirs to stop.",
                     ),
                 ports: z.array(z.number().int()).optional().describe("The ports it was listening on when its turn ended."),
                 stoppedBy: z
@@ -545,6 +567,10 @@ export const AgentSummarySchema = z.object({
         ),
 });
 export type AgentSummary = z.infer<typeof AgentSummarySchema>;
+// Whether a conversation runs again by itself: the daemon's own reading, or, from a daemon older than it, whether a watch
+// is armed, which was all that one could say.
+export const awaitsWake = (agent: { readonly awaitingWake?: boolean | undefined; readonly watches?: readonly unknown[] | undefined }): boolean =>
+    agent.awaitingWake ?? (agent.watches?.length ?? 0) > 0;
 // One armed watch as a card carries it; derived from AgentSummarySchema.watches so the two shapes can't drift apart.
 export type AgentWatch = NonNullable<AgentSummary["watches"]>[number];
 // One background job as a card carries it.

package/src/schemas/automations.ts

@@ -297,8 +297,10 @@ export const AutomationSchema = z.object({
         .describe(
             "Which models this automation may run on, best first. Required, and nothing is chosen for you: work that fires while nobody is watching spends a real allowance, so it names the models it spends rather than inheriting one. Tried in order, so a spent account does not silently stop the job.",
         ),
-    // Absent means the provider's first account; pinning matters more here than for a chat, since nobody is watching to
-    // notice a stuck one.
+    // Absent means the daemon's pick: the account its conversation runs on for a continuing thread (moved off one that
+    // can no longer serve), else the one that can serve with the most room. Named, it is a pin, run whatever its state,
+    // so a refused account says so rather than being swapped; pinning matters more here than for a chat, since nobody
+    // is watching to notice a stuck one.
     account: z.string().optional().describe("Which account pays for it."),
     // Absent means the wake reaches no logged-in account at all, the strictest default here, since nobody is at the
     // composer when it fires.

package/src/schemas/devices.ts

@@ -1,6 +1,6 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
-import { hostEntryOf, hostEnvironmentOf, type DeviceFacts, DeviceFactsSchema, userDistrosOf, WslEnvironmentSchema } from "./hosts.js";
+import { parseHostConnection, type DeviceFacts, DeviceFactsSchema, MachineIdSchema, userDistrosOf, WslEnvironmentSchema } from "./hosts.js";
 import { DEV_VERSION } from "../state/versions.js";
 // Desktop-sync report shape shared by the agent, daemon and browser, produced only by the agent's own `deviceReport`.
 // The agent never reports `sandboxes`; the docker half is filled in by whoever reads the report, scoped to the reader's
@@ -9,14 +9,33 @@ import { DEV_VERSION } from "../state/versions.js";
 // One sandbox's resource share as docker currently enforces it, read off the container by the machine agent.
 // `overlayRuntime` is the environment's locked demand; `hostRuntime` is the owner's addition; `privileged`/`gpu` are
 // docker's enforced truth.
-// Reshape request, turned into `ic sandbox reshape` flags: absent means leave it, `null` on the two caps means back to
-// the default; at least one key must be set.
+// A delta against what runs: absent means leave it, `null` on the two caps means back to the default; at least one key
+// must be set. What the old `reshape` op carries, which the machine agent carries out as `ic sandbox shape --set` (its
+// `olderResizePlan`); `set-shape` carries a whole shape instead.
 export const SandboxResourcesAskFieldsSchema = z.object({
     memoryGib: z.int().positive().nullable().optional(),
     cpus: z.int().positive().nullable().optional(),
     privileged: z.boolean().optional(),
     gpu: z.boolean().optional(),
 });
+// A sandbox's shape, WHOLE: the owner's own ask for its share of the machine, every field a value. `null` on a cap is
+// the contract's default (the share derived from the engine, or every core). The switches are the owner's ask, not
+// docker's answer: a directive the approved environment demands rides beside it (`overlayRuntime`), and a host
+// without the NVIDIA runtime drops the GPU. `ic` stores it, validates it against the image's run contract when it is
+// saved, and prints it in `ic sandbox list --json`; nobody else merges anything into it.
+export const SandboxShapeSchema = z.object({
+    memoryGib: z.int().positive().nullable(),
+    cpus: z.int().positive().nullable(),
+    privileged: z.boolean(),
+    gpu: z.boolean(),
+});
+export type SandboxShape = z.infer<typeof SandboxShapeSchema>;
+// When a `set-shape` takes effect: `now` restarts the sandbox onto it; `nextRestart` saves it in ic's record and
+// restarts nothing, and the next restart through ic applies it — Restart or Start from any door, an update, a rollback
+// or a rebuild. Docker restarting the container by itself (after a crash or a reboot) does not: only ic recreates one.
+export const SandboxShapeWhenSchema = z.enum(["now", "nextRestart"]);
+export type SandboxShapeWhen = z.infer<typeof SandboxShapeWhenSchema>;
+
 export const SandboxResourcesSchema = z.object({
     // The cgroup memory ceiling in bytes; absent when docker imposes none (the hosted shape).
     memoryBytes: z.number().optional(),
@@ -26,14 +45,19 @@ export const SandboxResourcesSchema = z.object({
     gpu: z.boolean(),
     hostRuntime: z.array(z.string()),
     overlayRuntime: z.array(z.string()),
-    // A reshape saved for the sandbox's next restart (`ic sandbox reshape --later`) and not yet in force: the next
-    // update, rollback, rebuild, reshape or Restart applies it. Absent when nothing is saved.
+    // The shape the container runs with (the owner's ask it carries). Absent from an agent older than `set-shape`.
+    shape: SandboxShapeSchema.optional(),
+    // The shape saved for the sandbox's next restart through ic, and not yet in force. Absent when nothing is saved.
+    desired: SandboxShapeSchema.optional(),
+    // READ-ONLY, from agents older than `set-shape`: their saved share, a delta against what runs. Nothing new writes
+    // it; kept one release so a newer page can still show what an older agent saved. Remove with `later`.
     saved: SandboxResourcesAskFieldsSchema.optional(),
 });
 export type SandboxResources = z.infer<typeof SandboxResourcesSchema>;
 
 // Fields also exported separately for callers that compose them and enforce the at-least-one rule themselves.
-export const SandboxResourcesAskSchema = SandboxResourcesAskFieldsSchema.refine((ask) => Object.values(ask).some((value) => value !== undefined), {
+// Strict like every device input (DeviceSandboxFlowSchema says why): it is only ever sent to a device.
+export const SandboxResourcesAskSchema = SandboxResourcesAskFieldsSchema.strict().refine((ask) => Object.values(ask).some((value) => value !== undefined), {
     message: "a reshape must change at least one thing",
 });
 export type SandboxResourcesAsk = z.infer<typeof SandboxResourcesAskSchema>;
@@ -50,10 +74,14 @@ export const DeviceSandboxSchema = z.object({
     tunnelRunning: z.boolean().optional(),
     // Absent when the reader only ran a cheap `docker ps` listing without inspecting the container.
     resources: SandboxResourcesSchema.optional(),
+    // The update `ic sandbox prepare` built and left waiting for this sandbox; absent when nothing is staged.
+    staged: z.object({ image: z.string(), version: z.string().optional(), channel: z.string().optional() }).optional(),
 });
 export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
 // One operation on one sandbox, streamed as lines ending in a `result` or `error` frame. `prepare` builds the pending
-// update without touching the container; `reshape` changes only its resources and privileges, not the image.
+// update without touching the container. `set-shape` sets its resources and privileges, now or for the next restart;
+// `forget-shape` drops a shape saved for the next restart. `start`/`restart` apply a saved shape (all through `ic`).
+// `reshape` is the older spelling of `set-shape`, kept one release for pages served by older sandboxes.
 // `runner-up`/`runner-remove` act on a runner (this sandbox's own container), not a person's sandbox; gated by the
 // `sandboxes` switch, not removal, since a runner holds no separate workspace to lose.
 export const DeviceSandboxOpSchema = z.enum([
@@ -65,6 +93,8 @@ export const DeviceSandboxOpSchema = z.enum([
     "rebuild",
     "rollback",
     "reshape",
+    "set-shape",
+    "forget-shape",
     "remove",
     "logs",
     // The two ops that redeem a fresh setup code; every other one recreates a container from its own existing env.
@@ -76,7 +106,11 @@ export const DeviceSandboxOpSchema = z.enum([
     "runner-remove",
 ]);
 export type DeviceSandboxOp = z.infer<typeof DeviceSandboxOpSchema>;
-export const DeviceSandboxFlowSchema = z.object({
+// STRICT, like every input a device is sent: an agent rejects a field it does not know instead of dropping it and doing
+// something else (an older agent once dropped `later` and restarted a sandbox it had been asked to leave running). New
+// behaviour is a new `op`, which an older agent refuses by name, and the daemon refuses an op the agent has not
+// advertised before sending it (device-reports.ts).
+export const DeviceSandboxFlowSchema = z.strictObject({
     op: DeviceSandboxOpSchema,
     // Sandbox slug, the runner's name for the runner ops (as `/system/runners`/`ic runner list` know it), or for
     // `create` the name the claim is about to produce — the one op where the slug is an expectation rather than a
@@ -84,11 +118,14 @@ export const DeviceSandboxFlowSchema = z.object({
     slug: z.string().min(1),
     // Approved overlay's sha256, required only by `rebuild`; only content matching it is ever built.
     hash: z.string().optional(),
-    // What `reshape` should change, meaningless to the rest. Absent on a reshape applies what is saved for the next
-    // restart now; absent with `later` forgets what is saved.
+    // `set-shape` only, both required by it: the whole shape, and when it takes effect.
+    // Strict too, unlike the same shape read off a report (where a newer ic's extra field must not fail an older
+    // reader): an order carrying a field this agent does not know is refused rather than carried out without it.
+    shape: z.strictObject(SandboxShapeSchema.shape).optional(),
+    when: SandboxShapeWhenSchema.optional(),
+    // READ-ONLY for one release, from pages served by sandboxes older than `set-shape`: the old `reshape` op's delta,
+    // and `later` to save it for the next restart instead. Nothing new sends either.
     resources: SandboxResourcesAskSchema.optional(),
-    // `reshape` only: save `resources` for the sandbox's next restart instead of restarting it now, replacing
-    // whatever was saved before (`ic sandbox reshape --later`).
     later: z.boolean().optional(),
     // `runner-up` only, daemon-filled, never by the caller: the browser never holds the pairing credential.
     parentUrl: z.string().optional(),
@@ -104,6 +141,26 @@ export const DeviceSandboxFlowSchema = z.object({
     overlayHash: z.string().optional(),
 });
 export type DeviceSandboxFlow = z.infer<typeof DeviceSandboxFlowSchema>;
+// The `ic` argv for the shape and power ops, the one place any caller spells them: the machine agent runs it and the
+// Devices view prints it for a person to type when the app's route to the machine is shut. The shape travels as the
+// contract's own object, one `--set <field>=<JSON value>` per field, so no caller maps a field onto a flag of its own:
+// ic reads the pairs back into the contract's shape and refuses a field it does not know, as every device input does.
+// `when` is the contract's own word too. A field left out keeps what ic already has for it (the shape saved for the
+// next restart, else what runs): the Devices view always sends the whole shape, a model's tool call may name one
+// field. Nothing is judged here; ic checks the shape against the image's run contract. Needs an ic that takes `--set`
+// (the `set-shape` feature is advertised only then).
+export type SandboxShapeFields = { readonly [K in keyof SandboxShape]?: SandboxShape[K] | undefined };
+export const icShapeArgs = (slug: string, fields: SandboxShapeFields, when: SandboxShapeWhen): string[] => [
+    "sandbox",
+    "shape",
+    slug,
+    ...Object.entries(fields).flatMap(([field, value]) => (value === undefined ? [] : ["--set", `${field}=${JSON.stringify(value)}`])),
+    "--when",
+    when,
+];
+export const icForgetShapeArgs = (slug: string): string[] => ["sandbox", "shape", slug, "--forget"];
+// Power goes through ic too, so a Start or Restart from any door applies the shape saved for the next restart.
+export const icPowerArgs = (op: "start" | "stop" | "restart", slug: string): string[] => ["sandbox", op, slug];
 // Adds the device id to the flow input; the daemon looks up machines by id.
 export const DeviceSandboxFlowInputSchema = DeviceSandboxFlowSchema.extend({ id: z.string().min(1) });
 export type DeviceSandboxFlowInput = z.infer<typeof DeviceSandboxFlowInputSchema>;
@@ -123,7 +180,7 @@ export type DeviceFlowLine = z.infer<typeof DeviceFlowLineSchema>;
 // dropping one is always somebody's decision.
 export const DeviceAgentOpSchema = z.enum(["upgrade", "restart", "forget-unreachable"]);
 export type DeviceAgentOp = z.infer<typeof DeviceAgentOpSchema>;
-export const DeviceAgentFlowSchema = z.object({ op: DeviceAgentOpSchema });
+export const DeviceAgentFlowSchema = z.strictObject({ op: DeviceAgentOpSchema });
 export type DeviceAgentFlow = z.infer<typeof DeviceAgentFlowSchema>;
 // Adds the device id to the flow input.
 export const DeviceAgentFlowInputSchema = DeviceAgentFlowSchema.extend({ id: z.string().min(1) });
@@ -362,8 +419,10 @@ export const AGENT_STALL_AFTER_MS = 60_000;
 export const agentStalled = (agent: DeviceAgent, now: number): boolean =>
     agent.running && agent.lastTickAt !== undefined && now - agent.lastTickAt > AGENT_STALL_AFTER_MS;
 export const DeviceReportSchema = z.object({
-    // OS hostname; the join key that dedupes a machine seen via sync and via its `host` capability. Not unique on its
-    // own: a WSL distro inherits the Windows machine's name, so `wsl` below is what tells those apart.
+    // The computer this reading is from (MachineIdSchema): what a sync enrollment is stamped with when its agent posts,
+    // and so what joins a machine seen through sync to the same machine seen through its card. Absent from an older agent.
+    machineId: MachineIdSchema.optional(),
+    // OS hostname, for the owner to read; not a join key (a WSL distro inherits the Windows machine's name).
     hostname: z.string(),
     os: z.string(),
     // Present only inside a WSL distro; the same fact rides the connect-time facts, which no scope can withhold.
@@ -420,9 +479,8 @@ export const DeviceGapSchema = z.enum([
     "unreported",
 ]);
 export type DeviceGap = z.infer<typeof DeviceGapSchema>;
-// A machine may be reachable via desktop sync and a host capability at once; the two are reconciled on `hostname` plus
-// the environment it came from (`environmentOf`), and left as separate rows when there is nothing to reconcile them by
-// or when the environments positively disagree.
+// A machine may be reachable via desktop sync and a host capability at once; the two are one row when both say the same
+// `machineId` and the same environment, and separate rows whenever either has not said (an agent too old to carry it).
 // `machine` is the enrollment's name for the box (the ssh key's comment): what reports are filed under and what the
 // revoke route takes. Two machines sharing a key comment share one enrollment identity.
 export const DeviceSyncSchema = z.object({
@@ -431,6 +489,10 @@ export const DeviceSyncSchema = z.object({
     mode: z.enum(["sync", "mirror"]),
     // When this machine last used its enrollment; absent means never, not merely unknown, and is not healthy.
     seenAt: z.number().optional(),
+    // The computer and the environment on it that hold this enrollment, as its agent said when enrolling or in a report
+    // since; absent until an agent new enough to say has done so.
+    machineId: MachineIdSchema.optional(),
+    environment: z.string().optional(),
 });
 export type DeviceSync = z.infer<typeof DeviceSyncSchema>;
 export const DeviceSchema = z.object({
@@ -440,8 +502,14 @@ export const DeviceSchema = z.object({
     label: z.string(),
     // Desktop-sync enrollment with this sandbox; absent when reached only via a host capability.
     sync: DeviceSyncSchema.optional(),
-    // The host capability's id, when this machine is also a connected device. Absent otherwise.
+    // The host connection's key, when this machine is also a connected device. Absent otherwise.
     hostId: z.string().optional(),
+    // The card that connection is of, beside the key rather than parsed out of it: the machine's name, a label. Absent
+    // with `hostId`, and from a daemon older than the field (`deviceCard` reads the key then).
+    card: z.string().optional(),
+    // The computer this row is an environment of, from whichever door has said (MachineIdSchema): what `machinesOf`
+    // groups by. Absent when no door has, which leaves the row a computer of its own.
+    machineId: MachineIdSchema.optional(),
     // Host-capability liveness; absent when there is no host capability, not the same as offline.
     online: z.boolean().optional(),
     // Carried beside the report so a device with no report still has an OS; `platform` is the normalised slug, `facts`
@@ -480,7 +548,7 @@ export const deviceHostname = (device: Device): string | undefined => device.fac
 // and that is all an environment nobody has reached since this daemon booted can say about itself: liveness resets on
 // restart, so facts and reports are absent on a side that is merely asleep.
 export const deviceEnvironment = (device: Device): string | undefined =>
-    environmentOf(device.facts, device.report) ?? (device.hostId === undefined ? undefined : hostEnvironmentOf(device.hostId));
+    environmentOf(device.facts, device.report) ?? (device.hostId === undefined ? undefined : parseHostConnection(device.hostId).environment);
 
 const WSL_PREFIX = "wsl:";
 export const isWslDevice = (device: Device): boolean => deviceEnvironment(device)?.startsWith(WSL_PREFIX) === true;
@@ -495,24 +563,25 @@ export const deviceDistro = (device: Device): string | undefined => {
 const byEnvironment = (a: Device, b: Device): number =>
     Number(isWslDevice(a)) - Number(isWslDevice(b)) || (deviceDistro(a) ?? a.label).localeCompare(deviceDistro(b) ?? b.label);
 
-const hostnameKey = (device: Device): string | undefined => deviceHostname(device)?.toLowerCase();
-
 // The card a device's door hangs off: one card is one computer, so two doors naming the same card are one machine
 // whatever either has said about itself — which is the whole of what an environment that has never connected says.
-const cardKey = (device: Device): string | undefined => (device.hostId === undefined ? undefined : hostEntryOf(device.hostId));
-
-// What makes two devices one computer: a shared card, or a shared hostname where a distro answers to it, since WSL
-// hands a distro the Windows machine's name. Two native installs that merely share a name stay two machines.
-const tokensOf = (device: Device, distroNames: ReadonlySet<string>): string[] => {
-    const card = cardKey(device);
-    const hostname = hostnameKey(device);
-    return [
-        ...(card === undefined ? [] : [`card:${card.toLowerCase()}`]),
-        ...(hostname !== undefined && distroNames.has(hostname) ? [`host:${hostname}`] : []),
-    ];
+// The row's own label, else its key read by the one parser there is (a row from a daemon older than `card`).
+export const deviceCard = (device: Pick<Device, "card" | "hostId">): string | undefined =>
+    device.card ?? (device.hostId === undefined ? undefined : parseHostConnection(device.hostId).card);
+
+// The computer a device is on, by whichever door said: its row, its connect-time facts, its report, its sync enrollment.
+export const deviceMachineId = (device: Device): string | undefined =>
+    device.machineId ?? device.facts?.machineId ?? device.report?.machineId ?? device.sync?.machineId;
+
+// What makes two devices one computer: a shared card, or a shared machine id. Nothing else: a hostname is shared by a
+// PC and its WSL distros and by two unrelated machines with the same name, so it joined things by accident.
+const tokensOf = (device: Device): string[] => {
+    const card = deviceCard(device);
+    const machine = deviceMachineId(device);
+    return [...(card === undefined ? [] : [`card:${card.toLowerCase()}`]), ...(machine === undefined ? [] : [`machine:${machine}`])];
 };
 
-// Components over both joins at once: a device holding a card token and a hostname token is the evidence that merges
+// Components over both joins at once: a device holding a card token and a machine token is the evidence that merges
 // the machines those tokens named, so a distro connected under a card of its own still lands on the PC it runs on.
 interface Component {
     readonly tokens: Set<string>;
@@ -520,10 +589,9 @@ interface Component {
 }
 
 const componentsOf = (devices: readonly Device[]): Component[] => {
-    const distroNames = new Set(devices.filter(isWslDevice).map(hostnameKey).filter((name) => name !== undefined));
     const components: Component[] = [];
     for (const device of devices) {
-        const tokens = tokensOf(device, distroNames);
+        const tokens = tokensOf(device);
         const [head, ...merged] = components.filter((component) => tokens.some((token) => component.tokens.has(token)));
         if (head === undefined) {
             components.push({ tokens: new Set(tokens), devices: [device] });
@@ -544,7 +612,7 @@ const componentsOf = (devices: readonly Device[]): Component[] => {
 
 // Addressed by the card of the side that owns the screen, an address that does not change when a second environment
 // connects — unlike a row key, which is a hostname another environment can take first. An uncarded fold has only the
-// hostname its doors share, and an uncarded lone device its own key. Called what the owner calls it: the name the
+// machine id its doors share, and an uncarded lone device its own key. Called what the owner calls it: the name the
 // leading environment carries, unless that is nothing but its door id, which reads as a PC named after one of its
 // own sides.
 const machineOf = (environments: readonly Device[]): Machine => {
@@ -553,8 +621,8 @@ const machineOf = (environments: readonly Device[]): Machine => {
     if (first === undefined) {
         return { key: "", label: "", environments };
     }
-    const named = environments.map(cardKey).find((key) => key !== undefined) ?? (rest.length === 0 ? undefined : deviceHostname(first));
-    const label = first.label === first.hostId ? (cardKey(first) ?? first.label) : first.label;
+    const named = environments.map(deviceCard).find((key) => key !== undefined) ?? (rest.length === 0 ? undefined : deviceMachineId(first));
+    const label = first.label === first.hostId ? (deviceCard(first) ?? first.label) : first.label;
     return { key: named ?? first.key, label, environments };
 };
 

package/src/schemas/extension-updates.ts

@@ -177,6 +177,12 @@ export const ExtensionSummarySchema = z.object({
         })
         .optional()
         .describe("Present only for an extension that ships a server half."),
+    problems: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "Declarations in its manifest the sandbox refused at load, each a sentence saying what and why, such as a listener for a provider another extension already owns. The rest of it still loads. Absent when nothing was refused.",
+        ),
     // Update lifecycle, present only for a git-installed extension (absent for builtin/workspace):
     // update: the badge.
     // advisory: the alarm.