@intentic/sandbox-contract 1.240.0 → 1.242.0

package/src/contracts/agents.contract.ts

@@ -9,6 +9,7 @@ import {
     AgentLandSchema,
     AgentPlaceSchema,
     AgentRenameSchema,
+    AgentResumeAfterLimitSchema,
     AgentResumeAfterOutageSchema,
     AgentsArchivedSchema,
     AgentSearchQuerySchema,
@@ -19,7 +20,7 @@ import {
     LandResultSchema,
 } from "../schemas/agents.js";
 import { AgentsListSchema } from "../schemas/automations.js";
-import { AgentChangesSchema } from "../schemas/git.js";
+import { AgentChangesSchema, AgentHistorySchema } from "../schemas/git.js";
 import { FileDiffSchema } from "../schemas/history.js";
 import { OkSchema } from "../schemas/shared.js";
 
@@ -100,7 +101,7 @@ export const agentsContract = {
         .input(AgentIdSchema)
         .output(AgentTranscriptSchema),
     /* SPEAK AS THE AGENT, append the user's words to the conversation's record as an assistant row, with no
-     * turn behind them and no reply. The row is marked `placed` for human readers (RestoredMessageSchema); the
+     * turn behind them and no reply. The row is marked `placed` for human readers (TranscriptRowSchema); the
      * provider session is FORGOTTEN in the same breath, rewind-style, so the next real turn opens a fresh
      * runtime session seeded from the record, where the placed line reads as the agent's own words, because
      * the handoff renders every assistant row identically. A running turn is CONFLICT: the illusion can only be
@@ -155,6 +156,23 @@ export const agentsContract = {
         })
         .input(AgentResumeAfterOutageSchema)
         .output(AgentSummarySchema),
+    /* THIS conversation's answer to a spent allowance, the same override in the same shape as the outage one
+     * above; null clears it back to "inherit". Offered on the CARD as well as in the chat, which is the one
+     * placement difference worth stating: an outage is over in minutes and is met by whoever is in the room,
+     * while a limit reopens hours later, so the person deciding is usually looking at a board rather than at a
+     * transcript.
+     *
+     * Legal mid-turn, and for a workspace conversation, for the same two reasons its neighbour is. */
+    resumeAfterLimit: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/resume-after-limit",
+            summary: "Whether this conversation sends itself again when its allowance comes back",
+            description:
+                "Overrides the sandbox-wide setting for one conversation; clear it to follow the default again. Off unless asked for, because the allowance is the user's own budget and a turn that spends it the moment it reopens is not a decision to make on their behalf.",
+        })
+        .input(AgentResumeAfterLimitSchema)
+        .output(AgentSummarySchema),
     seen: oc
         .route({
             method: "POST",
@@ -204,6 +222,21 @@ export const agentsContract = {
         })
         .input(AgentIdSchema)
         .output(AgentChangesSchema),
+    // The other side of `diff`: the work that is no longer a difference because it is in your own history, and
+    // the commits holding it. Asked for only once `diff` reports something absorbed, since it costs a `git log`
+    // per repo and answers nothing until then. Reading one of these files is the SAME call as reading a
+    // reviewable one (`fileDiff` below): the question "what did this conversation do to this file" has one
+    // answer whether or not you have since committed it.
+    history: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}/history",
+            summary: "Where a conversation's committed work lives",
+            description:
+                "The commits in your own history that carry this conversation's work, with the files each one brought. Use it when the change list is empty or short because you already committed what it wrote: those files are not differences against the main line any more, so they are not in the review, and this is where they went.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentHistorySchema),
     fileDiff: oc
         .route({
             method: "GET",

package/src/contracts/approvals.contract.ts

@@ -0,0 +1,37 @@
+import { oc } from "@orpc/contract";
+import { ApprovalIdParamSchema, ApprovalsListSchema, ApprovalSummarySchema } from "../schemas/approvals.js";
+import { OkSchema } from "../schemas/shared.js";
+
+// The sandbox's approvals queue (things the agent prepared and may not do until the owner says yes). The agent
+// creates the files directly, these routes are the OWNER's side: `list` is the inbox, `upsert` covers approve /
+// edit / reschedule / retry (all a plain re-post with a field changed, like the automations enabled toggle),
+// `remove` is reject. The verbs are the same whatever the kind, which is the point of one queue.
+export const approvalsContract = {
+    list: oc
+        .route({
+            method: "GET",
+            path: "/approvals",
+            summary: "Things waiting for your yes",
+            description:
+                "Everything an agent has prepared and would like to do: posts to publish, actions to carry out. Nothing here has happened yet.",
+        })
+        .output(ApprovalsListSchema),
+    upsert: oc
+        .route({
+            method: "POST",
+            path: "/approvals",
+            summary: "Approve, edit or retry one",
+            description: "All three are the same act with a different field changed, so they share one call. Send the item back as you want it.",
+        })
+        .input(ApprovalSummarySchema)
+        .output(OkSchema),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/approvals/{id}",
+            summary: "Reject one",
+            description: "Throws it away undone.",
+        })
+        .input(ApprovalIdParamSchema)
+        .output(OkSchema),
+};

package/src/contracts/ci.contract.ts

@@ -5,7 +5,6 @@ import {
     CiJobsResponseSchema,
     CiRunParamSchema,
     CiRunsResponseSchema,
-    CiSeenResponseSchema,
 } from "../schemas/ci.js";
 import { OkSchema } from "../schemas/shared.js";
 
@@ -61,16 +60,4 @@ export const ciContract = {
         })
         .input(CiFixParamSchema)
         .output(CiFixResponseSchema),
-    // "I have looked at the pipelines", what silences the rail badge for breakages already read. No input:
-    // the surface is read as a whole, and the daemon stamps its own clock so a skewed browser can't mark
-    // future failures as already seen.
-    seen: oc
-        .route({
-            method: "POST",
-            path: "/ci/seen",
-            summary: "Mark the pipelines as read",
-            description:
-                "Silences the badge for breakages already looked at. Takes nothing, because the view is read as a whole, and the daemon stamps its own clock so a browser with the wrong time cannot mark future failures as already seen.",
-        })
-        .output(CiSeenResponseSchema),
 };

package/src/contracts/git.contract.ts

@@ -16,6 +16,7 @@ import {
     GitRemoteStateSchema,
     GitStageSchema,
     GitStatusSchema,
+    PushRunSchema,
     PushSchema,
 } from "../schemas/git.js";
 import {
@@ -452,16 +453,40 @@ export const gitContract = {
         })
         .input(RepoParamSchema)
         .output(GitActionResultSchema),
+    /* THE PUSH IS A RUN, the pre-push check's three verbs over again (prepush.contract.ts), for the same reason:
+     * a push runs the repository's own pre-push hook, which for a workspace with a real gate is the whole suite,
+     * and a request held open for minutes dies at the first proxy and at the browser's own header deadline. So
+     * `push` starts it and answers at once, `pushState` is polled for the verdict, and the output is a terminal
+     * the owner can watch. Addressed by repo, unlike the check: there is one working tree but many remotes. */
     push: oc
         .route({
             method: "POST",
             path: "/git/{repo}/push",
-            summary: "Send commits to the remote",
+            summary: "Start sending commits to the remote",
             description:
-                "Pushes the current branch, setting its upstream on first push. A rejected push, a missing remote and missing credentials all come back as reported outcomes rather than failures.",
+                "Starts pushing the current branch, setting its upstream on first push, and answers at once: the push runs in a real terminal (it runs this repository's pre-push hook, which can be a whole suite), so watch it there and poll pushState for the verdict. A second start while one is going joins it rather than pushing twice.",
         })
         .input(PushSchema)
-        .output(GitActionResultSchema),
+        .output(OkSchema),
+    pushState: oc
+        .route({
+            method: "GET",
+            path: "/git/{repo}/push",
+            summary: "How the push is going",
+            description:
+                "The verdict, or the progress so far: where it is, the terminal it runs in, and for a push that did not go, git's last words and who refused it, the repository's own pre-push hook, the remote, or the transport. Idle when nothing has been started for this repository.",
+        })
+        .input(RepoParamSchema)
+        .output(PushRunSchema),
+    pushCancel: oc
+        .route({
+            method: "POST",
+            path: "/git/{repo}/push/cancel",
+            summary: "Stop the push",
+            description: "Kills the run. It settles as cancelled; nothing that git had not already sent reaches the remote.",
+        })
+        .input(RepoParamSchema)
+        .output(OkSchema),
     files: oc
         .route({
             method: "GET",

package/src/contracts/keys.contract.ts

@@ -0,0 +1,79 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { KeyProviderParamSchema } from "../schemas/agent.js";
+import { AccountIdSchema, AccountRenameSchema, OauthAccountListSchema, OauthAccountSchema } from "../schemas/provider-oauth.js";
+import { OkSchema } from "../schemas/shared.js";
+
+/* THE PROVIDERS YOU CONNECT BY PASTING A KEY (Sandbox ▸ Agent), on four routes with the provider as a PARAMETER
+ * rather than four routes each.
+ *
+ * The lesson providers.contract.ts already learned about model catalogs: five identical route files differing
+ * only in a name is a shape that costs a vertical slice through the contract, the router, the service container
+ * and every test double every time a provider is added. Here the providers genuinely are identical — a keyed
+ * provider is a base URL, a catalog URL and a store — so the id is a parameter and adding one is a spec row.
+ *
+ * WHY NOT THE OAUTH ROUTES. Claude and Cursor connect through a handshake this daemon runs: a `start` that
+ * returns something to open and an `exchange`/poll that completes it. There is no handshake here at all — the
+ * user already has the credential and hands it over — so `connect` takes the key and answers with the account
+ * it became. Sharing a route family with the OAuth providers would have meant a `start` that returns nothing
+ * and an `exchange` whose "code" is really a secret, which is a worse lie than two families.
+ *
+ * WHY NOT THE TRANSLATOR ROUTES. Those address subscriptions CLIProxyAPI holds; these credentials live in this
+ * daemon's own auth tree, and a disconnect here removes a file rather than asking a proxy to forget one.
+ *
+ * THE PATHS MIRROR THE OAUTH PROVIDERS' (`<base>/accounts`, `<base>/account/rename`,
+ * `<base>/account/disconnect`) with `/keys/<provider>` as the base, so the browser's account helpers reach
+ * these rows with the same three URLs they already build for Claude, Grok and Cursor. Only `connect`
+ * differs, because only `connect` is a different act.
+ *
+ * THE KEY TRAVELS IN, NEVER OUT. `connect` takes it and every answer on this contract is an OauthAccount, whose
+ * shape has no field a credential could ride in — which is what makes "does this leak the key" a question you
+ * answer by reading the schema instead of the handler. */
+export const keysContract = {
+    accounts: oc
+        .route({
+            method: "GET",
+            path: "/keys/{provider}/accounts",
+            summary: "Connected accounts for a key-based provider",
+            description: "Which keys are connected for this provider. The keys themselves never travel: being in this list is what connected means.",
+        })
+        .input(KeyProviderParamSchema)
+        .output(OauthAccountListSchema),
+    connect: oc
+        .route({
+            method: "POST",
+            path: "/keys/{provider}/connect",
+            summary: "Connect an API key",
+            description:
+                "Stores an API key for this provider and answers with the account it became. A sandbox can hold several keys for one provider side by side.",
+        })
+        .input(
+            KeyProviderParamSchema.extend({
+                apiKey: z.string().min(1).describe("The key, as the provider issued it. Stored in this sandbox and never sent back out."),
+                label: z
+                    .string()
+                    .max(80)
+                    .optional()
+                    .describe("What to call it. Blank falls back to the provider's own name, which is all a pasted key can say about itself."),
+            }),
+        )
+        .output(OauthAccountSchema),
+    rename: oc
+        .route({
+            method: "POST",
+            path: "/keys/{provider}/account/rename",
+            summary: "Rename one connected key",
+            description: "Nothing in a pasted key says whose it is, so naming it is the only way to tell two of them apart.",
+        })
+        .input(KeyProviderParamSchema.extend(AccountRenameSchema.shape))
+        .output(OkSchema),
+    disconnect: oc
+        .route({
+            method: "POST",
+            path: "/keys/{provider}/account/disconnect",
+            summary: "Disconnect one key",
+            description: "Removes a single stored key. Any others under the same provider stay connected.",
+        })
+        .input(KeyProviderParamSchema.extend(AccountIdSchema.shape))
+        .output(OkSchema),
+};

package/src/contracts/prepush.contract.ts

@@ -1,9 +1,9 @@
 import { oc } from "@orpc/contract";
-import { PrepushRunSchema } from "../schemas/ci.js";
+import { CommandRunSchema } from "../schemas/ci.js";
 import { OkSchema } from "../schemas/shared.js";
 
 // The pre-push check, the command the workspace runs when the user pushes, before anything leaves the machine
-// (see PrepushRunSchema for where this sits and why). Three verbs about ONE run: the check answers about the
+// (see CommandRunSchema for where this sits and why). Three verbs about ONE run: the check answers about the
 // main working tree, of which there is exactly one, so nothing here is addressed by id.
 //
 // `run` starts the check and returns immediately, a suite takes minutes, and an oRPC call held open for one
@@ -20,7 +20,7 @@ export const prepushContract = {
             description:
                 "The verdict, or the progress so far. Nothing is addressed by id here, because there is one working tree and so exactly one check.",
         })
-        .output(PrepushRunSchema),
+        .output(CommandRunSchema),
     run: oc
         .route({
             method: "POST",

package/src/contracts/safety.contract.ts

@@ -0,0 +1,48 @@
+import { oc } from "@orpc/contract";
+import { SafetyLogEntrySchema, SafetyPolicySchema } from "../safety-policy.js";
+import { OkSchema } from "../schemas/shared.js";
+import { z } from "zod";
+
+/* The owner's safety policy (.intentic/config/safety.md) and the log of what it decided.
+ *
+ * ITS OWN ROUTES RATHER THAN A FIELD ON /settings, and the split is the same one `rule-firings` already draws
+ * next door: the policy is a DOCUMENT edited at human speed, and the log is a value that changes on its own
+ * several times a turn. Folding either into the settings object would put a self-changing value inside the
+ * thing a screen optimistically patches, and would make every judged command a settings write.
+ *
+ * The policy is also the only config file here whose reader is a model rather than a parser, so it travels as
+ * text and is never parsed on the way through: whatever the owner wrote is what the judge reads.
+ */
+export const safetyContract = {
+    policy: oc
+        .route({
+            method: "GET",
+            path: "/safety/policy",
+            summary: "The safety policy this sandbox is judged against",
+            description:
+                "The document that decides when an agent stops to ask you before running something. Prose, not settings: it is read by the model that judges each command. When nobody has written one, this is the text the product ships with, and it describes the behaviour a fresh sandbox already has.",
+        })
+        .output(SafetyPolicySchema),
+    setPolicy: oc
+        .route({
+            method: "POST",
+            path: "/safety/policy",
+            summary: "Rewrite the safety policy",
+            description:
+                "Replaces the document whole. Nothing in it can widen what the sandbox is structurally allowed to do: it decides which of the things an agent may already do are worth interrupting you about.",
+        })
+        .input(z.object({ text: z.string().describe("The policy, as you want it written.") }))
+        .output(OkSchema),
+    // What the policy actually did, newest first. The half of the Safety page that makes the other half
+    // writable: nobody can author a policy for behaviour they cannot see, and a column of verdicts is what
+    // teaches an owner which line to add next.
+    log: oc
+        .route({
+            method: "GET",
+            path: "/safety/log",
+            summary: "Recent safety verdicts",
+            description:
+                "What was judged lately, what the judge decided, and whether you were interrupted. Newest first. This is where you find out why you were not asked about something, which is the question a policy page otherwise cannot answer.",
+        })
+        .output(z.array(SafetyLogEntrySchema)),
+};

package/src/contracts/usage.contract.ts

@@ -1,6 +1,15 @@
 import { oc } from "@orpc/contract";
+import { z } from "zod";
 import { DayWindowQuerySchema, UsageRollupSchema } from "../schemas/usage.js";
 
+// The one control over the headroom readings a person has: measure again, now, every connection. `force`
+// ignores the freshness the daemon otherwise honours (a reading from the last minute is what the provider
+// would answer again), because the person pressing it has just changed something about an account and is
+// asking whether what they can see survived it.
+export const RefreshPlanLimitsSchema = z.object({
+    force: z.boolean().default(false).describe("Measure again even if a reading was taken a moment ago."),
+});
+
 // The durable spend ledger (see UsageTurnSchema). Read-only over the wire, rows are appended daemon-side at
 // turn end, so the ledger stays a trustworthy record of what was actually spent, the same principle as the
 // activity log. `rollup` serves every cost/usage panel: it groups by day × provider × account × model, and the
@@ -16,4 +25,17 @@ export const usageContract = {
         })
         .input(DayWindowQuerySchema)
         .output(UsageRollupSchema),
+    // Not the ledger's business, but the same tab: the plan-limit readings behind every ring, re-measured on
+    // request for every provider at once. The readings themselves arrive on /events as they land, and on the
+    // account lists afterwards; this answers once the sweep is done or its deadline passes.
+    refreshPlanLimits: oc
+        .route({
+            method: "POST",
+            path: "/usage/plan-limits/refresh",
+            summary: "Measure every account's plan limits again",
+            description:
+                "Reads how full each connected account's plan limits are, for every provider, and records it. Forced, it measures even accounts read a moment ago, which is the right thing when a plan was just changed and the question is whether the number on screen is still true.",
+        })
+        .input(RefreshPlanLimitsSchema)
+        .output(z.object({ ok: z.literal(true) })),
 };

package/src/conversation-ids.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, expect, test, vi } from "vitest";
-import { newConversationId } from "./conversation-ids.js";
+import { CI_FIX_PREFIX, ciFixConversationId, newConversationId } from "./conversation-ids.js";
 import { ConversationIdSchema } from "./schemas/agent.js";
 
 const mockRandomValues = (values: readonly number[]) => {
@@ -59,3 +59,33 @@ test("ids are unique across a burst", () => {
     const ids = new Set(Array.from({ length: 5_000 }, newConversationId));
     expect(ids.size).toBe(5_000);
 });
+
+// The whole point of the derived id: the same failure names the same conversation, forever, from any browser.
+test("a CI fix id is the same string every time it is derived", () => {
+    expect(ciFixConversationId(`web`, 4213)).toBe(`ci-fix-web-4213`);
+    expect(ciFixConversationId(`web`, 4213)).toBe(ciFixConversationId(`web`, 4213));
+});
+
+// A run id belongs to one forge project, not to the workspace: without the repo, two repos' run 42 would share
+// an agent, and the second failure would be answered by the first one's conversation.
+test("two repos with the same run number get different conversations", () => {
+    expect(ciFixConversationId(`web`, 42)).not.toBe(ciFixConversationId(`api`, 42));
+});
+
+// The id becomes a branch and a path, so the guard is not a matter of taste. Held over the repo names a
+// workspace can actually produce: nested dirs, dots, spaces, punctuation, and something that slugs to nothing.
+test("every derived id passes the conversation-id guard", () => {
+    const repos = [`root`, `web`, `apps/web`, `my repo`, `.dotted`, `UPPER_Case`, `___`, `x`.repeat(80)];
+    for (const repo of repos) {
+        for (const runId of [1, 42, 18_446_744_073]) {
+            const id = ciFixConversationId(repo, runId);
+            expect(ConversationIdSchema.safeParse(id).success).toBe(true);
+            expect(id.startsWith(CI_FIX_PREFIX)).toBe(true);
+        }
+    }
+});
+
+// The join is a prefix scan over the fleet, so the prefix has to survive a repo name that starts with one.
+test("the prefix is carried by every fix id", () => {
+    expect(ciFixConversationId(`ci-fix`, 7)).toBe(`ci-fix-ci-fix-7`);
+});

package/src/conversation-ids.ts

@@ -25,9 +25,9 @@
  * is not a matter of taste; the test beside it holds the whole generated space to it.
  *
  * Conversations the SANDBOX starts keep their own minters and their own prefixes (an automation's fire is
- * `a-<automation>-<time>`, a CI fix is minted from the run), those names say WHERE the conversation came
- * from, which beats a random pair for a card the user did not ask for. This is the default for the ones a
- * person opens.
+ * `a-<automation>-<time>`, a CI fix is DERIVED from the run it fixes, see below), those names say WHERE the
+ * conversation came from, which beats a random pair for a card the user did not ask for. This is the default
+ * for the ones a person opens.
  */
 
 /* The two halves of the name. Kept short (nothing over seven letters) because the whole point is a string that
@@ -171,3 +171,37 @@ const tail = (): string => Array.from({ length: TAIL_LENGTH }, () => randomBelow
 /* A fresh conversation id: `<adjective>-<noun>-<tail>`, e.g. `swift-otter-k9m2`. Sixteen characters or so
  * against a UUID's thirty-six, and the first eleven of them are the ones a person reads. */
 export const newConversationId = (): string => `${pick(ADJECTIVES)}-${pick(NOUNS)}-${tail()}`;
+
+/* WHAT A CI FIX CONVERSATION IS CALLED, and the one id in this file that is DERIVED rather than drawn.
+ *
+ * It is derived because the question "has anybody already put an agent on this failure?" has to be answerable
+ * from the failure alone. Nothing records that anywhere: the fleet roster IS the record (the conversation, its
+ * worktree, its branch, its live status), and a roster is keyed by id, so an id nothing can re-compute is a
+ * record nothing can read. This one used to carry a timestamp and a per-process counter, which made every fix
+ * unfindable the moment the click was over: the board could offer "Fix with agent" and nothing else, forever,
+ * however many agents were already working on the row.
+ *
+ * Deriving it settles a second question the same way. One failed run is now one conversation, so a second press
+ * (from another tab, or from a reader who did not scroll to the state) CONTINUES the fix rather than starting a
+ * rival agent on a rival branch: the daemon refuses while the turn is live, and adds a turn to the same session
+ * once it is not. The old recipe made a fresh worktree every time.
+ *
+ * THE REPOSITORY IS IN IT because a run id belongs to one forge project, not to the workspace: two repos can
+ * each have a run 42, and without the repo their failures would share a conversation. It is slugified rather
+ * than hashed because this string is read by people, in `git branch` (`agent/ci-fix-web-4213`), in a path and
+ * on a card, and `ci-fix-a3f91c-4213` answers the join just as well while saying nothing. Two repositories
+ * whose names agree for the first REPO_SLUG_MAX characters share a slug, and would then share a fix
+ * conversation for identically-numbered runs, a pairing rare enough to prefer the readable name over guarding
+ * against it.
+ */
+export const CI_FIX_PREFIX = "ci-fix-";
+// Leaves ~24 characters for the run id inside ConversationIdSchema's 64, which is twice the widest id either
+// forge mints.
+const REPO_SLUG_MAX = 32;
+const repoSlug = (repo: string): string =>
+    repo
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .slice(0, REPO_SLUG_MAX)
+        .replace(/^-+|-+$/g, "") || "repo";
+export const ciFixConversationId = (repo: string, runId: number): string => `${CI_FIX_PREFIX}${repoSlug(repo)}-${runId}`;

package/src/credential-material.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { holdsCredentialMaterial } from "./credential-material.js";
+import { holdsCredentialMaterial, maskCredentialMaterial } 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
@@ -118,3 +118,71 @@ describe("files that do not", () => {
         expect(holdsCredentialMaterial("API=http://localhost:8080/v1\nSENTRY_DSN=https://abc123@o1.ingest.sentry.io/1\n")).toBe(false);
     });
 });
+
+/* THE SAME TABLE APPLIED, and the property that matters is the one about what SURVIVES: this runs over the
+ * files an agent legitimately opens and edits, so a mask that takes the structure with it costs the work rather
+ * than protecting it. Every case below asserts both halves — the value is gone, the file is still readable. */
+describe("masking what a credential file holds", () => {
+    test("a dotenv keeps its keys, its shape and its comments", () => {
+        const masked = maskCredentialMaterial(
+            ["# staging", "PORT=3000", "NODE_ENV=production", 'STRIPE_SECRET="sk_live_51H8xQzRvKpLmNbTy"', "MAX_TOKENS=8192"].join("\n"),
+        );
+        expect(masked).toBe(["# staging", "PORT=3000", "NODE_ENV=production", 'STRIPE_SECRET="***"', "MAX_TOKENS=8192"].join("\n"));
+    });
+
+    /* THE ROUND TRIP THE WHOLE THING RESTS ON. A deferred value holds no credential and is the one thing a
+     * rewritten file must come back with intact: masking `{{secret:X}}` would have the model paste `***` over
+     * this workspace's own convention for a file that must not hold a credential. */
+    test("a placeholder and a secret reference come back untouched", () => {
+        const template = ["GITHUB_TOKEN=", "NPM_TOKEN=${NPM_TOKEN}", "API_KEY=<your-api-key>", "STRIPE_SECRET={{secret:STRIPE}}"].join("\n");
+        expect(maskCredentialMaterial(template)).toBe(template);
+    });
+
+    test("a private key keeps the lines that say what it is", () => {
+        const masked = maskCredentialMaterial("-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAA\n-----END OPENSSH PRIVATE KEY-----\n");
+        expect(masked).toBe("-----BEGIN OPENSSH PRIVATE KEY-----\n***\n-----END OPENSSH PRIVATE KEY-----\n");
+    });
+
+    // A connection string with the host blanked is one nobody can debug, and the host is not the secret.
+    test("a url keeps everything but the password", () => {
+        expect(maskCredentialMaterial("DATABASE_URL=postgres://app:Rk29fPqz@db.internal:5432/app\n")).toBe(
+            "DATABASE_URL=postgres://app:***@db.internal:5432/app\n",
+        );
+    });
+
+    // No key names these, and none is needed: the issuer is in the token.
+    test("an issued token goes wherever it appears", () => {
+        expect(maskCredentialMaterial("gh auth: ghp_16C7e42F292c6912E7710c838347Ae178B4a expired")).toBe("gh auth: *** expired");
+        expect(maskCredentialMaterial("//registry.npmjs.org/:_authToken=npm_wCq3nTvR8xLm2ZbKp7HdJyE4sUaF6gN0iQ1t")).toBe(
+            "//registry.npmjs.org/:_authToken=***",
+        );
+    });
+
+    /* WHAT IT MUST NOT TOUCH, the other half of the bargain: this pass only ever runs over a result whose input
+     * named a credential file, and such a file is still mostly configuration the model has to read. */
+    test("the ordinary contents of a config file survive", () => {
+        for (const text of [
+            "registry=https://registry.npmjs.org/\nengine-strict=true\n",
+            "TOKEN_EXPIRY=3600\nMAX_TOKENS=8192\nREFRESH_TOKEN_URL=https://auth.example.com/refresh\n",
+            "Host github.com\n  User git\n  IdentityFile ~/.ssh/id_ed25519\n",
+            "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH1x radarsu@omen\n",
+            "POSTGRES_PASSWORD=dev\n",
+        ]) {
+            expect(maskCredentialMaterial(text), text.slice(0, 30)).toBe(text);
+        }
+    });
+
+    // The point of the pass, stated as the property the gate now depends on: what comes back holds nothing.
+    test("what comes back no longer holds credential material", () => {
+        for (const text of [
+            "//registry.npmjs.org/:_authToken=npm_wCq3nTvR8xLm2ZbKp7HdJyE4sUaF6gN0iQ1t\n",
+            "[default]\naws_access_key_id = AKIAIOSFODNN7EXAMPLE\naws_secret_access_key = wJalrXUtnFEMI/K7MDENG\n",
+            '{"accessToken":"ya29.a0AfB_bJq2Lm","expiresAt":1767000000}',
+            "PORT=3000\nSTRIPE_SECRET=sk_live_51H8xQzRvKpLmNbTy\n",
+            "https://radarsu:ghp_S8kQ2mVx@github.com\n",
+        ]) {
+            expect(holdsCredentialMaterial(text), `${text.slice(0, 30)} before`).toBe(true);
+            expect(holdsCredentialMaterial(maskCredentialMaterial(text)), `${text.slice(0, 30)} after`).toBe(false);
+        }
+    });
+});