@intentic/sandbox-contract 1.245.0 → 1.247.0

package/src/schemas/agent.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { KEY_PROVIDERS, NATIVE_PROVIDERS } from "../provider-specs.js";
+import { ModelRoleSchema } from "../model-roles.js";
+import { NATIVE_PROVIDERS } from "../provider-specs.js";
 import { AgentPlacementSchema } from "../runner-protocol.js";
 import { entryId } from "./internal.js";
 // The agent runtimes the daemon can serve, the vocabulary every surface that picks an agent shares (chat
@@ -21,11 +22,7 @@ export type AgentProvider = z.infer<typeof AgentProviderSchema>;
 // subjects are exactly the ones the daemon keeps one for. Closing it here is what makes an unknown id a 400 from
 // the contract instead of a registry lookup that reads back `undefined` and serves an empty list.
 export const NativeProviderParamSchema = z.object({ provider: z.enum(NATIVE_PROVIDERS) });
-// The provider naming an account on the routes that connect one by pasting a key (keys.contract.ts). Closed the
-// same way and for the same reason as the catalog param above, narrowed to the providers whose credential this
-// daemon actually stores as a key: pasting one at a provider that authenticates some other way is a 400 from
-// the contract rather than a handler discovering there is no store to write to.
-export const KeyProviderParamSchema = z.object({ provider: z.enum(KEY_PROVIDERS) });
+// The provider naming an account on the routes whose sign-in mints the vendor's own key (minted.contract.ts).
 // The harness (agentic loop) a turn runs on, orthogonal to the provider. See AgentTurnSchema.harness.
 export const AgentHarnessSchema = z.enum(["native", "claude-code"]);
 export type AgentHarness = z.infer<typeof AgentHarnessSchema>;
@@ -87,23 +84,55 @@ 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, and it changes what half of these classes MEAN.
+ *
+ * The same string is two different acts depending on which machine reads it. `rm -rf /usr` inside this
+ * container deletes files that come back with the image; on somebody's laptop it ends the laptop. A named
+ * Docker volume here is a dev database the agent created three commands ago; there it is whatever they run.
+ * `/work` and `/history` are this product's own trees and mean nothing on a device; `/Users` and `C:` are a
+ * device's and never appear here.
+ *
+ * So the catalog is read with a locus (command-classes.ts CommandContext), and the classes below are the
+ * answer to "what would this DO", asked of a stated place. Callers do not get to omit it: a default would be
+ * one of these two answers applied silently to the other machine, which is the bug this type exists to end. */
+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, the second layer under the admission
  * floor above. The floor decides whether a session may START; these decide whether one PARTICULAR command
  * inside a running session may go ahead, which is the only question left once the agent is already working.
  *
- * Five, chosen for one property: everything in them is hard or impossible to take back, so a person seeing it
- * once beats an audit trail read afterwards. Everything else an agent runs, builds, tests, greps, edits, is
- * recoverable in a container that is itself disposable, and gating it would be friction bought with nothing. */
+ * Six, chosen for one property: everything in them is hard or impossible to take back SOMEWHERE, so a person
+ * seeing it once beats an audit trail read afterwards. Everything else an agent runs, builds, tests, greps,
+ * edits, is recoverable in a container that is itself disposable, and gating it would be friction bought with
+ * nothing. "Somewhere" is the locus above: which class a command lands in is asked of a place. */
 export const CommandClassSchema = z.enum([
     // Rewrites or discards committed work: force-push, hard reset, force-delete a branch, clean -f, filter-branch.
     "git.destructive",
     // Recursive-force deletion (`rm -rf`), and its spelling in a script (`fs.rm(p, { recursive: true })`).
     "files.destructive",
-    /* State nothing here brings back: a formatted or overwritten disk, a deleted Docker volume, a recursive
-     * delete aimed at a root rather than at something inside one. The only class the daemon holds where the
-     * owner wrote no rule, which is why it is separate from files.destructive rather than a shade of it:
-     * `rm -rf build` is ordinary work in a disposable container and `rm -rf /` is the end of the machine. */
+    /* State nothing brings back AT THIS LOCUS: a formatted or overwritten disk, and a recursive delete aimed
+     * at a root rather than at something inside one. The class the daemon holds where the owner wrote no rule,
+     * which is why it is separate from files.destructive rather than a shade of it: `rm -rf build` is ordinary
+     * work in a disposable container and `rm -rf /` is the end of the machine.
+     *
+     * WHICH ROOTS COUNT IS THE LOCUS'S ANSWER, not a constant. In the sandbox it is `/` and `/history` — the
+     * filesystem itself, and the one tree holding work this turn cannot recreate because it is other
+     * conversations'. `/usr`, `/etc`, `/work` are NOT roots here: the container comes back from its image and
+     * the worktree's delta is uncommitted changes, both of which cost an afternoon rather than everything. On a
+     * device the full list applies, because nothing there is rebuilt from an image. */
     "system.destructive",
+    /* A CONTAINER VOLUME OR THE DATA IN IT: `docker volume rm`, `system prune`, `compose down -v`. Split out of
+     * system.destructive because the two loci disagree about it more sharply than about anything else in this
+     * enum. In the sandbox these reach the NESTED engine (the host's socket is never mounted, see
+     * capabilities/handlers/docker.ts), so the blast radius is dev databases the agent has been working
+     * against, and tearing down a smoke-test stack is ordinary work. Sent to somebody's own computer it is
+     * whatever they run on it, and their policy says never. */
+    "container.state",
     /* READS credential material: a `{{secret:NAME}}` reference (which becomes the value on the way into the
      * process), or a file that actually holds one — a dotenv, a private key, ~/.aws/credentials, an npmrc.
      * "Actually" is load-bearing and is checked rather than assumed where the caller can open the file: an
@@ -239,6 +268,23 @@ export const AgentTurnSchema = z
             .describe(
                 "Whether this turn's work merges into the workspace when it finishes. Overrides the conversation's own setting for this turn only.",
             ),
+        /* WHAT STARTED THIS TURN, when it was not a person at a composer, and therefore which of the owner's
+         * model lists answers for it (settings.modelRoles, model-roles.ts declares the roles).
+         *
+         * IT NAMES THE JOB, NOT THE TIER. Before this field there was one list for every unattended turn, so a
+         * production incident and a documentation sweep were configured together, and a surface added tomorrow
+         * inherited that tier by saying nothing. Now a starter says what it IS, and the owner gets to answer
+         * per job: cheap for the sweep, frontier for the incident.
+         *
+         * ONLY FILLS A SILENCE. The daemon applies the role's list to a turn that named no model AND no
+         * provider (turn-resume.ts): a caret pick, an acceptance run's own choice, a workflow step pinned to a
+         * provider — all of those already answered the question, and this must not overrule them.
+         *
+         * A `run` role, always. The `helper` roles never reach here: a one-shot is not a turn, it has no
+         * conversation and no worktree, and it asks its own role directly at the seam that spends it. */
+        runRole: ModelRoleSchema.optional().describe(
+            "What started this turn, when it was not a person typing: which of the sandbox's per-job model lists answers for it. Only used when the turn names no model of its own.",
+        ),
         // 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.
@@ -283,7 +329,7 @@ export const AgentTurnSchema = z
          * opposite defaults, the chat wants the provider's own catalog default, an unattended run wants the
          * tier its owner chose for work that spends money while they are not watching.
          *
-         * The daemon fills `agent`/`model` and the pinned entry's own knobs from agentRunModels for any turn that says
+         * The daemon fills `agent`/`model` and the pinned entry's own knobs from the turn's own role list for any turn that says
          * this and names none of them (startConversationTurn), walking that list until one can actually be
          * started. Naming one still wins: every surface-started run now carries a caret that overrides the list
          * for that run alone, and Acceptance picks per run because it fans a session out per story. Either way
@@ -388,14 +434,14 @@ export type AgentTurn = z.infer<typeof AgentTurnSchema>;
  * Shared rather than re-declared per route because every surface that starts an agent for the user now carries
  * that caret, and they must all mean the same thing by it: the pair rides onto the turn as `agent`/`model`, and
  * the daemon's own fill step then leaves it alone (turn-resume.ts fills only what is absent). ABSENT is the
- * ordinary case and the one to keep cheap, nobody touched the caret, so `agentRunModels` answers.
+ * ordinary case and the one to keep cheap, nobody touched the caret, so the turn's `runRole` list answers.
  *
  * Both halves or neither, because a model id is only meaningful to the provider that vends it: half a pick
  * would send a Codex model id to Claude. Routes that accept this pass it through verbatim; a model this build
  * has never heard of is a supported pick, since the picker offers a custom-id escape hatch.
  *
  * AND THE TIER IT RUNS AT, because naming a model is only half of what the standing setting says. A pinned
- * entry carries its own effort (AgentRunPinSchema), and the daemon applies the pin's knobs ONLY to a turn that
+ * entry carries its own effort (ModelPinSchema), and the daemon applies the pin's knobs ONLY to a turn that
  * named no model (turn-resume.ts): so a caret that could re-point the model but not the tier moved every
  * override onto the provider's own default effort, and the one moment somebody reaches for the caret is the
  * failure that just beat the standing order. Optional, and absent means absent, the turn goes out without an
@@ -414,29 +460,36 @@ export const AgentRunPickSchema = z
     })
     .optional();
 export type AgentRunPick = z.infer<typeof AgentRunPickSchema>;
-/* A MODEL PINNED FOR EVERY SURFACE-STARTED RUN, one entry of settings.agentRunModels: the standing version of
- * the pick above, and not merely which model but HOW it is to be run.
+/* ONE ENTRY OF ONE ROLE'S MODEL LIST (settings.modelRoles): the standing version of the pick above, and not
+ * merely which model but HOW it is to be run.
  *
- * THE KNOBS RIDE THE ENTRY RATHER THAN THE LIST, which is the whole reason this is an object where the setting
- * used to hold a `${provider}:${model}` string. The reasoning effort was a single field beside the list, so one
- * tier answered for every model in it — and the entries of that list are deliberately NOT interchangeable: it
- * is a frontier pin with the cheap account underneath that catches it when the first is spent. A tier scale is
- * a property of the MODEL as well ('max' is off Kimi's scale entirely, and off Claude's own the moment thinking
+ * THE KNOBS RIDE THE ENTRY RATHER THAN THE LIST, which is the whole reason this is an object rather than a
+ * `${provider}:${model}` string. The reasoning effort was once a single field beside a list, so one tier
+ * answered for every model in it — and the entries of such a list are deliberately NOT interchangeable: it is a
+ * frontier pin with the cheap account underneath that catches it when the first is spent. A tier scale is a
+ * property of the MODEL as well ('max' is off Kimi's scale entirely, and off Claude's own the moment thinking
  * is switched off), so a shared effort was either off-scale for half the list or the lowest common rung for all
- * of it. Each entry now carries what the composer's picker configures for the turn in front of you.
+ * of it. Each entry carries what the composer's picker configures for the turn in front of you.
+ *
+ * THE SAME SHAPE FOR EVERY ROLE, one-shot helpers included, and that is a deliberate widening. A commit
+ * message or a session title used to be pinnable by model alone, on the argument that the daemon runs those
+ * with reasoning off and no effort, so a control for either would be a switch with nothing behind it. True of
+ * the machinery, and it made the machinery the argument: an owner who pins a reasoning model to their commit
+ * subjects was paying that model's price to have its distinguishing feature suppressed. The knobs now travel
+ * through the one-shot path too, so an entry means the same thing wherever it is written.
  *
- * EVERY FIELD BUT THE PAIR IS OPTIONAL, AND ABSENT MEANS ABSENT: the turn goes out without the field and the
+ * EVERY FIELD BUT THE PAIR IS OPTIONAL, AND ABSENT MEANS ABSENT: the work goes out without the field and the
  * provider's own default answers, exactly as an unconfigured pin always did. Nothing here invents a "low".
  *
  * NO TIER HOLD, and its absence is the rule rather than an omission: automatic tier selection gates on
- * `unattended` (prompt-complexity.ts), so a surface-started run is never downgraded in the first place and a
- * veto over it would be a control whose state can make no difference to anything.
+ * `unattended` (prompt-complexity.ts), so a role-started run is never downgraded in the first place and a veto
+ * over it would be a control whose state can make no difference to anything.
  *
  * The pair is BOTH HALVES for the reason the pick above is: a model id is only meaningful to the provider that
  * vends it, so half a pin would send a Codex id to Claude. Taken verbatim, never validated against a catalog:
  * the picker offers a custom-id escape hatch, so a model this build has never heard of is a supported pin. */
-export const AgentRunPinSchema = z.object({
-    provider: AgentProviderSchema.describe("Which provider serves the run."),
+export const ModelPinSchema = z.object({
+    provider: AgentProviderSchema.describe("Which provider serves this work."),
     model: z.string().min(1).describe("Which of its models. Both halves, because a model name only means anything to the provider that serves it."),
     effort: z
         .string()
@@ -446,7 +499,7 @@ export const AgentRunPinSchema = z.object({
     fast: z.boolean().optional().describe("Ask for this model's work at a higher rate for a higher price. A request rather than a promise."),
     harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Leave it out to use the provider's own."),
 });
-export type AgentRunPin = z.infer<typeof AgentRunPinSchema>;
+export type ModelPin = z.infer<typeof ModelPinSchema>;
 // POST /agent's ack: the daemon-minted id of the detached turn run it started. The turn executes daemon-side
 // regardless of any client connection; every window, the initiator included, renders it via /agent/attach.
 export const StartedTurnSchema = z.object({

package/src/schemas/agents.ts

@@ -95,6 +95,45 @@ export const AgentAttentionSchema = z.object({
     conflict: z.boolean().describe("Its work cannot be merged without somebody resolving a clash."),
 });
 export type AgentAttention = z.infer<typeof AgentAttentionSchema>;
+/* WHAT THE LAST TURN LEFT OPEN, as the turn itself measured it at the moment it ended.
+ *
+ * Every other "needs you" on this card is a turn PARKED on somebody (AgentAttentionSchema): the agent is still
+ * there, waiting, and the board can say so because the pause is live. This is the opposite shape and the reason
+ * it is a field of its own: the turn is over, nobody is waiting, and the work stopped short anyway. That card
+ * reads `idle` beside a hundred others that finished what they were asked, which is how a session with three of
+ * seven steps still open goes back onto the board looking exactly like a session that is done.
+ *
+ * DERIVED, NEVER DECLARED, and that is the whole design constraint. Nothing here asks a model anything or asks
+ * an agent to report on itself: both readings are taken from frames the daemon already receives on every
+ * harness, once, at the finish that flushes the turn's tokens and tool counts. An agent cannot flatter this
+ * field, and a harness that never learned about it still fills it.
+ *
+ * Absent for the ordinary card, which is most of them: a turn that ends with its list clear and its check green
+ * has nothing to say here, and neither has one that kept no list and stood under no check. */
+export const UnfinishedWorkSchema = z.object({
+    // When the turn that left it this way ended, ms since epoch. What the mark's "…, 2h ago" is measured from,
+    // and NOT `updatedAt`: a card touched since (a land, a rename) has moved without the work moving.
+    at: z.number().describe("When the turn that left this ended, in milliseconds."),
+    /* THE AGENT'S OWN CHECKLIST, as of that turn's last word on it (the `todos` frames). `open` counts every
+     * item not marked completed, `total` the whole list, and `next` names the one it would have done next, the
+     * in-progress item if there is one, else the first still pending.
+     *
+     * It is the agent's own account of the job, so a count here is not an inference about what it meant: it is
+     * the list it wrote, with items on it nobody crossed off. Absent when the conversation kept no list. */
+    steps: z
+        .object({
+            open: z.number().describe("Items on it that were never completed."),
+            total: z.number().describe("Items on the whole list."),
+            next: z.string().optional().describe("The one it would have done next: what it was working through, or the first still waiting."),
+        })
+        .optional()
+        .describe("The agent's own checklist where that turn left it. Absent for a conversation that kept no list."),
+    // The name of the `turn.ending` check that ran red on the way out, when one did (rules/turn-ending.ts). A
+    // turn gets two rounds to repair what a check reports and can then end regardless, so this is the workspace's
+    // own gate saying the work is not done, in a place nothing but the land used to read.
+    check: z.string().optional().describe("The end-of-turn check that was still failing when the turn ended, by name."),
+});
+export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
 /* WHAT A LANDING IS CALLED, the commit message drafted from the landed diff (agents/landed-subject.ts), and
  * the whole of it: a subject, and the two trailer sentences a repo that keeps a changelog gets.
  *
@@ -143,8 +182,8 @@ export const LandedMessageSchema = z.object({
         .describe("What this change takes away, for anything already relying on it. Nearly always absent: it is for removals, not for additions."),
 });
 export type LandedMessage = z.infer<typeof LandedMessageSchema>;
-/* ONE MODEL'S TURN IN THE DRAFTING WALK, asked, and what became of the ask. The quick-model chain tries the
- * connected models in order (agent/quick-model.ts), and each rung ends one of four ways:
+/* ONE MODEL'S TURN IN THE DRAFTING WALK, asked, and what became of the ask. The one-shot helper chain tries the
+ * connected models in order (agent/role-model.ts), and each rung ends one of four ways:
  *   asking  , in flight right now; `ms` absent because it is still being spent.
  *   answered, it wrote the sentence, in `ms`.
  *   refused , it failed or declined, in `ms`, with its own words in `reason`.
@@ -361,7 +400,7 @@ export const AgentSummarySchema = z.object({
     // 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().describe("The commit its private copy started from, shortened."),
-    costUsd: z.number().optional().describe("What it has cost so far, in dollars. A helper agent's spend is its own and is not folded in here."),
+    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."),
     inputTokens: z.number().optional().describe("Tokens sent."),
     outputTokens: z.number().optional().describe("Tokens received."),
     contextTokens: z.number().optional().describe("How much of the window the conversation currently fills."),
@@ -414,6 +453,12 @@ export const AgentSummarySchema = z.object({
             "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.",
         ),
     attention: AgentAttentionSchema.describe("Which kinds of waiting-for-you it is doing."),
+    /* What the last turn left open, when it left anything (UnfinishedWorkSchema). Beside `attention` because a
+     * reader asks both questions in the same glance, and apart from it because the answers have opposite
+     * shapes: attention is a turn parked and waiting, this is a turn gone with the job half done. */
+    unfinished: UnfinishedWorkSchema.optional().describe(
+        "What its last turn left open: steps it never completed, a check still failing. Absent for a turn that finished what it started.",
+    ),
     // Completed turns and lifetime tool calls, the card's msgs/tools counters.
     turns: z.number().optional().describe("Turns it has finished."),
     toolUses: z.number().optional().describe("Tools it has used, over its whole life."),
@@ -431,12 +476,12 @@ export const AgentSummarySchema = z.object({
      * the Subagents area is where it is attributed. */
     subagents: z
         .object({
-            running: z.number().describe("Helpers working right now."),
-            total: z.number().describe("Helpers it has started over its whole life."),
+            running: z.number().describe("Subagents working right now."),
+            total: z.number().describe("Subagents it has started over its whole life."),
         })
         .optional()
         .describe(
-            "Helper agents this one delegated to. Absent means it never has, which is most conversations. Their spend is their own and is not folded into this conversation's cost.",
+            "Subagents and child agents this one delegated to. Absent means it never has, which is most conversations. Their spend is their own and is not folded into this conversation's cost.",
         ),
     // The agent's cumulative output (base → branch tip across every repo), refreshed on each land,
     // the card's "12 files · +412 −96" readout. Independent of what has landed.
@@ -573,6 +618,22 @@ export type AgentWatch = NonNullable<AgentSummary["watches"]>[number];
 // AgentsListSchema lives further down, after AutomationApprovalSchema, the fleet list carries the held wakes,
 // and zod declaration order forces the ride-along to be declared first.
 export const AgentIdSchema = z.object({ id: z.string().min(1).describe("Which conversation.") });
+
+/* ASKING FOR ONE PAGE OF A CONVERSATION. A transcript read answers with the most recent turns and says where
+ * they start (`from`); handing that number back as `before` asks for the page above it, and so on to the
+ * beginning. Both are optional: a tab opening a chat sends neither and gets the tail.
+ *
+ * A cursor is never an error. It can be stale by the time it arrives — a rewind truncated the record under it,
+ * a fork re-cut it, the tab slept through both — and the daemon clamps rather than refusing, because failing
+ * to open a conversation is a worse answer than opening it at the end. */
+export const AgentTranscriptQuerySchema = AgentIdSchema.extend({
+    before: z.coerce
+        .number()
+        .int()
+        .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."),
+});
 // 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).
 export const AgentArchiveSchema = z.object({

package/src/schemas/automations.ts

@@ -233,10 +233,12 @@ export const WebchatPublicConfigSchema = z.object({
     googleClientId: z.string().optional(),
 });
 export type WebchatPublicConfig = z.infer<typeof WebchatPublicConfigSchema>;
-// A proof-of-work challenge: find a nonce whose SHA-256 of `${salt}:${nonce}` starts with `difficulty` zero
-// bits. Issued per visitor conversation, spent on its first message.
-export const WebchatChallengeSchema = z.object({ salt: z.string(), difficulty: z.number().int().positive() });
-export type WebchatChallenge = z.infer<typeof WebchatChallengeSchema>;
+/* A proof-of-work challenge: find a nonce whose SHA-256 of `${salt}:${nonce}` starts with `difficulty` zero
+ * bits. ONE shape for every public door (the Front Desk issues it per visitor conversation and spends it on the
+ * first message; the bug intake per reporter, on a written report), and one solver on the embeds' side
+ * (embed.ts, which declares the same two fields without zod). */
+export const PowChallengeSchema = z.object({ salt: z.string(), difficulty: z.number().int().positive() });
+export type PowChallenge = z.infer<typeof PowChallengeSchema>;
 // One visitor message. `conversationId` is the widget's own localStorage id, it threads the visitor's messages
 // into ONE sandbox conversation, so it is the thread key, not a secret (anyone can mint one; the origin
 // allowlist, the challenge and the rate limit are the gate).

package/src/schemas/capabilities.ts

@@ -277,7 +277,7 @@ export const IdentityConfigSchema = z.object({
     exit: z.string().optional(),
 });
 export type IdentityConfig = z.infer<typeof IdentityConfigSchema>;
-/* A connected COMPUTER of the user's own, the inverse of `ssh`, which reaches a server the sandbox can dial.
+/* A connected DEVICE of the user's own, the inverse of `ssh`, which reaches a server the sandbox can dial.
  * A machine behind NAT can't be dialled, so it dials US: the @intentic/machine agent (installed by a one-liner,
  * enrolled with a single-use pairing token) holds one outbound WebSocket to this daemon and serves an MCP tool
  * surface, shell, files, screenshots, from the far end. The daemon tunnels the agent's JSON-RPC over it and
@@ -331,7 +331,7 @@ export const HostScopesSchema = z.object({
      * and cannot park it while somebody thinks, so the honest form of "ask me" here is "refuse until they
      * ticked it", which is exactly what a scope is.
      *
-     * Default off, with `shell` default ON, which is the pairing to read carefully: a connected computer runs
+     * Default off, with `shell` default ON, which is the pairing to read carefully: a connected device runs
      * commands out of the box, because that is what people connect one for, and the ones that delete are the
      * ones they have to say yes to. */
     destructive: hostScope.default("off"),
@@ -342,7 +342,7 @@ export type HostScopes = z.infer<typeof HostScopesSchema>;
 export const HostConfigSchema = HostScopesSchema.extend({ platform: z.string().min(1) });
 /* THE USER'S OWN BROWSER, reached through the extension they installed in it: the `webext` capability's config.
  *
- * The sibling of `host` and deliberately not an arm of it. A connected computer runs commands; a connected
+ * The sibling of `host` and deliberately not an arm of it. A connected device runs commands; a connected
  * browser has one power a sandbox's own Chromium can never have, and it is the whole reason this kind exists:
  * it is ALREADY SIGNED IN, as the person, with their passkeys, their hardware second factor, their corporate
  * SSO and their genuine fingerprint. That is the set of sites the sandbox's browser cannot reach at all, and
@@ -361,7 +361,7 @@ export const WebExtScopesSchema = z.object({
     // Read a granted page: its elements, its text, its tabs. The floor of usefulness, so it defaults on; with
     // it off the connection is inert and the card says so rather than pretending.
     read: webextScope.default("on"),
-    /* Click, type, press keys, navigate. ON by default, unlike a computer's `control`, and the difference is
+    /* Click, type, press keys, navigate. ON by default, unlike a device's `control`, and the difference is
      * what the two things ARE: driving a desktop is the last resort after every command-line route failed,
      * while driving the page IS this connector — a browser connection that may only look is a worse version
      * of fetching the URL. The grant that actually bounds it is per-site and lives in the browser. */

package/src/schemas/ci.ts

@@ -9,11 +9,25 @@ import { AgentRunPickSchema } from "./agent.js";
 
 export const CiHostSchema = z.enum(["github", "gitlab"]);
 export type CiHost = z.infer<typeof CiHostSchema>;
-// Terminal-or-not over both vendors' vocabularies: github's status+conclusion pair and gitlab's single status
-// both collapse onto these five. `running` covers everything non-terminal (queued, manual, preparing …), the
-// view only needs "still moving" vs the three ways it stopped.
-export const PipelineStatusSchema = z.enum(["running", "success", "failed", "canceled", "skipped"]);
+/* Both vendors' vocabularies over one enum: github's status+conclusion pair and gitlab's single status collapse
+ * onto these six.
+ *
+ * QUEUED IS ITS OWN STATE AND NOT A FLAVOUR OF RUNNING, which it used to be, on the reasoning that a view only
+ * needs "still moving" vs the three ways it stopped. What that produced is a board that spins over work nothing
+ * is doing: a nightly whose six self-hosted jobs are waiting for a runner that is offline reads as six jobs in
+ * progress, with a duration ticking up, for as long as the runner stays down. The distinction is not cosmetic,
+ * it is the difference between "wait" and "go look at your runners", and it is the only question a reader of a
+ * stuck pipeline actually has.
+ *
+ * The two are still one class for everything that asks "has this said anything yet": neither is a verdict, and
+ * the callers that care read them as a pair. */
+export const PipelineStatusSchema = z.enum(["queued", "running", "success", "failed", "canceled", "skipped"]);
 export type PipelineStatus = z.infer<typeof PipelineStatusSchema>;
+/* Whether a run or a job has yet to say anything, the pair against the three ways one stops. Here rather than
+ * in either consumer because both ends split on it and must split the same way: the daemon, to know that the
+ * span between two timestamps is not yet a duration, and the board, to count what is in flight, to keep a
+ * Cancel button on offer, and to leave a run out of a verdict walk. */
+export const isPipelineInFlight = (status: PipelineStatus): boolean => status === "queued" || status === "running";
 export const PipelineRunSchema = z.object({
     // The workspace repo dir (the panels `repo` convention), the join key back to the tree and to triggers.
     repo: z.string().describe("Which workspace repository it belongs to."),
@@ -45,7 +59,7 @@ export const PipelineRunSchema = z.object({
     branch: z.string().describe("Which branch."),
     sha: z.string().describe("Which commit."),
     status: PipelineStatusSchema.describe(
-        "How it is going. Running covers everything still moving, since the only distinction that matters is that against the three ways it can stop.",
+        "How it is going. Queued means the forge has accepted it and nothing is executing it yet, which is a different thing to wait on than a run actually in progress.",
     ),
     // The vendor's run page, the deep link out.
     url: z.string().describe("Its page on the forge."),
@@ -71,7 +85,10 @@ export type PipelineRun = z.infer<typeof PipelineRunSchema>;
  *   2. `stage`. GitLab's native sequential grouping, returned by its jobs API and used verbatim.
  *   3. The timestamps, the last resort, and GitHub's before `needs` existed: overlapping runtimes ⇒ the jobs
  *      ran in parallel. Honest about when things happened, silent about what actually gated what.
- * Both timestamps are epoch ms; absent while a job is still queued. */
+ * Both timestamps are epoch ms, and a `queued` job carries NEITHER. That is an invariant the normalizers hold
+ * up rather than something a vendor gives: GitHub reports a `started_at` on a job that has never started, set
+ * to the moment the run was queued, so a job waiting an hour for a runner arrives claiming an hour of work.
+ * Everything downstream reads a present `startedAt` as "this began", so the lie has to be dropped at the edge. */
 export const PipelineJobSchema = z.object({
     name: z.string().describe("The job's name."),
     status: PipelineStatusSchema.describe("How it went."),

package/src/schemas/context.ts

@@ -0,0 +1,87 @@
+// context: which part of the workspace a conversation carries
+import { z } from "zod";
+import { entryId } from "./internal.js";
+
+/* A CONVERSATION SEES A CHOSEN PART OF THE WORKSPACE, and these three schemas are how the choice is spelled.
+ *
+ * A workspace grows into more than any one session should open on: dozens of repositories, hundreds of skills,
+ * a shelf of reference clones. Every conversation used to get all of it, one worktree per repository, frozen at
+ * its first turn (sandbox agents/worktrees.ts). The cost is paid twice, in checkouts nobody reads and in a
+ * project map and a skill listing that describe everything to a session that needs a corner of it
+ * (docs/context-composition-plan.md at the workspace root measures both).
+ *
+ * THREE WORDS. A SHELF is what the owner writes: the items a session MAY take, in the order they are loaded and,
+ * when a cap bites, shed from the tail. A COMPOSITION is the pick for one conversation, a list of item ids in
+ * shelf order, stored on its registry entry. An ITEM ID names one thing in the workspace, `<kind>:<name>`.
+ *
+ * ONE KIND TODAY, `repo:`, which is the whole of what a composition can make real: a repository is in the
+ * conversation (a worktree of it exists) or it is not (the directory does not exist). The grammar takes a kind
+ * prefix so the next ones (a directory inside a repository through a sparse cone, a skill folder, a reference
+ * shelf entry, a capability) widen this list and change nothing else. The root repository is never an item: it
+ * is the workspace itself and every conversation stands in it. */
+export const CONTEXT_ITEM_KINDS = ["repo"] as const;
+export type ContextItemKind = (typeof CONTEXT_ITEM_KINDS)[number];
+
+/* `<kind>:<name>`. The name is a workspace-relative path or an id: safe segments, no `..`, no empty segment, so
+ * joining it under a root can never escape, the same shape repo-discovery.ts accepts for a repo id. */
+const ITEM = /^(repo):[a-zA-Z0-9][a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/;
+export const ContextItemIdSchema = z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(ITEM)
+    .describe("One thing in the workspace a conversation can carry, as `<kind>:<name>`. Today the kind is `repo` and the name is a repository's workspace-relative path.");
+export type ContextItemId = z.infer<typeof ContextItemIdSchema>;
+
+// The two halves of an id, for the code that has to act on the name. The schema above already proved the shape.
+export const contextItem = (id: ContextItemId): { readonly kind: ContextItemKind; readonly name: string } => {
+    const at = id.indexOf(":");
+    return { kind: id.slice(0, at) as ContextItemKind, name: id.slice(at + 1) };
+};
+
+/* HOW MANY OF EACH KIND A COMPOSITION MAY HOLD. Counted per kind because the kinds cost differently: a repository
+ * is a checkout, a skill is a line in every prompt. Absent means no limit. A pinned item is never shed to meet
+ * a cap: `pinned` is the owner saying "always", and a cap that could override it would make two fields disagree
+ * about the same item. */
+export const ContextCapsSchema = z.object({
+    repos: z.number().int().min(0).optional().describe("How many repositories a composition may hold. Absent means as many as the shelf allows."),
+});
+export type ContextCaps = z.infer<typeof ContextCapsSchema>;
+
+/* WHAT A SESSION MAY TAKE, in the owner's order. One file per shelf under `.intentic/config/context/<id>.json`,
+ * tracked and carried like a persona card (workspace-state.ts), for the same reason: a shelf is a list of
+ * names, holds no credential, and belongs in a pull request.
+ *
+ * `allowed` IS ORDERED, and the order is the only priority there is: it is what a curator is shown, the order
+ * items are loaded, and the order they are shed from the tail when a cap is hit. The owner fixes the order and
+ * the ceiling; whoever picks (a model, a person on the card, the shelf itself when nobody picks) decides
+ * membership and nothing else.
+ *
+ * `pinned` is always in, whether or not it is also listed in `allowed`. `denied` wins over everything, including
+ * a pinned item, so a shelf that inherits a list it did not write can still take one thing off it. */
+export const ContextShelfSchema = z.object({
+    id: entryId.describe("The shelf's id, which is also its file name."),
+    label: z.string().max(60).optional().describe("What to call it on screen. Absent falls back to the id."),
+    pinned: z.array(ContextItemIdSchema).max(200).default([]).describe("Items every composition from this shelf carries."),
+    allowed: z
+        .array(ContextItemIdSchema)
+        .max(500)
+        .default([])
+        .describe("Items a composition may carry, in the order they are loaded and shed. The order is the priority; nothing else is."),
+    denied: z.array(ContextItemIdSchema).max(200).default([]).describe("Items no composition from this shelf carries, whatever else says so."),
+    caps: ContextCapsSchema.optional().describe("How many of each kind a composition may hold."),
+});
+export type ContextShelf = z.infer<typeof ContextShelfSchema>;
+
+/* THE PICK FOR ONE CONVERSATION, on its registry entry beside the worktree composition it decides.
+ *
+ * `items` is exactly what the conversation carries, in shelf order, and the root repository besides. A
+ * conversation whose entry has NO composition carries everything the workspace has, which is what every
+ * conversation did before shelves existed and what a conversation opened with no shelf still does. Those two
+ * are one state on purpose: the absence is the answer, and a stored "everything" would be a second spelling of
+ * it that could disagree with the first. */
+export const ContextCompositionSchema = z.object({
+    shelf: entryId.optional().describe("Which shelf this pick was made from. Absent when the items were set without one."),
+    items: z.array(ContextItemIdSchema).max(500).describe("What the conversation carries, in shelf order. The root repository is always carried and never listed."),
+});
+export type ContextComposition = z.infer<typeof ContextCompositionSchema>;