@fungi.computer/oyster 0.4.1 → 0.6.0

package/dist/internal/host-gate.js

@@ -2,24 +2,31 @@ import { emptyAppDeclaration } from "@fungi.computer/puffball/app";
 import { deriveDeclaredOperations } from "../apps/operations.js";
 import { keyAppAccess } from "../keys.js";
 import { defaultAssetPolicy, verifyRelease, } from "../release.js";
+/** Verified Releases one cache keeps; the least recently added leaves first. */
+const releaseCacheLimit = 256;
 /**
- * Verify each Release once per process: a failed read is not cached, so the
- * next request reads it again. Installation verified every asset; serving
- * verifies each on read.
+ * Verify each Release once per owner (an isolate's HTTP host, or the
+ * Registry): a failed read is not cached, so the next request reads it again.
+ * Installation verified every asset; serving verifies each on read. A Release
+ * is content-addressed and immutable, so the key is its ID and root digest and
+ * a hit never goes stale; the bound only forgets the oldest-verified Releases.
  */
-export function releaseCache(artifacts) {
+export function releaseCache(artifacts, limit = releaseCacheLimit) {
     const verified = new Map();
     return (release) => {
         const key = `${release.releaseId}:${release.artifact.artifactDigest}`;
         let entry = verified.get(key);
         if (entry === undefined) {
-            // A failed read is not cached: the next request reads the Release again.
-            // Installation verified every asset; serving verifies each on read.
-            entry = verifyRelease(artifacts, release, defaultAssetPolicy, false).then((value) => value, (cause) => {
+            entry = verifyRelease(artifacts, release, defaultAssetPolicy, false).catch((cause) => {
                 verified.delete(key);
                 throw cause;
             });
             verified.set(key, entry);
+            for (const oldest of verified.keys()) {
+                if (verified.size <= limit)
+                    break;
+                verified.delete(oldest);
+            }
         }
         return entry;
     };

package/dist/invocation.d.ts

@@ -193,7 +193,7 @@ export declare function assertBackgroundBinding(frame: InvocationFrame<Backgroun
 export declare function admitBackgroundFrame(key: CryptoKey, frame: InvocationFrame<BackgroundFrameState>, raw: unknown): Promise<ClaimedJobAdmission>;
 /** The host's native guest-abort and authority-close hooks. */
 export type InvocationGatePorts<Host> = Readonly<{
-    /** Stop the guest when the captured invocation's authority closes. */
+    /** Stop the guest when live authority closes early (revocation, expiry). */
     abortGuest: () => Promise<void>;
     /** Release the host resources belonging to this completed or revoked frame. */
     close: (frame: InvocationFrame<Host>) => Promise<void>;
@@ -204,8 +204,8 @@ export type InvocationGatePorts<Host> = Readonly<{
 export type InvocationGate<Host> = Readonly<{
     /** Run work within one immutable frame and close its authority afterward. */
     run: <A>(facts: InvocationFacts, host: Host, work: (frame: InvocationFrame<Host>) => Promise<A>) => Promise<A>;
-    /** Resolve the sole admitted frame, refusing outside an active invocation. */
-    active: () => InvocationFrame<Host>;
+    /** Resolve one live frame by its id, refusing a closed or unknown frame. */
+    active: (frameId: string) => InvocationFrame<Host>;
     /** Close live authority, optionally restricted to frames of a selected run. */
     revoke: (reason?: Error, target?: Readonly<{
         runId: string;
@@ -215,7 +215,14 @@ export type InvocationGate<Host> = Readonly<{
 }>;
 /** Decode only identities minted from the invocation-frame ID family. */
 export declare const invocationFrameIdSchema: Schema.String;
-/** Serialize authority, preempt replay only for verified writes, and close each guest before admission. */
+/**
+ * Admit frames against one guest. Verified foreground reads share it, up to
+ * eight at once; writes, raw backend requests, Gills and replay run alone. Every guest binding packet names its frame, so a finished
+ * frame's leftover timers cannot borrow a later frame's authority and a
+ * normal finish keeps the guest warm. Closing authority early (revocation,
+ * expiry, a write preempting replay) aborts the guest and so every frame
+ * sharing it; replay only yields to a verified write.
+ */
 export declare function createInvocationGate<Host>(ports: InvocationGatePorts<Host>): InvocationGate<Host>;
 /** Verified selection, artifact and binding grants before caller attribution. */
 export type InvocationAuthority = Omit<InvocationFacts, "subject" | "deadlineAt">;

package/dist/invocation.js

@@ -1,8 +1,6 @@
 import { approvedBindingGrants } from "./apps/gate.js";
 import { appToolPolicySchema } from "./apps/tools.js";
-import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import * as Semaphore from "effect/Semaphore";
 import { defineIdFamily } from "@fungi.computer/cairn/id";
 import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
 import { appBackendBindingKinds, appBackendBindingsSchema, appMethodCallContextSchema, } from "@fungi.computer/puffball/app";
@@ -116,6 +114,8 @@ export async function admitBackgroundFrame(key, frame, raw) {
     frame.host.origin = decision.kind;
     return decision;
 }
+/** Foreground reads one Instance runs at once; every other frame runs alone. */
+const concurrentReadFrames = 8;
 const frameIds = defineIdFamily({
     family: "app-invocation-frame",
     version: 1,
@@ -152,28 +152,79 @@ function immutableFacts(facts) {
     Object.freeze(facts.ancestry);
     return Object.freeze(facts);
 }
-/** Serialize authority, preempt replay only for verified writes, and close each guest before admission. */
+/**
+ * First-come permits over one guest: a waiting exclusive frame holds back
+ * every frame queued after it, so a stream of reads never starves a write.
+ */
+function orderedPermits(total) {
+    let available = total;
+    const waiting = [];
+    const admit = () => {
+        for (let next = waiting[0]; next !== undefined && next.permits <= available; next = waiting[0]) {
+            waiting.shift();
+            available -= next.permits;
+            next.enter();
+        }
+    };
+    return async (permits, work) => {
+        await new Promise((enter) => {
+            waiting.push({ permits, enter });
+            admit();
+        });
+        try {
+            return await work();
+        }
+        catch (cause) {
+            throw cause instanceof Error
+                ? cause
+                : new Error("App invocation failed", { cause });
+        }
+        finally {
+            available += permits;
+            admit();
+        }
+    };
+}
+/** A foreground call to a verified read method; only these share the guest. */
+function concurrentRead(facts) {
+    return (facts.subject.kind === "call" &&
+        facts.subject.replay === undefined &&
+        facts.subject.method?.effect === "read");
+}
+/**
+ * Admit frames against one guest. Verified foreground reads share it, up to
+ * eight at once; writes, raw backend requests, Gills and replay run alone. Every guest binding packet names its frame, so a finished
+ * frame's leftover timers cannot borrow a later frame's authority and a
+ * normal finish keeps the guest warm. Closing authority early (revocation,
+ * expiry, a write preempting replay) aborts the guest and so every frame
+ * sharing it; replay only yields to a verified write.
+ */
 export function createInvocationGate(ports) {
-    const permit = Semaphore.makeUnsafe(1);
+    const withPermits = orderedPermits(concurrentReadFrames);
     const now = ports.now ?? Date.now;
     let foregroundWaiting = 0;
-    let active;
-    const close = (state, reason) => {
+    const live = new Map();
+    const finish = (state, reason) => {
         if (state.closing)
             return state.closing;
-        if (active === state)
-            active = undefined;
+        live.delete(state.frame.frameId);
         state.controller.abort(reason);
-        state.closing = (async () => {
-            try {
-                await ports.abortGuest();
-            }
-            finally {
-                await ports.close(state.frame);
-            }
-        })();
+        state.closing = ports.close(state.frame);
         return state.closing;
     };
+    // The guest is shared: aborting it ends every live frame's guest work, and
+    // each of those frames closes only after the guest abort has completed.
+    const abortAll = (reason) => {
+        const states = [...live.values()];
+        for (const state of states) {
+            live.delete(state.frame.frameId);
+            state.controller.abort(reason);
+        }
+        const guest = ports.abortGuest();
+        for (const state of states)
+            state.closing ??= guest.finally(() => ports.close(state.frame));
+        return Promise.all([guest, ...states.map((state) => state.closing)]).then(() => undefined);
+    };
     const run = async (input, host, work) => {
         let facts;
         try {
@@ -196,64 +247,63 @@ export function createInvocationGate(ports) {
             if (queuedForeground &&
                 facts.subject.kind === "call" &&
                 facts.subject.method?.effect === "write" &&
-                active?.frame.facts.subject.kind === "call" &&
-                active.frame.facts.subject.replay !== undefined)
-                await close(active, new AppInstanceError("revoked"));
-            return await Effect.runPromise(permit.withPermits(1)(Effect.tryPromise({
-                try: async () => {
-                    if (facts.subject.kind === "call" &&
-                        facts.subject.replay !== undefined &&
-                        foregroundWaiting > 0)
-                        throw new AppInstanceError("revoked");
-                    if (queuedForeground) {
-                        foregroundWaiting -= 1;
-                        queuedForeground = false;
-                    }
-                    const { deadlineAt } = facts;
-                    if (deadlineAt <= now())
-                        throw new AppInstanceError("expired");
-                    const frameId = frameIds.frame.generate();
-                    const controller = new AbortController();
-                    const frame = Object.freeze({
-                        frameId,
-                        facts,
-                        host,
-                        signal: controller.signal,
+                [...live.values()].some(({ frame }) => frame.facts.subject.kind === "call" &&
+                    frame.facts.subject.replay !== undefined))
+                await abortAll(new AppInstanceError("revoked"));
+            return await withPermits(concurrentRead(facts) ? 1 : concurrentReadFrames, async () => {
+                if (facts.subject.kind === "call" &&
+                    facts.subject.replay !== undefined &&
+                    foregroundWaiting > 0)
+                    throw new AppInstanceError("revoked");
+                if (queuedForeground) {
+                    foregroundWaiting -= 1;
+                    queuedForeground = false;
+                }
+                const { deadlineAt } = facts;
+                if (deadlineAt <= now())
+                    throw new AppInstanceError("expired");
+                const frameId = frameIds.frame.generate();
+                const controller = new AbortController();
+                const frame = Object.freeze({
+                    frameId,
+                    facts,
+                    host,
+                    signal: controller.signal,
+                });
+                const state = { frame, controller };
+                live.set(frameId, state);
+                let timer;
+                let stop = () => undefined;
+                const revoked = new Promise((_resolve, reject) => {
+                    const onAbort = () => {
+                        const reason = controller.signal.reason;
+                        reject(reason instanceof Error
+                            ? reason
+                            : new AppInstanceError("revoked"));
+                    };
+                    controller.signal.addEventListener("abort", onAbort, {
+                        once: true,
                     });
-                    const state = { frame, controller };
-                    active = state;
-                    let timer;
-                    let stop = () => undefined;
-                    const revoked = new Promise((_resolve, reject) => {
-                        const onAbort = () => {
-                            const reason = controller.signal.reason;
-                            reject(reason instanceof Error
-                                ? reason
-                                : new AppInstanceError("revoked"));
-                        };
-                        controller.signal.addEventListener("abort", onAbort, {
-                            once: true,
-                        });
-                        stop = () => {
-                            controller.signal.removeEventListener("abort", onAbort);
-                        };
-                        timer = setTimeout(() => {
-                            controller.abort(new AppInstanceError("expired"));
-                        }, Math.max(0, deadlineAt - now()));
-                    });
-                    try {
-                        return await Promise.race([work(frame), revoked]);
-                    }
-                    finally {
-                        clearTimeout(timer);
-                        stop();
-                        await close(state, new AppInstanceError("revoked"));
-                    }
-                },
-                catch: (cause) => cause instanceof Error
-                    ? cause
-                    : new Error("App invocation failed", { cause }),
-            })));
+                    stop = () => {
+                        controller.signal.removeEventListener("abort", onAbort);
+                    };
+                    timer = setTimeout(() => {
+                        // An expired frame's guest may still be running. Each frame's own
+                        // run awaits its close, so a failure reaches that caller.
+                        void Promise.allSettled([
+                            abortAll(new AppInstanceError("expired")),
+                        ]);
+                    }, Math.max(0, deadlineAt - now()));
+                });
+                try {
+                    return await Promise.race([work(frame), revoked]);
+                }
+                finally {
+                    clearTimeout(timer);
+                    stop();
+                    await finish(state, new AppInstanceError("revoked"));
+                }
+            });
         }
         finally {
             if (queuedForeground)
@@ -262,27 +312,20 @@ export function createInvocationGate(ports) {
     };
     return {
         run,
-        exclusive: (work) => Effect.runPromise(permit.withPermits(1)(Effect.tryPromise({
-            try: work,
-            catch: (cause) => cause instanceof Error
-                ? cause
-                : new Error("Instance supervisor operation failed", { cause }),
-        }))),
-        active: () => {
-            if (active === undefined ||
-                active.controller.signal.aborted ||
-                active.frame.facts.deadlineAt <= now())
+        exclusive: (work) => withPermits(concurrentReadFrames, work),
+        active: (frameId) => {
+            const state = live.get(frameId);
+            if (state === undefined ||
+                state.controller.signal.aborted ||
+                state.frame.facts.deadlineAt <= now())
                 throw new AppInstanceError("revoked");
-            return active.frame;
+            return state.frame;
         },
         revoke: (reason = new AppInstanceError("revoked"), target) => {
-            if (active === undefined)
-                return Promise.resolve();
-            if (target !== undefined &&
-                (active.frame.facts.subject.kind !== "call" ||
-                    active.frame.facts.subject.context.workflow?.runId !== target.runId))
-                return Promise.resolve();
-            return close(active, reason);
+            const matched = [...live.values()].some(({ frame }) => target === undefined ||
+                (frame.facts.subject.kind === "call" &&
+                    frame.facts.subject.context.workflow?.runId === target.runId));
+            return matched ? abortAll(reason) : Promise.resolve();
         },
     };
 }

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;