@intentic/sandbox-contract 1.337.0 → 1.339.0

package/src/models/agent-standing.ts

@@ -0,0 +1,279 @@
+import {
+    type AgentAttention,
+    type AgentJob,
+    type AgentStatus,
+    type AgentWatch,
+    awaitsWake,
+    type LandConflictReason,
+    type LandFailure,
+} from "../schemas/agents.js";
+import type { QueuePause } from "../schemas/agent.js";
+
+// (2026-10-16) Moved here from the editor (_editor/web/src/models/agent-status/agentStatus-standing.ts, which re-exports
+// it), so the daemon counts what needs the person by the very rules the board draws with (models/agent-lanes.ts): the
+// desktop app's status bar asks the daemon (`agents.attention`), and the board and the bar must never disagree.
+
+// Every projection of a fleet agent's state (lane, attention label, drill-in verb, glyphs). Nothing else may
+// derive these from `status` alone: a parked turn is `idle` with an attention flag raised. Pure functions over
+// plain data, no store, no Vue.
+
+// Four standings a conversation gets when the daemon has not registered it. `draft`: not sent yet. `starting`:
+// sent but not yet filed as an agent. `failed`: send refused, never became an agent. `resumed`: a past conversation
+// reopened from History with no surviving registry entry. All four have no registry entry, so nothing to archive,
+// review, land or drop (`unregistered` below). None may be widened into `AgentStatus`: that enum is only the
+// daemon's account of agents it has.
+export type ClientAgentStatus = "draft" | "starting" | "failed" | "resumed";
+
+// Enough of an agent to place one; every predicate below takes only this, so a FleetAgent, a roster AgentSummary,
+// or a test literal can all answer the same question. Each optional field also takes `undefined`, as the contract's own
+// AgentSummary spells it, so the daemon (strict about the difference) hands its roster over as it is.
+export interface AgentStanding {
+    readonly status: AgentStatus | ClientAgentStatus;
+    readonly attention: AgentAttention;
+    // Outside conditions this conversation is parked on (AgentSummary.watches); `laneOf` reads it alongside `status`
+    // and `attention`. Absent for nearly every conversation.
+    readonly watches?: readonly AgentWatch[] | undefined;
+    // Whether it runs again by itself (AgentSummary.awaitingWake): the daemon's one reading, which `watching` asks.
+    readonly awaitingWake?: boolean | undefined;
+    // The commands it left running and how the recent ones ended (AgentSummary.jobs); `heldByPrompt` reads which of its
+    // watches a job at a prompt holds. Absent for nearly every conversation.
+    readonly jobs?: readonly AgentJob[] | undefined;
+    // Why a refused land is still refusing (AgentSummary.conflictCauses), which decides whose press can clear it.
+    // Absent for every card but one refusing to merge.
+    readonly conflictCauses?: readonly LandConflictReason[] | undefined;
+    // Which kind of failure ended the last turn. `status: "error"` alone conflates a broken harness with a spent
+    // allowance; both belong in Attention, but this says which so the card can tell them apart. `laneOf` reads it too,
+    // so the lane, badge and chip stay in agreement.
+    readonly failureCode?: string | undefined;
+    // The words that turn died on (AgentSummary.failure), cleared with the code when it runs again.
+    readonly failure?: string | undefined;
+    /** When the spent allowance reopens, in epoch SECONDS (the wire's unit). Absent when nobody published one. */
+    readonly limitResetsAt?: number | undefined;
+    /** Whether the refused turn is held whole, so a press re-runs it rather than sending a new message after it. */
+    readonly limitHeld?: boolean | undefined;
+    /** Whether a fire is already booked for it (at the reset, or a move now), so no press is needed. */
+    readonly limitScheduled?: boolean | undefined;
+    /** The account the owner's policy is moving the held turn to, while that move is booked (a scheduled card's sentence). */
+    readonly limitMoving?: string | undefined;
+    // A land that broke (AgentSummary.landFailure), standing until one goes through whatever turns run after it. Absent
+    // from a sandbox older than it, where only a turn's own `failure` can say so.
+    readonly landFailure?: LandFailure | undefined;
+    // What waits for its next turn (AgentSummary.queue), read here only for its hold: messages booked to go by
+    // themselves at a time or once another agent's work lands (`scheduled`), which make the conversation one that runs
+    // again by itself. Never the words.
+    readonly queue?: QueueHold | undefined;
+}
+
+// The part of a conversation's queue the board reads: why it holds, and what a scheduled hold waits for. A queue-level
+// `scheduled` with its `until` or `after` is the soonest booked message's; a Stop's or a refusal's hold on the messages
+// with no booking takes that place, so each message's own booking (`items`, from sandboxes that book each message on its
+// own) is read then.
+export interface QueueHold {
+    readonly paused?: QueuePause | undefined;
+    readonly until?: number | undefined;
+    readonly after?: string | undefined;
+    readonly items?: readonly { readonly until?: number | undefined; readonly after?: string | undefined }[] | undefined;
+}
+
+// The soonest booking a queue holds, as a scheduled hold: the queue's own while it reads `scheduled`, else the earliest
+// message's time, else the first message waiting on a land; undefined when nothing is booked. One thing, never both.
+export const soonestHold = (queue: QueueHold | undefined): QueueHold | undefined => {
+    if (queue?.paused === "scheduled") {
+        if (queue.after !== undefined) {
+            return { paused: "scheduled", after: queue.after };
+        }
+        return queue.until === undefined ? { paused: "scheduled" } : { paused: "scheduled", until: queue.until };
+    }
+    const items = queue?.items ?? [];
+    const instants = items.flatMap((item) => (item.until === undefined ? [] : [item.until]));
+    if (instants.length > 0) {
+        return { paused: "scheduled", until: Math.min(...instants) };
+    }
+    const after = items.find((item) => item.after !== undefined)?.after;
+    return after === undefined ? undefined : { paused: "scheduled", after };
+};
+
+// Messages booked to go by themselves (sendLater.ts, or a spent allowance's reopen): the conversation runs again with
+// nobody pressing anything, so it is not finished, and nothing is owed by the reader for it to.
+export const scheduledSend = (agent: Pick<AgentStanding, "queue">): boolean => soonestHold(agent.queue) !== undefined;
+
+// How many messages are booked to go by themselves: each by its own booking, or all of them when an older sandbox booked
+// the queue whole. What an archive by hand cancels (the sandbox's archive.ts), which the card's Archive says first.
+export const scheduledCount = (agent: Pick<AgentStanding, "queue">): number => {
+    const items = agent.queue?.items ?? [];
+    return agent.queue?.paused === "scheduled" ? items.length : items.filter((item) => item.until !== undefined || item.after !== undefined).length;
+};
+
+// A spent allowance, not a failure to fix: nothing broken, and it comes back. Read off `failureCode` rather than
+// the provider's own sentence, which varies per provider; the code is the daemon's own classification
+// (error-frames.ts).
+export const limited = (agent: AgentStanding): boolean => agent.status === "error" && agent.failureCode === "rate_limit";
+
+// A message held at the door because the sandbox is short of memory (turn-admission): nothing ran and nothing failed,
+// it waits for a person's "send anyway". The daemon files it as an `error`, so this is read off the code, as `limited`
+// is, and the chip and glyph say held rather than error; the lane stays Attention, since the press is the reader's.
+export const memoryHeld = (agent: Pick<AgentStanding, "status" | "failureCode">): boolean =>
+    agent.status === "error" && agent.failureCode === "sandbox-memory-low";
+
+// Whether the window is still shut, feeding only the card's countdown, never the lane: a stranded card stays in
+// Attention shut or open. No published instant means never closed, not a guessed one.
+export const limitClosed = (agent: AgentStanding, now: number = Date.now()): boolean =>
+    limited(agent) && agent.limitResetsAt !== undefined && agent.limitResetsAt * 1_000 > now;
+
+// A booked fire needs no press: the held turn goes again at the reset by itself. Only where this conversation's answer
+// for the limit says so (`resend` or `move`); that answer starts at `wait`. Nothing is owed then, so it leaves Attention
+// for Active, as an armed watch does: a card counted in the badge and the tab title for the hours until a reset the
+// reader already answered was a call nobody could answer. The stall still shows, on the card's own chip and clock.
+export const limitScheduled = (agent: AgentStanding): boolean => limited(agent) && agent.limitScheduled === true;
+
+// A booked move: the owner's policy is already carrying the held turn to another account, on the resume pass's next
+// beat, seconds away, so the card names where it is going rather than when it goes.
+export const limitMoveBooked = (agent: AgentStanding): boolean => limitScheduled(agent) && agent.limitMoving !== undefined;
+
+// A refused land nothing the agent does can clear: every blocker left is a file the user has uncommitted edits on,
+// which only a commit or stash releases (git cannot merge through unstaged work, and the agent's checkout cannot
+// even see it). The distinction the board used to lack: it offered "have the agent resolve it" for every conflict,
+// including the ones where that press was refused the moment it was made.
+// False when the daemon named no causes, which is a build that predates them or a refusal it could not attribute;
+// the board then falls back to offering the agent, as it always did.
+export const conflictIsYours = (agent: AgentStanding): boolean =>
+    agent.conflictCauses !== undefined && agent.conflictCauses.length > 0 && agent.conflictCauses.every((cause) => cause === "workspace");
+
+// This conversation runs again by itself, with nobody pressing anything: its last turn ended (status is `idle`/`landed`,
+// never `ready`, since the daemon holds the land for the wake), but the conversation is not over. The daemon's own
+// reading (a watch, or a wake waiting in its queue); a daemon older than it is read by its watches.
+export const watching = (agent: AgentStanding): boolean => awaitsWake(agent);
+
+// The running job behind one of its armed watches that sits at a prompt (AgentJob.inputWait: blocked reading its
+// terminal, nothing moving), the first such where there are several. Its watch fires only on an exit that will not
+// come, so the card names it and offers to end it.
+export const promptHeldJob = (agent: AgentStanding): AgentJob | undefined => {
+    const armed = new Set((agent.watches ?? []).map((watch) => watch.id));
+    return agent.jobs?.find((job) => job.endedAt === undefined && job.inputWait !== undefined && job.watch !== undefined && armed.has(job.watch));
+};
+
+// Parked only on jobs at a prompt: every watch it holds waits on an exit nobody in the sandbox will bring about, so the
+// conversation is not resuming by itself, it is stuck until the reader ends the command (or types into its terminal).
+// Not while a turn runs, whose own readout says what it is doing. On 2026-10-04 such a card sat in Active for hours
+// under a six-hour countdown, with its Land press hidden behind the wake it was waiting for.
+export const heldByPrompt = (agent: AgentStanding): boolean => {
+    const watches = agent.watches ?? [];
+    if (watches.length === 0 || turnInFlight(agent)) {
+        return false;
+    }
+    const prompts = new Set(
+        (agent.jobs ?? [])
+            .filter((job) => job.endedAt === undefined && job.inputWait !== undefined && job.watch !== undefined)
+            .map((job) => job.watch),
+    );
+    return watches.every((watch) => prompts.has(watch.id));
+};
+
+// No registry entry behind this card: archiving, reviewing, landing, discarding and dropping all address an agent
+// by id through the daemon, and none of these ids name anything there.
+// Takes the status alone, unlike the lane predicates: callers like the tab's `open` and the detail page's
+// `registered` hold a status without an attention block to pair it with.
+export const unregistered = (status: AgentStatus | ClientAgentStatus): boolean =>
+    status === "draft" || status === "starting" || status === "failed" || status === "resumed";
+
+// A turn is in flight: running, unwinding after a Stop, or repairing itself after its daemon died. Every hands-off
+// guard (its worktree is a live turn's working state) and the live readouts (elapsed, activity line) key off this.
+// `starting` counts even though nothing is registered yet, elapsed should tick from the send. `dismissing` and
+// `landing` count for the guards only; both settle in Finished, so their lane is decided separately (see laneOf).
+// A land runs no turn, but the daemon holds the worktree exactly as a turn would, and every guard wants the same answer.
+// `awaiting` is deliberately excluded: it's live but parked, handled by `awaitingUser` instead.
+export const turnInFlight = (agent: AgentStanding): boolean =>
+    agent.status === "running" ||
+    agent.status === "starting" ||
+    agent.status === "stopping" ||
+    agent.status === "dismissing" ||
+    agent.status === "resuming" ||
+    agent.status === "landing";
+
+// The two standings a person's ending unwinds as, from the press until the turn has let go: Stop, or waving away the
+// question it was parked on. Both differ only in the lane they settle in (see laneOf).
+export type EndingByHand = Extract<AgentStatus, "stopping" | "dismissing">;
+
+// How a person ended this turn, while it unwinds; undefined for a turn nobody ended. The one reading both the board's
+// card and the chat's live line are drawn from, so the two say the same word about the same press.
+export const endingOf = (agent: AgentStanding): EndingByHand | undefined =>
+    agent.status === "stopping" || agent.status === "dismissing" ? agent.status : undefined;
+
+// A person already ended this turn and it's unwinding. Narrower than `turnInFlight`, which also covers turns nobody
+// ended.
+export const endingByHand = (agent: AgentStanding): boolean => endingOf(agent) !== undefined;
+
+// A turn actually producing something, as a card's readouts mean it: `landing` is in flight for the hands-off guards
+// but spends no model, and its `startedAt` belongs to the turn before it, so an elapsed clock would be someone else's.
+// A turn a person already ended produces nothing more either: its readout is the ending itself (the card's chip, the
+// chat's line), not the step it was on under a clock still counting, which reads as a Stop that did not take.
+export const turnWorking = (agent: AgentStanding): boolean => turnInFlight(agent) && agent.status !== "landing" && !endingByHand(agent);
+
+// The browser's copy of the daemon's `writing` guard (agents-registry.ts); exists for Land, where typing vs.
+// parked matters (everything else treats them alike). `stopping` and `resuming` are excluded because the provider
+// isn't producing anything then; the two sides must stay in step or the UI offers a press the daemon refuses.
+export const writingNow = (agent: AgentStanding): boolean => agent.status === "running" || agent.status === "starting";
+
+// "Blocked on you": the agent cannot proceed (or has failed) until the user acts. Not the same as unread.
+// `stopped`/`interrupted` leave a half-written worktree only a new message can carry forward; `stopping` is
+// counted the moment the press lands rather than once the unwind finishes, since it settles in the same lane
+// either way; `failed` is the same kind of dead end one step earlier, before a worktree existed. A spent allowance
+// counts until something is booked to carry it on (limitScheduled): a resend at the reset, or a move now.
+const BLOCKING_ENDINGS: ReadonlySet<AgentStatus | ClientAgentStatus> = new Set(["error", "interrupted", "stopping", "stopped", "failed"]);
+
+// A land that broke and still stands: its work is stuck on the branch, whatever the turn after it did, so the card is
+// the reader's to look at. Not while a turn or a land is under way, which ends in another land of its own.
+export const landBroken = (agent: AgentStanding): boolean => agent.landFailure !== undefined && !turnInFlight(agent);
+
+export const blocked = (agent: AgentStanding): boolean =>
+    limitScheduled(agent)
+        ? false
+        : agent.attention.plan ||
+          agent.attention.question ||
+          agent.attention.permission ||
+          agent.attention.capability ||
+          agent.attention.conflict ||
+          // A need outlives its turn (docs/architecture/needs.md): a conversation still running carries on beside it
+          // and stays in Active, one that stopped is waiting on nothing but the answer.
+          (agent.attention.need === true && agent.status !== "running") ||
+          landBroken(agent) ||
+          heldByPrompt(agent) ||
+          BLOCKING_ENDINGS.has(agent.status);
+
+// The half of `blocked` that is literally waiting on an answer (plan, question, permission, capability), narrower
+// than `blocked`: dead ends (a failed turn, an unlandable conflict) want looking at but owe the user nothing, so
+// ending the agent loses no answer.
+export const awaitingUser = (agent: AgentStanding): boolean =>
+    agent.attention.plan || agent.attention.question || agent.attention.permission || agent.attention.capability || agent.status === "awaiting";
+
+// An ask only the owner may answer: a plan to approve, a permission, a setup, a credential release, a hand-off to a
+// browser or terminal (a bare `awaiting`), or a refused land only their own commit clears. The parent a child agent
+// works for can answer its question (subagents/children.ts) and hears how its turns end, but none of these, so these
+// are what reach the reader from a child whatever its parent is doing (callsOwner).
+export const onlyOwnerCanAnswer = (agent: AgentStanding): boolean =>
+    agent.attention.plan ||
+    agent.attention.permission ||
+    agent.attention.capability ||
+    agent.attention.credential ||
+    agent.attention.need === true ||
+    (agent.status === "awaiting" && !agent.attention.question) ||
+    ((agent.attention.conflict || agent.status === "conflict") && conflictIsYours(agent));
+
+// Whether a child agent's stop is news its parent has already had. Every ending of a turn the parent started reaches
+// the parent (subagents/child-report.ts: a parked `wait` takes it, or it wakes the parent like any wake), so a parent
+// that moved after the child stopped (ran a turn, landed) heard it, and its own ending is the account the reader gets:
+// an orchestrator that worked around three spent allowances and landed is done, not stuck. Only a turn's ending
+// counts. A question is still parked and waits for an answer whoever has moved since, and a land refused or broken
+// leaves work stuck on the child's branch that no report settles. A turn a person ran in the child's own chat is never
+// reported to the parent, and it ends after the parent's last move, so it still reads as unheard here.
+// `updatedAt` is the clock on both sides: a rename keeps it (agents-registry), and reading does not move it.
+export const heardByParent = (child: AgentStanding & { readonly updatedAt: number }, parentAt: number): boolean =>
+    BLOCKING_ENDINGS.has(child.status) &&
+    // Still unwinding: its ending has not reached anyone yet.
+    child.status !== "stopping" &&
+    // Booked to run again by itself: not over, whatever its parent made of the pause.
+    !limitScheduled(child) &&
+    !child.attention.question &&
+    !child.attention.conflict &&
+    !landBroken(child) &&
+    child.updatedAt < parentAt;

package/src/models/agent-starter.ts

@@ -0,0 +1,26 @@
+// Who started a conversation when it was not a person, read off the summary's `startedBy` (the daemon's
+// auth/principal.ts writes these prefixes). Moved here from the editor's ownership.ts (2026-10-16), which re-exports it,
+// because which card a child agent rides under (models/agent-lanes.ts) is the daemon's count too.
+
+// A starter that is not a person: a program holding a control token, or the conversation that spawned this one.
+export type StarterLook = { readonly kind: "token"; readonly label: string } | { readonly kind: "child"; readonly parent: string };
+
+const TOKEN_PREFIX = "token:";
+const CHILD_PREFIX = "agent:";
+
+export const starterLook = (startedBy: string | undefined): StarterLook | undefined => {
+    if (startedBy?.startsWith(TOKEN_PREFIX) === true) {
+        return { kind: "token", label: startedBy.slice(TOKEN_PREFIX.length) };
+    }
+    if (startedBy?.startsWith(CHILD_PREFIX) === true) {
+        return { kind: "child", parent: startedBy.slice(CHILD_PREFIX.length) };
+    }
+    return undefined;
+};
+
+// The conversation that spawned this one, when one did. A fact apart from whose it is: a child inherits its parent's
+// owner, so on the reader's own work an ownership mark would never get to say it.
+export const parentOf = (startedBy: string | undefined): string | undefined => {
+    const look = starterLook(startedBy);
+    return look?.kind === "child" ? look.parent : undefined;
+};

package/src/netd/generated/netd-wire.json

@@ -648,7 +648,8 @@
   },
   "headers": [
     "x-intentic-preview",
-    "x-intentic-preview-unreachable"
+    "x-intentic-preview-unreachable",
+    "x-intentic-listener"
   ],
   "toNode": {
     "$defs": {

package/src/netd/generated/wire.ts

@@ -41,7 +41,7 @@ export type NetdAnswer = { "answer": "sync", generations: Array<number | null>,
  * Request headers only netd sets on what it forwards to Node; it strips them from everything arriving outside.
  * Exported as a literal type, so a Node constant naming one that drifts from this spelling fails to compile.
  */
-export type NetdHeader = "x-intentic-preview" | "x-intentic-preview-unreachable";
+export type NetdHeader = "x-intentic-preview" | "x-intentic-preview-unreachable" | "x-intentic-listener";
 
 /**
  * A question Node asks netd.

package/src/policy/identity-assertion.ts

@@ -1,4 +1,5 @@
 import { createPrivateKey, createPublicKey, randomBytes, sign as edSign, verify as edVerify } from "node:crypto";
+import { parseJsonWith } from "@intentic/base/json";
 import { z } from "zod";
 import { SANDBOX_ID } from "../ids/tunnel-ids.js";
 
@@ -92,14 +93,7 @@ const AssertionPayloadSchema = z.object({
     jti: z.string().min(16),
 });
 
-const parsePayload = (payload: Buffer): z.infer<typeof AssertionPayloadSchema> | undefined => {
-    try {
-        return AssertionPayloadSchema.safeParse(JSON.parse(payload.toString("utf8"))).data;
-    } catch {
-        // allow(silent-catch): a payload that is not JSON is an invalid assertion, which undefined is how this says.
-        return undefined;
-    }
-};
+const parsePayload = (payload: Buffer): z.infer<typeof AssertionPayloadSchema> | undefined => parseJsonWith(payload.toString("utf8"), AssertionPayloadSchema);
 
 // Verifies an assertion against the platform's public key at nowMs; undefined for any way of being invalid (wrong
 // prefix, bad signature, malformed claim, expired, issued in the future, living longer than the daemon allows). The

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

@@ -0,0 +1,93 @@
+import type { KeyringGrant } from "../schemas/keyring.js";
+import { grantNonce, keyFingerprint, newSealKeyPair, newSignKeyPair, seal, signGrant, unseal, verifyGrant } from "./keyring-seal.js";
+
+const SANDBOX = "https://a1b2c3d4e5f6.intentic.dev";
+
+const grantAt = (now: number, over: Partial<KeyringGrant> = {}): KeyringGrant => ({
+    v: 1,
+    sandbox: SANDBOX,
+    secret: "VPN_FORTI",
+    target: { kind: "window", programs: ["FortiClient.exe"], anyField: false },
+    purpose: "agent",
+    detail: "FortiClient sign-in",
+    nonce: grantNonce(),
+    issuedAt: now,
+    expiresAt: now + 60_000,
+    ...over,
+});
+
+describe("sealed boxes", () => {
+    test("open for their own key and purpose", () => {
+        const pair = newSealKeyPair();
+        const purpose = { kind: "release", sandbox: SANDBOX, secret: "VPN_FORTI", nonce: grantNonce() } as const;
+        const box = seal(pair.publicKey, "hunter2-but-longer", purpose);
+        expect(unseal(pair, box, purpose)).toBe("hunter2-but-longer");
+    });
+
+    test("refuse another key", () => {
+        const purpose = { kind: "inbox", sandbox: SANDBOX, secret: "X" } as const;
+        const box = seal(newSealKeyPair().publicKey, "value", purpose);
+        expect(() => unseal(newSealKeyPair(), box, purpose)).toThrow();
+    });
+
+    test("refuse another purpose, so one release cannot stand in for another", () => {
+        const pair = newSealKeyPair();
+        const nonce = grantNonce();
+        const box = seal(pair.publicKey, "value", { kind: "release", sandbox: SANDBOX, secret: "A", nonce });
+        expect(() => unseal(pair, box, { kind: "release", sandbox: SANDBOX, secret: "B", nonce })).toThrow();
+        expect(() => unseal(pair, box, { kind: "type", sandbox: SANDBOX, secret: "A", nonce })).toThrow();
+    });
+
+    test("are fresh every time, so equal values do not look equal", () => {
+        const pair = newSealKeyPair();
+        const purpose = { kind: "inbox", sandbox: SANDBOX, secret: "X" } as const;
+        expect(seal(pair.publicKey, "same", purpose).data).not.toBe(seal(pair.publicKey, "same", purpose).data);
+    });
+});
+
+describe("grants", () => {
+    test("verify under the signing key", () => {
+        const pair = newSignKeyPair();
+        const now = Date.now();
+        const verdict = verifyGrant(pair.publicKey, signGrant(pair, grantAt(now)), now + 1000);
+        expect(verdict.ok).toBe(true);
+        expect(verdict.ok && verdict.grant.secret).toBe("VPN_FORTI");
+    });
+
+    test("refuse another sandbox's key", () => {
+        const now = Date.now();
+        const verdict = verifyGrant(newSignKeyPair().publicKey, signGrant(newSignKeyPair(), grantAt(now)), now);
+        expect(verdict).toMatchObject({ ok: false, code: "bad-grant" });
+    });
+
+    test("refuse a payload changed after signing", () => {
+        const pair = newSignKeyPair();
+        const now = Date.now();
+        const signed = signGrant(pair, grantAt(now));
+        // SAFETY: the payload is the grant signGrant just serialised, so it parses back to one.
+        const body = JSON.parse(Buffer.from(signed.payload, "base64url").toString("utf8")) as KeyringGrant;
+        const changed = Buffer.from(JSON.stringify({ ...body, secret: "BANK" }), "utf8").toString("base64url");
+        expect(verifyGrant(pair.publicKey, { ...signed, payload: changed }, now)).toMatchObject({ ok: false, code: "bad-grant" });
+    });
+
+    test("expire", () => {
+        const pair = newSignKeyPair();
+        const now = Date.now();
+        expect(verifyGrant(pair.publicKey, signGrant(pair, grantAt(now)), now + 61_000)).toMatchObject({ ok: false, code: "expired" });
+    });
+
+    test("are never signed for longer than two minutes", () => {
+        const now = Date.now();
+        expect(() => signGrant(newSignKeyPair(), grantAt(now, { expiresAt: now + 5 * 60_000 }))).toThrow();
+    });
+
+    test("from far in the future are not this sandbox's", () => {
+        const pair = newSignKeyPair();
+        const now = Date.now();
+        expect(verifyGrant(pair.publicKey, signGrant(pair, grantAt(now + 10 * 60_000)), now)).toMatchObject({ ok: false, code: "bad-grant" });
+    });
+});
+
+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);
+});

package/src/policy/keyring-seal.ts

@@ -0,0 +1,148 @@
+import { createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, sign, verify, type KeyObject } from "node:crypto";
+import { z } from "zod";
+import {
+    KEYRING_GRANT_TTL_MAX_MS,
+    KEYRING_KEY_RE,
+    KeyringGrantSchema,
+    type KeyringGrant,
+    type SealedBox,
+    SealedBoxSchema,
+    type SignedKeyringGrant,
+} from "../schemas/keyring.js";
+
+// The two primitives a device-held secret rides on (schemas/keyring.ts): a SEALED BOX, a value only the holder of one
+// X25519 key can open, and a GRANT, the sandbox's Ed25519-signed word for one use of one value. Shared by the daemon,
+// which signs grants and opens what is sealed to it, and the keyring, which verifies grants and seals; one file so the
+// two cannot drift on an encoding.
+
+const SEAL_INFO = Buffer.from("intentic-keyring/seal/v1", "utf8");
+const GRANT_DOMAIN = Buffer.from("intentic-keyring/grant/v1\0", "utf8");
+// A clock on either side may run a little ahead; a grant from much further in the future is not one this sandbox made.
+const GRANT_SKEW_MS = 30_000;
+
+// A key pair as it is stored: both halves raw, base64url, the `x` and `d` of their JWK.
+export interface KeyringKeyPair {
+    readonly publicKey: string;
+    readonly privateKey: string;
+}
+
+type Curve = "X25519" | "Ed25519";
+
+// The halves of an OKP key's JWK, which Node always writes for a private key it just made.
+const OkpJwkSchema = z.object({ x: z.string().regex(KEYRING_KEY_RE), d: z.string().regex(KEYRING_KEY_RE) });
+
+const pairOf = (curve: Curve): KeyringKeyPair => {
+    const { privateKey } = curve === "X25519" ? generateKeyPairSync("x25519") : generateKeyPairSync("ed25519");
+    const jwk = OkpJwkSchema.parse(privateKey.export({ format: "jwk" }));
+    return { publicKey: jwk.x, privateKey: jwk.d };
+};
+
+export const newSealKeyPair = (): KeyringKeyPair => pairOf("X25519");
+export const newSignKeyPair = (): KeyringKeyPair => pairOf("Ed25519");
+
+const publicKeyOf = (curve: Curve, x: string): KeyObject => createPublicKey({ key: { kty: "OKP", crv: curve, x }, format: "jwk" });
+const privateKeyOf = (curve: Curve, pair: KeyringKeyPair): KeyObject =>
+    createPrivateKey({ key: { kty: "OKP", crv: curve, x: pair.publicKey, d: pair.privateKey }, format: "jwk" });
+
+// What a box is sealed FOR, mixed into its authentication tag: a box opened under any other purpose fails, so a value
+// released for one grant cannot be presented as another's, nor a typing payload as an inbox item.
+export type SealPurpose =
+    | { readonly kind: "release"; readonly sandbox: string; readonly secret: string; readonly nonce: string }
+    | { 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 };
+
+export const sealAad = (purpose: SealPurpose): Buffer => {
+    switch (purpose.kind) {
+        case "release":
+        case "type":
+            return Buffer.from(`${purpose.kind}\0${purpose.sandbox}\0${purpose.secret}\0${purpose.nonce}`, "utf8");
+        case "inbox":
+            return Buffer.from(`inbox\0${purpose.sandbox}\0${purpose.secret}`, "utf8");
+        case "copy":
+            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");
+    }
+};
+
+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.
+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") };
+};
+
+// Opens a box sealed to `pair` for `purpose`; throws on any way of not being one (malformed, another key, another purpose).
+export const unseal = (pair: KeyringKeyPair, box: SealedBox, purpose: SealPurpose): string => {
+    const parsed = SealedBoxSchema.parse(box);
+    const shared = diffieHellman({ privateKey: privateKeyOf("X25519", pair), publicKey: publicKeyOf("X25519", parsed.epk) });
+    const decipher = createDecipheriv("aes-256-gcm", boxKey(shared, parsed.epk, pair.publicKey), Buffer.from(parsed.iv, "base64url"));
+    decipher.setAAD(sealAad(purpose));
+    decipher.setAuthTag(Buffer.from(parsed.tag, "base64url"));
+    return Buffer.concat([decipher.update(Buffer.from(parsed.data, "base64url")), decipher.final()]).toString("utf8");
+};
+
+// A fresh grant's nonce: 16 random bytes, base64url.
+export const grantNonce = (): string => randomBytes(16).toString("base64url");
+
+export const signGrant = (pair: KeyringKeyPair, grant: KeyringGrant): SignedKeyringGrant => {
+    const body = KeyringGrantSchema.parse(grant);
+    if (body.expiresAt - body.issuedAt > KEYRING_GRANT_TTL_MAX_MS || body.expiresAt <= body.issuedAt) {
+        throw new Error(`a keyring grant lives at most ${String(KEYRING_GRANT_TTL_MAX_MS / 1000)} s`);
+    }
+    const payload = Buffer.from(JSON.stringify(body), "utf8");
+    const sig = sign(null, Buffer.concat([GRANT_DOMAIN, payload]), privateKeyOf("Ed25519", pair));
+    return { payload: payload.toString("base64url"), sig: sig.toString("base64url") };
+};
+
+export type GrantVerdict =
+    | { readonly ok: true; readonly grant: KeyringGrant }
+    | { readonly ok: false; readonly code: "bad-grant" | "expired"; readonly reason: string };
+
+// Verifies `signed` against the sandbox's pinned signing key at `nowMs`. The keyring checks the nonce, the share and
+// the target against its own facts; this says only whether the sandbox said it, and said it recently.
+export const verifyGrant = (signKey: string, signed: SignedKeyringGrant, nowMs: number): GrantVerdict => {
+    let payload: Buffer;
+    try {
+        payload = Buffer.from(signed.payload, "base64url");
+        if (!verify(null, Buffer.concat([GRANT_DOMAIN, payload]), publicKeyOf("Ed25519", signKey), Buffer.from(signed.sig, "base64url"))) {
+            return { ok: false, code: "bad-grant", reason: "the grant's signature is not the sandbox's" };
+        }
+    } catch {
+        return { ok: false, code: "bad-grant", reason: "the grant could not be read" };
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(payload.toString("utf8"));
+    } catch {
+        return { ok: false, code: "bad-grant", reason: "the grant is not JSON" };
+    }
+    const grant = KeyringGrantSchema.safeParse(parsed);
+    if (!grant.success) {
+        return { ok: false, code: "bad-grant", reason: "the grant is not one this keyring knows how to read" };
+    }
+    const { issuedAt, expiresAt } = grant.data;
+    if (expiresAt - issuedAt > KEYRING_GRANT_TTL_MAX_MS || expiresAt <= issuedAt || issuedAt > nowMs + GRANT_SKEW_MS) {
+        return { ok: false, code: "bad-grant", reason: "the grant's times are not ones this sandbox would sign" };
+    }
+    if (expiresAt <= nowMs) {
+        return { ok: false, code: "expired", reason: "the grant has expired: the sandbox asks again" };
+    }
+    return { ok: true, grant: grant.data };
+};
+
+// A short, readable fingerprint of a public key, for a person comparing what two screens show.
+export const keyFingerprint = (key: string): string => {
+    const raw = Buffer.from(key, "base64url");
+    const hex = raw.subarray(0, 8).toString("hex").toUpperCase();
+    return hex.replace(/(.{4})(?=.)/gu, "$1-");
+};

package/src/policy/message-limits.ts

@@ -5,6 +5,7 @@
 export const MESSAGE_LIMITS = {
     bluesky: 300,
     discord: 2_000,
+    facebook: 63_206,
     instagram: 2_200,
     linkedin: 3_000,
     mastodon: 500,
@@ -12,6 +13,8 @@ export const MESSAGE_LIMITS = {
     slack: 4_000,
     // sendMessage refuses anything longer outright.
     telegram: 4_096,
+    // A video's caption; a comment under one stops at 150.
+    tiktok: 4_000,
     // A linked device (what the WhatsApp extension is) sends up to 65,536; the 4,096 often quoted is the Business API's.
     whatsapp: 65_536,
     x: 280,