@intentic/sandbox-contract 1.344.0 → 1.346.0

package/src/schemas/hosts.ts

@@ -21,6 +21,22 @@ export const MachineIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{7,1
 export const derivedMachineId = (card: string): string => `card:${card}`;
 export const isDerivedMachineId = (machineId: string): boolean => machineId.startsWith("card:");
 
+// Which computer and which OS install on it is enrolling (`environmentKeyOf`), as the machine agent says it when it
+// redeems a pairing. Both optional, since an agent older than either says nothing.
+export const MachineIdentitySchema = z.object({
+    machineId: MachineIdSchema.optional(),
+    environment: z.string().min(1).optional(),
+});
+export type MachineIdentity = z.infer<typeof MachineIdentitySchema>;
+
+// (2026-10-20) The body of POST /system/hosts/enroll: the redeeming agent's identity, so the enrollment is written with
+// its real machine id instead of the card's derived one and joins that machine's sync row from its first write. Before
+// this the route took no body and the id was learned only at the agent's first connect, which left a freshly paired
+// computer as two machine cards until then. An agent older than it sends none, and the daemon reads one it cannot parse
+// as none. Kept here rather than beside the answer (peer-enrollment.ts), which the browser extension bundles.
+export const PeerEnrollmentRequestSchema = MachineIdentitySchema;
+export type PeerEnrollmentRequest = MachineIdentity;
+
 // How many skipped lines an agent sends in its upkeep summary at most; the counts cover the rest.
 export const UPKEEP_SKIPPED_SHOWN = 10;
 
@@ -113,6 +129,11 @@ export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 // - `keyring`: the keyring* procedures, intentic-keyring on this computer reached through the machine (keyring.ts);
 //   advertised only while a keyring is installed, so a sandbox never offers a computer without one as a place to keep or
 //   type a secret.
+// - `sleep`: the `sleep` op, a sandbox put to sleep now (`ic sandbox sleep <slug>`): stopped, and started again by
+//   itself when somebody opens it; advertised only when the agent's `ic` has `sandbox sleep`.
+// - `reachable-ways-back`: not an op but what a listing means: a sandbox's `rollbackTargets` are only the ways back a
+//   rollback can reach (ic 2026-10-19 on). Said by ic itself (`ic features`, golden/ic-features.json); without it the
+//   rows are an older ic's, which also listed pruned dev builds no download can bring back (state/ways-back.ts).
 export const DeviceFeatureSchema = z.enum([
     "reshape-later",
     "set-shape",
@@ -122,6 +143,8 @@ export const DeviceFeatureSchema = z.enum([
     "project-delivery",
     "programs",
     "keyring",
+    "sleep",
+    "reachable-ways-back",
 ]);
 export type DeviceFeature = z.infer<typeof DeviceFeatureSchema>;
 export const DEVICE_FEATURE_RESHAPE_LATER: DeviceFeature = "reshape-later";
@@ -132,6 +155,12 @@ export const DEVICE_FEATURE_BACKGROUND_PREPARE: DeviceFeature = "background-prep
 export const DEVICE_FEATURE_PROJECT_DELIVERY: DeviceFeature = "project-delivery";
 export const DEVICE_FEATURE_PROGRAMS: DeviceFeature = "programs";
 export const DEVICE_FEATURE_KEYRING: DeviceFeature = "keyring";
+export const DEVICE_FEATURE_SLEEP: DeviceFeature = "sleep";
+export const DEVICE_FEATURE_REACHABLE_WAYS_BACK: DeviceFeature = "reachable-ways-back";
+// What `ic features --json` answers (_sandbox/ic/src/features.rs, golden/ic-features.json): the optional ops that ic
+// implements, as strings, since a newer ic's word means nothing to an older agent.
+export const IcFeaturesAnswerSchema = z.object({ features: z.array(z.string()) });
+
 // The features an agent advertised that this build knows; an unknown one is a newer agent's and means nothing here.
 export const deviceFeatures = (facts: Pick<DeviceFacts, "features"> | undefined): DeviceFeature[] =>
     (facts?.features ?? []).flatMap((feature) => {
@@ -204,6 +233,34 @@ export const HostEnvironmentSchema = z.object({
 });
 export type HostEnvironment = z.infer<typeof HostEnvironmentSchema>;
 
+// HOW MUCH OF ONE COMPUTER ANSWERS RIGHT NOW (2026-10-20), read off its environments' own sockets: the one answer
+// /capabilities, the Devices board and a call's routing give about a machine. `online` while its native side answers
+// (the one named after the card, which owns the screen and every tool but `run_command`'s crossing), whatever its
+// distros do, since a distro asleep beside a live Windows is the ordinary state of a PC; `partly` while the native side
+// does not and another environment does (a call naming that side still reaches it); `offline` while nothing does. Before
+// this the card read the native side alone and the board any side, so one PC was offline on one screen and live on the
+// next (2026-10-13), and "partly" was worked out twice more. A list with no native side at all (a machine seen only
+// through a distro's sync) is online while anything of it answers.
+export type MachinePresence =
+    | { readonly kind: "online" }
+    | { readonly kind: "partly"; readonly awake: readonly string[] }
+    | { readonly kind: "offline" };
+
+export const machinePresence = (environments: readonly Pick<HostEnvironment, "key" | "online">[]): MachinePresence => {
+    const native = environments.find((environment) => environment.key === HOST_NATIVE_ENVIRONMENT);
+    const awake = environments
+        .filter((environment) => environment.key !== HOST_NATIVE_ENVIRONMENT && environment.online)
+        .map((environment) => environment.key)
+        .toSorted();
+    if (native?.online === true || (native === undefined && awake.length > 0)) {
+        return { kind: "online" };
+    }
+    return awake.length > 0 ? { kind: "partly", awake } : { kind: "offline" };
+};
+
+// An environment by the name a person and `run_command`'s `in` know it by: a distro by its WSL name, the rest by key.
+export const environmentName = (key: string): string => (key.startsWith("wsl:") ? key.slice("wsl:".length) : key);
+
 export const HostSummarySchema = z.object({
     // The capability id, the machine's name, and the prefix of its tools (mcp__<id>__run_command). On a per-connection
     // row (`hostConnections`) it is that connection's key instead, and `card` names the machine.
@@ -221,6 +278,9 @@ export const HostSummarySchema = z.object({
     // Epoch ms of the last held socket; absent means not since this daemon booted (liveness resets on restart).
     lastSeen: z.number().optional(),
     facts: DeviceFactsSchema.optional(),
+    // The card's "Manage sandboxes on this device" switch is on: a container verb sent to this machine (create, start,
+    // remove…) is let through rather than refused by the machine. Absent from a daemon older than it.
+    manages: z.boolean().optional(),
 });
 export type HostSummary = z.infer<typeof HostSummarySchema>;
 export const HostsListSchema = z.object({ hosts: z.array(HostSummarySchema) });

package/src/schemas/keyring-native.test.ts

@@ -0,0 +1,13 @@
+import { KEYRING_NAME_RE, KeyringCaptureOutcomeSchema, KeyringRefusalCodeSchema } from "./keyring.js";
+import { KeyringNativeNameSchema, KeyringNativeOutcomeSchema, KeyringNativeRefusalCodeSchema } from "./keyring-native.js";
+
+// keyring-native.ts spells three of keyring.ts's schemas again so the browser extension's bundle never reaches keyring.ts
+// (and the zod namespace it imports); these hold the two spellings equal.
+
+test("the extension's copies of keyring.ts's names, refusals and outcomes are the same", () => {
+    expect(KeyringNativeRefusalCodeSchema.options).toEqual(KeyringRefusalCodeSchema.options);
+    expect(KeyringNativeOutcomeSchema.options).toEqual(KeyringCaptureOutcomeSchema.options);
+    for (const name of ["GITHUB_COM", "_1PASSWORD", "a", "1BAD", "has-dash", ""]) {
+        expect(KeyringNativeNameSchema.safeParse(name).success).toBe(KEYRING_NAME_RE.test(name));
+    }
+});

package/src/schemas/keyring-native.ts

@@ -0,0 +1,101 @@
+// Named imports rather than the `z` namespace, and nothing from schemas/keyring.ts: this module is bundled into the
+// browser extension, where the namespace keeps zod's locales (~330 kB) that esbuild can otherwise drop
+// (_devices/webext/scripts/size-budget.mjs holds the ceiling). The three schemas it shares with keyring.ts are spelled
+// again below, and keyring-native.test.ts holds them equal.
+import { array, boolean, discriminatedUnion, enum as zEnum, literal, number, object, string, union } from "zod";
+import type * as z from "zod";
+
+// What the browser extension and `intentic-keyring native-host` say to each other over Chrome's native messaging: one
+// JSON message each way per request, length-prefixed by the browser, correlated by `id`. The native host is a process
+// the browser starts as the person's user; it seals a captured value to the vault's inbox key before it reaches the
+// keyring's pipe, and asks the keyring (which asks the person, with Windows Hello or polkit) before any value goes back
+// to the page. A site's host, never a full address, is all the extension ever names.
+//
+// `@intentic/sandbox-contract/webext` re-exports it.
+
+/** The name the extension connects to (`chrome.runtime.connectNative`), and the native host's manifest declares. */
+export const KEYRING_NATIVE_HOST = "dev.intentic.keyring";
+
+const id = string().min(1).max(64);
+const host = string().min(1).max(253);
+
+/** keyring.ts's secret name, refusal code and capture outcome, as the extension sees them. */
+export const KeyringNativeNameSchema = string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/u);
+export const KeyringNativeRefusalCodeSchema = zEnum([
+    "no-keyring",
+    "locked",
+    "declined",
+    "unknown",
+    "not-shared",
+    "bad-grant",
+    "expired",
+    "replayed",
+    "guard",
+    "unavailable",
+    "busy",
+    "pending",
+]);
+export const KeyringNativeOutcomeSchema = zEnum(["saved", "updated", "unchanged", "pending", "skipped"]);
+
+export const KeyringNativeRequestSchema = discriminatedUnion("type", [
+    // What the extension needs before it shows anything: whether remembering is on for browsers, and the vault's state.
+    object({
+        type: literal("hello"),
+        id,
+        browser: string().min(1).max(100).describe("The browser's own name, `Brave`, for the title line."),
+    }).strict(),
+    // A sign-in, sign-up or password change the page just submitted.
+    object({
+        type: literal("capture"),
+        id,
+        browser: string().min(1).max(100),
+        host,
+        username: string().max(256).optional(),
+        password: string().min(1).max(4096),
+        title: string().max(200).optional().describe("The site's own name (`og:site_name`, the title), when it has one."),
+        failed: boolean().optional().describe("The form came back for the same user: the last value saved for it did not work."),
+    }).strict(),
+    // What the keyring holds for this site: names, titles and users, never values.
+    object({ type: literal("candidates"), id, host }).strict(),
+    // One entry's value for the focused field, after the person's yes at the computer.
+    object({ type: literal("fill"), id, host, name: KeyringNativeNameSchema }).strict(),
+    // Take back a capture made moments ago (the toast's Undo).
+    object({ type: literal("undo"), id, name: KeyringNativeNameSchema, at: number().int() }).strict(),
+    // Never save for this site (the toast's "Never for this site").
+    object({ type: literal("never"), id, host }).strict(),
+]);
+export type KeyringNativeRequest = z.infer<typeof KeyringNativeRequestSchema>;
+
+const refused = object({ ok: literal(false), code: KeyringNativeRefusalCodeSchema, refusal: string() });
+
+export const KeyringNativeCandidateSchema = object({ name: KeyringNativeNameSchema, title: string(), username: string().optional() });
+export type KeyringNativeCandidate = z.infer<typeof KeyringNativeCandidateSchema>;
+
+// A plain union: a refusal shares its `type` with the answer it stands in for, which a discriminated union cannot hold.
+export const KeyringNativeResponseSchema = union([
+    object({
+        type: literal("hello"),
+        id,
+        ok: literal(true),
+        setUp: boolean(),
+        locked: boolean(),
+        remember: boolean().describe("Whether the person turned on remembering for browsers."),
+        version: string(),
+    }),
+    object({
+        type: literal("capture"),
+        id,
+        ok: literal(true),
+        outcome: KeyringNativeOutcomeSchema,
+        name: KeyringNativeNameSchema.optional(),
+        title: string().optional(),
+        at: number().int(),
+    }),
+    object({ type: literal("candidates"), id, ok: literal(true), items: array(KeyringNativeCandidateSchema) }),
+    object({ type: literal("fill"), id, ok: literal(true), username: string().optional(), password: string() }),
+    object({ type: literal("undo"), id, ok: literal(true) }),
+    object({ type: literal("never"), id, ok: literal(true) }),
+    // Any request refused, under the type it was asked as.
+    refused.extend({ type: zEnum(["hello", "capture", "candidates", "fill", "undo", "never"]), id }),
+]);
+export type KeyringNativeResponse = z.infer<typeof KeyringNativeResponseSchema>;

package/src/schemas/keyring.ts

@@ -82,15 +82,28 @@ export const KeyringSandboxKeysSchema = z.object({
 });
 export type KeyringSandboxKeys = z.infer<typeof KeyringSandboxKeysSchema>;
 
+// The one-time "let Intentic remember the passwords you type", per source. All off until the person turns them on;
+// each switches off on its own. Imports, an agent's `secrets ask` and adding by hand are deliberate acts and need none.
+export const KeyringRememberSchema = z.object({
+    browser: z.boolean().describe("Sign-ins in a browser with the Intentic extension."),
+    terminal: z.boolean().describe("ssh, sudo and git prompts on this computer, and git's credential helper."),
+    apps: z.boolean().describe("Password fields in programs on this computer, typed once into the keyring's own box."),
+    phone: z.boolean().describe("The paired phone's autofill."),
+    sandbox: z.boolean().describe("Prompts that hide what is typed, in a sandbox terminal the person types into."),
+});
+export type KeyringRemember = z.infer<typeof KeyringRememberSchema>;
+
 export const KeyringStateSchema = z.object({
     version: z.string().describe("The keyring's own release."),
     locked: z.boolean().describe("Whether the vault is locked. Locked, `while-here` entries ask like `each-use` ones."),
     unlockedUntil: z.number().optional().describe("When the current unlock ends, in milliseconds. Absent while locked."),
     unlock: z
-        .array(z.enum(["hello", "passphrase"]))
-        .describe("How a person unlocks it here: Windows Hello, or the keyring's passphrase."),
+        .array(z.enum(["hello", "passphrase", "polkit"]))
+        .describe("How a person unlocks it here: Windows Hello, the keyring's passphrase (its recovery key), or polkit's own check on Linux."),
     keys: KeyringDeviceKeysSchema.optional().describe("Absent until the keyring is set up: there is no vault, so no inbox to seal a value to."),
     pendingInbox: z.number().int().nonnegative().describe("Values sent to be kept that wait for the next unlock."),
+    pendingCaptures: z.number().int().nonnegative().optional().describe("Credentials seen in use while locked, kept sealed until the next unlock. Absent from a keyring older than 2026-10-19."),
+    remember: KeyringRememberSchema.optional().describe("Which sources the person let the keyring remember passwords from, so a collector knows whether to send one. Absent before setup and from an older keyring."),
 });
 export type KeyringState = z.infer<typeof KeyringStateSchema>;
 
@@ -173,9 +186,9 @@ export const SealedBoxSchema = z
 export type SealedBox = z.infer<typeof SealedBoxSchema>;
 
 export const KeyringRefusalCodeSchema = z
-    .enum(["no-keyring", "locked", "declined", "unknown", "not-shared", "bad-grant", "expired", "replayed", "guard", "unavailable", "busy"])
+    .enum(["no-keyring", "locked", "declined", "unknown", "not-shared", "bad-grant", "expired", "replayed", "guard", "unavailable", "busy", "pending"])
     .describe(
-        "Why: no keyring here; locked with nobody to unlock it; the person said no; no such entry; not shared with this sandbox; a grant that does not verify; one past its time; one already spent; the focused window or field is not one it may go to; its password manager did not answer; another prompt is open.",
+        "Why: no keyring here; locked with nobody to unlock it; the person said no; no such entry; not shared with this sandbox; a grant that does not verify; one past its time; one already spent; the focused window or field is not one it may go to; its password manager did not answer; another prompt is open; nobody has answered yet, and the request waits in the Passwords app.",
     );
 export type KeyringRefusalCode = z.infer<typeof KeyringRefusalCodeSchema>;
 
@@ -275,3 +288,188 @@ export const KeyringSyncPairResultSchema = z.discriminatedUnion("ok", [z.object(
 export const KeyringSyncOutboxSchema = z.object({ items: z.array(KeyringSyncItemSchema) });
 export const KeyringSyncDeliverSchema = z.object({ items: z.array(KeyringSyncItemSchema).max(64) }).strict();
 export const KeyringSyncDeliverResultSchema = z.object({ accepted: z.number().int().nonnegative().describe("How many it took; the rest were not from a paired keyring or did not open.") });
+
+// ---- origins: where a credential is used, and where it was seen ----
+
+// One place a credential belongs to. An entry's rules (programs, packages, hosts, askpass matchers) are the keyring's
+// own record of the same thing; policy/keyring-origins.ts maps one onto the other, so a captured credential gets its
+// rules without anyone typing them and the Passwords app can say "Works on github.com, git https://github.com".
+export const KeyringOriginSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("site"), host: z.string().min(1).max(253).describe("The page's host, `github.com`; never a path.") }).strict(),
+    z
+        .object({
+            kind: z.literal("program"),
+            program: KeyringProgramSchema,
+            label: z.string().max(200).optional().describe("The program's own name for people, `FortiClient VPN`, when the window says it."),
+        })
+        .strict(),
+    z.object({ kind: z.literal("package"), package: KeyringPackageSchema, label: z.string().max(200).optional() }).strict(),
+    z.object({ kind: z.literal("ssh"), target: z.string().min(1).max(300).describe("`user@host`, as ssh's prompt names it.") }).strict(),
+    z.object({ kind: z.literal("ssh-key"), path: z.string().min(1).max(1000) }).strict(),
+    z.object({ kind: z.literal("sudo"), user: z.string().max(64).optional() }).strict(),
+    z.object({ kind: z.literal("git"), url: z.string().min(1).max(500).describe("`https://host`, as git's credential helper or askpass names it.") }).strict(),
+    z
+        .object({
+            kind: z.literal("prompt"),
+            text: z.string().min(1).max(300).describe("The prompt's own words, `Password for npm:`."),
+            command: z.string().max(200).optional().describe("The command that asked, `npm login`, when known."),
+            sandbox: z.string().url().optional().describe("The sandbox whose terminal asked, for a prompt seen there rather than on this computer."),
+        })
+        .strict(),
+]);
+export type KeyringOrigin = z.infer<typeof KeyringOriginSchema>;
+
+// Where a capture came from, for its title line ("saved from Brave") and its record.
+export const KeyringCaptureSourceSchema = z
+    .enum(["browser", "askpass", "git", "app", "phone", "terminal", "import", "agent", "manual"])
+    .describe(
+        "What saw it: the browser extension, an ssh/sudo/git prompt answered through the keyring, git's credential helper, a password field in an app on this computer, the phone's autofill, a sandbox terminal's prompt, an import, an agent's `secrets ask`, or the person adding it by hand.",
+    );
+export type KeyringCaptureSource = z.infer<typeof KeyringCaptureSourceSchema>;
+
+// A credential seen in use, sent to be kept. The value is sealed to the vault's inbox key for `{ kind: "capture" }`
+// (policy/keyring-seal.ts), so whoever carries it (the native-messaging host, the sandbox for a phone or a terminal)
+// holds ciphertext. Taken in without asking once the person turned remembering on for its source: bringing a value IN
+// reveals nothing, and an update keeps the old value in the entry's history, so a capture can be undone.
+export const KEYRING_CAPTURE_BATCH_MAX = 5000;
+export const KeyringCaptureItemSchema = z
+    .object({
+        origin: KeyringOriginSchema,
+        username: z.string().max(256).optional().describe("The account it signs in as, when the form or prompt said. Not a secret."),
+        sealed: SealedBoxSchema,
+        source: KeyringCaptureSourceSchema,
+        via: z.string().min(1).max(200).describe("Who saw it, in words for the title line: `Brave`, `Pixel 8`, `intentic-dev`. Also bound into the seal."),
+        kind: z.enum(["password", "text"]).default("password"),
+        title: z.string().max(200).optional().describe("The site's or app's own name, when it said one; the keyring derives one otherwise."),
+        at: z.number().int().describe("When it was seen, in milliseconds. Also bound into the seal."),
+        failed: z
+            .boolean()
+            .optional()
+            .describe("The last value captured for this origin and user did not work (ssh asked again, git erased it, the form came back): replace it rather than keep it as history."),
+    })
+    .strict();
+export type KeyringCaptureItem = z.infer<typeof KeyringCaptureItemSchema>;
+
+export const KeyringCaptureOutcomeSchema = z
+    .enum(["saved", "updated", "unchanged", "pending", "skipped"])
+    .describe(
+        "A new entry; a new value for an existing one (the old kept in its history); the same value it already had; kept sealed until the next unlock; not kept, because remembering is off for its source or its origin is on the never-save list.",
+    );
+export type KeyringCaptureOutcome = z.infer<typeof KeyringCaptureOutcomeSchema>;
+
+export const KeyringCaptureResultSchema = z.discriminatedUnion("ok", [
+    z.object({
+        ok: z.literal(true),
+        outcome: KeyringCaptureOutcomeSchema,
+        name: KeyringSecretNameSchema.optional().describe("The entry it went to. Absent while pending or skipped."),
+        title: z.string().optional().describe("That entry's title, for the 'Saved github.com' notice."),
+    }),
+    refusal,
+]);
+export type KeyringCaptureResult = z.infer<typeof KeyringCaptureResultSchema>;
+
+// ---- an agent's need: asked for by what it is for, not by name ----
+
+// A sandbox asking for a credential by where it is to be used. The keyring matches its entries by origin and asks the
+// person (with their OS's own check: Windows Hello, polkit, a phone's biometric signature) whether this sandbox may use
+// the one it found, and on what terms. Nothing about entries that do not match, nor about one the person declines,
+// reaches the sandbox. A match nobody answers waits in the Passwords app's Requests, and the sandbox learns of the yes
+// from its next `shares` read.
+export const KeyringNeedSchema = z
+    .object({
+        origin: KeyringOriginSchema,
+        username: z.string().max(256).optional().describe("The account wanted, when the agent knows it."),
+        detail: z.string().min(1).max(300).describe("What it is for, in words for the prompt: `sign in to push the release branch`."),
+        conversation: z.string().max(200).optional(),
+        purpose: z.enum(["agent", "owner"]).default("agent"),
+        typeOnce: z
+            .boolean()
+            .default(false)
+            .describe(
+                "Nothing matched on any of the owner's computers: offer the person here the keyring's type-once box. Without it, a keyring with no match answers `unknown` at once, so the sandbox can ask the next computer without a box opening on each.",
+            ),
+    })
+    .strict();
+export type KeyringNeed = z.infer<typeof KeyringNeedSchema>;
+
+export const KeyringNeedAnswerSchema = z
+    .enum(["once", "while-here", "always", "deny"])
+    .describe("The person's answer: this one use (an `each-use` share), unasked while unlocked, a copy in the sandbox, or no.");
+export type KeyringNeedAnswer = z.infer<typeof KeyringNeedAnswerSchema>;
+
+export const KeyringNeedResultSchema = z.discriminatedUnion("ok", [
+    z.object({
+        ok: z.literal(true),
+        pointer: KeyringPointerSchema.describe("The entry now shared with the asking sandbox, as its next `shares` read will also list it."),
+        asked: z.boolean(),
+        saved: z.boolean().describe("Nothing matched, and the person typed it once into the keyring's own box: a new entry, kept here and shared."),
+    }),
+    refusal,
+]);
+export type KeyringNeedResult = z.infer<typeof KeyringNeedResultSchema>;
+
+// A need that waits for an answer, as the Passwords app lists it.
+export const KeyringPendingNeedSchema = z.object({
+    id: z.string().regex(KEYRING_NONCE_RE),
+    sandbox: z.string().url(),
+    need: KeyringNeedSchema,
+    matches: z.array(KeyringSecretNameSchema).describe("The entries that fit, best first. Empty: none yet, the app offers to type one once."),
+    at: z.number().int(),
+});
+export type KeyringPendingNeed = z.infer<typeof KeyringPendingNeedSchema>;
+
+// ---- the owner's phone as a place to save and fill ----
+
+// A phone paired with the keyring holds two keys made in its Android Keystore: `seal` (X25519, kept in software, which
+// Android's Keystore cannot do natively) that a value released for autofill is sealed to, and `presence` (ECDSA P-256,
+// `setUserAuthenticationRequired`, so it signs only after the person's fingerprint, face or screen lock). A signature by
+// `presence` over a fill request is the person's yes, checked by the keyring against the key it pinned at pairing, the
+// way a Windows Hello signature is. Pairing is carried by a sandbox both are linked to, with both fingerprints shown.
+export const KeyringPhoneKeysSchema = z
+    .object({
+        device: z.string().min(1).max(128).describe("The phone, by its device card."),
+        label: z.string().min(1).max(200).describe("The phone's name for people, `Pixel 8`."),
+        seal: KeyringPublicKeySchema,
+        presence: z.string().min(1).max(512).describe("The presence key, X.509 SubjectPublicKeyInfo DER, base64."),
+    })
+    .strict();
+export type KeyringPhoneKeys = z.infer<typeof KeyringPhoneKeysSchema>;
+
+export const KeyringPhonePairResultSchema = z.discriminatedUnion("ok", [
+    z.object({ ok: z.literal(true), fingerprint: z.string().describe("The keyring's own fingerprint, for the phone to show beside its own.") }),
+    refusal,
+]);
+export type KeyringPhonePairResult = z.infer<typeof KeyringPhonePairResultSchema>;
+
+export const KeyringPhoneFillSchema = z
+    .object({
+        v: z.literal(1),
+        device: z.string().min(1).max(128),
+        origin: KeyringOriginSchema.describe("Where the phone is filling: a `package`, or a `site` for a browser on the phone."),
+        username: z.string().max(256).optional(),
+        nonce: z.string().regex(KEYRING_NONCE_RE),
+        issuedAt: z.number().int(),
+        expiresAt: z.number().int(),
+    })
+    .strict();
+export type KeyringPhoneFill = z.infer<typeof KeyringPhoneFillSchema>;
+
+export const SignedKeyringPhoneFillSchema = z
+    .object({
+        payload: z.string().min(1).max(4096).describe("The fill request's JSON, base64url."),
+        sig: z.string().min(1).max(256).describe("The presence key's ECDSA P-256 signature (DER) over the payload, base64url."),
+    })
+    .strict();
+export type SignedKeyringPhoneFill = z.infer<typeof SignedKeyringPhoneFillSchema>;
+
+export const KeyringPhoneFillResultSchema = z.discriminatedUnion("ok", [
+    z.object({
+        ok: z.literal(true),
+        username: z.string().max(256).optional(),
+        sealed: SealedBoxSchema.describe("The value, sealed to the phone's `seal` key for `{ kind: \"phone\" }`."),
+        name: KeyringSecretNameSchema,
+        title: z.string(),
+    }),
+    refusal,
+]);
+export type KeyringPhoneFillResult = z.infer<typeof KeyringPhoneFillResultSchema>;

package/src/schemas/machine-presence.test.ts

@@ -0,0 +1,33 @@
+import { environmentName, machinePresence } from "./hosts.js";
+
+// One answer to "does this computer answer", read by /capabilities, the Devices board and a call's routing alike
+// (2026-10-13/15: one PC was offline on the card, live on the board, and partly connected by a third reading).
+
+const side = (key: string, online: boolean) => ({ key, online });
+
+test("a PC whose native side answers is online, whatever its distros do", () => {
+    expect(machinePresence([side("native", true), side("wsl:archlinux", false)])).toEqual({ kind: "online" });
+    expect(machinePresence([side("native", true), side("wsl:archlinux", true)])).toEqual({ kind: "online" });
+});
+
+test("a PC answering only through its distros is partly connected, and names them in order", () => {
+    expect(machinePresence([side("native", false), side("wsl:ubuntu", true), side("wsl:archlinux", true)])).toEqual({
+        kind: "partly",
+        awake: ["wsl:archlinux", "wsl:ubuntu"],
+    });
+});
+
+test("a computer nothing of which answers is offline", () => {
+    expect(machinePresence([side("native", false), side("wsl:archlinux", false)])).toEqual({ kind: "offline" });
+    expect(machinePresence([])).toEqual({ kind: "offline" });
+});
+
+// A machine seen only through a distro's sync has no native side to be missing.
+test("a computer with no native side is online while anything of it answers", () => {
+    expect(machinePresence([side("wsl:archlinux", true)])).toEqual({ kind: "online" });
+});
+
+test("names a distro the way WSL and `in` do", () => {
+    expect(environmentName("wsl:archlinux")).toBe("archlinux");
+    expect(environmentName("native")).toBe("native");
+});

package/src/schemas/phone-passwords.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import {
+    KeyringCaptureItemSchema,
+    KeyringCaptureResultSchema,
+    KeyringPhoneFillResultSchema,
+    KeyringPhoneKeysSchema,
+    KeyringPhonePairResultSchema,
+    KeyringPublicKeySchema,
+    SignedKeyringPhoneFillSchema,
+} from "./keyring.js";
+
+// THE PHONE'S WAY TO THE OWNER'S PASSWORDS (2026-10-19): the Intentic Device app as Android's autofill service, saving
+// what the person signs in with and filling it back, against the keyrings on the owner's computers. The phone door is
+// the sandbox asking and the phone answering (phone-protocol.ts); these go the other way, so they are plain HTTPS
+// requests from the app to its sandbox, authorised by the phone's enrollment token (`Authorization: Bearer <token>`),
+// and the sandbox relays each to the named computer's keyring over that computer's device link. What rides is sealed
+// end to end: a capture to the keyring's inbox key, a fill's answer to the phone's own seal key.
+
+export const PHONE_PASSWORDS_PATHS = {
+    keyrings: "/system/phones/passwords/keyrings",
+    pair: "/system/phones/passwords/pair",
+    capture: "/system/phones/passwords/capture",
+    fill: "/system/phones/passwords/fill",
+} as const;
+
+/** One of the owner's computers whose keyring the phone can save to and fill from. */
+export const PhoneKeyringSchema = z.object({
+    device: z.string().min(1).max(128).describe("The computer, by its device card."),
+    label: z.string().describe("The computer's name for people."),
+    online: z.boolean(),
+    locked: z.boolean().optional(),
+    inbox: KeyringPublicKeySchema.optional().describe("What a capture is sealed to. Absent until the keyring is set up."),
+    remember: z.boolean().describe("Whether the person turned on remembering from the phone on that computer."),
+    paired: z.boolean().describe("Whether this phone's keys are pinned there, so it can fill."),
+});
+export type PhoneKeyring = z.infer<typeof PhoneKeyringSchema>;
+
+// GET keyrings → the owner's keyrings this sandbox can reach.
+export const PhoneKeyringsResultSchema = z.object({ keyrings: z.array(PhoneKeyringSchema) });
+
+// POST pair → the computer's keyring asks its person, showing the phone's fingerprint; the phone shows the keyring's.
+export const PhonePasswordsPairSchema = z.object({ keyring: z.string().min(1).max(128), phone: KeyringPhoneKeysSchema }).strict();
+export const PhonePasswordsPairResultSchema = KeyringPhonePairResultSchema;
+
+// POST capture → onSaveRequest's credential, sealed on the phone for `{ kind: "capture", via, at }`.
+export const PhonePasswordsCaptureSchema = z.object({ keyring: z.string().min(1).max(128), item: KeyringCaptureItemSchema }).strict();
+export const PhonePasswordsCaptureResultSchema = KeyringCaptureResultSchema;
+
+// POST fill → after the person's fingerprint signed the request with the presence key.
+export const PhonePasswordsFillSchema = z.object({ keyring: z.string().min(1).max(128), fill: SignedKeyringPhoneFillSchema }).strict();
+export const PhonePasswordsFillResultSchema = KeyringPhoneFillResultSchema;

package/src/schemas/privacy-egress.test.ts

@@ -0,0 +1,83 @@
+import { DEFAULT_PRIVACY_SHIELD, type PrivacyShieldMode, type PrivacyShieldPolicy, withConversationTrust } from "./privacy.js";
+import { isPrivacyRefusal, ownerTrusted, type PrivacyEgress, type PrivacyRoute, shieldVerdict, turnRoute } from "./privacy-egress.js";
+
+// One verdict for every place bytes leave for a model, and for the editor's word before a send. Each scenario the shield
+// once got wrong at one of those places is a row here, so a place that reads the verdict cannot get it wrong again.
+
+const policy = (mode: PrivacyShieldMode, extra: Partial<PrivacyShieldPolicy> = {}): PrivacyShieldPolicy => ({ ...DEFAULT_PRIVACY_SHIELD, mode, ...extra });
+const egress = (route: PrivacyRoute, extra: Partial<PrivacyEgress> = {}): PrivacyEgress => ({ provider: "cursor", local: false, route, ...extra });
+
+const ROUTES: readonly PrivacyRoute[] = ["gateway", "hooks", "sealed", "runtime", "runner", "own-key", "shared-server"];
+
+describe(`shieldVerdict`, () => {
+    it(`passes everything while the shield is off, and only reads while it watches`, () => {
+        for (const route of ROUTES) {
+            expect(shieldVerdict(policy(`off`), egress(route))).toEqual({ kind: `pass`, because: `off` });
+        }
+        expect(ROUTES.map((route) => shieldVerdict(policy(`watch`), egress(route)).kind)).toEqual([
+            `watch`,
+            `watch`,
+            `watch`,
+            `pass`,
+            `pass`,
+            `pass`,
+            `pass`,
+        ]);
+    });
+
+    it(`masks every seam and refuses every bypass while it is on`, () => {
+        expect(ROUTES.map((route) => shieldVerdict(policy(`on`), egress(route)))).toEqual([
+            { kind: `mask` },
+            { kind: `mask` },
+            { kind: `mask` },
+            { kind: `refuse`, route: `runtime` },
+            { kind: `refuse`, route: `runner` },
+            { kind: `refuse`, route: `own-key` },
+            { kind: `refuse`, route: `shared-server` },
+        ]);
+    });
+
+    it(`passes a local model, a trusted provider and a granted conversation on every route`, () => {
+        const granted = withConversationTrust(policy(`on`), `c-1`, `cursor`, true);
+        for (const route of ROUTES) {
+            expect(shieldVerdict(policy(`on`), egress(route, { local: true }))).toEqual({ kind: `pass`, because: `local` });
+            expect(shieldVerdict(policy(`on`, { trusted: [`cursor`] }), egress(route))).toEqual({ kind: `pass`, because: `trusted` });
+            expect(shieldVerdict(granted, egress(route, { conversationId: `c-1` }))).toEqual({ kind: `pass`, because: `granted` });
+            // The grant is that conversation's alone, and a request outside any conversation (a helper) has none.
+            expect(shieldVerdict(granted, egress(route, { conversationId: `c-2` })).kind).not.toBe(`pass`);
+            expect(shieldVerdict(granted, egress(route)).kind).not.toBe(`pass`);
+        }
+    });
+
+    // grand-mesa-dsjg (2026-10-07): commit messages on Composer were refused before a word was read, while a turn on the
+    // same provider ran. A helper's prompt is sealed, so it is read and masked like a turn's, never refused for its runtime.
+    it(`reads a helper's sealed prompt exactly as a hooked turn is read`, () => {
+        expect(shieldVerdict(policy(`on`), egress(`sealed`))).toEqual(shieldVerdict(policy(`on`), egress(`hooks`)));
+    });
+
+    // calm-lichen-5wrn (2026-10-08): opening a Cursor composer warned before anything was sent. A hooked runtime is a seam.
+    // deft-shale-590s (2026-10-11): the same conversation on a runner was refused only after the send.
+    it(`refuses a turn by its placement, not by its runtime`, () => {
+        expect(shieldVerdict(policy(`on`), egress(turnRoute(`hooks`)))).toEqual({ kind: `mask` });
+        expect(shieldVerdict(policy(`on`), egress(turnRoute(`hooks`, `omen`)))).toEqual({ kind: `refuse`, route: `runner` });
+        expect(shieldVerdict(policy(`on`), egress(turnRoute(`gateway`, `omen`)))).toEqual({ kind: `refuse`, route: `runner` });
+        expect(shieldVerdict(policy(`on`), egress(turnRoute(`none`)))).toEqual({ kind: `refuse`, route: `runtime` });
+    });
+
+    it(`calls only the owner's own choices trusted`, () => {
+        expect(ownerTrusted({ kind: `pass`, because: `granted` })).toBe(true);
+        expect(ownerTrusted({ kind: `pass`, because: `local` })).toBe(true);
+        expect(ownerTrusted({ kind: `pass`, because: `off` })).toBe(false);
+        expect(ownerTrusted({ kind: `pass`, because: `unwatched` })).toBe(false);
+        expect(ownerTrusted({ kind: `mask` })).toBe(false);
+    });
+});
+
+describe(`isPrivacyRefusal`, () => {
+    it(`knows the shield's own refusals and nothing else`, () => {
+        expect(isPrivacyRefusal(`privacy-unshielded`)).toBe(true);
+        expect(isPrivacyRefusal(`privacy-instructions`)).toBe(true);
+        expect(isPrivacyRefusal(`model-unavailable`)).toBe(false);
+        expect(isPrivacyRefusal(undefined)).toBe(false);
+    });
+});