@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/contracts/capabilities.contract.ts

@@ -1,5 +1,5 @@
 import { eventIterator, oc } from "@orpc/contract";
-import { IntenticLineSchema } from "../events.js";
+import { IntenticLineSchema } from "../events/system-events.js";
 import {
     CapabilitiesListSchema,
     CapabilityCardParamSchema,
@@ -16,18 +16,8 @@ import {
 import { MarketplaceRequestSchema, MarketplaceSchema } from "../schemas/marketplace.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* The sandbox's unified capability manifest. `list` returns each active capability with its live status, the
- * non-secret echo of its config, and the NAMES of the credentials it holds. `add` upserts a capability and
- * STREAMS its apply (devops scaffolding / service provisioning emit ndjson progress; mcp/integration emit a
- * terminal frame), mirroring the /intentic runner. `remove` tears it down (devops refuses, deleting the repos
- * is data loss). `status` re-probes a single capability for a lazy UI refresh. `marketplace` resolves a Claude
- * Code plugin marketplace repo into installable plugin-capability configs.
- *
- * `add` IS ALSO THE EDIT, because the write is an upsert: the same id with a changed config changes that
- * connection. A caller editing one has never been shown its credentials, so it sends VAULTED
- * (capability-secrets.ts) for each it is leaving alone and the daemon resolves those from what is stored before
- * anything runs, the only way to change one setting on a tunnel without re-typing its key. A marker with
- * nothing behind it is refused rather than written. */
+// The sandbox's unified capability manifest, spanning `list`/`add`/`remove`/`status`/`marketplace`. A VAULTED marker
+// with nothing stored behind it is refused rather than silently written.
 export const capabilitiesContract = {
     list: oc
         .route({
@@ -48,11 +38,7 @@ export const capabilitiesContract = {
         })
         .input(CapabilitySchema)
         .output(eventIterator(IntenticLineSchema)),
-    /* TRY THE SETTINGS BEFORE SAVING THEM. Nothing is written and nothing is applied: the daemon dials the
-     * service the way the connection would and hands back what it said. It exists because the alternative is
-     * the form's only feedback being the card afterwards reading "not connected", which names none of the six
-     * answers that could have been wrong. A credential the caller is keeping arrives as VAULTED here too, so
-     * an edit can be tested without re-typing a key. */
+    // A credential the caller is keeping arrives as VAULTED here too, so an edit can be tested without retyping a key.
     probe: oc
         .route({
             method: "POST",
@@ -73,10 +59,6 @@ export const capabilitiesContract = {
         })
         .input(CapabilityIdParamSchema)
         .output(OkSchema),
-    /* Give a connection a different name, carrying what the old one keyed: a browser profile with its logins,
-     * a connected machine's enrollment, an extension's checkout. The name is the agent's handle for the thing,
-     * so this is a migration, add + remove would lose exactly the state that makes the connection worth
-     * keeping. A kind whose name is part of what it IS (the scaffolders, the one-per-sandbox cards) refuses. */
     rename: oc
         .route({
             method: "POST",
@@ -87,7 +69,7 @@ export const capabilitiesContract = {
         })
         .input(CapabilityRenameSchema)
         .output(OkSchema),
-    // Replace just the secret in a capability's config (the /secrets page's edit) and re-run its apply.
+    // Called by the /secrets page's edit action.
     setSecret: oc
         .route({
             method: "POST",
@@ -106,11 +88,7 @@ export const capabilitiesContract = {
         })
         .input(CapabilityIdParamSchema)
         .output(CapabilityStatusSchema),
-    /* One capability's stored config, secrets included, how an extension BACKEND dials the service behind a
-     * connected capability (ext-deployments reads its Komodo's key pair through this). Never a browser's: the
-     * handler refuses any caller with a member identity, so only the daemon's header grants reach it, and an
-     * extension's grant reaches it only when its manifest declares the route in `permissions.daemon`, which
-     * is the install dialog saying, in one line, "this extension can read connected credentials". */
+    // Gated by `permissions.daemon` in the manifest (ext-deployments reads its Komodo key pair this way).
     connection: oc
         .route({
             method: "GET",
@@ -130,8 +108,6 @@ export const capabilitiesContract = {
         })
         .input(MarketplaceRequestSchema)
         .output(MarketplaceSchema),
-    // "Not needed": stop offering this card until the workspace evidence behind it changes. Nothing is torn
-    // down and nothing is remembered about the card itself, only the evidence it was declined against.
     dismiss: oc
         .route({
             method: "DELETE",
@@ -142,8 +118,7 @@ export const capabilitiesContract = {
         })
         .input(CapabilityCardParamSchema)
         .output(OkSchema),
-    // Start an agent-kind capability's interactive login (its declared loginCommand) in a visible terminal
-    // session the user types into, device-code sign-in flows. Returns the session the panel attaches to.
+    // Runs the capability's declared `loginCommand` in the terminal session the panel attaches to.
     login: oc
         .route({
             method: "POST",
@@ -154,9 +129,7 @@ export const capabilitiesContract = {
         })
         .input(CapabilityIdParamSchema)
         .output(CapabilityLoginSchema),
-    // Mint one TOTP code from the capability's stored seed (a field its card marks `totp`). The one capability
-    // read the agent token is admitted to (see auth/grants): a code expires within its period and never reveals
-    // the seed, so the in-sandbox `otp` command can answer a 2FA prompt without the agent holding the factor.
+    // The seed comes from the config field the card marks `totp`.
     otp: oc
         .route({
             method: "GET",

package/src/contracts/chores.contract.ts

@@ -2,18 +2,10 @@ import { oc } from "@orpc/contract";
 import { ChoreLedgerWriteSchema, ChoreProbeRequestSchema, ChoresReportSchema } from "../schemas/maintenance.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* Maintenance evidence: what every repo under /work currently measures, and what has already been done about it.
- * Three routes, because there are exactly three things the surface does, read the evidence, ask for a
- * measurement to be retaken, and record what a turn concluded.
- *
- * There is no `GET /chores/{id}` and no "run this chore" route on purpose. A chore RUN is an ordinary isolated
- * fleet agent (`POST /agent` with a derived conversation id), the same as an acceptance run or a documentation
- * generation, so the worktree, the live status, the cost, the transcript and the /agents/<id> page already
- * exist, and adding a bespoke launcher here would be a second way to start a turn that has to be kept in step
- * with the first. */
+// Maintenance evidence across `list`/`probe`/`record`. No route runs a chore: a chore run is an ordinary isolated fleet
+// agent (`POST /agent`), reusing its worktree, status, cost and transcript rather than duplicating a launcher here.
 export const choresContract = {
-    // Every repo's standing evidence in one read: cached probe results (with their age and state), the cheap
-    // resident signals, the ledger, and the daemon's node version. The rail badge polls this; so does the panel.
+    // Polled by both the rail badge and the panel.
     list: oc
         .route({
             method: "GET",
@@ -23,8 +15,6 @@ export const choresContract = {
                 "Every repo's standing evidence in one read: what the last measurement found and how old it is, the cheap signals that are always current, and what has already been decided about each.",
         })
         .output(ChoresReportSchema),
-    // Re-run one repo's probe now, ignoring its TTL, the panel's per-probe refresh. An ack: the runner works in
-    // the background and the result arrives on the next `list`, because a jscpd sweep outlives any sane request.
     probe: oc
         .route({
             method: "POST",
@@ -35,8 +25,7 @@ export const choresContract = {
         })
         .input(ChoreProbeRequestSchema)
         .output(OkSchema),
-    // Record what a chore turn concluded, or snooze one. Upsert by repo+chore: a chore has one current verdict,
-    // and a growing history of "we looked at this and it was fine" is not something any reader wants paged.
+    // Also how a snooze is recorded, upserted the same way as a verdict.
     record: oc
         .route({
             method: "POST",

package/src/contracts/endpoints.contract.ts

@@ -3,19 +3,11 @@ import { z } from "zod";
 import { CapabilityIdParamSchema } from "../schemas/capabilities.js";
 import { ModelsSchema } from "../schemas/provider-oauth.js";
 
-// An `endpoint` capability's picker catalog, the models the configured server itself publishes, read from its
-// own /v1/models. Every other provider's catalog is one fixed route because there is one of each; endpoints are
-// user-created and unbounded, so the id rides in the path. There is no seed floor and no static list: what a
-// model API serves is knowable only by asking it, and an empty answer is the honest report that we could not.
+// Endpoints are user-created and unbounded (unlike every other provider, which has one fixed catalog route), so the id
+// rides in the path.
 
-/* The free trial's remaining allowance, on the endpoints contract because the trial IS an endpoint, the one
- * the daemon provisions rather than the user (agent-catalog.ts TRIAL_ENDPOINT_ID). It is a separate read from
- * the catalog above because it answers a different question and changes on a different clock: the model list is
- * a property of the upstream, while this is a property of the ACCOUNT and moves with every message sent.
- *
- * `available` false is the ordinary answer, not an error: most sandboxes run against a platform that serves no
- * trial, and the picker simply has no trial row to badge.
- */
+// The trial is an endpoint the daemon provisions rather than the user (TRIAL_ENDPOINT_ID); a separate read since
+// this is a property of the account, moving with every message, not of the upstream model list.
 const TrialHealthSchema = z.enum(["unknown", "healthy", "degraded", "unavailable"]);
 export type TrialHealth = z.infer<typeof TrialHealthSchema>;
 
@@ -30,16 +22,7 @@ export const TrialStatusSchema = z.object({
     resetsAt: z.string().optional(),
     // Earliest known time a quarantined upstream key can be tried again.
     retryAt: z.string().optional(),
-    /* THE REAL MODEL BEHIND THE TRIAL'S ONE PUBLISHED ID, on this account's most recent message.
-     *
-     * The trial routes per message across a ladder of models (the platform's trial-ladder.ts), so the id the
-     * user selected names the trial rather than what answered them. Telling them which model ran is what keeps
-     * that from being a black box: an answer that reads as weak has a visible cause, and a bug report can name
-     * the model instead of guessing at one.
-     *
-     * It arrives on the STATUS poll rather than in the turn's own stream because the translator sits between the
-     * platform and this daemon and does not forward response headers. The client refreshes this when a trial
-     * turn ends, so in practice it is the model that served the turn just finished. Absent until one has been. */
+    // The real model that served the last trial message; the published id only names the trial ladder.
     servedModel: z.string().optional(),
 });
 export type TrialStatusResponse = z.infer<typeof TrialStatusSchema>;

package/src/contracts/exit.contract.ts

@@ -1,24 +1,13 @@
 import { eventIterator, oc } from "@orpc/contract";
-import { IntenticLineSchema } from "../events.js";
+import { IntenticLineSchema } from "../events/system-events.js";
 import { ExitCountriesSchema, ExitIdParamSchema, ExitListSchema, ExitObservationSchema, ExitUseInputSchema } from "../schemas/exit.js";
 import { OkSchema } from "../schemas/shared.js";
 
-// The live GEO EXIT surface. An exit is ADDED as an `exit` capability (which provider, a resting country,
-// whether it comes up on boot); it is STARTED, MOVED and ROTATED here. Same split as the vpn contract and for
-// the same reason: switching country is a runtime operation performed many times over one stored pool, by the
-// operator from the capability card and by the agent through `exit` on its PATH, which calls these very routes.
-//
-// The difference from vpn is what "success" means. A dial succeeds when the tunnel is up; a country switch
-// succeeds only when the egress ADDRESS has moved, which is why `use` and `rotate` end by fetching an
-// ExitObservation through the exit's own proxy and fail when it does not agree with what was asked for.
-//
-// Nothing here changes the sandbox's default route, ever. Each exit publishes a SOCKS proxy and callers opt
-// in; the daemon's own traffic, the model endpoint and the tunnel that makes this sandbox reachable stay on
-// the plain uplink no matter what is up.
+// An exit is added as an `exit` capability; started, moved and rotated here, since switching country is a
+// runtime operation done both by the operator and by the agent's `exit` command on PATH. Each exit publishes an opt-in
+// SOCKS proxy; the sandbox's default route, model endpoint and reachability tunnel never move.
 export const exitContract = {
-    // Every configured exit with its live state, where it was asked to come out and where it actually does.
-    // Drives the capability card, the browser account picker and `geo list` (the CLI is `geo`: `exit` is a shell
-    // builtin, so a binary of that name is unreachable from a command line).
+    // Drives the capability card, the account picker and `geo list` (the CLI is `geo`; `exit` is a shell builtin).
     list: oc
         .route({
             method: "GET",
@@ -28,9 +17,7 @@ export const exitContract = {
                 "Every configured exit with its live state, the country it was asked to appear in, and the country it actually appears in. Those last two disagreeing is the whole reason this reports both.",
         })
         .output(ExitListSchema),
-    // What this exit can reach, ranked by how much capacity is actually there. Live from the provider when it
-    // answers (Tor's directory, VPN Gate's CSV, the pasted confs), from the baked fallback when it does not,
-    // and `live` says which. This is what auto-fills the country picker instead of a user hunting hostnames.
+    // "Provider" is Tor's directory, VPN Gate's CSV, or pasted confs; this is what auto-fills the country picker.
     countries: oc
         .route({
             method: "GET",
@@ -41,9 +28,6 @@ export const exitContract = {
         })
         .input(ExitIdParamSchema)
         .output(ExitCountriesSchema),
-    // Bring the exit up at its stored country. Streams, because a first start pulls a catalog, brings up a
-    // tunnel and then verifies the address, which is tens of seconds on the free providers and can fail at
-    // each step with something the user has to read. Idempotent: starting an up exit reports it and stops.
     start: oc
         .route({
             method: "POST",
@@ -54,9 +38,6 @@ export const exitContract = {
         })
         .input(ExitIdParamSchema)
         .output(eventIterator(IntenticLineSchema)),
-    // Move to another country, starting the exit first if it was down. Streams for the same reason as start,
-    // and THROWS when the observed country does not end up matching: a switch that silently left traffic where
-    // it was is the one failure mode this whole feature exists to make impossible.
     use: oc
         .route({
             method: "POST",
@@ -67,8 +48,7 @@ export const exitContract = {
         })
         .input(ExitUseInputSchema)
         .output(eventIterator(IntenticLineSchema)),
-    // A different address in the SAME country. Cheap on tor (a control-port signal), a re-dial to another
-    // server on the rest. Fails when the address does not actually change, which on a small pool it can't.
+    // Cheap on tor (a control-port signal); a re-dial to another server for everything else.
     rotate: oc
         .route({
             method: "POST",
@@ -79,8 +59,6 @@ export const exitContract = {
         })
         .input(ExitIdParamSchema)
         .output(eventIterator(IntenticLineSchema)),
-    // What the world sees through this exit right now. Cheap, unstreamed, and the honest answer to "am I
-    // actually in Germany", which is the question every other route here is judged against.
     check: oc
         .route({
             method: "POST",
@@ -91,7 +69,6 @@ export const exitContract = {
         })
         .input(ExitIdParamSchema)
         .output(ExitObservationSchema),
-    // Take it down. Tolerates an already-down exit: "make it not be up" is the contract, not "it was up".
     stop: oc
         .route({
             method: "POST",

package/src/contracts/extensions.contract.ts

@@ -19,10 +19,8 @@ import {
 import { ExtensionReadinessSchema } from "../schemas/maintenance.js";
 import { OkSchema } from "../schemas/shared.js";
 
-// Installed extensions resolved to their approved manifests, what the web extension host boots from. The
-// bundle itself is a plain Hono route (GET /extensions/{id}/bundle): raw ESM bytes are not an oRPC payload.
-// `settings`/`setSettings` carry the extension's own contributes.settings values; keys the manifest never
-// declared are refused, the same honesty rule the host applies to runtime view/command registrations.
+// Installed extensions resolved to their approved manifests. The bundle itself is a plain Hono route, `GET
+// /extensions/{id}/bundle`, not part of this oRPC contract: raw ESM bytes aren't a JSON payload.
 export const extensionsContract = {
     list: oc
         .route({
@@ -33,9 +31,7 @@ export const extensionsContract = {
                 "Every extension installed here, resolved to the manifest the owner approved, which is what the app boots its extension host from. The code itself is served separately, because raw script bytes are not a JSON answer.",
         })
         .output(ExtensionsListSchema),
-    // Author a new extension in place: writes a running one into .intentic/config/workspace-extensions/<name>/. The only
-    // creating route here, and it exists because that directory is otherwise reachable exclusively through an
-    // agent's file tools, which is a fine way to CHANGE an extension and a poor way to meet the idea of one.
+    // Writes into `.intentic/config/workspace-extensions/<name>/`.
     create: oc
         .route({
             method: "POST",
@@ -65,9 +61,7 @@ export const extensionsContract = {
         })
         .input(ExtensionSettingsInputSchema)
         .output(OkSchema),
-    // The owner's on/off switch. Disabling stops the extension's declared processes here and now; its agent
-    // plugin dir and PATH entry are rebuilt per turn, and an `environment` fragment only at the next image
-    // rebuild, the Extensions tab states which of those an extension actually has.
+    // The Extensions tab states which of these apply to a given extension.
     setEnabled: oc
         .route({
             method: "POST",
@@ -78,10 +72,7 @@ export const extensionsContract = {
         })
         .input(ExtensionEnabledInputSchema)
         .output(OkSchema),
-    // The host reporting which declared routes it just let through. Written by the browser because that is where
-    // the permission gate runs (apiImpl.ts), the daemon sees an extension's traffic as ordinary authenticated
-    // requests and cannot tell which extension, or which declared entry, any of it belongs to. Every extension's
-    // accumulated counts ride together so the bookkeeping is one request rather than a burst of them.
+    // The permission gate that produces these counts runs in the browser (apiImpl.ts).
     recordUsage: oc
         .route({
             method: "POST",
@@ -92,9 +83,6 @@ export const extensionsContract = {
         })
         .input(ExtensionUsageBatchSchema)
         .output(OkSchema),
-    /* Whether this extension is fit for somebody else to run, the checks answerable from its files alone. Read
-     * on demand rather than carried on the list: it reads the bundle off disk per extension, and it is looked at
-     * when an author is about to publish, not every time the tab renders. */
     readiness: oc
         .route({
             method: "GET",
@@ -105,14 +93,8 @@ export const extensionsContract = {
         })
         .input(CapabilityIdParamSchema)
         .output(ExtensionReadinessSchema),
-    /* The update lifecycle for a GIT-INSTALLED extension. The list carries what the periodic registry check
-     * found (update/advisory/health per row); these are the verbs around it. `checkUpdates` runs the comparison
-     * now (the tab's "check now"). `updatePreview` stages the offered sha and answers with the version story +
-     * the mechanical powers diff, the read BEFORE the click, costing one throwaway clone like a registry
-     * browse. `applyUpdate` is the transaction: re-clone, validate, quiesce, swap (keeping the outgoing
-     * checkout one back), restart, health-watch, on the EXISTING capability config, so a private-source token
-     * survives what a bare re-add would lose. `revert` swaps the kept-previous checkout back. Update and revert
-     * change the code that runs, so like install they are owner-only. */
+    // The extensions list itself carries what the periodic registry check found (update/advisory/health per row); these
+    // routes are the verbs around it.
     checkUpdates: oc
         .route({
             method: "POST",
@@ -151,8 +133,6 @@ export const extensionsContract = {
         })
         .input(CapabilityIdParamSchema)
         .output(ExtensionUpdateAppliedSchema),
-    // The owner's standing answer per extension (notify / agent / auto, and the advisory opt-out), see
-    // ExtensionUpdatePolicySchema for what each rung means.
     setUpdatePolicy: oc
         .route({
             method: "POST",
@@ -163,9 +143,7 @@ export const extensionsContract = {
         })
         .input(ExtensionUpdatePolicyInputSchema)
         .output(OkSchema),
-    // Declared background processes (contributes.processes): supervised children of the daemon (respawned
-    // with backoff, PORT-assigned, one log file each — the terminals list carries their `svc-ext-<id>-<name>`
-    // log-view rows), with an optional tunneled preview route.
+    // Declared via `contributes.processes`; the terminals list shows each one's log as `svc-ext-<id>-<name>`.
     processStatus: oc
         .route({
             method: "GET",

package/src/contracts/git.contract.ts

@@ -12,9 +12,9 @@ import {
     GitFileSchema,
     GitFilesSchema,
     GitFileWriteSchema,
+    GitIndexMoveSchema,
     GitOperationStateSchema,
     GitRemoteStateSchema,
-    GitStageSchema,
     GitStatusSchema,
     PushRunSchema,
     PushSchema,
@@ -48,10 +48,9 @@ import {
 import { FileDiffSchema } from "../schemas/history.js";
 import { OkSchema, RepoParamSchema } from "../schemas/shared.js";
 
-// Per-repo git ops over the workspace repos: "root" (the /work repo) plus every discovered repo under /work
-// ({repo} is the repo's root-relative dir, URL-encoded). An unknown {repo} is a handler-thrown
-// NOT_FOUND; a path that escapes the repo is a BAD_REQUEST. `changes` is the workspace-wide review set the
-// Changes panel renders; commit/discard take optional `paths` for per-file actions.
+// Per-repo git ops over the workspace repos; `root` is /work, others are discovered under it, and {repo} is the
+// root-relative dir, URL-encoded. Unknown {repo} throws NOT_FOUND, an escaping path throws BAD_REQUEST. `changes` is
+// the workspace-wide review set; commit/discard take optional `paths`.
 export const gitContract = {
     changes: oc
         .route({
@@ -62,9 +61,7 @@ export const gitContract = {
                 "The workspace's whole review set in one answer: every repo that has something uncommitted, and within it every changed file with its status and line counts. This is what the Changes panel draws, and it is the call to make when you want to know whether a workspace is clean without walking the repos yourself.",
         })
         .output(GitChangesSchema),
-    // The git-history graph over one repo's real commits: the repo list (for the tree affordance + switcher),
-    // one repo's commit log, and lazy per-commit detail (changed files, then a file's before/after AT the
-    // commit). Read-only, commit/discard on the working tree stay the write path (above).
+    // Read-only: repo list, commit log, lazy per-commit diff; commit/discard on the tree are a separate write path.
     repos: oc
         .route({
             method: "GET",
@@ -74,8 +71,7 @@ export const gitContract = {
                 "The repos the daemon found under the workspace root, each with the id every other call in this group expects as its `{repo}` segment. The workspace root itself is always present as `root`.",
         })
         .output(GitReposSchema),
-    // The same repos with the host + project their remote names, how a caller recognises a workspace repo in a
-    // list of `owner/name` strings that came from somewhere else. Kept off `repos` (a `git remote -v` per repo).
+    // Same repos with the remote's host and `owner/name`; kept off `repos` since it costs a lookup per repo.
     remoteRepos: oc
         .route({
             method: "GET",
@@ -115,13 +111,8 @@ export const gitContract = {
         })
         .input(GitCommitFileDiffQuerySchema)
         .output(FileDiffSchema),
-    // Write actions from the graph's commit context menu (VSCode "Git Graph" parity). Non-destructive refs
-    // (branch/tag) return Ok and let git's errors propagate; the sequence + HEAD-moving ops return a
-    // GitActionResult so a conflict/clean-apply failure is a value, not a 500. Read routes above.
-    /* The halted-operation pair. `operation` is a READ every git surface can use to explain a worktree it cannot
-     * otherwise act on; `abort` is the single way out, and it is git's own `--abort` rather than anything
-     * clever. Neither is reachable from the daemon's own verbs, those abort themselves, so this exists purely
-     * for what a terminal left behind. */
+    // Non-destructive writes return Ok; HEAD-moving ops return a GitActionResult, a conflict is a value not 500.
+    // `abort` is git's own `--abort`, the only way out of what `operation` reports; daemon verbs self-abort.
     operation: oc
         .route({
             method: "GET",
@@ -142,10 +133,7 @@ export const gitContract = {
         })
         .input(RepoParamSchema)
         .output(GitActionResultSchema),
-    /* Walk the current branch back to where it was before its last action, off the branch's own reflog. The
-     * complement to the Checkpoints timeline, not a duplicate of it: a checkpoint restores the working tree,
-     * this moves the ref. The read carries `previousSha`, which the write sends back as a concurrency token,
-     * an undo prepared against a stale view is refused rather than landing somewhere unlooked-at. */
+    // Moves the branch ref via reflog; requires `previousSha` from the matching read as a concurrency token.
     undoable: oc
         .route({
             method: "GET",
@@ -166,9 +154,7 @@ export const gitContract = {
         })
         .input(GitUndoSchema)
         .output(GitActionResultSchema),
-    /* The stash. Read as a list plus a per-entry diff, mirroring the commit log and commit-diff pair above,
-     * because a stash entry is a commit and the graph renders it as one. The writes are git's own four verbs;
-     * only `drop` is unrecoverable, and the route checkpoints before it. */
+    // A stash entry is a commit, read like the log/diff pair; only `drop` is unrecoverable and checkpoints first.
     stashes: oc
         .route({
             method: "GET",
@@ -237,7 +223,6 @@ export const gitContract = {
         })
         .input(GitTagCreateSchema)
         .output(OkSchema),
-    // The other two things one does with a tag, so the graph's tag pills are not a create-only affordance.
     deleteTag: oc
         .route({
             method: "POST",
@@ -353,7 +338,7 @@ export const gitContract = {
             path: "/git/{repo}/commit",
             summary: "Commit the pending changes",
             description:
-                "Records a commit with your message. Give it a list of paths to commit only those, or leave it out to commit everything pending. The answer carries the commit it created.",
+                "Records a commit with your message. It commits whatever is staged; add `stage` to stage something first — an empty object for everything pending, or a scope such as one side or one conversation's landed files. The answer carries the commit it created.",
         })
         .input(CommitSchema)
         .output(CommitResultSchema),
@@ -363,33 +348,32 @@ export const gitContract = {
             path: "/git/{repo}/discard",
             summary: "Throw away pending changes",
             description:
-                "Restores files to their committed state and deletes untracked ones. Give it paths to discard only those. The daemon checkpoints the workspace first, so this is recoverable from the timeline.",
+                "Restores files to their committed state and deletes untracked ones. Name paths or a scope to narrow it; with neither it throws away every uncommitted change in the repository. The daemon checkpoints the workspace first, so this is recoverable from the timeline.",
         })
         .input(DiscardSchema)
         .output(OkSchema),
-    // Index moves. Per-path, worktree untouched, so they need no checkpoint and can't fail destructively,
-    // git's own error (an unmatched pathspec) propagates.
+    // Take a scope, not a path list, so it covers files the caller never enumerated; the worktree is untouched.
     stage: oc
         .route({
             method: "POST",
             path: "/git/{repo}/stage",
-            summary: "Mark paths for the next commit",
-            description: "Adds paths to the index. Nothing on disk changes, so this is always safe and always reversible with the unstage call.",
+            summary: "Mark changes for the next commit",
+            description:
+                "Adds changes to the index: exactly the paths you name, everything a scope describes, or the whole repository when you name neither. Nothing on disk changes, so this is always safe and always reversible with the unstage call.",
         })
-        .input(GitStageSchema)
+        .input(GitIndexMoveSchema)
         .output(OkSchema),
     unstage: oc
         .route({
             method: "POST",
             path: "/git/{repo}/unstage",
-            summary: "Take paths back out of the next commit",
-            description: "Removes paths from the index and leaves the file itself untouched. The exact reverse of staging.",
+            summary: "Take changes back out of the next commit",
+            description:
+                "Removes changes from the index and leaves the files themselves untouched, on the same terms as staging. The exact reverse of it.",
         })
-        .input(GitStageSchema)
+        .input(GitIndexMoveSchema)
         .output(OkSchema),
-    // Local branch management for the switcher. `branches` also carries per-branch ahead/behind, so the list
-    // is enough to render sync state without a call per branch. Checkout is above (it moves HEAD, so it is
-    // checkpointed with the other HEAD-movers).
+    // `branches` includes per-branch ahead/behind, so the switcher renders sync state without a call per branch.
     branches: oc
         .route({
             method: "GET",
@@ -420,9 +404,7 @@ export const gitContract = {
         })
         .input(GitBranchDeleteSchema)
         .output(OkSchema),
-    // Remote sync. All three report a GitActionResult rather than throwing: no remote, no credentials and a
-    // non-fast-forwardable pull are ORDINARY outcomes the panel renders, not 500s. `remote` is the read
-    // (ahead/behind as of the last fetch, hence the Fetch button) the sync bar polls.
+    // Reflects the last fetch, not a live check; writes below report a GitActionResult, not a throw, on failure.
     remote: oc
         .route({
             method: "GET",
@@ -453,11 +435,7 @@ export const gitContract = {
         })
         .input(RepoParamSchema)
         .output(GitActionResultSchema),
-    /* THE PUSH IS A RUN, the pre-push check's three verbs over again (prepush.contract.ts), for the same reason:
-     * a push runs the repository's own pre-push hook, which for a workspace with a real gate is the whole suite,
-     * and a request held open for minutes dies at the first proxy and at the browser's own header deadline. So
-     * `push` starts it and answers at once, `pushState` is polled for the verdict, and the output is a terminal
-     * the owner can watch. Addressed by repo, unlike the check: there is one working tree but many remotes. */
+    // Starts the push and returns at once; poll `pushState` for the verdict, since it runs the pre-push hook.
     push: oc
         .route({
             method: "POST",
@@ -516,9 +494,7 @@ export const gitContract = {
         })
         .input(GitFileWriteSchema)
         .output(OkSchema),
-    // Write + commit-that-path-only + push, as one step with one answer. Reports rather than throws for the
-    // same reason the remote trio above does: no remote, no credentials and "you are on a side branch" are
-    // ordinary outcomes a screen renders, not 500s.
+    // Writes, commits only this path, and pushes in one call; no remote, no credentials, wrong branch are reported.
     publishFile: oc
         .route({
             method: "POST",

package/src/contracts/host.contract.ts

@@ -5,55 +5,20 @@ import { HostScopesSchema } from "../schemas/capabilities.js";
 import { HostFactsSchema } from "../schemas/hosts.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* What a connected device can be ASKED, over the socket it opened to this sandbox.
- *
- * The direction is the unusual part: the machine is the oRPC SERVER and the daemon holds the client, even though
- * the machine is the side that dialled. A personal device sits behind NAT with a closing lid, so it can only
- * ever be the one that connects, but everything is asked OF it. oRPC's websocket adapter takes any socket-like
- * object on either side, so the roles are free to be the opposite of who placed the call.
- *
- * No `.route()` on these: HTTP method and path are for the daemon's own REST surface, and this contract never
- * touches HTTP. The procedure path IS the address.
- *
- * `mcp` IS THE DELIBERATE HOLE in the typing, and it is worth understanding before someone "fixes" it. The agent
- * talks to a machine in MCP, over the daemon's loopback bridge; if this contract described each tool, then the
- * daemon would have to know every tool's schema and translate, and a machine could no longer learn a tool
- * without a matching daemon release. Keeping one opaque procedure is what buys the machine an independent
- * release cycle. The payload is still validated where it is understood: on the machine, against the tool's own
- * schema, and by the agent's MCP client on the way back. */
+// What a connected device can be asked, over the socket it opened; the machine is the oRPC server, the daemon the
+// client. No `.route()`: the procedure path is the address, not HTTP. `mcp` stays opaque (`z.unknown()`) so a machine
+// can add tools without a daemon release; validated on the machine and by the agent's MCP client.
 export const hostContract = {
-    // What this device is, pulled right after the socket authenticates, and again whenever the sandbox wants
-    // it fresh. The card shows it, and the agent's skill pack is written against it.
+    // Device facts, refreshed on connect and on demand; the agent's skill pack is written against this shape.
     describe: oc.output(HostFactsSchema),
-    // The grant, pushed down on every connect and again whenever the owner edits the card. The machine ENFORCES
-    // it; nothing on the sandbox side checks a scope, so this call is the only thing that moves the boundary.
+    // Pushed on connect and on edit; the machine enforces the grant, nothing on the sandbox side checks a scope.
     setScopes: oc.input(HostScopesSchema).output(OkSchema),
-    // Liveness, driven by the daemon: it doubles as the keepalive that stops an idle tunnel from reaping the
-    // connection, and as the probe whose failure means the machine is gone rather than quiet.
+    // Daemon-driven liveness; doubles as keepalive against an idle tunnel and the gone-vs-quiet probe.
     ping: oc.output(OkSchema),
-    // One MCP JSON-RPC message in, its answer out, forwarded verbatim in both directions. See above.
+    // One MCP JSON-RPC message forwarded verbatim in both directions, unmodified.
     mcp: oc.input(z.unknown()).output(z.unknown()),
-    /* One operation on one of this machine's sandboxes, narrated as it happens.
-     *
-     * TYPED, unlike `mcp`, and the difference is who is on the other end. `mcp`'s reader is a model, which has
-     * nothing to do with a line as it arrives and everything to gain from the machine learning tools without a
-     * daemon release. This reader is a PERSON watching a progress log: an update pulls an image and recreates a
-     * container, which is minutes of silence unless the lines travel while they are produced. A stream is what
-     * the browser needs, and a stream is the one thing an MCP tool result cannot be.
-     *
-     * The scope is still checked here, on the machine, by the same functions the MCP tools call, this adds a
-     * way of WATCHING an operation, never a way of skipping the switch that permits it. */
+    // Streamed for a person watching progress; the scope is checked on the machine, this only adds visibility.
     runSandboxFlow: oc.input(DeviceSandboxFlowSchema).output(eventIterator(DeviceFlowLineSchema)),
-    /* Update or restart the agent on this device, narrated the same way — and the one call that expects to be
-     * cut off, because the work it starts stops the process serving it (see DeviceAgentFlowSchema).
-     *
-     * A TYPED PROCEDURE rather than another `run_command` line, and the reason is the failure mode rather than
-     * the typing: run through `run_command` this is a child of a process about to be SIGTERMed, and a swap
-     * interrupted between its two renames leaves the device with no agent binary at all. Here the agent spawns
-     * the work detached from the socket first, so nothing the daemon does to this stream can brick it.
-     *
-     * It takes "Run commands" — the same grant `run_command` takes, since this is literally a command its owner
-     * could type — rather than the sandbox switches, which are about containers. An agent too old to serve this
-     * procedure is a real answer too: the view falls back to naming the command, as it did before. */
+    // Spawns the work detached from the socket, so restarting the agent process cannot brick a swap in progress.
     runAgentFlow: oc.input(DeviceAgentFlowSchema).output(eventIterator(DeviceFlowLineSchema)),
 };