@intentic/sandbox-contract 1.232.0 → 1.233.0

package/src/schemas/ci.ts

@@ -0,0 +1,235 @@
+// ci: pipeline runs on the workspace repos' github/gitlab remotes
+import { z } from "zod";
+import { AgentRunPickSchema } from "./agent.js";
+// The daemon maps each workspace repo to the CI project behind its remote (a connected github/gitlab
+// capability supplies the token), registers a webhook so completed pipelines dispatch `ci` listener
+// automations instantly, and serves the Pipelines rail view from a webhook-freshened cache backfilled over the
+// same REST clients. `host` names WHICH provider API serves a repo; the listener provider is always `ci`, one
+// automation covers both hosts because the repo, not the vendor, is what a trigger narrows to.
+
+export const CiHostSchema = z.enum(["github", "gitlab"]);
+export type CiHost = z.infer<typeof CiHostSchema>;
+// Terminal-or-not over both vendors' vocabularies: github's status+conclusion pair and gitlab's single status
+// both collapse onto these five. `running` covers everything non-terminal (queued, manual, preparing …), the
+// view only needs "still moving" vs the three ways it stopped.
+export const PipelineStatusSchema = z.enum(["running", "success", "failed", "canceled", "skipped"]);
+export type PipelineStatus = z.infer<typeof PipelineStatusSchema>;
+export const PipelineRunSchema = z.object({
+    // The workspace repo dir (the panels `repo` convention), the join key back to the tree and to triggers.
+    repo: z.string().describe("Which workspace repository it belongs to."),
+    host: CiHostSchema.describe("Which forge is running it."),
+    // owner/name (github) or the full project path (gitlab).
+    project: z.string().describe("The project there, as that forge names it."),
+    // The vendor's numeric run/pipeline id, what rerun/cancel address.
+    runId: z.number().describe("The forge's own id for the run, which is what re-running and cancelling take."),
+    // The run's headline: github's display_title (the commit subject, or the PR title when a PR triggered it),
+    // gitlab's pipeline name or the head commit's subject. Absent ⇒ the view falls back to ref@sha.
+    title: z
+        .string()
+        .optional()
+        .describe("The run's headline, usually the commit subject or the pull request's title. Absent means falling back to the branch and commit."),
+    // Who the vendor credits for the run, the actor who set it off, matching what both vendors' own UIs
+    // show. The avatar is a vendor-hosted URL; absent ⇒ the view draws the author's initials instead.
+    authorName: z.string().optional().describe("Who the forge credits for setting it off."),
+    authorAvatarUrl: z.string().optional().describe("Their picture, hosted by the forge. Absent means drawing their initials instead."),
+    // What set the run off, in the vendor's own vocabulary: gitlab's pipeline `source` (push, schedule,
+    // merge_request_event, web, api, trigger…) or github's `event` (push, pull_request, schedule,
+    // workflow_dispatch…). Left raw rather than flattened into a shared enum, the vendor's word is the
+    // precise one, and the view only calls it out when it isn't the everyday push.
+    trigger: z
+        .string()
+        .optional()
+        .describe(
+            "What set it off, in the forge's own word rather than flattened into a shared vocabulary, because the forge's word is the precise one.",
+        ),
+    branch: z.string().describe("Which branch."),
+    sha: z.string().describe("Which commit."),
+    status: PipelineStatusSchema.describe(
+        "How it is going. Running covers everything still moving, since the only distinction that matters is that against the three ways it can stop.",
+    ),
+    // The vendor's run page, the deep link out.
+    url: z.string().describe("Its page on the forge."),
+    createdAt: z.number().describe("When it started, in milliseconds."),
+    durationSeconds: z.number().optional().describe("How long it took."),
+    // Names of the failed jobs, fetched only for failed runs (one extra call), so a wake or a view names what broke.
+    failedJobs: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "What broke, by name. Fetched only for failed runs, so that a notification or a screen can say what went wrong rather than just that something did.",
+        ),
+});
+export type PipelineRun = z.infer<typeof PipelineRunSchema>;
+/* One job inside a pipeline run. The view fetches these lazily (one extra call per visible run) so the list
+ * endpoint stays cheap. Both GitHub Actions jobs and GitLab CI jobs normalize onto these fields.
+ *
+ * HOW THE VIEW LEARNS THE RUN'S SHAPE, in descending order of truth:
+ *   1. `needs`, the dependencies the pipeline itself declares. The real graph, and the only one that can say
+ *      a job waited on THIS one rather than on everything before it. Neither vendor's jobs API returns it, so
+ *      it is read out of the pipeline definition (github: workflowGraph.ts) and is absent whenever that could
+ *      not be resolved, a private workflow file, a deleted one, a name no declared job matches.
+ *   2. `stage`. GitLab's native sequential grouping, returned by its jobs API and used verbatim.
+ *   3. The timestamps, the last resort, and GitHub's before `needs` existed: overlapping runtimes ⇒ the jobs
+ *      ran in parallel. Honest about when things happened, silent about what actually gated what.
+ * Both timestamps are epoch ms; absent while a job is still queued. */
+export const PipelineJobSchema = z.object({
+    name: z.string().describe("The job's name."),
+    status: PipelineStatusSchema.describe("How it went."),
+    stage: z.string().optional().describe("Which stage it belongs to, where the pipeline groups its jobs that way."),
+    // Names of jobs IN THIS RUN that this one declared it waits on. Absent ⇒ nothing was resolved and the view
+    // must fall back; an empty array is the different, meaningful claim that this job is a root.
+    needs: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "Which jobs in this run it declared it waits on: the real shape of the pipeline. Absent means nothing could be read, which is different from an empty list, which is the claim that it waits on nothing.",
+        ),
+    startedAt: z.number().optional().describe("When it began, in milliseconds. Absent while it is queued."),
+    finishedAt: z.number().optional().describe("When it ended, in milliseconds."),
+    durationSeconds: z.number().optional().describe("How long it took."),
+    // The job's page on its host, the shortest path from "this step failed" to the log that says why.
+    webUrl: z.string().optional().describe("Its page on the forge, which is the shortest path from this step failed to the log that says why."),
+});
+export type PipelineJob = z.infer<typeof PipelineJobSchema>;
+export const CiJobsResponseSchema = z.object({
+    jobs: z.array(PipelineJobSchema).describe("The steps inside one run. Fetched separately from the run list, so that list stays cheap."),
+});
+export type CiJobsResponse = z.infer<typeof CiJobsResponseSchema>;
+// One mapped repo's CI wiring state. `hookWarning` is the manual-setup story when webhook registration was
+// refused (token scope, role) or impossible (no public URL): what happened plus the target URL + secret to
+// paste into the repo's webhook settings, the git-access sshRegistrationWarning pattern.
+export const CiRepoSchema = z.object({
+    repo: z.string().describe("Which workspace repository."),
+    host: CiHostSchema.describe("Which forge it lives on."),
+    project: z.string().describe("The project there."),
+    // The project's home page on its host.
+    url: z.string().describe("Its page on the forge."),
+    hookWarning: z
+        .string()
+        .optional()
+        .describe(
+            "Present when the sandbox could not register for instant notifications, with what happened and what to paste in by hand. Without them the sandbox polls instead, so this costs a couple of minutes' delay rather than the feature.",
+        ),
+});
+export type CiRepo = z.infer<typeof CiRepoSchema>;
+/* How often the daemon polls a repo whose webhook could NOT be registered (ci/poller.ts), the fallback that
+ * keeps a `ci` automation firing on a sandbox with no public URL or a token without hook scope.
+ *
+ * Here rather than beside the poller because both ends need the number: the daemon to run on it, and the
+ * automation editor to tell the owner what a `hookWarning` actually costs them. "Webhooks are off" is a fact
+ * about infrastructure; "this fires within two minutes instead of instantly" is the answer to the question
+ * they were really asking. */
+export const CI_POLL_INTERVAL_MS = 2 * 60_000;
+export const CiRunsResponseSchema = z.object({
+    repos: z.array(CiRepoSchema).describe("Which workspace repositories are wired to a forge, and how each one's notifications are set up."),
+    // Newest first, across all mapped repos.
+    runs: z.array(PipelineRunSchema).describe("Runs across all of them, newest first."),
+    // When the owner last opened the pipelines view. Rides the runs response so the rail can decide what is
+    // NEW without a second call, a breakage older than this has already been seen and must not badge again.
+    // Absent ⇒ never opened, so everything counts as unseen.
+    seenAt: z
+        .number()
+        .optional()
+        .describe(
+            "When this was last looked at, in milliseconds, so a badge can tell new breakages from ones already read without a second call. Absent means never, so everything counts as new.",
+        ),
+});
+export type CiRunsResponse = z.infer<typeof CiRunsResponseSchema>;
+// Stamping the view as read hands back the timestamp it wrote, so the client updates without a refetch.
+export const CiSeenResponseSchema = z.object({
+    seenAt: z.number().describe("The timestamp that was written, handed back so a caller can update without asking again."),
+});
+export type CiSeenResponse = z.infer<typeof CiSeenResponseSchema>;
+// rerun/cancel/fix address a run by repo + vendor id; the daemon re-resolves repo → project + token per call,
+// so a stale card can't act on a project the workspace no longer maps to.
+export const CiRunParamSchema = z.object({
+    repo: z
+        .string()
+        .describe(
+            "Which workspace repository. The project behind it is resolved fresh each call, so a stale screen cannot act on one the workspace no longer maps to.",
+        ),
+    runId: z.number().describe("Which run, by the forge's own id."),
+});
+export type CiRunParam = z.infer<typeof CiRunParamSchema>;
+// Fixing takes one thing the vendor proxies do not: which model to open the session on, when the user reached
+// for the caret beside the button rather than pressing it (AgentRunPickSchema). Absent is the ordinary path.
+export const CiFixParamSchema = CiRunParamSchema.extend({
+    pick: AgentRunPickSchema.describe(
+        "Which model to open the conversation on, when somebody chose one. Leave it out for the sandbox's own choice, which is the ordinary path.",
+    ),
+});
+export type CiFixParam = z.infer<typeof CiFixParamSchema>;
+// The fix route opens an isolated conversation (fleet card + chat tab) seeded with the failure context.
+export const CiFixResponseSchema = z.object({
+    conversationId: z.string().describe("The conversation that was opened, already holding the failure. Open it to watch, or attach to its turn."),
+});
+export type CiFixResponse = z.infer<typeof CiFixResponseSchema>;
+/* ---- the pre-push check: the workspace's own answer to "would this push go red" ----
+ *
+ * WHERE THIS SITS. A fleet of 5-20 agents lands work into the main tree, the user reviews and commits it by
+ * parts, pushes, and CI answers minutes later. The check front-runs that answer at the push itself, the last
+ * moment before the work leaves the machine, and the first moment at which what will be pushed is finally
+ * settled.
+ *
+ * WHY THE PUSH AND NOT THE LAND, which is where this used to run. A post-land verdict is about a tree that
+ * keeps moving: the user commits by parts, another agent lands, an edit arrives, so the verdict spent its life
+ * either stale or being recomputed, and needed a content fingerprint, a staleness rule and a badge to say which.
+ * All of that machinery existed to answer a question the push asks for free, because at the push there is
+ * exactly one artifact and the user is standing in front of it waiting.
+ *
+ * SO THERE IS NO STORED VERDICT AND NOTHING IS POLLED AT REST. A run exists while it runs, reports to the
+ * dialog that started it, and is gone. Nothing survives a daemon restart because nothing needs to: the next
+ * push asks again. */
+
+/* Where a run is.
+ *
+ *   idle     , nothing has run in this daemon's life, or the last run was cleared.
+ *   running  , the check is live. Its output is the terminal's (`session`), not this object's.
+ *   passed   , exited 0. The push goes.
+ *   failed   , exited non-zero, or was killed by prepushTimeoutMs (`timedOut`). The state a fix answers.
+ *   error    , the check could not run at all: the command was not spawnable. NOT a fix-able failure, because
+ *               there is nothing wrong with the code, the command is misconfigured, and saying "tests failed"
+ *               would send an agent hunting a bug that isn't there.
+ *   cancelled, the user stopped the run.
+ */
+export const PrepushStatusSchema = z.enum(["idle", "running", "passed", "failed", "error", "cancelled"]);
+export type PrepushStatus = z.infer<typeof PrepushStatusSchema>;
+export const PrepushRunSchema = z.object({
+    status: PrepushStatusSchema.describe(
+        "Where the run is. Failed and error are deliberately different: failed means the code is wrong, error means the command could not be run at all, and calling the second one a test failure would send an agent hunting a bug that is not there.",
+    ),
+    // The command this run executed, echoed rather than read back from settings: a result read after the
+    // setting changed still has to say what produced it.
+    command: z
+        .string()
+        .describe(
+            "What actually ran, echoed here rather than read back from the settings, so a result looked at after the setting changed still says what produced it.",
+        ),
+    startedAt: z.number().optional().describe("When it began, in milliseconds."),
+    finishedAt: z.number().optional().describe("When it ended, in milliseconds."),
+    exitCode: z.number().optional().describe("How the command exited."),
+    timedOut: z.boolean().optional().describe("It was killed for taking too long rather than finishing."),
+    /* The tmux session the suite runs in, for the browser to open the terminals panel on, the check is a
+     * visible terminal like every other shell command the daemon runs on a click (terminal/terminal-run.ts), so
+     * WATCHING it is not this object's job and never was. Absent where the sandbox has no tmux wrapper (local
+     * dev): the runner falls back to an invisible shell, and a name nothing can attach to would send the browser
+     * after a tab that is never going to be listed. */
+    session: z
+        .string()
+        .optional()
+        .describe(
+            "The terminal it runs in, which is where to watch it. Absent where the sandbox has no terminals, in which case there is nothing to attach to.",
+        ),
+    /* What the fix proposal quotes, and its only reader, tail-capped (PREPUSH_OUTPUT_BYTES) so a prompt seeded
+     * from a red run stays about fixing rather than scrolling. The TAIL, not the head: a suite's verdict and its
+     * failure summary are at the end. PLAIN TEXT, not what the terminal received: the suite's colour codes and
+     * redrawn progress lines are resolved away (terminal/plain-text.ts) before the cap, so a quoted tail reads
+     * as a failure instead of as litter. Empty while the run is going, and for a run that was killed: the pane
+     * (and its log) is where the whole of it lives. */
+    output: z
+        .string()
+        .describe(
+            "The end of what it printed, as plain text with the colour codes and redrawn progress lines resolved away. The end rather than the beginning, because a suite's verdict is at the end. Empty while it runs, and for one that was killed.",
+        ),
+});
+export type PrepushRun = z.infer<typeof PrepushRunSchema>;

package/src/schemas/claude-gate.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+// The GATE signal: whether the provider is letting turns through right now, and, when it is refusing, which
+// window is binding and when it lifts. This is the SDK's rate_limit_event, mapped one-to-one, and it is only
+// ever about the CURRENT moment. It is deliberately NOT the thing the headroom displays read: the event names a
+// single window (whichever the CLI considered binding), which is how "weekly 1%" ended up standing in for an
+// account that was really at 98% on another weekly pool.
+export const RateLimitInfoSchema = z.object({
+    status: z.enum(["allowed", "allowed_warning", "rejected"]),
+    resetsAt: z.number().optional(), // epoch seconds
+    rateLimitType: z.string().optional(), // 'five_hour' | 'seven_day' | 'seven_day_opus' | ...
+    utilization: z.number().optional(), // 0-100, how much of the window is used
+});
+export type RateLimitInfo = z.infer<typeof RateLimitInfoSchema>;

package/src/schemas/codebase-health.ts

@@ -0,0 +1,64 @@
+// codebase health: one repository's structure and risk, in numbers
+import { z } from "zod";
+import { WorkspaceSearchFreshnessSchema } from "./workspace-search.js";
+// The repo-level companion to the management panel and the git-history graph: what the same resident engine's
+// `hotspots` (churn × complexity) and `map` (PageRank over the import graph) verbs rank, as figures a panel can
+// plot instead of lines a terminal prints.
+//
+// Every field is a COUNT that can be recounted in the files themselves, commits, branch points, exported
+// symbols. Deliberately no composite "maintainability grade": those aren't comparable across projects and can't
+// be checked, and a repo-health surface that launders counts into a letter is worse than none.
+// How many hotspot files and key modules a report carries when the caller names no limit. A leaderboard, not an
+// inventory: past a screenful the ranking stops being the point, and the reader should be reading the files.
+export const HEALTH_LIMIT = 20;
+export const WorkspaceHealthQuerySchema = z.object({
+    // "root" (the /work repo) or a nested repo's root-relative dir, the same {repo} ids the git routes take.
+    repo: z.string().min(1).describe("Which repository, using the same ids the git routes take."),
+    // Churn window (2d, 12h, 1w, 3m). Absent = all of history, which is what a hotspot ranking wants by default.
+    since: z
+        .string()
+        .max(16)
+        .optional()
+        .describe("How far back to count changes, written as a span such as 2d, 12h, 1w or 3m. Leave it out for all of history."),
+    limit: z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .describe("How many files and modules to rank. A leaderboard rather than an inventory: past a screenful the ranking stops being the point."),
+});
+// One file that is BOTH churning and tangled. `score` is the product the ranking sorts by, carried explicitly
+// so the panel plots the number it ranks by rather than recomputing it.
+export const WorkspaceHotspotSchema = z.object({
+    path: z.string(),
+    commits: z.number(),
+    adds: z.number(),
+    dels: z.number(),
+    complexity: z.number(),
+    score: z.number(),
+    // Epoch ms of the latest commit touching the file, within the window.
+    latestMs: z.number(),
+});
+export type WorkspaceHotspot = z.infer<typeof WorkspaceHotspotSchema>;
+// A file of the import graph's ranked skeleton, order IS the rank, so no rank number rides along.
+export const WorkspaceKeyModuleSchema = z.object({ path: z.string(), exports: z.number() });
+export type WorkspaceKeyModule = z.infer<typeof WorkspaceKeyModuleSchema>;
+export const WorkspaceHealthSchema = z.object({
+    repo: z.string().describe("Which repository this describes."),
+    totals: z
+        .object({
+            files: z.number().describe("Files counted."),
+            symbols: z.number().describe("Named things they export."),
+            complexity: z.number().describe("Branch points across all of them added up."),
+            hotspots: z.number().describe("How many files qualify as hotspots at all. The list below is capped; this is not."),
+        })
+        .describe(
+            "Counts anybody could recount in the files themselves. Deliberately no single maintainability grade: those cannot be checked and are not comparable between projects.",
+        ),
+    hotspots: z.array(WorkspaceHotspotSchema).describe("Files that change often and are complicated at the same time, worst first."),
+    modules: z.array(WorkspaceKeyModuleSchema).describe("The parts of the codebase the rest of it leans on most."),
+    // Same index-freshness signal the search route reports: a panel drawn off a half-built index says so.
+    freshness: WorkspaceSearchFreshnessSchema.describe("Whether the index these numbers were read from is up to date."),
+});
+export type WorkspaceHealth = z.infer<typeof WorkspaceHealthSchema>;

package/src/schemas/computers.ts

@@ -0,0 +1,287 @@
+// computers: what ONE of the user's own machines is running
+import { z } from "zod";
+import { HostFactsSchema } from "./hosts.js";
+/* The other end of desktop sync, stated as a fact instead of a claim.
+ *
+ * Everything here already existed, as the machine agent's printed status on a terminal nobody running the desktop app
+ * has open, and as `docker ps` rows only the desktop app could see. Three surfaces each held a third of it: the
+ * desktop app knew the containers and nothing about sync, the Desktop sync card knew an enrollment record and
+ * printed the status command for the rest, and the folder a machine syncs into was known to neither
+ * (SYNC_DIR is local agent state; the daemon is never told it). This is that one shape, so the same report can
+ * be produced by the agent, read by the daemon, and rendered by one component in both apps.
+ *
+ * The producer is `intentic-machine status --json` in every carrier (this report rides as its `sync` half), the desktop app spawns it, the mirror watcher
+ * posts it, a `host` capability runs it over run_command. One producer is what keeps the three from drifting,
+ * the same argument as the desktop app spawning connect.sh rather than reimplementing it.
+ *
+ * WHO FILLS WHAT is the disclosure rule, made structural. The agent reports only what it uniquely knows, its
+ * own pairings, folders, ports, watcher, and NEVER `sandboxes`: enumerating a machine's other containers to one
+ * of them is the leak this design exists to avoid, and a sync agent has no business doing it anyway. The docker
+ * half is supplied by whoever is READING (the desktop app from its own `docker ps`, the daemon from a
+ * `host`-capability one), which is also the only side that has a reason to be trusted with it.
+ *
+ * What remains is scoping: a report reaching a sandbox carries that sandbox's pairing, not its siblings', and a
+ * `mirror` enrollment, a collaborator's own laptop, drops `localDir` with it. So a member who mirrors one
+ * dev-server port does not hand the sandbox's owner a map of their machine. */
+
+// One sandbox container on the machine, the docker half, filled in by the reader, never by the sync agent.
+export const MachineSandboxSchema = z.object({
+    slug: z.string(),
+    container: z.string(),
+    // The display name, when the machine has one recorded. Docker knows only the container name.
+    name: z.string().optional(),
+    running: z.boolean(),
+    image: z.string(),
+    // Absent when the sandbox has no cloudflared sidecar AT ALL (reached over the user's own proxy), which is
+    // not the same fact as a sidecar that is down, and must not render as one.
+    tunnelRunning: z.boolean().optional(),
+});
+export type MachineSandbox = z.infer<typeof MachineSandboxSchema>;
+/* ONE OPERATION ON ONE SANDBOX ON ONE MACHINE, the Computers view's buttons, and the only thing that changes a
+ * machine's fleet from a browser.
+ *
+ * All nine ops travel one route because they are one decision to the person clicking, however differently they
+ * behave underneath: three are a docker call that returns in a second, four run the `ic` flow for minutes, one
+ * deletes, and one only reads. Splitting them by duration would put the same button on two doors and give the
+ * view two shapes to render. So every op answers as a STREAM of lines ending in a result, the fast ones simply
+ * have little to say, and `logs` is the case where the lines ARE the answer.
+ *
+ * `prepare` is the one that changes nothing on purpose: it downloads and builds the next update and stops
+ * there, leaving the container running the image it was already running. It is what turns `update` from a wait
+ * of minutes into a restart of seconds, and it is safe to offer at any moment for exactly that reason.
+ *
+ * `logs` is here rather than on a route of its own for the same reason the rest share it: it is a button in the
+ * same row as the others, on a container that may be too broken to answer any other way, and the stream shape
+ * already carries "many lines, then an outcome" exactly as a log tail wants to arrive.
+ *
+ * The machine enforces which of them it will do: `sandboxes` covers everything but removal, which takes its own
+ * switch, and a refusal comes back as the machine's own sentence naming the control to flip. */
+/* `runner-up` / `runner-remove` are the same door for a container that belongs to THIS SANDBOX rather than to
+ * a person: a runner (runners/, docs/remote-runners-plan.md at the workspace root). They ride here because to
+ * the machine they are the same act it already does, run and remove a sandbox container, and to the person
+ * clicking they are the same row of buttons. Both take the `sandboxes` switch and neither takes the removal
+ * one: a runner holds no workspace of its own, only a mirror of the parent's git, so removing it destroys
+ * nothing the parent does not still have. */
+export const MachineSandboxOpSchema = z.enum([
+    "start",
+    "stop",
+    "restart",
+    "prepare",
+    "update",
+    "rebuild",
+    "rollback",
+    "remove",
+    "logs",
+    "runner-up",
+    "runner-remove",
+]);
+export type MachineSandboxOp = z.infer<typeof MachineSandboxOpSchema>;
+export const MachineSandboxFlowSchema = z.object({
+    op: MachineSandboxOpSchema,
+    // Which sandbox, or, for the two runner ops, which RUNNER: the name it is known by at both ends, the
+    // parent's `/system/runners` list and the machine's `ic runner list`.
+    slug: z.string().min(1),
+    // The approved overlay's sha256, required by `rebuild` and meaningless to the rest. It is the trust anchor:
+    // only content that still hashes to what the owner reviewed is ever built.
+    hash: z.string().optional(),
+    /* `runner-up` only, and both are filled in by the DAEMON, never by the caller: where the runner dials
+     * (this sandbox's public URL) and the single-use pairing it redeems there. The browser asks for a runner
+     * on a machine; it never holds the credential that makes one, which is what keeps a pairing out of every
+     * surface between here and that machine. */
+    parentUrl: z.string().optional(),
+    pair: z.string().optional().meta({ secret: true }),
+    /* `runner-up` only, daemon-filled like the pair: the parent's SHAPE, riding to the machine so the runner
+     * starts as this sandbox's twin instead of a bare base image.
+     *
+     * `definition` is a settings-only sandbox.toml the container boots with as SANDBOX_DEFINITION_SEED (the
+     * fleet door in @intentic/sandbox-run); the daemon scopes it before sending, capabilities and secret
+     * names deliberately never ride to a runner. `overlay`/`overlayHash` are the parent's APPROVED composed
+     * overlay, byte-exact with its sha256: the parent's owner already approved those bytes, so `ic runner up`
+     * re-checks the hash and builds them at creation — approval by provenance, the same byte-exact check
+     * `ic sandbox rebuild` runs, where a definition handed to a STRANGER must park at an approval gate. */
+    definition: z.string().optional(),
+    overlay: z.string().optional(),
+    overlayHash: z.string().optional(),
+});
+export type MachineSandboxFlow = z.infer<typeof MachineSandboxFlowSchema>;
+// The same input plus which machine it is for, the browser's half, since the daemon reaches the machine by id.
+export const MachineSandboxFlowInputSchema = MachineSandboxFlowSchema.extend({ id: z.string().min(1) });
+export type MachineSandboxFlowInput = z.infer<typeof MachineSandboxFlowInputSchema>;
+/* What a running operation says, in the one line shape every streamed flow in this product already uses
+ * (IntenticLineSchema, which the browser's reader parses): `line` as the machine prints it, then exactly one
+ * terminal frame, `result` when it worked, `error` when it did not, carrying the machine's own words either
+ * way rather than a code this side invented. */
+export const MachineFlowLineSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("line"), text: z.string() }),
+    z.object({ kind: z.literal("result"), message: z.string() }),
+    z.object({ kind: z.literal("error"), message: z.string() }),
+]);
+export type MachineFlowLine = z.infer<typeof MachineFlowLineSchema>;
+// One paired sandbox as the local agent holds it. `localDir` is the answer to the question the Desktop sync card
+// has never been able to answer: which folder on that computer this sandbox's /work actually is.
+export const MachinePairingSchema = z.object({
+    sandboxId: z.string(),
+    mode: z.enum(["sync", "mirror"]),
+    // Set only for mode "sync", and only for the sandbox being reported to, see the redaction note above.
+    localDir: z.string().optional(),
+    // Mutagen's own word for what the session is doing ("watching", "scanning", "transitioning", "halted-…").
+    // Carried verbatim rather than mapped to a traffic light: the halted states name their own cause, and a UI
+    // that reduces them to "problem" sends the user back to the terminal this report exists to replace.
+    mutagenStatus: z.string().optional(),
+    // Conflicts Mutagen is holding rather than clobbering (the sync mode is two-way-SAFE). Nothing else in the
+    // product surfaces these, so a file edited on both ends stays stuck until someone runs the CLI.
+    conflicts: z.number().int().nonnegative().optional(),
+    paused: z.boolean().optional(),
+    /* The SECOND session's word, the one-way mirror carrying the sandbox's state dir down (sync's backupSpec).
+     * Reported separately rather than folded into the status above, because the two fail independently and mean
+     * different things: the first going quiet stops the owner's edits moving, the second going quiet stops their
+     * personas, skills, automations, drafts and transcripts from surviving the sandbox. A backup that is not
+     * running is only dangerous while nobody knows, so it gets its own word on the line. */
+    backupStatus: z.string().optional(),
+});
+export type MachinePairing = z.infer<typeof MachinePairingSchema>;
+/* One sandbox port and what became of it on this machine's localhost. The rows that did NOT make it are the
+ * reason this carries a state rather than being a list of live forwards: two sandboxes on one computer routinely
+ * serve the same dev-server port and only one can own localhost:6480, so the loser's port is simply missing from
+ * localhost with nothing anywhere saying why. Today that fact exists only as a line in mirror.log. */
+export const MachinePortStateSchema = z.enum([
+    // Forwarded: the sandbox's listener answers on this machine's localhost at the same number.
+    "mirrored",
+    // Another PAIRED SANDBOX got there first (first paired wins), `heldBy` names it, because "busy on this
+    // machine" sends people hunting for a process that does not exist.
+    "held-by-sandbox",
+    // Something else on this computer already binds the port, a local dev server, another tool. Not ours to
+    // name, and not ours to take.
+    "busy",
+]);
+export const MachinePortSchema = z.object({
+    port: z.number().int().min(1).max(65535),
+    host: z.enum(["127.0.0.1", "::1"]),
+    // The sandbox serving the port, whose /ports listed it, not whoever ended up holding the local bind.
+    sandboxId: z.string(),
+    state: MachinePortStateSchema,
+    // Set only for "held-by-sandbox": the sandbox id that owns the local bind instead.
+    heldBy: z.string().optional(),
+    // What is listening on the sandbox side ("node …/vite"), for a row the user has to recognise to act on.
+    command: z.string().optional(),
+});
+export type MachinePort = z.infer<typeof MachinePortSchema>;
+/* The resident watcher's liveness. This is the field that decides whether everything ELSE in the report is still
+ * true: a healthy session list under a dead watcher means new dev-server ports stop appearing on localhost and
+ * commits stop arriving in the local clones, while every other row keeps reading exactly as it did. */
+export const MachineWatcherSchema = z.object({
+    running: z.boolean(),
+    pid: z.number().int().optional(),
+    /* When the watcher last FINISHED a pass, the field that makes `running` mean something. The agent holds its
+     * SSH transport listeners on its own event loop, so a failure that escapes the loop leaves a process that is
+     * alive and a loop that is gone: pid present, unit "active", mirroring and the git bridge stopped. Absent
+     * means the agent has not reported one (too old to stamp, or its first pass has not landed), which is not
+     * the same as stalled, and readers must not treat it as either state. */
+    lastTickAt: z.number().optional(),
+});
+export type MachineWatcher = z.infer<typeof MachineWatcherSchema>;
+/* How long a watcher may go without finishing a pass before "running" stops being the honest word for it. Its
+ * loop polls every 5s and its slowest step is bounded by two 10s network timeouts per pairing, so a minute is
+ * several passes of slack, the same yardstick the Computers view already ages a whole report by.
+ *
+ * The rule lives HERE, next to the field, because the terminal and the browser both answer this question and a
+ * machine that is "running" in one and "stalled" in the other is worse than either answer alone. */
+export const WATCHER_STALL_AFTER_MS = 60_000;
+export const watcherStalled = (watcher: MachineWatcher, now: number): boolean =>
+    watcher.running && watcher.lastTickAt !== undefined && now - watcher.lastTickAt > WATCHER_STALL_AFTER_MS;
+export const MachineReportSchema = z.object({
+    /* The OS hostname, and the JOIN KEY. A machine can arrive here two ways at once, volunteered by its sync
+     * agent, and read through its `host` capability, and those two know it by different names (the enrolled
+     * key's comment vs. the capability id the user typed). The hostname is the one thing both can state about
+     * the same box, so it is what dedupes them into a single row. */
+    hostname: z.string(),
+    os: z.string(),
+    // Which of this machine's agents are installed, and at what version, a machine running an old build is
+    // visible rather than mysteriously lacking a field. Same argument as HostSummary.version. `host` is filled
+    // by the daemon at merge time (it already knows it from the socket), not by the sync agent, which would have
+    // to go reading another agent's config to guess at it.
+    agents: z.object({ sync: z.string().optional(), host: z.string().optional() }),
+    // Filled by the READER, never the agent (see above). Empty is the resting state: no Docker on the machine,
+    // or nothing has looked. Neither is an error, and neither means "no sandboxes exist".
+    sandboxes: z.array(MachineSandboxSchema),
+    pairings: z.array(MachinePairingSchema),
+    ports: z.array(MachinePortSchema),
+    watcher: MachineWatcherSchema,
+    // When the machine took this reading. NOT when the daemon received it. A report is a snapshot from a box
+    // that may since have gone to sleep, and the UI ages it against this rather than presenting it as now.
+    capturedAt: z.number(),
+});
+export type MachineReport = z.infer<typeof MachineReportSchema>;
+// Why a computer that is plainly THERE has no report to show. Each is a different errand for the reader, which is
+// the whole reason they are not collapsed into one "unavailable".
+export const ComputerGapSchema = z.enum([
+    // A host capability that is enrolled but has no socket right now. Laptops sleep; this is not a fault.
+    "offline",
+    // Connected, but "Run commands" is switched off on its capability card, so the daemon may not ask it
+    // anything. The one gap the user can close in a single click, and the UI says which switch.
+    "scope-off",
+    // Reachable, asked, but has no `intentic-machine` on it, so nothing knows about folders or mirrored ports there.
+    "no-agent",
+    // A sync-enrolled machine that has not posted a report yet: either it just enrolled, or its agent predates
+    // machine reports. Distinct from "no-agent" because the agent IS there and the folders ARE syncing.
+    "unreported",
+]);
+export type ComputerGap = z.infer<typeof ComputerGapSchema>;
+/* ONE COMPUTER, however the sandbox happens to be able to see it, and it may be both ways at once.
+ *
+ * A machine reaches a sandbox through two independent doors: a desktop-sync enrollment (which volunteers its own
+ * report) and a `host` capability (which the daemon can ask). They know the same box by different names, the
+ * enrolled ssh key's comment vs. the capability id the user typed, so the two are reconciled on the `hostname`
+ * their reports agree on, and left as separate rows when there is nothing to reconcile them by. Guessing that two
+ * differently-named machines are the same one would merge two people's laptops on a shared sandbox. */
+export const ComputerSchema = z.object({
+    // Stable row key: the reported hostname when either door produced one, else the name that door knows it by.
+    key: z.string(),
+    // What to call it on screen, the user's own name for the machine wherever one exists.
+    label: z.string(),
+    // Whether a desktop-sync enrollment exists for this machine (it syncs files and/or mirrors ports).
+    syncEnrolled: z.boolean(),
+    // The host capability's id, when this machine is also a connected computer. Absent otherwise.
+    hostId: z.string().optional(),
+    // Host-capability liveness. Absent when there is no host capability, which is NOT the same as offline.
+    online: z.boolean().optional(),
+    /* WHAT THE COMPUTER IS, as distinct from how it is reachable, the half a row used to leave out entirely,
+     * so a Windows laptop and a Linux desktop were two identical lines of text with different names on them.
+     *
+     * It is carried BESIDE the report rather than inside it because the rows that need it most are the ones with
+     * no report: a connected computer with no sync agent, or one that is asleep, still knows its own OS. Nothing
+     * here depends on an agent being installed, and the daemon has held all of it since the machine connected.
+     *
+     * `platform` is the slug this side classifies the machine by, the host capability's own card ("windows",
+     * "linux"), or the platform token a sync report carries, normalised to the same words. `facts` is the
+     * machine's connect-time description of ITSELF, which is what says which Windows and which shell. */
+    platform: z.string().optional(),
+    facts: HostFactsSchema.optional(),
+    // The host agent's version and when the machine last held a socket, how a connected computer AGES. An old
+    // agent explains a row that lacks something newer machines have, and "last seen" is the one honest thing an
+    // offline row can still say about itself.
+    hostAgent: z.string().optional(),
+    lastSeen: z.number().optional(),
+    report: MachineReportSchema.optional(),
+    gap: ComputerGapSchema.optional(),
+});
+export type Computer = z.infer<typeof ComputerSchema>;
+export const ComputersListSchema = z.object({ computers: z.array(ComputerSchema) });
+// GET /system/sync, the enrollment state the Desktop sync card is built on, plus what each enrolled machine has
+// said about itself. `machines` is optional because a daemon predating machine reports omits it, and an SPA is
+// routinely newer than the daemon it is pointed at during a rolling update.
+export const SyncStatusSchema = z.object({
+    enrolled: z.boolean(),
+    /* Whether this sandbox can do desktop sync at all. It used to be the SSH hostname the laptop would dial, and
+     * its absence meant "this sandbox's reachability can't carry SSH", true of every sandbox on the platform's
+     * own fabric, which is what made sync fail on the default path. The transport rides the daemon's own HTTPS
+     * surface now, so a sandbox that can answer this read can also sync. Kept as a field rather than assumed,
+     * because the card branches on it and a daemon too old to say is one that should not be offered sync. */
+    available: z.boolean().optional(),
+    // The single machine holding file sync, and when its heartbeat last landed.
+    syncingFrom: z.string().optional(),
+    syncSeenAt: z.number().optional(),
+    mirroredBy: z.array(z.string()).optional(),
+    machines: z.array(MachineReportSchema).optional(),
+});
+export type SyncStatus = z.infer<typeof SyncStatusSchema>;