@intentic/sandbox-contract 1.245.0 → 1.246.1

package/src/command-classes.ts

@@ -1,10 +1,12 @@
-import { type CommandClass, CommandClassSchema } from "./schemas/agent.js";
+import { HISTORY_ROOT, WORKSPACE_ROOT } from "@intentic/constants";
+import { type CommandClass, CommandClassSchema, type CommandLocus } from "./schemas/agent.js";
+import { inertRegions, isLive } from "./shell-regions.js";
 
 /* WHICH CLASSES A SHELL COMMAND FALLS IN, the classifier behind every command gate, read before the command runs.
  *
  * IT LIVES IN THE CONTRACT PACKAGE because there are TWO enforcement points and they must not drift. The
  * sandbox's own gate (sandbox/src/guard/command-gate.ts) judges what the agent types here; the machine agent's
- * shell tool (_computers/machine/src/computer/tools/shell.ts) judges what it sends to somebody's laptop. Those answer to
+ * shell tool (_devices/machine/src/device/tools/shell.ts) judges what it sends to somebody's laptop. Those answer to
  * different policy (a rulebook with a permission card here, a scope switch on the card there) but they must
  * agree on WHAT A COMMAND IS, or a class the owner thought they had covered turns out to mean something else on
  * the surface where it mattered most. One table, two consults.
@@ -18,7 +20,7 @@ import { type CommandClass, CommandClassSchema } from "./schemas/agent.js";
  * A creatively quoted command, a path assembled from a variable, or a script written in one call and run in the
  * next goes past it untouched. So a gate built on this is friction and a prompt for well-behaved work, never a
  * boundary, the boundaries are structural and elsewhere: the container, the isolated worktree, the land gate,
- * an automation's tool allowlist, and, on somebody's own computer, the scope switches enforced there.
+ * an automation's tool allowlist, and, on somebody's own device, the scope switches enforced there.
  *
  * WHICH IS WHY THIS NO LONGER DECIDES ANYTHING. A match used to BE the verdict: whatever fired here became the
  * permission card, so `echo "rm -rf /"`, `rg 'rm -rf'` and an actual delete were one question with one answer.
@@ -28,6 +30,18 @@ import { type CommandClass, CommandClassSchema } from "./schemas/agent.js";
  * positive now costs one model call rather than one interruption, and a miss still costs everything. Anyone
  * tuning a pattern below should widen rather than narrow it.
  *
+ * WITH ONE EXCEPTION, AND IT IS WHY `live` EXISTS. The hard rule (safety-policy.ts hardRuleClasses) still turns
+ * a match straight into an interruption nothing can waive, so for the classes it covers a false positive costs
+ * exactly what it always did. That left the old failure standing in the one place it could not be argued out
+ * of: `echo "rm -rf /" >> notes.md` and `rg 'rm -rf /'` were un-waivable cards over a string. So every match
+ * carries whether a shell would RUN the fragment or merely print, search or write it (shell-regions.ts), and
+ * only the hard rule reads that bit. The tables stay over-inclusive; the un-waivable tier stops firing on text.
+ *
+ * AND IT IS ASKED OF A PLACE. `rm -rf /usr` ends a laptop and costs a container nothing, because a container is
+ * rebuilt from an image; a Docker volume here is a dev database the agent made and there is the owner's data.
+ * Half the tables below therefore have two answers, chosen by CommandContext.locus, and the caller must say
+ * which machine it is asking about. schemas/agent.ts CommandLocus argues the split.
+ *
  * Matching is deliberately UNANCHORED, substrings, not line starts. Another PreToolUse hook may have rewrapped
  * the command by the time this reads it (agent-terminals.ts wraps every Bash call in bin/tmux-run), and the
  * agent's own line survives verbatim inside that wrapper. Nothing the wrapper adds is in any class below.
@@ -58,16 +72,30 @@ export interface CommandSpan {
     readonly end: number;
 }
 
-// One class the command fell in, and the fragments that put it there. `spans` is never empty: a class with
-// nothing to point at is a class this walk does not report.
+/* One class the command fell in, and the fragments that put it there. `spans` is never empty: a class with
+ * nothing to point at is a class this walk does not report. */
 export interface CommandMatch {
     readonly commandClass: CommandClass;
     readonly spans: readonly CommandSpan[];
+    /* Would a shell RUN any of those fragments, or are they all text — a heredoc body, a comment, a quoted
+     * argument to echo or a grep (shell-regions.ts says how that is decided and how wrong it is allowed to be)?
+     *
+     * ONLY THE HARD RULE READS THIS, and that is the whole point of it being a flag on the match rather than a
+     * filter over the tables. A mention still puts the command in the class, still reaches the judge, and is
+     * still marked on the card: the judge is the tier that can tell a README from a delete, and taking the
+     * class away would take the question away from it. What a mention must NOT do is trip the one tier that
+     * cannot be argued with, which is what `echo "rm -rf /" >> notes.md` used to do. */
+    readonly live: boolean;
 }
 
 /* WHAT THE CALLER CAN CHECK THAT THE PATTERNS CANNOT. Optional everywhere: absent ⇒ every table answers from
  * the command text alone, which is what the browser, the machine agent and every test that does not care get. */
 export interface CommandContext {
+    /* WHERE THIS COMMAND WOULD RUN, and it is the one field with no default. Half this catalog means something
+     * different on a disposable container than on somebody's laptop — which directories are roots, whether a
+     * Docker volume is a dev database or their data — and a default would be one of those two answers applied
+     * silently to the other machine. Callers state it; schemas/agent.ts CommandLocus argues the split. */
+    readonly locus: CommandLocus;
     /* Does the file at this path — as the command spells it, `~/.npmrc`, `.env`, `/work/app/.env.local` — hold
      * credential material? (credential-material.ts says what that means; the caller says how to read a file.)
      *
@@ -251,16 +279,38 @@ const parseRm = (command: string): RmInvocation[] => {
 };
 
 /* A TARGET THAT IS A ROOT RATHER THAN SOMETHING INSIDE ONE. This is the whole difference between the two
- * deletion classes, so it is deliberately a short, closed list of whole names rather than a clever heuristic:
- * the filesystem root and the top-level directories an OS keeps, the two trees this product keeps state in, a
- * home directory however it is spelled, and a Windows drive.
+ * deletion classes, so it is deliberately a short, closed list of whole names rather than a clever heuristic.
  *
- * `/tmp` is deliberately absent. It is scratch by definition and emptying it is a chore, not an incident. */
-const ROOT_DIRECTORIES = new Set([
-    // The empty string is what the filesystem root normalizes to, see trimTarget.
+ * AND IT IS A DIFFERENT LIST PER LOCUS, because "root" means "the thing nothing here brings back" and the two
+ * machines answer that very differently. Everything below is measured against one question: after this delete,
+ * what restores it?
+ *
+ * `/tmp` is deliberately absent from both. It is scratch by definition and emptying it is a chore, not an
+ * incident. */
+
+/* IN THIS SANDBOX: two entries, and the shortness is the point rather than an oversight.
+ *
+ *   ``        the filesystem root itself (what trimTarget normalizes `/` to). Nothing restores it.
+ *   /history  every OTHER conversation's worktrees and logs. THIS turn cannot recreate them at any price,
+ *             which is exactly what makes it a root here and the reason it outranks anything in /work.
+ *
+ * WHAT IS DELIBERATELY NOT HERE, and each was hard-ruled before this: `/usr`, `/etc`, `/bin`, `/var`, `/opt`
+ * and the rest of the container's OS come back with the image — recreating this sandbox is a documented
+ * operation, not a catastrophe. `/work` is a git worktree whose delta lands as uncommitted changes, and it is
+ * also the directory an agent has the most legitimate reason to clear. `/Users`, `/Applications`, `/System`,
+ * `/Library` and a Windows drive do not exist in this container at all, so holding them here bought nothing and
+ * cost a card. All of them are still files.destructive, still triaged, still judged — they have simply stopped
+ * being un-waivable. */
+const SANDBOX_ROOTS = new Set(["", HISTORY_ROOT]);
+
+/* ON THE OWNER'S OWN COMPUTER: the full list, because nothing there is rebuilt from an image and there is no
+ * checkpoint under any of it. The filesystem root, the top-level directories an OS keeps, both of this
+ * product's own trees (a device may be running one), a home directory however it is spelled, and a Windows
+ * drive. Unchanged from what this catalog held before the split. */
+const DEVICE_ROOTS = new Set([
     "",
-    "/work",
-    "/history",
+    WORKSPACE_ROOT,
+    HISTORY_ROOT,
     "/home",
     "/root",
     "/etc",
@@ -284,6 +334,8 @@ const ROOT_DIRECTORIES = new Set([
     "/Library",
 ]);
 
+const rootsAt = (locus: CommandLocus): ReadonlySet<string> => (locus === "sandbox" ? SANDBOX_ROOTS : DEVICE_ROOTS);
+
 const HOME_ALIAS = /^(?:~|\$HOME|\$\{HOME\}|%USERPROFILE%)$/;
 const WINDOWS_DRIVE = /^[A-Za-z]:$/;
 
@@ -293,14 +345,16 @@ const WINDOWS_DRIVE = /^[A-Za-z]:$/;
  * case this class exists to stay out of the way of. */
 const trimTarget = (operand: string): string => operand.replace(/[/\\]\*+$/, "").replace(/[/\\]+$/, "");
 
-const isRootTarget = (operand: string): boolean => {
+const isRootTarget = (operand: string, locus: CommandLocus): boolean => {
     const target = trimTarget(operand);
+    /* A home directory and a Windows drive are roots on a DEVICE only. In the container `~` is the agent's own
+     * scratch home, rebuilt with the image, and `C:` is not a path that exists. */
     if (HOME_ALIAS.test(target) || WINDOWS_DRIVE.test(target)) {
-        return true;
+        return locus === "device";
     }
     // Only an absolute path can name a root, and `""` is the root itself. A relative path is inside whatever
     // the shell is standing in, which this cannot know and must not guess about.
-    return target === "" ? operand.startsWith("/") || operand.startsWith("\\") : ROOT_DIRECTORIES.has(target);
+    return target === "" ? operand.startsWith("/") || operand.startsWith("\\") : rootsAt(locus).has(target);
 };
 
 /* --- the JS execution backend's own deletes -------------------------------------------------------------
@@ -355,9 +409,13 @@ const nodeDeleteTargets = (program: string): { readonly target: string; readonly
  * it), `docker image prune` (pull it again), `git reset --hard` (that is git.destructive, and the reflog has
  * it), `rm -rf node_modules` (install it again). The point of a floor is that it is rare enough to be worth
  * stopping for; a floor that fires on ordinary work is one people learn to click through. */
-const SYSTEM_DESTRUCTIVE = [
-    // Format, wipe or overwrite a block device. `dd` only counts when it is pointed AT a device: reading one
-    // into a file is how an image is taken, and holding a backup would be exactly the wrong lesson.
+/* A BLOCK DEVICE, FORMATTED, WIPED OR OVERWRITTEN. The only membership of system.destructive that does not
+ * depend on where the command runs: there is no image, checkpoint or worktree behind a disk at either locus,
+ * and this is what the shipped safety policy has always told the owner it holds unconditionally.
+ *
+ * `dd` only counts when it is pointed AT a device: reading one into a file is how an image is taken, and
+ * holding a backup would be exactly the wrong lesson. */
+const BLOCK_DEVICE = [
     /\bmkfs(?:\.\w+)?\b/,
     /\bwipefs\b/,
     /\bblkdiscard\b/,
@@ -366,11 +424,22 @@ const SYSTEM_DESTRUCTIVE = [
     /\bshred\b[^|;&]*\s\/dev\//,
     // A redirect straight onto a disk device, which is the same wipe without the ceremony.
     />\s*\/dev\/(?:[shv]d[a-z]|nvme\d|disk\d|mmcblk\d)/,
-    /* Docker state that is data rather than image. A named volume IS the database; `system prune` takes every
-     * unused one with it, and `compose down -v` is the spelling people reach for without reading the flag.
-     * In this sandbox these hit the nested engine (the host's socket is never mounted, see
-     * capabilities/handlers/docker.ts), so the blast radius is the dev databases the agent has been working
-     * against. Sent to somebody's own computer through the host agent, it is whatever they run on it. */
+];
+
+/* CONTAINER STATE THAT IS DATA RATHER THAN IMAGE, its own class (container.state) because the two loci
+ * disagree about it more sharply than about anything else in this catalog.
+ *
+ * IN THIS SANDBOX these reach the NESTED engine — the host's Docker socket is never mounted, see
+ * capabilities/handlers/docker.ts — so the volumes in reach are the ones the agent itself created, and tearing
+ * down a smoke-test stack it just brought up is ordinary work. Holding it as an un-waivable card was the
+ * concrete complaint that produced this split: `docker volume rm` on a throwaway test container is not the
+ * class of thing a person needs woken for.
+ *
+ * ON SOMEBODY'S OWN COMPUTER a named volume IS the database, and the owner's policy says never. It stays
+ * hard-ruled there (safety-policy.ts hardRuleClasses), and the machine's own `destructive` scope sits under
+ * that (machine/src/device/tools/shell.ts GATED_CLASSES), which is the part that is a boundary rather than
+ * friction. */
+const CONTAINER_STATE = [
     /\b(?:docker|podman)\s+volume\s+(?:rm|remove|prune)\b/,
     /\b(?:docker|podman)\s+system\s+prune\b/,
     /\b(?:docker(?:\s+compose|-compose)?|podman-compose)\s+down\b[^|;&]*\s(?:-v\b|--volumes\b)/,
@@ -381,25 +450,27 @@ const recursiveForceRms = (command: string): CommandSpan[] =>
         .filter((invocation) => invocation.recursive && invocation.force)
         .map((invocation) => invocation.span);
 
-// A recursive delete aimed at a root, in either spelling the gate can be handed: the shell's `rm -rf /` and
-// the script's `fs.rmSync("/", { recursive: true })`.
-const rootDeletes = (program: string): CommandSpan[] => [
+/* A recursive delete aimed at a root, in either spelling the gate can be handed: the shell's `rm -rf /` and
+ * the script's `fs.rmSync("/", { recursive: true })`. Which targets count as roots is the locus's answer, so
+ * `rm -rf /usr` is this class on a laptop and merely files.destructive in a container built from an image. */
+const rootDeletes = (program: string, locus: CommandLocus): CommandSpan[] => [
     ...parseRm(program)
-        .filter((invocation) => invocation.recursive && invocation.force && invocation.operands.some(isRootTarget))
+        .filter((invocation) => invocation.recursive && invocation.force && invocation.operands.some((operand) => isRootTarget(operand, locus)))
         .map((invocation) => invocation.span),
     ...nodeDeleteTargets(program)
-        .filter((delete_) => isRootTarget(delete_.target))
+        .filter((delete_) => isRootTarget(delete_.target, locus))
         .map((delete_) => delete_.span),
 ];
 
 // The `g` twins, built once at load rather than per call: a card is minted per held command and a classify runs
-// per command the agent types, so recompiling six tables of patterns each time is work with no reader.
+// per command the agent types, so recompiling seven tables of patterns each time is work with no reader.
 const GIT_DESTRUCTIVE_G = globally(GIT_DESTRUCTIVE);
 const SECRET_REFERENCES_G = globally(SECRET_REFERENCES);
 const CREDENTIAL_PATHS_G = globally(CREDENTIAL_PATHS);
 const PACKAGE_PUBLISH_G = globally(PACKAGE_PUBLISH);
 const NETWORK_OUTBOUND_G = globally(NETWORK_OUTBOUND);
-const SYSTEM_DESTRUCTIVE_G = globally(SYSTEM_DESTRUCTIVE);
+const BLOCK_DEVICE_G = globally(BLOCK_DEVICE);
+const CONTAINER_STATE_G = globally(CONTAINER_STATE);
 
 /* THE PATH A MATCHED FRAGMENT SITS IN, so the oracle is asked about the file the command would actually open
  * rather than about the suffix that fired: `sed 's/…/' ~/.npmrc` fires on `.npmrc` and must ask about
@@ -463,20 +534,21 @@ const namesAPattern = (word: string): boolean =>
  * `!== false` is the whole fact-check, and the comparison is written against `false` rather than for `true` on
  * purpose: `undefined` (nobody could look) has to behave like `true` (there is a credential in there), or the
  * class would evaporate on every caller without a filesystem. */
-const credentialReads = (command: string, context: CommandContext | undefined): CommandSpan[] => [
+const credentialReads = (command: string, context: CommandContext): CommandSpan[] => [
     ...spansOf(SECRET_REFERENCES_G, command),
     ...spansOf(CREDENTIAL_PATHS_G, command).filter((span) => {
         const word = enclosingPath(command, span);
-        return !namesAPattern(word) && context?.holdsSecret?.(word) !== false;
+        return !namesAPattern(word) && context.holdsSecret?.(word) !== false;
     }),
 ];
 
 // WHERE each class fires, one entry per class. Empty ⇒ the command is not in it, so membership and evidence are
 // the same walk and cannot disagree: there is no way to be held for a class with nothing to show for it.
-const MATCHES: Readonly<Record<CommandClass, (command: string, context: CommandContext | undefined) => CommandSpan[]>> = {
+const MATCHES: Readonly<Record<CommandClass, (command: string, context: CommandContext) => CommandSpan[]>> = {
     "git.destructive": (command) => spansOf(GIT_DESTRUCTIVE_G, command),
     "files.destructive": (command) => [...recursiveForceRms(command), ...recursiveDeletes(command)],
-    "system.destructive": (command) => [...spansOf(SYSTEM_DESTRUCTIVE_G, command), ...rootDeletes(command)],
+    "system.destructive": (command, context) => [...spansOf(BLOCK_DEVICE_G, command), ...rootDeletes(command, context.locus)],
+    "container.state": (command) => spansOf(CONTAINER_STATE_G, command),
     "secrets.access": credentialReads,
     "package.publish": (command) => spansOf(PACKAGE_PUBLISH_G, command),
     "network.outbound": (command) => spansOf(NETWORK_OUTBOUND_G, command),
@@ -485,31 +557,61 @@ const MATCHES: Readonly<Record<CommandClass, (command: string, context: CommandC
 /* Every class the command falls in AND the fragments that put it there, in the catalog's own order so a card and
  * a log name them the same way twice. The primitive; classifyCommand is this with the offsets dropped.
  *
- * `context` is what a caller that can check a fact hands in (CommandContext); omitting it classifies from the
- * command text alone, which is every caller that has no filesystem to consult. */
-export const matchCommand = (command: string, context?: CommandContext): CommandMatch[] =>
-    CommandClassSchema.options.flatMap((commandClass) => {
+ * `context` is REQUIRED, unlike before: its `locus` decides what half of this catalog means (see
+ * CommandContext), and the fact-check is the optional part of it.
+ *
+ * THE INERT SCAN RUNS ONCE, here, and is handed to every class rather than being redone per table: it walks the
+ * whole command, and seven walks would be six more than the answer needs. A class with no live span is still
+ * reported — `live` rides on the match and only the hard rule reads it (shell-regions.ts argues why). */
+export const matchCommand = (command: string, context: CommandContext): CommandMatch[] => {
+    const regions = inertRegions(command);
+    return CommandClassSchema.options.flatMap((commandClass) => {
         const spans = mergeSpans(MATCHES[commandClass](command, context));
-        return spans.length === 0 ? [] : [{ commandClass, spans }];
+        return spans.length === 0 ? [] : [{ commandClass, spans, live: spans.some((span) => isLive(span, regions)) }];
     });
+};
 
 // Every class the command falls in, for the callers that only take a verdict from it (the gate's rulebook
 // consult, the machine agent's scope switch).
-export const classifyCommand = (command: string, context?: CommandContext): CommandClass[] =>
+export const classifyCommand = (command: string, context: CommandContext): CommandClass[] =>
     matchCommand(command, context).map((match) => match.commandClass);
 
 // What the card says the command would DO. The class name is a settings key, not a sentence to show a person.
 export const COMMAND_CLASS_LABELS: Readonly<Record<CommandClass, string>> = {
     "git.destructive": "rewrite or discard git history",
     "files.destructive": "delete files recursively",
-    "system.destructive": "wipe a disk, a container volume, or a whole home or root directory",
+    "system.destructive": "wipe a disk, or delete a whole root directory",
+    "container.state": "delete a container volume or the data in it",
     "secrets.access": "read credential material",
     "package.publish": "publish or release a package",
     "network.outbound": "send a request out to the internet",
 };
 
+/* THE PATTERNS BEHIND EACH CLASS, IN WORDS, for the one reader that is a person rather than a gate: the Safety
+ * page's "What gets stopped" panel (editor/web/.../AgentSafetyRules.vue). A card says which class fired; this
+ * says what the class is, so an owner can see the whole catalog without reading this file.
+ *
+ * PROSE RATHER THAN THE REGEXES THEMSELVES, deliberately. A `/\b(?:docker|podman)\s+volume\s+(?:rm|remove|prune)\b/`
+ * on a settings page is a worse answer to "what stops my commands" than "docker volume rm, remove, prune" is,
+ * and rendering source at somebody implies they can edit it. Pinned to the tables by the conformance test in
+ * command-classes.test.ts, so a pattern added without a line here fails the suite rather than going unlisted. */
+export const COMMAND_CLASS_PATTERNS: Readonly<Record<CommandClass, readonly string[]>> = {
+    "git.destructive": ["git push --force / -f / --force-with-lease / --delete", "git reset --hard", "git clean -f", "git branch -D", "git filter-branch"],
+    "files.destructive": ["rm -rf <path>", "fs.rm / rmSync / rmdir with recursive: true", "rimraf(<path>)"],
+    "system.destructive": [
+        "mkfs, wipefs, blkdiscard, sgdisk --zap-all",
+        "dd of=/dev/…, shred /dev/…, > /dev/sda",
+        "rm -rf aimed at a root directory",
+    ],
+    "container.state": ["docker / podman volume rm, remove, prune", "docker / podman system prune", "docker compose down -v"],
+    "secrets.access": ["a {{secret:NAME}} reference in the command", ".env, .ssh/*, id_rsa, .aws/credentials, .npmrc, .git-credentials"],
+    "package.publish": ["npm / pnpm / yarn / bun publish", "cargo publish", "gh release create", "docker push", "twine upload"],
+    "network.outbound": ["curl / wget to a non-loopback https:// host", 'fetch("https://…") in a script'],
+};
+
 /* No verdict set lives here any more. Which classes are worth stopping for is a POLICY question now, and it is
- * answered in two places that are honest about being different: safety-policy.ts's HARD_RULE_CLASSES for the
- * one thing nothing recovers, and the owner's own written policy for everything else. The machine agent keeps
- * its own set beside its scope switches (machine/src/computer/tools/shell.ts), because "which commands need
- * the destructive switch" is a question about that capability card rather than about this catalog. */
+ * answered in two places that are honest about being different: safety-policy.ts's hardRuleClasses for the
+ * things nothing recovers at a given locus, and the owner's own written policy for everything else. The machine
+ * agent keeps its own set beside its scope switches (machine/src/device/tools/shell.ts), because "which
+ * commands need the destructive switch" is a question about that capability card rather than about this
+ * catalog. */

package/src/contracts/accounts.contract.ts

@@ -0,0 +1,94 @@
+import { oc } from "@orpc/contract";
+import { NativeProviderParamSchema } from "../schemas/agent.js";
+import {
+    AccountIdSchema,
+    AccountListQuerySchema,
+    AccountRenameSchema,
+    LoginCancelSchema,
+    LoginCompletedSchema,
+    LoginCompleteSchema,
+    LoginRequestSchema,
+    LoginStartSchema,
+    OauthAccountListSchema,
+    OauthAccountSchema,
+} from "../schemas/provider-oauth.js";
+import { OkSchema } from "../schemas/shared.js";
+
+/* THE ACCOUNTS THIS SANDBOX HOLDS ITSELF, one route family with the provider as a PARAMETER.
+ *
+ * Four families used to serve this (Claude's, Cursor's, Grok's, and one for every provider whose sign-in mints
+ * its own key), each "the previous one's shape" with a verb renamed: `oauth/start` here, `login/start` there,
+ * an `exchange` for the flow whose proof travelled and a `complete` for the one whose proof did not. The
+ * lesson providers.contract.ts learned about model catalogs holds for accounts too: the operations are the
+ * same six for all of them, so the id is a parameter and a provider's own mechanism is its module's to declare
+ * (the daemon's ProviderModule.accounts), not a vertical slice through the contract, the router and every test
+ * double.
+ *
+ * WHY NOT THE TRANSLATOR ROUTES. Those address subscriptions CLIProxyAPI holds and re-serves behind an Anthropic
+ * endpoint; these credentials live in this daemon's own auth tree (or, for Grok, in OpenCode's), and a
+ * disconnect here removes a file rather than asking a proxy to forget one. A provider served both ways (Grok)
+ * has a row in each.
+ *
+ * Nothing redeemable is on any answer here: `accounts` is an OauthAccount list, whose shape has no field a
+ * credential could ride in, and a sign-in's proof never leaves the sandbox (provider-oauth.ts, LoginStart). */
+export const accountsContract = {
+    start: oc
+        .route({
+            method: "POST",
+            path: "/accounts/{provider}/login/start",
+            summary: "Begin connecting an account",
+            description:
+                "Hands back the page to sign in on, and the code it will ask for where there is one. The sandbox holds the proof and finishes what it can itself: a device sign-in lands in the account list on its own, a paste or a redirect needs one thing brought back to the finishing call.",
+        })
+        .input(NativeProviderParamSchema.extend(LoginRequestSchema.shape))
+        .output(LoginStartSchema),
+    complete: oc
+        .route({
+            method: "POST",
+            path: "/accounts/{provider}/login/complete",
+            summary: "Finish a sign-in with what the page handed back",
+            description:
+                "Takes the code the page showed, or the address a redirect landed on, and finishes the attempt. Answers with the account where the exchange ends here; otherwise the sandbox still has a mint to do and the row appears in the account list.",
+        })
+        .input(NativeProviderParamSchema.extend(LoginCompleteSchema.shape))
+        .output(LoginCompletedSchema),
+    cancel: oc
+        .route({
+            method: "POST",
+            path: "/accounts/{provider}/login/cancel",
+            summary: "Abandon a sign-in",
+            description: "Stops waiting on a sign-in nobody completed. An abandoned attempt also expires on its own.",
+        })
+        .input(NativeProviderParamSchema.extend(LoginCancelSchema.shape))
+        .output(OkSchema),
+    // Each account carries its plan-limit reading where the provider publishes one. `force` re-measures before
+    // answering (AccountListQuerySchema); a provider with nothing to measure accepts it and answers at once.
+    accounts: oc
+        .route({
+            method: "GET",
+            path: "/accounts/{provider}",
+            summary: "Connected accounts of a provider",
+            description:
+                "Each connected account with how full its plan limits were when last measured, where the provider publishes any. Ask for a fresh measurement and it takes one before answering, which is slower. The credentials themselves never travel: being in this list is what connected means.",
+        })
+        .input(NativeProviderParamSchema.extend(AccountListQuerySchema.shape))
+        .output(OauthAccountListSchema),
+    rename: oc
+        .route({
+            method: "POST",
+            path: "/accounts/{provider}/rename",
+            summary: "Rename an account",
+            description: "Changes the label one account shows under, so several are tellable apart. Blank restores the one derived from the sign-in.",
+        })
+        .input(NativeProviderParamSchema.extend(AccountRenameSchema.shape))
+        .output(OauthAccountSchema),
+    disconnect: oc
+        .route({
+            method: "POST",
+            path: "/accounts/{provider}/disconnect",
+            summary: "Disconnect an account",
+            description: "Clears one stored credential, and stops any sign-in still in flight for this provider. The others stay connected.",
+        })
+        .input(NativeProviderParamSchema.extend(AccountIdSchema.shape))
+        .output(OkSchema),
+};

package/src/contracts/agents.contract.ts

@@ -5,6 +5,7 @@ import {
     AgentAutoLandSchema,
     AgentFileDiffQuerySchema,
     AgentIdSchema,
+    AgentTranscriptQuerySchema,
     AgentIdsSchema,
     AgentLandSchema,
     AgentPlaceSchema,
@@ -94,11 +95,11 @@ export const agentsContract = {
         .route({
             method: "GET",
             path: "/agents/{id}/transcript",
-            summary: "The full conversation record",
+            summary: "One page of a conversation",
             description:
-                "Every message in one conversation, in order, including the tool calls and their results. This is the record the chat replays and the next turn is seeded from.",
+                "The most recent turns of one conversation, in order, including the tool calls and their results: what the chat replays and the next turn is seeded from. A page, not the whole record — pass the answer's `from` back as `before` to walk further back, until `more` reads false.",
         })
-        .input(AgentIdSchema)
+        .input(AgentTranscriptQuerySchema)
         .output(AgentTranscriptSchema),
     /* SPEAK AS THE AGENT, append the user's words to the conversation's record as an assistant row, with no
      * turn behind them and no reply. The row is marked `placed` for human readers (TranscriptRowSchema); the

package/src/contracts/exit.contract.ts

@@ -6,7 +6,7 @@ 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 Status card and by the agent through `exit` on its PATH, which calls these very routes.
+// 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
@@ -17,7 +17,7 @@ import { OkSchema } from "../schemas/shared.js";
 // 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
+    // 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).
     list: oc
         .route({

package/src/contracts/host.contract.ts

@@ -1,14 +1,14 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
-import { MachineFlowLineSchema, MachineSandboxFlowSchema } from "../schemas/computers.js";
+import { DeviceAgentFlowSchema, DeviceFlowLineSchema, DeviceSandboxFlowSchema } from "../schemas/devices.js";
 import { HostScopesSchema } from "../schemas/capabilities.js";
 import { HostFactsSchema } from "../schemas/hosts.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* What a connected computer can be ASKED, over the socket it opened to this sandbox.
+/* 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 computer sits behind NAT with a closing lid, so it can only
+ * 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.
  *
@@ -22,7 +22,7 @@ import { OkSchema } from "../schemas/shared.js";
  * 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 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.
     describe: oc.output(HostFactsSchema),
     // The grant, pushed down on every connect and again whenever the owner edits the card. The machine ENFORCES
@@ -43,5 +43,17 @@ export const hostContract = {
      *
      * 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)),
+    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. */
+    runAgentFlow: oc.input(DeviceAgentFlowSchema).output(eventIterator(DeviceFlowLineSchema)),
 };

package/src/contracts/settings.contract.ts

@@ -5,7 +5,7 @@ import { DayWindowQuerySchema } from "../schemas/usage.js";
 
 // 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 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