@intentic/sandbox-contract 1.243.0 → 1.245.0

package/src/batch-runs.ts

@@ -0,0 +1,181 @@
+import { STATE_DIR } from "@intentic/constants";
+
+/* ONE BATCH RUN ENGINE, for every surface that fans an ISOLATED AGENT TURN out over a set of items and reads
+ * the answers back off disk.
+ *
+ * Three packs had written this separately — acceptance (a run per story), maintenance (a run per chore, per
+ * repository) and documentation (a run per package) — and the three copies agreed on every decision that
+ * matters and drifted on every detail that does not: `SCAN_RUNS` was 10 in one and 30 in another, one minted
+ * run ids with a per-process counter and one without (the one without could collide, and did, the moment a
+ * surface started several runs inside a millisecond), and each spelled the reporting clause its own way, so an
+ * agent's instructions for where to leave its answer depended on which screen started it.
+ *
+ * WHY THE CORE OWNS IT rather than one of them exporting it. A substrate is what other packs fire into, and a
+ * pack can be switched off: a run engine that stops existing because somebody hid a screen is not an engine.
+ * The reverse — a substrate living in one pack — is what produced the three copies, because reaching into
+ * `acceptance` for a run id is a dependency no other pack wants and reinventing it is one afternoon.
+ * `_extensions/README.md` states the rule; this is the second of the four substrates named there.
+ *
+ * WHAT A RUN IS, and the part that is load-bearing rather than incidental:
+ *
+ *  • IT IS BACKED BY FILES, never by a store a pack owns. `run.json` is written before the first turn starts
+ *    and each agent writes its own result beside it. So a run survives archiving the fleet agents, discarding
+ *    them, closing the browser and rebuilding the image, and a browser that was shut when a turn finished picks
+ *    the answer up the next time it opens.
+ *  • ITS CONVERSATION IDS ARE DERIVED, so joining a run to the fleet is a filter over `GET /agents` rather than
+ *    bookkeeping that can drift. This is why none of these surfaces owns session machinery: the worktree, the
+ *    live status, the cost, the transcript and the `/agents/<id>` page all already exist.
+ *  • IT LIVES UNDER `.intentic`, which is outside every repo (the root repo excludes it) and is bound back in
+ *    SHARED for isolated turns, so an agent writing its result from inside its own worktree writes into the
+ *    same tree the browser reads: nothing to land, no git noise.
+ *
+ * The manifest and result SHAPES stay with the packs. A chore's outcome vocabulary and a story's criteria have
+ * nothing to say to each other, and a substrate that tried to own both would be a union that grows a field per
+ * screen. What is here is what all three do identically: where the files go, how the ids are made, how a
+ * half-written file is survived, and what the agent is told about where to leave its answer. */
+
+/* WHERE ONE KIND OF RUN KEEPS ITS DIRECTORIES. Taken as the tail rather than composed from a pack id, because
+ * the three existing layouts are not uniform and rewriting them would orphan every run already on disk:
+ * acceptance keeps runs under `records/artifacts/acceptance`, maintenance under `records/chores/runs`. A path
+ * is a fact about a tree that exists, not a naming opportunity. */
+export interface BatchRunKind {
+    /* The directory holding this kind's run directories, workspace-relative, under the state dir. */
+    readonly runsDir: string;
+    /* The conversation-id prefix, two or three characters. Every conversation this kind starts carries it, so a
+     * prefix filter over `GET /agents` is the join key and not merely a naming convention. */
+    readonly prefix: string;
+    /* How many runs deep anything that READS RESULTS goes. A bound on the walk, not on what can be run: only
+     * recent runs carry news, and a workspace with hundreds of run directories must not spend a request per
+     * item to render a list or light a badge. One number per kind, shared by every reader of that kind, so a
+     * badge's idea of "recent" and a list's can never disagree. */
+    readonly scanRuns: number;
+}
+
+/* The conversation id's own regex is `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$` — it lands in branch names and in
+ * paths — so this is a hard ceiling rather than a style choice. */
+const CONVERSATION_ID_MAX = 64;
+
+/* `r` + a base-36 millisecond, zero-padded, + a per-process counter: sortable, ~10 characters, and readable
+ * enough to match a directory to a moment. The clock is taken from the caller so this stays pure and testable.
+ *
+ * THE PADDING IS WHAT MAKES "SORTABLE" TRUE. Both copies this replaces claimed it and neither had it: a base-36
+ * number is shorter when it is smaller, so a plain `toString(36)` sorts `r1a` after `rzz` the moment two ids
+ * straddle a digit boundary. Today's milliseconds are all eight digits so nothing has gone wrong yet, and
+ * nothing will until 2059 — which is exactly the kind of latent boundary that is cheap to remove now and
+ * expensive to find later. Padded to the same width, the ids on disk are the length they already were.
+ *
+ * THE COUNTER IS NOT OPTIONAL, the other drift worth naming. A surface that fans out over items can get away
+ * without one, because its ids differ by item; a surface where one run IS one item cannot, and "run this chore
+ * in every repository" starts several inside the same millisecond. Both kinds share this function, so the
+ * safe answer is the only answer, and it costs the id one character. */
+const TIME_DIGITS = 8;
+let sequence = 0;
+export const batchRunIdAt = (epochMs: number): string => `r${epochMs.toString(36).padStart(TIME_DIGITS, `0`)}${(sequence++).toString(36)}`;
+
+/* The fleet conversation id for one item of one run, or for a run that is a single item (omit `item`).
+ *
+ * THE RUN ID SURVIVES TRUNCATION and the item is what gets cut, because the run id is how a card is attributed
+ * back to its run: lose that and a finished turn belongs to nothing. Callers that fan out must already have
+ * made their item slugs unique by suffixing, and the suffix sits at the end — exactly where the cut lands — so
+ * uniqueness holds only while the cut leaves it. In practice nothing is close: slugs are capped at 40 and run
+ * ids are ~10, well inside 64. A trailing separator left by the cut is trimmed, because `xt-r5k2-` is a
+ * conversation id the regex above would refuse. */
+export const batchConversationId = (kind: BatchRunKind, runId: string, item?: string): string =>
+    `${kind.prefix}-${runId}${item === undefined ? `` : `-${item}`}`.slice(0, CONVERSATION_ID_MAX).replace(/[-_]+$/u, ``);
+
+// Every conversation one kind starts, for the prefix filter over `GET /agents` that joins a run to the fleet.
+export const batchRunPrefix = (kind: BatchRunKind): string => `${kind.prefix}-`;
+
+// The directory holding one kind's run directories, workspace-relative. What a listing is asked for.
+export const batchRunsDir = (kind: BatchRunKind): string => `${STATE_DIR}/${kind.runsDir}`;
+export const batchRunDir = (kind: BatchRunKind, runId: string): string => `${batchRunsDir(kind)}/${runId}`;
+export const batchRunManifestPath = (kind: BatchRunKind, runId: string): string => `${batchRunDir(kind, runId)}/run.json`;
+
+/* Where one item of a run leaves its files. A run whose items are the run itself (`item` omitted) writes
+ * straight into the run directory, which is what maintenance already does and what keeps its `result.json`
+ * beside its `run.json` rather than one pointless level down. */
+export const batchItemDir = (kind: BatchRunKind, runId: string, item?: string): string =>
+    item === undefined ? batchRunDir(kind, runId) : `${batchRunDir(kind, runId)}/${item}`;
+export const batchResultPath = (kind: BatchRunKind, runId: string, item?: string): string => `${batchItemDir(kind, runId, item)}/result.json`;
+
+/* A FILE THAT IS HALF-WRITTEN, or written by a build whose shape has since changed, IS SKIPPED rather than
+ * thrown on. One bad directory must not blank a whole history, and a run directory is written by an agent
+ * mid-turn, so reading one that is not finished being written is ordinary rather than exceptional.
+ *
+ * The caller supplies the shape check, because the shape is the pack's. This owns only the two failure modes
+ * every reader shares: text that is not JSON, and JSON that is not an object. */
+export const parseBatchFile = <T>(text: string, shape: (value: Record<string, unknown>) => T | undefined): T | undefined => {
+    try {
+        const parsed: unknown = JSON.parse(text);
+        return typeof parsed !== `object` || parsed === null ? undefined : shape(parsed as Record<string, unknown>);
+    } catch {
+        return undefined;
+    }
+};
+
+/* WHAT THE AGENT IS TOLD ABOUT WHERE TO LEAVE ITS ANSWER, appended to whatever prompt the pack composed.
+ *
+ * WHY THE AGENT WRITES A FILE AND NOT A ROUTE. A ledger is a daemon route, and reaching it from a turn would
+ * mean handing the agent a token and a client it needs for nothing else. Writing one small JSON file is
+ * something every agent can already do, and the surface promotes finished runs when it next sees them. The
+ * promotion is idempotent and re-runs on every poll, so nothing is lost by not being watched.
+ *
+ * `outcomes` is the pack's vocabulary and is spelled out in full, because a closed set is what lets a surface
+ * debounce without hiding anything: an agent that verified some findings and concluded they were false
+ * positives has to be able to SAY so, or the next poll starts the same turn again forever. Pass the
+ * explanations with the words — a model that reads an outcome as an admission of having done nothing useful
+ * will avoid it and report something else, and the surface never goes quiet.
+ *
+ * The closing line is not decoration. A turn that concludes there was nothing to do and writes no file is
+ * indistinguishable from a turn that died, and the surface has to show the second as an unknown. */
+export const batchReportingClause = (params: {
+    readonly path: string;
+    readonly fields: string;
+    readonly outcomes?: string | undefined;
+}): string =>
+    [
+        `When you are finished, write your conclusion to ${params.path} as JSON:`,
+        params.fields,
+        ...(params.outcomes === undefined ? [] : [params.outcomes]),
+        `Write that file even if you conclude there was nothing to do.`,
+    ].join(`\n\n`);
+
+/* THE BODY OF THE `POST /agent` THAT STARTS ONE ITEM, so the flag combination that makes a run a run is decided
+ * once. `isolated: true` with a conversationId is the shape (and the only shape) that registers a fleet entry,
+ * which is why none of these packs owns session machinery; `unattended: true` is what the turn IS — started by
+ * a row rather than by a person at a composer — and it is what makes the daemon answer with the owner's
+ * `agentRunModels` unless the caller pinned a model on the row's caret, in which case the pick rides along and
+ * the daemon's fill step leaves it alone.
+ *
+ * PERMISSIONS AND ISOLATION ARE THE CALLER'S, deliberately. They are the two decisions that differ by kind and
+ * both are about safety rather than plumbing: an acceptance test that parks on a permission card is a test that
+ * never finishes, so that surface trades the prompt away; a maintenance chore is different in kind — nobody is
+ * waiting on it, it may take until tomorrow, and a sweep that can answer its own permission prompts is exactly
+ * the thing an owner would want to have been asked about. A default here would decide that for both. */
+export interface BatchTurnPick {
+    readonly provider: string;
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+}
+
+export const batchTurnBody = (params: {
+    readonly prompt: string;
+    readonly title: string;
+    readonly conversationId: string;
+    readonly pick?: BatchTurnPick | undefined;
+    readonly extra?: Readonly<Record<string, unknown>> | undefined;
+}): Record<string, unknown> => ({
+    prompt: params.prompt,
+    title: params.title.slice(0, 80),
+    conversationId: params.conversationId,
+    isolated: true,
+    unattended: true,
+    ...(params.pick === undefined
+        ? {}
+        : {
+              agent: params.pick.provider,
+              ...(params.pick.model === undefined ? {} : { model: params.pick.model }),
+              ...(params.pick.effort === undefined ? {} : { effort: params.pick.effort }),
+          }),
+    ...params.extra,
+});

package/src/card-status.ts

@@ -13,7 +13,7 @@ type Cards = { -readonly [K in CardField]?: TranscriptRow[K] };
 
 export const settledCards = (cards: TranscriptCards, reply: AgentReply | undefined): TranscriptCards => {
     const out: Cards = {};
-    const { plan, question, permission, browserHelp, terminalHelp, serviceOffer, capabilityOffer, paymentOffer } = cards;
+    const { plan, question, permission, browserHelp, terminalHelp, serviceOffer, capabilityOffer, paymentOffer, credentialOffer } = cards;
     if (plan !== undefined) {
         out.plan = { ...plan, status: reply?.kind !== "plan" ? "cancelled" : reply.approve ? "approved" : "rejected" };
     }
@@ -59,6 +59,17 @@ export const settledCards = (cards: TranscriptCards, reply: AgentReply | undefin
     if (paymentOffer !== undefined) {
         out.paymentOffer = { ...paymentOffer, status: reply?.kind !== "payment_offer" ? "cancelled" : reply.approve ? "approved" : "skipped" };
     }
+    /* A yes settles the decision; WHO decided is the credential_receipt frame's to say, because only the
+     * daemon knows it — the reply carries no name, the identity was verified off the request that delivered
+     * it. A reply that reaches this derivation at all is one the daemon already accepted from an approver: a
+     * click from anybody else is refused before the card is settled, so it never gets here and the card stays
+     * pending. */
+    if (credentialOffer !== undefined) {
+        out.credentialOffer = {
+            ...credentialOffer,
+            status: reply?.kind !== "credential_offer" ? "cancelled" : reply.approve ? "approved" : "skipped",
+        };
+    }
     return out;
 };
 
@@ -77,6 +88,7 @@ export const cancelledCards = (cards: TranscriptCards): TranscriptCards => {
         "serviceOffer",
         "capabilityOffer",
         "paymentOffer",
+        "credentialOffer",
     ] as const) {
         const card = cards[field];
         if (card === undefined) {

package/src/chores/stack.test.ts

@@ -72,6 +72,42 @@ describe(`the patterns are safe to interpolate`, () => {
     });
 });
 
+/* THE PATTERNS AGAINST LINES, which is the only place a false finding can be caught before a reader is told to go
+ * and fix one. The invariants above ask whether a rule is well formed; these ask whether it is right, and the cases
+ * are lines from real files rather than invented ones.
+ *
+ * Only the rule whose names are ordinary words is covered here. `@NgModule(` and `ReactDOM.render(` cannot be
+ * mistaken for anything, and a test that restated them would be asserting that a literal is itself. */
+describe(`the Vue 2 teardown hooks`, () => {
+    const hits = (line: string): boolean => new RegExp(idiomRule(`vue-2-lifecycle`)?.pattern ?? `(?:)`).test(line);
+
+    test(`a hook is found however the component writes it`, () => {
+        expect(hits(`    destroyed() {`)).toBe(true);
+        expect(hits(`    beforeDestroy() {`)).toBe(true);
+        expect(hits(`    destroyed: function () {`)).toBe(true);
+        expect(hits(`    destroyed: async () => {`)).toBe(true);
+        // The name is Vue's alone, so it is the finding whatever it is assigned.
+        expect(hits(`    beforeDestroy: this.teardown,`)).toBe(true);
+    });
+
+    /* The finding this rule really produced, against a module that deletes idle machines. Every line below is a
+     * fact about a tally, and a chore that reads them as a lifecycle hook sends its reader at a file with no
+     * component in it. */
+    test(`a field named after the word is not a hook`, () => {
+        expect(hits(`): Promise<{ warned: number; destroyed: number; dropped: number }> => {`)).toBe(false);
+        expect(hits(`    const tally = { warned: 0, destroyed: 0, dropped: 0 };`)).toBe(false);
+        expect(hits(`    return \`destroyed\`;`)).toBe(false);
+        expect(hits(`    if (machine.destroyed) {`)).toBe(false);
+        expect(hits(`type IdleVerdict = "kept" | "warned" | "destroyed" | "dropped";`)).toBe(false);
+    });
+
+    // The other half of the same guard: the pattern above is only ever asked about a component file, so a backend
+    // module is not eligible for this finding whatever it happens to name a variable.
+    test(`the sweep asks the question of components only`, () => {
+        expect(idiomRule(`vue-2-lifecycle`)?.globs).toEqual([`*.vue`]);
+    });
+});
+
 describe(`recognising the stack`, () => {
     test(`a framework is recognised from any manifest's dependency names`, () => {
         expect(frameworksOf([`vue`, `vite`]).map((framework) => framework.id)).toEqual([`vue`]);

package/src/chores/stack.ts

@@ -168,8 +168,19 @@ export const IDIOM_RULES: readonly IdiomRule[] = [
         framework: `vue`,
         label: `the Vue 2 teardown hooks`,
         replacement: `beforeUnmount and unmounted`,
-        pattern: `\\b(beforeDestroy|destroyed)\\s*[(:]`,
-        globs: [`*.vue`, `*.ts`, `*.js`],
+        /* TWO NAMES, AND ONLY ONE OF THEM IS VUE'S. `beforeDestroy` is a word nobody writes by accident, so its
+         * presence is the finding. `destroyed` is ordinary English, and asking only for a `(` or a `:` after it
+         * matched `{ warned: number; destroyed: number }` in a backend module that reaps idle machines: the chore
+         * told its reader to migrate a Node file to beforeUnmount, which is the kind of row that teaches people to
+         * stop reading the rest. So the ambiguous half has to be a FUNCTION in an options object, the only shape a
+         * hook is ever written in, and a field or a type named after the word is no longer evidence of anything.
+         *
+         * The globs are the second half of the same guard, and `*.ts` was the reason a backend file was eligible at
+         * all. A teardown hook is a component's, so this reads components. What that gives up is a Vue 2 mixin
+         * living in a plain `.js` file, and it is the right trade: `vue-global-api` still catches such a file when
+         * it constructs anything, and an idiom found nowhere costs less than one found in the wrong repository. */
+        pattern: `\\bbeforeDestroy\\s*[(:]|\\bdestroyed\\s*(\\(\\s*\\)\\s*\\{|:\\s*(async\\s+)?(function|\\(\\s*\\)\\s*=>))`,
+        globs: [`*.vue`],
     },
     {
         id: `vue-global-api`,

package/src/command-classes.ts

@@ -94,8 +94,13 @@ const spansOf = (patterns: readonly RegExp[], command: string): CommandSpan[] =>
 /* Sorted, with overlaps folded together. Two patterns firing on one fragment is ordinary here (a script's
  * recursive delete matches both the with-a-literal-path pattern and the any-path one), and handing a renderer
  * overlapping ranges makes it either double-paint or reinvent this. Adjacency is NOT merged: touching spans
- * from genuinely different fragments read correctly as two marks. */
-const normalize = (spans: readonly CommandSpan[]): CommandSpan[] => {
+ * from genuinely different fragments read correctly as two marks.
+ *
+ * EXPORTED because a caller that marks SEVERAL classes at once needs it too, and the overlap it has to fold is
+ * across classes rather than within one: `rm -rf /work` is both files.destructive and system.destructive on the
+ * same characters, and a card that painted both would hand its renderer two ranges over one fragment. The
+ * command gate marks every matched class now (guard/command-gate.ts says why), so this is the second caller. */
+export const mergeSpans = (spans: readonly CommandSpan[]): CommandSpan[] => {
     const merged: CommandSpan[] = [];
     for (const span of [...spans].sort((left, right) => left.start - right.start || left.end - right.end)) {
         const last = merged.at(-1);
@@ -484,7 +489,7 @@ const MATCHES: Readonly<Record<CommandClass, (command: string, context: CommandC
  * command text alone, which is every caller that has no filesystem to consult. */
 export const matchCommand = (command: string, context?: CommandContext): CommandMatch[] =>
     CommandClassSchema.options.flatMap((commandClass) => {
-        const spans = normalize(MATCHES[commandClass](command, context));
+        const spans = mergeSpans(MATCHES[commandClass](command, context));
         return spans.length === 0 ? [] : [{ commandClass, spans }];
     });
 

package/src/contracts/secrets.contract.ts

@@ -1,5 +1,16 @@
 import { oc } from "@orpc/contract";
-import { SecretInventorySchema, SecretKeyParamSchema, SecretKeysSchema, SecretRevealSchema, SecretSetSchema } from "../schemas/secrets.js";
+import {
+    CredentialGateSchema,
+    CredentialGateSubjectParamSchema,
+    CredentialGatesSchema,
+    CredentialGrantSchema,
+    CredentialRequestSchema,
+    SecretInventorySchema,
+    SecretKeyParamSchema,
+    SecretKeysSchema,
+    SecretRevealSchema,
+    SecretSetSchema,
+} from "../schemas/secrets.js";
 import { OkSchema } from "../schemas/shared.js";
 
 // User-supplied env-var secrets, written to the sandbox's gitignored desired-state/.env (which
@@ -54,4 +65,59 @@ export const secretsContract = {
         })
         .input(SecretKeyParamSchema)
         .output(SecretRevealSchema),
+    /* THE APPROVAL GATES, four routes with three different audiences, which is why they are worth reading as a
+     * group.
+     *
+     * `gates` is READ BY EVERYONE who needs to explain the sandbox to itself: the Secrets view draws a badge
+     * from it, and the AGENT is allowed it too (auth/grants.ts), because a model that cannot see which
+     * credentials are gated cannot tell "not connected" from "needs Bob", and the difference decides whether
+     * its next move is to ask a person or to go looking for another road. It answers names, subjects and
+     * approver addresses; there is nothing else in it to leak.
+     *
+     * `setGate` and `removeGate` are the OWNER's alone, enforced in-route with authorizeOwner rather than by
+     * the /secrets role floor, because the floor is maintainer and a maintainer is exactly who a gate is
+     * sometimes written about. The policy lives off the workspace beside the credential vault for the same
+     * reason the vault does: `.intentic/config/` is tracked and agent-editable, so a gate stored there would
+     * be a lock whose key is in the room with the agent.
+     *
+     * `request` is the AGENT's door, and the only one of the four that can park a turn: it raises the release
+     * card and waits, so a gated account can be asked for rather than merely discovered to be absent. */
+    gates: oc
+        .route({
+            method: "GET",
+            path: "/secrets/gates",
+            summary: "Which credentials need somebody's approval",
+            description:
+                "What is gated and who may release it. Names and addresses only, never values, and the agent may read it too: knowing a credential needs Bob is what stops it concluding the account is simply not connected.",
+        })
+        .output(CredentialGatesSchema),
+    setGate: oc
+        .route({
+            method: "PUT",
+            path: "/secrets/gates/{subject}",
+            summary: "Put a credential behind named approvers",
+            description:
+                "Names exactly who may release one secret or one connected account, and how far a single release goes. The owner's call alone. A signed-in browser or a mounted server cannot be released for one use, so those are always for the rest of the conversation.",
+        })
+        .input(CredentialGateSchema)
+        .output(OkSchema),
+    removeGate: oc
+        .route({
+            method: "DELETE",
+            path: "/secrets/gates/{subject}",
+            summary: "Stop requiring approval for a credential",
+            description: "Removes one gate, so the agent can use that credential the way it uses any other. The owner's call alone.",
+        })
+        .input(CredentialGateSubjectParamSchema)
+        .output(OkSchema),
+    request: oc
+        .route({
+            method: "POST",
+            path: "/secrets/request",
+            summary: "Ask a named person to release a credential",
+            description:
+                "Raises the release card in the live conversation and waits for one of the people named on it. Refused, rather than held, when there is nobody to ask: an unattended turn, no live conversation, or a click with no verified identity behind it.",
+        })
+        .input(CredentialRequestSchema)
+        .output(CredentialGrantSchema),
 };

package/src/events.ts

@@ -4,6 +4,7 @@ import { AgentSummarySchema, LandConflictSchema } from "./schemas/agents.js";
 import { RateLimitInfoSchema } from "./schemas/claude-gate.js";
 import { FastModeStateSchema } from "./schemas/fast-mode.js";
 import { AccountUsageSchema, AgentReplySchema, ProviderRefusalSchema, UsageWindowSchema } from "./schemas/plan-limits.js";
+import { CredentialGateKindSchema, CredentialGateScopeSchema, CredentialLaneSchema } from "./schemas/secrets.js";
 import { ShareDetailSchema } from "./schemas/share.js";
 import { MemberRoleSchema } from "./schemas/shared.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "./schemas/terminal.js";
@@ -35,10 +36,16 @@ export type AskQuestion = z.infer<typeof AskQuestionSchema>;
  * 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
+ * `spans` is where the pattern match fired, computed by the classifier at the moment it did (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.
+ * would be a second classifier, and the day the two disagreed the card would be marking a fragment the daemon
+ * never saw. Offsets are into `text` AFTER truncation, so they are always paintable.
+ *
+ * IT IS NOT A CLAIM ABOUT WHY THE CARD EXISTS, and the card no longer presents it as one. The reason is the
+ * judge's sentence in the title; these are the fragments TRIAGE noticed, all of the matched classes' rather
+ * than whichever sorts first — the card used to show one class's and label them "Stopped for", so a command
+ * that cleaned a build directory on its way to publishing offered `rm -rf …` as its reason under a sentence
+ * about npm. Under the hard rule the title DOES name a class, so there the marks are that class's alone.
  *
  * `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. */
@@ -52,7 +59,9 @@ export const ProgramAskSchema = z.object({
         ),
     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."),
+        .describe(
+            "Which fragments of the text the pattern match fired on: every matched class's, or, under the hard rule, only the class the title names. Offsets into text, in order, never overlapping.",
+        ),
 });
 export type ProgramAsk = z.infer<typeof ProgramAskSchema>;
 
@@ -80,16 +89,20 @@ export const PermissionAskSchema = z.object({
     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.",
     ),
-    /* THE JUDGE'S OWN SENTENCE, and on a command card it is the reason the card exists rather than a note added
-     * to it: the judge read the owner's policy and the program and decided this needed asking, and this is what
-     * it decided. Written by the quick model from the program text and the policy, never by the agent being
-     * gated — a card whose persuasive half was authored by the thing it is stopping argues for its own approval,
-     * and the turns that raise cards are exactly the ones whose account of themselves may be a stranger's. */
+    /* THE JUDGE'S OWN SENTENCE, WHERE THE TITLE IS SOMEBODY ELSE'S. On an ordinary command card the sentence IS
+     * the title (the judge read the owner's policy and the program, and its account of why this needs asking is
+     * the only account there is), so this is left off rather than printing the same words twice. It carries the
+     * sentence on the two cards whose title says something the sentence cannot: the hard rule's, which names the
+     * consequence that stopped it, and a machine command's, which names the computer.
+     *
+     * Written by the quick model from the program text and the policy, never by the agent being gated — a card
+     * whose persuasive half was authored by the thing it is stopping argues for its own approval, and the turns
+     * that raise cards are exactly the ones whose account of themselves may be a stranger's. */
     explain: z
         .string()
         .optional()
         .describe(
-            "One plain sentence saying what the program does and why it is being asked about. Written by the judge that read your safety policy, never by the agent being gated.",
+            "One plain sentence saying what the program does and why it is being asked about, where the title says something else. Written by the judge that read your safety policy, never by the agent being gated.",
         ),
 });
 export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
@@ -209,6 +222,39 @@ export const PaymentOfferSchema = z.object({
 });
 export type PaymentOffer = z.infer<typeof PaymentOfferSchema>;
 
+/* ONE GATED CREDENTIAL, ASKED FOR, the card the daemon raises when the agent reaches for a secret or a
+ * connected account the owner put behind a named person (secrets/credential-gate.ts).
+ *
+ * Every field but `why` is the daemon's own: the subject and its approvers come off the gate policy the owner
+ * wrote (which lives off the workspace, where the agent cannot edit it), the lane and detail come from the
+ * exit that was about to spend the credential, and the scope is the policy's, not the asker's. The model
+ * contributes one line of rationale and nothing else, which is what makes the card impossible to
+ * misrepresent: a prompt-injected turn can ask for the production password and cannot make the card say it is
+ * asking for the staging one.
+ *
+ * THE APPROVERS ARE ON THE CARD because the card is not addressed to "the owner" the way every other offer
+ * here is — it is addressed to a LIST, the server checks the clicker's verified identity against it, and a
+ * click from anybody else is refused with the card left standing. So the names have to be visible: a card
+ * whose buttons do nothing for the person looking at it must say who it is waiting for. */
+export const CredentialOfferSchema = z.object({
+    // The gate's subject: a secret's reference name (`DATABASE_URL`) or a capability id (`reddit`).
+    subject: z.string().describe("Which credential is being asked for."),
+    kind: CredentialGateKindSchema,
+    lane: CredentialLaneSchema,
+    // Where it would go, in the reader's terms: the head of the agent's command line, the page's host, or the
+    // capability's own name. Reference-form by construction on the secret lanes (resolution is what fires the
+    // ask), so this can be shown without leaking anything.
+    detail: z
+        .string()
+        .optional()
+        .describe("Where it would go: the start of the command, the site, or what is being mounted. Never a value: the command still reads as a reference at this point."),
+    // The agent's one-line case, the only prose on the card that is the model's.
+    why: z.string().optional().describe("The agent's case for using it, and the only words on this card that are the agent's."),
+    approvers: z.array(z.string()).describe("Who may release it. A click from anyone else is refused and leaves the card standing."),
+    scope: CredentialGateScopeSchema,
+});
+export type CredentialOffer = z.infer<typeof CredentialOfferSchema>;
+
 // One provider-advertised slash command, an ACP agent's available_commands entry, or a Claude Code session's
 // supportedCommands() (its built-ins plus the workspace's own .claude/commands and any plugin/skill commands).
 // `hint` is the argument placeholder the popover shows after the name.
@@ -360,6 +406,7 @@ const terminalHelpCard = {
 const serviceOfferCard = { requestId: z.string(), offer: ServiceOfferSchema };
 const capabilityOfferCard = { requestId: z.string(), offer: CapabilityOfferSchema };
 const paymentOfferCard = { requestId: z.string(), offer: PaymentOfferSchema };
+const credentialOfferCard = { requestId: z.string(), offer: CredentialOfferSchema };
 
 /* HOW AN OFFER'S ACCEPTED HALF ENDED, the follow-up that lands on the card after the click. Each is the body of
  * the frame that reports it (`service_receipt`, `capability_outcome`, `payment_receipt`) and the field the
@@ -382,6 +429,15 @@ export const PaymentReceiptSchema = z.object({
     network: z.string().optional(),
 });
 export type PaymentReceipt = z.infer<typeof PaymentReceiptSchema>;
+/* WHO RELEASED A GATED CREDENTIAL, or that a person refused it. `released` carries the approver's own address,
+ * read off the VERIFIED identity on the reply rather than off anything the click claimed, which is what makes
+ * the row an audit line rather than a rendering. There is no receipt for a card nobody answered: `resolved`
+ * already says so, and inventing "refused" for a deadline would put words in a person's mouth. */
+export const CredentialReceiptSchema = z.object({
+    outcome: z.enum(["released", "refused"]),
+    approvedBy: z.string().optional(),
+});
+export type CredentialReceipt = z.infer<typeof CredentialReceiptSchema>;
 
 /* THE THREE RESTORABLE CARDS, named so the turn journal can hold them verbatim: a parked turn's raised cards
  * are written down beside its prompt (sandbox turn-journal.ts), and a daemon death under the park restores the
@@ -468,6 +524,12 @@ export const TranscriptPaymentOfferSchema = z.object({
     receipt: PaymentReceiptSchema.optional().describe("How the approved payment ended (the payment_receipt frame)."),
 });
 export type TranscriptPaymentOffer = z.infer<typeof TranscriptPaymentOfferSchema>;
+export const TranscriptCredentialOfferSchema = z.object({
+    ...credentialOfferCard,
+    status: OfferStatusSchema.describe("Where the decision stands."),
+    receipt: CredentialReceiptSchema.optional().describe("Who released it, or that somebody refused (the credential_receipt frame)."),
+});
+export type TranscriptCredentialOffer = z.infer<typeof TranscriptCredentialOfferSchema>;
 
 // ---- transcript rows ----
 // What a conversation is made of, on every surface: the rows the daemon folds a turn's frames into as they
@@ -664,13 +726,26 @@ export const TranscriptRowSchema = z.object({
     serviceOffer: TranscriptServiceOfferSchema.optional().describe("The priced service run this row offered, the decision, and the receipt."),
     capabilityOffer: TranscriptCapabilityOfferSchema.optional().describe("The capability setup this row asked for, the decision, and the outcome."),
     paymentOffer: TranscriptPaymentOfferSchema.optional().describe("The payment this row asked for, the decision, and the receipt."),
+    credentialOffer: TranscriptCredentialOfferSchema.optional().describe(
+        "The gated credential this row asked to use, who may release it, and who did.",
+    ),
 });
 export type TranscriptRow = z.infer<typeof TranscriptRowSchema>;
 
 /* THE CARD FIELDS A ROW CAN CARRY, as one list, for every reader that has to ask "does this row hold a card":
  * the fold that counts a card-only bubble as a row, the chat's row count (a branch is cut by it), and the
  * surfaces that draw whichever card a bubble is waiting on. */
-export const CARD_FIELDS = ["plan", "question", "permission", "browserHelp", "terminalHelp", "serviceOffer", "capabilityOffer", "paymentOffer"] as const;
+export const CARD_FIELDS = [
+    "plan",
+    "question",
+    "permission",
+    "browserHelp",
+    "terminalHelp",
+    "serviceOffer",
+    "capabilityOffer",
+    "paymentOffer",
+    "credentialOffer",
+] as const;
 export type CardField = (typeof CARD_FIELDS)[number];
 export type TranscriptCards = Pick<TranscriptRow, CardField>;
 // Whether a row holds a card at all, answered or not.
@@ -1164,6 +1239,20 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * case the signed authorization expires unused and NOTHING left the wallet. A skip needs no receipt,
      * nothing moved, and `resolved` already says so. */
     PaymentReceiptSchema.extend({ kind: z.literal("payment_receipt"), requestId: z.string() }),
+    /* A GATED CREDENTIAL awaiting a NAMED person's click, the one card on this stream that is not addressed to
+     * the owner: the daemon holds an exit (a `{{secret:…}}` about to resolve, a browser field about to be
+     * typed into, a connected account about to be mounted) parked until one of the gate's approvers releases
+     * it (secrets/credential-gate.ts). Raised OUTSIDE the turn generator like the offers above — the exits run
+     * inside a PreToolUse hook and inside the daemon's own `secrets request` route — so it is not journalled
+     * for restore: its waiter is a held hook or a held connection, both of which die with the daemon, and the
+     * next use after a restart simply asks again. Settles through the same `POST /agent/reply`, which is where
+     * the clicker's identity is checked against `offer.approvers`. */
+    z.object({ kind: z.literal("credential_offer"), ...credentialOfferCard }),
+    /* WHO RELEASED IT, pushed the moment a person decided, so the settled card names them rather than saying
+     * only that something was approved: `released` with the approver's verified address, or `refused` when a
+     * person said no. Nothing is pushed for a card nobody answered — `resolved` already says that, and a
+     * deadline is not a refusal by anybody. */
+    CredentialReceiptSchema.extend({ kind: z.literal("credential_receipt"), requestId: z.string() }),
     // The card above named by `requestId` is released, the user answered (or dismissed it, or the turn was
     // stopped out from under it), so the turn is executing again. Emitted by whoever parked, the moment its
     // waiter settles, because the park's END is otherwise invisible on this stream: nothing else here says

package/src/safety-policy.ts

@@ -46,6 +46,29 @@ import type { CommandClass } from "./schemas/agent.js";
  * set shrinks to block devices when that lands. */
 export const HARD_RULE_CLASSES: ReadonlySet<CommandClass> = new Set<CommandClass>(["system.destructive"]);
 
+/* WHETHER THE JUDGE RUNS AT ALL, and whether its answer is allowed to stop anything. The owner's switch over
+ * everything below, and the reason it exists is that a tier which spends a model call and can interrupt you is a
+ * tier somebody is entitled to decline — the old rulebook could be set to allow everything, and losing that when
+ * the judge arrived made the redesign a thing you could only opt further INTO.
+ *
+ * THREE STATES, and the middle one is the one worth arguing for. Nobody trusts a judge they have not watched,
+ * and the only evidence that it asks about the right things is a log of what it decided while it could not
+ * interrupt them. Same shape, and the same reasoning, as the tier judge's own Measure state (settings.autoTier).
+ *
+ *   off    nothing is judged. No model call, no cards, nothing written to the log. Triage still runs, because
+ *          the hard rule below is built on it and costs nothing.
+ *   watch  the judge runs on every triage hit and every verdict is recorded, and NOTHING is ever held: an `ask`
+ *          is logged as an ask and the command runs anyway. What it costs is one model call per triage hit;
+ *          what it buys is the Recent decisions list, read against a policy nobody has tested yet.
+ *   on     the verdict decides, which is the behaviour this design describes everywhere else.
+ *
+ * THE HARD RULE IS NOT UNDER THIS SWITCH, at any setting. HARD_RULE_CLASSES is a typed verdict rather than a
+ * judgment, it never needed a model, and the Safety page promises in as many words that it cannot be edited
+ * away. So `off` and `watch` still raise a card for wiping a block device or deleting under /history — with a
+ * sentence saying the judge did not weigh in, rather than one pretending it did. */
+export const CommandJudgeModeSchema = z.enum(["off", "watch", "on"]);
+export type CommandJudgeMode = z.infer<typeof CommandJudgeModeSchema>;
+
 /* WHAT THE JUDGE ANSWERS. Three verdicts, and each is a different instruction to the gate:
  *
  *   allow   run it, say nothing, nobody is interrupted. The ordinary answer for a triage false positive,

package/src/schemas/agents.ts

@@ -86,6 +86,12 @@ export const AgentAttentionSchema = z.object({
     // A missing capability parked on the owner's setup (capabilities/capability-offer.ts), the agent is
     // waiting for something to be connected, so the lane can 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 (secrets/credential-gate.ts). Its own lane because
+    // it is the one pause the person reading the board may not be able to clear: every other card here waits
+    // for whoever is looking at it, this one waits for the specific people the gate names.
+    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."),
     conflict: z.boolean().describe("Its work cannot be merged without somebody resolving a clash."),
 });
 export type AgentAttention = z.infer<typeof AgentAttentionSchema>;