@intentic/sandbox-contract 1.158.0 → 1.160.0

package/src/contracts/agents.contract.ts

@@ -1,13 +1,19 @@
 import { oc } from "@orpc/contract";
+import { AgentTranscriptSchema } from "../events.js";
 import {
     AgentArchiveSchema,
+    AgentAutoLandSchema,
     AgentChangesSchema,
     AgentFileDiffQuerySchema,
     AgentIdSchema,
     AgentIdsSchema,
+    AgentLandSchema,
     AgentRenameSchema,
+    AgentSearchQuerySchema,
+    AgentSearchResultSchema,
     AgentsListSchema,
     AgentsMovedSchema,
+    AgentsRemovedSchema,
     AgentSummarySchema,
     FileDiffSchema,
     LandResultSchema,
@@ -29,17 +35,35 @@ import {
 // per repo per agent) and keeps the branch, the entry, and the transcript. `list` then stops carrying it and
 // `archived` does; `unarchive` puts it back, and either way the next turn re-attaches a worktree from the
 // surviving branch. Archiving a running agent is CONFLICT, same as land/discard.
+//
+// PURGE empties the archive, and it is `discard` applied to every agent already in there: worktree remnants,
+// branches and entries all go. Deliberately the whole archive and not a list of ids — the archive is the pile
+// of agents the user has already decided are over, so "clean it up" is one act with one confirmation, and a
+// per-id purge would be `discard`, which already exists. Never touches a running agent (a turn un-archives its
+// own agent, so there should be none) and answers with what it actually deleted: a teardown that fails on one
+// agent's repo leaves that one behind rather than taking the batch down with it.
 export const agentsContract = {
     list: oc.route({ method: "GET", path: "/agents" }).output(AgentsListSchema),
     archived: oc.route({ method: "GET", path: "/agents/archived" }).output(AgentsListSchema),
+    // The board's filter. Answers over BOTH halves of the fleet — the live roster and the archive — because
+    // the board hides by design (the Finished lane windows to a handful, archived agents are off the roster
+    // entirely), and a filter that reports "no matches" while the agent sits one click away is a lie. The
+    // never-carded conversations that are neither are `sessions.list`'s query, which matches by the same rule.
+    search: oc.route({ method: "GET", path: "/agents/search" }).input(AgentSearchQuerySchema).output(AgentSearchResultSchema),
     get: oc.route({ method: "GET", path: "/agents/{id}" }).input(AgentIdSchema).output(AgentSummarySchema),
+    transcript: oc.route({ method: "GET", path: "/agents/{id}/transcript" }).input(AgentIdSchema).output(AgentTranscriptSchema),
     rename: oc.route({ method: "POST", path: "/agents/{id}/rename" }).input(AgentRenameSchema).output(AgentSummarySchema),
+    // This agent's own land-at-completion posture — an override of the sandbox-wide `autoLand` setting; null
+    // clears it back to "inherit". Legal mid-turn on purpose: the setting is read at turn COMPLETION, so
+    // flipping it while the agent works is exactly "hold THIS turn's work for review", the press that matters.
+    autoLand: oc.route({ method: "POST", path: "/agents/{id}/auto-land" }).input(AgentAutoLandSchema).output(AgentSummarySchema),
     seen: oc.route({ method: "POST", path: "/agents/{id}/seen" }).input(AgentIdSchema).output(AgentSummarySchema),
     seenAll: oc.route({ method: "POST", path: "/agents/seen" }).output(AgentsListSchema),
     diff: oc.route({ method: "GET", path: "/agents/{id}/diff" }).input(AgentIdSchema).output(AgentChangesSchema),
     fileDiff: oc.route({ method: "GET", path: "/agents/{id}/{repo}/file-diff" }).input(AgentFileDiffQuerySchema).output(FileDiffSchema),
-    land: oc.route({ method: "POST", path: "/agents/{id}/land" }).input(AgentIdSchema).output(LandResultSchema),
+    land: oc.route({ method: "POST", path: "/agents/{id}/land" }).input(AgentLandSchema).output(LandResultSchema),
     discard: oc.route({ method: "POST", path: "/agents/{id}/discard" }).input(AgentIdSchema).output(OkSchema),
     archive: oc.route({ method: "POST", path: "/agents/archive" }).input(AgentArchiveSchema).output(AgentsMovedSchema),
     unarchive: oc.route({ method: "POST", path: "/agents/unarchive" }).input(AgentIdsSchema).output(AgentsMovedSchema),
+    purge: oc.route({ method: "POST", path: "/agents/purge" }).output(AgentsRemovedSchema),
 };

package/src/contracts/claude.contract.ts

@@ -1,6 +1,7 @@
 import { oc } from "@orpc/contract";
 import {
     AccountIdSchema,
+    AccountRenameSchema,
     AuthorizeChallengeSchema,
     ModelsSchema,
     OauthAccountListSchema,
@@ -11,12 +12,14 @@ import {
 
 // 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; `disconnect` clears the one named by id. A sandbox can hold several Claude accounts.
+// connected accounts; `rename` renames one; `disconnect` clears the one named by id. A sandbox can hold several
+// Claude accounts.
 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),
     // Claude's available models for the picker, from the Agent SDK's supportedModels() (see claude-models.ts).
     models: oc.route({ method: "GET", path: "/claude/models" }).output(ModelsSchema),
     accounts: oc.route({ method: "GET", path: "/claude/accounts" }).output(OauthAccountListSchema),
+    rename: oc.route({ method: "POST", path: "/claude/account/rename" }).input(AccountRenameSchema).output(OauthAccountSchema),
     disconnect: oc.route({ method: "POST", path: "/claude/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
 };

package/src/contracts/git.contract.ts

@@ -1,5 +1,7 @@
 import { oc } from "@orpc/contract";
 import {
+    CommitMessageDraftSchema,
+    CommitMessageSchema,
     CommitResultSchema,
     CommitSchema,
     DiscardSchema,
@@ -39,6 +41,10 @@ import {
 // Changes panel renders; commit/discard take optional `paths` for per-file actions.
 export const gitContract = {
     changes: oc.route({ method: "GET", path: "/git/changes" }).output(GitChangesSchema),
+    // Drafts a commit message for what the commit box is about to record, on the sandbox's quick model (the
+    // cheap rung — see quick-model.ts). Workspace-wide like `changes` and for the same reason: one commit box,
+    // one message, every staged repo. POST because it spends a model call, not because it writes anything.
+    commitMessage: oc.route({ method: "POST", path: "/git/commit-message" }).input(CommitMessageDraftSchema).output(CommitMessageSchema),
     // 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).

package/src/contracts/kimi.contract.ts

@@ -1,15 +1,26 @@
 import { oc } from "@orpc/contract";
-import { AccountIdSchema, KimiConnectSchema, ModelsSchema, OauthAccountListSchema, OauthAccountSchema, OkSchema } from "../schemas.js";
+import {
+    AccountIdSchema,
+    AccountRenameSchema,
+    KimiConnectSchema,
+    ModelsSchema,
+    OauthAccountListSchema,
+    OauthAccountSchema,
+    OkSchema,
+} from "../schemas.js";
 
 // Kimi Code (Moonshot) — the sandbox owns the credential, an API key rather than an OAuth grant. Kimi speaks the
 // Anthropic Messages protocol, so a Kimi turn runs on the SAME Claude Code harness as Claude, with the harness
 // pointed at Moonshot's Anthropic-compatible endpoint and authenticated with the stored key (see agent.routes).
 // `connect` stores a pasted key as a new account and returns it; `models` is the live catalog for the picker;
-// `accounts` lists connected keys (tokens never ride back); `disconnect` clears the one named by id.
+// `accounts` lists connected keys (tokens never ride back); `rename` renames one (a pasted key carries no
+// identity to derive a name from, so this is the ONLY way a Kimi row gets a distinguishing name);
+// `disconnect` clears the one named by id.
 export const kimiContract = {
     connect: oc.route({ method: "POST", path: "/kimi/account/connect" }).input(KimiConnectSchema).output(OauthAccountSchema),
     // Kimi/Moonshot's live models for the picker — the source of valid ids (see kimi-models.ts).
     models: oc.route({ method: "GET", path: "/kimi/models" }).output(ModelsSchema),
     accounts: oc.route({ method: "GET", path: "/kimi/accounts" }).output(OauthAccountListSchema),
+    rename: oc.route({ method: "POST", path: "/kimi/account/rename" }).input(AccountRenameSchema).output(OauthAccountSchema),
     disconnect: oc.route({ method: "POST", path: "/kimi/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
 };

package/src/contracts/memory.contract.ts

@@ -0,0 +1,13 @@
+import { oc } from "@orpc/contract";
+import { MemoryFileQuerySchema, MemoryFileSchema, MemoryListSchema, MemoryWriteSchema, OkSchema } from "../schemas.js";
+
+// The agent's persistent memory notes (.intentic/claude/projects/<project>/memory) — the one browser surface
+// for that control-plane subtree (see schemas.ts). Read for the memory panel; write/delete so the owner can
+// curate what the agent remembers (fix a stale fact, drop a wrong one). oRPC's OpenAPI codec reads non-GET
+// input from the JSON body, so write and delete send {project, name} in the body (same as /workspace/entry).
+export const memoryContract = {
+    list: oc.route({ method: "GET", path: "/memory" }).output(MemoryListSchema),
+    read: oc.route({ method: "GET", path: "/memory/file" }).input(MemoryFileQuerySchema).output(MemoryFileSchema),
+    write: oc.route({ method: "PUT", path: "/memory/file" }).input(MemoryWriteSchema).output(OkSchema),
+    delete: oc.route({ method: "DELETE", path: "/memory/file" }).input(MemoryFileQuerySchema).output(OkSchema),
+};

package/src/contracts/push.contract.ts

@@ -1,5 +1,5 @@
 import { oc } from "@orpc/contract";
-import { OkSchema, PushConfigQuerySchema, PushConfigSchema, PushEndpointSchema, PushSubscriptionSchema } from "../schemas.js";
+import { OkSchema, PushConfigQuerySchema, PushConfigSchema, PushEndpointSchema, PushSubscriptionSchema, PushTestSchema } from "../schemas.js";
 
 // Web-push notifications for this sandbox. The daemon owns the VAPID keypair and the subscription list (see
 // push/push-store.ts for why the key lives on the history volume), and sends on the three moments where the
@@ -13,5 +13,5 @@ export const pushContract = {
     config: oc.route({ method: "GET", path: "/push/config" }).input(PushConfigQuerySchema).output(PushConfigSchema),
     subscribe: oc.route({ method: "POST", path: "/push/subscribe" }).input(PushSubscriptionSchema).output(OkSchema),
     unsubscribe: oc.route({ method: "POST", path: "/push/unsubscribe" }).input(PushEndpointSchema).output(OkSchema),
-    test: oc.route({ method: "POST", path: "/push/test" }).output(OkSchema),
+    test: oc.route({ method: "POST", path: "/push/test" }).output(PushTestSchema),
 };

package/src/contracts/settings.contract.ts

@@ -1,11 +1,15 @@
 import { oc } from "@orpc/contract";
-import { CleanerSavingsSchema, OkSchema, SandboxSettingsSchema } from "../schemas.js";
+import { BuiltinPromptSchema, BuiltinPromptTextSchema, CleanerSavingsSchema, OkSchema, SandboxSettingsSchema } from "../schemas.js";
 
 // Per-sandbox agent settings (.intentic/settings.json). `get` returns the current flags with defaults applied
 // when the file is absent; `set` overwrites them. `savings` reports the output-cleaner token savings aggregated
 // from the live filter-stats ledger (the rtk-`gain` surface — read-only, so a UI card can show what's working).
+// `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),
     set: oc.route({ method: "POST", path: "/settings" }).input(SandboxSettingsSchema).output(OkSchema),
     savings: oc.route({ method: "GET", path: "/settings/savings" }).output(CleanerSavingsSchema),
+    builtinPrompt: oc.route({ method: "GET", path: "/settings/system-prompt/{base}" }).input(BuiltinPromptSchema).output(BuiltinPromptTextSchema),
 };

package/src/contracts/system.contract.ts

@@ -2,6 +2,7 @@ import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
 import { SystemEventSchema } from "../events.js";
 import {
+    DaemonSessionSchema,
     HostTunnelInputSchema,
     HostTunnelSchema,
     InfoSchema,
@@ -19,6 +20,9 @@ import {
 // connection simply never joins the roster.
 export const systemContract = {
     info: oc.route({ method: "GET", path: "/info" }).output(InfoSchema),
+    // 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.
+    session: oc.route({ method: "POST", path: "/system/session" }).output(DaemonSessionSchema),
     events: oc
         .route({ method: "GET", path: "/events" })
         .input(z.object({ clientId: z.string().optional() }))

package/src/contracts/translator.contract.ts

@@ -4,7 +4,8 @@ import { KeyedProviderSchema, OkSchema, TranslatorAccountsSchema, TranslatorComp
 
 // Routed-provider subscriptions (Sandbox ▸ Agent). The bundled translator (CLIProxyAPI) runs a non-Claude model
 // UNDER the Claude Code harness on the user's SUBSCRIPTION, so each provider connects via an OAuth login rather
-// than an API key. `accounts` reports which subscriptions are connected; `disconnect` clears a provider's tokens.
+// than an API key. A provider can hold several accounts side by side (the translator balances across them);
+// `accounts` lists what's connected per provider and `disconnect` clears ONE account by its auth-file `name`.
 //
 // Two login shapes ride one pair of routes. Codex and Grok mint a one-time device `code`: the user enters it at
 // the provider's site and the translator polls to completion in the background, so the UI just polls `accounts`
@@ -21,6 +22,6 @@ export const translatorContract = {
     complete: oc.route({ method: "POST", path: "/translator/{provider}/complete" }).input(TranslatorCompleteSchema).output(OkSchema),
     disconnect: oc
         .route({ method: "POST", path: "/translator/{provider}/disconnect" })
-        .input(z.object({ provider: KeyedProviderSchema }))
+        .input(z.object({ provider: KeyedProviderSchema, name: z.string().min(1) }))
         .output(OkSchema),
 };

package/src/contracts/workspace.contract.ts

@@ -19,9 +19,13 @@ import {
     WorkspaceFileQuerySchema,
     WorkspaceFileSchema,
     WorkspaceGraphSchema,
+    WorkspaceHealthQuerySchema,
+    WorkspaceHealthSchema,
     WorkspaceInstallResultSchema,
     WorkspaceInstallSchema,
     WorkspaceMoveSchema,
+    WorkspaceResolveQuerySchema,
+    WorkspaceResolveSchema,
     WorkspaceSetupSchema,
     WorkspaceSyncSchema,
     WorkspaceTreeSchema,
@@ -36,9 +40,17 @@ export const workspaceContract = {
     // and the client fetches them here on expand so a giant node_modules can't blow the tree walk's entry budget.
     children: oc.route({ method: "GET", path: "/workspace/children" }).input(WorkspaceChildrenQuerySchema).output(WorkspaceChildrenSchema),
     file: oc.route({ method: "GET", path: "/workspace/file" }).input(WorkspaceFileQuerySchema).output(WorkspaceFileSchema),
+    // Which file a NAMED reference means — the lookup behind every clickable path in the UI. A path an agent
+    // wrote in prose is often only a suffix of the real one, so it is matched against the workspace tree rather
+    // than trusted as root-relative.
+    resolve: oc.route({ method: "GET", path: "/workspace/resolve" }).input(WorkspaceResolveQuerySchema).output(WorkspaceResolveSchema),
     // Ranked groups, match-reason tags, freshness, resumable cursor. `mode` narrows to one verb; default is
     // auto-mode fusion. (Implementation detail: the daemon backs this with a resident in-process iq engine.)
     search: oc.route({ method: "GET", path: "/workspace/search" }).input(WorkspaceSearchQuerySchema).output(WorkspaceSearchResultSchema),
+    // One repository's health in numbers: churn × complexity per file, index totals, and the import graph's
+    // top modules — the `hotspots` and `map` rankings the CLI prints, shaped for a panel. Repo-scoped, because
+    // "the codebase" is a repo, not the whole /work drop.
+    health: oc.route({ method: "GET", path: "/workspace/health" }).input(WorkspaceHealthQuerySchema).output(WorkspaceHealthSchema),
     // Deterministic, no-LLM classification of the dropped workspace into coarse buckets (repositories / documents
     // / media / archives / other). Read-only proposal: the browser renders it and applies accepted moves via the
     // existing /workspace/move route — this route never touches the tree.

package/src/events.ts

@@ -1,5 +1,13 @@
 import { z } from "zod";
-import { AgentProviderSchema, AgentSummarySchema, PermissionModeSchema, RateLimitInfoSchema, UsageWindowSchema } from "./schemas.js";
+import {
+    AgentProviderSchema,
+    AgentReplySchema,
+    AgentSummarySchema,
+    LandConflictSchema,
+    PermissionModeSchema,
+    RateLimitInfoSchema,
+    UsageWindowSchema,
+} from "./schemas.js";
 
 // The wire shapes streamed from the daemon's event-iterator procedures. This is their canonical home: the
 // daemon yields them and the browser client consumes them from the same schema, so the two can't drift (they
@@ -72,7 +80,7 @@ export const ContextUsageSchema = z.object({
 export type ContextUsage = z.infer<typeof ContextUsageSchema>;
 
 // ACP-aligned tool taxonomy (Agent Client Protocol's ToolKind, verbatim): what a tool call *does*, driving
-// the card icon and follow-along behavior regardless of which backend named the tool.
+// the card icon and the live-writes bookkeeping regardless of which backend named the tool.
 export const ToolKindSchema = z.enum(["read", "edit", "delete", "move", "search", "execute", "think", "fetch", "other"]);
 export type ToolKind = z.infer<typeof ToolKindSchema>;
 
@@ -129,31 +137,46 @@ export type RestoredToolCall = z.infer<typeof RestoredToolCallSchema>;
 export const RestoredMessageSchema = z.object({
     role: z.enum(["user", "assistant"]),
     text: z.string(),
+    // Files the user attached to this turn (user bubbles only) as workspace-relative paths, recovered from
+    // the stored prompt's attachment note — so a reopened tab redraws chips, not the injected protocol text.
+    attachments: z.array(z.string()).optional(),
     thinking: z.string().optional(),
     tools: z.array(RestoredToolCallSchema).optional(),
 });
 export type RestoredMessage = z.infer<typeof RestoredMessageSchema>;
 
 export const SessionTranscriptSchema = z.object({ messages: z.array(RestoredMessageSchema) });
+export const AgentTranscriptSchema = SessionTranscriptSchema.extend({ sessionId: z.string().optional() });
 
 // One frame from an agent turn, relayed to the UI. `kind`-discriminated. The daemon normalizes the SDK's
 // ~40 SDKMessage types down to this union: high-value block types get a dedicated frame
 // (delta/thinking/tool_call/tool_call_update/todos/usage/rate_limit_info/account_usage/context_usage/init/compact); any SDK message
 // without a UI mapping is dropped. `plan`/`question`/`permission` pause the turn until the user answers on the
-// `POST /agent/reply` side channel; `mode` reports the live permission posture as the agent changes it.
+// `POST /agent/reply` side channel, and `resolved` releases the one it names; `mode` reports the live
+// permission posture as the agent changes it.
 // `parentToolUseId` tags frames produced inside a subagent (Task tool).
 export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("session"), sessionId: z.string() }),
-    // First frame of an isolated turn: the conversation's worktree identity — its branch (agent/<id>) and the
-    // ROOT repo's short base sha (the checkout moment). Emitted before any provider frames.
-    z.object({ kind: z.literal("worktree"), branch: z.string(), base: z.string() }),
+    /* First frame of an isolated turn: the conversation's worktree identity — its branch (agent/<id>) and the
+     * ROOT repo's short base sha (the checkout moment). Emitted before any provider frames.
+     *
+     * `unenforced` marks the degraded container: no CAP_SYS_ADMIN, so the turn's worktree could not be
+     * bind-mounted over the workspace root and the harness is rewriting tool paths into it instead. That
+     * fallback covers what arrives as tool input and not what a subprocess computes for itself, so the
+     * operator needs to know — this state used to be one line in the daemon log at boot, and the way it got
+     * noticed was files appearing in the main tree from agents that were supposed to be on branches. */
+    z.object({ kind: z.literal("worktree"), branch: z.string(), base: z.string(), unenforced: z.boolean().optional() }),
     // Emitted after a clean isolated turn whose delta auto-landed (or failed to): landed ⇒ the work is now
     // UNCOMMITTED changes in the main tree (the Changes panel is the review); conflicts ⇒ it stayed safely in
-    // the worktree — the named paths collide with the user's own edits, "Land now" recovers after they resolve.
+    // the worktree, and each named path carries WHY it would not apply (see LandConflictSchema) so the report
+    // can say whether the user's own copy is at risk or the main line simply moved on underneath the agent.
+    // held ⇒ auto-land is off for this agent: nothing was applied and nothing failed — the delta is waiting
+    // on the branch for a deliberate Land (landed is false, conflicts absent).
     z.object({
         kind: z.literal("landed"),
         landed: z.boolean(),
-        conflicts: z.array(z.object({ repo: z.string(), paths: z.array(z.string()) })).optional(),
+        conflicts: z.array(LandConflictSchema).optional(),
+        held: z.boolean().optional(),
     }),
     // The SDK's init handshake; carries the model it actually resolved for the turn.
     z.object({ kind: z.literal("init"), model: z.string() }),
@@ -227,6 +250,21 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("plan"), requestId: z.string(), text: z.string() }),
     z.object({ kind: z.literal("question"), requestId: z.string(), questions: z.array(AskQuestionSchema) }),
     PermissionAskSchema.extend({ kind: z.literal("permission"), requestId: z.string() }),
+    // The card above named by `requestId` is released — the user answered (or dismissed it, or the turn was
+    // stopped out from under it), so the turn is executing again. Emitted by whoever parked, the moment its
+    // waiter settles, because the park's END is otherwise invisible on this stream: nothing else here says
+    // "that card is done", and it cannot be inferred from the next frame that happens along. Frames DO arrive
+    // while a turn is parked — the pausing tool's own `tool_call` regularly trails its card (the SDK queues
+    // stream messages while dispatching an in-process MCP tool straight off the transport), and a card raised
+    // beside a parallel tool call sits through that tool's whole life. See agents-registry.ts, which reads
+    // this pair as the fleet's "needs you" state.
+    //
+    // `reply` says HOW it settled, and is what a transcript rebuilt from this log freezes the card with: a
+    // reload replays the run from seq 0 and a second window renders it live, so both would otherwise restore
+    // the card pending — offering buttons on a requestId nothing holds any more, under a transcript that has
+    // already moved on. It rides verbatim, exactly as the client POSTed it; absent, nobody answered (the turn
+    // was stopped, or died under the card), which is not a decision and must not replay as one.
+    z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),
     // The turn's permission mode, whenever it changes — the user's pick at turn start, then every move the
     // AGENT makes on its own (EnterPlanMode on a request that needs thinking through, ExitPlanMode once the
     // user approves). The composer's mode selector follows this, so the UI never lies about the live posture.
@@ -240,13 +278,41 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
             .enum([
                 "session-not-found",
                 "rate_limit",
+                // Codex ran the turn but warned about it (fallback model metadata) — a notice, not a failure.
+                "codex-advisory",
                 "codex-reauth",
+                // The Claude subscription credential is dead (revoked, or its refresh token rejected) and only a
+                // reconnect fixes it. Distinct from "no account connected": the account IS there, so the UI can
+                // offer reconnect where the user already is and replay the message that bounced.
+                "claude-reauth",
+                // The API refused this turn's token MID-FLIGHT — nearly always one superseded by a rotation,
+                // which Anthropic retires the moment its successor is minted. Distinct from claude-reauth: the
+                // account is fine and the daemon re-mints on the spot, so this frame is a notice about a turn
+                // that resumed itself, not a request for the user to do anything. It only reaches the client
+                // when the resume could NOT start, which is when reconnecting really is the fix.
+                "claude-token-refused",
+                // The harness read the message as a slash command it doesn't have, and discarded everything
+                // after the name — the model never saw the message. Nothing was processed, so the client holds
+                // the text back instead of leaving the user to retype it (same treatment as claude-reauth).
+                "unknown-command",
                 "grok-model-invalid",
                 "codex-model-invalid",
                 "subscription-required",
                 "agent-busy",
             ])
             .optional(),
+        // rate_limit only: when the exhausted window reopens (epoch seconds, from the stream's own
+        // rate_limit_event or the account's persisted usage windows), and what the daemon did about it —
+        // "scheduled" = auto-resume is on and this turn re-runs itself a minute after `resetsAt`;
+        // "available" = the daemon remembered the failed turn and enabling the autoResumeOnLimit setting
+        // arms that same resume, which is what the chat's offer banner hangs off. Absent together when the
+        // reset instant is unknown (nothing to schedule against).
+        resetsAt: z.number().optional(),
+        autoResume: z.enum(["scheduled", "available"]).optional(),
+        // rate_limit only: the account whose allowance is spent, as the DAEMON resolved it (the client's own
+        // selection can be empty, which means "the provider's first"). It is what lets the chat offer the
+        // provider's OTHER accounts as a resume-now instead of a wait — see /agent/resume-limit.
+        account: z.string().optional(),
     }),
     z.object({ kind: z.literal("done") }),
 ]);
@@ -283,7 +349,15 @@ export type Heartbeat = z.infer<typeof HeartbeatSchema>;
 // browser remembers it per sandbox id and drops that sandbox's persisted query cache when it changes — a wiped
 // and recreated workspace (cleanup.sh + reconnect keeps the same sandbox id) must not be painted from the
 // previous workspace's cache.
-export const HelloSchema = z.object({ kind: z.literal("hello"), workspaceId: z.string() });
+//
+// It also advertises `routes` — the contract route names (`vpn.list`, `kimi.models`) this daemon actually
+// implements, from ITS build of the contract. A browser is routinely newer than the daemon it talks to (a
+// released app plane serves whatever image each user last pulled; in local dev the web app is always ahead of
+// the last `pnpm build:sandbox`), and that stays fully supported — the browser just compares the two sets so a
+// route the daemon predates surfaces as a named, explained gap instead of a bare 404 nobody can attribute.
+// Optional: a daemon built before this field simply advertises nothing, and every route is assumed present,
+// which is exactly the pre-existing behaviour.
+export const HelloSchema = z.object({ kind: z.literal("hello"), workspaceId: z.string(), routes: z.array(z.string()).optional() });
 export type Hello = z.infer<typeof HelloSchema>;
 
 // The FULL discovered repo set (sorted root-relative ids), pushed whenever it changes — a clone, a scaffold,
@@ -325,8 +399,12 @@ export const PresenceSchema = z.object({ kind: z.literal("presence"), users: z.a
 export type Presence = z.infer<typeof PresenceSchema>;
 
 // The FULL fleet roster, broadcast on every registry change — same snapshot-not-diff contract as presence:
-// a reconnecting browser is consistent from its first frame and last frame wins.
-export const AgentsSchema = z.object({ kind: z.literal("agents"), agents: z.array(AgentSummarySchema) });
+// a reconnecting browser is consistent from its first frame. NOT simply "last frame wins", though: `rev` is the
+// registry revision the snapshot was taken at, and the browser applies a frame only if it is newer than the one
+// it already holds. Snapshots race two other sources of the same fact — an explicit GET /agents and the
+// browser's own optimistic writes — and an unordered full replace lets the slowest of them win, which is how an
+// archived card came back. See AgentsListSchema and useAgents.ts.
+export const AgentsSchema = z.object({ kind: z.literal("agents"), agents: z.array(AgentSummarySchema), rev: z.number() });
 export type Agents = z.infer<typeof AgentsSchema>;
 
 // The /events stream union: the hello identity frame, then liveness heartbeats interleaved with

package/src/hostnames.test.ts

@@ -9,6 +9,9 @@ import {
     previewHostname,
     previewLabel,
     previewUrl,
+    sandboxHostname,
+    sandboxIdFromUrl,
+    syncFolder,
 } from "./hostnames.js";
 
 const ID = "abc123def456";
@@ -35,6 +38,25 @@ test("labels are the mintable unit: hostname = <label>-<id>.<zone> for both sche
     expect(labelHostname(portLabel("a"), ID, "example.com")).toBe(portHostname("a", ID, "example.com"));
 });
 
+test("the local sync folder carries the very id the sandbox's URL does", () => {
+    const url = `https://${sandboxHostname(ID, "intentic.dev")}`;
+    expect(sandboxIdFromUrl(url)).toBe(ID);
+    expect(syncFolder("Radarsu Local", url)).toBe(`~/intentic/radarsu-local-${ID}`);
+    // A bare host (no scheme) and a port are both accepted — the daemon/CLI and the browser pass different shapes.
+    expect(sandboxIdFromUrl(`${sandboxHostname(ID, "intentic.dev")}:443`)).toBe(ID);
+    // Own-Cloudflare: the owner's chosen subdomain IS the id, so the folder still matches what they browse to.
+    expect(syncFolder("shop", "https://dev-box.example.com")).toBe("~/intentic/shop-dev-box");
+});
+
+test("sandbox ids that can't be read off a URL leave the folder named for the sandbox alone", () => {
+    expect(sandboxIdFromUrl(undefined)).toBeUndefined();
+    expect(sandboxIdFromUrl("")).toBeUndefined();
+    expect(sandboxIdFromUrl("not a url")).toBeUndefined();
+    expect(sandboxIdFromUrl("https://sandbox-.intentic.dev")).toBeUndefined();
+    expect(syncFolder("My Repo", undefined)).toBe("~/intentic/my-repo");
+    expect(syncFolder("", undefined)).toBe("~/intentic/sandbox");
+});
+
 test("preview/port URLs require both a zone and a sandbox id", () => {
     expect(previewUrl("app", "example.com", ID)).toBe(`https://preview-app-${ID}.example.com`);
     expect(portUrl("a", "example.com", ID)).toBe(`https://port-a-${ID}.example.com`);

package/src/hostnames.ts

@@ -7,7 +7,8 @@
 // the zone's SOA TTL. This module is that agreement.
 
 // The sandbox daemon's subdomain + hostname: `sandbox-<id>` / `sandbox-<id>.<zone>`.
-export const sandboxSubdomain = (id: string): string => `sandbox-${id}`;
+const SANDBOX_PREFIX = "sandbox-";
+export const sandboxSubdomain = (id: string): string => `${SANDBOX_PREFIX}${id}`;
 export const sandboxHostname = (id: string, zone: string): string => `${sandboxSubdomain(id)}.${zone}`;
 
 // The container sshd hostname the desktop-sync (Mutagen) reaches over the sandbox tunnel: `ssh-<id>.<zone>`.
@@ -73,6 +74,44 @@ export const panelFromHost = (hostHeader: string | undefined, sandboxId: string
 export const portSlotFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
     keyFromHost("port-", hostHeader, sandboxId);
 
+// The sandbox's identity AS THE USER SEES IT: the leading DNS label of its public URL, minus the `sandbox-`
+// prefix — `https://sandbox-0f310c3c4db4.intentic.dev` → `0f310c3c4db4`, i.e. sandboxIdFromToken's digest read
+// back off the wire by anyone holding only the URL. On the own-Cloudflare path the label is whatever subdomain
+// the owner chose, so that is the id there. undefined until the sandbox has a URL at all.
+export const sandboxIdFromUrl = (url: string | undefined): string | undefined => {
+    if (url === undefined || url === "") {
+        return undefined;
+    }
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
+    let label: string;
+    try {
+        label = new URL(withScheme).hostname.split(".")[0] ?? "";
+    } catch {
+        return undefined;
+    }
+    if (label === "" || label === SANDBOX_PREFIX) {
+        return undefined;
+    }
+    return label.startsWith(SANDBOX_PREFIX) ? label.slice(SANDBOX_PREFIX.length) : label;
+};
+
+// The LOCAL folder desktop sync mirrors /work into: `~/intentic/<sandbox name>-<sandboxIdFromUrl>`. Both halves
+// are strings the user already has in front of them — the name in the sandbox switcher, the id in the address
+// bar — so the folder on disk and the sandbox it mirrors read as ONE identity: `~/intentic/shop-0f310c3c4db4`
+// belongs to `https://sandbox-0f310c3c4db4.intentic.dev` and nothing else. Keyed on the URL rather than the
+// name alone for the same reason the hostname is: a torn-down sandbox recreated under the same name gets a new
+// id, hence its own fresh folder instead of reusing the dead one's (which cleanup never deletes) and colliding
+// on the two-way sync. Lives here, beside the hostname builders, because that match IS the contract.
+export const syncFolder = (name: string, url: string | undefined): string => {
+    const slug =
+        name
+            .replace(/[^a-zA-Z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .toLowerCase() || "sandbox";
+    const id = sandboxIdFromUrl(url);
+    return `~/intentic/${slug}${id === undefined ? "" : `-${id}`}`;
+};
+
 // The Cloudflare zone from a sandbox public URL (https://sandbox-<id>.<zone> → <zone>): the hostname minus its
 // first DNS label. undefined when the URL is unparsable OR the hostname has fewer than three labels (no zone
 // suffix to strip — e.g. a 2-label host would otherwise yield a bare TLD). Accepts scheme-less input too, so it

package/src/index.ts

@@ -1,3 +1,5 @@
+import type { ContractRoute } from "./routes.js";
+import { contractRoutes, routeNameForRequest } from "./routes.js";
 import { activityContract } from "./contracts/activity.contract.js";
 import { agentContract } from "./contracts/agent.contract.js";
 import { agentsContract } from "./contracts/agents.contract.js";
@@ -15,6 +17,7 @@ import { intenticContract } from "./contracts/intentic.contract.js";
 import { inventoryContract } from "./contracts/inventory.contract.js";
 import { kimiContract } from "./contracts/kimi.contract.js";
 import { logsContract } from "./contracts/logs.contract.js";
+import { memoryContract } from "./contracts/memory.contract.js";
 import { panelsContract } from "./contracts/panels.contract.js";
 import { portsContract } from "./contracts/ports.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
@@ -44,6 +47,7 @@ export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
 export { kimiContract } from "./contracts/kimi.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
+export { memoryContract } from "./contracts/memory.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";
 export { pushContract } from "./contracts/push.contract.js";
@@ -58,11 +62,15 @@ export { workspaceContract } from "./contracts/workspace.contract.js";
 export * from "./effects.js";
 export * from "./events.js";
 export * from "./sse.js";
+export * from "./routes.js";
 export * from "./agent-catalog.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";
+export * from "./path-refs.js";
+export * from "./quick-model.js";
 export * from "./schemas.js";
 export * from "./terminal-protocol.js";
+export * from "./title.js";
 
 // The aggregated contract — implemented on the server by the per-domain route factories and consumed by the
 // browser's typed oRPC client (ContractRouterClient<typeof sandboxContract>). The wire paths it declares are
@@ -88,6 +96,7 @@ export const sandboxContract = {
     workspace: workspaceContract,
     inventory: inventoryContract,
     logs: logsContract,
+    memory: memoryContract,
     panels: panelsContract,
     ports: portsContract,
     push: pushContract,
@@ -97,3 +106,14 @@ export const sandboxContract = {
     usage: usageContract,
     vpn: vpnContract,
 };
+
+// Every route in THIS build of the contract, and the names the daemon advertises on its hello frame. Bound here
+// rather than in routes.ts so that module stays a pure function of whatever contract it is handed — importing
+// `sandboxContract` from there would close a load-time cycle back through this file. See routes.ts for why a
+// daemon advertises its route surface at all.
+export const SANDBOX_ROUTES: readonly ContractRoute[] = contractRoutes(sandboxContract);
+export const SANDBOX_ROUTE_NAMES: readonly string[] = SANDBOX_ROUTES.map((route) => route.name);
+
+// The contract route a concrete browser request belongs to, bound to this build's route table.
+export const sandboxRouteName = (method: string, pathWithQuery: string): string | undefined =>
+    routeNameForRequest(SANDBOX_ROUTES, method, pathWithQuery);