@intentic/sandbox-contract 1.233.0 → 1.234.0

package/src/schemas/maintenance.ts

@@ -13,7 +13,7 @@ import { WorkspaceHotspotSchema, WorkspaceKeyModuleSchema } from "./codebase-hea
  *   signals  things the daemon already knows, the resident iq index's health ranking, the package manifests it
  *            reads for the dependency graph, its own node version. Recomputed per request; all of it is cheap. */
 
-export const PROBE_IDS = ["outdated", "audit", "knip", "jscpd", "ui", "bundle"] as const;
+export const PROBE_IDS = ["outdated", "audit", "knip", "jscpd", "ui", "bundle", "mutation"] as const;
 export const ProbeIdSchema = z.enum(PROBE_IDS);
 export type ProbeId = z.infer<typeof ProbeIdSchema>;
 // One dependency the registry has moved past. `kind` is the SEMVER distance, which is the whole reason this is
@@ -165,6 +165,55 @@ export const BundleSchema = z.object({
         .describe("What is in it, piece by piece."),
 });
 export type Bundle = z.infer<typeof BundleSchema>;
+/* WHAT THE SUITE WOULD NOTICE IF THE CODE BROKE. Coverage says a line ran; this says an assertion depended on it.
+ *
+ * The distinction is the whole reason this probe exists, and it is not theoretical here. Measured on
+ * sandbox-contract's chore module — 109 hand-written tests, every line covered — 16 of 58 mutants survived, and
+ * one of them flips the zero boundary in `bucketOf` that digest.ts's own comment argues is load-bearing. The test
+ * that was supposed to hold it (`expect(bucketOf(0)).not.toBe(bucketOf(1))`) is written in the careful,
+ * deliberately un-brittle style, and that is exactly why it cannot see the change: with the boundary moved the two
+ * values are still different, so the assertion still passes.
+ *
+ * That is the failure this measures and nothing else in the repository can. A linter sees the assertion's shape,
+ * not its power; a coverage report sees the line, not whether anything checked it. Only killing the code and
+ * watching what the suite says distinguishes a test from a test-shaped thing.
+ *
+ * SURVIVORS, NOT JUST A SCORE. A percentage is a mood; `bucketOf: count <= 0 → count < 0 survives` is a morning's
+ * work with the answer already in it. The score decides whether the chore speaks, the survivors are what makes it
+ * worth speaking about. */
+export const MutationScoreSchema = z.object({
+    score: z
+        .number()
+        .describe("The share of injected faults the suite caught. Not a coverage figure: coverage says a line ran, this says an assertion depended on it."),
+    killed: z.number().int().nonnegative().describe("Faults the suite caught."),
+    survived: z.number().int().nonnegative().describe("Faults it did not: code that can be broken with every test still green."),
+    /* Mutants that never got a verdict: ones that would not compile, and ones the configuration ignored. Kept
+     * apart from both counts above, and OUT of the score, because an unmeasured mutant is not evidence either
+     * way — the same conflation `unavailable` exists to prevent one level up.
+     *
+     * A timeout is deliberately NOT here. Stryker counts it as detected, on the reasoning that a mutant which
+     * hangs the suite is one the suite noticed, and this follows Stryker's arithmetic rather than inventing a
+     * second definition of the same word: the number on the row has to mean what the tool that produced it
+     * means, or the row is quietly arguing with its own evidence. */
+    inconclusive: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Faults it never got a verdict on, because they would not compile or were configured out. Left out of the score entirely, since neither answer is known."),
+    /* The worst offenders, named. Capped, and the cap is the point: a survivor list is only useful while it is
+     * short enough to act on, and the rest are still there on the next run. */
+    survivors: z
+        .array(
+            z.object({
+                file: z.string().describe("Where it is."),
+                line: z.number().int().nonnegative().describe("Which line."),
+                mutator: z.string().describe("What was changed, in the mutation tool's own vocabulary."),
+                replacement: z.string().describe("What it became, so a reader can judge whether it matters without opening the file."),
+            }),
+        )
+        .describe("The surviving faults themselves. A percentage is a mood; a named line with the change that went unnoticed is a morning's work."),
+});
+export type MutationScore = z.infer<typeof MutationScoreSchema>;
 /* One probe's cached result. The three states are deliberately distinct, because a panel that collapses them
  * lies about the most important case:
  *   ok           the tool ran and reported. `facts` carries its findings, including "nothing found", which is
@@ -187,6 +236,7 @@ export const ProbeFactsSchema = z.discriminatedUnion("id", [
     z.object({ id: z.literal("jscpd"), duplication: DuplicationSchema }),
     z.object({ id: z.literal("ui"), scan: UiScanSchema }),
     z.object({ id: z.literal("bundle"), bundle: BundleSchema }),
+    z.object({ id: z.literal("mutation"), mutation: MutationScoreSchema }),
 ]);
 export type ProbeFacts = z.infer<typeof ProbeFactsSchema>;
 export const ProbeResultSchema = z.object({

package/src/schemas/settings.ts

@@ -422,6 +422,38 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Whether a version the agent is about to pin is checked against the package's own registry first. Facts only, or facts plus the name of a maintained replacement where the registry agrees the current choice has been abandoned. It tells the agent and lets it decide rather than refusing, because matching a version your project already uses is usually the right answer and a gate would fight it.",
         ),
+    /* DOES THE TEST IT JUST WROTE ACTUALLY TEST THE CHANGE?
+     *
+     * A model writes a test that passes, and a passing test is the thing it was asked for, so nothing in the loop
+     * objects. The failure this catches is the one where the test would have passed BEFORE the change too: it
+     * exercises the code without depending on the behaviour that was added, and it will keep passing when that
+     * behaviour is broken later. It type-checks, it lints, `pnpm verify` is green, and the suite has grown a test
+     * that can never fail.
+     *
+     * The check is a differential, and it is cheap for one specific reason: in an agent turn we already know
+     * exactly which source files changed. So the test is re-run with those files' HEAD contents served in place
+     * of the working copies, and the answer is one bit — did it still pass? A test that passes against the old
+     * code did not test the new code. This is one-mutant mutation testing where the mutant is "your change,
+     * reverted", which is the cheapest useful mutant there is and the only one already known for free.
+     *
+     * NOTHING IS WRITTEN TO THE TREE. The HEAD copies are served through a vite `load` hook in a generated config,
+     * never checked out over the working files — a hook that could leave a half-reverted tree behind on a crash
+     * would be trading a whole turn's work for a lint-grade signal.
+     *
+     * IT REPORTS AND GETS OUT OF THE WAY, for the same reason the freshness check above does. Two legitimate
+     * cases pass on HEAD and must not be fought: a test written BEFORE its implementation (it fails now, which
+     * the agent can see without help), and a pure refactor, where a test that keeps passing is the entire point.
+     * Distinguishing those from a weak test needs intent, so the fact rides back as context and the model decides.
+     *
+     * Scoped to source changed in the SAME package as the test, because that is what a package's own vitest run
+     * loads from source; a cross-package import resolves to the other package's built output, where there is
+     * nothing to swap. Off by default like every flag here, and off wires no hook at all. */
+    testFaultDetection: z
+        .boolean()
+        .default(false)
+        .describe(
+            "After the agent writes a test, re-run it against the code as it was before this turn's changes. A test that still passes did not test the change — it will pass just as happily when that behaviour breaks. Reports what it finds and lets the agent decide, because a test written before its implementation and a pure refactor both pass this honestly.",
+        ),
     outputCleaners: z
         .string()
         .default("")

package/src/schemas/terminal.ts

@@ -10,10 +10,12 @@ import { z } from "zod";
 // Bash commands run in (live-watchable, AI-marked in the UI; running:false once every window is a finished
 // command's dead pane, which is what lets the panel sweep it), `job` = a job-* session the daemon's terminal
 // runner executes user-triggered flows in (capability adds, infra check), `process` = a managed background
-// process riding a panel session (an extension's declared processes, dockerd), surfaced in the panel's
-// background-processes popover with read-only log views, never as a killable tab; running is the actual
-// process (a lingering shell after a crash reads false). A process row that maps to an installed extension's
-// declared process carries extensionId+processName, the address for its /extensions start/stop routes. The
+// process: a supervised daemon child for an extension's declared processes (name `svc-<key>`, whose
+// "terminal" is a tail of the service's log file), or a tmux-riding one for dockerd and the local model
+// servers, which outlive daemon restarts on purpose. Surfaced in the panel's background-processes popover
+// with read-only log views, never as a killable tab; running is the actual process. A process row that maps
+// to an installed extension's declared process carries extensionId+processName, the address for its
+// /extensions start/stop routes. The
 // `{name}` kill-route param is a bare string validated in the handler (a bad name is a BAD_REQUEST) since the
 // same charset gates a `tmux kill-session -t` shell-out. The agent's BROWSER is deliberately NOT one of these
 // kinds: a Chromium with its own tab strip is a surface in its own right, not a pane in the terminal panel, so

package/src/schemas/webext.ts

@@ -77,3 +77,32 @@ export const WebExtSessionImportSchema = z.object({
     cookies: z.array(WebExtCookieSchema).min(1).max(300),
 });
 export type WebExtSessionImport = z.infer<typeof WebExtSessionImportSchema>;
+
+/* ---- and the same door in the other direction: LENDING a sandbox session to the person's own browser ----
+ *
+ * The case this answers is the one no amount of streaming quality can: a passkey bound to an authenticator the
+ * person physically holds, a hardware second factor that has to be touched, an employer's SSO that checks the
+ * device. Driving the sandbox's browser remotely is not a worse experience on those sites, it is an impossible
+ * one — so the session goes to the browser the account was actually enrolled on, the person finishes the step
+ * as themselves, and `connect_site` hands it back.
+ *
+ * Same door and same rule as the import above: the cookies travel on the extension's own HTTPS request, never
+ * as a socket answer, because socket answers are MCP results and MCP results land in the model's context. */
+export const WebExtSessionExportSchema = z.object({
+    // The `browser`-kind capability to lend FROM. Named by the agent out of the roster it can already read.
+    account: z.string().min(1),
+    // The registrable domain to lend, and the reason this cannot lend a whole profile: a profile holds every
+    // account its owner ever connected, and handing all of it over because one site got stuck is the kind of
+    // over-broad grant that is invisible until it matters.
+    domain: z.string().min(1),
+});
+export type WebExtSessionExport = z.infer<typeof WebExtSessionExportSchema>;
+
+export const WebExtSessionExportResultSchema = z.object({
+    ok: z.boolean(),
+    // What the owner reads and the agent reads back. Never carries a cookie name or a value.
+    message: z.string(),
+    // Only ever read by the extension, which writes it straight into this browser's own cookie store.
+    cookies: z.array(WebExtCookieSchema).optional(),
+});
+export type WebExtSessionExportResult = z.infer<typeof WebExtSessionExportResultSchema>;

package/src/tunnel-ids.test.ts

@@ -42,7 +42,9 @@ test("slots are not derivable from the sandbox id: only from the token behind it
     expect(portSlotsFromToken(OTHER)).not.toEqual(portSlotsFromToken(TOKEN));
     // No slot leaks the id it will be paired with in `port-<slot>-<sandboxId>`.
     const id = sandboxIdFromToken(TOKEN);
-    expect(id).toBeDefined();
+    // Load-bearing, and not merely tidy: `not.toContain(undefined)` is true of every slot list ever produced,
+    // so without a real id the leak check below would pass on a function that had stopped deriving one at all.
+    expect(id).toEqual(expect.any(String));
     expect(portSlotsFromToken(TOKEN)).not.toContain(id);
     // And none of them is the old fixed alphabet, which is what made the hostnames guessable.
     expect(portSlotsFromToken(TOKEN).some((slot) => slot.length === 1)).toBe(false);

package/src/webext-links.ts

@@ -23,6 +23,16 @@ export const webextConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.re
  * and the one thing that would be catastrophic to leak is the one thing the model never sees. */
 export const webextSessionUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/session`;
 
+/* The same door in the other direction: where the extension asks for a sandbox account's session to be LENT to
+ * this browser, so the owner can finish a step no remote browser can do — a passkey, a hardware second factor,
+ * an employer's SSO that checks the device.
+ *
+ * A separate path rather than a verb on the one above, because the two are different acts with different
+ * refusals ("no such account" versus "that account is not signed in there") and a single endpoint doing both
+ * would have to be read twice to know which. Same bearer, and the same rule about the socket: the cookies come
+ * back on THIS request, never as an MCP result. */
+export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/lend`;
+
 /* ---- the pairing code: the one string that travels from the sandbox's card into the extension ----
  *
  * A connected computer is paired by a shell one-liner, which can carry two values in two environment variables

package/src/workspace-state.test.ts

@@ -162,7 +162,9 @@ describe(`WORKSPACE_STATE_FILES`, () => {
         // the difference visible at review time.
         for (const file of WORKSPACE_STATE_FILES) {
             if (file.invalidates.length === 0) {
-                expect(file.why, `${file.path} invalidates nothing and must say why`).toBeTruthy();
+                // A string with something in it. Truthiness would accept the number 1 or an object, and the
+                // failure this guards against — a `why` left blank to quiet the check — reads as whitespace.
+                expect(file.why, `${file.path} invalidates nothing and must say why`).toEqual(expect.stringMatching(/\S/));
             } else {
                 expect(file.why, `${file.path} invalidates queries, so \`why\` is dead weight`).toBeUndefined();
             }

package/src/workspace-state.ts

@@ -301,6 +301,24 @@ const STATE_FILES = [
         why: "Declared by the intentic.automations extension's contributes.files, `automation-approvals` is its query key, not core's.",
         portability: "carry",
     },
+    /* The bug-report inbox, one file per fingerprint, written by the daemon's issues-store as reports arrive
+     * from the owner's own sites and apps, and rendered by the intentic.issues extension. Its invalidation is
+     * the extension's own (`issues`), declared in that manifest, the automations shape exactly.
+     *
+     * `carry` rather than `local`: an issue is a fact about the PRODUCT, not about this container. A workspace
+     * exported and restored elsewhere that arrived claiming nothing had ever crashed would have thrown away
+     * the one record that says which bug is worth fixing first, and the counts are the whole of that record.
+     *
+     * NOT `versioned`, and the drafts entry is the contrast worth reading: a draft is authored, reviewable and
+     * goes out under the owner's name, so it earns a diff. An issue is machine-recorded telemetry whose count
+     * moves on every crash: tracking it would put a commit's worth of churn in `git log` per bad afternoon,
+     * and nothing in it is a decision anybody made. */
+    {
+        path: ".intentic/records/issues/",
+        invalidates: [],
+        why: "Declared by the intentic.issues extension's contributes.files, `issues` is its query key, not core's.",
+        portability: "carry",
+    },
     /* The maintenance ledger and probe evidence, written by the daemon's chores-store and rendered by the
      * intentic.maintenance extension, the automations shape exactly: the path is the daemon's, the query keys
      * (`maintenance-report`, `maintenance-runs`) are the extension's own contributes.files. Point-in-time
@@ -359,6 +377,12 @@ const STATE_FILES = [
         why: "Which origins have loaded a Front Desk's widget, written on a 30s flush timer while a customer's site serves page views. The install panel that renders it fetches on open and polls itself while it is on screen, which is the whole window in which the answer changes for anyone. Pushing instead would bill every connected browser a refetch per flush, for a panel almost nobody has open.",
         portability: "carry",
     },
+    {
+        path: ".intentic/records/issue-installs.json",
+        invalidates: [],
+        why: "The same probe for the bug reporter's script, on the same flush timer and read by the same kind of panel, so it is outside the push path for the same reason the Front Desk's is.",
+        portability: "carry",
+    },
     {
         path: ".intentic/records/thread-sessions.json",
         invalidates: [],
@@ -805,34 +829,6 @@ export const REPORTED_MANIFEST_PATHS: readonly string[] = WORKSPACE_STATE_FILES.
 // them relative at the last moment, and normalizing at each call site is the one that eventually gets forgotten.
 export const isReportedManifest = (relPath: string): boolean => REPORTED_MANIFEST_PATHS.includes(relPath.replaceAll("\\", "/"));
 
-/* Old directory names are never read or migrated. Keep that finite set in one quarantine record so access,
- * export, and search cannot reinterpret abandoned machine state as ordinary workspace content after a rename.
- * `artifacts` still carry; the distinction here tells portability only which retired roots are secrets or
- * derived, and tells the state janitor which it may DELETE: a retired `derived` root is a rebuildable cache
- * by its own classification, so leaving 466 MB of abandoned model where only a manual `rm` reaches it was
- * quarantine doing half its job. Secret and artifact roots stay until an owner removes them by hand: deleting
- * content is not the janitor's call, only deleting what the class already says is disposable. */
-export const RETIRED_WORKSPACE_STATE_DIRS = {
-    /* The flat spellings, from before the state dir was grouped into its five folders. Every entry in the table
-     * used to sit directly under `.intentic/`, and a sandbox that predates the move still has those directories
-     * on disk with real contents in them. They are quarantined rather than migrated, the workspace rule is fresh
-     * state and no compatibility layers, but quarantine is exactly what they need, because the alternative is
-     * worse than leaving them: `auth` at the old spelling is a real credential store that the classifier no
-     * longer recognises, so without these names it would read as ordinary workspace content and be indexed by
-     * search, carried by an export and copied down by the backup. Being listed here keeps the old copy as
-     * untouchable as the new one, and lets the janitor delete the rebuildable half. */
-    secret: ["claude", "codex", "kimi", "opencode", "cliproxy", "auth", "ci.json"],
-    /* The ownership records at their OLD flat spelling, and a bucket of their own rather than a few more names
-     * in `secret`, because the two classes differ on exactly the thing that matters for a leftover. A `secret`
-     * travels when the owner opts in at export; an `identity` never travels at all, since a list of who may
-     * drive this sandbox arriving in another one is how a source hands itself the target's ownership. Filed under
-     * `secret` these would have become carryable by ticking a box, which is the one outcome their live entries
-     * are written to prevent. */
-    identity: ["owner.json", "members.json", "workspace.json", "control-tokens.json"],
-    derived: ["iq", "extensions-runtime", "whisper", "browser/output", "browser", "cache", "runtime", "tmp", ".pnpm-store", "extensions", "verify"],
-    artifacts: ["attachments", "acceptance", "loops", "workflow-runs", "transcripts", "artifacts", "sessions"],
-} as const;
-
 /* THE DAEMON'S OWN CONTROL PLANE, the entries directly under the workspace root's `.intentic/` that the file
  * API refuses to read, write, move or delete for anyone, the owner included (workspace/workspace-files.ts holds
  * the enforcement and the full reasoning for each name).
@@ -884,15 +880,9 @@ export const isLockedWorkspacePath = (relPath: string): boolean => {
     if (segments[0] !== STATE_DIR) {
         return false;
     }
-    /* Two shapes, because two layouts exist on disk. A current entry is `<group>/<name>`; a leftover from before
-     * the regrouping is a bare name directly under the state dir, and the quarantine record is what still knows
-     * those are credentials. Both are locked, a stale `auth/` full of real tokens is no safer to open than the
-     * live one, and the whole point of quarantining the old spellings was that nothing downstream reclassifies
-     * them as ordinary content. */
-    return (
-        LOCKED_STATE_ENTRIES.has(segments.slice(1, 3).join("/")) ||
-        (segments.length >= 2 && RETIRED_WORKSPACE_STATE_DIRS.secret.includes(segments[1] as never))
-    );
+    // Two segments, which covers both spellings in the set above: a grouped entry (`secrets/auth`) matches as
+    // written, and a bare root entry (`claude.json`) joins to itself because there is no second segment to add.
+    return LOCKED_STATE_ENTRIES.has(segments.slice(1, 3).join("/"));
 };
 
 /* THE LOCKED ENTRIES THE ROOT REPO TRACKS, refused by the file API, and diffable anyway.