@intentic/sandbox-contract 1.158.0 → 1.159.0

package/src/model-order.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { compareModelIds, familyOf, releaseOf, tierRankOf } from "./model-order.js";
+import { compareModelIds, compareUnrankedModelIds, familyOf, releaseOf, tierRankOf } from "./model-order.js";
 
 /* The order every provider's catalog is served and browsed in. The rule exists because only Anthropic publishes
  * a ranking: the OpenAI-compatible endpoints behind Codex, Gemini, Kimi and Grok hand back a SET, and taking
@@ -26,6 +26,29 @@ test("lands the same models at the head and the tail whichever order the endpoin
     }
 });
 
+test("an unranked catalog settles its own ties, so the SAME sibling opens the group on every refresh", () => {
+    // The measured failure: the translator's /v1/models hands sol/terra/luna back in a different order per
+    // request, and the rule above ranks all three equally — same tier, same 5.6 release. Under plain stability
+    // the catalog's head (i.e. the model a fresh conversation starts on) followed that reshuffling.
+    const arrivals = [
+        ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"],
+        ["gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.6-sol"],
+        ["gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra"],
+    ];
+    const heads = arrivals.map((arrival) => arrival.toSorted(compareUnrankedModelIds)[0]);
+
+    expect(new Set(heads).size).toBe(1);
+    // Same rule, so ranking still outranks the tiebreak: the mini rung stays at the tail, under every sibling.
+    expect(["gpt-5.4-mini", ...arrivals[0]!].toSorted(compareUnrankedModelIds).at(-1)).toBe("gpt-5.4-mini");
+});
+
+test("leaves a RANKED catalog's ties alone — the id tiebreak is for sets, and Anthropic publishes an opinion", () => {
+    // compareUnrankedModelIds would seat claude-fable-5 ahead of claude-opus-5 on the id alone. Anthropic's
+    // catalog arrives newest-first, so that order is a fact about the provider, not a leftover to be broken.
+    expect(["claude-opus-5", "claude-fable-5"].toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-fable-5"]);
+    expect(["claude-opus-5", "claude-fable-5"].toSorted(compareUnrankedModelIds)).toEqual(["claude-fable-5", "claude-opus-5"]);
+});
+
 test("reads each vendor's tier vocabulary, not just Claude's", () => {
     expect(["gemini-3-flash", "gemini-3-flash-lite", "gemini-3-pro"].toSorted(compareModelIds)).toEqual([
         "gemini-3-pro",
@@ -57,6 +80,16 @@ test("leads with a family carrying no tier word at all, so a brand-new flagship
     expect(["claude-sonnet-5", "claude-mythos-1", "claude-opus-5"].toSorted(compareModelIds)[0]).toBe("claude-mythos-1");
 });
 
+test("files a re-served open-weights model on the cheap rung, not at the head of the catalog it visits", () => {
+    // Google's channel vends gpt-oss beside Gemini and Claude. It carries no tier word of its own, so the
+    // lead-the-unknown rule would open that whole section on it — above Opus.
+    expect(["gpt-oss-120b-medium", "claude-opus-4-6-thinking", "gemini-pro-agent"].toSorted(compareModelIds)).toEqual([
+        "claude-opus-4-6-thinking",
+        "gemini-pro-agent",
+        "gpt-oss-120b-medium",
+    ]);
+});
+
 test("keeps the arrival order between ids the rule cannot separate — Anthropic's catalog IS ranked", () => {
     // Same tier, same version: nothing here outranks the order the provider itself reported.
     expect(["claude-opus-5", "claude-fable-5"].toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-fable-5"]);

package/src/model-order.ts

@@ -97,6 +97,10 @@ const TIER_RANK: Readonly<Record<string, number>> = {
     mini: 1,
     // Efficient: the cheap/fast end, the rung whose whole purpose is to cost less than the one above it.
     haiku: 2,
+    // An open-weights model a vendor re-serves beside its own (gpt-oss-120b on Google's channel) is that rung by
+    // construction: it is there to be the free/cheap option next to the frontier line, never the flagship. Without
+    // it the id carries no tier word at all and would LEAD the section it sits in.
+    oss: 2,
     lite: 2,
     nano: 2,
     fast: 2,
@@ -122,3 +126,15 @@ export const tierRankOf = (family: string): number => {
 // is stable, so two ids this rule cannot separate keep the order they arrived in (for Claude, the provider's own).
 export const compareModelIds = (left: string, right: string): number =>
     tierRankOf(familyOf(left)) - tierRankOf(familyOf(right)) || compareRelease(releaseOf(left), releaseOf(right));
+
+/* The order for a catalog its endpoint published as a SET — Codex, Gemini, Kimi and Grok, i.e. everything but
+ * Anthropic's ranked list. Falling back on arrival order is what the rule above does with a tie, and for a RANKED
+ * catalog that is exactly right: the tie is the provider's own opinion, so claude-opus-5 stays ahead of
+ * claude-fable-5. For a set there is no opinion to keep, and the header of this file assumed the leftover order
+ * was at least alphabetical — it is not. A subscription vending sol/terra/luna (same tier, same 5.6 release, three
+ * ids this rule cannot separate) hands its rows back in whatever order its registry iterated THIS request, so the
+ * tie decided which model a fresh conversation opened on AND flipped between catalog refreshes.
+ *
+ * So a set breaks its own ties on the id. Which sibling that seats first is arbitrary — but it is the same
+ * arbitrary answer every refresh, which is the property `default` actually needs. */
+export const compareUnrankedModelIds = (left: string, right: string): number => compareModelIds(left, right) || left.localeCompare(right);

package/src/path-refs.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "vitest";
+import { rankRefCandidates, referenceTails } from "./path-refs.js";
+
+describe("referenceTails", () => {
+    test("offers the reference itself first, then shorter tails of it", () => {
+        expect(referenceTails("_apps/web/src/foo.ts", "/work")).toEqual(["_apps/web/src/foo.ts", "web/src/foo.ts", "src/foo.ts"]);
+    });
+
+    test("anchors an absolute path under the workspace root", () => {
+        expect(referenceTails("/work/_apps/foo.ts", "/work")[0]).toBe("_apps/foo.ts");
+    });
+
+    test("strips an isolated turn's worktree lead by dropping segments", () => {
+        // The worktree mirrors the workspace layout below /history/worktrees/<id>, so the real path is a tail.
+        expect(referenceTails("/history/worktrees/agent-7/_apps/foo.ts", "/work")).toContain("_apps/foo.ts");
+    });
+
+    test("never cuts down to a bare filename — one `index.ts` is as good as another", () => {
+        expect(referenceTails("a/b/index.ts", "/work").at(-1)).toBe("b/index.ts");
+        expect(referenceTails("index.ts", "/work")).toEqual([]);
+    });
+
+    test("normalizes a ./ lead and windows separators", () => {
+        expect(referenceTails("./src/foo.ts", "/work")).toEqual(["src/foo.ts"]);
+        expect(referenceTails("src\\foo.ts", "/work")).toEqual(["src/foo.ts"]);
+    });
+});
+
+describe("rankRefCandidates", () => {
+    test("keeps only matches that end in the tail on a segment boundary", () => {
+        // `mypages/` merely ends with the same characters — the daemon's glob can't tell, so this must.
+        expect(rankRefCandidates("pages/Foo.vue", ["app/mypages/Foo.vue", "app/pages/Foo.vue"])).toEqual(["app/pages/Foo.vue"]);
+    });
+
+    test("ranks the shallowest match first — the app's file, not a copy in a fixture tree", () => {
+        expect(rankRefCandidates("pages/Foo.vue", ["a/b/c/pages/Foo.vue", "a/pages/Foo.vue"])).toEqual(["a/pages/Foo.vue", "a/b/c/pages/Foo.vue"]);
+    });
+
+    test("matches the tail as a whole path too", () => {
+        expect(rankRefCandidates("src/foo.ts", ["src/foo.ts", "vendor/src/foo.ts"])).toEqual(["src/foo.ts", "vendor/src/foo.ts"]);
+    });
+});

package/src/path-refs.ts

@@ -0,0 +1,43 @@
+/* Which file a NAMED reference means. A path written in prose is only loosely anchored to the workspace: an
+ * agent that has been working in `_apps/web/src` writes `pages/workspace/Foo.vue`, and a turn running in an
+ * isolated worktree prints `/history/worktrees/<id>/_apps/web/src/foo.ts` — neither is the workspace-relative
+ * path the file routes speak, but both END in it.
+ *
+ * So a reference is resolved by matching progressively shorter TAILS of it against the real tree. The rules
+ * live here, in the contract package, because both sides run them: the browser first against the workspace
+ * tree it already has cached, then the daemon (/workspace/resolve) against the iq engine's full sweep, which
+ * sees the files the capped tree walk left out. Two matchers that disagreed would make a link's destination
+ * depend on which one answered. */
+
+// How many leading segments a reference may carry that the workspace doesn't (the `/history/worktrees/<id>/`
+// lead of a worktree path is 3; a foreign absolute root is rarely deeper).
+const MAX_DROPS = 6;
+// A tail is never cut down to a bare filename: `index.ts` names a hundred files in a monorepo and picking one
+// at random is worse than not linking. The link grammar never emits a slash-less reference either.
+const MIN_SEGMENTS = 2;
+// Enough candidates for a picker; a reference matching more than this is ambiguous by any measure.
+export const MAX_REF_CANDIDATES = 10;
+
+// The tails worth matching, longest (most specific) first. `root` is the container workspace root: a path
+// under it is already the answer minus that lead, and a path under any OTHER absolute root (a worktree) still
+// mirrors the layout below its own lead, which the successive drops strip.
+export const referenceTails = (raw: string, root: string): readonly string[] => {
+    const normalized = raw.replaceAll(`\\`, `/`).replace(/^\.\//, ``);
+    const anchored = normalized.startsWith(`${root}/`) ? normalized.slice(root.length + 1) : normalized.replace(/^\/+/, ``);
+    const segments = anchored.split(`/`).filter((segment) => segment !== `` && segment !== `.`);
+    const tails: string[] = [];
+    for (let drop = 0; drop <= MAX_DROPS && segments.length - drop >= MIN_SEGMENTS; drop++) {
+        tails.push(segments.slice(drop).join(`/`));
+    }
+    return tails;
+};
+
+// The paths that genuinely END in `tail` on a segment boundary, best first — the shared ranking both matchers
+// return their candidates in. Shallowest wins: `pages/Foo.vue` means the app's page, not the copy six
+// directories down in a fixture tree. (The daemon's glob is anchored only at the string level — `**/pages/x.vue`
+// also matches `mypages/x.vue` — so the boundary is enforced here rather than by the pattern.)
+export const rankRefCandidates = (tail: string, paths: readonly string[]): readonly string[] =>
+    paths
+        .filter((path) => path === tail || path.endsWith(`/${tail}`))
+        .toSorted((a, b) => a.split(`/`).length - b.split(`/`).length || a.length - b.length || (a < b ? -1 : 1))
+        .slice(0, MAX_REF_CANDIDATES);

package/src/routes.test.ts

@@ -0,0 +1,83 @@
+import { oc } from "@orpc/contract";
+import { describe, expect, it } from "vitest";
+import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTES, sandboxRouteName } from "./index.js";
+import { contractRoutes, routeNameForRequest } from "./routes.js";
+
+const fixture = {
+    vpn: {
+        list: oc.route({ method: "GET", path: "/vpn" }),
+        connect: oc.route({ method: "POST", path: "/vpn/{id}/connect" }),
+    },
+    system: {
+        killTerminal: oc.route({ method: "DELETE", path: "/system/terminals/{name}" }),
+    },
+};
+
+describe(`contractRoutes`, () => {
+    it(`names every procedure <group>.<route>, sorted`, () => {
+        expect(contractRoutes(fixture).map((route) => route.name)).toEqual([`system.killTerminal`, `vpn.connect`, `vpn.list`]);
+    });
+
+    it(`carries the wire method and path template`, () => {
+        expect(contractRoutes(fixture).find((route) => route.name === `vpn.connect`)).toEqual({
+            name: `vpn.connect`,
+            method: `POST`,
+            path: `/vpn/{id}/connect`,
+        });
+    });
+
+    it(`ignores non-procedure members rather than inventing routes for them`, () => {
+        expect(contractRoutes({ vpn: { list: fixture.vpn.list, NOT_A_ROUTE: { hello: true } } }).map((r) => r.name)).toEqual([`vpn.list`]);
+    });
+});
+
+describe(`routeNameForRequest`, () => {
+    const routes = contractRoutes(fixture);
+
+    it(`matches a literal path`, () => {
+        expect(routeNameForRequest(routes, `GET`, `/vpn`)).toBe(`vpn.list`);
+    });
+
+    it(`matches a templated segment`, () => {
+        expect(routeNameForRequest(routes, `POST`, `/vpn/corp-gw/connect`)).toBe(`vpn.connect`);
+        expect(routeNameForRequest(routes, `DELETE`, `/system/terminals/web-1`)).toBe(`system.killTerminal`);
+    });
+
+    it(`strips the query string before matching`, () => {
+        expect(routeNameForRequest(routes, `GET`, `/vpn?refresh=1`)).toBe(`vpn.list`);
+    });
+
+    it(`is method-sensitive`, () => {
+        expect(routeNameForRequest(routes, `POST`, `/vpn`)).toBeUndefined();
+    });
+
+    it(`never matches a longer or shorter path than the template`, () => {
+        expect(routeNameForRequest(routes, `POST`, `/vpn/corp-gw/connect/extra`)).toBeUndefined();
+        expect(routeNameForRequest(routes, `POST`, `/vpn/connect`)).toBeUndefined();
+    });
+
+    it(`does not let an empty segment stand in for a param`, () => {
+        expect(routeNameForRequest(routes, `DELETE`, `/system/terminals/`)).toBeUndefined();
+    });
+
+    it(`returns undefined for the daemon's hand-written non-contract routes`, () => {
+        expect(routeNameForRequest(routes, `GET`, `/health`)).toBeUndefined();
+    });
+});
+
+describe(`the real sandbox contract`, () => {
+    it(`derives a route table with no duplicate names`, () => {
+        expect(SANDBOX_ROUTE_NAMES.length).toBe(SANDBOX_ROUTES.length);
+        expect(new Set(SANDBOX_ROUTE_NAMES).size).toBe(SANDBOX_ROUTE_NAMES.length);
+    });
+
+    it(`covers every oc.route in the contract`, () => {
+        // Guards the walk against a future contract nesting deeper than group → procedure, which would
+        // silently advertise fewer routes than the daemon serves.
+        expect(SANDBOX_ROUTES.length).toBeGreaterThan(100);
+    });
+
+    it(`resolves a known concrete request back to its contract name`, () => {
+        expect(sandboxRouteName(`GET`, `/vpn`)).toBe(`vpn.list`);
+    });
+});

package/src/routes.ts

@@ -0,0 +1,84 @@
+/* The daemon's route surface, named. A sandbox daemon is baked into an image, so the browser talking to it is
+ * routinely NEWER than the daemon: a released app plane serves every user's sandbox, whatever image they last
+ * pulled, and in local development the web app is always ahead of the last `pnpm build:sandbox`. Both are
+ * normal and neither should force an update.
+ *
+ * What must not happen is the failure being SILENT. A route the daemon predates answers 404, which the browser
+ * has no way to tell apart from "you asked for a file that isn't there" — so a missing feature reads as a
+ * broken one, and diagnosing it costs an hour of "did the image rebuild?".
+ *
+ * So the daemon ADVERTISES the routes it implements (the /events hello frame) and the browser compares that
+ * against the contract it was itself built with. Everything present on both sides works exactly as before;
+ * anything the daemon lacks is a KNOWN, NAMED gap the UI can gate a feature on or explain in an error, instead
+ * of a mystery 404. Old daemon + new browser stays fully supported — it just stops being confusing.
+ *
+ * Route names are `<group>.<route>` (`vpn.list`, `kimi.models`), derived from the contract object both sides
+ * import. Nothing is generated and nothing is hand-maintained: adding a route to the contract adds it here.
+ *
+ * Everything here is a pure function of a contract passed in — index.ts binds them to `sandboxContract` once it
+ * is assembled, which is what keeps this module out of an import cycle with it. */
+
+// The shape we read off an oRPC contract procedure. `~orpc.route` is the contract metadata oRPC attaches to
+// every `oc.route(...)` procedure; we only need the wire method + path, so this is deliberately structural
+// rather than an import of oRPC's internal types (which are not part of its public surface).
+interface ContractProcedureLike {
+    readonly "~orpc": { readonly route?: { readonly method?: string; readonly path?: string } };
+}
+
+const procedureRoute = (value: unknown): { method: string; path: string } | undefined => {
+    if (typeof value !== "object" || value === null || !("~orpc" in value)) {
+        return undefined;
+    }
+    const { route } = (value as ContractProcedureLike)["~orpc"];
+    if (route?.method === undefined || route.path === undefined) {
+        return undefined;
+    }
+    return { method: route.method, path: route.path };
+};
+
+// One advertised route: its contract name plus the wire shape, so a concrete request path can be matched back
+// to the name it came from (see routeNameForRequest).
+export interface ContractRoute {
+    readonly name: string;
+    readonly method: string;
+    // The oRPC path template, with `{param}` placeholders — e.g. `/system/terminals/{name}`.
+    readonly path: string;
+}
+
+// Walk a contract object (two levels: group → procedure) into its flat route list, sorted by name so the
+// advertised array is stable and diffable.
+export const contractRoutes = (contract: Record<string, unknown>): ContractRoute[] => {
+    const routes: ContractRoute[] = [];
+    for (const [group, procedures] of Object.entries(contract)) {
+        if (typeof procedures !== "object" || procedures === null) {
+            continue;
+        }
+        for (const [name, procedure] of Object.entries(procedures as Record<string, unknown>)) {
+            const route = procedureRoute(procedure);
+            if (route !== undefined) {
+                routes.push({ name: `${group}.${name}`, method: route.method, path: route.path });
+            }
+        }
+    }
+    return routes.toSorted((a, b) => a.name.localeCompare(b.name));
+};
+
+// Does a concrete request path match this route's template? Segment-wise, with `{param}` matching exactly one
+// segment — the same shape oRPC mounts, so a template can never match a longer or shorter path.
+const pathMatches = (template: string, path: string): boolean => {
+    const wanted = template.split("/");
+    const actual = path.split("/");
+    if (wanted.length !== actual.length) {
+        return false;
+    }
+    return wanted.every((segment, index) => (segment.startsWith("{") && segment.endsWith("}") ? actual[index] !== "" : segment === actual[index]));
+};
+
+// The contract route a concrete request belongs to, or undefined when the path is not a contract route at all
+// (the daemon also serves hand-written Hono routes like /health and /workspace/raw — those are never gated).
+// The query string is stripped first; callers pass whatever they handed to fetch.
+export const routeNameForRequest = (routes: readonly ContractRoute[], method: string, pathWithQuery: string): string | undefined => {
+    const path = pathWithQuery.split("?")[0] ?? pathWithQuery;
+    const upper = method.toUpperCase();
+    return routes.find((route) => route.method.toUpperCase() === upper && pathMatches(route.path, path))?.name;
+};

package/src/schemas.ts

@@ -54,6 +54,24 @@ export type EditorContext = z.infer<typeof EditorContextSchema>;
 // and filesystem paths — the regex is the injection guard. Shared by the turn input and the attach input.
 const ConversationIdSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/);
 
+// Where a conversation came from when nobody typed it into the browser: an automation wake carrying a message
+// from OUTSIDE the sandbox (a Discord mention, a web-chat visitor, a webhook). Such a wake runs as an ordinary
+// isolated conversation — registry entry, worktree, chat tab, land flow — and this is the only thing that
+// distinguishes it on the surface: the card's provenance line and the reason its first prompt is not the
+// user's. Set daemon-side by the dispatcher that received the message; the browser never sends one.
+export const AgentOriginSchema = z.object({
+    // The automation whose configured prompt opened the conversation.
+    automationId: z.string(),
+    // The listener provider that received the message ("discord", "webchat", …) or "webhook" for an event
+    // trigger. An open string for the same reason Trigger.provider is: sources are extension-declared.
+    provider: z.string(),
+    // The external thread it arrived on — a Discord channel id, a widget conversation id. Absent for webhooks.
+    channelId: z.string().optional(),
+    // Who sent it, as the source names them.
+    author: z.string().optional(),
+});
+export type AgentOrigin = z.infer<typeof AgentOriginSchema>;
+
 // How tool calls are gated — the Claude Agent SDK's PermissionMode, narrowed to the four the composer offers
 // (the SDK also has 'dontAsk'/'auto', which have no UI here). The user picks one per turn AND the agent can
 // move itself between them mid-turn, so this is both a turn input and the payload of the `mode` frame.
@@ -89,6 +107,10 @@ export const AgentTurnSchema = z
         // When true, the turn runs in the conversation's isolated git worktree (created lazily on first use)
         // instead of the shared /work tree — the parallel-agents mode. Requires conversationId.
         isolated: z.boolean().optional(),
+        // Set ONLY by the daemon's own automation dispatchers: this turn opens a conversation on behalf of an
+        // outside message rather than a user. Recorded on the registry entry so the fleet can say where the
+        // agent came from. Requires conversationId — there is nothing to record it on otherwise.
+        origin: AgentOriginSchema.optional(),
         // The client-held transcript of a conversation that just switched provider/account: seeds the FIRST
         // turn of the replacement session. The daemon folds it into the prompt as one role-attributed context
         // preamble for every runtime. Mutually exclusive with sessionId — a resumed session has its context.
@@ -114,6 +136,9 @@ export const AgentTurnSchema = z
     })
     .refine((turn) => turn.isolated !== true || turn.conversationId !== undefined, {
         message: "isolated requires conversationId",
+    })
+    .refine((turn) => turn.origin === undefined || turn.conversationId !== undefined, {
+        message: "origin requires conversationId",
     });
 export type AgentTurn = z.infer<typeof AgentTurnSchema>;
 
@@ -169,6 +194,9 @@ export const AgentSummarySchema = z.object({
     account: z.string().optional(),
     // The worktree branch (agent/<id>); absent for a non-isolated (main-tree) conversation.
     branch: z.string().optional(),
+    // Present when the conversation was opened by an outside message rather than by the user (see
+    // AgentOriginSchema) — the card's provenance line. Absent ⇒ the user started it.
+    origin: AgentOriginSchema.optional(),
     // The ROOT repo's short base sha — the checkout moment's display identity. Per-repo bases stay
     // daemon-internal (agents.diff already reports against them).
     base: z.string().optional(),
@@ -200,7 +228,12 @@ export const AgentSummarySchema = z.object({
     archivedAt: z.number().optional(),
 });
 export type AgentSummary = z.infer<typeof AgentSummarySchema>;
-export const AgentsListSchema = z.object({ agents: z.array(AgentSummarySchema) });
+// `rev` is the registry revision this roster was read at — a counter the daemon bumps on every registry change.
+// It is what makes the browser's optimistic writes safe: the fleet is published as full snapshots (last frame
+// wins), so without an ordering stamp a roster READ before a mutation but delivered after it silently puts the
+// mutated agents back. The browser drops any roster older than the newest it has applied, and holds its own
+// pending change until a roster at or past the revision that applied it arrives. See useAgents.ts.
+export const AgentsListSchema = z.object({ agents: z.array(AgentSummarySchema), rev: z.number() });
 export const AgentIdSchema = z.object({ id: z.string().min(1) });
 // archive's input: the agents to take off the board. Absent `ids` ⇒ every finished agent that is archivable
 // right now (the lane header's "Clear"); unarchive always names its ids (a restore, or a bulk archive's undo).
@@ -211,7 +244,9 @@ export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).
 // the slower response resurrect what the faster one just filed away — a delta composes where a snapshot races.
 // Whole summaries rather than ids because the receiving side has to SHOW them (the archive list, and the agent
 // detail page addressed by id); the ids "Undo" needs come off them for free.
-export const AgentsMovedSchema = z.object({ moved: z.array(AgentSummarySchema) });
+// The agents an archive/unarchive actually moved, plus the registry revision that applied the move — the
+// browser holds its optimistic add/remove of exactly these ids until it sees a roster at or past `rev`.
+export const AgentsMovedSchema = z.object({ moved: z.array(AgentSummarySchema), rev: z.number() });
 export type AgentsMoved = z.infer<typeof AgentsMovedSchema>;
 // rename's input: the user-chosen display title (bounded like sanitizeTitle's cap).
 export const AgentRenameSchema = z.object({ id: z.string().min(1), title: z.string().trim().min(1).max(80) });
@@ -795,6 +830,12 @@ export const WorkspaceChildrenSchema = z.object({
 export type WorkspaceChildren = z.infer<typeof WorkspaceChildrenSchema>;
 export const WorkspaceFileQuerySchema = z.object({ path: z.string().min(1) });
 export const WorkspaceFileSchema = z.object({ path: z.string(), content: z.string() });
+// 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 `_apps/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.
+export const WorkspaceResolveQuerySchema = z.object({ path: z.string().min(1).max(512) });
+export const WorkspaceResolveSchema = z.object({ path: z.string().optional() });
 // 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.
 export const WorkspaceDirSchema = z.object({ path: z.string().min(1) });
@@ -1546,6 +1587,10 @@ export const AutomationApprovalSchema = z.object({
     automationId: z.string(),
     // The event/listener payload the wake would have carried; absent for schedule triggers.
     payload: z.string().optional(),
+    // The provenance + title the held wake would have opened its conversation with — snapshotted alongside the
+    // payload so an approved external wake surfaces on the fleet exactly as an auto one would have.
+    origin: AgentOriginSchema.optional(),
+    title: z.string().optional(),
     createdAt: z.number(),
 });
 export type AutomationApproval = z.infer<typeof AutomationApprovalSchema>;
@@ -1696,7 +1741,8 @@ export type PortForwardResult = z.infer<typeof PortForwardResultSchema>;
 // is the /system/terminal WebSocket, not oRPC): `shell` = a web-* session the user opened (numbered pill),
 // `panel` = a panel-* dev-server session (labeled by its panel key, started via Start; running:false =
 // untracked, e.g. a finished one-shot job's lingering shell), `agent` = an agent-* session the Claude agent's
-// Bash commands run in (live-watchable, AI-marked in the UI), `job` = a job-* session the daemon's terminal
+// Bash commands run in (live-watchable, AI-marked in the UI; running:false once every window is a finished
+// command's dead pane, which is what lets the panel sweep it), `job` = a job-* session the daemon's terminal
 // runner executes user-triggered flows in (capability adds, infra check), `process` = a managed background
 // process riding a panel session (an extension's declared processes, dockerd) — surfaced in the panel's
 // background-processes popover with read-only log views, never as a killable tab; running is the actual