@intentic/sandbox-contract 1.240.0 → 1.242.0

package/src/approvals-execution.ts

@@ -0,0 +1,96 @@
+/* HOW AN APPROVED THING GETS DONE, the shared half, written once because the daemon acts on it, the app draws
+ * it, and the two have to agree on the same seconds.
+ *
+ * THERE IS NO EXECUTOR AUTOMATION, and its absence is the design. Publishing used to be a scheduled automation:
+ * a cron waking every few minutes, running a shell guard over the queue directory, almost always finding
+ * nothing, a job whose entire job was to ask "yet?" forever. It also made the approve button conditional on a
+ * row in a list nobody had asked for: delete the automation and approvals silently went nowhere, with the
+ * button still there and still saying yes. The daemon owns execution (approvals-executor.ts). It knows the
+ * moment an item comes due because it is the process that wrote it, so it sleeps until exactly then and costs
+ * nothing in between.
+ *
+ * APPROVAL IS NOT "DO IT NOW", IT IS "DO IT UNLESS I STOP YOU". A post is public and permanent the instant it
+ * lands, a booking is charged, and the gap between realising and clicking is about two seconds, so an approved
+ * item carrying no date of its own is dated HOLD into the future, and the queue counts it down in the open. The
+ * hold is stored as an ordinary scheduledAt rather than as a new state, which is what keeps it honest: it
+ * survives a restart, it reads as one number in the same place a scheduled item's date is already read, and
+ * calling it off is the "put it back in review" click that was there before any of this.
+ *
+ * A MINUTE, because that is the whole width of the decision: long enough to catch the wrong word you see the
+ * moment the row stops being a form, short enough that approving something still feels like doing it. */
+export const APPROVAL_HOLD_MS = 60_000;
+
+/* WHO CAN BE SENT BY CODE ALONE. A connector reached through a real API with a stored credential is a request
+ * the daemon can make itself, no model, no browser, no turn, and it either got a 200 or it did not. A
+ * connector that IS a logged-in browser session (reddit, x) has no such door: posting there means driving a
+ * page whose markup moves under you, past dialogs and rate screens nobody can enumerate in advance, which is
+ * precisely the work an agent turn exists to absorb.
+ *
+ * So the split follows what the platform actually offers rather than what would be cheaper, and it is stated
+ * here rather than guessed at a call site, because being wrong in the optimistic direction means a post that
+ * silently never goes out. A platform absent from this set is published by an agent turn, which always works
+ * and merely costs more. */
+export const DIRECT_PUBLISH_PLATFORMS: ReadonlySet<string> = new Set(["discord"]);
+
+// The workspace-relative directory both prompts below name, spelled once.
+const APPROVALS_DIR = ".intentic/config/approvals";
+
+// The status bookkeeping every executing turn is told, identical across kinds so the file the queue reads back
+// is the same shape whoever wrote it.
+const WRITE_BACK = [
+    `Before you act on one, set its "status" to "running" and "startedAt" to the epoch ms, so a turn that dies`,
+    `here cannot do it twice. When it is done, set "status":"done" plus "finishedAt" (epoch ms) and, where`,
+    `there is one, "result": the post's URL, a confirmation number, whatever a person would want to go and`,
+    `look at. If it failed, set "status":"failed" plus an "error" saying what went wrong in plain words the`,
+    `owner can act on, then move to the next one instead of retrying in a loop.`,
+];
+
+/* WHAT THE PUBLISH TURN IS TOLD, for the posts no API can carry. It NAMES the files rather than saying "go and
+ * look": the daemon has already decided what is due, and a turn that re-derives that decision can disagree
+ * with it, sending something the owner pulled back a second ago, or skipping something it judged not ready.
+ * The turn's job is the part only it can do, which is working the platform's own UI.
+ *
+ * It still writes the outcome back into the file, because the file is where the queue reads it, and a post
+ * that went out without saying so is a post the owner sends twice. */
+export const publishTurnPrompt = (posts: readonly { readonly id: string; readonly platform: string }[]): string =>
+    [
+        `Publish these approved posts, which are due now. They live in ${APPROVALS_DIR}/, one JSON file each:`,
+        ``,
+        ...posts.map((post) => `- ${post.id}.json (${post.platform})`),
+        ``,
+        `Take them ONE AT A TIME, and for each:`,
+        `1. Read the file. ${WRITE_BACK[0]}`,
+        `   ${WRITE_BACK[1]}`,
+        `2. Post exactly its "content": with its "title", "target" and "media", using that platform's skill.`,
+        `   A "target" that is a URL means this post is a REPLY to whatever is at it: open that exact URL and`,
+        `   reply where it lands. On reddit a comment permalink (.../comments/<post>/<slug>/<comment>/) has to`,
+        `   nest under that comment rather than becoming a new top-level comment on the thread.`,
+        `3. ${WRITE_BACK[2]} ${WRITE_BACK[3]}`,
+        `   ${WRITE_BACK[4]}`,
+        ``,
+        `Never rewrite the content: the owner approved these exact words. Never touch a file not listed above.`,
+    ].join(`\n`);
+
+/* WHAT THE ACTION TURN IS TOLD. The same discipline as a publish turn, named files, status written before and
+ * after, with the work itself coming from the file: the agent that proposed the action wrote its own
+ * instructions for this moment, knowing this turn would arrive with none of the conversation. The owner's yes
+ * covered what `summary` and `details` said, so the instructions are carried out as written and nothing beyond
+ * them is done; an action that turns out to need more than it said is failed with that sentence, not
+ * improvised. */
+export const actionTurnPrompt = (actions: readonly { readonly id: string; readonly summary: string }[]): string =>
+    [
+        `Carry out these approved actions, which are due now. They live in ${APPROVALS_DIR}/, one JSON file each:`,
+        ``,
+        ...actions.map((action) => `- ${action.id}.json: ${action.summary}`),
+        ``,
+        `Take them ONE AT A TIME, and for each:`,
+        `1. Read the file. ${WRITE_BACK[0]}`,
+        `   ${WRITE_BACK[1]}`,
+        `2. Do exactly what its "instructions" say. The owner approved what "summary" and "details" describe and`,
+        `   nothing more: if carrying it out would need something they do not say, stop and fail it with that`,
+        `   reason rather than improvising.`,
+        `3. ${WRITE_BACK[2]} ${WRITE_BACK[3]}`,
+        `   ${WRITE_BACK[4]}`,
+        ``,
+        `Never touch a file not listed above.`,
+    ].join(`\n`);

package/src/arrival.ts

@@ -0,0 +1,160 @@
+import { z } from "zod";
+import { NeedsActionSchema } from "./needs-action.js";
+
+/* AN ARRIVAL: something coming INTO this sandbox, whatever it came from and whatever it is made of.
+ *
+ * There used to be three of these, each with its own schemas, its own routes and its own card, and the split
+ * was by ARTIFACT: a `sandbox.toml` had one surface, an environment bundle a second, a foreign assistant's
+ * home directory a third. That is the wrong axis. The owner's question is never "which of your three import
+ * features is this" — it is "I have a thing, take what is safe from it" — and the three artifacts answer it
+ * with the same four moves: read the thing, show what would land, take the ticked rows, say what is left.
+ *
+ * So there is ONE pipeline, and the artifact is a parser:
+ *
+ *   source  →  plan   (items the owner ticks, refused lines, needsAction said BEFORE anything writes)
+ *           →  apply  (the ticked ids, against a plan RE-DERIVED from the held bytes)
+ *           →  report (what landed, what did not and why, what still needs a person)
+ *
+ * WHAT THE MERGE FIXED, beyond three of everything: the bundle door was the only one that WROTE ON FILE PICK.
+ * It is also the most destructive of the three — a bundle lands over a workspace rather than beside it — so
+ * the one arrival most deserving of a preview was the one without it. Sharing the pipeline is what gave it
+ * one, and what makes "untick the 6 GB monorepo" a thing an owner can say to a bundle at all.
+ *
+ * THE OUTBOUND HALF IS NOT HERE. Deriving a definition, packing a bundle and publishing the workspace repo
+ * live on definition.ts and schemas/environment.ts, because they answer the opposite question and share no
+ * shape with this one. */
+
+// Which of the four things this is. The two assistants are separate members rather than one "foreign": the
+// checklist badges the source by name, and an owner who packed a Hermes folder should read the word Hermes.
+export const ArrivalSourceSchema = z.enum(["definition", "bundle", "hermes", "openclaw"]);
+export type ArrivalSource = z.infer<typeof ArrivalSourceSchema>;
+
+// The subset a foreign assistant's home directory can be. Narrower than ArrivalSource on purpose: a connected
+// computer is scanned for these two and never for a bundle, which is a file, not a setup.
+export const AssistantSourceSchema = z.enum(["hermes", "openclaw"]);
+export type AssistantSource = z.infer<typeof AssistantSourceSchema>;
+
+/* WHAT AN ITEM BECOMES HERE, not what it was there. The apply loop dispatches on this and the checklist
+ * groups by it, so an owner reads "3 skills, 2 connections" rather than a foreign directory listing or a tar
+ * table of contents. One enum across all four sources, which is what makes the union honest: a repository is
+ * a `repo` whether it arrived as a remote to clone (definition) or as a git dir in a tar (bundle), and the
+ * owner ticking it means the same thing either way. */
+export const ArrivalGroupSchema = z.enum([
+    // The /work tree as a whole, cloned from the remote a definition's `[workspace]` names.
+    "workspace",
+    // One repository: cloned from its remote, or unpacked with its real git dir from a bundle.
+    "repo",
+    // Loose files landing in /work: a bundle's workspace bytes, an assistant's notes folder.
+    "files",
+    // Transcripts, checkpoint timelines, ledgers. Bundle-only — nothing else can reference them.
+    "history",
+    // The overlay Dockerfile.
+    "environment",
+    // One connection, landing unauthenticated unless its secret travelled.
+    "capability",
+    // The agent settings that differ from their defaults.
+    "settings",
+    // A merge into CLAUDE.md / AGENTS.md.
+    "memory",
+    "skill",
+    "automation",
+    // One credential VALUE, and the only group gated behind the apply's second consent.
+    "secret",
+]);
+export type ArrivalGroup = z.infer<typeof ArrivalGroupSchema>;
+
+/* ONE ROW OF THE CHECKLIST. Two flags rather than one, because the four sources fail an item for two
+ * genuinely different reasons and collapsing them would lose the one the owner can act on:
+ *
+ *   `applicable: false`  the target already holds this, so it CANNOT be ticked. A definition and a bundle
+ *                        land beside what is there, never over it, so an existing repo directory or
+ *                        capability id greys its row and prints the reason.
+ *   `recommended: false` it can be ticked and the reader should look first. An adapter's judgment about a
+ *                        server URL pointing at the old machine, or an env key that reads as tuning.
+ *
+ * A source that has no use for one of them fills it constantly: a definition recommends everything it can
+ * apply, an assistant adapter refuses inside its own walk rather than emitting inapplicable rows. */
+export const ArrivalItemSchema = z.object({
+    /* Deterministic and derived from the artifact ("repo:intentic", "skill:weather", "bundle:history"), which
+     * is the whole reason the apply may re-derive: the ids the owner ticked name the same items in the
+     * second derivation as in the one the browser rendered. */
+    id: z.string(),
+    group: ArrivalGroupSchema,
+    // The checklist line, in plain words: "Repository intentic", "Skill, weather", "Workspace files".
+    label: z.string(),
+    detail: z.string().optional(),
+    applicable: z.boolean(),
+    // Why it cannot be ticked. Present exactly when `applicable` is false.
+    reason: z.string().optional(),
+    recommended: z.boolean(),
+    /* Names of the secrets this row would store — never values. Non-empty rows only move when the apply
+     * carries `includeSecrets`; the report names what stayed behind rather than pretending it landed. */
+    secrets: z.array(z.string()),
+});
+export type ArrivalItem = z.infer<typeof ArrivalItemSchema>;
+
+export const ArrivalPlanSchema = z.object({
+    source: ArrivalSourceSchema,
+    /* Names the held artifact for the apply call. Minted per plan; a new plan replaces the held one, because
+     * an owner changing their mind is the ordinary case and not a conflict. */
+    token: z.string(),
+    // What the artifact calls itself: a definition's `name`, a bundle's source sandbox. For the reader only.
+    name: z.string().optional(),
+    items: z.array(ArrivalItemSchema),
+    /* Whether this artifact holds credential VALUES at all, which is what decides whether the apply's second
+     * consent is even a question. A definition is false by construction (it carries names, never values); a
+     * bundle is whatever its owner chose at export; an assistant's home directory is true whenever any row
+     * names a secret. The card asks with a toggle only when this is true, so the ordinary arrival is not made
+     * to answer a question about credentials that do not exist. */
+    carriesSecrets: z.boolean(),
+    // What the reader saw and will not offer at all: sessions, logs, pairing state, a tar entry this daemon
+    // refuses to write. Listed rather than silent.
+    refused: z.array(z.string()),
+    // What is already known not to move mechanically, surfaced at PREVIEW time so the owner ticks with open
+    // eyes and again on the report.
+    needsAction: z.array(NeedsActionSchema),
+});
+export type ArrivalPlan = z.infer<typeof ArrivalPlanSchema>;
+
+export const ArrivalApplySchema = z.object({
+    token: z.string(),
+    // The ticked ids. Ids the re-derived plan does not contain are ignored rather than erroring: the artifact
+    // is the truth, and a stale checklist must not block the items that still exist.
+    items: z.array(z.string()),
+    /* The owner's explicit consent to move credential VALUES, asked once, on the inbound side, for every
+     * source. It used to be asked at EXPORT time for a bundle and at APPLY time for an assistant, which is
+     * the same question in two places with two different answers about who is consenting to what. */
+    includeSecrets: z.boolean(),
+});
+export type ArrivalApply = z.infer<typeof ArrivalApplySchema>;
+
+export const ArrivalReportSchema = z.object({
+    applied: z.array(z.object({ id: z.string(), group: ArrivalGroupSchema, label: z.string() })),
+    // Ticked and did not land, each with its reason. Distinct from `refused` and from inapplicable rows,
+    // which were never attempted.
+    failed: z.array(z.object({ id: z.string(), label: z.string(), error: z.string() })),
+    refused: z.array(z.string()),
+    needsAction: z.array(NeedsActionSchema),
+});
+export type ArrivalReport = z.infer<typeof ArrivalReportSchema>;
+
+/* ONE OF THE OWNER'S OWN COMPUTERS, as an arrival source that needs no packing at all: the daemon walks the
+ * machine's home folder over the socket it already holds. Read on the card's first render for every enrolled
+ * machine, so the offer appears before the owner has read a single instruction.
+ *
+ * `found` absent means "connected, and nothing to bring in from here", which is a real answer worth rendering
+ * quietly rather than an error: the machine may simply not be the one the assistant runs on. */
+export const ArrivalHostSchema = z.object({
+    id: z.string(),
+    online: z.boolean(),
+    found: AssistantSourceSchema.optional(),
+    // Why this machine cannot be read right now, when it cannot: asleep, or its own refusal, in its words.
+    detail: z.string().optional(),
+});
+export type ArrivalHost = z.infer<typeof ArrivalHostSchema>;
+export const ArrivalHostsSchema = z.object({ hosts: z.array(ArrivalHostSchema) });
+
+// Read a setup off a connected computer instead of an upload. Answers with a plan exactly as the upload door
+// does; everything after this point is identical whichever door the arrival came through.
+export const ArrivalScanSchema = z.object({ host: z.string().min(1) });
+export type ArrivalScan = z.infer<typeof ArrivalScanSchema>;

package/src/capability-ledger.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { type AgentCapabilities, capabilitiesOf, limitationsOf } from "./agent-catalog.js";
+import { capabilitiesOf, limitationsOf } from "./agent-catalog.js";
+import type { AgentCapabilities } from "./agent-runtimes.js";
 
 /* THE CAPABILITY LEDGER, which claims in the record are backed by machinery, and which by prose.
  *
@@ -118,9 +119,10 @@ describe("a descriptive claim reaches the user", () => {
         // A boolean's floor is `false` and needs no entry; every other descriptive field has to name its own.
         // Asserted against the KEYS of DIMINISHED so the failure prints the floors that do exist, which is what
         // tells "this field was never added" apart from "this field was renamed and its entry left behind".
-        expect(boolean ? [field] : Object.keys(DIMINISHED), `${field} is descriptive and not a boolean: add its weakest value to DIMINISHED above`).toContain(
-            field,
-        );
+        expect(
+            boolean ? [field] : Object.keys(DIMINISHED),
+            `${field} is descriptive and not a boolean: add its weakest value to DIMINISHED above`,
+        ).toContain(field);
         const floor = boolean ? false : DIMINISHED[field];
 
         const lacking: AgentCapabilities = { ...CEILING, [field]: floor };

package/src/card-status.ts

@@ -0,0 +1,93 @@
+import type { CardField, TranscriptCards, TranscriptRow } from "./events.js";
+import type { AgentReply } from "./schemas/plan-limits.js";
+
+/* HOW A REPLY SETTLES THE CARD IT ANSWERS, the one derivation, used by the fold when the `resolved` frame lands
+ * (transcript-fold.ts) and by a chat freezing its own card the instant its answer is accepted, before that
+ * frame comes back. Two callers, one rule, which is what keeps "answered" looking the same on the window that
+ * clicked and on every window that only watched.
+ *
+ * No reply is nobody answering: the turn was stopped, or died under the card, which is not a decision, so every
+ * card reads `cancelled`. A reply of the wrong kind cannot reach a card of another, the requestId is what
+ * matched it, and reads as unanswered rather than inventing a decision. */
+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;
+    if (plan !== undefined) {
+        out.plan = { ...plan, status: reply?.kind !== "plan" ? "cancelled" : reply.approve ? "approved" : "rejected" };
+    }
+    if (question !== undefined) {
+        const answers = reply?.kind === "question" ? reply.answers : undefined;
+        out.question = {
+            ...question,
+            status: reply?.kind === "question" && reply.cancelled !== true ? "answered" : "cancelled",
+            ...(answers === undefined ? {} : { answers }),
+        };
+    }
+    if (permission !== undefined) {
+        out.permission = {
+            ...permission,
+            status:
+                reply?.kind !== "permission"
+                    ? "cancelled"
+                    : reply.decision === "deny"
+                      ? "denied"
+                      : reply.decision === "always"
+                        ? "always"
+                        : "allowed",
+        };
+    }
+    if (browserHelp !== undefined) {
+        out.browserHelp = { ...browserHelp, status: reply?.kind !== "browser_help" ? "cancelled" : reply.helped ? "helped" : "declined" };
+    }
+    if (terminalHelp !== undefined) {
+        out.terminalHelp = { ...terminalHelp, status: reply?.kind !== "terminal_help" ? "cancelled" : reply.helped ? "helped" : "declined" };
+    }
+    if (serviceOffer !== undefined) {
+        out.serviceOffer = { ...serviceOffer, status: reply?.kind !== "service_offer" ? "cancelled" : reply.approve ? "approved" : "skipped" };
+    }
+    // A yes settles the DECISION, not the ask: the owner is now setting the capability up, so the card moves to
+    // `connecting` and stays there until the capability_outcome frame says how the setup ended.
+    if (capabilityOffer !== undefined) {
+        out.capabilityOffer = {
+            ...capabilityOffer,
+            status: reply?.kind !== "capability_offer" ? "cancelled" : reply.connect ? "connecting" : "skipped",
+        };
+    }
+    // A yes settles the decision; whether the money actually moved is the payment_receipt frame's to say.
+    if (paymentOffer !== undefined) {
+        out.paymentOffer = { ...paymentOffer, status: reply?.kind !== "payment_offer" ? "cancelled" : reply.approve ? "approved" : "skipped" };
+    }
+    return out;
+};
+
+/* The same cards with every one still `pending` frozen as `cancelled`: the turn ended out from under the ask
+ * (a Stop, a death, a failure) and nobody decided anything. Returns the SAME object when nothing was pending,
+ * so a caller can tell a row that changed from one that did not. */
+export const cancelledCards = (cards: TranscriptCards): TranscriptCards => {
+    const out: Cards = {};
+    let changed = false;
+    for (const field of [
+        "plan",
+        "question",
+        "permission",
+        "browserHelp",
+        "terminalHelp",
+        "serviceOffer",
+        "capabilityOffer",
+        "paymentOffer",
+    ] as const) {
+        const card = cards[field];
+        if (card === undefined) {
+            continue;
+        }
+        if (card.status === "pending") {
+            changed = true;
+            (out as Record<CardField, unknown>)[field] = { ...card, status: "cancelled" };
+        } else {
+            (out as Record<CardField, unknown>)[field] = card;
+        }
+    }
+    return changed ? out : cards;
+};

package/src/chores/chores.ts

@@ -460,9 +460,12 @@ const testStrength: Chore = {
     criterion: `Stryker's mutation score for the repo is under ${MUTATION_FLOOR}%.`,
     stance: `act`,
     needs: [`mutation`],
-    // Quarterly rather than monthly: a mutation score moves when tests are rewritten, which is not a weekly event,
-    // and the probe behind it is the most expensive one here.
-    cadenceMs: 90 * DAY_MS,
+    /* Weekly. This was quarterly on the reasoning that a mutation score moves when tests are rewritten and that
+     * is not a weekly event; on 2026-08-31 agents rewrote about 180 test files in an afternoon, and the score is
+     * exactly the number that should have said so. The probe is still the most expensive one here, and
+     * `--incremental` is what makes a weekly cadence affordable: the first run costs a full run, every one after it
+     * costs the mutants whose code or tests changed. */
+    cadenceMs: 7 * DAY_MS,
     assess: (context) => {
         const facts = factsOf(context, `mutation`);
         if (facts === undefined || facts.mutation.score >= MUTATION_FLOOR) {

package/src/command-classes.test.ts

@@ -198,6 +198,31 @@ describe("secrets.access", () => {
         }
     });
 
+    /* A SEARCH PATTERN IS NOT A PATH, and the escaped dot is why this needed saying: `process.env` is excluded
+     * by the dotenv pattern's own lookbehind, and `process\.env` — the same thing typed into a grep — walked
+     * straight past it, because the character before `.env` is then a backslash rather than the `s`. Grepping
+     * this workspace for its own env reads was one of the commonest cards the class raised. */
+    test("a credential-shaped name inside a regex is a pattern, not a file", () => {
+        for (const command of [
+            String.raw`rg -n 'process\.env\.(INTENTIC_[A-Z]+|GITHUB_[A-Z]+)\b' --type ts .`,
+            String.raw`rg -o 'process\.env\.\w+' . | sort -u`,
+            String.raw`grep -rn '\.npmrc' .`,
+            String.raw`rg '\.ssh/id_ed25519' -l`,
+            String.raw`rg -n '\.env\b' -g '!*.md' .`,
+        ]) {
+            expect(classifyCommand(command), command).not.toContain("secrets.access");
+        }
+    });
+
+    /* THE ONE PATH THAT SPELLS `\.` AND IS A PATH. The machine agent's shell runs on somebody's Windows laptop,
+     * where the backslash is the separator, so the rule above must not read a real credential read as a regex:
+     * a separator is followed by a path segment, an escape by the character it escapes. */
+    test("a windows path keeps the class", () => {
+        for (const command of [String.raw`type C:\Users\me\.env`, String.raw`copy %USERPROFILE%\.ssh\id_rsa \tmp`]) {
+            expect(classifyCommand(command), command).toContain("secrets.access");
+        }
+    });
+
     /* Carrying a reference IS reading the credential: it becomes the value on the way into the process, so a
      * command holding one belongs in this class however it is spelled. Otherwise the outside-content floor in
      * actions.ts is bypassed by the shorter route to the same place, writing `{{secret:X}}` into a curl rather

package/src/command-classes.ts

@@ -20,6 +20,14 @@ import { type CommandClass, CommandClassSchema } from "./schemas/agent.js";
  * boundary, the boundaries are structural and elsewhere: the container, the isolated worktree, the land gate,
  * an automation's tool allowlist, and, on somebody's own computer, the scope switches enforced there.
  *
+ * WHICH IS WHY THIS NO LONGER DECIDES ANYTHING. A match used to BE the verdict: whatever fired here became the
+ * permission card, so `echo "rm -rf /"`, `rg 'rm -rf'` and an actual delete were one question with one answer.
+ * Now a match only means A JUDGE SHOULD LOOK (safety-policy.ts argues the move at length, guard/command-gate.ts
+ * implements it), and the judge reads the owner's written policy plus what the daemon knows about the turn.
+ * That changes what these patterns should optimise for: being OVER-inclusive is close to free, because a false
+ * positive now costs one model call rather than one interruption, and a miss still costs everything. Anyone
+ * tuning a pattern below should widen rather than narrow it.
+ *
  * Matching is deliberately UNANCHORED, substrings, not line starts. Another PreToolUse hook may have rewrapped
  * the command by the time this reads it (agent-terminals.ts wraps every Bash call in bin/tmux-run), and the
  * agent's own line survives verbatim inside that wrapper. Nothing the wrapper adds is in any class below.
@@ -414,6 +422,36 @@ const enclosingPath = (command: string, span: CommandSpan): string => {
         .replace(/^[@<>=]+/, "");
 };
 
+/* A WORD THAT IS A PATTERN RATHER THAN A PATH, dropped before the table's guess about a FILE is believed at all.
+ *
+ * The table reads shell text looking for filenames, and a search command carries something that looks exactly
+ * like one and is not: `rg 'process\.env\.(INTENTIC_[A-Z]+)' --type ts .` names no file and opens nothing, and
+ * it earned a card reading "this command would read credential material" over a grep of this workspace's own
+ * source. The `.env` in it survives the dotenv pattern's `process.env` exclusion for one reason: the lookbehind
+ * sees the REGEX'S BACKSLASH rather than the `s` of `process`, and a backslash is neither a word character nor a
+ * dot. Every credential-shaped name has the same hole — `rg '\.npmrc'`, `rg '\.ssh/id_ed25519'` — so it is fixed
+ * once here rather than seven times in the table.
+ *
+ * THE ESCAPED DOT IS THE TELL. `\.` is how a regex spells a literal dot, and a POSIX path never needs it. The
+ * one thing that spells `\.` and IS a path is Windows (`type C:\Users\me\.env`), which the machine agent's shell
+ * really does see — and there the other backslashes are SEPARATORS, each followed by a path segment rather than
+ * by the character it escapes. That is the whole discrimination.
+ *
+ * A CHARACTER CLASS and a CLASS ESCAPE are the other two tells, and both are nearly free: `[…]` is legal in a
+ * filename and never in one anybody writes, and `\w`, `\d`, `\b` mean nothing to a shell. The class escapes are
+ * matched only where a word character does NOT follow, which is what keeps `\dev` and `\swap` (Windows
+ * directories) out of them. The word edges (WORD_EDGE) already cut a word at the `(`, `|` and quotes carrying
+ * the rest of a regex's syntax, so these are what is left of it by the time a word reaches here.
+ *
+ * Judged on the ENCLOSING WORD, the same word the fact-check would have asked the filesystem about, so a
+ * pattern and a path are told apart once and both consults see the same answer. */
+const CHARACTER_CLASS = /\[[^\]]*\]/;
+const CLASS_ESCAPE = /\\[wdsbWDSB](?!\w)/;
+const ESCAPED_DOT = /\\\./;
+const PATH_SEPARATOR = /\\\w/;
+const namesAPattern = (word: string): boolean =>
+    CHARACTER_CLASS.test(word) || CLASS_ESCAPE.test(word) || (ESCAPED_DOT.test(word) && !PATH_SEPARATOR.test(word));
+
 /* WHERE A COMMAND READS CREDENTIAL MATERIAL: every secret reference in it, plus every credential-shaped path the
  * context did not positively clear.
  *
@@ -422,7 +460,10 @@ const enclosingPath = (command: string, span: CommandSpan): string => {
  * class would evaporate on every caller without a filesystem. */
 const credentialReads = (command: string, context: CommandContext | undefined): CommandSpan[] => [
     ...spansOf(SECRET_REFERENCES_G, command),
-    ...spansOf(CREDENTIAL_PATHS_G, command).filter((span) => context?.holdsSecret?.(enclosingPath(command, span)) !== false),
+    ...spansOf(CREDENTIAL_PATHS_G, command).filter((span) => {
+        const word = enclosingPath(command, span);
+        return !namesAPattern(word) && context?.holdsSecret?.(word) !== false;
+    }),
 ];
 
 // WHERE each class fires, one entry per class. Empty ⇒ the command is not in it, so membership and evidence are
@@ -462,7 +503,8 @@ export const COMMAND_CLASS_LABELS: Readonly<Record<CommandClass, string>> = {
     "network.outbound": "send a request out to the internet",
 };
 
-/* THE CLASSES THE DAEMON HOLDS WHERE THE OWNER WROTE NO RULE, and the machine agent refuses without its own
- * switch. Named here rather than at either consult, so "which commands are dangerous enough to stop by
- * default" has one answer that both enforcement points read. */
-export const FLOOR_CLASSES: ReadonlySet<CommandClass> = new Set<CommandClass>(["system.destructive"]);
+/* No verdict set lives here any more. Which classes are worth stopping for is a POLICY question now, and it is
+ * answered in two places that are honest about being different: safety-policy.ts's HARD_RULE_CLASSES for the
+ * one thing nothing recovers, and the owner's own written policy for everything else. The machine agent keeps
+ * its own set beside its scope switches (machine/src/computer/tools/shell.ts), because "which commands need
+ * the destructive switch" is a question about that capability card rather than about this catalog. */

package/src/command-run.ts

@@ -0,0 +1,78 @@
+import type { CommandRun } from "./schemas/ci.js";
+
+/* THE HEADING OVER A SETTLED RUN, three or four words, because it is read at a glance and from across a view
+ * the user may have walked back into, and because it is read in TWO places that must agree: the card the app
+ * floats over the workspace, and the notification the daemon sends to a phone when the user is not there to
+ * see the card. Two copies of these words drifted once ("Checks failed" on the card, "Check failed" on the
+ * phone), which is the whole reason the sentence lives in the package both sides already share.
+ *
+ * `subject` is what ran, in the words the button used: "Checks" for the pre-push check, "Push" for the push,
+ * and the verb the user actually clicked ("Publish", "Sync") where the flow knows it. `passed` is included
+ * for totality; no card is raised for it, a pass sends the push and says so where the click was. */
+export interface FollowRunOptions<R extends CommandRun> {
+    // The wait between "is it done yet" questions.
+    readonly intervalMs: number;
+    // Stop following: the caller has moved on. Resolves undefined rather than throwing, the run itself is
+    // still going wherever it was, and nobody here has anything to report about it.
+    readonly signal?: AbortSignal | undefined;
+    // Every state read, settled or not, for a surface that draws progress (the terminal to open, the command).
+    readonly onState?: ((run: R) => void) | undefined;
+    // A poll that could not be read. NOT the run failing: it is still going on the daemon, and the next tick
+    // usually reconnects, so following continues; the caller decides what to show meanwhile.
+    readonly onError?: ((cause: unknown) => void) | undefined;
+}
+
+const sleep = (ms: number, signal: AbortSignal | undefined): Promise<void> =>
+    new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done(): void {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+
+/* FOLLOW A RUN TO ITS VERDICT: read its state until it is no longer running, and answer with the settled run.
+ * The one loop under every surface that starts a command and waits for the answer, the web's run watcher and
+ * an extension's push pill alike, because a daemon that answers "started" at once (prepush.contract.ts,
+ * git.contract.ts push) leaves every caller to write this loop, and each one that did wrote the dropped-poll
+ * case differently. Reads once immediately, so a run that has already settled is answered without a wait. */
+export const followCommandRun = async <R extends CommandRun>(read: () => Promise<R>, options: FollowRunOptions<R>): Promise<R | undefined> => {
+    const { intervalMs, signal, onState, onError } = options;
+    for (;;) {
+        if (signal?.aborted === true) {
+            return undefined;
+        }
+        try {
+            const run = await read();
+            onState?.(run);
+            if (run.status !== "running") {
+                return run;
+            }
+        } catch (cause) {
+            onError?.(cause);
+        }
+        await sleep(intervalMs, signal);
+    }
+};
+
+export const commandRunOutcome = (run: Pick<CommandRun, "status" | "timedOut">, subject: string): string => {
+    if (run.timedOut === true) {
+        return `${subject} timed out`;
+    }
+    switch (run.status) {
+        case "error":
+            return `${subject} couldn't run`;
+        case "cancelled":
+            return `${subject} stopped`;
+        case "failed":
+            return `${subject} failed`;
+        case "passed":
+            return `${subject} passed`;
+        default:
+            // `idle` reaches a card only when the command was cleared between the click and the request, there
+            // is no run any more, so it says so rather than implying one ran and said nothing.
+            return `${subject} didn't run`;
+    }
+};

package/src/contract-lock.test.ts

@@ -5,7 +5,7 @@ import { currentLock } from "./contract-lock.js";
 /* The committed lock and the code must say the same thing: see contract-lock.ts for what the pair buys.
  *
  * This is the HALF that runs everywhere the tests run; the other half (a shrunk lock needs a declared break)
- * lives in prepass.mjs, which has git and this suite does not.
+ * lives in _tools/checks/contract-shrink.mjs, which has git and this suite does not.
  *
  * ITS OWN BUDGET, because the default one is a HANG DETECTOR and this test does real work: it serializes every
  * schema this package exports, ~500 of them, to JSON Schema. That is ~100ms with the machine to itself and it

package/src/contract-lock.ts

@@ -4,7 +4,7 @@
  *
  * Two readers depend on that answer. contract-lock.test.ts fails whenever the committed file is out of step
  * with the code, so a contract change always lands WITH its lock diff, visible in review, attributable to a
- * commit. And prepass.mjs (invariant 6) compares the committed lock against its merge-base to insist that a
+ * commit. And the contract-shrink check (_tools/checks/) compares the committed lock against its merge-base to insist that a
  * SHRUNK surface, a schema or field removed, a type changed, arrives as a `!` commit carrying a
  * `Breaking-Note:` trailer, which is what feeds the release's "Breaking changes" section and the update card's
  * warning. Additions pass freely; every persisted-manifest reader parses loosely, so growth breaks nobody.
@@ -58,7 +58,7 @@ export const currentLock = (): Record<string, unknown> => {
 /* ONE LINE PER SCHEMA, on purpose, not JSON.stringify(lock, null, 4). Pretty-printed, the lock is a 35k-line
  * wall nobody scrolls; a line per export keeps it ~500 lines and makes `git diff` read as the list of WHICH
  * surfaces moved, which is the level a reviewer reviews at. The path-level detail lives in the tooling: the
- * lock test diffs parsed objects and prepass invariant 6 names the exact removed paths, so nothing is lost by
+ * lock test diffs parsed objects and the contract-shrink check names the exact removed paths, so nothing is lost by
  * not laying the structure out vertically. */
 export const serializeLock = (lock: Record<string, unknown>): string =>
     `{\n${Object.entries(lock)