@intentic/sandbox-contract 1.252.1 → 1.254.0

package/src/contracts/settings.contract.ts

@@ -1,4 +1,5 @@
 import { oc } from "@orpc/contract";
+import { RepoChecksAdoptSchema, RepoChecksListSchema } from "../schemas/repo-checks.js";
 import { BuiltinPromptSchema, BuiltinPromptTextSchema, RuleFiringsSchema, SandboxSettingsSchema, SavingsReportSchema } from "../schemas/settings.js";
 import { OkSchema } from "../schemas/shared.js";
 import { DayWindowQuerySchema } from "../schemas/usage.js";
@@ -54,4 +55,25 @@ export const settingsContract = {
                 "A separate read rather than a field on the settings, because a rule firing is not somebody editing anything: folding it in would turn every firing into a settings write and put a self-changing value inside the object a screen edits.",
         })
         .output(RuleFiringsSchema),
+    // Read off the repositories themselves, not out of the settings file: the declaration is a tracked file in each
+    // repository, and only the owner's answer to it lives here.
+    repoChecks: oc
+        .route({
+            method: "GET",
+            path: "/settings/repo-checks",
+            summary: "What each repository asks to run on its own code",
+            description:
+                "Every repository that declares its own checks at `.intentic/checks.json`, what it declares, and whether you have switched it on. A repository declares what to run because the command belongs beside the scripts it names; nothing it declares runs until you say so.",
+        })
+        .output(RepoChecksListSchema),
+    adoptRepoChecks: oc
+        .route({
+            method: "POST",
+            path: "/settings/repo-checks/adopt",
+            summary: "Switch a repository's own checks on or off",
+            description:
+                "Adopts exactly what that repository declares as it stands now. If the declaration changes afterwards it stops running until you adopt it again, so a command nobody has read cannot inherit the answer given to a different one.",
+        })
+        .input(RepoChecksAdoptSchema)
+        .output(OkSchema),
 };

package/src/index.ts

@@ -168,6 +168,7 @@ export * from "./schemas/provider-oauth.js";
 export * from "./schemas/provider-subscriptions.js";
 export * from "./schemas/public.js";
 export * from "./schemas/push.js";
+export * from "./schemas/repo-checks.js";
 export * from "./schemas/secrets.js";
 export * from "./schemas/sessions.js";
 export * from "./schemas/settings.js";

package/src/protocol/peer-dial.test.ts

@@ -35,6 +35,10 @@ class FakeSocket implements SocketLike {
     says(): void {
         this.emit("message");
     }
+    // What a socket that cannot reach its far end emits before it closes: no code, no reason, just a fault.
+    errors(): void {
+        this.emit("error");
+    }
     private emit(type: string, code?: number): void {
         for (const listener of this.listeners.get(type) ?? []) {
             listener(code === undefined ? {} : { code });
@@ -57,7 +61,7 @@ const ladder = (delay = 1_000) => {
     };
 };
 
-const dialling = () => {
+const dialling = (delay?: number) => {
     const sockets: FakeSocket[] = [];
     const attached: FakeSocket[] = [];
     const said: string[] = [];
@@ -70,7 +74,7 @@ const dialling = () => {
         },
         hello: () => ({ type: "hello", token: "iht_test", version: "1.0.0" }),
         attach: (socket) => void attached.push(socket),
-        backoff: ladder(),
+        backoff: ladder(delay),
         silenceMs: SILENCE_MS,
         log: (message) => void said.push(message),
         revoked,
@@ -153,6 +157,73 @@ test("a socket that goes silent is abandoned and redialled, though no close ever
     }
 });
 
+/* THE FAR END THAT IS NEVER COMING BACK, which is not a failure the loop can fix and not one it may narrate
+ * forever: a sandbox deleted, a tunnel repointed, a machine left on for a week. Every attempt here errors and
+ * closes without ever opening, exactly as a laptop's agent did 1,992 times into a 2.3 MB log. What is asserted
+ * is BOTH halves: the log stops repeating, and the dialling does not slow down to achieve it. */
+test("a far end that never answers is reported a few times, then retried quietly at the same cadence", async () => {
+    vi.useFakeTimers();
+    try {
+        const { link, sockets, said } = dialling(60_000);
+        for (let attempt = 1; attempt <= 20; attempt += 1) {
+            // oxlint-disable-next-line eslint/no-await-in-loop -- one attempt after another is the thing under test
+            await vi.waitFor(() => expect(sockets).toHaveLength(attempt));
+            sockets.at(-1)?.errors();
+            sockets.at(-1)?.drops(1006);
+            // oxlint-disable-next-line eslint/no-await-in-loop -- the ladder's own wait, serial by construction
+            await vi.advanceTimersByTimeAsync(60_000);
+        }
+
+        // Twenty minutes of a dead link: eight lines, the last of them a count rather than a repetition.
+        expect(said).toEqual([
+            "connection error",
+            "disconnected (1006); reconnecting in 60s",
+            "connection error",
+            "disconnected (1006); reconnecting in 60s",
+            "connection error",
+            "disconnected (1006); reconnecting in 60s",
+            expect.stringContaining("still nothing after 4 attempts"),
+            expect.stringContaining("14 failed attempts"),
+        ]);
+        // The retries themselves are untouched: one dial per ladder delay, still going, plus the one now armed.
+        await vi.waitFor(() => expect(sockets).toHaveLength(21));
+
+        link.stop();
+        await link.done;
+    } finally {
+        vi.useRealTimers();
+    }
+});
+
+// Quiet is a property of the current outage, not of the link: whatever it hid, the next one starts from nothing.
+test("a link that comes back is loud again about the outage after it", async () => {
+    vi.useFakeTimers();
+    try {
+        const { link, sockets, said } = dialling();
+        for (let attempt = 1; attempt <= 5; attempt += 1) {
+            // oxlint-disable-next-line eslint/no-await-in-loop -- one attempt after another is the thing under test
+            await vi.waitFor(() => expect(sockets).toHaveLength(attempt));
+            sockets.at(-1)?.drops(1006);
+            // oxlint-disable-next-line eslint/no-await-in-loop -- the ladder's own wait, serial by construction
+            await vi.advanceTimersByTimeAsync(1_000);
+        }
+        const whileQuiet = said.length;
+
+        await vi.waitFor(() => expect(sockets).toHaveLength(6));
+        sockets.at(-1)?.opens();
+        await vi.waitFor(() => expect(said.at(-1)).toBe("connected #6"));
+        sockets.at(-1)?.drops(1006);
+
+        expect(said.at(-1)).toBe("disconnected (1006); reconnecting in 1s");
+        expect(said).toHaveLength(whileQuiet + 2);
+
+        link.stop();
+        await link.done;
+    } finally {
+        vi.useRealTimers();
+    }
+});
+
 test("a refused enrollment (1008) is never retried and is reported once", async () => {
     vi.useFakeTimers();
     try {

package/src/protocol/peer-dial.ts

@@ -5,6 +5,20 @@
 // Reconnect backoff: fast floor for a restart, low cap so a reopened laptop is back within a minute.
 export const PEER_LINK_BACKOFF = { floorMs: 1_000, capMs: 30_000, stableMs: 60_000 } as const;
 
+/* HOW MUCH A LINK THAT CANNOT BE REACHED IS ALLOWED TO SAY, which is a different question from how often it
+ * may try. At the cap above, a far end that is gone for good — a sandbox deleted, a tunnel pointed elsewhere —
+ * costs two lines every 30 seconds for as long as the machine is on: 5,760 a day. One laptop's agent had
+ * written 1,992 pairs of them, 2.3 MB, and this log is exactly where its owner had been sent to read why a
+ * DIFFERENT thing had failed; the answer was in there, under an hour of repetition.
+ *
+ * The cadence is not the problem and is deliberately untouched — a reopened laptop must be back within a
+ * minute, which is what the low cap buys. The REPETITION is. So the first few failures are reported in full,
+ * then the loop says so once more to mark that it is going quiet, and after that repeats itself at most once
+ * per QUIET_LOG_MS with the attempt count that says how long it has been trying. A link that opens resets all
+ * of it: every reconnect is news, and the reconnect line is what reports it. */
+const LOUD_ATTEMPTS = 3;
+const QUIET_LOG_MS = 10 * 60_000;
+
 /* HOW LONG A SOCKET MAY SAY NOTHING before this side calls the link dead, as a multiple of the door's own
  * heartbeat: the hub pings every live peer on an interval (peer-hub.ts), so a socket with nothing on it for
  * three heartbeats is not quiet, it is gone.
@@ -57,12 +71,16 @@ export interface PeerDialSpec<S extends SocketLike> {
     readonly revoked: () => void;
 }
 
+// What the socket is doing right now. "connecting" covers a dial in flight and a retry waiting on the ladder:
+// nobody should start another. Named, because processes that are not this one report it (a machine agent stamps
+// it for `status`, which otherwise has only the link list on disk and no idea whether any of it is up).
+export type PeerLinkState = "open" | "connecting" | "closed";
+
 export interface PeerLink {
     // Resolves when the loop is asked to stop or refused for good; never rejects, a connection error is a retry.
     readonly done: Promise<void>;
     readonly stop: (reason?: string) => void;
-    // "connecting" covers a dial in flight and a retry waiting on the ladder: nobody should start another.
-    readonly state: () => "open" | "connecting" | "closed";
+    readonly state: () => PeerLinkState;
 }
 
 export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink => {
@@ -77,6 +95,32 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
     const done = new Promise<void>((resolve) => {
         resolveDone = resolve;
     });
+    // Consecutive attempts that have failed since this link was last open, and when the loop last complained out
+    // loud: between them they are the whole of the quiet rule above.
+    let failures = 0;
+    let quietSince = 0;
+
+    /* What ONE failed attempt is allowed to say. Three sentences rather than one repeated forever: the first few
+     * failures in full, then the line that marks the loop going quiet (so a reader who sees it knows the retries
+     * continue unlogged), then a complaint carrying the attempt count at most once per window. */
+    const complain = (said: string, delay: number): void => {
+        const every = `retrying every ${Math.round(delay / 1000)}s`;
+        if (failures <= LOUD_ATTEMPTS) {
+            spec.log(`${said}; reconnecting in ${Math.round(delay / 1000)}s`);
+            return;
+        }
+        if (failures === LOUD_ATTEMPTS + 1) {
+            quietSince = Date.now();
+            spec.log(
+                `${said}; still nothing after ${failures} attempts — ${every}, and saying so at most every ${Math.round(QUIET_LOG_MS / 60_000)} minutes from here`,
+            );
+            return;
+        }
+        if (Date.now() - quietSince >= QUIET_LOG_MS) {
+            quietSince = Date.now();
+            spec.log(`${said}; ${failures} failed attempts, ${every}`);
+        }
+    };
 
     const open = async (): Promise<void> => {
         waiting = true;
@@ -123,7 +167,8 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
             }
             const delay = spec.backoff.next(openedAt === undefined ? 0 : Date.now() - openedAt);
             openedAt = undefined;
-            spec.log(`${said}; reconnecting in ${Math.round(delay / 1000)}s`);
+            failures += 1;
+            complain(said, delay);
             waiting = true;
             setTimeout(() => void open(), delay);
         };
@@ -149,6 +194,10 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
                 return; // abandoned mid-connect: this socket is already closed and its replacement is on the ladder
             }
             openedAt = Date.now();
+            // A link that is up owes nothing to the failures behind it: the next outage is news again, and the
+            // "connected to …" line this open is about to log is what reports the recovery.
+            failures = 0;
+            quietSince = 0;
             arm();
             spec.attach(ws);
             const send = (hello: Record<string, unknown>): void => {
@@ -184,8 +233,15 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
             drop(`disconnected (${event.code ?? "no code"})`);
         });
 
-        // Always followed by a close event that owns the retry; this only records a cause the close code can't carry.
-        ws.addEventListener("error", () => spec.log("connection error"));
+        /* Always followed by a close event that owns the retry; this only records a cause the close code can't
+         * carry, so it is silenced with the rest once the loop goes quiet — it is half of every repeated pair in
+         * a dead link's log, and it says nothing the drop line beside it does not. The attempt that finally
+         * reconnects is loud again, this line included. */
+        ws.addEventListener("error", () => {
+            if (failures < LOUD_ATTEMPTS) {
+                spec.log("connection error");
+            }
+        });
     };
 
     void open();

package/src/schemas/devices.ts

@@ -237,9 +237,14 @@ export const AGENT_STALL_AFTER_MS = 60_000;
 export const agentStalled = (agent: DeviceAgent, now: number): boolean =>
     agent.running && agent.lastTickAt !== undefined && now - agent.lastTickAt > AGENT_STALL_AFTER_MS;
 export const DeviceReportSchema = z.object({
-    // OS hostname; the join key that dedupes a machine seen via sync and via its `host` capability.
+    // OS hostname; the join key that dedupes a machine seen via sync and via its `host` capability. Not unique on its
+    // own: a WSL distro inherits the Windows machine's name, so `wsl` below is what tells those apart.
     hostname: z.string(),
     os: z.string(),
+    // Present only inside a WSL distro. `distro` is that distro's own name ("Arch", "Ubuntu-22.04"), empty when the
+    // machine won't say. Windows, and every distro it hosts, all answer `hostname` with the same string while being
+    // separate filesystems running separate agents, so this is the only thing that keeps them apart.
+    wsl: z.object({ distro: z.string() }).optional(),
     // Filled by the reader, never the agent; empty means no Docker or nothing looked, not that none exist.
     sandboxes: z.array(DeviceSandboxSchema),
     pairings: z.array(DevicePairingSchema),
@@ -256,6 +261,21 @@ export type DeviceReport = z.infer<typeof DeviceReportSchema>;
 export const REPORT_QUIET_AFTER_MS = 60_000;
 export const reportQuiet = (report: DeviceReport, receivedAt: number): boolean => receivedAt - report.capturedAt > REPORT_QUIET_AFTER_MS;
 
+// The environment a reading came from, as opposed to the machine hosting it: a Windows install and every WSL distro
+// on it are separate filesystems running separate agents, and all of them answer `hostname` with the same string.
+// Undefined when nothing has reported — an absence of evidence, never read as agreement.
+export const environmentOf = (report: DeviceReport | undefined): string | undefined =>
+    report === undefined ? undefined : report.wsl === undefined ? report.os : `wsl:${report.wsl.distro}`;
+
+// Whether two readings positively disagree about which environment they describe. False whenever either side has not
+// said, so this only ever blocks a fold it holds evidence against, and an agent too old to report `wsl` keeps the
+// behaviour it had before the field existed.
+export const differentEnvironment = (left: DeviceReport | undefined, right: DeviceReport | undefined): boolean => {
+    const a = environmentOf(left);
+    const b = environmentOf(right);
+    return a !== undefined && b !== undefined && a !== b;
+};
+
 // Compares running build against installed; silent when the loop is stopped, nothing installed, or installed is a dev
 // build. An unstamped `running` still counts as skew.
 export const agentBuildSkew = (agent: DeviceAgent): { readonly running: string | undefined; readonly installed: string } | undefined => {
@@ -278,8 +298,9 @@ export const DeviceGapSchema = z.enum([
     "unreported",
 ]);
 export type DeviceGap = z.infer<typeof DeviceGapSchema>;
-// A machine may be reachable via desktop sync and a host capability at once; the two are reconciled on `hostname`, and
-// left as separate rows when there is nothing to reconcile them by.
+// A machine may be reachable via desktop sync and a host capability at once; the two are reconciled on `hostname` plus
+// the environment it came from (`environmentOf`), and left as separate rows when there is nothing to reconcile them by
+// or when the environments positively disagree.
 // `machine` is the enrollment's name for the box (the ssh key's comment): what reports are filed under and what the
 // revoke route takes. Two machines sharing a key comment share one enrollment identity.
 export const DeviceSyncSchema = z.object({

package/src/schemas/repo-checks.ts

@@ -0,0 +1,64 @@
+// repo-checks: what a REPOSITORY says should be run on its own code, declared in the repository, at
+// `<repo>/.intentic/checks.json`.
+//
+// The line between this file and the sandbox's own settings is authority, not subject matter: a repository may declare
+// WHAT to run, because the command belongs beside the scripts it names and travels with the checkout; only the sandbox
+// owner decides what happens when it fails (whether work lands, whether a push goes), and that stays in settings.json.
+// Nothing declared here runs until the owner adopts it for that repository (settings `adoptedChecks`), the same rule
+// git keeps for hooks, which are never cloned.
+import { z } from "zod";
+
+// Named for the occasion as a repository would say it, not for the daemon's wire moment: `turn` is `turn.ending` and
+// `push` is `push.starting` (rules/repo-checks.ts maps them). Two, because these are the two occasions whose command a
+// repository actually owns; a verdict moment has nothing here to express.
+export const RepoCheckMomentSchema = z.enum(["turn", "push"]);
+export type RepoCheckMoment = z.infer<typeof RepoCheckMomentSchema>;
+
+export const RepoCheckSchema = z.object({
+    when: RepoCheckMomentSchema.describe("When to run it: `turn` before the assistant finishes, `push` before code leaves the machine."),
+    run: z.string().min(1).max(500).describe("The command, run in this repository's own directory, so it reads as it would in a terminal there."),
+    label: z.string().min(1).max(80).optional().describe("What to call it on screen. Absent names it after the command."),
+    // Same ceiling as a rule's own command; past it the process group is killed and the run is a failure, never a
+    // silent pass.
+    timeoutMs: z.number().min(60_000).max(3_600_000).optional().describe("How long it may take before it is killed and counted as failed."),
+    // Repo-relative, as anybody reading this file would write them; the daemon prefixes the repo id before matching,
+    // since a rule's globs are workspace-relative.
+    paths: z
+        .array(z.string().min(1))
+        .max(20)
+        .optional()
+        .describe("Only run it when the change touches these paths, written relative to this repository. Absent runs it on every change here."),
+});
+export type RepoCheck = z.infer<typeof RepoCheckSchema>;
+
+// The file itself. One key, so a second concern can be added later without breaking a file anyone has written.
+export const RepoChecksFileSchema = z.object({ checks: z.array(RepoCheckSchema).max(10).default([]) });
+export type RepoChecksFile = z.infer<typeof RepoChecksFileSchema>;
+
+// One repository, as a screen reads it: what it declares, and where that stands with the owner.
+export const RepoChecksSummarySchema = z.object({
+    repo: z.string().describe('Which repository, by its workspace id ("root" is the workspace itself).'),
+    path: z.string().describe("Where the declaration lives, relative to the workspace, whether or not the file exists yet."),
+    checks: z.array(RepoCheckSchema).describe("What it declares, in the order the file lists them."),
+    adopted: z
+        .boolean()
+        .describe("Whether these are running. False means declared and inert: nothing a repository writes runs until the owner switches it on."),
+    changed: z
+        .boolean()
+        .describe(
+            "Whether the declaration changed since it was adopted, which holds it until the owner looks again. True only for a repository that was adopted before.",
+        ),
+    error: z.string().optional().describe("Why the file could not be read, when it exists but does not parse. The checks list is empty in that case."),
+});
+export type RepoChecksSummary = z.infer<typeof RepoChecksSummarySchema>;
+export const RepoChecksListSchema = z.object({
+    repos: z.array(RepoChecksSummarySchema).describe("Every repository that declares checks, plus any the owner has adopted before, sorted by id."),
+});
+export type RepoChecksList = z.infer<typeof RepoChecksListSchema>;
+export const RepoChecksAdoptSchema = z.object({
+    repo: z.string().min(1).describe("Which repository's declaration to switch."),
+    on: z
+        .boolean()
+        .describe("On adopts what it declares as it stands now; off stops running it. Adopting again is how a changed declaration is accepted."),
+});
+export type RepoChecksAdopt = z.infer<typeof RepoChecksAdoptSchema>;

package/src/schemas/settings.ts

@@ -369,8 +369,18 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Whether a turn killed by the sandbox restarting is re-run once it comes back. Off to begin with, for the same reason: it would spend your allowance on work you are not watching and edit files while you are still waiting for the sandbox to return. Either way the interruption is recorded rather than silently lost.",
         ),
+    // Which repositories' own declarations (`<repo>/.intentic/checks.json`) the owner has switched on, each against the
+    // fingerprint of what was declared when they did. A declaration that has since changed no longer matches its
+    // fingerprint and is held rather than run, which is what makes adoption a decision about a command rather than a
+    // permanent permission on a folder. Keyed by repo id, so `/` in the key is ordinary.
+    adoptedChecks: z
+        .record(z.string(), z.string())
+        .default({})
+        .describe(
+            "Which repositories may run the checks they declare for themselves, and exactly which version of those checks you agreed to. A repository's declaration does nothing until it appears here, the same rule git keeps for hooks, which are never cloned; and a declaration that changes afterwards is held until you look at it again.",
+        ),
     // Lives in the owner's own settings, not the workspace: a rule can hold work and gate a push, so it answers to the
-    // sandbox owner alone. Repo- or extension-contributed rules aren't supported yet.
+    // sandbox owner alone. A repository may declare a COMMAND of its own (see `adoptedChecks`), never a verdict.
     rules: z
         .array(RuleSchema)
         .max(50)
@@ -511,6 +521,22 @@ export const TierReportSchema = z.object({
     denied: z.number(),
 });
 export type TierReport = z.infer<typeof TierReportSchema>;
+// One dependency version or library improvement suggested or pinned.
+export const DependencyImprovementSchema = z.object({
+    prevented: z.string(),
+    chosen: z.string(),
+    reason: z.string(),
+    at: z.number().optional(),
+});
+export type DependencyImprovement = z.infer<typeof DependencyImprovementSchema>;
+// Rollup of registry freshness interventions over the queried day window.
+export const DependencySavingsSchema = z.object({
+    checked: z.number(),
+    improved: z.number(),
+    recent: z.array(DependencyImprovementSchema),
+    updatedAt: z.number().optional(),
+});
+export type DependencySavings = z.infer<typeof DependencySavingsSchema>;
 export const SavingsReportSchema = z.object({
     input: InputSavingsSchema,
     search: TurnExperimentSchema.optional(),
@@ -518,5 +544,6 @@ export const SavingsReportSchema = z.object({
     map: TurnExperimentSchema.optional(),
     // Automatic tier selection's readout, see TierReportSchema. Absent ⇒ nothing was judged in the window.
     tier: TierReportSchema.optional(),
+    dependencies: DependencySavingsSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;