@intentic/sandbox-contract 1.343.0 → 1.345.0

package/src/policy/keyring-origins.ts

@@ -0,0 +1,287 @@
+import { KEYRING_NAME_RE, type KeyringCaptureSource, type KeyringOrigin, type KeyringRemember } from "../schemas/keyring.js";
+
+// WHERE A CREDENTIAL BELONGS, in the two shapes the product keeps it in: an ORIGIN (schemas/keyring.ts), which is how a
+// capture, an agent's need and the Passwords app speak of it ("github.com", "ssh radar@build-01"), and an entry's RULES
+// (programs, packages, hosts, askpass matchers), which is how the keyring decides where a value may go. One file maps
+// each onto the other, names and titles a new entry, and finds the entry a capture updates, so the keyring, the
+// sandbox and the app agree on all four. Pure: no crypto, no I/O, safe in a browser bundle.
+
+/** The parts of an entry's rules an origin speaks to. */
+export interface OriginRules {
+    readonly programs: readonly string[];
+    readonly packages: readonly string[];
+    readonly hosts: readonly string[];
+    readonly askpass: readonly string[];
+}
+
+const EMPTY: OriginRules = { programs: [], packages: [], hosts: [], askpass: [] };
+
+/** A host as two captures of the same site agree on it: lower case, no trailing dot, no leading `www.`. */
+export const normalizeHost = (host: string): string =>
+    host
+        .trim()
+        .toLowerCase()
+        .replace(/\.$/u, "")
+        .replace(/^www\./u, "");
+
+// A program by its executable's file name, as Windows compares them: without case, without its folder.
+const programName = (program: string): string => (program.split(/[\\/]/u).pop() ?? program).toLowerCase();
+
+const hostOfUrl = (url: string): string | undefined => {
+    try {
+        return normalizeHost(new URL(url).host);
+    } catch {
+        // allow(silent-catch): a git remote named without a scheme is not an address to take a host from
+        return undefined;
+    }
+};
+
+/** `https://github.com/org/repo` → `https://github.com`: git asks per host, and an entry answers for all its repos. */
+export const gitOrigin = (url: string): string => {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.protocol}//${normalizeHost(parsed.host)}`;
+    } catch {
+        // allow(silent-catch): kept as written; it still matches itself
+        return url;
+    }
+};
+
+/** One string per place, so two captures of the same place compare equal. */
+export const originKey = (origin: KeyringOrigin): string => {
+    switch (origin.kind) {
+        case "site":
+            return `site:${normalizeHost(origin.host)}`;
+        case "program":
+            return `program:${programName(origin.program)}`;
+        case "package":
+            return `package:${origin.package}`;
+        case "ssh":
+            return `ssh:${origin.target.toLowerCase()}`;
+        case "ssh-key":
+            return `ssh-key:${origin.path}`;
+        case "sudo":
+            return `sudo:${origin.user ?? ""}`;
+        case "git":
+            return `git:${gitOrigin(origin.url)}`;
+        case "prompt":
+            return `prompt:${origin.sandbox ?? ""}:${origin.command ?? ""}:${origin.text.trim()}`;
+    }
+};
+
+/** The rules an entry needs to be used where `origin` is: what a captured credential's entry gets without anyone typing it. */
+export const rulesForOrigin = (origin: KeyringOrigin): OriginRules => {
+    switch (origin.kind) {
+        case "site":
+            return { ...EMPTY, hosts: [normalizeHost(origin.host)] };
+        case "program":
+            return { ...EMPTY, programs: [origin.program] };
+        case "package":
+            return { ...EMPTY, packages: [origin.package] };
+        case "ssh":
+            return { ...EMPTY, askpass: [`ssh:${origin.target}`] };
+        case "ssh-key":
+            return { ...EMPTY, askpass: [`ssh-key:${origin.path}`] };
+        case "sudo":
+            return { ...EMPTY, askpass: [origin.user === undefined ? "sudo" : `sudo:${origin.user}`] };
+        case "git": {
+            const host = hostOfUrl(origin.url);
+            return { ...EMPTY, askpass: [`git:${gitOrigin(origin.url)}`], hosts: host === undefined ? [] : [host] };
+        }
+        case "prompt":
+            // A sandbox terminal's prompt is no rule on this computer: the entry is found by its title, and shared on a need.
+            return origin.sandbox === undefined ? { ...EMPTY, askpass: [`prompt:${origin.text.trim()}`] } : EMPTY;
+    }
+};
+
+/** Two sets of rules as one, each list without repeats: how a second place is added to an entry. */
+export const mergeRules = (a: OriginRules, b: OriginRules): OriginRules => {
+    const union = (x: readonly string[], y: readonly string[]): string[] => [...new Set([...x, ...y])];
+    return { programs: union(a.programs, b.programs), packages: union(a.packages, b.packages), hosts: union(a.hosts, b.hosts), askpass: union(a.askpass, b.askpass) };
+};
+
+// An askpass matcher back into the origin it was made from; undefined for one this file did not make.
+const originOfMatcher = (matcher: string): KeyringOrigin | undefined => {
+    const colon = matcher.indexOf(":");
+    const head = colon === -1 ? matcher : matcher.slice(0, colon);
+    const rest = colon === -1 ? "" : matcher.slice(colon + 1);
+    switch (head) {
+        case "ssh":
+            return rest === "" ? undefined : { kind: "ssh", target: rest };
+        case "ssh-key":
+            return rest === "" ? undefined : { kind: "ssh-key", path: rest };
+        case "sudo":
+            return rest === "" ? { kind: "sudo" } : { kind: "sudo", user: rest };
+        case "git":
+            return rest === "" ? undefined : { kind: "git", url: rest };
+        case "prompt":
+            return rest === "" ? undefined : { kind: "prompt", text: rest };
+        default:
+            return undefined;
+    }
+};
+
+/** Every place an entry's rules say it is used, for the app's "Works on" chips. A `*.domain` host reads as the domain. */
+export const originsOfRules = (rules: OriginRules): KeyringOrigin[] => {
+    const fromAskpass = rules.askpass.map(originOfMatcher).filter((origin): origin is KeyringOrigin => origin !== undefined);
+    // A git entry's host is said by its `git:` matcher; listing the site again would say it twice.
+    const gitHosts = new Set(fromAskpass.flatMap((origin) => (origin.kind === "git" ? [hostOfUrl(origin.url)] : [])));
+    return [
+        ...rules.hosts.map((host) => host.replace(/^\*\./u, "")).filter((host) => !gitHosts.has(normalizeHost(host))).map((host): KeyringOrigin => ({ kind: "site", host })),
+        ...rules.programs.map((program): KeyringOrigin => ({ kind: "program", program })),
+        ...rules.packages.map((pkg): KeyringOrigin => ({ kind: "package", package: pkg })),
+        ...fromAskpass,
+    ];
+};
+
+const hostServes = (host: string, pattern: string): boolean => {
+    const want = normalizeHost(host);
+    const wildcard = pattern.startsWith("*.");
+    const base = normalizeHost(wildcard ? pattern.slice(2) : pattern);
+    // A saved `github.com` also fills `gist.github.com`, as every password manager's site matching does.
+    return want === base || want.endsWith(`.${base}`);
+};
+
+/** Whether an entry with these rules is the one for `origin`: the test a need, a fill and a capture all use. */
+export const rulesServe = (rules: OriginRules, origin: KeyringOrigin): boolean => {
+    switch (origin.kind) {
+        case "site":
+            return rules.hosts.some((pattern) => hostServes(origin.host, pattern));
+        case "program": {
+            const want = programName(origin.program);
+            return rules.programs.some((program) => programName(program) === want);
+        }
+        case "package":
+            return rules.packages.includes(origin.package);
+        case "git": {
+            const want = `git:${gitOrigin(origin.url)}`;
+            const host = hostOfUrl(origin.url);
+            return rules.askpass.some((matcher) => matcher.startsWith("git:") && `git:${gitOrigin(matcher.slice(4))}` === want) || (host !== undefined && rules.hosts.some((pattern) => hostServes(host, pattern)));
+        }
+        case "ssh":
+        case "ssh-key":
+        case "sudo":
+        case "prompt": {
+            const wanted = rulesForOrigin(origin).askpass;
+            return wanted.length > 0 && rules.askpass.some((matcher) => wanted.includes(matcher));
+        }
+    }
+};
+
+const sameUser = (a: string | undefined, b: string | undefined): boolean => (a ?? "").trim().toLowerCase() === (b ?? "").trim().toLowerCase();
+
+/** What a capture is compared against: each entry's name, the rules that place it, and the account it signs in as. */
+export interface CaptureCandidate {
+    readonly name: string;
+    readonly rules: OriginRules;
+    readonly username?: string | undefined;
+    readonly title?: string | undefined;
+}
+
+/**
+ * The entry a capture updates: one used at the same place for the same account. Undefined: the capture is a new entry,
+ * even where the place has entries for other accounts (a second GitHub login is a second entry, not an overwrite).
+ */
+export const findCaptureTarget = <T extends CaptureCandidate>(entries: readonly T[], origin: KeyringOrigin, username: string | undefined): T | undefined =>
+    entries.find((entry) => rulesServe(entry.rules, origin) && sameUser(entry.username, username)) ??
+    // A sandbox terminal's prompt places nothing on this computer, so its entry is found by the title it was given.
+    (origin.kind === "prompt" && origin.sandbox !== undefined ? entries.find((entry) => entry.title === titleForOrigin(origin) && sameUser(entry.username, username)) : undefined);
+
+/** Entries that serve `origin`, the given account first: what a need, a browser's or a phone's fill offers. */
+export const entriesFor = <T extends CaptureCandidate>(entries: readonly T[], origin: KeyringOrigin, username?: string): T[] => {
+    const serving = entries.filter((entry) => rulesServe(entry.rules, origin));
+    return username === undefined ? serving : [...serving.filter((entry) => sameUser(entry.username, username)), ...serving.filter((entry) => !sameUser(entry.username, username))];
+};
+
+const baseName = (path: string): string => path.split(/[\\/]/u).pop() ?? path;
+
+/** What a person calls the place: `github.com`, `FortiClient VPN`, `ssh radar@build-01`, `sudo`, `git github.com`. */
+export const titleForOrigin = (origin: KeyringOrigin, given?: string): string => {
+    const named = given?.trim();
+    if (named !== undefined && named !== "") {
+        return named.slice(0, 200);
+    }
+    switch (origin.kind) {
+        case "site":
+            return normalizeHost(origin.host);
+        case "program":
+            return origin.label ?? baseName(origin.program).replace(/\.exe$/iu, "");
+        case "package":
+            return origin.label ?? origin.package.split(".").pop() ?? origin.package;
+        case "ssh":
+            return `ssh ${origin.target}`;
+        case "ssh-key":
+            return `ssh key ${baseName(origin.path)}`;
+        case "sudo":
+            return origin.user === undefined ? "sudo" : `sudo as ${origin.user}`;
+        case "git":
+            return `git ${hostOfUrl(origin.url) ?? origin.url}`;
+        case "prompt":
+            return origin.command ?? origin.text.replace(/[:\s]+$/u, "");
+    }
+};
+
+const NAME_MAX = 128;
+
+// Upper case, every run of anything else one underscore, never starting with a digit: the shape a reference takes.
+const referenceName = (text: string): string => {
+    const upper = text
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/gu, "")
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/gu, "_")
+        .replace(/^_+|_+$/gu, "");
+    const named = upper === "" ? "PASSWORD" : /^[0-9]/u.test(upper) ? `_${upper}` : upper;
+    return named.slice(0, NAME_MAX).replace(/_+$/u, "");
+};
+
+/**
+ * A new entry's name, the `{{secret:NAME}}` an agent writes: from its title (`GITHUB_COM`), then with the account
+ * (`GITHUB_COM_RADARSU`) when that is taken, then numbered. Always matches KEYRING_NAME_RE.
+ */
+export const entryNameFor = (title: string, username: string | undefined, taken: (name: string) => boolean): string => {
+    const base = referenceName(title);
+    const tries = [base];
+    if (username !== undefined && username.trim() !== "") {
+        tries.push(referenceName(`${base}_${username.split("@")[0] ?? username}`));
+    }
+    for (const name of tries) {
+        if (!taken(name) && KEYRING_NAME_RE.test(name)) {
+            return name;
+        }
+    }
+    const stem = (tries.at(-1) ?? base).slice(0, NAME_MAX - 6);
+    for (let n = 2; ; n++) {
+        const name = `${stem}_${String(n)}`;
+        if (!taken(name)) {
+            return name;
+        }
+    }
+};
+
+/**
+ * The remember switch a capture source needs on, or undefined for a deliberate act (an import, an agent's `secrets ask`,
+ * adding by hand) that needs none.
+ */
+export const rememberSwitchFor = (source: KeyringCaptureSource): keyof KeyringRemember | undefined => {
+    switch (source) {
+        case "browser":
+            return "browser";
+        case "askpass":
+        case "git":
+            return "terminal";
+        case "app":
+            return "apps";
+        case "phone":
+            return "phone";
+        case "terminal":
+            return "sandbox";
+        case "import":
+        case "agent":
+        case "manual":
+            return undefined;
+    }
+};
+
+/** Remembering off everywhere: a vault's settings before the person's one yes. */
+export const REMEMBER_NOTHING: KeyringRemember = { browser: false, terminal: false, apps: false, phone: false, sandbox: false };

package/src/policy/keyring-seal.test.ts

@@ -1,5 +1,24 @@
-import type { KeyringGrant } from "../schemas/keyring.js";
-import { grantNonce, keyFingerprint, newSealKeyPair, newSignKeyPair, seal, signGrant, unseal, verifyGrant } from "./keyring-seal.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import type { KeyringGrant, SealedBox } from "../schemas/keyring.js";
+import { SealedBoxSchema } from "../schemas/keyring.js";
+import { grantNonce, keyFingerprint, newSealKeyPair, newSignKeyPair, seal, sealWithEphemeral, signGrant, unseal, verifyGrant, type SealPurpose } from "./keyring-seal.js";
+
+const goldenPath = join(packageRoot(import.meta.url), "golden", "keyring-seal.json");
+const golden = JSON.parse(readFileSync(goldenPath, "utf8")) as {
+    recipient: { publicKey: string; privateKey: string };
+    phone: { publicKey: string; privateKey: string };
+    vectors: Array<{
+        name: string;
+        plaintext: string;
+        purpose: SealPurpose;
+        ephemeral: { publicKey: string; privateKey: string };
+        iv: string;
+        box: SealedBox;
+    }>;
+    unseal: { phonePlaintext: string; phonePurpose: SealPurpose };
+};
 
 const SANDBOX = "https://a1b2c3d4e5f6.intentic.dev";
 
@@ -91,3 +110,19 @@ describe("grants", () => {
 test("fingerprints read in groups of four", () => {
     expect(keyFingerprint(newSealKeyPair().publicKey)).toMatch(/^[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}$/u);
 });
+
+describe("golden vectors (shared with the Android app)", () => {
+    test.each(golden.vectors)("$name seals to the golden box", ({ name, plaintext, purpose, ephemeral, iv, box }) => {
+        const recipient = name === "phone" ? golden.phone.publicKey : golden.recipient.publicKey;
+        const rebuilt = sealWithEphemeral(recipient, plaintext, purpose, ephemeral, Buffer.from(iv, "base64url"));
+        expect(rebuilt).toEqual(SealedBoxSchema.parse(box));
+    });
+
+    test("the phone opens the golden phone box", () => {
+        const phoneVector = golden.vectors.find((vector) => vector.name === "phone");
+        if (phoneVector === undefined) {
+            throw new Error("the golden file has no phone vector");
+        }
+        expect(unseal(golden.phone, phoneVector.box, phoneVector.purpose)).toBe(golden.unseal.phonePlaintext);
+    });
+});

package/src/policy/keyring-seal.ts

@@ -51,7 +51,12 @@ export type SealPurpose =
     | { readonly kind: "type"; readonly sandbox: string; readonly secret: string; readonly nonce: string }
     | { readonly kind: "inbox"; readonly sandbox: string; readonly secret: string }
     | { readonly kind: "copy"; readonly sandbox: string; readonly secret: string; readonly updatedAt: number }
-    | { readonly kind: "sync"; readonly account: string; readonly device: string; readonly revision: number };
+    | { readonly kind: "sync"; readonly account: string; readonly device: string; readonly revision: number }
+    // A credential seen in use and sent to be kept (schemas/keyring.ts KeyringCaptureItem): bound to who saw it and when,
+    // so a box lifted from one capture cannot be replayed as another's.
+    | { readonly kind: "capture"; readonly via: string; readonly at: number }
+    // A value released to a paired phone for one autofill (KeyringPhoneFill), bound to that request's nonce.
+    | { readonly kind: "phone"; readonly device: string; readonly nonce: string };
 
 export const sealAad = (purpose: SealPurpose): Buffer => {
     switch (purpose.kind) {
@@ -64,21 +69,42 @@ export const sealAad = (purpose: SealPurpose): Buffer => {
             return Buffer.from(`copy\0${purpose.sandbox}\0${purpose.secret}\0${String(purpose.updatedAt)}`, "utf8");
         case "sync":
             return Buffer.from(`sync\0${purpose.account}\0${purpose.device}\0${String(purpose.revision)}`, "utf8");
+        case "capture":
+            return Buffer.from(`capture\0${purpose.via}\0${String(purpose.at)}`, "utf8");
+        case "phone":
+            return Buffer.from(`phone\0${purpose.device}\0${purpose.nonce}`, "utf8");
     }
 };
 
 const boxKey = (shared: Buffer, epk: string, recipient: string): Buffer =>
     Buffer.from(hkdfSync("sha256", shared, Buffer.concat([Buffer.from(epk, "base64url"), Buffer.from(recipient, "base64url")]), SEAL_INFO, 32));
 
+// Seals `plaintext` to the holder of `recipient`'s private half, for `purpose` alone, with a caller-chosen ephemeral
+// key and IV. The phone app's unit tests and golden/keyring-seal.json call this with fixed inputs so Kotlin can match.
+export const sealWithEphemeral = (
+    recipient: string,
+    plaintext: string,
+    purpose: SealPurpose,
+    ephemeralPair: KeyringKeyPair,
+    iv: Buffer,
+): SealedBox => {
+    const shared = diffieHellman({ privateKey: privateKeyOf("X25519", ephemeralPair), publicKey: publicKeyOf("X25519", recipient) });
+    const cipher = createCipheriv("aes-256-gcm", boxKey(shared, ephemeralPair.publicKey, recipient), iv);
+    cipher.setAAD(sealAad(purpose));
+    const data = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    return {
+        v: 1,
+        epk: ephemeralPair.publicKey,
+        iv: iv.toString("base64url"),
+        tag: cipher.getAuthTag().toString("base64url"),
+        data: data.toString("base64url"),
+    };
+};
+
 // Seals `plaintext` to the holder of `recipient`'s private half, for `purpose` alone.
 export const seal = (recipient: string, plaintext: string, purpose: SealPurpose): SealedBox => {
     const ephemeral = newSealKeyPair();
-    const shared = diffieHellman({ privateKey: privateKeyOf("X25519", ephemeral), publicKey: publicKeyOf("X25519", recipient) });
-    const iv = randomBytes(12);
-    const cipher = createCipheriv("aes-256-gcm", boxKey(shared, ephemeral.publicKey, recipient), iv);
-    cipher.setAAD(sealAad(purpose));
-    const data = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-    return { v: 1, epk: ephemeral.publicKey, iv: iv.toString("base64url"), tag: cipher.getAuthTag().toString("base64url"), data: data.toString("base64url") };
+    return sealWithEphemeral(recipient, plaintext, purpose, ephemeral, randomBytes(12));
 };
 
 // Opens a box sealed to `pair` for `purpose`; throws on any way of not being one (malformed, another key, another purpose).

package/src/policy/safety-policy.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { COMMAND_CLASS_LABELS, COMMAND_CLASS_PATTERNS, type CommandPattern } from "./command-classes.js";
-import { type CommandClass, CommandClassSchema, type CommandLocus, CommandLocusSchema } from "../schemas/agent.js";
+import { type CommandClass, CommandClassSchema, type CommandLocus, CommandLocusSchema } from "../schemas/command-admission.js";
 
 // The owner's safety policy as prose, judged by a model rather than a table of verdicts, since deciding whether a
 // command is malicious takes understanding a regex can't reach. Patterns (command-classes.ts) are now just triage,

package/src/policy/tests/safety-policy.test.ts

@@ -1,6 +1,6 @@
 import { COMMAND_CLASS_LABELS, COMMAND_CLASS_PATTERNS } from "../command-classes.js";
 import { COMMAND_RULE_CATALOG, DEFAULT_SAFETY_POLICY, hardRuleClasses } from "../safety-policy.js";
-import { CommandClassSchema, CommandLocusSchema } from "../../schemas/agent.js";
+import { CommandClassSchema, CommandLocusSchema } from "../../schemas/command-admission.js";
 
 // The hard rule is the one thing on this page nobody can argue with, so it's pinned here rather than trusted to review:
 // a class added silently is one an owner can never decide about for themselves.

package/src/policy/turned-away.ts

@@ -22,6 +22,7 @@ const TURNED_AWAY: ReadonlySet<string> = new Set([
     "sandbox-memory-low",
     // The conversation's own view of the workspace could not be set up in time: nothing was started in it.
     "workspace-setup",
+    "sandbox-disk-low",
     "trial-unavailable",
     "trial-model-unavailable",
     "trial-exhausted",
@@ -29,5 +30,20 @@ const TURNED_AWAY: ReadonlySet<string> = new Set([
     "engine-version-floor",
 ]);
 
+// The refusals about the model itself (its allowance, its account, its catalogue, its window), which another model
+// gets past: a turn one of these stops partway offers to carry on elsewhere rather than to wait.
+const ANOTHER_MODEL_CLEARS: ReadonlySet<string> = new Set([
+    "claude-not-entitled",
+    "context-window-too-small",
+    "model-helper-only",
+    "trial-unavailable",
+    "trial-model-unavailable",
+    "trial-exhausted",
+    "model-unavailable",
+]);
+
+/** Whether another model would get past a refusal: the trial's, the model's, or the account's on it. */
+export const anotherModelClears = (code: string | undefined): boolean => code !== undefined && ANOTHER_MODEL_CLEARS.has(code);
+
 /** Whether a failure code refuses a turn before the model sees any of it. */
 export const turnedAwayCode = (code: string | undefined): boolean => code !== undefined && TURNED_AWAY.has(code);

package/src/protocol/doors/host-protocol.ts

@@ -19,3 +19,6 @@ export type HostHello = z.infer<typeof HostHelloSchema>;
 // The URL the machine's agent dials, given the sandbox's public URL. Carries no credential (the token rides the hello
 // frame); one place builds it, so the agent and the daemon route can't disagree.
 export const hostConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/hosts/connect`;
+
+// Where a connected machine tells its sandbox that Passwords shares changed (2026-10-20), bearer-authenticated.
+export const hostKeyringChangedUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/hosts/keyring-changed`;

package/src/protocol/doors/webext-links.ts

@@ -22,6 +22,9 @@ export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.repla
 // are: a tool answer over the socket lands in the model's context, and this value must never reach one.
 export const webextSecretUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/secret`;
 
+// Where the extension tells its sandbox that site access changed outside the popup (2026-10-20), bearer-authenticated.
+export const webextGrantsChangedUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/grants-changed`;
+
 // The tool the daemon calls on a browser to type a secret into its focused field, taking only a ticket the daemon
 // minted for that one call. The agent's own mount of the browser never lists it (webext-peer.ts): a model holding the
 // tool would hold nothing it could use, so it is not offered.

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

@@ -47,16 +47,22 @@ class FakeSocket implements SocketLike {
 // This door's silence deadline, named so the assertions can read it off the same number the loop is given.
 const SILENCE_MS = 30_000;
 
-// A ladder that answers with a fixed delay and records what it was told, so the test can read the held time.
+// A ladder that answers with a fixed delay and records what it was told, so the test can read the held time, and how
+// often it was put back on its floor.
 const ladder = (delay = 1_000) => {
     const held: number[] = [];
-    return {
+    const rungs = {
         held,
+        resets: 0,
         next: (heldMs: number) => {
             held.push(heldMs);
             return delay;
         },
+        reset: () => {
+            rungs.resets += 1;
+        },
     };
+    return rungs;
 };
 
 const dialling = (delay?: number) => {
@@ -64,6 +70,7 @@ const dialling = (delay?: number) => {
     const attached: FakeSocket[] = [];
     const said: string[] = [];
     const revoked = jest.fn();
+    const backoff = ladder(delay);
     const link = dialPeer<FakeSocket>({
         open: async () => {
             const socket = new FakeSocket();
@@ -72,12 +79,12 @@ const dialling = (delay?: number) => {
         },
         hello: () => ({ type: "hello", token: "iht_test", version: "1.0.0" }),
         attach: (socket) => void attached.push(socket),
-        backoff: ladder(delay),
+        backoff,
         silenceMs: SILENCE_MS,
         log: (message) => void said.push(message),
         revoked,
     });
-    return { link, sockets, attached, said, revoked };
+    return { link, sockets, attached, said, revoked, backoff };
 };
 
 test("the handler is attached before the hello goes out, and the hello is the first frame", async () => {
@@ -305,6 +312,85 @@ test("a link nobody has answered in a long time rests between tries, and is neve
     }
 });
 
+/* A FAR END SOMEBODY KNOWS IS BACK (a sandbox the machine agent just woke) is dialled at once, whatever the ladder had
+   left to wait, and a dial that still finds it booting is back on the ladder's first rung, not on the long rest. */
+test("retryNow ends the long rest and dials at once, and the outage behind it no longer counts", async () => {
+    jest.useFakeTimers();
+    try {
+        const RUNG_MS = 30_000;
+        const { link, sockets, said, backoff } = dialling(RUNG_MS);
+        for (let attempt = 1; attempt <= LONG_OUTAGE_ATTEMPTS; attempt += 1) {
+            // one drop per attempt is serial by definition
+            await waitFor(() => expect(sockets).toHaveLength(attempt));
+            sockets.at(-1)?.drops(1006);
+            if (attempt < LONG_OUTAGE_ATTEMPTS) {
+                // ditto
+                await advanceTimersByTimeAsync(RUNG_MS);
+            }
+        }
+        // Resting now: the long outage's quarter hour on top of the rung.
+        expect(link.outage()).toEqual({ failures: LONG_OUTAGE_ATTEMPTS, since: expect.any(Number) });
+        await advanceTimersByTimeAsync(RUNG_MS);
+        expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS);
+
+        link.retryNow();
+        await waitFor(() => expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS + 1));
+        expect(backoff.resets).toBe(1);
+        expect(link.outage()).toBeUndefined();
+        expect(link.state()).toBe("connecting");
+
+        // Still booting: the first failure of a new outage, said out loud, waits one rung and no rest.
+        sockets.at(-1)?.drops(PEER_TRY_AGAIN);
+        expect(said.at(-1)).toBe("the sandbox is not ready to admit this connection yet; reconnecting in 30s");
+        expect(link.outage()).toEqual({ failures: 1, since: expect.any(Number) });
+        await advanceTimersByTimeAsync(RUNG_MS);
+        await waitFor(() => expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS + 2));
+
+        // Nothing of the cut wait is left to fire (the one dial it owed has been made): the open socket's watchdog is
+        // the one timer armed.
+        sockets.at(-1)?.opens();
+        expect(link.state()).toBe("open");
+        expect(jest.getTimerCount()).toBe(1);
+
+        link.stop();
+        await link.done;
+    } finally {
+        jest.useRealTimers();
+    }
+});
+
+test("retryNow dials nothing beside an open link or a dial in flight, and nothing once the link is stopped", async () => {
+    jest.useFakeTimers();
+    try {
+        const { link, sockets, backoff } = dialling(60_000);
+        await waitFor(() => expect(sockets).toHaveLength(1));
+        // In flight: no second dial beside it, though its ladder is reset so a failure of it retries on the floor.
+        link.retryNow();
+        await advanceTimersByTimeAsync(0);
+        expect(sockets).toHaveLength(1);
+        expect(backoff.resets).toBe(1);
+
+        sockets[0]?.opens();
+        link.retryNow();
+        await advanceTimersByTimeAsync(0);
+        expect(sockets).toHaveLength(1);
+        expect(backoff.resets).toBe(1);
+        expect(link.state()).toBe("open");
+
+        sockets[0]?.drops(1006);
+        link.stop();
+        await link.done;
+        link.retryNow();
+        await advanceTimersByTimeAsync(120_000);
+        expect(sockets).toHaveLength(1);
+        expect(backoff.resets).toBe(1);
+        expect(jest.getTimerCount()).toBe(0);
+        expect(link.state()).toBe("closed");
+    } finally {
+        jest.useRealTimers();
+    }
+});
+
 // A stop that lands while the address is still being decided has nothing to close and must open nothing after
 // the fact: a socket dialled by a loop that has already reported itself done would be a connection nobody stops.
 test("a stop during resolution opens nothing, and a socket a slow resolver still hands over is closed", async () => {