@intentic/sandbox-contract 1.344.0 → 1.346.0

package/src/schemas/agent.ts

@@ -1,12 +1,13 @@
 import { TurnErrandSchema } from "./speaker.js";
 import { z } from "zod";
-import { CONVERSATION_ID } from "../ids/conversation-ids.js";
+import { CONVERSATION_ID, CONVERSATION_TITLE_MAX } from "../ids/conversation-ids.js";
 import { canonicalHarness } from "../models/agent-catalog.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { NATIVE_PROVIDERS } from "../models/provider-specs.js";
 import { AgentPlacementSchema } from "../protocol/doors/runner-protocol.js";
 import { MENTION_LIMIT } from "../text/mentions.js";
 import { entryId } from "./internal.js";
+import { FRESH_OF_DESCRIPTION, FreshOfSchema, freshOfIssues } from "./conversation-links.js";
 // Agent runtimes the daemon can serve: native providers have dedicated adapters, `endpoint/<id>` names an installed
 // endpoint capability, anything else is an ACP agent capability id. A bare string, not an enum, so an unknown id is a
 // clean error, not a contract change.
@@ -66,81 +67,29 @@ export const AgentOriginSchema = z.object({
     author: z.string().optional(),
 });
 export type AgentOrigin = z.infer<typeof AgentOriginSchema>;
-// The class of thing asking to start a session, the admission policy's key space; derived daemon-side, never sent by a
-// client. Chat and loops are absent since both begin with the owner's own click.
-export const WakeSourceSchema = z.enum(["schedule", "event", "listener", "webchat", "issues", "workspace", "workflow"]);
-export type WakeSource = z.infer<typeof WakeSourceSchema>;
-// One admission verdict the owner can configure: let it run, hold it for approval, or refuse it outright.
-export const AdmissionRuleSchema = z.enum(["allow", "hold", "deny"]);
-export type AdmissionRule = z.infer<typeof AdmissionRuleSchema>;
-// Where a command would run; the same string means different things on each machine (rm -rf /usr is recoverable here,
-// fatal on a laptop). Read with a locus (command-classes.ts CommandContext); callers must state one rather than
-// default.
-export const CommandLocusSchema = z.enum([
-    // This sandbox's own shell: a disposable container, /work a git worktree, /history every other agent's.
-    "sandbox",
-    // One of the owner's own computers, reached through the machine agent. Nothing here is disposable.
-    "device",
-]);
-export type CommandLocus = z.infer<typeof CommandLocusSchema>;
-// What kind of thing a shell command is, the command gate's key space under the admission floor; gates one command
-// inside an already-running session. Six classes, chosen because each is hard or impossible to undo somewhere.
-export const CommandClassSchema = z.enum([
-    // Rewrites or discards committed work: force-push, hard reset, force-delete a branch, clean -f, filter-branch.
-    "git.destructive",
-    // Moves a checkout to another branch. Only ever matches in a tree the conversation SHARES with its owner: inside
-    // its own copy a conversation may stand where it likes, and the drift that causes is reported, not refused.
-    "git.branch-switch",
-    // Recursive-force deletion (`rm -rf`), and its spelling in a script (`fs.rm(p, { recursive: true })`).
-    "files.destructive",
-    // State nothing recovers at this locus; which roots count (/, /history in the sandbox) depends on the locus.
-    "system.destructive",
-    // A container volume or its data; the sandbox's blast radius (nested engine) differs sharply from a device's.
-    "container.state",
-    // Reads credential material: a secret reference, or a file confirmed to actually hold one.
-    "secrets.access",
-    // Publishes outward and irreversibly: npm/pnpm/yarn/cargo publish, gh release create, docker push.
-    "package.publish",
-    // A network program (curl, nc, ssh, scp, …) or interpreter one-liner aimed at a non-loopback or run-time-built
-    // destination, the general exfiltration channel under the per-provider actionRules.
-    "network.outbound",
-]);
-export type CommandClass = z.infer<typeof CommandClassSchema>;
-// Workspace-wide admission floor per wake source, consulted on every outside-driven wake; composes with per-automation
-// overrides most-restrictive-wins. `workflow` is allow|deny only, since a hold there is indistinguishable from a CI
-// runner's timeout.
-export const AdmissionPolicySchema = z.object({
-    schedule: AdmissionRuleSchema.default("allow"),
-    event: AdmissionRuleSchema.default("allow"),
-    listener: AdmissionRuleSchema.default("allow"),
-    webchat: AdmissionRuleSchema.default("allow"),
-    // Defaults to hold, unlike the others: a bug-report wake has full repo powers and a stranger's stack trace as its
-    // brief.
-    issues: AdmissionRuleSchema.default("hold"),
-    workspace: AdmissionRuleSchema.default("allow"),
-    workflow: z.enum(["allow", "deny"]).default("allow"),
-});
-export type AdmissionPolicy = z.infer<typeof AdmissionPolicySchema>;
 // How tool calls are gated, the Claude Agent SDK's PermissionMode narrowed to the three the composer offers. Both a
 // turn input and the payload of the `mode` frame, since the agent can move itself between them mid-turn. The SDK's
 // acceptEdits is not one of them: only `default` asks a person here, so it would differ from bypassPermissions in name
 // alone.
 export const PermissionModeSchema = z.enum(["default", "plan", "bypassPermissions"]);
 export type PermissionMode = z.infer<typeof PermissionModeSchema>;
-// Where a conversation was cut from, the durable half of a fork, carried on the registry entry. `index` is the message
-// the cut sat above in the source, so its transcript can put the mark back.
-export const ForkedFromSchema = z.object({
-    conversationId: ConversationIdSchema,
-    index: z.number().int().nonnegative(),
-    // Which files this fork opened on; kept so the fork can still say it later, not only right after the click.
-    files: z.enum(["then", "now"]),
-});
-export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
+// How one conversation relates to another (a fork's cut, a fresh session's origin): conversation-links.ts.
+export * from "./conversation-links.js";
 // The turn's fields before the cross-field refinements below, so a subset (TurnProfileSchema) can be picked from them.
 // How many files one turn may carry. A batch of a person's queued messages joins their files, so the admission splits a
 // batch rather than build a turn past this (turn-admission.ts, together): a turn the daemon makes must parse back.
 export const ATTACHMENT_LIMIT = 20;
 
+// Where a fork is cut from, as the client that cut it names it (its first turn, or a draft no turn has started yet).
+export const ForkOfSchema = z.object({
+    conversationId: ConversationIdSchema.describe("The conversation this one was cut from."),
+    keep: z.number().int().nonnegative().describe("How many of that conversation's messages to copy in before this turn runs."),
+    files: z
+        .enum(["then", "now"])
+        .describe(
+            'Which files the fork opens on: "now" is the workspace as it stands, "then" is the files as they were at the cut, which needs a private copy.',
+        ),
+});
 const AgentTurnFieldsSchema = z.object({
     prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
     errand: TurnErrandSchema.optional().describe(
@@ -158,7 +107,7 @@ const AgentTurnFieldsSchema = z.object({
     // Seeds a fresh registry entry's title; an existing entry's title always wins over this.
     title: z
         .string()
-        .max(80)
+        .max(CONVERSATION_TITLE_MAX)
         .optional()
         .describe("A title for a conversation this turn is opening. Ignored for a conversation that already has one."),
     // Already uploaded via /workspace/upload; Claude reads them via Read, Codex gets images as native input.
@@ -250,18 +199,9 @@ const AgentTurnFieldsSchema = z.object({
     // the new session from its own conversationId-keyed record.
     // Where a fork was cut from, on its first turn only; requires conversationId, and files:"then" implies
     // isolated.
-    forkOf: z
-        .object({
-            conversationId: ConversationIdSchema.describe("The conversation this one was cut from."),
-            keep: z.number().int().nonnegative().describe("How many of that conversation's messages to copy in before this turn runs."),
-            files: z
-                .enum(["then", "now"])
-                .describe(
-                    'Which files the fork opens on: "now" is the workspace as it stands, "then" is the files as they were at the cut, which needs a private copy.',
-                ),
-        })
-        .optional()
-        .describe("Where this conversation was cut from, on its first turn only. Only the client knows this, so only the client can say it."),
+    forkOf: ForkOfSchema.optional().describe("Where this conversation was cut from, on its first turn only. Only the client knows this, so only the client can say it."),
+    // A fresh session's origin, on its first turn only; requires an isolated conversationId the registry has never seen.
+    freshOf: FreshOfSchema.optional().describe(FRESH_OF_DESCRIPTION),
     // The browser sends the chosen model per turn; the provider token is the sandbox's own stored credential.
     model: z.string().optional().describe("Which model to use. Leave it out for the provider's default."),
     // Audience only, never model routing: `runRole` is what fills a model in. A run somebody pressed and is
@@ -327,6 +267,15 @@ const AgentTurnFieldsSchema = z.object({
         .describe(
             "Hold this message until then (epoch milliseconds) instead of starting a turn now: a time you chose, or the reopen of an allowance you know is spent. It waits in the conversation's queue, where it can be sent early, reworded, rescheduled or removed, and goes by itself at that instant, even for a conversation this message opens or one whose turn is running now. Ignored when already past; at most a month ahead.",
         ),
+    // Why `sendAt` is the instant it is, when it is not a time somebody chose: the composer booked the message for the
+    // spent allowance's reopen. Kept with the booking (`reopenOf` on the queue), so every window can tell an allowance
+    // wait from an appointment without matching instants against whatever the usage feed says now.
+    sendAtReopen: z
+        .literal(true)
+        .optional()
+        .describe(
+            "Says `sendAt` is the reopen of the allowance this message would be refused by, not a time you chose. Recorded with the booking (the queue's `reopenOf` names the account it waits for), so every window can say the message waits on an allowance, and see when the conversation has moved somewhere with room. Only with `sendAt`.",
+        ),
     // The other scheduled send: work that builds on another agent's, held until that agent's work is in the workspace.
     // Held in the queue like `sendAt`; the queue's `after` is this. Never both: a hold waits on exactly one thing.
     sendAfter: ConversationIdSchema.optional().describe(
@@ -362,6 +311,7 @@ export const AgentTurnSchema = AgentTurnFieldsSchema
     .refine((turn) => turn.forkOf?.files !== "then" || turn.isolated === true, {
         message: 'forkOf.files "then" requires isolated',
     })
+    .superRefine(freshOfIssues)
     .refine((turn) => turn.sendAt === undefined || turn.sendAfter === undefined, {
         message: "sendAt and sendAfter are two different holds: name one",
     })
@@ -372,6 +322,16 @@ export type AgentTurn = z.infer<typeof AgentTurnSchema>;
 // What `agent.run` takes: a turn, plus the one field only a request carries and no stored turn keeps. A daemon from before
 // `continues` reads past it and takes `prompt` as the words, which is why a client still sends some.
 export const AgentRunSchema = AgentTurnSchema.safeExtend({
+    // Request-only like `continues`: the draft goes in the same step that takes the message, so it is cleared exactly
+    // once, by the send itself, and a window that closes before its own clear arrives leaves no ghost of sent words.
+    draft: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(
+            "The revision of your composer draft for this conversation these words were sent from (`agents.drafts`). The sandbox clears that draft as it takes the message, unless it has been written again since. Leave it out to leave your draft as it is.",
+        ),
     continues: z
         .literal(true)
         .optional()
@@ -514,6 +474,25 @@ export type MessageReceipt = z.infer<typeof MessageReceiptSchema>;
 // a job that ended, a land that broke something), or another agent (a child reporting back).
 export const MessageVoiceSchema = z.enum(["person", "sandbox", "agent"]);
 export type MessageVoice = z.infer<typeof MessageVoiceSchema>;
+// The account a message booked for an allowance's reopen waits on: what it waits out, which the booking's instant alone
+// cannot say once the chat has moved somewhere with room.
+export const QueuedReopenSchema = z.object({
+    agent: AgentProviderSchema.describe("The provider whose allowance it waits out."),
+    account: z
+        .string()
+        .optional()
+        .describe("Which of its accounts. Absent when none was named, and every account of the provider read spent."),
+});
+export type QueuedReopen = z.infer<typeof QueuedReopenSchema>;
+// Who a person's waiting message goes on, as its request names it now.
+export const QueuedServingSchema = z.object({
+    agent: AgentProviderSchema.describe("The provider."),
+    harness: AgentHarnessSchema.describe("The agentic loop."),
+    model: z.string().optional().describe("The model. Absent when it named none, and takes the conversation's own."),
+    effort: z.string().optional().describe("How hard it thinks, where the model offers a choice."),
+    account: z.string().optional().describe("The account that pays for it. Absent when it named none, and goes on the conversation's own."),
+});
+export type QueuedServing = z.infer<typeof QueuedServingSchema>;
 // One message waiting for the conversation's next turn, as every window shows it.
 export const QueuedMessageSchema = z.object({
     id: z.string().describe("The message's id: what its sender named it, or what the sandbox did."),
@@ -533,6 +512,12 @@ export const QueuedMessageSchema = z.object({
     after: ConversationIdSchema.optional().describe(
         "The conversation whose finished work must land before this message goes out by itself, in place of `until`.",
     ),
+    reopenOf: QueuedReopenSchema.optional().describe(
+        "The allowance this message's `until` waits out: it was booked for that account's reopen, by the composer or by the sandbox holding words it would not send into a spent allowance, rather than for a time somebody chose. Absent on any other booking, and from sandboxes older than the field.",
+    ),
+    serves: QueuedServingSchema.optional().describe(
+        "Who serves the turn this message starts: the provider, loop, model, effort and account it was sent under, or was moved to since (`agent.queueReroute`, an account switch). Only on a person's words; the sandbox's and an agent's own go on wherever the conversation runs when they go. Absent from sandboxes older than the field.",
+    ),
     continues: z
         .literal(true)
         .optional()
@@ -586,15 +571,3 @@ export const QueueResumedSchema = z.object({
         ),
 });
 export type QueueResumed = z.infer<typeof QueueResumedSchema>;
-// Attaches to a conversation's newest run (live, or finished within retention); no cursor to resume from, the head
-// carries all rows. `run` names what the client was watching, so a newer run's head id tells it to catch up.
-export const AttachTurnSchema = z.object({
-    conversationId: ConversationIdSchema.describe("Which conversation to watch."),
-    run: z
-        .string()
-        .optional()
-        .describe(
-            "The run you were watching. The stream opens on the conversation's newest run whatever you name: if a newer turn has started since, the head names that one instead, and its rows are that turn's.",
-        ),
-});
-export type AttachTurn = z.infer<typeof AttachTurnSchema>;

package/src/schemas/agents.ts

@@ -1,13 +1,15 @@
 // agents: the conversation fleet
 import { LandingDeliverySchema } from "./project-delivery.js";
+import { AgentNextSchema } from "./agent-next.js";
 import { z } from "zod";
-import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema } from "./agent.js";
+import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema, FreshSessionSchema } from "./agent.js";
 import { LoopStateSchema } from "./loops.js";
 import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
 import { KeepWarmSchema } from "./keep-warm.js";
 import { AgentNeedSchema } from "./needs.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 import { ProgramAskSchema } from "../events/requests.js";
+import { ReviewTallySchema, TurnProofSchema } from "./work-assurance.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
 
@@ -62,8 +64,7 @@ export const AgentAttentionSchema = z.object({
     // A missing capability on a card from before needs (docs/architecture/needs.md); lets the lane say "setup needed" rather than a generic
     // pause.
     capability: z.boolean().describe("It needs something connected that is not connected yet."),
-    // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear
-    // themselves.
+    // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear themselves.
     credential: z
         .boolean()
         .describe("It is waiting for a named person to release a credential. The one pause that may not be yours to clear, whatever your role."),
@@ -101,22 +102,8 @@ export const UnfinishedWorkSchema = z.object({
         ),
 });
 export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
-// What the last turn showed of its own work, read off its tool calls and never asked of the model: the record a card
-// badges instead of sending the turn back to prove anything. CI checks what the owner pushes (schemas/ci.ts).
-export const TurnProofSchema = z.object({
-    at: z.number().describe("When the turn that left this ended, in milliseconds."),
-    verification: z
-        .enum(["verified", "unproven", "failing", "no-code"])
-        .describe(
-            "Verified: a check it ran passed after its last edit to code. Failing: the last one it ran failed. Unproven: it changed code and ran nothing that checked it. No-code: it changed nothing a check could speak to.",
-        ),
-    check: z.string().optional().describe("The command that spoke, when one did, so a targeted test is never read as the whole suite."),
-    unviewed: z
-        .number()
-        .optional()
-        .describe("How many rendered files it changed (pages, components, styles) without looking at the result afterwards. Absent when none."),
-});
-export type TurnProof = z.infer<typeof TurnProofSchema>;
+// What has looked at a conversation's work (its last turn's own checks, its latest code review): work-assurance.ts.
+export * from "./work-assurance.js";
 // How many entries each of a reach's lists carries; past it, the list's `…More` count says how many were left out.
 export const TURN_REACH_LIST_MAX = 10;
 // Where the last turn's work went when it went somewhere other than its own branch, read off what the turn touched and
@@ -175,8 +162,7 @@ export type TurnReach = z.infer<typeof TurnReachSchema>;
 // A landing's commit message: subject plus the two trailer sentences a changelog repo gets. One schema, not three
 // duplicated fields, since both the live roster and the review carrier must read the same shape and can't disagree.
 export const LandedMessageSchema = z.object({
-    // Written from the landed diff, not the opening prompt: a session that drifts from its title still needs an
-    // accurate subject.
+    // Written from the landed diff, not the opening prompt: a session that drifts from its title still needs an accurate subject.
     subject: z
         .string()
         .describe(
@@ -189,8 +175,7 @@ export const LandedMessageSchema = z.object({
         .describe(
             "The same change said to somebody who uses the product, for a repository that keeps a changelog. Usually absent, because most changes are not ones a user would notice.",
         ),
-    // Nearly always absent (removals only); required and mechanically guaranteed when a landing shrinks a wire-contract
-    // lock.
+    // Nearly always absent (removals only); required and mechanically guaranteed when a landing shrinks a wire-contract lock.
     breaking: z
         .string()
         .optional()
@@ -220,8 +205,7 @@ export const LandedMessageStepSchema = z.object({
     status: z
         .enum(["asking", "answered", "refused", "skipped"])
         .describe("How this one went. Skipped means it was not asked at all, because it refused a few minutes ago and the walk stepped over it."),
-    // Epoch ms it started; client-measures an in-flight step's ticking display. Absent for `skipped`, which cost no
-    // time.
+    // Epoch ms it started; client-measures an in-flight step's ticking display. Absent for `skipped`, which cost no time.
     at: z.number().optional().describe("When it started being asked, in milliseconds. Absent for one that was skipped, which cost no time."),
     ms: z.number().optional().describe("How long it took. Absent while it is still being asked."),
     reason: z.string().optional().describe("Why it refused, in its own words."),
@@ -297,31 +281,41 @@ export const AgentSummarySchema = z.object({
     status: AgentStatusSchema.describe(
         "What it is doing. Stopping and stopped are the two halves of somebody pressing stop, because a cancel is not instant; dismissing is the same window for a question waved away, which ends the turn too but owes the user nothing; resuming means the sandbox is already putting right whatever killed the turn; landing means its work is being carried into the workspace right now, and nothing may act on its branch until that settles.",
     ),
-    // Sentence the last turn died on; carried since `error` status alone isn't an answer, especially for an unwatched
-    // run.
+    // Sentence the last turn died on; carried since `error` status alone isn't an answer, especially for an unwatched run.
     failure: z
         .string()
         .optional()
         .describe(
             "Why the last turn failed, in the words it died on. Absent unless it did, and cleared the moment it runs again. Carried here because the word error on its own is not an answer, least of all for a run nobody was watching.",
         ),
-    // The error frame's own code, so the board can distinguish e.g. a rate limit from a crash the way chat already
-    // does.
+    // The error frame's own code, so the board can distinguish e.g. a rate limit from a crash the way chat already does.
     failureCode: z
         .string()
         .optional()
         .describe(
             "Which kind of failure it was, as the turn's own error frame coded it. Absent for a failure nothing could classify, which reads as the plain red line it is.",
         ),
+    // Who worded `failure`, as the turn's error frame said (its `own`): a card leads with those words only when they are
+    // the sandbox's own sentence, as the chat's notice does (failureView), and with its kind's line otherwise.
+    failureOwn: z
+        .boolean()
+        .optional()
+        .describe(
+            "Whether `failure` is the sandbox's own sentence rather than the provider's or the harness's words. Absent for theirs, and for an ending recorded before it was said.",
+        ),
     // Epoch seconds the spent allowance reopens; absent means genuinely unknown (Grok, Cursor) — never guess one.
     limitResetsAt: z.number().optional().describe("When the spent allowance reopens, in epoch seconds. Absent when the provider publishes no instant."),
     limitHeld: z.boolean().optional().describe("Whether the refused turn is held whole, so sending again re-runs it instead of appending to it."),
-    // Whether the daemon has already booked a retry at the reset; the one thing that keeps a stranded card out of the
-    // Attention lane.
-    limitScheduled: z.boolean().optional().describe("Whether the held turn is already booked to go again at the reset, so nobody has to press anything."),
-    // Account a booked move is sending the held turn to; set alongside `limitScheduled`, cleared by the move's own
-    // turn.
-    limitMoving: z.string().optional().describe("The account the held turn is being moved to by the owner's policy, while that move is booked."),
+    // What a sandbox older than `next` (before 1.343.0) said in its place, read so the editor can derive `next` from it
+    // (agentStatus-standing.ts, withNext): the hosted editor meets such a sandbox for as long as it stays off the release
+    // that dropped them, which carried a Breaking-Note and so is never taken by itself. No sandbox sends them since.
+    limitScheduled: z.boolean().optional().describe("Sent only by sandboxes older than `next`: whether the held turn was booked to go again by itself."),
+    limitMoving: z.string().optional().describe("Sent only by sandboxes older than `next`: the account a booked move was taking the held turn to."),
+    limitNextAt: z.number().optional().describe("Sent only by sandboxes older than `next`: when the booked re-run went, in epoch seconds."),
+    // The one answer to "does it go by itself, and when" (agent-next.ts), derived from what it holds every time it is read.
+    next: AgentNextSchema.optional().describe(
+        "What carries it on next with nobody pressing anything, and when: a held turn re-run, a message held for memory, or messages booked for later. Absent when only a press moves it.",
+    ),
     provider: AgentProviderSchema.describe("Which model provider it runs on."),
     harness: AgentHarnessSchema.describe("Which agentic loop it runs on."),
     // Latched with the conversation, so the card can say where work runs without asking anything else.
@@ -414,6 +408,10 @@ export const AgentSummarySchema = z.object({
     forkedFrom: ForkedFromSchema.optional().describe(
         "The conversation this one was cut from. Recorded once and never cleared: it is the relationship, not a pending state.",
     ),
+    // Recorded once on a fresh session's first turn and never cleared; `startedBy` names the same origin as its parent.
+    fresh: FreshSessionSchema.optional().describe(
+        "Set on a conversation started on another conversation's work without its messages (a code review, a test pass, a person's own ask): which one, for what, and when. Absent for every other conversation.",
+    ),
     // Root repo's short base sha; per-repo bases stay daemon-internal.
     base: z.string().optional().describe("The commit its private copy started from, shortened."),
     costUsd: z.number().optional().describe("What it has cost so far, in dollars. A subagent's spend is its own and is not folded in here."),
@@ -484,7 +482,8 @@ export const AgentSummarySchema = z.object({
         .describe(
             "When somebody last opened it, in milliseconds. Newer activity than this is what makes it unread. Kept by the sandbox rather than by a browser, so clearing site data or picking up a phone does not resurrect every badge.",
         ),
-    // Browser-side words the daemon cannot read, reported so the unattended archive sweep never files them away.
+    // Derived from the drafts the sandbox holds (composer-drafts.ts), or reported by a client that keeps its own, so the
+    // unattended archive sweep never files away a conversation somebody is still writing to.
     unsentAt: z
         .number()
         .optional()
@@ -521,10 +520,10 @@ export const AgentSummarySchema = z.object({
         .describe(
             "The last attempt to bring its work into the workspace failed, and why. Cleared by the next land that goes through. Absent when nothing failed, and from a sandbox older than it.",
         ),
-    // The land's own last word on the owner's folder, for a project attached to this computer's sandbox: written there,
+    // The land's own last word on the owner's folder, for a sandbox made for one folder: written there,
     // partly kept out, waiting for the computer, or refused (schemas/project-delivery.ts).
     delivery: LandingDeliverySchema.optional().describe(
-        "What became of its last land in the folder on the owner's computer, for a project folder attached to this computer's sandbox. Absent for any other land, and from a sandbox older than it.",
+        "What became of its last land in the folder on the owner's computer, for a sandbox made for one folder. Absent for any other land, and from a sandbox older than it.",
     ),
     // Only the causes that still hold, re-read live (conversations/land/standing.ts), never the stored report's own list: a
     // blocker the user has since cleared is not something to offer them an action about.
@@ -543,6 +542,10 @@ export const AgentSummarySchema = z.object({
     proof: TurnProofSchema.optional().describe(
         "What its last turn showed of its work: whether a check it ran passed after its last edit, and whether it looked at interface files it changed. Absent until a turn that edited or checked anything has ended.",
     ),
+    // Written by the settle of the turn that reported a review, from its review frames; never asked of the model.
+    review: ReviewTallySchema.optional().describe(
+        "The latest code review this conversation reported: how many findings, and how many are still open. Absent until one has.",
+    ),
     // Written by the turn's own settle from its tool calls and a read of the clones and installs it could have touched;
     // replaced by every turn, so it says where the LAST turn's work went.
     reach: TurnReachSchema.optional().describe(
@@ -750,6 +753,19 @@ export const AgentTranscriptQuerySchema = AgentIdSchema.extend({
         .optional()
         .describe("Return the messages before this position in the record: the `from` of the page below. Absent asks for the most recent turns."),
     turns: z.coerce.number().int().min(1).max(200).optional().describe("How many of the user's turns to return, newest first. Absent takes the daemon's default."),
+    // Reading forward from the reader's cursor, checked by the row it names: a rewind since reuses positions.
+    after: z.coerce
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe(
+            "Return what the record holds from this position on: the `through` of the reader's last page. Answered `continuous` when it still runs through there; otherwise with its latest page. Ignored beside `before`.",
+        ),
+    afterRow: z
+        .string()
+        .optional()
+        .describe("The `rowId` of the row just before `after`, as the reader holds it: how a record rewound since is told apart from one that only grew."),
 });
 
 // Fills in what a page counted instead of carrying: a delegation's own calls, addressed by the card's id, which is
@@ -801,53 +817,6 @@ export const AgentsRemovedSchema = z.object({
         ),
 });
 export type AgentsRemoved = z.infer<typeof AgentsRemovedSchema>;
-// Searches only speech, both sides of the conversation, never thinking, tool output or protocol text, which would
-// otherwise match nearly the whole board. Two-char minimum; `caseSensitive` off means case-insensitive, matching
-// workspace search's own switch.
-export const AgentSearchQuerySchema = z.object({
-    query: z
-        .string()
-        .trim()
-        .min(2)
-        .describe(
-            "What to look for. Searched against what was said, both sides of the conversation, and nothing else: not the thinking, not the tool output, which between them name nearly every identifier in the workspace and would return most of the board.",
-        ),
-    caseSensitive: z.stringbool().optional().describe("Whether capitals matter."),
-});
-// Why a row survived the filter: the matched line, windowed, and who said it. `speaker` rides with the text since agent
-// prose alone can read as something the user typed.
-export const SpeakerSchema = z.enum(["user", "agent"]);
-export type Speaker = z.infer<typeof SpeakerSchema>;
-export const MatchSnippetSchema = z.object({
-    text: z.string().describe("The matching line, with a little either side of it."),
-    speaker: SpeakerSchema.describe(
-        "Who said it. Carried with the words rather than beside them, because a line of the agent's prose under a card reads as something you typed until the row says otherwise.",
-    ),
-});
-export type MatchSnippet = z.infer<typeof MatchSnippetSchema>;
-// One matching agent and its evidence; `snippet` is absent for a title match, which the card already shows.
-export const AgentMatchSchema = z.object({
-    id: z.string().describe("Which conversation matched."),
-    snippet: MatchSnippetSchema.optional().describe(
-        "Why, in its own words. Absent when the title was the match, which the card already shows: repeating it underneath is noise where evidence was wanted.",
-    ),
-});
-export type AgentMatch = z.infer<typeof AgentMatchSchema>;
-// How many agents were actually read, so the board can say a search saw less than the whole fleet.
-export const AgentSearchResultSchema = z.object({
-    matches: z.array(AgentMatchSchema).describe("What matched, from the live fleet and the archive together."),
-    scanned: z
-        .number()
-        .describe(
-            "How many conversations were actually read, so a screen can say when a search saw less than everything rather than implying it saw all of it.",
-        ),
-    indexing: z
-        .boolean()
-        .describe(
-            "Whether what was said is still being read in the background. True means this answer can still grow, so a screen must say it is incomplete rather than presenting it as the whole list.",
-        ),
-});
-export type AgentSearchResult = z.infer<typeof AgentSearchResultSchema>;
 // The user-chosen display title, bounded like sanitizeTitle's own cap.
 export const AgentRenameSchema = z.object({
     id: z.string().min(1).describe("Which conversation."),
@@ -871,19 +840,6 @@ export const AgentReactSchema = z.object({
         .describe("The mark to leave, as the emoji character itself. Exactly one: a chip has room for one mark, and a press is one press."),
     on: z.boolean().describe("Whether to add your mark or take it back. Saying what you want rather than flipping what is there, so pressing twice lands where pressing once did."),
 });
-// Bounded just above the handoff's per-message render cap, so a line too long to carry whole doesn't reach the agent
-// truncated.
-export const AgentPlaceSchema = z.object({
-    id: z.string().min(1).describe("Which conversation."),
-    text: z
-        .string()
-        .trim()
-        .min(1)
-        .max(8_000)
-        .describe(
-            "The words to put in the agent's mouth. Bounded just above what the next turn can carry whole, because a line too long to be handed over intact would reach the agent truncated and quietly break the very thing this is for.",
-        ),
-});
 // `null` clears the override back to inheriting the sandbox setting, so an agent doesn't hold a frozen copy that stops
 // following it.
 export const AgentAutoLandSchema = z.object({
@@ -895,7 +851,7 @@ export const AgentAutoLandSchema = z.object({
             "Whether its work merges automatically when a turn finishes. Null clears the override and goes back to following the sandbox-wide setting, so a conversation does not sit holding a frozen copy of a default it has quietly stopped following.",
         ),
 });
-// A composer's unsent words, reported by the editor that holds them: the words themselves stay in the browser.
+// A composer's unsent words, reported by a client that keeps them to itself rather than writing them as a draft.
 export const AgentUnsentSchema = z.object({
     id: z.string().min(1).describe("Which conversation."),
     at: z

package/src/schemas/attach.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { ConversationIdSchema } from "./agent.js";
+
+// Attaches to a conversation's newest run (live, or finished within retention); no cursor to resume from, the head
+// carries all rows. `run` names what the client was watching, so a newer run's head id tells it to catch up.
+export const AttachTurnSchema = z.object({
+    conversationId: ConversationIdSchema.describe("Which conversation to watch."),
+    run: z
+        .string()
+        .optional()
+        .describe(
+            "The run you were watching. The stream opens on the conversation's newest run whatever you name: if a newer turn has started since, the head names that one instead, and its rows are that turn's.",
+        ),
+    // The next run after one the reader saw end, which the conversation's queue starts a moment after: waited for here,
+    // where the start is an event, rather than looked for by a client asking again on a timer.
+    after: z
+        .string()
+        .optional()
+        .describe(
+            "A run you already watched to its end. The stream opens on the first run after it, waiting a few seconds for one to start (the message the conversation's queue sends next) before answering that nothing runs.",
+        ),
+});
+export type AttachTurn = z.infer<typeof AttachTurnSchema>;

package/src/schemas/command-admission.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+
+// The class of thing asking to start a session, the admission policy's key space; derived daemon-side, never sent by a
+// client. Chat and loops are absent since both begin with the owner's own click.
+export const WakeSourceSchema = z.enum(["schedule", "event", "listener", "webchat", "issues", "workspace", "workflow"]);
+export type WakeSource = z.infer<typeof WakeSourceSchema>;
+// One admission verdict the owner can configure: let it run, hold it for approval, or refuse it outright.
+export const AdmissionRuleSchema = z.enum(["allow", "hold", "deny"]);
+export type AdmissionRule = z.infer<typeof AdmissionRuleSchema>;
+// Where a command would run; the same string means different things on each machine (rm -rf /usr is recoverable here,
+// fatal on a laptop). Read with a locus (command-classes.ts CommandContext); callers must state one rather than
+// default.
+export const CommandLocusSchema = z.enum([
+    // This sandbox's own shell: a disposable container, /work a git worktree, /history every other agent's.
+    "sandbox",
+    // One of the owner's own computers, reached through the machine agent. Nothing here is disposable.
+    "device",
+]);
+export type CommandLocus = z.infer<typeof CommandLocusSchema>;
+// What kind of thing a shell command is, the command gate's key space under the admission floor; gates one command
+// inside an already-running session. Six classes, chosen because each is hard or impossible to undo somewhere.
+export const CommandClassSchema = z.enum([
+    // Rewrites or discards committed work: force-push, hard reset, force-delete a branch, clean -f, filter-branch.
+    "git.destructive",
+    // Moves a checkout to another branch. Only ever matches in a tree the conversation SHARES with its owner: inside
+    // its own copy a conversation may stand where it likes, and the drift that causes is reported, not refused.
+    "git.branch-switch",
+    // Recursive-force deletion (`rm -rf`), and its spelling in a script (`fs.rm(p, { recursive: true })`).
+    "files.destructive",
+    // State nothing recovers at this locus; which roots count (/, /history in the sandbox) depends on the locus.
+    "system.destructive",
+    // A container volume or its data; the sandbox's blast radius (nested engine) differs sharply from a device's.
+    "container.state",
+    // Reads credential material: a secret reference, or a file confirmed to actually hold one.
+    "secrets.access",
+    // Publishes outward and irreversibly: npm/pnpm/yarn/cargo publish, gh release create, docker push.
+    "package.publish",
+    // A network program (curl, nc, ssh, scp, …) or interpreter one-liner aimed at a non-loopback or run-time-built
+    // destination, the general exfiltration channel under the per-provider actionRules.
+    "network.outbound",
+]);
+export type CommandClass = z.infer<typeof CommandClassSchema>;
+// Workspace-wide admission floor per wake source, consulted on every outside-driven wake; composes with per-automation
+// overrides most-restrictive-wins. `workflow` is allow|deny only, since a hold there is indistinguishable from a CI
+// runner's timeout.
+export const AdmissionPolicySchema = z.object({
+    schedule: AdmissionRuleSchema.default("allow"),
+    event: AdmissionRuleSchema.default("allow"),
+    listener: AdmissionRuleSchema.default("allow"),
+    webchat: AdmissionRuleSchema.default("allow"),
+    // Defaults to hold, unlike the others: a bug-report wake has full repo powers and a stranger's stack trace as its
+    // brief.
+    issues: AdmissionRuleSchema.default("hold"),
+    workspace: AdmissionRuleSchema.default("allow"),
+    workflow: z.enum(["allow", "deny"]).default("allow"),
+});
+export type AdmissionPolicy = z.infer<typeof AdmissionPolicySchema>;

package/src/schemas/compose-overlay.test.ts

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { ComposedOverlayLineSchema } from "./compose-overlay.js";
+
+// The lines a target image's composer prints, as examples: golden/compose-overlay.json, which ic's reader is held to
+// (_sandbox/ic/src/sandbox/composition.rs). This is the TS half: each is a line the contract reads, its hash its overlay's.
+
+interface ComposeCase {
+    readonly name: string;
+    readonly base: string;
+    readonly line: unknown;
+}
+
+// SAFETY: the golden is this package's own file; the assertions below fail on any field it lacks.
+const GOLDEN = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "golden", "compose-overlay.json"), "utf8")) as { readonly cases: readonly ComposeCase[] };
+
+test("every golden line is a composer's line, its hash the overlay's own and its FROM the base it was asked for", () => {
+    expect(GOLDEN.cases.length).toBeGreaterThan(2);
+    for (const { base, line } of GOLDEN.cases) {
+        const read = ComposedOverlayLineSchema.parse(line);
+        expect(line).toEqual(read);
+        if (read.overlay === null) {
+            expect(read.hash).toBeUndefined();
+            continue;
+        }
+        expect(read.hash).toBe(createHash("sha256").update(read.overlay).digest("hex"));
+        expect(read.overlay).toContain(`\nFROM ${base}\n`);
+    }
+});
+
+test("a line in another format is not one this contract reads", () => {
+    expect(ComposedOverlayLineSchema.safeParse({ compose: 2, overlay: null }).success).toBe(false);
+});