@intentic/sandbox-contract 1.248.0 → 1.250.0

package/src/schemas/workspace-search.ts

@@ -1,13 +1,9 @@
 import { z } from "zod";
-// The workspace-search wire shape, shared by the daemon's /workspace/search route and the web client.
-// (Implementation detail, not part of the contract: the daemon backs this route with a resident in-process iq
-// engine; the engine is interchangeable behind this shape.) Groups are relevance-ranked (best first, never path
-// order); each hit carries the match-reason tags the fused engines contributed, and the char spans within `text`
-// that matched, so clients highlight without re-finding the needle.
+// Shared by /workspace/search and the web client. Groups rank by relevance, best first; each hit carries match tags and
+// the char spans in `text`, for highlighting without a re-find.
 export const WorkspaceSearchQuerySchema = z.object({
     query: z.string().min(2).max(512).describe("What to look for. Plain words, a pattern, a symbol name, or a question."),
-    // Search verbs only, anchor/git verbs (outline, context, log, who, …) are CLI-only surface. Natural language
-    // has no verb of its own: `q` classifies the query and answers it semantically when the words call for it.
+    // Search verbs only; anchor/git verbs are CLI-only. Natural language needs none, `q` classifies it.
     mode: z
         .enum(["q", "find", "files", "def", "refs", "sym", "ast"])
         .optional()
@@ -15,16 +11,11 @@ export const WorkspaceSearchQuerySchema = z.object({
             "Narrow the search to one kind: plain text, filenames, definitions, references, symbols, or code structure. Leave it out to blend them, which also answers a question asked in words.",
         ),
     includeIgnored: z.stringbool().optional().describe("Search inside installed packages and other ignored folders too."),
-    // How `find` reads the query, the three switches every editor's search box has (VSCode: Aa, ab, .*).
-    // `literal` treats it as fixed text instead of a regex; `caseSensitive` off means case-INSENSITIVE, not
-    // ripgrep's smart case.
+    // The three switches every search box has; caseSensitive off means case-insensitive, not ripgrep's smart case.
     literal: z.stringbool().optional().describe("Treat the query as fixed text rather than a pattern."),
     word: z.stringbool().optional().describe("Match whole words only."),
     caseSensitive: z.stringbool().optional().describe("Whether capitals matter. Off means they do not, rather than being guessed at from the query."),
-    // Which FILES the query is asked of, in VSCode's files-to-include grammar, as TYPED, because the reading
-    // of it is shared (search-globs.ts) rather than each end guessing: comma-separated patterns, each matched
-    // at any depth unless `./` anchors it, a leading `!` excluding instead. Distinct from `includeIgnored`,
-    // which decides whether the ignored layers are searched at all, this narrows within what that admitted.
+    // Files-to-include grammar: comma-separated patterns, any depth unless `./`-anchored, leading ! excludes.
     include: z
         .string()
         .max(512)
@@ -52,15 +43,14 @@ export type WorkspaceSearchSpan = z.infer<typeof WorkspaceSearchSpanSchema>;
 export const WorkspaceSearchHitSchema = z.object({
     line: z.number().describe("Which line, counting from one."),
     text: z.string().describe("The line itself."),
-    // Every matched span in `text`, in order, a text search marks all of them, the way an editor does. Empty
-    // where the LINE is the match and no span of it is (a semantic or definition hit reports none).
+    // Every matched span in text, in order; empty when the whole line is the match, not part of it.
     spans: z
         .array(WorkspaceSearchSpanSchema)
         .describe(
             "Where in the line the matches are, so you can highlight without searching again. Empty when the whole line is the match rather than part of it.",
         ),
     tags: z.array(WorkspaceSearchTagSchema).describe("Why it matched."),
-    // Enclosing symbol ("createWidget (fn)"), parent-document context so the reader often needs no follow-up.
+    // Enclosing symbol or heading; often enough on its own, no need to open the file.
     context: z
         .string()
         .optional()
@@ -71,22 +61,20 @@ export const WorkspaceSearchGroupSchema = z.object({
     path: z.string().describe("The file."),
     score: z.number().describe("How well it matched. Groups arrive best first, never in path order."),
     hits: z.array(WorkspaceSearchHitSchema).describe("The matching lines in it."),
-    // This file had more matching lines than the engine keeps per file, so `hits` is a floor, a panel showing a
-    // per-file count has to say "50+" rather than "50".
+    // This file had more matches than kept per file; the count is a floor (say "50+", not "50").
     capped: z
         .boolean()
         .optional()
         .describe("This file had more matches than are kept per file, so the count is a floor. Say fifty-plus rather than fifty."),
 });
 export type WorkspaceSearchGroup = z.infer<typeof WorkspaceSearchGroupSchema>;
-// `building` = index still filling (progress 0..1, e.g. embeddings pending); `stale` = revalidation was skipped
-// (cursor replay). ageMs = time since the index last matched the disk state.
+// building means the index is still filling (progress 0..1); stale means revalidation was skipped. ageMs is time since
+// the index last matched disk.
 export const WorkspaceSearchFreshnessSchema = z.object({
     state: z.enum(["fresh", "building", "stale"]).describe("Whether the index matches what is on disk, is still filling, or has fallen behind."),
     ageMs: z.number().optional().describe("How long since it last matched the disk, in milliseconds."),
     progress: z.number().optional().describe("How far through building it is, from zero to one."),
-    // How many files the index has not caught up with, when it is stale. A count is reportable; "stale" alone
-    // reads as a warning about the answer, which it almost never is.
+    // How many files it hasn't caught up with; worth showing since "stale" alone reads as a warning.
     behind: z
         .number()
         .optional()
@@ -98,15 +86,13 @@ export type WorkspaceSearchFreshness = z.infer<typeof WorkspaceSearchFreshnessSc
 export const WorkspaceSearchResultSchema = z.object({
     mode: z.string().describe("Which kind of search actually ran, which matters when you let it choose."),
     total: z.number().describe("Matching lines across the whole workspace, not just this page."),
-    // Files the query matched in total, which `groups` reports only for the page it carries, the count a
-    // results panel puts beside the hit total ("218 results in 61 files").
+    // Files matched in total; `groups` only reports the ones on this page.
     files: z.number().describe("Files the query matched in total."),
     shown: z.number().describe("How many of those lines are on this page."),
     groups: z.array(WorkspaceSearchGroupSchema).describe("The results, grouped by file, best first."),
     freshness: WorkspaceSearchFreshnessSchema.describe("Whether the index behind the answer is up to date."),
     truncated: z.boolean().describe("This page is not all of it. Use the cursor."),
-    // `total` is a FLOOR: at least one file had more matches than the engine keeps per file. Distinct from
-    // `truncated`, which is about this PAGE, a result can be complete on the page and still count partially.
+    // A floor: some file had more matches than kept per file. Distinct from truncated, which is about the page.
     partial: z
         .boolean()
         .optional()
@@ -115,27 +101,23 @@ export const WorkspaceSearchResultSchema = z.object({
         ),
     cursor: z.string().optional().describe("Pass this back as `after` to get the next page."),
     hint: z.string().optional().describe("A suggestion for getting a better answer out of this query."),
-    // What the engine did with the query that the query did not ask for, a pattern rerun as literal text
-    // because it is not valid regex, grep-style escapes rewritten, a language filter that matched no files. The
-    // text surface has always printed this above the results; a JSON caller could not see it at all.
+    // What the engine did unasked: a pattern rerun as literal, escapes rewritten, or a filter matching nothing.
     note: z
         .string()
         .optional()
         .describe(
             "What the engine did that you did not ask for: a pattern rerun as plain text because it was not valid, escapes rewritten, a language filter that matched nothing.",
         ),
-    // Code-graph neighbors of the top hits (definition anchors + the strongest caller of each).
+    // Code-graph neighbors of the top hits: definition anchors and each one's strongest caller.
     related: z.array(z.string()).optional().describe("Places next door to the best results: where each is defined, and whatever calls it most."),
-    // Ranked `path:line` anchors that placed but were NOT shown, best first, the answer often sits at rank 5–13,
-    // behind groups the budget spent itself on. The text surface has always printed this map; a JSON caller could
-    // not see it, so it had to page through `cursor` to learn what the terminal was told up front.
+    // Ranked path:line anchors that placed but weren't shown, best first; the answer often sits at rank 5-13.
     candidates: z
         .array(z.string())
         .optional()
         .describe(
             "Ranked places that scored but did not make the page, best first. The answer often sits at rank five to thirteen, so this saves paging through to find out.",
         ),
-    // Run provenance for benchmarking: retrieval stages DISABLED this invocation (absent = full pipeline).
+    // Retrieval stages disabled for this run, for benchmarking; absent means the full pipeline ran.
     features: z.array(z.string()).optional().describe("Which stages of the search were switched off for this run. Absent means all of them ran."),
 });
 export type WorkspaceSearchResult = z.infer<typeof WorkspaceSearchResultSchema>;

package/src/schemas/workspace-setup.ts

@@ -1,14 +1,7 @@
 // workspace setup (dependency readiness)
 import { z } from "zod";
-// One project under /work and whether its dependencies are actually installed. A drop omits node_modules/.venv
-// on purpose, so a freshly imported project is present-but-unusable until this says "ready", the import UI,
-// the agent's post-edit type-check, and the agent's turn context all gate on it.
-// `dir` is root-relative ("" = the workspace root itself); `manager` is the real binary (pnpm/npm/uv/…);
-// `evidence` is the file that decided it ("pnpm-lock.yaml"), so the UI can show WHY, not just what.
-// state: ready | installing | needs-setup | unsupported (manager absent from this sandbox, `manager` names it)
-//      | stale, installed ONCE and since outgrown: the manifests declare dependencies that are not on disk,
-//        which is what an agent leaves behind when it adds one and does not install it. Same command fixes it,
-//        so `missing` (how many names cannot resolve) is what separates the two in the UI's wording.
+// Whether a project's dependencies are actually installed; a checkout omits node_modules/.venv, so an import is
+// unusable until this reads ready. Gates the import UI, the post-edit type-check, and turn context.
 export const ProjectSetupSchema = z.object({
     dir: z.string().describe("Where the project is, relative to the workspace root. Empty means the root itself."),
     ecosystem: z.enum(["node", "python"]).describe("Which language's tooling it uses."),
@@ -27,8 +20,8 @@ export const WorkspaceSetupSchema = z.object({
     projects: z.array(ProjectSetupSchema).describe("Every project the sandbox found, and whether each is usable."),
 });
 export type WorkspaceSetup = z.infer<typeof WorkspaceSetupSchema>;
-// Install these projects' dependencies. Dirs already ready, already installing, or whose manager is missing are
-// skipped server-side, so a stale client list can't spawn redundant installs, `started` is what actually ran.
+// Dirs already ready, installing, or with no manager are skipped server-side, so a stale client list can't spawn
+// redundant installs; queued is what actually ran.
 export const WorkspaceInstallSchema = z.object({
     dirs: z
         .array(z.string().max(500))

package/src/schemas/workspace-tree.ts

@@ -1,51 +1,20 @@
 // workspace tree + files
 import { z } from "zod";
 import { ConversationIdSchema } from "./agent.js";
-/* WHOSE COPY OF THE WORKSPACE A READ MEANS, the half of a file address that used to be implicit, and wrong.
- *
- * There is not one workspace. There is the shared /work tree, and there is one private checkout per isolated
- * conversation, each holding files that conversation created and versions of files it edited. Every workspace
- * read route named a PATH and nothing else, so it could only ever answer from the shared tree, and an agent
- * that had just written `docs/plan.md` in its own checkout described a file the viewer could not open, while
- * an agent that had EDITED a file got something worse: the shared version, same path, different text, with
- * nothing to say so.
- *
- * So the conversation rides the request. Absent ⇒ the shared tree, which is what every existing caller means
- * and why the field is optional rather than a second set of routes. Present ⇒ that conversation's own
- * checkout, resolved daemon-side in ONE place (workspaceRootFor) so the escape guard, the control-plane
- * denylist and the ignore rules apply to it exactly as they do to /work.
- *
- * A conversation that is not isolated resolves BACK to the shared tree rather than failing: the shared tree
- * genuinely is its tree, and a caller should not have to know which mode a conversation runs in to link to a
- * file in it. */
+// Which copy of the workspace a read means: the shared /work tree, or (if `agent` is set) that conversation's own
+// checkout, resolved in one place so the escape guard, denylist and ignore rules apply the same either way.
 export const WorkspaceScopeSchema = z.object({
     agent: ConversationIdSchema.optional().describe(
         "Read a conversation's own private copy of the workspace rather than the shared tree. Leave it out for the shared tree. A conversation that is not working privately resolves back to the shared tree rather than failing, so a link need not know which mode it runs in.",
     ),
 });
 export type WorkspaceScope = z.infer<typeof WorkspaceScopeSchema>;
-/* One node of the full /work filesystem tree the agent sees (untracked + generated files included), distinct
- * from the git-tracked listing. `path` is root-relative with forward slashes so it feeds straight back to the
- * file route.
- *
- * Recursive, and the type is declared rather than inferred. Zod's getter form does infer one, but it collapses
- * to `{}` below the first level of nesting, so `entry.children[0].name` type-checked as an index-signature
- * read on both sides of the wire, and the tree walker's own suite was reading a `hidden` field off entries
- * that has never existed there without the compiler minding. The interface is the contract; the schema
- * validates against it, and z.ZodType makes a divergence between the two an error here. */
-/* A SYMLINK, as the tree reports one. Present only on entries that are links; `type` beside it is the type of
- * whatever the link POINTS AT, so a link to a directory expands and a link to a file opens, exactly like the
- * real thing (the model VSCode uses, its FileType carries SymbolicLink as a bit alongside File/Directory,
- * precisely so every consumer can keep asking "file or folder?").
- *
- * `to` is the link's own text, verbatim, `../../.agents/skills/discord`, not the resolved path. That is what
- * the row shows on hover, because it is what the person who made the link wrote and what they would edit.
- *
- * `state` is absent for the ordinary case: it resolves, and it resolves to somewhere inside the workspace.
- *   - "broken", nothing at the other end. Listed anyway, because a dangling link is a fact about the
- *     workspace worth seeing rather than an entry to hide.
- *   - "outside", it resolves to bytes outside the workspace. The daemon will not read, list or descend
- *     through it (workspace-files.ts realWithin), so the row is shown and refused, like a locked one. */
+// path is root-relative with forward slashes, feeding straight into the file routes. The interface is declared by hand:
+// zod's inferred type for this recursive getter collapses to `{}` past the first level.
+// `type` alongside a link is its target's type, so a directory link opens like a directory. `to` is the link's literal
+// text, verbatim, what hovering shows and what the author would edit.
+// broken: nothing at the other end; listed anyway.
+// outside: resolves outside the workspace; shown but refused, like a locked entry.
 export interface WorkspaceLink {
     readonly to: string;
     readonly state?: "broken" | "outside" | undefined;
@@ -66,13 +35,11 @@ export interface WorkspaceTreeEntry {
     readonly path: string;
     readonly type: "file" | "dir";
     readonly size?: number | undefined;
-    // Ignored-by-tooling (node_modules, .git, .gitignore'd paths, browser profiles): the client grays the row.
+    // Ignored by tooling (node_modules, .git, gitignored paths, browser profiles); client greys the row.
     readonly ignored?: boolean | undefined;
-    // Set when this entry is a symlink, `type` above is then its TARGET's type. See WorkspaceLink.
+    // Set when this entry is a symlink; `type` above is then its target's type.
     readonly link?: WorkspaceLink | undefined;
-    // A DIR without `children` was listed but not descended into, because it's ignored, or because the walk's
-    // breadth-first budget stopped above it. Either way the client lazy-loads it via /workspace/children on
-    // expand, so "not loaded yet" and "empty directory" (`children: []`) stay distinguishable.
+    // Absent means not descended (ignored or budget-stopped); lazy-load via /workspace/children, distinct from [].
     readonly children?: readonly WorkspaceTreeEntry[] | undefined;
 }
 export const WorkspaceTreeEntrySchema: z.ZodType<WorkspaceTreeEntry> = z.object({
@@ -97,14 +64,9 @@ export const WorkspaceTreeEntrySchema: z.ZodType<WorkspaceTreeEntry> = z.object(
 export const WorkspaceTreeSchema = z.object({
     root: z.string().describe("The path everything below is relative to."),
     tree: z.array(WorkspaceTreeEntrySchema).describe("The workspace, one entry per file and folder."),
-    // How many of the ROOT's own entries the budget cut (0 = complete); per-dir cuts are counted on each dir entry.
+    // How many of the root's own entries the budget cut (0 = complete); per-dir cuts count on each dir entry.
     hidden: z.number().describe("How many entries at the top level were cut for size. Zero means the listing is complete."),
-    /* Every folder holding nothing but empty folders, root-relative, in tree order. Answered by its own walk
-     * (workspace/empty-dirs.ts) precisely because it must NOT be read off `tree` above: that listing stops at
-     * the entry budget, so a directory below the cut arrives without `children`, which means "not looked at",
-     * and the emptiness question would silently shrink to whatever the budget happened to reach, the workspace
-     * root and little else. This list is complete, and it says nothing about whether the folders in it were
-     * listed. */
+    // From its own walk (empty-dirs.ts), not derived from `tree`, which stops at budget and would undercount.
     barren: z
         .array(z.string())
         .describe(
@@ -112,9 +74,8 @@ export const WorkspaceTreeSchema = z.object({
         ),
 });
 export type WorkspaceTree = z.infer<typeof WorkspaceTreeSchema>;
-// Lazy-load one directory's children, for a dir the tree walk listed but didn't descend into. The ordinary
-// request is one level; a bounded `depth` lets a caller that genuinely needs a small subtree receive its
-// descendants in the same flat `entries` list instead of issuing one request per directory.
+// Lazy-loads one directory's children past the tree walk's budget; depth reads several levels into one flat `entries`
+// list instead of one request per directory.
 export const WorkspaceChildrenQuerySchema = WorkspaceScopeSchema.extend({
     path: z.string().min(1).describe("The folder to open, as a workspace path."),
     depth: z.coerce
@@ -134,25 +95,20 @@ export const WorkspaceChildrenSchema = z.object({
     hidden: z.number().describe("How many entries were cut for size. Zero means the listing is complete."),
 });
 export type WorkspaceChildren = z.infer<typeof WorkspaceChildrenSchema>;
-// Write routes (delete) and the read they mirror. No scope: a conversation's own checkout is READ-ONLY through
-// the file API, see workspaceRootFor for why the refusal lives daemon-side rather than in each screen.
+// Write routes (delete) and the read they mirror. No scope: a conversation's own checkout is read-only through the file
+// API, refused daemon-side.
 export const WorkspaceFileQuerySchema = z.object({ path: z.string().min(1).describe("The file or folder, as a workspace path.") });
 export const WorkspaceMediaTicketQuerySchema = WorkspaceScopeSchema.extend({
     path: z.string().min(1).describe("The media file the ticket should cover."),
 });
-/* The credential a <video>/<audio> element carries to GET /workspace/media, which is the one workspace route a
- * browser cannot put a header on. Minted here, over the ordinary bearer-authenticated contract, and scoped to
- * the single FILE it was asked for, the resolved one, so a ticket minted against a conversation's checkout
- * buys that file and not its shared-tree namesake (see auth/media-tickets.ts for why scope rather than
- * single-use is what bounds it). `expiresAt` is epoch ms so a player can tell a dead ticket from a dead file. */
+// Credential for <video>/<audio>'s GET /workspace/media, the one route a browser can't header-authenticate. Scoped to
+// the resolved file, so a ticket minted against a checkout can't buy its shared-tree namesake.
 export const WorkspaceMediaTicketSchema = z.object({
     ticket: z.string().describe("Hand this to the streaming route in the query string. It buys exactly the one file it was minted for."),
     expiresAt: z.number().describe("When it stops working, in milliseconds, so a player can tell a dead ticket from a dead file."),
 });
-/* A text read is a read of a WINDOW: `offset` is the byte to start at (negative reads that many bytes from the
- * END, which is what following a growing log means, the tail's offset isn't knowable until the size is), and
- * `limit` how many bytes to serve. The daemon clamps `limit` to its own cap, so an omitted or oversized one is
- * the cap rather than the file. Coerced: these arrive as query strings. */
+// A read of a window: offset negative reads that many bytes from the end (for following a growing log); limit is
+// clamped to the daemon's own cap. Coerced from query strings.
 export const WorkspaceFileReadQuerySchema = WorkspaceScopeSchema.extend({
     path: z.string().min(1).describe("The file to read, as a workspace path."),
     offset: z.coerce
@@ -171,8 +127,8 @@ export const WorkspaceFileReadQuerySchema = WorkspaceScopeSchema.extend({
             "How many bytes to read. Capped by the sandbox, so leaving it out or asking for too much gives you the cap rather than the whole file.",
         ),
 });
-// `size` is the whole file; `offset`/`bytes` the byte range `content` decodes from, so the reader can tell a
-// window from a whole file (offset > 0 || offset + bytes < size ⇒ there is more) and ask for the next one.
+// size is the whole file; offset/bytes is the window content decodes from. offset > 0 || offset + bytes < size means
+// there is more to read.
 export const WorkspaceFilePresentSchema = z.object({
     present: z.literal(true).describe("There is something at that path."),
     path: z.string().describe("The path, as asked for."),
@@ -180,26 +136,15 @@ export const WorkspaceFilePresentSchema = z.object({
     size: z.number().describe("How large the whole file is. Compare it with the window below to know whether there is more."),
     offset: z.number().describe("Which byte the window starts at."),
     bytes: z.number().describe("How many bytes the window holds."),
-    // Which tree answered. Always true when no `agent` was asked for; true DESPITE one when that conversation's
-    // checkout doesn't carry the path (see scopedTarget, its checkout is not a superset of /work), which is
-    // the one case the reader has to be told about rather than left to assume.
+    // True when no conversation was named, or one was but its checkout lacks the file, worth flagging.
     shared: z
         .boolean()
         .describe(
             "Which tree answered. True when no conversation was named, and also when one was but its own copy has no such file, which is the case a reader has to be told about rather than left to assume.",
         ),
 });
-/* NOTHING TO READ AT THAT PATH, an ANSWER, not a failure, which is the whole reason this branch exists.
- *
- * Most reads in this product are "read it if it is there": the file each extension keeps of what its badge has
- * already shown, a repo's documentation index, a run's result, a directory's own UI document. Absent is their
- * ordinary FIRST state, and every one of them already treats it as a value. Answering those with a 404 made the
- * browser log a failed request per read, around a dozen red lines on every page load, none of which meant
- * anything was wrong, and none of which a `catch` can suppress: the log happens in the network stack before any
- * JavaScript sees the response.
- *
- * A read that is REFUSED (an escape, the control plane, a denylisted path) is still an error, because that is a
- * real answer about the caller rather than about the file. */
+// Nothing there is an answer, not a failure: most reads here are read-it-if-there, and a 404 would spam the browser's
+// network log per miss. A refused read (an escape, a denylisted path) is still an error.
 export const WorkspaceFileAbsentSchema = z.object({
     present: z
         .literal(false)
@@ -209,10 +154,8 @@ export const WorkspaceFileAbsentSchema = z.object({
     path: z.string().describe("The path, as asked for."),
 });
 export const WorkspaceFileSchema = z.discriminatedUnion("present", [WorkspaceFilePresentSchema, WorkspaceFileAbsentSchema]);
-// Resolve a file reference an agent (or a compiler, or a terminal) NAMED to the workspace path it means. Prose
-// paths are routinely partial, a model that has been discussing `_editor/web/src` writes
-// `pages/workspace/Foo.vue`, so a clickable mention has to be matched as a path SUFFIX against the real tree,
-// not read as root-relative. `path` is absent when nothing in the workspace ends in that reference.
+// Resolves a possibly-partial path reference (a model's mention, a compiler's path) to the real workspace path it
+// means, matched as a suffix.
 export const WorkspaceResolveQuerySchema = WorkspaceScopeSchema.extend({
     path: z
         .string()
@@ -225,17 +168,15 @@ export const WorkspaceResolveQuerySchema = WorkspaceScopeSchema.extend({
 export const WorkspaceResolveSchema = z.object({
     path: z.string().optional().describe("The real path it means. Absent when nothing in the workspace ends that way."),
 });
-// Direct file management over the /work tree (delete / new folder / rename+move / copy). Byte writes + the
-// editor's text save go through the plain POST /workspace/upload route (a body doesn't fit oRPC), not here.
+// Direct file management (delete, new folder, rename/move, copy). Byte writes and editor saves go through POST
+// /workspace/upload instead, since oRPC can't carry a body.
 export const WorkspaceDirSchema = z.object({ path: z.string().min(1).describe("The folder to create. Missing folders above it are created too.") });
 export const WorkspaceMoveSchema = z.object({
     from: z.string().min(1).describe("What to move or copy, as a workspace path."),
     to: z.string().min(1).describe("Where it should end up. Changing only the last part is how you rename something."),
 });
-// Deterministic (no-LLM) classification of the dropped workspace: each repo dir and loose file sorted into one
-// coarse bucket. Read-only, the browser turns it into a proposed layout and applies the accepted moves via the
-// existing /workspace/move route. `reason` records the winning signal (magic:<mime>, ext:<ext>,
-// repository:<marker>, text-content, unknown) so the proposal is explainable.
+// Deterministic, no-LLM classification into coarse buckets, read-only, applied via /workspace/move. reason is the
+// winning signal: magic:<mime>, ext:<ext>, repository:<marker>, text-content, or unknown.
 export const WorkspaceBucketSchema = z.enum(["repositories", "documents", "media", "archives", "other"]);
 export type WorkspaceBucket = z.infer<typeof WorkspaceBucketSchema>;
 export const WorkspaceClassificationSchema = z.object({

package/src/state/arrival.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { NeedsActionSchema } from "../policy/needs-action.js";
+
+// Anything entering the sandbox, any source or format, goes through one pipeline: source to plan (ticked by the owner),
+// apply (re-derived from the held bytes), report (what landed). The outbound half lives in definition.ts and
+// schemas/environment.ts.
+
+// Two assistant members rather than one "foreign", so the checklist can badge the source by name.
+export const ArrivalSourceSchema = z.enum(["definition", "bundle", "hermes", "openclaw"]);
+export type ArrivalSource = z.infer<typeof ArrivalSourceSchema>;
+
+// Narrower than ArrivalSource: a connected device is scanned for these two only, never for a bundle.
+export const AssistantSourceSchema = z.enum(["hermes", "openclaw"]);
+export type AssistantSource = z.infer<typeof AssistantSourceSchema>;
+
+// What an item becomes here, not what it was there: the apply dispatches on this and the checklist groups by it. One
+// enum across every source, so a repo means the same thing whichever way it arrived.
+export const ArrivalGroupSchema = z.enum([
+    // The /work tree as a whole, cloned from the remote a definition's `[workspace]` names.
+    "workspace",
+    // One repository: cloned from its remote, or unpacked with its real git dir from a bundle.
+    "repo",
+    // Loose files landing in /work: a bundle's workspace bytes, an assistant's notes folder.
+    "files",
+    // Transcripts, checkpoint timelines, ledgers. Bundle-only — nothing else can reference them.
+    "history",
+    // The overlay Dockerfile.
+    "environment",
+    // One connection, landing unauthenticated unless its secret travelled.
+    "capability",
+    // The agent settings that differ from their defaults.
+    "settings",
+    // A merge into the workspace's memory file.
+    "memory",
+    "skill",
+    "automation",
+    // One credential VALUE, and the only group gated behind the apply's second consent.
+    "secret",
+]);
+export type ArrivalGroup = z.infer<typeof ArrivalGroupSchema>;
+
+// Two flags, not one: the four sources fail an item for two different reasons.
+// applicable: false when the target already holds this; it cannot be ticked.
+// recommended: false when it can be ticked but the reader should look first.
+export const ArrivalItemSchema = z.object({
+    // Deterministic, derived from the artifact ("repo:intentic"), so a re-derived plan names the same items.
+    id: z.string(),
+    group: ArrivalGroupSchema,
+    // The checklist line in plain words ("Repository intentic", "Skill, weather").
+    label: z.string(),
+    detail: z.string().optional(),
+    applicable: z.boolean(),
+    // Why it cannot be ticked; present exactly when applicable is false.
+    reason: z.string().optional(),
+    recommended: z.boolean(),
+    // Names of secrets this row would store, never values; moves only when apply sets includeSecrets.
+    secrets: z.array(z.string()),
+});
+export type ArrivalItem = z.infer<typeof ArrivalItemSchema>;
+
+export const ArrivalPlanSchema = z.object({
+    source: ArrivalSourceSchema,
+    // Names the held artifact for apply; minted per plan, a new plan replaces the held one.
+    token: z.string(),
+    // What the artifact calls itself (a definition's name, a bundle's source sandbox); for display only.
+    name: z.string().optional(),
+    items: z.array(ArrivalItemSchema),
+    // Whether the artifact holds credential values at all; the card only asks the second consent when true.
+    carriesSecrets: z.boolean(),
+    // What the reader saw but won't offer (sessions, logs, pairing state, a refused entry); listed, not silent.
+    refused: z.array(z.string()),
+    // Known not to move mechanically, shown at preview so the owner ticks knowingly, and again in the report.
+    needsAction: z.array(NeedsActionSchema),
+});
+export type ArrivalPlan = z.infer<typeof ArrivalPlanSchema>;
+
+export const ArrivalApplySchema = z.object({
+    token: z.string(),
+    // The ticked ids; ones missing from the re-derived plan are ignored rather than erroring.
+    items: z.array(z.string()),
+    // The owner's explicit consent to move credential values, asked once on the inbound side, for every source.
+    includeSecrets: z.boolean(),
+});
+export type ArrivalApply = z.infer<typeof ArrivalApplySchema>;
+
+export const ArrivalReportSchema = z.object({
+    applied: z.array(z.object({ id: z.string(), group: ArrivalGroupSchema, label: z.string() })),
+    // Ticked but didn't land, each with its reason; distinct from refused rows, which were never attempted.
+    failed: z.array(z.object({ id: z.string(), label: z.string(), error: z.string() })),
+    refused: z.array(z.string()),
+    needsAction: z.array(NeedsActionSchema),
+});
+export type ArrivalReport = z.infer<typeof ArrivalReportSchema>;
+
+// One of the owner's own devices: the daemon walks its home folder over the socket it already holds, no packing needed.
+// found absent means connected with nothing to bring in, not an error.
+export const ArrivalHostSchema = z.object({
+    id: z.string(),
+    online: z.boolean(),
+    found: AssistantSourceSchema.optional(),
+    // Why this machine can't be read right now (asleep, or its own refusal), in its own words.
+    detail: z.string().optional(),
+});
+export type ArrivalHost = z.infer<typeof ArrivalHostSchema>;
+export const ArrivalHostsSchema = z.object({ hosts: z.array(ArrivalHostSchema) });
+
+// Reads a setup off a connected device instead of an upload; answers with a plan exactly like the upload door does.
+export const ArrivalScanSchema = z.object({ host: z.string().min(1) });
+export type ArrivalScan = z.infer<typeof ArrivalScanSchema>;

package/src/state/contract-lock.test.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { expect, test } from "vitest";
+import { currentLock } from "./contract-lock.js";
+
+// contract.lock.json must match the exported schemas; the git-aware half of this check lives in contract-shrink.mjs.
+// Needs 30s: serializing ~500 schemas can run past vitest's 5s hang-detector default under load.
+test("contract.lock.json matches the schemas this package exports", { timeout: 30_000 }, () => {
+    const committed: unknown = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "contract.lock.json"), "utf8"));
+    expect(
+        currentLock(),
+        "the wire contract moved — run `pnpm --filter @intentic/sandbox-contract lock` and commit contract.lock.json with this change. " +
+            "If a schema or field was removed or changed (not added), land it as a `type!:` commit with a `Breaking-Note:` trailer " +
+            "saying, in the user's words, what stops working and what to do instead.",
+    ).toEqual(committed);
+});

package/src/state/contract-lock.ts

@@ -0,0 +1,49 @@
+// contract.lock.json is every exported schema serialized to canonical JSON Schema, so git can flag a wire-contract
+// change. contract-shrink demands a `!` commit with a Breaking-Note when a schema, field or type shrinks; additions
+// pass freely. Derived from the package's exports, not a hand-kept list.
+
+import { z } from "zod";
+import * as contract from "../index.js";
+
+// Canonical key order so two runs are byte-identical and a diff is a real contract change, not key-order noise. Arrays
+// keep zod's own (stable) order.
+const sorted = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+        return value.map(sorted);
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(
+            Object.keys(value)
+                .sort()
+                .map((key) => [key, sorted((value as Record<string, unknown>)[key])]),
+        );
+    }
+    return value;
+};
+
+export const currentLock = (): Record<string, unknown> => {
+    const lock: Record<string, unknown> = {};
+    for (const name of Object.keys(contract).sort()) {
+        const value = (contract as Record<string, unknown>)[name];
+        if (!(value instanceof z.ZodType)) {
+            continue;
+        }
+        try {
+            const schema = sorted(z.toJSONSchema(value, { unrepresentable: "any" })) as Record<string, unknown>;
+            // The dialect banner is identical on every entry; pure weight, no signal.
+            delete schema["$schema"];
+            lock[name] = schema;
+        } catch {
+            // Holds a place even when unserializable: appearing, disappearing or becoming serializable is still a diff.
+            lock[name] = "<unserializable>";
+        }
+    }
+    return lock;
+};
+
+// One line per schema, not pretty-printed: keeps the lock short enough that a diff shows which surfaces moved.
+// Path-level detail lives in the lock test and contract-shrink instead.
+export const serializeLock = (lock: Record<string, unknown>): string =>
+    `{\n${Object.entries(lock)
+        .map(([name, schema]) => `${JSON.stringify(name)}: ${JSON.stringify(schema)}`)
+        .join(",\n")}\n}\n`;