@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/contracts/ci.contract.ts

@@ -12,7 +12,7 @@ import {
 // Pipelines on the workspace repos' github/gitlab remotes. `runs` serves the Pipelines rail view (cache +
 // on-demand backfill; per-repo webhook warnings ride along); `rerun`/`cancel` proxy to the vendor; `fix`
 // opens an isolated agent conversation seeded with the failure context. The public webhook receiver
-// (/ci/webhook/:host) is a plain Hono route — vendors can't do Google ID tokens — so it lives outside this
+// (/ci/webhook/:host) is a plain Hono route, vendors can't do Google ID tokens, so it lives outside this
 // contract, like /automations/{id}/fire.
 export const ciContract = {
     runs: oc.route({ method: "GET", path: "/ci/runs" }).output(CiRunsResponseSchema),
@@ -20,7 +20,7 @@ export const ciContract = {
     cancel: oc.route({ method: "POST", path: "/ci/runs/cancel" }).input(CiRunParamSchema).output(OkSchema),
     jobs: oc.route({ method: "POST", path: "/ci/runs/jobs" }).input(CiRunParamSchema).output(CiJobsResponseSchema),
     fix: oc.route({ method: "POST", path: "/ci/fix" }).input(CiFixParamSchema).output(CiFixResponseSchema),
-    // "I have looked at the pipelines" — what silences the rail badge for breakages already read. No input:
+    // "I have looked at the pipelines", what silences the rail badge for breakages already read. No input:
     // the surface is read as a whole, and the daemon stamps its own clock so a skewed browser can't mark
     // future failures as already seen.
     seen: oc.route({ method: "POST", path: "/ci/seen" }).output(CiSeenResponseSchema),

package/src/contracts/claude.contract.ts

@@ -10,18 +10,18 @@ import {
     OkSchema,
 } from "../schemas.js";
 
-// Claude subscription OAuth — the sandbox owns the credential. `start` hands the browser the authorize URL +
+// Claude subscription OAuth, the sandbox owns the credential. `start` hands the browser the authorize URL +
 // PKCE material; `exchange` stores the resulting tokens as a new account and returns it; `accounts` lists the
 // connected accounts; `rename` renames one; `disconnect` clears the one named by id. A sandbox can hold several
 // Claude accounts.
 //
 // The model catalog is NOT here: it is the one thing every provider answers identically, so it lives on the
 // shared /providers/{provider}/models route (providers.contract.ts). What is left is what is genuinely Claude's
-// — an account handshake no other provider has.
+//, an account handshake no other provider has.
 export const claudeContract = {
     start: oc.route({ method: "POST", path: "/claude/oauth/start" }).output(AuthorizeChallengeSchema),
     exchange: oc.route({ method: "POST", path: "/claude/oauth/exchange" }).input(OauthExchangeSchema).output(OauthAccountSchema),
-    // Each account carries its plan-limit reading. `force` re-measures before answering — see
+    // Each account carries its plan-limit reading. `force` re-measures before answering, see
     // AccountListQuerySchema, and USAGE_WAIT_MS in claude.routes.ts for what an ordinary read waits.
     accounts: oc.route({ method: "GET", path: "/claude/accounts" }).input(AccountListQuerySchema).output(OauthAccountListSchema),
     rename: oc.route({ method: "POST", path: "/claude/account/rename" }).input(AccountRenameSchema).output(OauthAccountSchema),

package/src/contracts/drafts.contract.ts

@@ -2,7 +2,7 @@ import { oc } from "@orpc/contract";
 import { DraftIdParamSchema, DraftsListSchema, DraftSummarySchema, OkSchema } from "../schemas.js";
 
 // The sandbox's post-drafts queue (agent-proposed posts awaiting approval). The agent creates draft files
-// directly — these routes are the OWNER's side: `list` is the approval inbox, `upsert` covers approve / edit /
+// directly, these routes are the OWNER's side: `list` is the approval inbox, `upsert` covers approve / edit /
 // retry (all a plain re-post with a field changed, like the automations enabled toggle), `remove` is reject.
 export const draftsContract = {
     list: oc.route({ method: "GET", path: "/drafts" }).output(DraftsListSchema),

package/src/contracts/endpoints.contract.ts

@@ -2,12 +2,12 @@ import { oc } from "@orpc/contract";
 import { z } from "zod";
 import { CapabilityIdParamSchema, ModelsSchema } from "../schemas.js";
 
-// An `endpoint` capability's picker catalog — the models the configured server itself publishes, read from its
+// 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.
 
-/* The free trial's remaining allowance, on the endpoints contract because the trial IS an endpoint — the one
+/* 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.

package/src/contracts/exit.contract.ts

@@ -0,0 +1,42 @@
+import { eventIterator, oc } from "@orpc/contract";
+import { IntenticLineSchema } from "../events.js";
+import { ExitCountriesSchema, ExitIdParamSchema, ExitListSchema, ExitObservationSchema, ExitUseInputSchema, OkSchema } from "../schemas.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 Status 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.
+export const exitContract = {
+    // Every configured exit with its live state, where it was asked to come out and where it actually does.
+    // Drives the Status 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).
+    list: oc.route({ method: "GET", path: "/exit" }).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.
+    countries: oc.route({ method: "GET", path: "/exit/{id}/countries" }).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", path: "/exit/{id}/start" }).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", path: "/exit/{id}/use" }).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.
+    rotate: oc.route({ method: "POST", path: "/exit/{id}/rotate" }).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", path: "/exit/{id}/check" }).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", path: "/exit/{id}/stop" }).input(ExitIdParamSchema).output(OkSchema),
+};

package/src/contracts/extensions.contract.ts

@@ -19,7 +19,7 @@ import {
     WorkspaceExtensionCreateSchema,
 } from "../schemas.js";
 
-// Installed extensions resolved to their approved manifests — what the web extension host boots from. The
+// 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.
@@ -27,28 +27,28 @@ export const extensionsContract = {
     list: oc.route({ method: "GET", path: "/extensions" }).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.
+    // agent's file tools, which is a fine way to CHANGE an extension and a poor way to meet the idea of one.
     create: oc.route({ method: "POST", path: "/extensions/workspace" }).input(WorkspaceExtensionCreateSchema).output(WorkspaceExtensionCreatedSchema),
     settings: oc.route({ method: "GET", path: "/extensions/{id}/settings" }).input(CapabilityIdParamSchema).output(ExtensionSettingsSchema),
     setSettings: oc.route({ method: "POST", path: "/extensions/{id}/settings" }).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.
+    // rebuild, the Extensions tab states which of those an extension actually has.
     setEnabled: oc.route({ method: "POST", path: "/extensions/{id}/enabled" }).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
+    // 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.
     recordUsage: oc.route({ method: "POST", path: "/extensions/{id}/usage" }).input(ExtensionUsageInputSchema).output(OkSchema),
-    /* Whether this extension is fit for somebody else to run — the checks answerable from its files alone. Read
+    /* 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", path: "/extensions/{id}/readiness" }).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
+     * 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
+     * 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. */
     checkUpdates: oc.route({ method: "POST", path: "/extensions/updates/check" }).output(ExtensionUpdatesCheckedSchema),
@@ -61,7 +61,7 @@ export const extensionsContract = {
         .input(ExtensionUpdateActionSchema)
         .output(ExtensionUpdateAppliedSchema),
     revert: oc.route({ method: "POST", path: "/extensions/{id}/revert" }).input(CapabilityIdParamSchema).output(ExtensionUpdateAppliedSchema),
-    // The owner's standing answer per extension (notify / agent / auto, and the advisory opt-out) — see
+    // 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", path: "/extensions/{id}/update-policy" }).input(ExtensionUpdatePolicyInputSchema).output(OkSchema),
     // Declared background processes (contributes.processes): tmux-managed through the panel machinery

package/src/contracts/git.contract.ts

@@ -54,9 +54,9 @@ export const gitContract = {
     changes: oc.route({ method: "GET", path: "/git/changes" }).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).
+    // commit). Read-only, commit/discard on the working tree stay the write path (above).
     repos: oc.route({ method: "GET", path: "/git/repos" }).output(GitReposSchema),
-    // The same repos with the host + project their remote names — how a caller recognises a workspace repo in a
+    // 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).
     remoteRepos: oc.route({ method: "GET", path: "/git/remote-repos" }).output(GitRemoteReposSchema),
     log: oc.route({ method: "GET", path: "/git/{repo}/log" }).input(GitLogQuerySchema).output(GitLogSchema),
@@ -67,13 +67,13 @@ export const gitContract = {
     // 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
+     * clever. Neither is reachable from the daemon's own verbs, those abort themselves, so this exists purely
      * for what a terminal left behind. */
     operation: oc.route({ method: "GET", path: "/git/{repo}/operation" }).input(RepoParamSchema).output(GitOperationStateSchema),
     abort: oc.route({ method: "POST", path: "/git/{repo}/abort" }).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 —
+     * 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. */
     undoable: oc.route({ method: "GET", path: "/git/{repo}/undo" }).input(RepoParamSchema).output(GitUndoStateSchema),
     undo: oc.route({ method: "POST", path: "/git/{repo}/undo" }).input(GitUndoSchema).output(GitActionResultSchema),
@@ -101,7 +101,7 @@ export const gitContract = {
     status: oc.route({ method: "GET", path: "/git/{repo}/status" }).input(RepoParamSchema).output(GitStatusSchema),
     commit: oc.route({ method: "POST", path: "/git/{repo}/commit" }).input(CommitSchema).output(CommitResultSchema),
     discard: oc.route({ method: "POST", path: "/git/{repo}/discard" }).input(DiscardSchema).output(OkSchema),
-    // Index moves. Per-path, worktree untouched, so they need no checkpoint and can't fail destructively —
+    // Index moves. Per-path, worktree untouched, so they need no checkpoint and can't fail destructively,
     // git's own error (an unmatched pathspec) propagates.
     stage: oc.route({ method: "POST", path: "/git/{repo}/stage" }).input(GitStageSchema).output(OkSchema),
     unstage: oc.route({ method: "POST", path: "/git/{repo}/unstage" }).input(GitStageSchema).output(OkSchema),
@@ -113,7 +113,7 @@ export const gitContract = {
     deleteBranch: oc.route({ method: "POST", path: "/git/{repo}/branches/delete" }).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.
+    // (ahead/behind as of the last fetch, hence the Fetch button) the sync bar polls.
     remote: oc.route({ method: "GET", path: "/git/{repo}/remote" }).input(RepoParamSchema).output(GitRemoteStateSchema),
     fetch: oc.route({ method: "POST", path: "/git/{repo}/fetch" }).input(RepoParamSchema).output(GitActionResultSchema),
     pull: oc.route({ method: "POST", path: "/git/{repo}/pull" }).input(RepoParamSchema).output(GitActionResultSchema),

package/src/contracts/grok.contract.ts

@@ -1,14 +1,14 @@
 import { oc } from "@orpc/contract";
 import { AccountIdSchema, DeviceStartSchema, OauthAccountListSchema, OkSchema } from "../schemas.js";
 
-// xAI Grok (via OpenCode) uses subscription OAuth — the sandbox owns the credential (OpenCode persists the
+// xAI Grok (via OpenCode) uses subscription OAuth, the sandbox owns the credential (OpenCode persists the
 // tokens and refreshes them). `start` authorizes xAI's headless device-code method and returns the verification
 // URL + instructions (which carry the one-time code the user enters at x.ai); OpenCode then polls to completion
-// — there is no paste-back — and the UI polls `accounts` until connected. `disconnect` clears the tokens.
-// ponytail: OpenCode holds one xAI auth per data dir, so `accounts` is 0 or 1 — the list shape matches the
+//, there is no paste-back, and the UI polls `accounts` until connected. `disconnect` clears the tokens.
+// ponytail: OpenCode holds one xAI auth per data dir, so `accounts` is 0 or 1, the list shape matches the
 // other providers without paying for per-account OpenCode servers yet.
 //
-// Like Claude's, this contract is now the account handshake alone — the model catalog answers on the shared
+// Like Claude's, this contract is now the account handshake alone, the model catalog answers on the shared
 // /providers/{provider}/models route (providers.contract.ts).
 export const grokContract = {
     start: oc.route({ method: "POST", path: "/grok/oauth/start" }).output(DeviceStartSchema),

package/src/contracts/host.contract.ts

@@ -6,7 +6,7 @@ import { HostFactsSchema, HostScopesSchema, MachineFlowLineSchema, MachineSandbo
  *
  * 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 computer 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
+ * 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
@@ -14,12 +14,12 @@ import { HostFactsSchema, HostScopesSchema, MachineFlowLineSchema, MachineSandbo
  *
  * `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
+ * 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. */
 export const hostContract = {
-    // What this computer is — pulled right after the socket authenticates, and again whenever the sandbox wants
+    // What this computer 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.
     describe: oc.output(HostFactsSchema),
     // The grant, pushed down on every connect and again whenever the owner edits the card. The machine ENFORCES
@@ -28,7 +28,7 @@ export const hostContract = {
     // 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.
     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 in, its answer out, forwarded verbatim in both directions. See above.
     mcp: oc.input(z.unknown()).output(z.unknown()),
     /* One operation on one of this machine's sandboxes, narrated as it happens.
      *
@@ -38,7 +38,7 @@ export const hostContract = {
      * 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
+     * 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. */
     runSandboxFlow: oc.input(MachineSandboxFlowSchema).output(eventIterator(MachineFlowLineSchema)),
 };

package/src/contracts/intentic.contract.ts

@@ -7,9 +7,9 @@ import { IntenticRunSchema, OkSchema } from "../schemas.js";
 export const intenticContract = {
     run: oc.route({ method: "POST", path: "/intentic" }).input(IntenticRunSchema).output(eventIterator(IntenticLineSchema)),
     // Launch the minutes-long apply → adopt reconcile as a one-shot tmux job (session panel-infra-apply) and
-    // return immediately — progress is followed by attaching the terminal, not by holding this request open.
+    // return immediately, progress is followed by attaching the terminal, not by holding this request open.
     apply: oc.route({ method: "POST", path: "/intentic/apply" }).output(OkSchema),
-    // Tail the running (or just-finished) apply's structured event stream — the same ndjson lines the tmux pane
+    // Tail the running (or just-finished) apply's structured event stream, the same ndjson lines the tmux pane
     // renders as text, persisted to a durable file so the UI shows per-resource progress that survives a page
     // refresh. Replays from the run's {kind:"start"} then follows live, closing on {kind:"exit"}. GET, like
     // /events, because it takes no input; reuses the loose IntenticLine shape so no new schema is needed.

package/src/contracts/logs.contract.ts

@@ -2,7 +2,7 @@ import { oc } from "@orpc/contract";
 import { LogReadQuerySchema, LogReadSchema, LogsListSchema } from "../schemas.js";
 
 // Daemon-owned debug logs (historyRoot/logs): terminal pipe-pane captures, intentic CLI run logs, daemon.log.
-// Read-only by design — the files are written by the daemon/tmux only, so the record stays trustworthy.
+// Read-only by design, the files are written by the daemon/tmux only, so the record stays trustworthy.
 export const logsContract = {
     list: oc.route({ method: "GET", path: "/logs" }).output(LogsListSchema),
     read: oc.route({ method: "GET", path: "/logs/file" }).input(LogReadQuerySchema).output(LogReadSchema),

package/src/contracts/loops.contract.ts

@@ -11,29 +11,29 @@ import {
     OkSchema,
 } from "../schemas.js";
 
-/* The loop routes — "run this conversation again until the goal is met".
+/* The loop routes, "run this conversation again until the goal is met".
  *
  * TWO HALVES THAT LOOK LIKE ONE FEATURE AND ARE NOT, which is why they share a file and share nothing else.
  *
  * A RUNNING LOOP has no editor. It is started against a conversation, it converges or it gives up, and then it
- * is history: `start`, `stop`, and a `list` of what has run. No upsert, no enabled toggle, no id of its own —
+ * is history: `start`, `stop`, and a `list` of what has run. No upsert, no enabled toggle, no id of its own,
  * the conversation IS the id.
  *
  * A SAVED LOOP is a manifest entry like a workflow, and gets the manifest treatment: list, save, remove. It is
  * the loop's MACHINERY without its goal (LoopDesignSchema says why at length), so it is authored once and
- * pointed at a different job every time. It has no `run` route of its own on purpose — running one is `start`
+ * pointed at a different job every time. It has no `run` route of its own on purpose, running one is `start`
  * with the design's fields and the composer's sentence, so there is exactly one way a loop begins and exactly
  * one place that can refuse it.
  *
  * `start` acks immediately with the loop as recorded and runs detached, the same contract POST /agent keeps: the
  * first iteration alone can take minutes, and every surface that would render progress is already attached to
- * the conversation. What comes back is the record, not an outcome — the outcome arrives on the fleet card.
+ * the conversation. What comes back is the record, not an outcome, the outcome arrives on the fleet card.
  */
 export const loopsContract = {
-    // Every loop this workspace has run, newest first — the record is kept after the loop ends, because "why did
+    // Every loop this workspace has run, newest first, the record is kept after the loop ends, because "why did
     // it stop at iteration 4" is the question a loop is read for, and the answer is its iteration history.
     list: oc.route({ method: "GET", path: "/loops" }).output(LoopsListSchema),
-    /* Start looping a conversation. Rejects when that conversation is already looping — a second loop on one
+    /* Start looping a conversation. Rejects when that conversation is already looping, a second loop on one
      * agent would have two pumps racing the same worktree and the same turn mutex, and the loser would spend a
      * turn to discover it.
      *
@@ -49,10 +49,10 @@ export const loopsContract = {
     stop: oc.route({ method: "POST", path: "/loops/{conversationId}/stop" }).input(LoopIdParamSchema).output(OkSchema),
 
     // Every saved loop. A literal path segment under /loops rather than a surface of its own, because a saved
-    // loop is not a different feature — it is the same loop with its goal left blank until somebody types one.
+    // loop is not a different feature, it is the same loop with its goal left blank until somebody types one.
     designs: oc.route({ method: "GET", path: "/loops/designs" }).output(LoopDesignsListSchema),
     /* Create or replace a saved loop, with the operation explicit so a name collision cannot turn a create into
-     * a replacement. Refuses a design that could never finish — nothing to produce and nothing to check — with
+     * a replacement. Refuses a design that could never finish, nothing to produce and nothing to check, with
      * the same sentence `start` refuses an ad-hoc loop for, because it is the same mistake made earlier and
      * catching it at save time is the whole advantage of saving. */
     saveDesign: oc.route({ method: "POST", path: "/loops/designs" }).input(LoopDesignSaveSchema).output(LoopDesignSchema),

package/src/contracts/personas.contract.ts

@@ -13,12 +13,12 @@ import {
 
 /* The sandbox's named personas (PersonaSchema): which connected accounts each one speaks for, what a session
  * wearing it may do, where it works, and what it is told. The card half is a plain three-verb CRUD with no apply
- * step, because a card provisions NOTHING — unlike a capability, saving one connects nothing, installs nothing
+ * step, because a card provisions NOTHING, unlike a capability, saving one connects nothing, installs nothing
  * and spends nothing. It records a decision about accounts that already exist.
  *
  * The file behind it is committed workspace config (personas/personas-store.ts), so these routes are one of
  * two equally supported ways to edit them: this, and opening the file in the editor like any other project
- * config. Neither is the "real" one — which is why `save` is a whole-card upsert rather than a field patch, so
+ * config. Neither is the "real" one, which is why `save` is a whole-card upsert rather than a field patch, so
  * a round trip through the UI leaves a diff a reviewer would recognise.
  *
  * THE KIT ROUTES BELOW EDIT FILES, not the card, and they are here rather than on the skills contract because
@@ -30,14 +30,14 @@ import {
  * a save that shipped the whole folder would make an edit to one skill capable of deleting another. */
 export const personasContract = {
     list: oc.route({ method: "GET", path: "/personas" }).output(PersonasListSchema),
-    // Upsert by id — re-saving the same id edits that card.
+    // Upsert by id, re-saving the same id edits that card.
     save: oc.route({ method: "POST", path: "/personas" }).input(PersonaSchema).output(OkSchema),
     /* Removing a card takes away a persona, never an account: the login it named stays connected and reachable from
-     * every other surface. What it CAN do is orphan a reference — an automation pinned to this id now names a
-     * card that no longer exists — and the resolver reads that as "no accounts at all" rather than "all of
+     * every other surface. What it CAN do is orphan a reference, an automation pinned to this id now names a
+     * card that no longer exists, and the resolver reads that as "no accounts at all" rather than "all of
      * them", so the automation goes quiet instead of posting as somebody unintended. */
     /* Removing a card takes away a persona, never an account: the login it named stays connected and reachable from
-     * every other surface. It DOES take the card's kit with it — a folder no card can reach is a folder no list
+     * every other surface. It DOES take the card's kit with it, a folder no card can reach is a folder no list
      * shows, and leaving the owner's prompt and skills orphaned on disk is worse than deleting what they just
      * asked to delete. */
     remove: oc.route({ method: "DELETE", path: "/personas/{id}" }).input(PersonaIdParamSchema).output(OkSchema),
@@ -46,10 +46,10 @@ export const personasContract = {
 
     kit: oc.route({ method: "GET", path: "/personas/{id}/kit" }).input(PersonaIdParamSchema).output(PersonaKitSchema),
     // An empty prompt DELETES the file rather than storing a blank one, so "custom with nothing written" is one
-    // state instead of two — the resolver falls back to the sandbox's prompt for it (personas.ts personaPrompt).
+    // state instead of two, the resolver falls back to the sandbox's prompt for it (personas.ts personaPrompt).
     savePrompt: oc.route({ method: "POST", path: "/personas/{id}/prompt" }).input(PersonaPromptSchema).output(OkSchema),
     readSkill: oc.route({ method: "GET", path: "/personas/{id}/skills/read" }).input(PersonaSkillNameSchema).output(PersonaSkillBodySchema),
-    // Upsert by name, like the sandbox's own skills — and with no enabled list to write, because a kit skill is
+    // Upsert by name, like the sandbox's own skills, and with no enabled list to write, because a kit skill is
     // on exactly when its persona is worn. That is what "specific to that persona" has to mean.
     saveSkill: oc.route({ method: "POST", path: "/personas/{id}/skills" }).input(PersonaSkillSchema).output(OkSchema),
     removeSkill: oc.route({ method: "POST", path: "/personas/{id}/skills/remove" }).input(PersonaSkillNameSchema).output(OkSchema),

package/src/contracts/ports.contract.ts

@@ -2,7 +2,7 @@ import { oc } from "@orpc/contract";
 import { OkSchema, PortForwardResultSchema, PortParamSchema, PortsListSchema } from "../schemas.js";
 
 // Listening TCP ports in the sandbox + explicit forwarding through the preview proxy (see the ports section in
-// schemas.ts). `forward` is idempotent — re-forwarding a port returns its existing slot's URL; `unforward`
+// schemas.ts). `forward` is idempotent, re-forwarding a port returns its existing slot's URL; `unforward`
 // frees the slot immediately (the hostname keeps resolving, the proxy just stops mapping it).
 export const portsContract = {
     list: oc.route({ method: "GET", path: "/ports" }).output(PortsListSchema),

package/src/contracts/prepush.contract.ts

@@ -1,11 +1,11 @@
 import { oc } from "@orpc/contract";
 import { OkSchema, PrepushRunSchema } from "../schemas.js";
 
-// The pre-push check — the command the workspace runs when the user pushes, before anything leaves the machine
+// The pre-push check, the command the workspace runs when the user pushes, before anything leaves the machine
 // (see PrepushRunSchema for where this sits and why). Three verbs about ONE run: the check answers about the
 // main working tree, of which there is exactly one, so nothing here is addressed by id.
 //
-// `run` starts the check and returns immediately — a suite takes minutes, and an oRPC call held open for one
+// `run` starts the check and returns immediately, a suite takes minutes, and an oRPC call held open for one
 // would die on the first proxy timeout with the work still going. The dialog that started it polls `state` for
 // the verdict, and opens the terminals panel on the `session` the first answer names: the suite runs in a real
 // tmux window, so watching it is the terminal's job. `cancel` kills that window; the run settles as `cancelled`

package/src/contracts/providers.contract.ts

@@ -3,21 +3,21 @@ import { ModelsSchema, NativeProviderParamSchema } from "../schemas.js";
 
 // EVERY NATIVE PROVIDER'S PICKER CATALOG, ON ONE ROUTE.
 //
-// There were five of these — /claude/models, /codex/models, /grok/models, /kimi/models, /gemini/models — one per
+// There were five of these: /claude/models, /codex/models, /grok/models, /kimi/models, /gemini/models, one per
 // provider, each a contract entry, a route factory and a service field wired separately. They differed in
 // nothing: same method, same output schema, same "the daemon's catalog for this provider, never empty". Three of
 // the five route files were the same fifteen lines with a name swapped, and the daemon paid for that shape twice
 // more in the branch chains that had to fan back out over the providers to ask them all the same question.
 //
-// So the provider is a PARAMETER, not five routes. Adding one is a row in the daemon's catalog registry — the
-// same discipline the adapter registry already applies to serving a turn — rather than a vertical slice through
+// So the provider is a PARAMETER, not five routes. Adding one is a row in the daemon's catalog registry, the
+// same discipline the adapter registry already applies to serving a turn, rather than a vertical slice through
 // the contract, the router, the service container and every test double.
 //
 // Endpoints keep their own route (endpoints.contract.ts) and should: they are user-created and unbounded, their
 // id names a capability that may not exist, and a missing one is a NOT_FOUND rather than an empty catalog. That
 // is a different question with a different failure, not a sixth provider.
 export const providersContract = {
-    // One provider's models (+ its default id), never empty — live discovery with a persisted/seed floor behind
+    // One provider's models (+ its default id), never empty, live discovery with a persisted/seed floor behind
     // it. Order is the provider's own preference order and is not re-ranked here; see ModelsSchema.
     models: oc.route({ method: "GET", path: "/providers/{provider}/models" }).input(NativeProviderParamSchema).output(ModelsSchema),
 };

package/src/contracts/public.contract.ts

@@ -1,7 +1,7 @@
 import { oc } from "@orpc/contract";
 import { OkSchema, PublicListSchema, PublishResultSchema, PublishSchema, UnpublishSchema } from "../schemas.js";
 
-// The workspace outbox — what `public/` currently holds and its address (see the public section in schemas.ts).
+// The workspace outbox, what `public/` currently holds and its address (see the public section in schemas.ts).
 // `publish` copies a workspace file or directory in, creating the outbox if this is the first one; `unpublish`
 // withdraws one and removes the outbox behind the last, so the directory's presence always means exactly "there
 // is something published". There is no route to READ a published file: that is the whole point of the

package/src/contracts/push.contract.ts

@@ -5,10 +5,10 @@ import { OkSchema, PushChannelIdSchema, PushChannelSchema, PushConfigQuerySchema
 // push/push-store.ts for why the key lives on the history volume), and sends on the three moments where the
 // operator's attention is genuinely wanted: a turn finished, the agent is blocked on an answer, and an
 // automation is waiting for approval. A channel is either a browser's web-push subscription or a native
-// install reached through the platform's push relay — see PushChannelSchema for the split and why.
+// install reached through the platform's push relay, see PushChannelSchema for the split and why.
 //
 // `test` exists because a notification pipeline has four independent failure points the user cannot inspect
-// (device permission, service-worker or shell registration, the daemon's key, the push service itself) — a
+// (device permission, service-worker or shell registration, the daemon's key, the push service itself), a
 // button that proves the whole chain end-to-end is worth more than any amount of status rendering.
 export const pushContract = {
     config: oc.route({ method: "GET", path: "/push/config" }).input(PushConfigQuerySchema).output(PushConfigSchema),

package/src/contracts/secrets.contract.ts

@@ -2,9 +2,9 @@ import { oc } from "@orpc/contract";
 import { OkSchema, SecretInventorySchema, SecretKeyParamSchema, SecretKeysSchema, SecretRevealSchema, SecretSetSchema } from "../schemas.js";
 
 // User-supplied env-var secrets, written to the sandbox's gitignored desired-state/.env (which
-// `apply` reloads each run — no restart). `set` upserts one KEY=value, `remove` deletes it; `list` returns the
+// `apply` reloads each run, no restart). `set` upserts one KEY=value, `remove` deletes it; `list` returns the
 // keys present. `inventory` aggregates every secret store into one view (keys + status + provenance, never
-// values). `reveal` is the single value-returning route — owner-only, POST so the key never sits in a URL.
+// values). `reveal` is the single value-returning route, owner-only, POST so the key never sits in a URL.
 // set/remove/list/reveal refuse until DevOps has scaffolded the desired-state repo; inventory always answers.
 export const secretsContract = {
     set: oc.route({ method: "POST", path: "/secrets" }).input(SecretSetSchema).output(OkSchema),

package/src/contracts/sessions.contract.ts

@@ -3,12 +3,12 @@ import { z } from "zod";
 import { SessionTranscriptSchema } from "../events.js";
 import { SessionIdParamSchema, SessionsListSchema } from "../schemas.js";
 
-// Past conversations in this workspace (the SDK-native session store, keyed on the working dir — which for a
+// Past conversations in this workspace (the SDK-native session store, keyed on the working dir, which for a
 // repo covers its linked worktrees too, so an isolated conversation's transcript is reachable from the
 // workspace root). `list` returns summaries for the history menu (filtered by `query` when the search box is
 // used); `get` restores one transcript for display.
 //
-// `caseSensitive` is the filter's Aa switch, on the same terms as the fleet search's — off means the letters do
+// `caseSensitive` is the filter's Aa switch, on the same terms as the fleet search's, off means the letters do
 // not matter, and the two routes answer one query together (the board lists these rows under its own cards), so
 // a switch either of them ignored would show as one field returning two different match sets.
 export const sessionsContract = {

package/src/contracts/settings.contract.ts

@@ -11,10 +11,10 @@ import {
 
 // Per-sandbox agent settings (.intentic/config/settings.json). `get` returns the current flags with defaults applied
 // when the file is absent; `set` overwrites them. `savings` reports what each token-reduction mechanism was
-// worth — the cleaners' realized per-command savings and the terse steer's measured A/B — over an inclusive
+// worth, the cleaners' realized per-command savings and the terse steer's measured A/B, over an inclusive
 // UTC day window, the same one the spend ledger takes, so a screen can filter both with one calendar.
-// `builtinPrompt` returns one of the two built-in system prompts as text — Intentic's own, or Claude Code's
-// read out of the installed CLI — so the settings page can SHOW the prompt behind a mode instead of asking the
+// `builtinPrompt` returns one of the two built-in system prompts as text. Intentic's own, or Claude Code's
+// read out of the installed CLI, so the settings page can SHOW the prompt behind a mode instead of asking the
 // user to trust a description of it, and can fork either into a custom one.
 export const settingsContract = {
     get: oc.route({ method: "GET", path: "/settings" }).output(SandboxSettingsSchema),

package/src/contracts/share.contract.ts

@@ -8,7 +8,7 @@ import { OkSchema, ShareCreateSchema, ShareListSchema, ShareRemoveSchema, ShareU
  * share takes a CONVERSATION ID and renders something that did not exist as a file until it was asked for.
  * Folding them together would have `publish` accept two unrelated kinds of input distinguished by a flag.
  *
- * There is no route to read a share back. The page is the read — it answers on the unauthenticated
+ * There is no route to read a share back. The page is the read, it answers on the unauthenticated
  * `public-<slot>` hostname like every other published file, which is the point of having made one. */
 export const shareContract = {
     list: oc.route({ method: "GET", path: "/share" }).output(ShareListSchema),

package/src/contracts/skills.contract.ts

@@ -7,7 +7,7 @@ import { OkSchema, SkillBodySchema, SkillDraftSchema, SkillIdSchema, SkillRemove
  * the settings file: the rest are the owner's own skill store, the plugin checkouts a capability cloned, and the
  * skills folders inside installed extensions. `list` is the join of all four (skill-inventory.ts).
  *
- * The ENABLED half still rides the settings object's `skills` array — that array is what the reconciler
+ * The ENABLED half still rides the settings object's `skills` array, that array is what the reconciler
  * converges and what the boot path already reads, so a switch on this list is an ordinary settings write and
  * there is exactly one place that decides which skills exist on disk. `save` and `remove` write the text AND
  * that array together, which is why they are here rather than being two calls a screen has to sequence.
@@ -18,7 +18,7 @@ export const skillsContract = {
     list: oc.route({ method: "GET", path: "/skills" }).output(SkillsListSchema),
     read: oc.route({ method: "GET", path: "/skills/read" }).input(SkillIdSchema).output(SkillBodySchema),
     // Upsert by name: saving over an existing skill rewrites it, which is also how one is renamed (the old name
-    // is a different skill and is deleted on its own). A saved skill is switched ON — you wrote it to use it.
+    // is a different skill and is deleted on its own). A saved skill is switched ON, you wrote it to use it.
     save: oc.route({ method: "POST", path: "/skills" }).input(SkillDraftSchema).output(OkSchema),
     remove: oc.route({ method: "POST", path: "/skills/remove" }).input(SkillRemoveSchema).output(OkSchema),
 };