@intentic/sandbox-contract 1.240.0 → 1.243.0

package/src/schemas/computers.ts

@@ -133,7 +133,19 @@ export type MachineFlowLine = z.infer<typeof MachineFlowLineSchema>;
  *
  * The machine still enforces its own switches. "Run commands" being off comes back as its own refusal, in its
  * own words, naming the control to flip — exactly as it does for the sandbox ops. */
-export const MachineCommandSchema = z.enum(["mirror-off", "mirror-on"]);
+/* THE SET, and why the file-sync half of it is here beside the mirroring half.
+ *
+ * Both are the same gesture to the person clicking: something this computer is doing for this sandbox, turned
+ * off or on from the row that describes it. They were split for a while by nothing but which one had been built
+ * — mirroring had a button and pausing a file sync had a paragraph telling you to go and find a terminal — and
+ * that is exactly the gap this door exists to close.
+ *
+ * `sync-unpair` is the one that DESTROYS something, and it is deliberately the machine's `sync uninstall
+ * --sandbox`, not this side's idea of unpairing: the agent terminates both Mutagen sessions, drops the local
+ * pairing and self-revokes its enrollment on the way out, so the machine cleans up after itself rather than
+ * leaving a sandbox to guess what it managed to do. Revoking from the SANDBOX side (an unreachable machine, a
+ * laptop that is never coming back) is a different act and a different route, see the enrollment revoke. */
+export const MachineCommandSchema = z.enum(["mirror-off", "mirror-on", "sync-pause", "sync-resume", "sync-unpair"]);
 export type MachineCommand = z.infer<typeof MachineCommandSchema>;
 /* Which paired sandbox the command acts on: the machine's own id for it, as it appears in that machine's report,
  * so nothing here has to re-derive the sanitizing the agent applied. Absent means every sandbox that machine
@@ -195,7 +207,7 @@ export const MachinePairingSchema = z.object({
     /* 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
+     * personas, skills, automations, approvals 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(),
 });
@@ -232,6 +244,12 @@ export type MachinePort = z.infer<typeof MachinePortSchema>;
 export const MachineWatcherSchema = z.object({
     running: z.boolean(),
     pid: z.number().int().optional(),
+    /* WHICH BUILD IS ACTUALLY SERVING, stamped into the pidfile by the loop that claimed it, which is the only
+     * place the fact exists: replacing the binary does not touch the running process, so a machine can hold a
+     * current agent and go on serving a months-old one indefinitely. `agents.sync` is the file, this is the
+     * process, and the two differing is a restart somebody is owed (see watcherBuildSkew). Absent when no loop
+     * is running, and when the one running predates the stamp. */
+    build: z.string().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
@@ -256,10 +274,18 @@ export const MachineReportSchema = z.object({
      * 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.
+    /* Which agents this machine has, and at what version, so one on an old build is visible rather than
+     * mysteriously lacking a field. Same argument as HostSummary.version.
+     *
+     * `sync` is the agent INSTALLED here — the file on disk — and `watcher.build` beside it is the loop running
+     * from that file. It used to be neither: whichever process happened to build the report stamped its own
+     * version here, so the same machine answered its running build to a sandbox its loop posted to and its
+     * installed build to one that ran `status --json` over a host capability. One field, two meanings, and the
+     * gap between them — a machine updated but never restarted — invisible in both.
+     *
+     * `host` is what the live socket announced (so: what is running), filled by the daemon at merge time from
+     * the hello frame it already holds, never 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".
@@ -272,6 +298,27 @@ export const MachineReportSchema = z.object({
     capturedAt: z.number(),
 });
 export type MachineReport = z.infer<typeof MachineReportSchema>;
+
+/* THE AGENT THIS MACHINE INSTALLED AND THE ONE IT IS RUNNING, when they are not the same build — the whole of
+ * "you updated the agent and nothing changed", as a value.
+ *
+ * It is one comparison, and it lives HERE for the same reason watcherStalled does: the terminal (`intentic-machine
+ * status`) and the browser (the Computers row) both answer this question, and a machine that is behind in one and
+ * fine in the other is worse than either answer alone. The remedy is the same in both: restart the loop.
+ *
+ * Silent whenever either half is unknown, which covers a loop that is stopped (nothing is serving, and the row
+ * already says so in louder words), an agent too old to stamp its build, and a machine with no installed agent to
+ * compare against — none of which is a skew, and each of which would otherwise nag about a difference nobody can
+ * act on. */
+export const watcherBuildSkew = (report: MachineReport): { readonly running: string; readonly installed: string } | undefined => {
+    const running = report.watcher.build;
+    const installed = report.agents.sync;
+    if (!report.watcher.running || running === undefined || installed === undefined || running === installed) {
+        return undefined;
+    }
+    return { running, installed };
+};
+
 // 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([
@@ -294,13 +341,39 @@ export type ComputerGap = z.infer<typeof ComputerGapSchema>;
  * 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. */
+/* THE DESKTOP-SYNC ENROLLMENT BEHIND A ROW, which used to be a boolean and could not be.
+ *
+ * `syncEnrolled: true` answered "is this machine paired" and nothing a reader standing in front of the row
+ * actually asks next: WHICH half of desktop sync it holds (files and ports, or ports alone), whether it has
+ * ever used the enrollment, and how to name it when they want it gone. Those three lived on /system/sync
+ * instead, as one machine's worth of `syncingFrom` plus a list of `mirroredBy` names, which is the sandbox-level
+ * shape this view exists to stop being: one card claiming a sandbox has A desktop sync, over a list of the
+ * several computers that actually do.
+ *
+ * `machine` is the enrollment's own name for the box (the ssh key's comment). It is what the reports are filed
+ * under, and it is the id the revoke route takes — the same string, so a row can revoke exactly the enrollment
+ * it is drawn from. Two machines that present the same comment share one enrollment identity throughout the
+ * daemon (reports included); that is a pre-existing property of naming machines by their key comment, and this
+ * field inherits it rather than inventing a second identity that would disagree with the first. */
+export const ComputerSyncSchema = z.object({
+    machine: z.string(),
+    /* Which half. "sync" is files AND ports and is SINGLE-HOLDER for the sandbox; "mirror" is ports only and any
+     * number of machines may hold one. The row says which, because "your laptop is paired" is read as the first
+     * by somebody who has the second, and then their files are not where they expect them. */
+    mode: z.enum(["sync", "mirror"]),
+    // When this machine last USED its enrollment (its watcher's own polls stamp it). Absent on one that never
+    // has, which is exactly what a setup that did not finish leaves behind, and must not read as healthy.
+    seenAt: z.number().optional(),
+});
+export type ComputerSync = z.infer<typeof ComputerSyncSchema>;
 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 desktop-sync enrollment this machine holds with this sandbox, absent when it has none (a computer
+    // reached only through its `host` capability).
+    sync: ComputerSyncSchema.optional(),
     // 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.
@@ -327,9 +400,16 @@ export const ComputerSchema = z.object({
 });
 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.
+/* GET /system/sync: what desktop sync is doing for this sandbox, WITHOUT naming any one machine as the answer.
+ *
+ * It used to carry `syncingFrom` + `syncSeenAt` + `mirroredBy`, which is the enrollment list flattened into one
+ * holder and a list of everybody else — the shape a card that believed a sandbox has A desktop sync needed, and
+ * the reason that card kept restating facts the Computers list beside it already had per machine. Every one of
+ * those now rides on the machine's own row (ComputerSync), where a reader can act on it.
+ *
+ * What is left is what is genuinely about the SANDBOX rather than about any computer: whether sync is possible
+ * here at all, whether anything at all is enrolled, and the raw reports, which is the cheap ambient read the
+ * rail's badge lives on (it must never fan out to somebody's laptop just to decide whether to draw a chip). */
 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
@@ -338,10 +418,6 @@ export const SyncStatusSchema = z.object({
      * 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>;

package/src/schemas/environment.ts

@@ -70,8 +70,22 @@ export const EnvironmentRecurringSchema = z.object({
     live: z.boolean(),
     drafted: z.boolean().optional(),
     declined: z.boolean().optional(),
+    /* The Dockerfile step that would bake this tool, when its ecosystem has one that follows from the name
+     * alone (auto-drafts.ts `stepFor`). Sent rather than re-derived in the browser because it is the SAME string
+     * the owner would approve, and because its presence is the honest answer to "can this be fixed by pressing a
+     * button?": absent means the fix is a judgement call (which pip package, replaying which installer) and the
+     * card offers an agent instead. */
+    step: z.string().optional(),
 });
 export type EnvironmentRecurring = z.infer<typeof EnvironmentRecurringSchema>;
+/* The owner's answer to ONE line of that list. `adopt` writes the tool's overlay draft now, without waiting for
+ * the sweep to re-earn it; `dismiss` tombstones it so nothing proposes it again; `restore` undoes a dismissal.
+ * One route rather than three because it is one decision surface about one ledger entry. */
+export const EnvironmentRuntimeDecisionSchema = z.object({
+    tool: z.string().min(1),
+    decision: z.enum(["adopt", "dismiss", "restore"]),
+});
+export type EnvironmentRuntimeDecision = z.infer<typeof EnvironmentRuntimeDecisionSchema>;
 export const EnvironmentSchema = z.object({
     proposal: environmentFileSchema.optional(),
     // The owner-approved agent-written custom section (.intentic/config/environment.custom.Dockerfile).
@@ -142,116 +156,23 @@ export const EnvironmentItemSchema = z.object({
 export type EnvironmentItem = z.infer<typeof EnvironmentItemSchema>;
 export const EnvironmentContentsSchema = z.object({ items: z.array(EnvironmentItemSchema) });
 export type EnvironmentContents = z.infer<typeof EnvironmentContentsSchema>;
-/* ---- portability: exporting a sandbox's environment and restoring it into a fresh one ----
+/* ---- portability: exporting a sandbox's environment ----
  *
  * A sandbox is four stores, not one: `/work` (the workspace and the daemon's manifests), `/history` (every
  * repo's real git dir, the fleet registry, the ledgers), the CONTAINER (the built overlay image plus the env
  * the run contract replays) and the AI-provider credential root. A bundle carries the first two, declared entry
  * by entry in WORKSPACE_STATE_FILES / HISTORY_STATE_FILES. It cannot carry the other two, and the honest
- * consequence is that an import ends in a REPORT rather than a claim of equivalence, the container has no
+ * consequence is that taking one in ends in a REPORT rather than a claim of equivalence, the container has no
  * docker socket, so only the host can rebuild the image the overlay describes.
  *
  * The bundle's manifest (BundleManifestSchema) lives in definition.ts beside the sandbox DEFINITION it embeds:
  * a bundle is definition + state, and keeping the two schemas together is what keeps the two export doors from
- * drifting into different answers about what an environment is. */
-
-// What a restore actually did. `needsAction` is the part that matters: the environment rebuild command, the
-// credentials to re-enter, the logins to redo, each one a thing the target cannot do for itself.
-export const ImportReportSchema = z.object({
-    restored: z.object({ workspaceFiles: z.number(), historyFiles: z.number(), repos: z.array(z.string()), bytes: z.number() }),
-    // Entries the bundle carried that this daemon refused to write (an identity file, an escaping path), empty
-    // for any bundle a matching exporter produced, and a tamper signal when it is not.
-    refused: z.array(z.string()),
-    needsAction: z.array(z.object({ subject: z.string(), detail: z.string() })),
-});
-export type ImportReport = z.infer<typeof ImportReportSchema>;
-/* ---- migrations: importing a FOREIGN assistant's setup (Hermes, OpenClaw) ----
- *
- * A different crossing than a bundle restore, and deliberately a different surface: a bundle is our own format,
- * re-derived entry by entry against the state manifests, while a migration reads a directory some OTHER
- * program laid out (`~/.hermes`) and TRANSLATES it into native things, skills, automations, capabilities,
- * merged memory. Nothing foreign is executed or copied verbatim into daemon state; every item lands through the
- * same write paths the settings/skills/automations/capabilities surfaces use, which is what keeps an imported
- * setup editable and deletable in the ordinary UI the day after (docs/assistant-import-design.md).
+ * drifting into different answers about what an environment is.
  *
- * The flow is PREVIEW-FIRST, mirroring what these tools' own `migrate` commands taught their users to expect:
- * `plan` parses the uploaded archive into an itemized checklist and holds the upload in memory under a token;
- * `apply` names the ticked item ids and the token. The plan is RE-DERIVED from the held archive at apply, the
- * wire plan is a rendering for the owner, never the input the write trusts (restore.ts's rule, kept). */
-export const MigrationSourceSchema = z.enum(["hermes", "openclaw"]);
-export type MigrationSource = z.infer<typeof MigrationSourceSchema>;
-// What an item becomes here, not what it was there, the apply loop dispatches on this, and the checklist
-// groups by it so the owner reads "3 skills, 2 automations" rather than a foreign directory listing.
-export const MigrationTargetSchema = z.enum(["memory", "skill", "automation", "capability", "secret", "file"]);
-export type MigrationTarget = z.infer<typeof MigrationTargetSchema>;
-export const MigrationItemSchema = z.object({
-    // Deterministic (derived from the source artifact, e.g. `skill:weather`), so the ids the owner ticked name
-    // the same items when the plan is re-derived at apply.
-    id: z.string(),
-    target: MigrationTargetSchema,
-    // The checklist line, plain words: "Skill, weather", "Nightly digest (9:00 every day)".
-    label: z.string(),
-    detail: z.string().optional(),
-    /* The default tick. False marks the items the owner should read before taking, a server URL that points at
-     * localhost on the OLD machine, an .env key that looks like tuning rather than a credential. They still
-     * import fine when ticked; the flag is the adapter's judgment, not a gate. */
-    recommended: z.boolean(),
-    // Names of the secrets this item would store (never values, values stay in the held archive until apply,
-    // and only move when the apply says includeSecrets). Empty for items that carry none.
-    secrets: z.array(z.string()),
-});
-export type MigrationItem = z.infer<typeof MigrationItemSchema>;
-export const MigrationNeedsActionSchema = z.object({ subject: z.string(), detail: z.string() });
-export const MigrationPlanSchema = z.object({
-    source: MigrationSourceSchema,
-    // Names the held upload for the apply call. Minted per plan; a new upload replaces the held one.
-    token: z.string(),
-    items: z.array(MigrationItemSchema),
-    // What the adapter saw and will not move, sessions, logs, pairing state, listed rather than silent.
-    refused: z.array(z.string()),
-    // What is already known not to move mechanically (channels to reconnect, a model to pick), the same
-    // honesty ImportReportSchema carries, surfaced at PREVIEW time so the owner ticks with open eyes.
-    needsAction: z.array(MigrationNeedsActionSchema),
-});
-export type MigrationPlan = z.infer<typeof MigrationPlanSchema>;
-/* One of the owner's own computers, as an import SOURCE, the answer to "where is my setup" that needs no
- * packing at all. Read on the card's first render for every enrolled machine, so the offer appears before the
- * owner has read a single instruction.
- *
- * `found` absent means "connected, and nothing to import here", which is a real answer worth rendering
- * quietly, not an error: the machine may simply be a different one from the machine the assistant runs on. */
-export const MigrationHostSchema = z.object({
-    id: z.string(),
-    online: z.boolean(),
-    found: MigrationSourceSchema.optional(),
-    // Why this machine cannot be read right now, when it cannot, offline, or its own refusal, in its words.
-    detail: z.string().optional(),
-});
-export const MigrationHostsSchema = z.object({ hosts: z.array(MigrationHostSchema) });
-export type MigrationHost = z.infer<typeof MigrationHostSchema>;
-// Read the setup off a connected computer instead of an upload. Answers with a plan, exactly as the upload
-// route does, everything after this point is identical whichever door the setup came through.
-export const MigrationScanSchema = z.object({ host: z.string().min(1) });
-export const MigrationApplySchema = z.object({
-    token: z.string(),
-    // The ticked item ids. Ids the re-derived plan does not contain are ignored rather than erroring, the
-    // archive is the truth, and a stale checklist must not block the items that still exist.
-    items: z.array(z.string()),
-    // The owner's explicit consent to move credential VALUES (mirrors the bundle export's `?secrets=`, and the
-    // `--include-secrets` these tools' own migrate commands require). Off: secret items are skipped and
-    // capability configs land without their keys.
-    includeSecrets: z.boolean(),
-});
-export type MigrationApply = z.infer<typeof MigrationApplySchema>;
-export const MigrationReportSchema = z.object({
-    applied: z.array(z.object({ id: z.string(), target: MigrationTargetSchema, label: z.string() })),
-    // Items that were ticked and did not land, each with the reason, a full disk, an env store that needs
-    // DevOps active. Distinct from `refused`, which is the class of things never attempted.
-    failed: z.array(z.object({ id: z.string(), label: z.string(), error: z.string() })),
-    refused: z.array(z.string()),
-    needsAction: z.array(MigrationNeedsActionSchema),
-});
-export type MigrationReport = z.infer<typeof MigrationReportSchema>;
+ * ONLY THE OUTBOUND HALF IS HERE. Taking a bundle IN is not a surface of its own any more: it is one of the
+ * four sources the arrival pipeline reads (arrival.ts), beside a definition and the two foreign assistants,
+ * because all four answer the same question and used to answer it three different ways. */
+
 /* One export sitting in the daemon's export directory, the ARTIFACT a bundle is, rather than the request that
  * produced it. Packing takes minutes over a real workspace, so tying it to a response made it a property of one
  * browser tab: a refresh abandoned the work and left nothing to come back to. It is a file now, and every field

package/src/schemas/git.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { AgentProviderSchema } from "./agent.js";
 import { LandConflictSchema, LandedMessageSchema } from "./agents.js";
+import { CommandRunSchema } from "./ci.js";
 import { RefNameSchema } from "./internal.js";
 import { RepoParamSchema } from "./shared.js";
 // What a commit records, three shapes, each a real git spelling. The last two are for the case where nothing
@@ -48,6 +49,34 @@ export const PushSchema = RepoParamSchema.extend({
         .optional()
         .describe("Which branch to push. Leave it out for the checked-out one. A branch with no upstream yet gets one set on this push."),
 });
+/* WHO SAID NO to a push, read off git's final words (git/git.ts pushRefusal), because the three answers ask
+ * three different things of the owner and only one of them is an agent's to fix:
+ *   hook      , this repository's own pre-push hook refused it: the code is known to be wrong, the hook's
+ *               output says how, and a fix is worth proposing.
+ *   remote    , the server rejected the refs: a non-fast-forward, a protected branch. Pull first, or push
+ *               somewhere else; nothing about the code has been judged.
+ *   transport , it never got there: credentials, a host that does not answer, a remote that is not a
+ *               repository. The same again, and a retry is the only sensible button. */
+export const PushRefusalSchema = z.enum(["hook", "remote", "transport"]);
+export type PushRefusal = z.infer<typeof PushRefusalSchema>;
+/* THE PUSH AS A RUN: the pre-push check's shape (CommandRunSchema) with the three things a push adds. A push is
+ * a command that runs this repository's pre-push hook, which for a workspace with a real gate is the whole
+ * suite, minutes of output; it is a terminal to watch and a verdict to poll for exactly as the check is, and
+ * NOT a request held open for its duration (the browser's header deadline is seconds, and a push that ran a
+ * suite inside its own request reported "failed" over a push that had gone). One shape for both halves of
+ * the push flow is what lets the browser render a refused push with the card, the terminal link and the
+ * proposed fix it already has for a red check. */
+export const PushRunSchema = CommandRunSchema.extend({
+    repo: z.string().describe("The repository this run is about, the same id the routes take."),
+    reason: z
+        .string()
+        .optional()
+        .describe("Why not, in git's own words: the last verdict line, for a row that has room for one line. The whole tail is `output`."),
+    refusedBy: PushRefusalSchema.optional().describe(
+        "Who refused a failed push: this repository's pre-push hook (the code is wrong, a fix is worth proposing), the remote (pull first), or the transport (credentials, network: retry). Absent while it runs and for a push that went.",
+    ),
+});
+export type PushRun = z.infer<typeof PushRunSchema>;
 export const GitFileQuerySchema = RepoParamSchema.extend({ path: z.string().min(1).describe("The file to read, relative to the repository root.") });
 export const GitFileWriteSchema = RepoParamSchema.extend({
     path: z.string().min(1).describe("Where to write, relative to the repository root. Missing folders are created."),
@@ -107,6 +136,22 @@ export const GitChangeSchema = z.object({
         .optional()
         .describe("Lines added. Absent for a binary file, and for an untracked one, which has nothing to compare against."),
     deletions: z.number().optional().describe("Lines removed. Absent for the same reasons additions is."),
+    /* THE SAME CHANGE WITH THE COMMENTS TAKEN OUT, computed here rather than by whoever renders the row, and
+     * that is the whole point of it being on the wire. A review's diffs open on code alone, so the numbers beside
+     * them are the code's; working those out needs both whole sides of the file and a TextMate walk over each,
+     * which the app used to do per file, as the files were read — so a row arrived showing git's count and
+     * changed to this one the moment anything read it, which moved the row under the reader when the list was
+     * sorted by size. Shipped with the list, the number a reader sees first is the number it stays.
+     *
+     * Absent, not zero, when there is nothing to say: a binary file, one side too large to read, a path whose
+     * grammar this build does not ship, or a list too long to count whole (see git/code-counts.ts). The caller
+     * then shows git's own counts, which for such a file are the only honest reading anyway. */
+    code: z
+        .object({ additions: z.number(), deletions: z.number() })
+        .optional()
+        .describe(
+            "The same +/− with every comment stripped from both sides, which is what a review shows beside a diff that opens on code alone. Absent when the file cannot be read that way (binary, too large, or a language this build ships no grammar for): git's own counts above are then the reading.",
+        ),
 });
 export type GitChange = z.infer<typeof GitChangeSchema>;
 // Where a repo's checked-out branch stands against its remote. Every field is optional-or-zero because every
@@ -375,16 +420,25 @@ export const RepoModulesSchema = z.object({
 export type RepoModules = z.infer<typeof RepoModulesSchema>;
 export const WorkspaceModulesSchema = z.object({ repos: z.array(RepoModulesSchema).describe("Every repository with the packages inside it.") });
 export type WorkspaceModules = z.infer<typeof WorkspaceModulesSchema>;
-// One file an agent touched, plus whether that change is ALREADY in the main tree. The review lists the
-// agent's CUMULATIVE output (base → worktree), not just the not-yet-landed remainder, because landing is not
-// the end of the review: a clean turn auto-lands within milliseconds, and a list scoped to the remainder shows
-// the user an empty panel for work they never got to look at. `landed` is what still separates the two, the
-// remainder is what "Land now" would apply, and the panel filters on exactly this flag.
+/* One file an agent touched AND STILL DIFFERS FROM MAIN ON, plus whether the main working tree is already
+ * holding it. The list is what the conversation wrote measured against the main line as it stands right now,
+ * which takes three states to say and each one decides a different next move for the reader:
+ *
+ *   · main's history has this content: the user accepted it, it is their commit, and it is no longer a
+ *     difference against main. There is no row (see `absorbed` on the response).
+ *   · the main working tree has it, uncommitted: the steady state seconds after a land, waiting in the Changes
+ *     panel. A row, `landed: true`.
+ *   · neither: never landed, or landed and then discarded. A row, `landed: false`, and this is exactly what
+ *     "Land now" would apply.
+ *
+ * Landed work keeps its row on purpose: a clean turn auto-lands within milliseconds, so a list scoped to the
+ * outstanding remainder would show an empty panel for work nobody had looked at yet. What retires a row is the
+ * user committing it, which is the one act that says they are done reviewing it. */
 export const AgentChangeSchema = GitChangeSchema.extend({
     landed: z
         .boolean()
         .describe(
-            "Whether this change is already in the shared tree. The list is everything the conversation wrote, not just what is left over, because a clean turn merges in milliseconds and a list of leftovers would show an empty panel for work nobody had looked at yet.",
+            "Whether your workspace already holds this content. Read from the tree at request time, not from what a land recorded: discard a landed file in the Changes panel and this goes back to false, which is what puts it back under Land now.",
         ),
 });
 export type AgentChange = z.infer<typeof AgentChangeSchema>;
@@ -420,6 +474,16 @@ export type AgentRepoChanges = z.infer<typeof AgentRepoChangesSchema>;
  * than the last attempt. */
 export const AgentChangesSchema = z.object({
     repos: z.array(AgentRepoChangesSchema).describe("One entry per repository the conversation touched."),
+    /* HOW MUCH OF THE WORK IS NO LONGER A DIFFERENCE, so an empty list can say WHICH kind of empty it is. An
+     * agent that has written nothing and an agent whose every file the user committed both answer with no rows,
+     * and they are opposite facts: one is "ask it for something", the other is "it is all in your history". A
+     * count rather than the rows themselves, because that is the whole of what the surface needs to pick a
+     * sentence, and carrying the rows would put the list back where it started. */
+    absorbed: z
+        .number()
+        .describe(
+            "How many of this conversation's files your own history already carries, and which are therefore not listed as differences any more.",
+        ),
     conflicts: z
         .array(LandConflictSchema)
         .optional()
@@ -428,3 +492,54 @@ export const AgentChangesSchema = z.object({
         ),
 });
 export type AgentChanges = z.infer<typeof AgentChangesSchema>;
+
+/* WHERE THE WORK WENT once it stopped being a difference, the other half of the sentence `absorbed` above can
+ * only start. The review is what still differs from main, so a reader who committed an agent's every file
+ * arrives at an empty panel; the count lets it say WHICH kind of empty, and this says where to go and shows
+ * the work, which is what the reader actually came for.
+ *
+ * Deliberately its OWN read rather than more fields on the review. The review is on the panel's hot path and
+ * this is a `git log` per repo that only matters once history has taken something, so it is asked for exactly
+ * when there is an answer to have. That also keeps the review's shape honest: its rows are differences against
+ * main, and these are not.
+ *
+ * A COMMIT CARRIES the work, it did not necessarily author it: a path is attributed to the newest commit that
+ * left the agent's content there, which is where a reader should be sent to read it now. See the daemon's
+ * agents/landed-history.ts for the span this is measured over and for why an unattributable path is counted
+ * rather than assigned to a plausible commit. */
+export const AgentHistoryCommitSchema = z.object({
+    sha: z.string().describe("The commit."),
+    short: z.string().describe("Its abbreviated hash, which is what a reader recognises it by."),
+    subject: z.string().describe("Its first line."),
+    author: z.string().describe("Who committed it."),
+    at: z.number().describe("When it was authored, in milliseconds."),
+    changes: z
+        .array(GitChangeSchema)
+        .describe(
+            "The conversation's files that this commit is the newest carrier of, as the conversation changed them. Every file appears under exactly one commit, so these counts add up to the work rather than over-counting a file that history touched twice.",
+        ),
+});
+export type AgentHistoryCommit = z.infer<typeof AgentHistoryCommitSchema>;
+export const AgentRepoHistorySchema = z.object({
+    repo: z.string().describe("Which repository."),
+    commits: z.array(AgentHistoryCommitSchema).describe("The commits carrying this conversation's work there, newest first."),
+    /* Carried for the same reason the review's rows carry it, and read from the same tree at the same instant:
+     * a package the conversation created lives only in its own copy, so the shared tree cannot name it, and
+     * without this every file of a brand-new package groups under no package at all. */
+    modules: z.array(WorkspaceModuleSchema).describe("The packages of the tree these files came from, so a review can group them by package."),
+});
+export type AgentRepoHistory = z.infer<typeof AgentRepoHistorySchema>;
+export const AgentHistorySchema = z.object({
+    repos: z.array(AgentRepoHistorySchema).describe("One entry per repository holding committed work of this conversation."),
+    /* FILES HISTORY HOLDS THAT NO COMMIT HERE ACCOUNTS FOR, reported rather than hidden. Content reaches the
+     * main line by roads that do not pass through a commit since the land: a cherry-pick from elsewhere,
+     * another conversation landing the same lines, the user typing them by hand before this one landed. Those
+     * files are absorbed and unattributable at once, and a surface that quietly dropped them would be claiming
+     * the commits it names are the whole story. */
+    unaccounted: z
+        .number()
+        .describe(
+            "How many of the conversation's absorbed files none of these commits carries. Above zero means its content reached your main line by some other road, so the commits listed are not the whole story.",
+        ),
+});
+export type AgentHistory = z.infer<typeof AgentHistorySchema>;

package/src/schemas/issues.ts

@@ -150,7 +150,7 @@ export type Issue = z.infer<typeof IssueSchema>;
 export const IssueSummarySchema = IssueSchema.extend({ id: entryId.describe("The issue's id, which is its fingerprint.") });
 export type IssueSummary = z.infer<typeof IssueSummarySchema>;
 
-// `invalid` is the same trust-boundary confession the drafts list makes, for the opposite reason: nothing but
+// `invalid` is the same trust-boundary confession the approvals list makes, for the opposite reason: nothing but
 // the daemon writes these, so a file in here that will not parse is a BUG in this daemon or a half-written
 // volume, and either is worth seeing rather than silently skipping.
 export const IssuesListSchema = z.object({

package/src/schemas/panels.ts

@@ -5,12 +5,32 @@ import { z } from "zod";
 // preview-<panelKey>-<sandboxId>.<zone> to it) PLUS content facts, evidence the web app's extensions run their
 // detect() over, computed daemon-side in one pass so the browser never scans /work file-by-file.
 
+/* WHERE A START THE SANDBOX IS RUNNING HAS GOT TO, between the click and the first byte served. The process
+ * manager watches the pane's foreground command every couple of seconds (processes/managed-processes.ts), and
+ * these four words are what that sampling can honestly say: the shell is still coming up; the install that
+ * runs first when node_modules is missing is still going; the dev command is running but nothing listens yet;
+ * or the command has already exited back to a prompt, which is the one a person needs told at once, because
+ * the "Preparing the preview…" it would otherwise sit behind never ends. Absent once the preview proxy has
+ * something to serve, and absent for anything the sandbox is not starting. */
+export const PanelLaunchSchema = z.enum(["launching", "installing", "starting", "exited"]);
+export type PanelLaunch = z.infer<typeof PanelLaunchSchema>;
+
 export const PanelSummarySchema = z.object({
     // The repo id: its root-relative dir under /work (slashes become `--` in the preview subdomain label).
     repo: z.string().describe("Which repository."),
     // Whether the repo ships a runnable dev server (a package.json `dev` script at operator/ or the root).
     hasPanel: z.boolean().describe("Whether it has anything runnable at all."),
     running: z.boolean().describe("Whether the sandbox has it running."),
+    /* Whether its dependencies are on disk, a node_modules at the directory Start runs in. What decides what a
+     * Start COSTS: seconds when true, an install first when false, and the Start screen's copy says which
+     * instead of promising "a few minutes" over a tree that is already installed (the starter site's is: the
+     * image bakes it). True for a repo with nothing runnable, which has nothing to install for. */
+    installed: z
+        .boolean()
+        .describe("Whether its dependencies are installed, which is what decides whether a start takes seconds or an install first."),
+    launch: PanelLaunchSchema.optional().describe(
+        "Where a start the sandbox is running has got to: its shell coming up, installing, its dev command running with nothing listening yet, or exited back to a prompt. Absent when nothing is starting and once it serves.",
+    ),
     // Whether anything this repo owns is answering, see `servers`. Not the same question as `running`: a panel
     // whose install is still going is running and not yet healthy, and a dev server someone started in their own
     // terminal is healthy without the daemon running it.