@fungi.computer/oyster 0.4.1 → 0.5.0

package/dist/channels/ids.d.ts

@@ -0,0 +1,8 @@
+/** Server- and widget-minted channel identities, shared by both Oyster hosts. */
+export declare const channelIds: Readonly<{
+    readonly binding: import("@fungi.computer/cairn").IdCodec<"channel", "binding", 1>;
+    readonly site: import("@fungi.computer/cairn").IdCodec<"channel", "site", 1>;
+    readonly endpoint: import("@fungi.computer/cairn").IdCodec<"channel", "endpoint", 1>;
+    readonly visitor: import("@fungi.computer/cairn").IdCodec<"channel", "visitor", 1>;
+    readonly message: import("@fungi.computer/cairn").IdCodec<"channel", "message", 1>;
+}>;

package/dist/channels/ids.js

@@ -0,0 +1,15 @@
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+/** Server- and widget-minted channel identities, shared by both Oyster hosts. */
+export const channelIds = defineIdFamily({
+    family: "channel",
+    version: 1,
+    kinds: {
+        binding: { prefix: "chb" },
+        site: { prefix: "site_pk" },
+        /** The public, unguessable address of one incoming-events binding. */
+        endpoint: { prefix: "evt_ep" },
+        visitor: { prefix: "v" },
+        /** One visitor message; the widget mints it so a resend replays. */
+        message: { prefix: "msg" },
+    },
+});

package/dist/host.d.ts

@@ -18,7 +18,7 @@ import * as Schema from "effect/Schema";
 import { type BackgroundSyncRefusal } from "@fungi.computer/puffball/background-replay";
 import { type Installation, type InstallationReader } from "./apps/installation.js";
 import type { AppToolPolicy } from "./apps/tools.js";
-import type { LiveOysterKey } from "./keys.js";
+import { type LiveOysterKey } from "./keys.js";
 import { type AppMethodReply } from "@fungi.computer/agar/backend";
 import type { AppCapabilityId, HostActor } from "@fungi.computer/puffball/app";
 import { type CapabilityDescriptor } from "./capability-descriptor.js";

package/dist/host.js

@@ -20,6 +20,7 @@ import { emptyAppDeclaration } from "@fungi.computer/puffball/app";
 import { applyInstallationCommand, installationIdSchema, } from "./apps/installation.js";
 import { admits, scopedBindings, grantsFor } from "./apps/gate.js";
 import { appPermissionPageSchema, permissionSaveSchema, } from "./apps/permissions.js";
+import { keyAppAccess } from "./keys.js";
 import { deriveDeclaredOperations, appCallOperation, } from "./apps/operations.js";
 import { appBackendActorHeader, appBackendComputerHeader, appMethodRefusalStatus, } from "@fungi.computer/agar/backend";
 import { appCallsDescriptor, } from "./capability-descriptor.js";
@@ -487,6 +488,10 @@ export function createOyster(host) {
                 kind: "capability-route",
                 capability: capability.permission,
                 operation,
+                effect: (context.req.method === "GET" || context.req.method === "HEAD") &&
+                    context.req.header("Upgrade")?.toLowerCase() !== "websocket"
+                    ? "read"
+                    : "write",
             }).kind === "refused")
                 continue;
             url.pathname = `/${url.pathname.slice(capability.base.length)}`;
@@ -498,14 +503,23 @@ export function createOyster(host) {
         return refusal(403, "Capability permission denied");
     });
     app.get("/", async (context) => {
-        const publicHome = context.get("principal").actor.kind === "visitor";
+        const actor = context.get("principal").actor;
+        const publicHome = actor.kind === "visitor";
+        const key = actor.kind === "team-key"
+            ? ((await host.keys?.live(actor.keyId)) ?? null)
+            : null;
         if (!publicHome && host.homeInstallationId !== undefined) {
             const home = await host.installations.get(host.homeInstallationId);
-            if (home?.status === "enabled")
+            if (home?.status === "enabled" &&
+                (actor.kind !== "team-key" ||
+                    (key !== null && keyAppAccess(key, home.installationId) !== null)))
                 return context.redirect(`/apps/${encodeURIComponent(home.installationId)}/`);
         }
         const installations = (await host.installations.list()).filter((installation) => installation.status === "enabled" &&
-            (!publicHome || installation.visibility === "public"));
+            (!publicHome || installation.visibility === "public") &&
+            (actor.kind !== "team-key" ||
+                (key !== null &&
+                    keyAppAccess(key, installation.installationId) !== null)));
         if (publicHome) {
             const apps = [];
             for (const installation of installations) {
@@ -846,10 +860,11 @@ export function createOyster(host) {
         const facts = await gateFacts(installation, release, principal);
         const capabilities = [];
         for (const capability of host.capabilities ?? []) {
-            const methods = Object.fromEntries(Object.entries(capability.methods).filter(([name]) => admits(facts, {
+            const methods = Object.fromEntries(Object.entries(capability.methods).filter(([name, method]) => admits(facts, {
                 kind: "capability-route",
                 capability: capability.permission,
                 operation: `route:${capability.id}:${name}`,
+                effect: method.method === "GET" ? "read" : "write",
             }).kind === "admitted"));
             if (Object.keys(methods).length > 0) {
                 const { id, version, base } = capability;
@@ -862,6 +877,7 @@ export function createOyster(host) {
                 kind: "capability-route",
                 capability: "apps.call",
                 operation: appCallOperation(call.appId, method),
+                effect: "write",
             }).kind === "admitted"))) {
             capabilities.push({
                 ...appCallsDescriptor,
@@ -1119,6 +1135,7 @@ export function createOyster(host) {
                 kind: "capability-route",
                 capability: "apps.call",
                 operation: appCallOperation(appId, method),
+                effect: "write",
             }).kind === "admitted");
         };
         if (!(await allows(caller, principal)))

package/dist/keys.d.ts

@@ -2,12 +2,13 @@ import type { Grant, GrantVocabulary, Scope } from "@fungi.computer/ear-tag/gran
 import type { KeyPrincipal, KeyRecord, KeyStore } from "@fungi.computer/ear-tag/keys";
 import type { AppToolPolicy } from "./apps/tools.js";
 /** Every capability an Oyster key may carry. */
-export type OysterKeyCapability = "apps.read" | "apps.use" | "computer.use" | "machine.enroll";
+export type OysterKeyCapability = "apps.read" | "apps.use" | "agents.use" | "computer.use" | "machine.enroll";
 /**
  * `apps.use` also reaches `apps.read` (one level, per `defineGrants`'s own
  * `implies`): a key that may change an App's data may also read it.
  * `computer.use` has no narrower capability under it; the Computer is on or
  * off, host-wide.
+ * `agents.use` selects Agent ids independently of App grants.
  * `machine.enroll` admits enrollment only; it implies no App or Computer access.
  * The enrollment owner, not this vocabulary, owns one-use consumption.
  */
@@ -46,6 +47,8 @@ export type LiveOysterKey = Readonly<{
  * binding name for MCP) to reach the full `AppToolAccess`.
  */
 export declare function keyAppAccess(key: LiveOysterKey, installationId: string): AppToolPolicy | null;
+/** Agent access is scoped to the granted Agent ids, never inferred from App grants. */
+export declare function keyAgentAccess(key: LiveOysterKey, agentId: string): boolean;
 /** Whether a live key's own grants turn its Computer access on. Off by default. */
 export declare function keyAllowsComputerUse(key: LiveOysterKey): boolean;
 /** Whether a live key's grants permit a one-use device enrollment. */

package/dist/keys.js

@@ -1,7 +1,7 @@
 /**
- * Oyster's own Ear Tag vocabulary: named keys an owner issues for its
- * installed Apps, its Computer or machine enrollment. A key's id is its name, so
- * forks and other name-derived identities stay stable across the cutover.
+ * Oyster's own Ear Tag vocabulary: named keys an owner issues for selected
+ * Apps and Agents, its Computer or machine enrollment. App grants never imply
+ * Agent access. A key's id is its name, so name-derived identities stay stable.
  */
 import { defineGrants } from "@fungi.computer/ear-tag/grants";
 /**
@@ -9,11 +9,18 @@ import { defineGrants } from "@fungi.computer/ear-tag/grants";
  * `implies`): a key that may change an App's data may also read it.
  * `computer.use` has no narrower capability under it; the Computer is on or
  * off, host-wide.
+ * `agents.use` selects Agent ids independently of App grants.
  * `machine.enroll` admits enrollment only; it implies no App or Computer access.
  * The enrollment owner, not this vocabulary, owns one-use consumption.
  */
 export const oysterKeyVocabulary = defineGrants({
-    capabilities: ["apps.read", "apps.use", "computer.use", "machine.enroll"],
+    capabilities: [
+        "apps.read",
+        "apps.use",
+        "agents.use",
+        "computer.use",
+        "machine.enroll",
+    ],
     implies: { "apps.use": ["apps.read"] },
 });
 /** A grant reaching every current and future installation for `capability`. */
@@ -48,6 +55,10 @@ export function keyAppAccess(key, installationId) {
         grantedBy: key.owner,
     };
 }
+/** Agent access is scoped to the granted Agent ids, never inferred from App grants. */
+export function keyAgentAccess(key, agentId) {
+    return oysterKeyVocabulary.grantsAllow(key.grants, "agents.use", agentId);
+}
 /** Whether a live key's own grants turn its Computer access on. Off by default. */
 export function keyAllowsComputerUse(key) {
     return oysterKeyVocabulary.grantsAllow(key.grants, "computer.use");

package/dist/machine-link/authority.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { PostDeliveryResult, PostEnvelope } from "@fungi.computer/carrier/post";
 import type { MachineAgentHome } from "./home.js";
+import type { MachineLinkDispositionMail } from "./disposition.js";
 export declare const machineLinkIdentitySchema: z.ZodObject<{
     teamId: z.ZodString;
     deviceId: z.ZodString;
@@ -73,10 +74,16 @@ export type MachineLinkAuthority = Readonly<{
         agentId: string;
         name: string;
     }[]>;
+    /** Current home of one Team Agent, including machine-hosted homes. */
+    agentHome(id: MachineLinkIdentity, agentId: string): Promise<MachineAgentHome | null>;
     /** Sender, actor and the target's actual home, rechecked for this act. */
     resolveTarget(id: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, requesterAgentId: string | null): Promise<MachineLinkTargetFacts>;
     /** Carry mail received from this device to its target's actual home. */
     deliverHome(id: MachineLinkIdentity, caller: MachineLinkCaller, target: MachineLinkTargetFacts, envelope: PostEnvelope): Promise<PostDeliveryResult>;
+    /** Deliver a typed expiry reply authenticated by this device's held row. */
+    deliverUndeliverable(id: MachineLinkIdentity, original: MachineLinkDispositionMail, reply: MachineLinkDispositionMail): Promise<PostDeliveryResult>;
+    /** Ask the sending link to attest that it durably staged this disposition. */
+    verifyRelayDisposition(relay: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<boolean>;
     /** Whether this link's replay ledger may be erased now. */
     canErase(id: MachineLinkIdentity): Promise<boolean>;
     /** Push one committed fence fact to the device's link (C2 promptness). */

package/dist/machine-link/delivery.d.ts

@@ -1,6 +1,8 @@
 import * as Schema from "effect/Schema";
 import { type PostEnvelope, type PostDeliveryResult, type PostRoute } from "@fungi.computer/carrier/post";
 import { type MachineAgentHome } from "./home.js";
+import type { MachineLinkIdentity } from "./authority.js";
+import type { MachineLinkDispositionMail } from "./disposition.js";
 /**
  * Home selection only, as the namespace under the host's disclosure-owning
  * Agent mail route. Carrier retains retries; the receiving Agent admits work.
@@ -16,3 +18,13 @@ export declare function createHomeAwareAgentMailNamespace(options: {
     /** Host's Agent grammar: validates Accepted or Held without conflating them. */
     accepted: (receipt: Schema.Json) => void;
 }): PostRoute<never, never>["namespace"];
+/** Route one checked expiry reply through the same home-aware mail owner. */
+export declare function deliverUndeliverableMail(options: {
+    identity: MachineLinkIdentity;
+    original: MachineLinkDispositionMail;
+    reply: MachineLinkDispositionMail;
+    senderHome: MachineAgentHome;
+    hosted: PostRoute<never, never>["namespace"];
+    machine: (deviceId: string, envelope: PostEnvelope) => Promise<PostDeliveryResult>;
+    accepted: (receipt: Schema.Json) => void;
+}): Promise<PostDeliveryResult>;

package/dist/machine-link/delivery.js

@@ -23,12 +23,17 @@ export function createHomeAwareAgentMailNamespace(options) {
                 const mail = Schema.decodeUnknownSync(BirdDogMailSchema, {
                     onExcessProperty: "error",
                 })(envelope.event);
+                const senderMatches = mail.from.kind === "agent" &&
+                    mail.from.agentId === options.sender.agentId;
+                const systemOfflineDisposition = mail.from.kind === "system" &&
+                    mail.reply?.outcome === "undeliverable" &&
+                    mail.reply.reason === "recipient_offline";
                 if (envelope.kind !== "agentMail" ||
                     envelope.key !== mail.key ||
                     address.scopeId !== options.sender.teamId ||
                     address.agentId !== agentId ||
                     mail.to.agentId !== agentId ||
-                    mail.from.agentId !== options.sender.agentId)
+                    (!senderMatches && !systemOfflineDisposition))
                     return "refused";
                 const projected = await options.home(agentId);
                 if (projected === null)
@@ -52,3 +57,19 @@ export function createHomeAwareAgentMailNamespace(options) {
         }),
     };
 }
+/** Route one checked expiry reply through the same home-aware mail owner. */
+export function deliverUndeliverableMail(options) {
+    const sent = options.original.event;
+    if (sent.from.kind !== "agent")
+        return Promise.resolve("refused");
+    const senderAgentId = sent.from.agentId;
+    return createHomeAwareAgentMailNamespace({
+        sender: { teamId: options.identity.teamId, agentId: sent.to.agentId },
+        home: (agentId) => Promise.resolve(agentId === senderAgentId ? options.senderHome : null),
+        hosted: options.hosted,
+        machine: options.machine,
+        accepted: options.accepted,
+    })
+        .getByName(senderAgentId)
+        .deliver(options.reply);
+}

package/dist/machine-link/disposition.d.ts

@@ -0,0 +1,16 @@
+import * as Schema from "effect/Schema";
+import type { BirdDogMail } from "@fungi.computer/bird-dog";
+import { agentMailAddressSchema } from "@fungi.computer/seam/machine-link-protocol";
+import type { PostEnvelope } from "@fungi.computer/carrier/post";
+import type { MachineLinkIdentity } from "./authority.js";
+export type MachineLinkDispositionMail = Readonly<{
+    key: string;
+    kind: "agentMail";
+    address: Schema.Schema.Type<typeof agentMailAddressSchema>;
+    event: BirdDogMail;
+}>;
+/** Parse and authenticate the only terminal reply a device relay may author. */
+export declare function machineLinkDisposition(identity: MachineLinkIdentity, rawOriginal: PostEnvelope, rawReply: PostEnvelope): Readonly<{
+    original: MachineLinkDispositionMail;
+    reply: MachineLinkDispositionMail;
+}> | undefined;

package/dist/machine-link/disposition.js

@@ -0,0 +1,65 @@
+import * as Schema from "effect/Schema";
+import { BirdDogMailSchema } from "@fungi.computer/bird-dog/effect";
+import { agentMailAddressSchema } from "@fungi.computer/seam/machine-link-protocol";
+const machineMailEnvelope = Schema.Struct({
+    key: Schema.String,
+    kind: Schema.Literal("agentMail"),
+    address: agentMailAddressSchema,
+    event: BirdDogMailSchema,
+});
+function originalMatchesLink(identity, original) {
+    const sentFrom = original.event.from;
+    if (sentFrom.kind !== "agent")
+        return false;
+    return (original.key === original.event.key &&
+        original.address.scopeId === identity.teamId &&
+        original.address.agentId === original.event.to.agentId &&
+        original.event.reply === undefined);
+}
+function reverseIdentityMatches(original, reply) {
+    const sentFrom = original.event.from;
+    if (sentFrom.kind !== "agent")
+        return false;
+    return (reply.event.from.kind === "system" &&
+        reply.event.to.agentId === sentFrom.agentId &&
+        reply.event.to.sessionId === sentFrom.sessionId);
+}
+function replyMatchesDisposition(identity, original, reply) {
+    const sent = original.event;
+    const returned = reply.event;
+    if (sent.from.kind !== "agent")
+        return false;
+    const senderAgentId = sent.from.agentId;
+    const expectedKey = `${original.key}:reply:0`;
+    return [
+        reply.key === expectedKey,
+        returned.key === reply.key,
+        reply.address.scopeId === identity.teamId,
+        reply.address.agentId === senderAgentId,
+        returned.replyTo.length === 0,
+        returned.reply?.outcome === "undeliverable",
+        returned.reply?.outcome === "undeliverable" &&
+            returned.reply.reason === "recipient_offline",
+        reverseIdentityMatches(original, reply),
+    ].every((valid) => valid);
+}
+/** Parse and authenticate the only terminal reply a device relay may author. */
+export function machineLinkDisposition(identity, rawOriginal, rawReply) {
+    let original;
+    let reply;
+    try {
+        original = Schema.decodeUnknownSync(machineMailEnvelope, {
+            onExcessProperty: "error",
+        })(rawOriginal);
+        reply = Schema.decodeUnknownSync(machineMailEnvelope, {
+            onExcessProperty: "error",
+        })(rawReply);
+    }
+    catch {
+        return undefined;
+    }
+    if (!originalMatchesLink(identity, original) ||
+        !replyMatchesDisposition(identity, original, reply))
+        return undefined;
+    return { original, reply };
+}

package/dist/machine-link/host.d.ts

@@ -33,6 +33,8 @@ export declare class MachineLinkHost {
         authorize: (deviceId: string) => Promise<MachineLinkDevice>;
         replay: () => Promise<SeamReplayStore>;
         receive: (device: MachineLinkDevice, envelope: PostEnvelope) => Promise<PostDeliveryResult>;
+        /** Deliver one relay-authored reply to its original sender. */
+        disposition: (original: PostEnvelope, reply: PostEnvelope) => Promise<PostDeliveryResult>;
         /** Arm the Durable Object alarm for Carrier/Watchdog progress. */
         scheduleWake: (at: number) => Promise<void>;
         /** The host's failure log for refused dials and closed links. */
@@ -44,12 +46,17 @@ export declare class MachineLinkHost {
     connected(socket: WebSocket, deviceId: string): Promise<void>;
     private publishDirectory;
     private channel;
-    deliver(deviceId: string, envelope: PostEnvelope): Promise<PostDeliveryResult>;
+    deliver(deviceId: string, envelope: PostEnvelope, options?: Readonly<{
+        refuseDuplicate?: boolean;
+    }>): Promise<PostDeliveryResult>;
     private deliverLiveOperation;
     private deliverCustodyMail;
     /** Run due Carrier work; expired rows remain visible as Carrier dead letters. */
     alarm(): Promise<void>;
-    /** Expose terminal custody rows so S9 can stage its own disposition reply. */
+    /** Turn each terminal incoming-mail row into a durable reply outbox row. */
+    private stageUndeliverableReplies;
+    private stageUndeliverableReply;
+    /** Expose terminal custody rows for the device-owned diagnostic surface. */
     deadLetters(afterKey?: string): Promise<Readonly<{
         letters: readonly Readonly<{
             key: string;
@@ -59,6 +66,8 @@ export declare class MachineLinkHost {
         }>[];
         nextCursor: string | undefined;
     }>>;
+    /** Prove a disposition is still present in this link's durable Post outbox. */
+    hasStagedDisposition(deviceId: string, original: PostEnvelope, reply: PostEnvelope): Promise<boolean>;
     private deliverToSocket;
     private custody;
     private createCustody;

package/dist/machine-link/host.js

@@ -5,10 +5,12 @@ import { correlationKey } from "@fungi.computer/cairn";
 import { createMachineLinkPostChannel, MachineLinkPostUnavailable, machineLinkAudience, machineLinkProtocolVersion, } from "@fungi.computer/seam/machine-link-protocol";
 import { importSeamVerifiers, seamHeader, verifySeamRequest, } from "@fungi.computer/seam";
 import { createPost, definePostRoute, PostDeliveryResultSchema, } from "@fungi.computer/carrier/post";
+import { undeliverableReply } from "@fungi.computer/bird-dog";
 import { BirdDogMailSchema } from "@fungi.computer/bird-dog/effect";
 import { machineAgentOperationSchema } from "@fungi.computer/seam/machine-link-protocol";
 import { Watchdog, } from "@fungi.computer/watchdog";
 import { createMachineLinkSockets } from "./presence.js";
+import { machineLinkDisposition } from "./disposition.js";
 const attachmentSchema = z.strictObject({
     deviceId: z.string().min(1).max(256),
     fenceEpoch: z.int().nonnegative(),
@@ -48,6 +50,15 @@ const machineMailEnvelope = Schema.Struct({
     address: custodyAddress,
     event: BirdDogMailSchema,
 });
+const machineDispositionEnvelope = Schema.Struct({
+    key: Schema.String,
+    kind: Schema.Literal("machineLinkDisposition"),
+    address: custodyAddress,
+    event: Schema.Struct({
+        original: machineMailEnvelope,
+        reply: BirdDogMailSchema,
+    }),
+});
 const machineAgentEnvelope = Schema.Struct({
     key: Schema.String,
     kind: Schema.Literal("machineAgent"),
@@ -87,6 +98,25 @@ export class MachineLinkHost {
                     }),
                 },
             }),
+            machineLinkDisposition: definePostRoute({
+                addressKind: "machineLinkAgent",
+                address: custodyAddress,
+                event: machineDispositionEnvelope.fields.event,
+                name: ({ agentId }) => agentId,
+                namespace: {
+                    getByName: () => ({
+                        deliver: async (envelope) => {
+                            const typed = Schema.decodeUnknownSync(machineDispositionEnvelope, { onExcessProperty: "error" })(envelope);
+                            return await this.options.disposition(typed.event.original, {
+                                key: typed.key,
+                                kind: "agentMail",
+                                address: typed.address,
+                                event: typed.event.reply,
+                            });
+                        },
+                    }),
+                },
+            }),
         };
         context.setWebSocketAutoResponse(new WebSocketRequestResponsePair("ping", "pong"));
         this.router = new Hono().get("/api/teams/:teamId/local/mesh/:deviceId/connect", async (context) => {
@@ -141,6 +171,8 @@ export class MachineLinkHost {
         await this.publishDirectory(socket, deviceId);
         await this.releaseCustody();
         await this.drainCustody();
+        await this.stageUndeliverableReplies();
+        await this.drainCustody();
     }
     async publishDirectory(socket, deviceId) {
         this.deviceId = deviceId;
@@ -195,7 +227,7 @@ export class MachineLinkHost {
         }
         return channel;
     }
-    async deliver(deviceId, envelope) {
+    async deliver(deviceId, envelope, options = {}) {
         this.deviceId = deviceId;
         await this.options.authorize(deviceId);
         const links = createMachineLinkSockets(this.context, deviceId);
@@ -205,7 +237,7 @@ export class MachineLinkHost {
         const typedEnvelope = Schema.decodeUnknownSync(Schema.Union([machineMailEnvelope, machineAgentEnvelope]))(envelope);
         if (typedEnvelope.kind === "machineAgent")
             return await this.deliverLiveOperation(deviceId, socket, typedEnvelope);
-        return await this.deliverCustodyMail(deviceId, socket, typedEnvelope);
+        return await this.deliverCustodyMail(deviceId, socket, typedEnvelope, options.refuseDuplicate === true);
     }
     async deliverLiveOperation(deviceId, socket, envelope) {
         if (socket === undefined)
@@ -213,18 +245,31 @@ export class MachineLinkHost {
         await this.publishDirectory(socket, deviceId);
         return await this.channel(socket, deviceId).deliver(envelope);
     }
-    async deliverCustodyMail(deviceId, socket, envelope) {
+    async deliverCustodyMail(deviceId, socket, envelope, refuseDuplicate = false) {
         const { post } = await this.custody();
         const existing = post.read(envelope.key);
         if (existing !== undefined) {
+            if (refuseDuplicate)
+                return "refused";
             this.owner.transactionSync(() => {
                 post.send(envelope);
             });
             return previousCustodyReceipt(existing);
         }
-        this.owner.transactionSync(() => {
+        const duplicate = this.owner.transactionSync(() => {
+            if (post.read(envelope.key) !== undefined)
+                return true;
             post.send(envelope);
+            return false;
         });
+        if (duplicate) {
+            if (refuseDuplicate)
+                return "refused";
+            const raced = post.read(envelope.key);
+            return raced === undefined
+                ? recipientOffline
+                : previousCustodyReceipt(raced);
+        }
         await this.options.scheduleWake(post.nextWake() ?? Date.now());
         if (socket === undefined)
             return recipientOffline;
@@ -237,12 +282,87 @@ export class MachineLinkHost {
     /** Run due Carrier work; expired rows remain visible as Carrier dead letters. */
     async alarm() {
         await this.drainCustody();
+        await this.stageUndeliverableReplies();
+        await this.drainCustody();
+    }
+    /** Turn each terminal incoming-mail row into a durable reply outbox row. */
+    async stageUndeliverableReplies() {
+        const { post } = await this.custody();
+        let cursor;
+        do {
+            const page = post.deadLetters(64, cursor);
+            for (const letter of page.letters)
+                this.stageUndeliverableReply(post, letter);
+            cursor = page.nextCursor;
+        } while (cursor !== undefined);
+    }
+    stageUndeliverableReply(post, letter) {
+        if ((letter.reason !== "exhausted" && letter.reason !== "expired") ||
+            letter.envelope.kind !== "agentMail")
+            return;
+        const original = Schema.decodeUnknownSync(machineMailEnvelope, {
+            onExcessProperty: "error",
+        })(letter.envelope);
+        if (original.event.reply !== undefined ||
+            original.event.from.kind !== "agent")
+            return;
+        const replyKey = `${original.key}:reply:0`;
+        if (post.read(replyKey) !== undefined)
+            return;
+        const reply = {
+            key: replyKey,
+            kind: "agentMail",
+            address: {
+                scopeId: original.address.scopeId,
+                agentId: original.event.from.agentId,
+            },
+            event: undeliverableReply(original.event, Date.now()),
+        };
+        const disposition = {
+            key: replyKey,
+            kind: "machineLinkDisposition",
+            address: reply.address,
+            event: { original, reply: reply.event },
+        };
+        this.owner.transactionSync(() => {
+            if (post.read(replyKey) === undefined)
+                post.send(disposition);
+        });
     }
-    /** Expose terminal custody rows so S9 can stage its own disposition reply. */
+    /** Expose terminal custody rows for the device-owned diagnostic surface. */
     async deadLetters(afterKey) {
         const { post } = await this.custody();
         return post.deadLetters(64, afterKey);
     }
+    /** Prove a disposition is still present in this link's durable Post outbox. */
+    async hasStagedDisposition(deviceId, original, reply) {
+        this.deviceId = deviceId;
+        await this.options.authorize(deviceId);
+        const identity = { teamId: this.options.teamId, deviceId };
+        const requested = machineLinkDisposition(identity, original, reply);
+        if (requested === undefined)
+            return false;
+        const { post } = await this.custody();
+        const row = post.read(requested.reply.key);
+        if (row?.state !== "pending")
+            return false;
+        try {
+            const staged = Schema.decodeUnknownSync(machineDispositionEnvelope, {
+                onExcessProperty: "error",
+            })(row.envelope);
+            const stagedDisposition = machineLinkDisposition(identity, staged.event.original, {
+                key: staged.key,
+                kind: "agentMail",
+                address: staged.address,
+                event: staged.event.reply,
+            });
+            return (stagedDisposition !== undefined &&
+                JSON.stringify(stagedDisposition) === JSON.stringify(requested));
+        }
+        catch {
+            return false;
+        }
+    }
     async deliverToSocket(envelope) {
         const deviceId = this.deviceId;
         if (deviceId === undefined)

package/dist/machine-link/link.d.ts

@@ -29,6 +29,10 @@ export declare function createMachineLink<Readback>(state: MachineLinkState, opt
     fetch: (request: Request) => Promise<Response>;
     /** Mail addressed to this device's Agent, rechecked against its home. */
     deliver(input: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, envelope: PostEnvelope): Promise<PostDeliveryResult>;
+    /** A relay's typed terminal reply to an Agent homed on this device. */
+    deliverRelayDisposition(input: MachineLinkIdentity, relayInput: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<PostDeliveryResult>;
+    /** Attest a still-pending disposition in this device's own Post outbox. */
+    hasStagedDisposition(input: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<boolean>;
     /** One finite Agent operation on this device, returning its receipt. */
     operation(input: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, raw: MachineAgentOperation): Promise<Schema.Json>;
     /**