@intentic/sandbox-contract 1.233.0 → 1.235.0

package/src/schemas/automations.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema } from "./agent.js";
 import { AgentSummarySchema } from "./agents.js";
 import { entryId } from "./internal.js";
+import { IssuesConfigSchema } from "./issues.js";
 // An automation wakes the agent autonomously: the daemon's scheduler fires each enabled automation on its
 // trigger, runs the optional guard command (a shell command in the workspace; non-zero exit skips the wake),
 // then runs one agent turn with the prompt. The manifest is user config; run history is daemon-recorded.
@@ -108,8 +109,14 @@ export const TriggerSchema = z.discriminatedUnion("kind", [
             .min(1)
             .optional()
             .describe("Narrow it to one branch, for the sources that have branches. Absent means every branch of the repositories it matches."),
-        // webchat only: the website origins allowed to POST to the widget endpoint. Absent/empty ⇒ none admitted.
-        allowedOrigins: z.array(z.string()).optional().describe("Which websites may reach the chat widget. Absent or empty admits nobody."),
+        /* The two gateway-less browser sources, `webchat` and `issues`: the website origins allowed to POST to
+         * the public endpoint. Absent/empty ⇒ none admitted, on both. One field rather than one per source,
+         * because it is the same question asked of the same header by the same kind of caller, and an intake
+         * whose allowlist lived somewhere else would be a second gate to keep in step with the first. */
+        allowedOrigins: z
+            .array(z.string())
+            .optional()
+            .describe("Which websites may reach the public endpoint, the chat widget's or the bug reporter's. Absent or empty admits nobody."),
     }),
     // `repo` narrows to events whose span touches one workspace repo ("root" or a repo id); absent ⇒ any.
     z.object({
@@ -266,6 +273,11 @@ export const AutomationSchema = z.object({
     prompt: z.string().min(1).describe("What the woken agent is told."),
     // The Front Desk widget's settings, `webchat` listener automations only, ignored on every other trigger.
     webchat: WebchatConfigSchema.optional().describe("Settings for the public chat widget, for an automation that answers visitors."),
+    // The bug intake's settings, `issues` listener automations only, ignored on every other trigger. Its own
+    // field rather than a shared "public endpoint" bag: the two sources answer different questions (a chat's
+    // greeting and access model, an intake's dedup ceiling and ingest key) and a union of both would be a
+    // schema where most fields are wrong for whichever source is reading it.
+    issues: IssuesConfigSchema.optional().describe("Settings for the bug reporter, for an automation that takes crash reports from your own sites and apps."),
     /* NARROW THIS ONE JOB FURTHER than the persona it runs as, raw tool names, and the escape hatch under the
      * shelves rather than the way anyone is expected to answer this question.
      *

package/src/schemas/computers.ts

@@ -117,6 +117,53 @@ export const MachineFlowLineSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("error"), message: z.string() }),
 ]);
 export type MachineFlowLine = z.infer<typeof MachineFlowLineSchema>;
+/* RUNNING ONE OF THIS PRODUCT'S OWN CLIs ON A CONNECTED COMPUTER, FROM A BUTTON, with no agent in the loop.
+ *
+ * A machine that is connected as a computer can already be told things: the ops above drive its docker, and an
+ * agent with the `host` capability can run whatever it likes through `run_command`. What had no door was the
+ * ordinary case in between — the user wants the thing the CLI on their machine already does, and the sandbox is
+ * where they are looking. Their alternatives were to go and find a terminal, or to ask an agent to do it, which
+ * spends a turn and a model's judgement on a decision that has none in it.
+ *
+ * So: a CLOSED SET OF NAMES, and the argv is built on the daemon from the name alone (hosts/machine-commands.ts).
+ * The browser sends `mirror-off`, never a command line. That is the whole security property, and it is the
+ * reason this is an enum rather than a string: the same socket carries `run_command`, so a route that forwarded
+ * caller-supplied text would hand every browser session a shell on the user's laptop, which is a grant the
+ * capability card never made.
+ *
+ * The machine still enforces its own switches. "Run commands" being off comes back as its own refusal, in its
+ * own words, naming the control to flip — exactly as it does for the sandbox ops. */
+export const MachineCommandSchema = z.enum(["mirror-off", "mirror-on"]);
+export type MachineCommand = z.infer<typeof MachineCommandSchema>;
+/* Which paired sandbox the command acts on: the machine's own id for it, as it appears in that machine's report,
+ * so nothing here has to re-derive the sanitizing the agent applied. Absent means every sandbox that machine
+ * pairs, which is what the CLI does when it is run bare.
+ *
+ * Pattern-bound because it becomes an argv token. It must start with an alphanumeric, not merely consist of id
+ * characters: a value like `--takeover` is made only of legal id characters and is a FLAG by the time the CLI on
+ * the machine parses it. Real ids are `sandbox-<hex>-<zone>`-shaped, so nothing legitimate leads with a dash. */
+export const MachineSandboxIdSchema = z
+    .string()
+    .max(200)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+export const MachineCommandInputSchema = z.object({
+    id: z.string().min(1),
+    command: MachineCommandSchema,
+    sandboxId: MachineSandboxIdSchema.optional(),
+});
+export type MachineCommandInput = z.infer<typeof MachineCommandInputSchema>;
+/* What came back. `ok` is the command's own exit status, not this route's: a machine that refused the call, or a
+ * CLI that exited non-zero, is a real answer to show the person who clicked, not an exception to convert into
+ * one. Only an unreachable machine throws, because then there is nothing to report at all.
+ *
+ * `output` is what the command printed, kept because the CLI's own sentences ("Port mirroring OFF for: …") are
+ * better than anything this side would write over them. */
+export const MachineCommandResultSchema = z.object({
+    ok: z.boolean(),
+    message: z.string(),
+    output: z.string().optional(),
+});
+export type MachineCommandResult = z.infer<typeof MachineCommandResultSchema>;
 // One paired sandbox as the local agent holds it. `localDir` is the answer to the question the Desktop sync card
 // has never been able to answer: which folder on that computer this sandbox's /work actually is.
 export const MachinePairingSchema = z.object({
@@ -124,6 +171,19 @@ export const MachinePairingSchema = z.object({
     mode: z.enum(["sync", "mirror"]),
     // Set only for mode "sync", and only for the sandbox being reported to, see the redaction note above.
     localDir: z.string().optional(),
+    /* Whether that computer is putting this sandbox's ports on its own localhost, which is a switch its owner
+     * holds and not a state this sandbox can read off anything else. An empty port list means two opposite
+     * things — nothing is listening in the sandbox, or the machine was told to keep them off — and only the
+     * second is worth a word on screen or a button to undo.
+     *
+     * The MACHINE owns the flag (the agent's `sync mirror off`), because the localhost being written to is
+     * there: a computer told to keep ports off must keep them off while this sandbox is asleep, unreachable, or
+     * arguing. A browser asks for it by running that same command over the machine's `host` capability, so the
+     * button and the CLI are one gesture rather than two mechanisms that can disagree.
+     *
+     * Optional because it is a fact only an agent new enough to have the switch reports; absent is read as "on",
+     * which is what mirroring has always been. */
+    mirroring: z.enum(["on", "off"]).optional(),
     // Mutagen's own word for what the session is doing ("watching", "scanning", "transitioning", "halted-…").
     // Carried verbatim rather than mapped to a traffic light: the halted states name their own cause, and a UI
     // that reduces them to "problem" sends the user back to the terminal this report exists to replace.

package/src/schemas/extension-updates.ts

@@ -315,8 +315,10 @@ export const ExtensionProcessParamSchema = z.object({
 });
 export const ExtensionProcessStatusSchema = z.object({
     name: z.string().describe("Which process."),
-    running: z.boolean().describe("Whether it is up."),
+    running: z.boolean().describe("Whether it is up. False with a port means it crashed and the supervisor is waiting to retry it."),
     port: z.number().optional().describe("The port it was given."),
+    restarts: z.number().optional().describe("How many times it died and was brought back since it was started. A growing number is a service in trouble."),
+    lastExitCode: z.number().optional().describe("How it last exited, when it has crashed at least once."),
     previewUrl: z.string().optional().describe("Where to open it, when it has an address."),
 });
 export type ExtensionProcessStatus = z.infer<typeof ExtensionProcessStatusSchema>;

package/src/schemas/issues.ts

@@ -0,0 +1,279 @@
+// issues: inbound bug reports from the owner's own sites and apps, grouped by fingerprint
+// (.intentic/records/issues/<fingerprint>.json, one file per group)
+import { z } from "zod";
+import { entryId } from "./internal.js";
+
+/* WHAT A USER'S CRASH LOOKS LIKE BY THE TIME AN AGENT CAN ACT ON IT.
+ *
+ * Three shapes live here and the split between them is the whole design:
+ *
+ *   IssueReportSchema  what a stranger's browser POSTs to /intake/<id>/report. UNTRUSTED, every field of it,
+ *                      and bounded field by field because the endpoint is public and the body is a stack trace
+ *                      somebody else's machine wrote.
+ *   IssueSchema        what the daemon KEEPS: one group per fingerprint, with a count, a first/last seen and
+ *                      the most recent sample. A crash loop is one of these, not ten thousand.
+ *   IssuesConfigSchema what the owner configures on the automation, and IssuePublicConfigSchema the subset the
+ *                      SDK is allowed to read back. Named field by field there, never by omission, the same
+ *                      rule WebchatConfig's public half is built on.
+ *
+ * The SDK imports these as TYPES ONLY (`import type`), so zod never reaches a visitor's browser, which is why
+ * the wire shapes live in this package beside the stored ones rather than being re-typed in the bundle. */
+
+// What kind of thing arrived. `crash` and `detection` GROUP (one fingerprint, a rising count); `report` never
+// does, because two people describing the same annoyance in their own words are two things to read.
+export const IssueKindSchema = z.enum(["crash", "report", "detection"]);
+export type IssueKind = z.infer<typeof IssueKindSchema>;
+
+/* One thing that happened before the crash. Deliberately a flat {at, kind, message} rather than a per-source
+ * union: the value of a breadcrumb is being READ in order next to the others, and a shape the SDK can produce
+ * for a console line, a failed fetch and a route change alike is one the agent can render as a timeline
+ * without knowing which instrumentations the site switched on. */
+export const IssueBreadcrumbSchema = z.object({
+    at: z.number().describe("When, in milliseconds."),
+    kind: z.string().max(40).describe("What sort of thing it was: a console line, a request, a click, a route change."),
+    message: z.string().max(300).describe("What it said, already truncated by the SDK."),
+});
+export type IssueBreadcrumb = z.infer<typeof IssueBreadcrumbSchema>;
+
+// How much of the reporter we are willing to believe: nothing. Both fields are typed by whoever is reporting,
+// so they reach the model beside the content rather than above it, exactly as a Front Desk visitor's
+// `unverifiedDisplayName` does. There is no signed identity on this endpoint and there should not be one: a
+// crash handler fires on a dying page, where no sign-in ceremony can run.
+export const IssueReporterSchema = z.object({
+    email: z.string().max(320).optional().describe("An address they typed, to reach them about it. Unverified."),
+    name: z.string().max(200).optional().describe("A name they typed. Unverified, and never identity."),
+});
+export type IssueReporter = z.infer<typeof IssueReporterSchema>;
+
+// A small bag of host-supplied strings (route, app version, locale, tenant). Bounded in both dimensions
+// because it is the one open-ended field on a public endpoint, and an unbounded map is a storage bug waiting
+// for the first person who loops over it.
+const CONTEXT_KEYS_MAX = 20;
+const IssueContextSchema = z
+    .record(z.string().max(60), z.string().max(300))
+    .refine((context) => Object.keys(context).length <= CONTEXT_KEYS_MAX, { message: `at most ${CONTEXT_KEYS_MAX} context entries` });
+
+/* ONE REPORT, AS IT ARRIVES. Everything optional except `kind` and `message`, because the three kinds carry
+ * genuinely different evidence and a schema that demanded the union of them would refuse the commonest case:
+ * `window.onerror` in an old browser, which has a message and very little else. */
+export const IssueReportSchema = z.object({
+    kind: IssueKindSchema.describe("A crash the SDK caught, something a person wrote in, or a problem the SDK noticed on its own."),
+    message: z.string().min(1).max(1000).describe("The error's own message, or the headline of what a person reported."),
+    stack: z.string().max(20_000).optional().describe("The stack, verbatim from the browser."),
+    url: z.string().max(2000).optional().describe("Where it happened: the page's address, or a screen name in an app."),
+    /* THE ONE FIELD THAT REPLACES AN ENTIRE INTEGRATION. The agent has the repository, so a build's sha or tag
+     * is enough to check that commit out and read the real frames; there is nothing to upload, no artifact
+     * store, and no sourcemap pipeline to keep in step with a deploy. A site that sets nothing here still gets
+     * a grouped, readable issue: it just costs the agent a guess about which build it came from. */
+    release: z.string().max(200).optional().describe("Which build it came from: a commit sha or a tag. With it the agent reads your real source rather than minified frames."),
+    userAgent: z.string().max(400).optional().describe("What the browser said it was."),
+    description: z.string().max(5000).optional().describe("What the person typed, when a person is the one reporting."),
+    reporter: IssueReporterSchema.optional().describe("Who says they are reporting it. Unverified by construction."),
+    breadcrumbs: z.array(IssueBreadcrumbSchema).max(40).optional().describe("What happened just before, oldest first."),
+    context: IssueContextSchema.optional().describe("Whatever else the app attached: a route, a version, a locale."),
+    /* The host's own grouping override, Sentry's convention and worth keeping: an app that knows two crashes
+     * are the same thing (or knows one crash is really two) can say so, and the daemon groups on this instead
+     * of on the stack. It is hashed like everything else, never used as a filename directly. */
+    fingerprint: z.string().max(200).optional().describe("Group by this instead of by the stack, when your app knows better than the stack does."),
+});
+export type IssueReport = z.infer<typeof IssueReportSchema>;
+
+/* The body POSTed to /intake/<id>/report: the report plus the two things the GATE needs and the report itself
+ * has no business carrying, a client id to rate-limit against and the anti-bot answer. Kept out of
+ * IssueReportSchema so that what gets STORED (the sample) is the evidence and not the doorman's paperwork. */
+export const IssueIngestSchema = z.object({
+    report: IssueReportSchema,
+    // The SDK's own per-browser id (localStorage). Not a secret and not identity, anyone can mint one: it is
+    // the key the per-minute limit counts against, so one runaway tab cannot spend the whole day's budget.
+    clientId: z.string().min(1).max(200).describe("The SDK's own id for this browser. Not a secret: it is what the rate limit counts against."),
+    // Only for `report`, and only when the automation asks for a proof of work: a crash fires on a dying page,
+    // where there is no second to spend on a puzzle and no user to wait for it.
+    powNonce: z.string().max(400).optional(),
+    // Minted by the owner, pasted into a mobile or server SDK that has no Origin header for the allowlist to
+    // read. An abuse LABEL rather than a secret (it ships inside a mobile binary and can be pulled out of one):
+    // the real ceilings are the dedup, the rate limit and the daily budget.
+    key: z.string().max(200).optional(),
+});
+export type IssueIngest = z.infer<typeof IssueIngestSchema>;
+
+/* Where a group stands with the owner. `investigating` is set by the daemon when a turn is actually started
+ * for it (from a wake or from the Investigate button), never guessed: it is the difference between "nobody has
+ * looked at this" and "something is looking at it right now", which is the question a triage inbox is for. */
+export const IssueStatusSchema = z.enum(["open", "investigating", "resolved", "ignored"]);
+export type IssueStatus = z.infer<typeof IssueStatusSchema>;
+
+// One agent turn started for this issue. The conversation id is the link: the fleet board already knows how to
+// open one, so the inbox does not have to store anything about the run beyond which conversation it became.
+export const IssueRunSchema = z.object({
+    conversationId: z.string().describe("The conversation this run became."),
+    at: z.number().describe("When it started, in milliseconds."),
+    // What the count stood at when this run was started, so a recurrence after a fix reads as "it came back",
+    // not as "someone already looked at this".
+    atCount: z.number().describe("How many times it had happened when this run started."),
+});
+export type IssueRun = z.infer<typeof IssueRunSchema>;
+
+/* ONE GROUP. The id is the fingerprint and is the FILENAME, never in the body (json-dir.ts owns that rule), so
+ * a body that disagrees with its own grouping cannot be written. */
+export const IssueSchema = z.object({
+    kind: IssueKindSchema,
+    // The one-line headline the inbox lists it under, derived from the report rather than typed, so two
+    // recurrences of one crash cannot be filed under two names.
+    title: z.string().min(1).max(300).describe("The one line this is listed under."),
+    culprit: z.string().max(300).optional().describe("The frame it came from, when the stack named one."),
+    // Which issues automation received it. A workspace can run several (one per site), and the inbox is one
+    // list across all of them, so the group has to say which door it came in through.
+    automationId: entryId.describe("Which intake received it."),
+    // The site or app it came from, as the browser's Origin or the SDK's declared one; absent for a keyed
+    // client (a mobile app, a server) that has no origin to send.
+    origin: z.string().max(400).optional().describe("Which site it came from."),
+    firstSeen: z.number().describe("When it first happened, in milliseconds."),
+    lastSeen: z.number().describe("When it last happened, in milliseconds."),
+    count: z.number().describe("How many times this exact thing has arrived."),
+    status: IssueStatusSchema.default("open").describe("Where it stands with you."),
+    statusAt: z.number().optional().describe("When the status last changed, in milliseconds."),
+    release: z.string().max(200).optional().describe("The build the latest one came from."),
+    // The most recent event in full. The LATEST rather than the first, deliberately: when a crash is still
+    // happening, what it looks like now is what a fix has to reproduce, and the first one is often from a
+    // build that no longer exists.
+    sample: IssueReportSchema.describe("The most recent one, in full."),
+    /* How many arrivals had been counted the last time this group WOKE an agent. The whole of the escalation
+     * rule lives in this one number: a group fires once when it is new, and again only when it has moved this
+     * far past its last firing. Stored rather than derived, because "how many since the last wake" is not
+     * recoverable from a count and a timestamp after a restart. */
+    firedAt: z.number().optional().describe("What the count stood at the last time this woke an agent."),
+    runs: z.array(IssueRunSchema).max(20).optional().describe("The turns started for it."),
+});
+export type Issue = z.infer<typeof IssueSchema>;
+
+// The list row: the stored group plus its filename id (the fingerprint).
+export const IssueSummarySchema = IssueSchema.extend({ id: entryId.describe("The issue's id, which is its fingerprint.") });
+export type IssueSummary = z.infer<typeof IssueSummarySchema>;
+
+// `invalid` is the same trust-boundary confession the drafts list makes, for the opposite reason: nothing but
+// the daemon writes these, so a file in here that will not parse is a BUG in this daemon or a half-written
+// volume, and either is worth seeing rather than silently skipping.
+export const IssuesListSchema = z.object({
+    issues: z.array(IssueSummarySchema).describe("The inbox, most recently seen first."),
+    invalid: z.array(z.string()).describe("Files in the issues directory that could not be read at all."),
+});
+export type IssuesList = z.infer<typeof IssuesListSchema>;
+
+export const IssueIdParamSchema = z.object({ id: entryId.describe("Which issue.") });
+// Triage: the owner moving one row. `investigating` is not offered here, the daemon sets it when a turn
+// actually starts, and letting a click claim it would make the one status that means something a lie.
+export const IssueStatusInputSchema = z.object({
+    id: entryId.describe("Which issue."),
+    status: z.enum(["open", "resolved", "ignored"]).describe("Where it now stands with you."),
+});
+export type IssueStatusInput = z.infer<typeof IssueStatusInputSchema>;
+
+/* ---- the automation's own settings ----
+ *
+ * Present only on `issues` listener automations, ignored on every other trigger, the shape WebchatConfig
+ * already established. `allowedOrigins` is NOT here: it lives on the trigger, because it is the admission gate
+ * the ingest route reads rather than a rendering choice, and one gate in two places is one gate. */
+export const IssuesConfigSchema = z.object({
+    /* The key a client with no Origin presents (a mobile app, a server, a desktop build). Minted by the daemon
+     * on upsert like the event webhook's token, and for the same reason: every sender supports "paste this
+     * string", and nothing else is available to a caller with no identity and no browser.
+     *
+     * It is an abuse LABEL, not a secret, and the difference matters: it ships inside a binary anyone can pull
+     * apart. What it buys is that a leaked key can be rotated in one click while the origin allowlist keeps
+     * covering the web. The ceilings are what actually bound the damage. */
+    ingestKey: z.string().min(1).optional().describe("The key an app with no website origin presents. Rotate it freely: the limits, not this, are what bound the damage."),
+    /* Whether a browser with no allowed origin may still report by presenting the key. Off by default: the
+     * commonest way an intake gets abused is its key ending up in a public web bundle, and the allowlist is
+     * the thing that stops that mattering. */
+    keyFromBrowsers: z.boolean().optional().describe("Let a browser report with the key alone, rather than only from a site you listed. Off unless you need it."),
+    // The whole intake's ceiling per UTC day, counted in reports that reach the store. Absent ⇒
+    // ISSUES_DAILY_MAX_DEFAULT, never uncapped, for the reason the Front Desk's own daily cap gives.
+    dailyReportMax: z.number().int().positive().optional().describe("How many reports a day this intake accepts at all."),
+    /* HOW FAR A KNOWN CRASH HAS TO GO BEFORE IT INTERRUPTS ANYONE AGAIN. A group wakes an agent when it is
+     * new, and after that only when its count has grown by this much since the last wake. Absent ⇒
+     * ISSUES_ESCALATE_AFTER_DEFAULT.
+     *
+     * This is the number that makes the whole product safe to leave on. Without it a crash loop on one popular
+     * page is an agent turn per affected browser, which is a bill rather than a bug report. */
+    escalateAfter: z.number().int().positive().optional().describe("How many more times a known crash must happen before it wakes an agent again."),
+    // A proof-of-work puzzle on WRITTEN REPORTS only (a crash has no second to spend and no user to wait for
+    // it). Absent ⇒ off, leaving the origin allowlist and the ceilings as the whole boundary.
+    antiBot: z.enum(["pow"]).optional().describe("Make a person's browser solve a small puzzle before it accepts a written report."),
+    /* ---- the report dialog's chrome, all of it public by construction ---- */
+    title: z.string().max(80).optional().describe("The dialog's heading."),
+    prompt: z.string().max(300).optional().describe("The line above the box they type in."),
+    thanks: z.string().max(300).optional().describe("What it says once they have sent it."),
+    askEmail: z.boolean().optional().describe("Ask for an address to reply to. Optional for them either way."),
+    // A hex colour, for the reason WebchatConfig's `accent` is one: the SDK derives a hover and a focus ring
+    // from its channels rather than only painting it.
+    accent: z
+        .string()
+        .regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, "accent must be a hex colour, e.g. #e47100")
+        .optional(),
+    // Whether the SDK arms window.onerror / unhandledrejection at all. Absent ⇒ on: a site that embedded a
+    // crash reporter meant to report crashes.
+    captureCrashes: z.boolean().optional().describe("Catch uncaught errors automatically, as well as what people write in."),
+});
+export type IssuesConfig = z.infer<typeof IssuesConfigSchema>;
+
+/* What the SDK is told about itself, fully RESOLVED daemon-side so the bundle carries no fallback logic. Every
+ * field is named here rather than spread from the config: a secret added to IssuesConfig later is invisible to
+ * a stranger's browser until somebody deliberately lists it, which is the property this shape exists for.
+ * `ingestKey` is conspicuously absent, a browser proves itself by its origin. */
+export const IssuePublicConfigSchema = z.object({
+    automationId: z.string(),
+    title: z.string(),
+    prompt: z.string(),
+    thanks: z.string(),
+    askEmail: z.boolean(),
+    accent: z.string(),
+    captureCrashes: z.boolean(),
+    // "off" spelled out rather than left absent, for the reason the Front Desk's is: the SDK branches on it,
+    // and a missing field meaning "no challenge" is how one serialization bug becomes an open door.
+    antiBot: z.enum(["pow", "off"]),
+});
+export type IssuePublicConfig = z.infer<typeof IssuePublicConfigSchema>;
+
+// The proof-of-work challenge, the same shape and the same solver as the Front Desk's.
+export const IssueChallengeSchema = z.object({ salt: z.string(), difficulty: z.number().int().positive() });
+export type IssueChallenge = z.infer<typeof IssueChallengeSchema>;
+
+/* What the intake answers with. A short reference the reporter can be shown ("we filed this as 4f3a…"), and
+ * nothing else: whether this crash is new, how often it has happened and whether it woke anybody are the
+ * owner's facts, and the caller is a stranger's browser. */
+export const IssueAcceptedSchema = z.object({ ok: z.literal(true), id: z.string() });
+export type IssueAccepted = z.infer<typeof IssueAcceptedSchema>;
+
+/* Which origins have loaded this intake's SDK, and which were turned away. The Front Desk's install probe,
+ * whole, because the setup mistake is identical and so is the silence it produces: a snippet that was never
+ * pasted, and one pasted on an origin the allowlist does not have, are both "an intake with no reports". */
+export const IssueInstallSchema = z.object({
+    origin: z.string(),
+    allowed: z.boolean(),
+    lastSeenAt: z.number(),
+    loads: z.number(),
+});
+export const IssueInstallsSchema = z.object({ origins: z.array(IssueInstallSchema) });
+export type IssueInstalls = z.infer<typeof IssueInstallsSchema>;
+export const IssueIntakeIdParamSchema = z.object({ automationId: entryId.describe("Which intake.") });
+
+/* ---- the numbers both ends need ----
+ *
+ * Here rather than beside the route that enforces them, for WebchatConfig's reason: the automation editor has
+ * to be able to show the owner what they are already protected by, and a limit that is invisible until it is
+ * hit gets filed as a bug. */
+
+/* The daily ceiling an intake gets when its owner sets none. Larger than the Front Desk's 200 because the unit
+ * is different: a report is a file write and only SOMETIMES an agent turn (dedup decides), where a visitor
+ * message is always a turn. High enough that a real product's bad afternoon fits inside it, low enough that a
+ * script pointed at the endpoint stops being interesting within seconds. */
+export const ISSUES_DAILY_MAX_DEFAULT = 2000;
+
+/* How much a known crash has to grow before it wakes anybody again. Ten is chosen to be quiet on the tail (one
+ * more person hitting a known bug is not news) and prompt on a spike: a regression that starts affecting
+ * everybody crosses it almost at once, which is exactly when the second wake is worth having. */
+export const ISSUES_ESCALATE_AFTER_DEFAULT = 10;
+
+// How much of one ingest body the daemon will read. A stack plus forty breadcrumbs plus a description is a few
+// kilobytes; this leaves room for a pathological framework trace without letting the endpoint be a file upload.
+export const ISSUE_PAYLOAD_MAX = 96_000;

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();
             }