@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/contracts/system.contract.ts

@@ -1,6 +1,7 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
-import { SessionTranscriptSchema, SystemEventSchema } from "../events.js";
+import { SessionTranscriptSchema } from "../events/transcript.js";
+import { SystemEventSchema } from "../events/system-events.js";
 import {
     DeviceAgentFlowInputSchema,
     DeviceCommandInputSchema,
@@ -10,7 +11,7 @@ import {
 } from "../schemas/devices.js";
 import { PresenceReportSchema } from "../schemas/logs.js";
 import { OkSchema } from "../schemas/shared.js";
-import { DaemonSessionSchema, InfoSchema, ManifestProblemsSchema } from "../schemas/system.js";
+import { DaemonSessionSchema, InfoSchema, ManifestProblemsSchema, ManifestRepairSchema } from "../schemas/system.js";
 import {
     BrowserNameParamSchema,
     BrowsersListSchema,
@@ -23,11 +24,9 @@ import {
 } from "../schemas/terminal.js";
 import { UsageSummarySchema } from "../schemas/usage.js";
 
-// Sandbox status + identity, the long-lived liveness stream, and the connect-token-relayed host tunnel.
-// `events` interleaves heartbeat frames (browser holds it open to detect the sandbox dying instantly) with
-// workspaceChanged batches (live file tree/viewer refresh) and presence roster snapshots until the request
-// aborts. `clientId` is the tab's per-connection presence key; absent (an older web client) means the
-// connection simply never joins the roster.
+// Sandbox status/identity, the long-lived liveness stream, and the connect-token-relayed host tunnel. `events`
+// interleaves heartbeats, workspaceChanged batches and presence snapshots until the request aborts. `clientId` is this
+// tab's presence key; omitting it means never joining the roster.
 export const systemContract = {
     info: oc
         .route({
@@ -38,9 +37,7 @@ export const systemContract = {
                 "The sandbox's own identity and state: which workspace it holds, which image it runs, what it is called, and the list of calls it actually implements. Start here, because a browser is routinely newer than the sandbox it is talking to and this is how it finds out what is there.",
         })
         .output(InfoSchema),
-    // What the daemon could not read in its own `.intentic/` manifests, a file it fell back on, a key it did
-    // not recognise, an entry it skipped. Its own route rather than a field on /info because it is invalidated
-    // by a different thing: a manifest changing on disk, which the workspace-state table already broadcasts.
+    // Own route, not a field on /info: it goes stale on a manifest changing on disk, not on identity changing.
     manifestProblems: oc
         .route({
             method: "GET",
@@ -50,8 +47,18 @@ export const systemContract = {
                 "Anything the daemon tripped over in its own configuration on disk: a file it had to fall back from, a key it did not recognise, an entry it skipped. Separate from the identity call because it goes stale for a different reason, namely a file changing.",
         })
         .output(ManifestProblemsSchema),
-    // Exchange the request's verified bearer (a Google ID token, or a still-valid session, which makes this
-    // route sliding renewal) for a daemon-minted session, the credential every steady-state call presents.
+    // Removes or renames only a key, never a value; writes queue through the owning store, not racing a live save.
+    repairManifest: oc
+        .route({
+            method: "POST",
+            path: "/system/manifest-problems/repair",
+            summary: "Take a stray setting out of a file",
+            description:
+                "Removes a key the sandbox does not recognise from one of its settings files, or renames it to the one it was probably meant to be, keeping the value. Only the files a person hand-edits can be named, and only a key — never a value — so this can only ever remove something already being ignored. Renaming onto a key the file already has is refused instead of overwriting it.",
+        })
+        .input(ManifestRepairSchema)
+        .output(OkSchema),
+    // Trades a verified bearer or unexpired session for a fresh daemon session; calling it again renews it.
     session: oc
         .route({
             method: "POST",
@@ -91,10 +98,7 @@ export const systemContract = {
             description: "Token and cost totals per account, added up from the record of every finished turn.",
         })
         .output(UsageSummarySchema),
-    // The web-owned tmux sessions behind the terminal tabs. `terminals` enumerates them (the panel rebuilds a tab
-    // per name on load/reload); `killTerminal` destroys one when its tab's close button is clicked. The live I/O
-    // is the separate /system/terminal WebSocket, these are just the control plane. Bearer-authed like the rest
-    // (browser fetch sends the header), unlike the header-less WS route which app.ts exempts.
+    // Control plane only; live I/O is /system/terminal WebSocket, exempt from the Bearer auth these routes take.
     terminals: oc
         .route({
             method: "GET",
@@ -113,9 +117,7 @@ export const systemContract = {
         })
         .input(TerminalNameParamSchema)
         .output(OkSchema),
-    // One session's pane history as selectable text, the answer to "scroll back and copy that" in a surface
-    // whose live view is a tmux client on the alternate screen, where the scrollback is on the far side of the
-    // socket and the page has nothing to select. See TerminalScrollbackSchema.
+    // Scrollback as selectable text; the live view is a tmux alternate screen, with nothing in the page to select.
     terminalScrollback: oc
         .route({
             method: "GET",
@@ -126,11 +128,7 @@ export const systemContract = {
         })
         .input(TerminalScrollbackQuerySchema)
         .output(TerminalScrollbackSchema),
-    // The agent's live Chromiums and the pages each has open, the Browsers view's roster, polled while it is on
-    // screen and by the rail so its tile can appear the moment a turn starts browsing. The frames are the
-    // separate /system/browser-view WebSocket; this is the control plane, exactly as `terminals` is for tmux.
-    // `closeBrowser` shuts one Chromium down: the agent's next browser tool call then fails as if it had crashed,
-    // which is the honest account of the owner pulling the plug.
+    // Control plane like `terminals`; frames stream separately. `closeBrowser` fails the next call as crashed.
     browsers: oc
         .route({
             method: "GET",
@@ -150,13 +148,7 @@ export const systemContract = {
         })
         .input(BrowserNameParamSchema)
         .output(OkSchema),
-    // The agents this sandbox's agents started. SDK subagents and delegated Codex/Grok runs alike (see
-    // SubagentSessionSchema). Same two-route shape as the browsers above, and same division of labour: the list
-    // is polled by the Subagents area while it is on screen and loosely by the rail, so its tile can appear the
-    // moment a turn delegates. There is no third WebSocket here, because a subagent has no byte stream to watch,
-    // what you watch it through is its TRANSCRIPT, which `subagentTranscript` serves in the one shape every
-    // other transcript route already answers in: live from the parent turn's frame log while it runs, off the
-    // provider's own store once it has finished.
+    // SDK subagents and delegated runs alike; watched via transcript, not a socket, live then from stored history.
     subagents: oc
         .route({
             method: "GET",
@@ -176,13 +168,7 @@ export const systemContract = {
         })
         .input(SubagentIdParamSchema)
         .output(SessionTranscriptSchema),
-    /* Start, stop, restart, update, rebuild, roll back or remove a sandbox on one of the user's own devices,
-     * the Devices view's buttons, relayed to the machine over the socket it holds open to us.
-     *
-     * Streamed because the slowest of these takes minutes, and it is the same stream whatever the op: one door
-     * for one decision, so the view has one shape to render rather than one per duration. The daemon adds no
-     * judgement, the machine enforces its own switches and its refusal arrives as the terminal `error` line,
-     * in its own words, naming the control to flip. */
+    // One stream for every op; the daemon adds no judgment, a refusal is the machine's own `error` line.
     manageDeviceSandbox: oc
         .route({
             method: "POST",
@@ -193,12 +179,7 @@ export const systemContract = {
         })
         .input(DeviceSandboxFlowInputSchema)
         .output(eventIterator(DeviceFlowLineSchema)),
-    /* Run one of this product's own CLI actions on a connected device, from a button rather than through an
-     * agent. A closed set of names, and the daemon builds the command line from the name (see the schema): the
-     * browser never sends one, because the socket underneath also carries `run_command`.
-     *
-     * Not a stream, unlike the sandbox ops beside it: these are seconds-long CLI calls whose whole answer is the
-     * sentence they print at the end, and a stream for that is a shape with nothing to put in it. */
+    // Closed set of actions; the daemon builds the command line, not the caller. One sentence is the whole answer.
     runDeviceCommand: oc
         .route({
             method: "POST",
@@ -209,14 +190,7 @@ export const systemContract = {
         })
         .input(DeviceCommandInputSchema)
         .output(DeviceCommandResultSchema),
-    /* Update or restart the agent on one of the user's own devices — the remedy the Devices view used to print
-     * as a command to go and type, on the view built to replace that terminal.
-     *
-     * Streamed like the sandbox ops, and for a reason of its own: this is the one call whose transport the work
-     * destroys. Both ops stop the resident process holding the socket, so the stream ends WITHOUT a terminal
-     * frame in the ordinary, successful case, and callers must read that as "it started" rather than as a
-     * failure (DeviceAgentFlowSchema has the whole argument). The confirmation is the device's agent version
-     * moving on the next read of the fleet. */
+    // The stream usually ends without a frame; a bare stop means success, the device's version confirms it later.
     runDeviceAgentFlow: oc
         .route({
             method: "POST",

package/src/contracts/usage.contract.ts

@@ -3,18 +3,13 @@ import { z } from "zod";
 import { LimitResetClaimSchema, LimitResetStatusSchema } from "../schemas/plan-limits.js";
 import { DayWindowQuerySchema, UsageRollupSchema } from "../schemas/usage.js";
 
-// The one control over the headroom readings a person has: measure again, now, every connection. `force`
-// ignores the freshness the daemon otherwise honours (a reading from the last minute is what the provider
-// would answer again), because the person pressing it has just changed something about an account and is
-// asking whether what they can see survived it.
+// `force` ignores the daemon's freshness window and measures now instead of reusing a recent reading.
 export const RefreshPlanLimitsSchema = z.object({
     force: z.boolean().default(false).describe("Measure again even if a reading was taken a moment ago."),
 });
 
-// The durable spend ledger (see UsageTurnSchema). Read-only over the wire, rows are appended daemon-side at
-// turn end, so the ledger stays a trustworthy record of what was actually spent, the same principle as the
-// activity log. `rollup` serves every cost/usage panel: it groups by day × provider × account × model, and the
-// browser re-projects from there (spend per day, cost by model, cache hit rate) without another round trip.
+// Durable spend ledger, read-only over the wire; rows are appended daemon-side at turn end.
+// `rollup` groups by day, provider, account and model, so every cost panel re-projects from this one answer.
 export const usageContract = {
     rollup: oc
         .route({
@@ -26,9 +21,7 @@ export const usageContract = {
         })
         .input(DayWindowQuerySchema)
         .output(UsageRollupSchema),
-    // Not the ledger's business, but the same tab: the plan-limit readings behind every ring, re-measured on
-    // request for every provider at once. The readings themselves arrive on /events as they land, and on the
-    // account lists afterwards; this answers once the sweep is done or its deadline passes.
+    // Re-measures every account's plan limits on request; readings also arrive via /events and account lists otherwise.
     refreshPlanLimits: oc
         .route({
             method: "POST",
@@ -39,16 +32,9 @@ export const usageContract = {
         })
         .input(RefreshPlanLimitsSchema)
         .output(z.object({ ok: z.literal(true) })),
-    /* THE WAY PAST A SPENT SESSION WINDOW THAT ISN'T WAITING (LimitResetStatusSchema has what it costs).
-     *
-     * ASKED, NOT POLLED, and that is the whole reason it is a route of its own rather than another field on the
-     * account list. The provider only evaluates it when told the account is at the wall, so asking is a claim
-     * about the account's state; asking on every headroom sweep, for every connection, would be that claim made
-     * continuously and falsely. It is asked at the one moment it is true — a refused turn, with its strip on
-     * screen — and the answer is worth nothing a moment later, so nothing caches it.
-     *
-     * Answers `available: false` rather than failing for an account with no such mechanism, so a caller can ask
-     * about any account it holds without first knowing which provider grants one. */
+    // Asked, not polled: the provider only evaluates this when told the account is at the wall, and the answer isn't
+    // cached.
+    // Answers `available: false` rather than failing when the account has no such mechanism.
     limitReset: oc
         .route({
             method: "GET",

package/src/contracts/vpn.contract.ts

@@ -1,18 +1,14 @@
 import { eventIterator, oc } from "@orpc/contract";
-import { IntenticLineSchema } from "../events.js";
+import { IntenticLineSchema } from "../events/system-events.js";
 import { OkSchema } from "../schemas/shared.js";
 import { ForticlientImportInputSchema, ForticlientImportSchema, VpnConnectInputSchema, VpnIdParamSchema, VpnListSchema } from "../schemas/vpn.js";
 
-// The live VPN surface. A VPN is ADDED as a `vpn` capability (credentials, autoConnect, capabilities.contract);
-// it is DIALLED here. The split is deliberate: connecting is a runtime operation that both the operator (the
-// VPN capability card) and the agent (`vpn` on its PATH, which calls these very routes) perform many times
-// over one stored connection, so it cannot be a capability re-add, and its result is richer than a
-// CapabilityStatus, which is why `list` returns VpnLinks instead of {state, detail}.
-//
-// Every route reads tunnel state back from the OS rather than from daemon memory, so the agent dropping a
-// tunnel from a shell and the UI dropping it are the same event, and a daemon restart observes the truth.
+// A VPN is added as a `vpn` capability; connecting and dropping it happen through the routes here, called by both the
+// operator UI and the agent's `vpn` CLI.
+// Every route reads tunnel state from the OS, not daemon memory, so a shell-dropped tunnel and a UI-dropped one are the
+// same event across a restart.
 export const vpnContract = {
-    // Every configured VPN with its live link state, the VPN card, the rail indicator, and `vpn list`.
+    // Every configured VPN with its live link state; feeds the VPN card, rail indicator, and `vpn list`.
     list: oc
         .route({
             method: "GET",
@@ -22,9 +18,7 @@ export const vpnContract = {
                 "Every stored VPN with its live link state, read back from the operating system rather than from memory, so a tunnel dropped from a shell and one dropped from a screen look the same here.",
         })
         .output(VpnListSchema),
-    // Dial a stored VPN. Streams the client's progress (auth, then routing) because a dial takes seconds and
-    // can fail with something the user must read, a wrong password, an untrusted gateway certificate, or a
-    // required 2FA code. Idempotent: connecting an already-up tunnel reports it and stops.
+    // Dials a stored VPN, streaming auth and routing progress; idempotent, an already-up tunnel is just reported.
     connect: oc
         .route({
             method: "POST",
@@ -35,7 +29,7 @@ export const vpnContract = {
         })
         .input(VpnConnectInputSchema)
         .output(eventIterator(IntenticLineSchema)),
-    // Drop a tunnel. Tolerates an already-down one, "make it not be up" is the contract, not "it was up".
+    // Drops a tunnel; tolerates one already down, since the contract is "not up," not "it was up."
     disconnect: oc
         .route({
             method: "POST",
@@ -45,8 +39,7 @@ export const vpnContract = {
         })
         .input(VpnIdParamSchema)
         .output(OkSchema),
-    // Parse an exported FortiClient configuration into addable connections, so a user with that file fills the
-    // add form by picking a connection instead of re-keying host/port/protocol per tunnel.
+    // Parses an exported FortiClient config into addable connections a user can pick instead of retyping.
     importForticlient: oc
         .route({
             method: "POST",

package/src/contracts/webext.contract.ts

@@ -4,34 +4,18 @@ import { WebExtScopesSchema } from "../schemas/capabilities.js";
 import { OkSchema } from "../schemas/shared.js";
 import { WebExtFactsSchema } from "../schemas/webext.js";
 
-/* What a connected BROWSER can be asked, over the socket its extension opened to this sandbox.
- *
- * The inversion is the host contract's (contracts/host.contract.ts): the extension dialled out, and the
- * extension is the oRPC SERVER. A browser cannot be dialled — it is behind the same NAT as the laptop it runs
- * on, and it is not even a process that is always there — so it can only be the side that connects, while
- * everything is asked OF it.
- *
- * `mcp` IS THE SAME DELIBERATE HOLE IN THE TYPING, for the same reason: if this contract described each tool,
- * a browser could not learn one without a matching daemon release, and the daemon would have to hold every
- * tool's schema to translate. Keeping one opaque procedure buys the extension the Chrome Web Store's release
- * cycle, which is measured in review days and is not this daemon's to wait on. The payload is still validated
- * where it is understood: in the extension, against the tool's own schema.
- *
- * There is no `runSandboxFlow` twin here. A browser runs nothing that takes minutes and narrates itself; every
- * one of its operations is a click or a read that either happened or did not. */
+// What a connected browser can be asked, over the socket its extension opened; the extension is the oRPC server here,
+// inverted from host.contract.ts, since a browser cannot be dialled.
+// `mcp` stays one opaque procedure so a browser can gain a tool without a matching daemon release; the payload is
+// validated in the extension against the tool's own schema.
+// No `runSandboxFlow` twin: every browser operation is a click or read that either happened or did not.
 export const webextContract = {
-    // What this browser is, and what it is currently allowed to touch: pulled right after the socket
-    // authenticates and again whenever the card is read, because the grant list changes IN THE BROWSER (the
-    // person clicks Allow on a site) rather than here, so a cached copy would be a card that lies.
+    // Refetched on connect and each card read, never cached: the grant list changes in the browser, not here.
     describe: oc.output(WebExtFactsSchema),
-    /* The switches the owner ticked on the capability card. The extension ENFORCES them; nothing on this side
-     * checks one. Note what is NOT in here: which sites the agent may touch. Those are Chrome's own optional
-     * host permissions, granted by the person in the browser and revocable there, so the strongest boundary in
-     * this feature is one the sandbox cannot even describe, let alone widen. */
+    // Enforced by the extension, not checked here; site access is a separate, browser-granted permission.
     setScopes: oc.input(WebExtScopesSchema).output(OkSchema),
-    // Liveness, driven by the daemon: doubles as the keepalive for the tunnel and as the probe whose failure
-    // means the browser is closed rather than quiet.
+    // Doubles as the tunnel keepalive; failure means the browser closed, not that it's merely 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 forwarded verbatim in both directions; kept opaque, not typed per tool.
     mcp: oc.input(z.unknown()).output(z.unknown()),
 };

package/src/contracts/workflows.contract.ts

@@ -1,5 +1,5 @@
 import { oc } from "@orpc/contract";
-import { OkSchema } from "../schemas/shared.js";
+import { DoorTokenSchema, OkSchema } from "../schemas/shared.js";
 import {
     WorkflowIdParamSchema,
     WorkflowRunIdParamSchema,
@@ -7,25 +7,16 @@ import {
     WorkflowRunsListSchema,
     WorkflowRunStartSchema,
     WorkflowSaveSchema,
-    WorkflowSchema,
     WorkflowsListSchema,
+    WorkflowSavedSchema,
 } from "../schemas/workflows.js";
 
-/* The workflow routes, "run these sessions, in this order, each handing its result to the next".
- *
- * SPLIT LIKE AUTOMATIONS, NOT LIKE LOOPS, and the split says what a workflow is. A loop has no editor because
- * it is started against a conversation and then it is history; a workflow is a DESIGN, a thing the user
- * authors once, keeps, edits, and runs repeatedly, so it gets the manifest treatment: create/update, delete,
- * list. What it does not get is an `enabled` toggle, because nothing fires it on its own: a workflow runs when
- * somebody (or an automation's prompt) says run it.
- *
- * `run` acks with the run as recorded and executes detached, the contract every turn-starting route here
- * keeps. The first step alone can take minutes and the run may take hours; the run view is where it is watched,
- * and the fleet board shows its steps as the ordinary agents they are.
- */
+// Workflow routes: run these sessions in order, each handing its result to the next. Manifest treatment (create/update,
+// delete, list), like automations not loops, since a workflow is authored once and run repeatedly.
+// No `enabled` toggle: nothing fires a workflow on its own, only an explicit run.
+// `run` acks with the run as recorded and executes detached, the same contract every turn-starting route here keeps.
 export const workflowsContract = {
-    // Every saved workflow with its run history, newest run first. One route rather than two because the list
-    // page shows both and a workflow with no runs is the interesting case, not an error.
+    // Every saved workflow with its run history, newest first; a never-run workflow isn't an error case.
     list: oc
         .route({
             method: "GET",
@@ -35,11 +26,9 @@ export const workflowsContract = {
                 "Every workflow somebody has designed, each with its own run history, newest first. One answer rather than two, because a workflow that has never been run is the interesting case rather than a mistake.",
         })
         .output(WorkflowsListSchema),
-    /* Create or replace a workflow, with the operation made explicit so an accidental id collision cannot turn
-     * a create into replacement. Refuses a graph that cannot run, a cycle, a `needs` naming a step
-     * that is not there, a step with no way to know it is finished, with the same sentences the designer shows
-     * while you type (see workflowFaults). Validation lives in the contract precisely so those two can never
-     * disagree about what is legal. */
+    // Create or replace, with the operation explicit so an id collision can't turn a create into an overwrite.
+    // Refuses a graph that can't run (a cycle, an unmet `needs`, a step with no completion signal), in the same words
+    // the design-time validator (workflowFaults) uses.
     save: oc
         .route({
             method: "POST",
@@ -49,9 +38,19 @@ export const workflowsContract = {
                 "Writes a workflow design. Say which of the two you mean, so an id that happens to collide cannot silently overwrite somebody's work. A design that could never run is refused, in the same words the editor shows while you type: a loop in the steps, a step waiting on one that is not there, a step with no way of knowing it is finished.",
         })
         .input(WorkflowSaveSchema)
-        .output(WorkflowSchema),
-    // Deleting a workflow does NOT stop a run of it that is in flight, and does not delete its history: the run
-    // snapshotted its definition when it started, so it stays readable and stays stoppable.
+        .output(WorkflowSavedSchema),
+    // Mints a new gate credential; every pipeline holding the old URL stops working the moment this answers.
+    rotateGateToken: oc
+        .route({
+            method: "POST",
+            path: "/workflows/{id}/gate/rotate",
+            summary: "Rotate a release gate's token",
+            description:
+                "Mints a new credential for the workflow's release gate and retires the old one at once. Every pipeline wired to the gate has to be handed the new URL. Refused for a workflow that declares no gate.",
+        })
+        .input(WorkflowIdParamSchema)
+        .output(DoorTokenSchema),
+    // Deleting a workflow doesn't stop or erase an in-flight run: a run snapshots its definition at start.
     remove: oc
         .route({
             method: "DELETE",
@@ -62,11 +61,9 @@ export const workflowsContract = {
         })
         .input(WorkflowIdParamSchema)
         .output(OkSchema),
-    /* Start a run, optionally pointed at a request, the sentence the user typed in the composer, which every
-     * step is handed on top of its own prompt. Every step is recorded `pending` up front, so the graph is
-     * complete from the first frame and a missing node never has to mean two things. Several runs of one
-     * workflow may be in flight at once, they derive different conversation ids, so nothing is shared and
-     * nothing can collide, which is what makes "run this design again on a different question" free. */
+    // Starts a run, optionally with a request appended to every step's own prompt; each step is recorded `pending` up
+    // front so the graph is complete from the first frame.
+    // Multiple runs of one workflow can be in flight at once; each derives its own conversation ids, so none collide.
     run: oc
         .route({
             method: "POST",
@@ -77,8 +74,7 @@ export const workflowsContract = {
         })
         .input(WorkflowRunStartSchema)
         .output(WorkflowRunSchema),
-    // Every run across every workflow, newest first, the history the run view opens onto, and the only place a
-    // deleted workflow's runs are still reachable.
+    // Every run across every workflow, newest first; the only place a deleted workflow's runs are still reachable.
     runs: oc
         .route({
             method: "GET",
@@ -88,19 +84,9 @@ export const workflowsContract = {
                 "All runs across all workflows, newest first. This is also the only place the runs of a deleted workflow are still reachable.",
         })
         .output(WorkflowRunsListSchema),
-    /* Stop a run: nothing that has not started will start, and the steps in flight are CUT OFF where they
-     * are, their turns aborted exactly as /agent/stop aborts one, so whatever they had written stays on
-     * their branches and the step settles as stopped.
-     *
-     * Not the graceful "finish the iteration you are on" a LOOP's stop performs, and the difference is the
-     * unit: a loop's iteration is a round somebody is watching, a workflow step's is an entire agent turn.
-     * Waiting for one meant a stopped run kept working, kept spending and kept asking questions for minutes
-     * after the press, which is indistinguishable from a button that does nothing.
-     *
-     * IT ALWAYS ENDS THE RUN, including one no scheduler is behind, a record left `running` by a daemon that
-     * was replaced mid-flight. That case used to be refused, which made the stuck run permanent: a Stop that
-     * could not work, a step count that would never move, and no way off the board.
-     */
+    // Cuts off in-flight steps where they stand, aborting their turns like /agent/stop; not the graceful
+    // finish-the-iteration stop a loop performs, since a step is a whole agent turn.
+    // Always ends the run, including one left `running` by a daemon that was replaced mid-flight.
     stopRun: oc
         .route({
             method: "POST",
@@ -111,18 +97,9 @@ export const workflowsContract = {
         })
         .input(WorkflowRunIdParamSchema)
         .output(OkSchema),
-    /* Take an ENDED run off the board, the run's half of `agents.archive`, and the same bargain: nothing is
-     * lost, the checkouts are reclaimed, and `unarchiveRun` puts it all back. It needs an exit of its own
-     * because nothing about a run transitions once it is over, so a failed one would sit in Attention until
-     * fifty more had rolled it off the ledger. Refused while the run is going.
-     *
-     * IT ARCHIVES THE STEPS WITH THE RUN, which is what makes it an archive rather than a dismissal. A step
-     * has no card of its own, the run's row stands for it, so merely dropping the record released the run's
-     * conversations onto the board as loose cards at the exact moment the user said they were done with the
-     * job. Every step that ran is archived, on the same terms as pointing `agents.archive` at those ids: that
-     * route archives what the user named without re-litigating whether each one was ready to go, and a run the
-     * user has archived is exactly that gesture made once for the whole graph.
-     */
+    // Ends a run's board presence, the run's half of `agents.archive`: nothing is lost, checkouts are reclaimed, and
+    // `unarchiveRun` reverses it. Refused while the run is going.
+    // Archives every step that ran along with it, since a step has no card of its own; the run's row stands for it.
     archiveRun: oc
         .route({
             method: "POST",
@@ -133,8 +110,7 @@ export const workflowsContract = {
         })
         .input(WorkflowRunIdParamSchema)
         .output(OkSchema),
-    // Put an archived run and its sessions back on the board, the inverse of the above and the run's half of
-    // `agents.unarchive`.
+    // Inverse of archiveRun: puts an archived run and its sessions back on the board.
     unarchiveRun: oc
         .route({
             method: "POST",