@intentic/sandbox-contract 1.232.0 → 1.234.0

package/src/credential-material.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "vitest";
+import { holdsCredentialMaterial } from "./credential-material.js";
+
+/* The two directions are not symmetric and the tests are written to say so: a MISS here costs one permission
+ * card that should not have been raised, and a WRONG CLEAR un-gates a real credential read. So the "no" cases
+ * are the ones that have to be exactly right, and every "yes" case is a real file's real shape. */
+
+describe("files that hold a credential", () => {
+    test("an npmrc with a token", () => {
+        expect(holdsCredentialMaterial("//registry.npmjs.org/:_authToken=npm_wCq3nTvR8xLm2ZbKp7HdJyE4sUaF6gN0iQ1t\n")).toBe(true);
+    });
+
+    test("an aws credentials ini", () => {
+        expect(
+            holdsCredentialMaterial("[default]\naws_access_key_id = AKIAIOSFODNN7EXAMPLE\naws_secret_access_key = wJalrXUtnFEMI/K7MDENG\n"),
+        ).toBe(true);
+    });
+
+    test("a private key file, whatever generated it", () => {
+        for (const text of [
+            "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAA\n-----END OPENSSH PRIVATE KEY-----\n",
+            "-----BEGIN RSA PRIVATE KEY-----\nMIIEow\n",
+            "-----BEGIN PRIVATE KEY-----\nMIIEvQ\n",
+            "PuTTY-User-Key-File-3: ssh-ed25519\nEncryption: none\n",
+        ]) {
+            expect(holdsCredentialMaterial(text), text.slice(0, 30)).toBe(true);
+        }
+    });
+
+    // `.git-credentials` is nothing but these lines, and a dotenv hides the same secret inside a connection
+    // string, where no key names it.
+    test("a password carried in a URL", () => {
+        expect(holdsCredentialMaterial("https://radarsu:ghp_S8kQ2mVx@github.com\n")).toBe(true);
+        expect(holdsCredentialMaterial("DATABASE_URL=postgres://app:Rk29fPqz@db.internal:5432/app\n")).toBe(true);
+    });
+
+    test("a dotenv with one real value among the ordinary ones", () => {
+        expect(holdsCredentialMaterial("PORT=3000\nNODE_ENV=production\nSTRIPE_SECRET=sk_live_51H8xQzRvKpLmNbTy\n")).toBe(true);
+    });
+
+    test("a json credentials file", () => {
+        expect(holdsCredentialMaterial('{"accessToken":"ya29.a0AfB_bJq2Lm","expiresAt":1767000000}')).toBe(true);
+    });
+
+    // The issuers whose tokens announce themselves, found without any key naming them.
+    test("a token that carries its own prefix", () => {
+        for (const text of [
+            "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
+            "xoxb-2410-1230-AbCdEfGhIjKlMnOpQrSt",
+            "AKIAIOSFODNN7EXAMPLE",
+            "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
+        ]) {
+            expect(holdsCredentialMaterial(text), text.slice(0, 20)).toBe(true);
+        }
+    });
+});
+
+describe("files that do not", () => {
+    /* THE FILE THAT STARTED THIS. An npmrc is the most-named credential path in this workspace's own commands
+     * and most of them are three lines of registry config. */
+    test("an npmrc with only registry config", () => {
+        expect(holdsCredentialMaterial("registry=https://registry.npmjs.org/\nengine-strict=true\nstore-dir=/root/.pnpm-store\n")).toBe(
+            false,
+        );
+    });
+
+    test("a dotenv of ports and flags", () => {
+        expect(holdsCredentialMaterial("PORT=3000\nNODE_ENV=development\nVITE_API_URL=http://localhost:8080\nLOG_LEVEL=debug\n")).toBe(false);
+    });
+
+    /* THE TEMPLATE THAT IS STILL A TEMPLATE. A key named `TOKEN` proves nothing on its own — half the dotenvs
+     * in a monorepo are this file, waiting for someone to fill them in. */
+    test("a dotenv whose credential keys are still placeholders", () => {
+        expect(
+            holdsCredentialMaterial(
+                [
+                    "GITHUB_TOKEN=",
+                    "NPM_TOKEN=${NPM_TOKEN}",
+                    "API_KEY=<your-api-key>",
+                    'CLIENT_SECRET=""',
+                    "DB_PASSWORD=changeme",
+                    "SLACK_TOKEN=xxxxxxxx",
+                    "STRIPE_SECRET={{secret:STRIPE}}",
+                    "AUTH_TOKEN=your-token-here",
+                    "SESSION_SECRET=REDACTED",
+                ].join("\n"),
+            ),
+        ).toBe(false);
+    });
+
+    // The public half of a keypair, and the host list beside it: named in the same directory, credential
+    // material in neither.
+    test("the public files an ssh directory is full of", () => {
+        expect(holdsCredentialMaterial("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH1x radarsu@omen\n")).toBe(false);
+        expect(holdsCredentialMaterial("github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzr\n")).toBe(false);
+        expect(holdsCredentialMaterial("Host github.com\n  User git\n  IdentityFile ~/.ssh/id_ed25519\n")).toBe(false);
+    });
+
+    test("a key whose name only looks like one", () => {
+        expect(holdsCredentialMaterial("TOKEN_EXPIRY=3600\nREFRESH_TOKEN_URL=https://auth.example.com/refresh\nMAX_TOKENS=8192\n")).toBe(
+            false,
+        );
+    });
+
+    // A dev default is a real password in the strictest reading and nothing this class exists to stop; the
+    // length floor is what draws that line.
+    test("a dev-compose default is not what the card is for", () => {
+        expect(holdsCredentialMaterial("POSTGRES_PASSWORD=dev\nREDIS_PASSWORD=x\n")).toBe(false);
+    });
+
+    test("an empty file", () => {
+        expect(holdsCredentialMaterial("")).toBe(false);
+        expect(holdsCredentialMaterial("\n\n# nothing here\n")).toBe(false);
+    });
+
+    // A URL with a port is not a URL with a password: `user:pass@` needs both halves and the `@`.
+    test("an ordinary url is not userinfo", () => {
+        expect(holdsCredentialMaterial("API=http://localhost:8080/v1\nSENTRY_DSN=https://abc123@o1.ingest.sentry.io/1\n")).toBe(false);
+    });
+});

package/src/credential-material.ts

@@ -0,0 +1,100 @@
+/* WHETHER A FILE ACTUALLY HOLDS A CREDENTIAL, the fact that `secrets.access` only guesses at from a path.
+ *
+ * The classifier next door (command-classes.ts) reads shell text, so the strongest thing it can honestly say
+ * about `sed … ~/.npmrc` is "this names a file that USUALLY holds a token". Usually is not always, and the gap
+ * is where the class earns its reputation: most `~/.npmrc` files are three lines of registry config, most
+ * `.env` files in a monorepo are ports and feature flags, `~/.ssh/known_hosts` is a list of public keys, and a
+ * file that does not exist reads nothing at all. A card raised over one of those is not a near miss, it is
+ * noise, and noise is what teaches an owner to answer the card without reading it, which is precisely how a
+ * real credential read gets waved through six weeks later.
+ *
+ * So the class is split in two. The path table says WHICH FILES ARE WORTH LOOKING AT; this says WHAT A
+ * CREDENTIAL LOOKS LIKE once one has been opened. It lives here, beside that table, because the two halves are
+ * one definition of the class and an enforcement point that has a filesystem should not have to invent the
+ * second half for itself (guard/credential-files.ts is the sandbox's fs half; a caller with no filesystem, the
+ * browser or the machine agent, simply never asks and the path stands on its name alone).
+ *
+ * PURE, over the file's own text: no fs, no path logic, nothing to configure. That keeps this package free of
+ * a runtime the editor bundle cannot have, and keeps the rule testable as a table of strings.
+ *
+ * IT ANSWERS THE EASY DIRECTION WELL AND THE HARD ONE CONSERVATIVELY. Everything below is written to say YES
+ * on anything credential-shaped, because a yes costs one card and a no costs the whole rule: the only use of
+ * this answer is to REMOVE a class the path table already added, so a false yes leaves behavior exactly as it
+ * was and a false no silently un-gates a real read.
+ */
+
+/* A KEY THAT NAMES A CREDENTIAL, AND ITS VALUE. Matched as a suffix of whatever the key is spelled as, because
+ * these files say the same thing a dozen ways and only the last word carries the meaning: `NPM_TOKEN`,
+ * `//registry.npmjs.org/:_authToken`, `"accessToken"`, `aws_secret_access_key`, `password =`.
+ *
+ * The three value arms are the three ways a value is quoted across the formats this ever sees: JSON's double
+ * quotes, a shell-ish dotenv's single quotes, and an ini file's bare rest-of-line.
+ *
+ * THE SEPARATOR MAY NOT CROSS A LINE, which is the difference between reading a file and reading a soup: with
+ * `\s*` around it, an empty `GITHUB_TOKEN=` borrows the NEXT line as its value, and a dotenv of nine blank
+ * placeholders reads as eight credentials. Every format here puts a value on its key's own line. */
+const CREDENTIAL_ASSIGNMENT =
+    /(?:auth[_-]?token|access[_-]?token|refresh[_-]?token|api[_-]?key|access[_-]?key|secret[_-]?key|client[_-]?secret|private[_-]?key|passwo?rd|passphrase|credentials?|secret|token|bearer)["']?[ \t]*[:=][ \t]*(?:"([^"\n]*)"|'([^'\n]*)'|([^\s"',;}\n]*))/gi;
+
+/* A VALUE THAT IS NOT A CREDENTIAL EVEN THOUGH ITS KEY SAYS IT IS: the empty one, the one still holding the
+ * template's own words, and the one deferring to an environment variable or a secret reference. Every dotenv
+ * that ships in a repo is made of these, and firing on `GITHUB_TOKEN=${GITHUB_TOKEN}` would put a card in front
+ * of reading a file whose entire content is the absence of a secret. */
+const PLACEHOLDER =
+    /^(?:\$\{?[\w:.-]+\}?|\{\{[^}]*\}\}|<[^>]*>|%\w+%|x{3,}|\*{3,}|\.{3,}|…|(?:your|my|our|the)[-_\s].*|change[-_]?me|replace[-_]?(?:me|this|with)|todo|tbd|fixme|none|null|nil|undefined|true|false|example|placeholder|redacted|dummy|sample|test|fake|secret|password|token|value|here)$/i;
+
+/* Shorter than any credential a service actually issues. It clears the dev-compose defaults an agent reads all
+ * day (`POSTGRES_PASSWORD=dev`, `password=x`), which are not what a card asking about credential material is
+ * for, and it is well under the shortest real token below (a 36-character npm one). */
+const MIN_VALUE = 6;
+
+/* A CREDENTIAL RECOGNISABLE WITHOUT ITS KEY: the issuers whose tokens carry their own prefix, the PEM and PuTTY
+ * headers that ARE the private key file, and a URL that carries a password in its userinfo (which is the whole
+ * content of `.git-credentials`, and the shape a `DATABASE_URL` hides one in).
+ *
+ * These are checked first and independently of any key, because half of these files have no `key = value` in
+ * them at all. */
+const TOKEN_SHAPES = [
+    /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/,
+    /PuTTY-User-Key-File-\d/,
+    // scheme://user:password@host — the password is the point; a Sentry DSN (`https://key@host`) has no colon
+    // before the `@` and is deliberately not this.
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@/i,
+    /\bnpm_[A-Za-z0-9]{30,}/,
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}/,
+    /\bgithub_pat_[A-Za-z0-9_]{50,}/,
+    /\bglpat-[A-Za-z0-9_-]{16,}/,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}/,
+    /\bsk-[A-Za-z0-9_-]{20,}/,
+    /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}/,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\bASIA[0-9A-Z]{16}\b/,
+    /\bAIza[0-9A-Za-z_-]{35}\b/,
+    /\bhf_[A-Za-z0-9]{30,}/,
+    /\bdop_v1_[a-f0-9]{60,}/,
+    // A JWT: three base64url segments, the first two of which decode from `{"` and so always begin `ey`.
+    /\bey[A-Za-z0-9_-]{10,}\.ey[A-Za-z0-9_-]{10,}\./,
+];
+
+/* A VALUE DEFERRED TO SOMEWHERE ELSE, removed before anything is read, because it is not one value but two
+ * things to get wrong. `STRIPE_SECRET={{secret:STRIPE}}` holds no credential — that is the platform's own
+ * convention for a file that must not hold one — and yet it reads as a credential twice over: the outer
+ * assignment has a substantial-looking value, and the reference's own `secret:STRIPE` is a second `key: value`
+ * inside it. Cutting them out first is simpler and steadier than teaching the value patterns to survive them. */
+const DEFERRED_VALUE = /\{\{[^}\n]*\}\}|\$\{[^}\n]*\}/g;
+
+// Does this file's text hold something worth a card? Handed the WHOLE file by its caller, which is why the
+// caller (not this) is the one that decides how much of a large file is worth reading.
+export const holdsCredentialMaterial = (file: string): boolean => {
+    const text = file.replace(DEFERRED_VALUE, "");
+    if (TOKEN_SHAPES.some((pattern) => pattern.test(text))) {
+        return true;
+    }
+    for (const match of text.matchAll(CREDENTIAL_ASSIGNMENT)) {
+        const value = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+        if (value.length >= MIN_VALUE && !PLACEHOLDER.test(value)) {
+            return true;
+        }
+    }
+    return false;
+};

package/src/definition-action.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+/* One "do this by hand" line, the definition surface's honesty unit (definition.ts is the home story; this
+ * lives in its own leaf module because runner-protocol.ts also speaks it, and THAT file is imported by
+ * schemas/agent.ts, which definition.ts imports — the schema living in definition.ts made a cycle that left
+ * schemas half-initialized under module-eval). A subject the UI bolds, a detail written as an instruction. */
+export const DefinitionActionSchema = z.object({ subject: z.string(), detail: z.string() });
+export type DefinitionAction = z.infer<typeof DefinitionActionSchema>;

package/src/definition.ts

@@ -1,9 +1,11 @@
 import { z } from "zod";
-import { CapabilitySchema, SandboxSettingsSchema } from "./schemas.js";
+import { DefinitionActionSchema } from "./definition-action.js";
+import { CapabilitySchema } from "./schemas/capabilities.js";
+import { SandboxSettingsSchema } from "./schemas/settings.js";
 
 /* THE SANDBOX DEFINITION: the declarable SHAPE of a sandbox, split off from its state.
  *
- * A bundle (portability section of schemas.ts) moves everything a sandbox holds; this is the half of it that
+ * A bundle (BundleSchema, schemas/maintenance.ts) moves everything a sandbox holds; this is the half of it that
  * is a REFERENCE to a source of truth rather than bytes only this sandbox has: which repos (as remotes a
  * target can clone), which connections (as shapes a target re-authenticates), which overlay steps (as source
  * a target's owner approves), which secrets (as NAMES a target asks for), which agent settings. Everything
@@ -19,7 +21,7 @@ import { CapabilitySchema, SandboxSettingsSchema } from "./schemas.js";
 // One repository, by reference: the id it lands under in the workspace, where a target clones it from, and
 // (optionally) the branch to check out. A repo with NO remote cannot appear here, the exporter reports it as
 // omitted instead of inventing a source for bytes only the source sandbox holds.
-export const DefinitionRepositorySchema = z.object({
+export const DefinitionRepositorySchema = z.strictObject({
     // Workspace-relative repo id ("intentic", "clients/foo"), the same id the wire {repo} routes use.
     id: z.string().min(1),
     // The clone URL, verbatim from the source repo's own remote.
@@ -29,7 +31,26 @@ export const DefinitionRepositorySchema = z.object({
 });
 export type DefinitionRepository = z.infer<typeof DefinitionRepositorySchema>;
 
-export const DefinitionEnvironmentSchema = z.object({
+/* THE WORKSPACE ITSELF, by reference. `/work` is a git repo of its own (the daemon's `root` scope, git dir on
+ * /history), tracking every workspace file that is not a nested repo, the reference shelf, or daemon-internal
+ * state — which by the versioned-state allowlist means the owner's AUTHORED content: notes, skills, personas,
+ * automations, workflow and loop designs, drafts, workspace extensions. None of that has a source anywhere else,
+ * so before this section a definition could only shrug at it and a bundle was the sole way to move it.
+ *
+ * With a remote it becomes referenceable like any other repo, which is the whole point: `[workspace]` plus
+ * `[[repositories]]` is a sandbox's code AND its way of working, and what remains bundle-only is exactly what
+ * cannot be pushed anywhere — secrets, identity, /history, the built image.
+ *
+ * A workspace with no remote cannot appear here; the exporter says so in `omitted` rather than inventing one. */
+export const DefinitionWorkspaceSchema = z.strictObject({
+    // The clone URL, verbatim from the workspace repo's own remote.
+    remote: z.string().min(1),
+    // The branch to check out; absent means the remote's default.
+    ref: z.string().optional(),
+});
+export type DefinitionWorkspace = z.infer<typeof DefinitionWorkspaceSchema>;
+
+export const DefinitionEnvironmentSchema = z.strictObject({
     // The image the overlay extends, informational: the target composes against ITS OWN base (see
     // composeEnvironment's baseImageOf), this records what the source was on.
     baseImage: z.string().optional(),
@@ -57,16 +78,19 @@ const bareField = (field: z.ZodType): z.ZodType => {
 
 const definitionSettings = (): z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>> => {
     const shape = Object.fromEntries(Object.entries(SandboxSettingsSchema.shape).map(([key, field]) => [key, bareField(field).optional()]));
-    return z.object(shape).prefault({}) as unknown as z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>>;
+    return z.strictObject(shape).prefault({}) as unknown as z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>>;
 };
 
-export const SandboxDefinitionSchema = z.object({
+export const SandboxDefinitionSchema = z.strictObject({
     // Bumped when the layout changes in a way an older daemon would misread. Refused rather than guessed at,
     // the bundle manifest's own rule.
     schemaVersion: z.literal(1),
     // What the source sandbox was called, for the reader; never used to authorize anything.
     name: z.string().optional(),
     environment: DefinitionEnvironmentSchema.prefault({}),
+    // The workspace repo itself, when it has a remote to be named by. Absent is the ordinary state of a
+    // workspace nobody has published, not an error.
+    workspace: DefinitionWorkspaceSchema.optional(),
     repositories: z.array(DefinitionRepositorySchema).prefault([]),
     /* Each connection IN FULL (id, kind, config), not merely named: the manifest they come from carries the
      * SHAPE of a connection and never its credential (workspace-state.ts argues the split on the
@@ -82,9 +106,9 @@ export const SandboxDefinitionSchema = z.object({
 export type SandboxDefinition = z.infer<typeof SandboxDefinitionSchema>;
 
 // One "do this by hand" line, the same honesty unit ImportReportSchema carries: a subject the UI bolds and a
-// detail written as an instruction to the owner.
-export const DefinitionActionSchema = z.object({ subject: z.string(), detail: z.string() });
-export type DefinitionAction = z.infer<typeof DefinitionActionSchema>;
+// detail written as an instruction to the owner. Defined in its own leaf module (definition-action.ts says
+// why) and re-exported here, where every consumer of the definition surface finds it.
+export { DefinitionActionSchema, type DefinitionAction } from "./definition-action.js";
 
 // What GET /definition answers: the emitted TOML, plus what the derivation could not express (a repo with no
 // remote), listed rather than silent, the export's own `excluded` discipline.
@@ -99,7 +123,7 @@ export type DefinitionExport = z.infer<typeof DefinitionExportSchema>;
 // same items the owner reviewed.
 export const DefinitionItemSchema = z.object({
     id: z.string(),
-    kind: z.enum(["repo", "capability", "environment", "settings"]),
+    kind: z.enum(["workspace", "repo", "capability", "environment", "settings"]),
     label: z.string(),
     detail: z.string().optional(),
     /* False when the target already holds this piece (the repo's directory exists, a capability with that id
@@ -144,6 +168,46 @@ export const DefinitionDiffSchema = z.object({
 });
 export type DefinitionDiff = z.infer<typeof DefinitionDiffSchema>;
 
+/* ---- publishing the workspace repo, the one step a definition cannot take for itself ----
+ *
+ * `[workspace]` names a remote; nothing can name one that does not exist. So the owner-facing half of the
+ * feature is this: create a PRIVATE repo on a connected git host and push /work to it, or adopt a URL the
+ * owner made themselves. Deliberately its own route rather than a side effect of the export, publishing a
+ * workspace is an outward act with its own confirmation, and deriving a document must stay read-only.
+ */
+export const WorkspacePublishSchema = z.object({
+    /* An existing repo's clone URL. Given, nothing is created: the remote is wired up and pushed to, which is
+     * the path for an owner who made the repo themselves or is moving hosts. */
+    remote: z.string().min(1).optional(),
+    // The repo to create when `remote` is absent. Owner-side default is the sandbox's own name.
+    name: z.string().min(1).optional(),
+    /* The account or organization to create it under; absent means the authenticated user. Ignored when
+     * `remote` is given. */
+    owner: z.string().min(1).optional(),
+});
+export type WorkspacePublish = z.infer<typeof WorkspacePublishSchema>;
+
+// Where the workspace now lives, and what a definition will name. `created` distinguishes "made you a repo"
+// from "wired up the one you gave me", which is the difference the card reports back.
+export const WorkspacePublishResultSchema = z.object({
+    remote: z.string(),
+    branch: z.string(),
+    created: z.boolean(),
+});
+export type WorkspacePublishResult = z.infer<typeof WorkspacePublishResultSchema>;
+
+// What the card renders before anything is published: whether /work has a remote, and which connected git
+// hosts could make one. Read-only, so the button can say "Publish to github.com" rather than opening a form
+// into a void.
+export const WorkspaceRemoteSchema = z.object({
+    remote: z.string().optional(),
+    branch: z.string().optional(),
+    // Hostnames of connected github/gitlab accounts, in the order they would be tried. Empty means the owner
+    // must connect one (or paste a URL).
+    hosts: z.array(z.string()),
+});
+export type WorkspaceRemote = z.infer<typeof WorkspaceRemoteSchema>;
+
 /* ---- the bundle manifest, restated on the definition ----
  *
  * A bundle is DEFINITION + STATE: its manifest embeds the same definition `GET /definition` emits, and the

package/src/events.ts

@@ -1,18 +1,12 @@
 import { z } from "zod";
-import {
-    AgentProviderSchema,
-    AgentReplySchema,
-    AgentSummarySchema,
-    FastModeStateSchema,
-    LandConflictSchema,
-    MemberRoleSchema,
-    PermissionModeSchema,
-    RateLimitInfoSchema,
-    ShareDetailSchema,
-    SubagentKindSchema,
-    SubagentStatusSchema,
-    UsageWindowSchema,
-} from "./schemas.js";
+import { AgentProviderSchema, PermissionModeSchema } from "./schemas/agent.js";
+import { AgentSummarySchema, LandConflictSchema } from "./schemas/agents.js";
+import { RateLimitInfoSchema } from "./schemas/claude-gate.js";
+import { FastModeStateSchema } from "./schemas/fast-mode.js";
+import { AgentReplySchema, UsageWindowSchema } from "./schemas/plan-limits.js";
+import { ShareDetailSchema } from "./schemas/share.js";
+import { MemberRoleSchema } from "./schemas/shared.js";
+import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "./schemas/terminal.js";
 
 // The wire shapes streamed from the daemon's event-iterator procedures. This is their canonical home: the
 // daemon yields them and the browser client consumes them from the same schema, so the two can't drift (they
@@ -35,6 +29,29 @@ export const AskQuestionSchema = z.object({
 });
 export type AskQuestion = z.infer<typeof AskQuestionSchema>;
 
+/* THE PROGRAM A COMMAND CARD IS HOLDING, as the thing it is rather than as prose about it.
+ *
+ * It used to ride in `description`, the field every other permission ask fills with a sentence, which left the
+ * card with no way to know it was holding four hundred characters of shell: it rendered them as a paragraph,
+ * wrapped mid-flag, and the fragment that caused the hold was somewhere in the middle of it.
+ *
+ * `spans` is the gate's own evidence, computed by the classifier at the moment the rule fired (contract's
+ * command-classes.ts, matchCommand) and carried rather than re-derived: a browser that re-ran the patterns
+ * would be a second classifier, and the day the two disagreed the card would be marking a fragment that is not
+ * the one anybody was held for. Offsets are into `text` AFTER truncation, so they are always paintable.
+ *
+ * `language` is a Shiki grammar id, and the two are the two execution backends the gate reads (command-gate's
+ * EXECUTION_SOURCES): a shell line and a script. */
+export const ProgramAskSchema = z.object({
+    text: z.string().describe("What would run."),
+    language: z.enum(["bash", "javascript"]).describe("Which of the two backends it is written for, named as the grammar that colours it."),
+    truncated: z.boolean().describe("Whether this is the head of a longer program, so the card can say so instead of ending mid-word."),
+    spans: z
+        .array(z.object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() }))
+        .describe("Which fragments of the text put it in the class that held it. Offsets into text, in order, never overlapping."),
+});
+export type ProgramAsk = z.infer<typeof ProgramAskSchema>;
+
 // One per-tool permission prompt (the SDK's canUseTool callback, surfaced as a card). The daemon passes the
 // bridge's own rendered strings through rather than re-deriving them, so the prompt reads exactly as Claude
 // Code words it. `alwaysLabel` is present only when the SDK offered rules to persist, without it the card
@@ -56,6 +73,15 @@ export const PermissionAskSchema = z.object({
         .describe(
             "The wording for an always-allow answer. Present only when there is something an always could actually remember; without it the only answers are once and no.",
         ),
+    program: ProgramAskSchema.optional().describe(
+        "The program this card is holding, when the card is about one. Present on a command gate's card and absent on every other permission ask.",
+    ),
+    explain: z
+        .string()
+        .optional()
+        .describe(
+            "One plain sentence saying what the program does and why the agent wants it. Written by the quick model, never by the agent being gated, and only when the owner switched the setting on.",
+        ),
 });
 export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
 
@@ -360,8 +386,9 @@ export const RestoredMessageSchema = z.object({
     thinking: z.string().optional().describe("What the agent was reasoning about."),
     tools: z.array(RestoredToolCallSchema).optional().describe("The tool calls this part of the turn made."),
     /* What the daemon added to this turn's message (user rows only), the same notes the live `preamble` frame
-     * carries, recovered from the stored prompt when the transcript is read back. The reader that strips them out
-     * of the user's words is the one that hands them over here instead of dropping them on the floor.
+     * carries. A daemon-recorded turn takes them straight off that frame in its own log, typed end to end
+     * (sessions/turn-transcript.ts); only a conversation adopted from a provider's session store recovers them
+     * by parsing the composed prompt kept there, the one store the daemon never wrote typed.
      *
      * On the message rather than as a row of its own, and that matters twice: they ARE part of what was
      * sent, and a record row per turn preamble would break the one-row-per-bubble correspondence a branch counts
@@ -489,8 +516,9 @@ export type ParkedCard = z.infer<typeof ParkedCardSchema>;
 // ~40 SDKMessage types down to this union: high-value block types get a dedicated frame
 // (delta/thinking/tool_call/tool_call_update/todos/usage/rate_limit_info/account_usage/context_usage/init/compact); any SDK message
 // without a UI mapping is dropped. `plan`/`question`/`permission` pause the turn until the user answers on the
-// `POST /agent/reply` side channel, and `resolved` releases the one it names; `mode` reports the live
-// permission posture as the agent changes it.
+// `POST /agent/reply` side channel, and `resolved` releases the one it names; `permission_note` adds a sentence
+// to a permission card already on screen without settling it; `mode` reports the live permission posture as the
+// agent changes it.
 // `parentToolUseId` tags frames produced inside a subagent (Task tool); `subagent`/`subagent_update` report the
 // subagent itself, keyed by the same tool_use id those tagged frames carry.
 export const AgentEventSchema = z.discriminatedUnion("kind", [
@@ -554,12 +582,14 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * way to find out what those instructions said. This frame is the fix: the note text verbatim, one entry per
      * note, rendered collapsed so it costs a click rather than a scroll.
      *
-     * `title` is the note's own opening header, which is what the stripper already anchors on, so the two
-     * cannot drift, and a note nobody thought to title cannot reach the wire unlabelled.
+     * Emitted from the TYPED notes the wire prompt is serialized from at the same point (turn-preamble.ts,
+     * composeWirePrompt), so the disclosure and what the model receives cannot drift: a note is in both or in
+     * neither, and a note nobody thought to title cannot reach the wire unlabelled.
      *
      * ONE MOMENT, always: the notes went in front of the user's own message before the turn started, so they hang
-     * off that message and are stored on it, which is how a reopened tab still has them. Nothing is injected into
-     * a RUNNING turn, the rebase taken while a card sat waiting was the only thing that ever was, and it no
+     * off that message and are stored on it, the transcript fold reads this very frame out of the turn's own
+     * frame log (sessions/turn-transcript.ts), which is how a reopened tab still has them. Nothing is injected
+     * into a RUNNING turn, the rebase taken while a card sat waiting was the only thing that ever was, and it no
      * longer says anything to the model at all (agent/turn-preamble.ts). */
     z.object({ kind: z.literal("preamble"), notes: z.array(TurnNoteSchema) }),
     // The SDK's init handshake; carries the model it actually resolved for the turn.
@@ -666,6 +696,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         lastTool: z.string().optional(),
         summary: z.string().optional(),
         error: z.string().optional(),
+        // Whether anything checked the work the report describes (SubagentVerificationSchema). Rides the frame
+        // that ENDS the child, beside the report itself, so the card carries both at once.
+        verification: SubagentVerificationSchema.optional(),
     }),
     z.object({ kind: z.literal("todos"), items: z.array(TodoItemSchema) }),
     // The provider's own slash commands (ACP available_commands_update), replaced whole each time, the
@@ -875,6 +908,19 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // already moved on. It rides verbatim, exactly as the client POSTed it; absent, nobody answered (the turn
     // was stopped, or died under the card), which is not a decision and must not replay as one.
     z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),
+    /* A LATE SENTENCE FOR A CARD ALREADY ON SCREEN: the quick model's plain-language reading of a held command,
+     * landing on the permission card named by `requestId` (see PermissionAsk.explain).
+     *
+     * A frame of its own rather than a field on the card, because the card MUST NOT WAIT FOR IT. This is a
+     * safety prompt and the turn is parked on it; a quick-model rung can take tens of seconds before the chain
+     * steps down (agent/quick-model.ts measured one at 58), and holding the card back for that reads exactly
+     * like the agent freezing, which is the failure the explanation was meant to prevent rather than cause. So
+     * the card goes out complete and unexplained, and this arrives if and when it does. Same shape and the same
+     * reason as `service_event`, which streams a running service's status onto an offer already rendered.
+     *
+     * Never arrives at all when the setting is off, when nothing is connected to answer, or when the user
+     * settles the card first, and none of those change what the card says. */
+    z.object({ kind: z.literal("permission_note"), requestId: z.string(), explain: z.string() }),
     // The turn's permission mode, whenever it changes, the user's pick at turn start, then every move the
     // AGENT makes on its own (EnterPlanMode on a request that needs thinking through, ExitPlanMode once the
     // user approves). The composer's mode selector follows this, so the UI never lies about the live posture.
@@ -955,6 +1001,22 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                  * context-window-too-small does: they never reached a provider, and losing them to a
                  * capacity fact the user did not cause would be ours to answer for. */
                 "sandbox-memory-low",
+                /* THE LOOP RAN OUT OF ITERATIONS, not out of work: the runtime hit its own turn ceiling and
+                 * stopped. Nothing failed, nothing is disconnected and nothing is spent, which is exactly why
+                 * it needs a code of its own rather than a sentence: it is the one ending that LOOKS like a
+                 * finished turn from the outside, and a ledger that filed it as an ordinary error told a
+                 * reader nothing they could act on.
+                 *
+                 * The recovery is the user's, not the daemon's: whatever the turn was doing is half done, and
+                 * re-running it blind would either redo the finished half or resume work nobody looked at. */
+                "turn-cap",
+                /* THE HARNESS ENDED THE TURN WITHOUT SUCCEEDING and did not say why in terms anything here
+                 * models: an internal execution error, or a result subtype a later vendor build invented. The
+                 * sentence carries the subtype verbatim, because that word is the only thing separating two of
+                 * these, and a code that meant "one of several unrelated things" would be worse than none. It
+                 * is a real classification all the same: it says the failure came from the LOOP rather than
+                 * from the provider, the credential or the request, which rules out every recovery next door. */
+                "harness-incomplete",
             ])
             .optional(),
         // rate_limit only: when the exhausted window reopens (epoch seconds, from the stream's own

package/src/fast-tier.ts

@@ -1,6 +1,6 @@
 import { compareCheapestFirst, isCheaperRung } from "./model-order.js";
 import { parsePinned } from "./quick-model.js";
-import type { AgentProvider } from "./schemas.js";
+import type { AgentProvider } from "./schemas/agent.js";
 
 /* WHICH MODEL A DOWNGRADED TURN ACTUALLY RUNS ON, the second half of automatic tier selection.
  * prompt-complexity.ts decides a turn COULD be cheaper; this decides whether there is anything cheaper to put

package/src/history-state.ts

@@ -37,6 +37,18 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // The fleet: every conversation card, its branch, its session ids, its standing.
     { path: "agents.json", portability: "carry" },
     { path: "turns/", portability: "carry" },
+    /* THE ARMED CONDITION WATCHES, one file per watch, put back at boot (agent/watchers.ts `restoreWatchers`).
+     *
+     * Carried for the reason loops.json is: an arrangement the agent entered into on the user's behalf and
+     * that is still outstanding travels with the conversation that is waiting on it, or a restored sandbox
+     * shows a card parked on a condition nothing will ever check. It can be carried safely because the journal
+     * holds no credential, only the NAMES of the environment its check ran with (agent/watch-journal.ts); the
+     * values are re-derived on the target from whatever capabilities it actually has, so a watch landing
+     * somewhere without them fails its check honestly and ends in a wake that says so, rather than arriving
+     * with a working copy of a token the bundle was never supposed to carry. A watch whose isolated checkout
+     * did not travel (those are `derived`) is dropped by the restore rather than re-armed against a tree that
+     * is not there. */
+    { path: "watches/", portability: "carry" },
     { path: "transcripts/", portability: "carry" },
     // What each message can be put back to, a workspace checkpoint, or an isolated conversation's own commits.
     // Carried WITH the transcripts and the scopes above, because it is the join between them: without it a
@@ -128,6 +140,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
     { path: "sync-pair-consumed.json", portability: "identity" },
     { path: "host-enrollments.json", portability: "identity" },
+    /* A connected BROWSER's enrollment (webext/webext-store.ts). Identity for the hosts file's reason and one
+     * more of its own: the token admits a socket into somebody's signed-in browser, and that browser was paired
+     * with THIS sandbox — carried into another one it would either be dead weight or, worse, a second sandbox
+     * holding a live key to a browser its owner never connected it to. Re-pairing is a code and one click. */
+    { path: "webext-enrollments.json", portability: "identity", note: "Pair your browser again from its card: the extension is still installed." },
     // The burn list for setup-time computer pairings. Identity, like sync's beside it, and for a sharper reason:
     // carrying it into another sandbox would mark that sandbox's own fresh pairing as already spent.
     { path: "host-pair-consumed.json", portability: "identity" },

package/src/host-protocol.ts

@@ -24,7 +24,7 @@ export const HostHelloSchema = z.object({
      * onto one-shot tickets, auth/ws-tickets.ts). A frame is body, not URL, so it is logged nowhere. Until this
      * arrives the socket is anonymous and short-lived: the daemon closes it in seconds if it never does. */
     token: z.string(),
-    // The @intentic/host build the machine is running, surfaced per machine so an old binary is visible rather
+    // The @intentic/machine build the machine is running, surfaced per machine so an old binary is visible rather
     // than mysteriously missing a tool. What the machine IS (`describe`) is not here: it is pulled over the
     // typed link a moment later, so there is one definition of those facts rather than two.
     version: z.string(),

package/src/hostnames.test.ts

@@ -25,8 +25,8 @@ test("preview and port hostnames round-trip through their Host-header parsers",
 });
 
 test("the two schemes never bleed into each other, and stray/wrong-id hosts parse to nothing", () => {
-    expect(portSlotFromHost("preview-app-" + ID + ".example.com", ID)).toBeUndefined();
-    expect(panelFromHost("port-a-" + ID + ".example.com", ID)).toBeUndefined();
+    expect(portSlotFromHost(`preview-app-${ID}.example.com`, ID)).toBeUndefined();
+    expect(panelFromHost(`port-a-${ID}.example.com`, ID)).toBeUndefined();
     expect(panelFromHost("app.example.com", ID)).toBeUndefined();
     expect(panelFromHost(`preview-app-000000000000.example.com`, ID)).toBeUndefined();
     expect(portSlotFromHost(`port-a-000000000000.example.com`, ID)).toBeUndefined();