harnery 0.45.2 → 0.46.0

package/dist/core/inbox/service.d.ts

@@ -6,6 +6,8 @@ export interface HarneryInboxServiceOptions {
     id?: () => string;
 }
 export interface HarneryInboxSendInput {
+    message_id?: string;
+    replay_only?: boolean;
     sender_instance_id: string | null;
     sender_display_name: string;
     recipient_instance_id: string;
@@ -13,15 +15,20 @@ export interface HarneryInboxSendInput {
     body: string;
 }
 export interface HarneryInboxSendReceipt {
-    state: "queued";
+    state: "queued" | "duplicate";
     message_id: string;
     body_bytes: number;
     synced: true;
 }
+/** A caller freezes the operation and recipient before its first attempt. */
+export declare function stableInboxMessageId(operationId: string, recipientInstanceId: string): string;
 export declare class HarneryInboxService {
     #private;
     constructor(options: HarneryInboxServiceOptions);
     send(input: HarneryInboxSendInput): HarneryInboxSendReceipt;
+    /** Append a message created on another machine, keeping its id. Importers
+     * on one machine can race, so the duplicate check runs under the lease. */
+    receive(record: HarneryInboxMessageRecordV1): "received" | "duplicate";
     records(recipientInstanceId: string): HarneryInboxRecordV1[];
     pending(recipientInstanceId: string): HarneryInboxMessageRecordV1[];
     status(recipientInstanceId: string): HarneryInboxStatusV1;

package/dist/core/inbox/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/service.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,CAAC;CACd;AAED,qBAAa,mBAAmB;;gBAGlB,OAAO,EAAE,0BAA0B;IAK/C,IAAI,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB;IA2C3D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB,EAAE;IAS5D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,2BAA2B,EAAE;IAInE,MAAM,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB;IA0BnD,OAAO,CACX,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAChF,MAAM,GAAE,yBAIP,GACA,OAAO,CAAC,yBAAyB,CAAC;IAiBrC;0EACsE;IACtE,cAAc,CACZ,mBAAmB,EAAE,MAAM,EAC3B,MAAM,GAAE,yBAIP,GACA,2BAA2B,EAAE;IAKhC;;2DAEuD;IACvD,kBAAkB,CAAC,mBAAmB,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;CA2BrF;AA4BD,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,GAAG;IACjE,OAAO,EAAE,2BAA2B,EAAE,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAsBA"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/service.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,kBAAkB,EAGvB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,CAAC;CACd;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAO7F;AAED,qBAAa,mBAAmB;;gBAGlB,OAAO,EAAE,0BAA0B;IAK/C,IAAI,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB;IAsE3D;+EAC2E;IAC3E,OAAO,CAAC,MAAM,EAAE,2BAA2B,GAAG,UAAU,GAAG,WAAW;IA4CtE,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB,EAAE;IAS5D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,2BAA2B,EAAE;IAInE,MAAM,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB;IA0BnD,OAAO,CACX,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAChF,MAAM,GAAE,yBAIP,GACA,OAAO,CAAC,yBAAyB,CAAC;IAiBrC;0EACsE;IACtE,cAAc,CACZ,mBAAmB,EAAE,MAAM,EAC3B,MAAM,GAAE,yBAIP,GACA,2BAA2B,EAAE;IAKhC;;2DAEuD;IACvD,kBAAkB,CAAC,mBAAmB,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;CA2BrF;AA8CD,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,GAAG;IACjE,OAAO,EAAE,2BAA2B,EAAE,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAsBA"}

package/dist/core/inbox/service.js

@@ -1,8 +1,17 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { readCrashSafeJsonlFile, updateCrashSafeJsonlFile, } from "../storage/durable-history.js";
-import { HARNERY_INBOX_RECORD_SCHEMA, HARNERY_INBOX_STATUS_SCHEMA, HarneryInboxCapacityError, } from "./contract.js";
+import { HARNERY_INBOX_RECORD_SCHEMA, HARNERY_INBOX_STATUS_SCHEMA, HarneryInboxCapacityError, HarneryInboxMessageConflictError, HarneryInboxMessageHistoryMissingError, } from "./contract.js";
+/** A caller freezes the operation and recipient before its first attempt. */
+export function stableInboxMessageId(operationId, recipientInstanceId) {
+    const identity = JSON.stringify([
+        "harnery.inbox-operation/v1",
+        opaqueId(operationId, "operation"),
+        opaqueId(recipientInstanceId, "recipient instance"),
+    ]);
+    return `msg_op_${createHash("sha256").update(identity).digest("hex")}`;
+}
 export class HarneryInboxService {
     #options;
     constructor(options) {
@@ -10,6 +19,12 @@ export class HarneryInboxService {
         this.#options = options;
     }
     send(input) {
+        if (input.replay_only !== undefined && typeof input.replay_only !== "boolean") {
+            throw new Error("invalid replay_only flag");
+        }
+        if (input.replay_only && input.message_id === undefined) {
+            throw new Error("replay requires explicit message id");
+        }
         const recipient = opaqueId(input.recipient_instance_id, "recipient instance");
         const bodyBytes = Buffer.byteLength(input.body);
         const limits = this.#options.limits;
@@ -19,7 +34,9 @@ export class HarneryInboxService {
         const record = {
             schema: HARNERY_INBOX_RECORD_SCHEMA,
             kind: "message",
-            message_id: `msg_${this.#options.id?.() ?? randomUUID()}`,
+            message_id: input.message_id === undefined
+                ? `msg_${this.#options.id?.() ?? randomUUID()}`
+                : opaqueId(input.message_id, "message"),
             sender_instance_id: senderId(input.sender_instance_id),
             sender_display_name: boundedDisplay(input.sender_display_name),
             recipient_instance_id: recipient,
@@ -31,6 +48,21 @@ export class HarneryInboxService {
         const path = inboxPath(this.#options.coord_root, recipient);
         return updateInboxHistory(path, readOptions(limits), (records) => {
             const projection = project(records);
+            const existing = records.find((item) => item.kind === "message" && item.message_id === record.message_id);
+            if (existing) {
+                assertSameMessage(existing, record);
+                return {
+                    result: {
+                        state: "duplicate",
+                        message_id: existing.message_id,
+                        body_bytes: existing.body_bytes,
+                        synced: true,
+                    },
+                };
+            }
+            if (input.replay_only) {
+                throw new HarneryInboxMessageHistoryMissingError(record.message_id);
+            }
             capacityCheck(projection, record, path, limits);
             return {
                 append: [record],
@@ -43,6 +75,40 @@ export class HarneryInboxService {
             };
         });
     }
+    /** Append a message created on another machine, keeping its id. Importers
+     * on one machine can race, so the duplicate check runs under the lease. */
+    receive(record) {
+        const recipient = opaqueId(record.recipient_instance_id, "recipient instance");
+        const limits = this.#options.limits;
+        if (record.body_bytes === 0 || record.body_bytes > limits.max_message_body_bytes) {
+            throw new HarneryInboxCapacityError("message_body_limit", record.body_bytes, limits.max_message_body_bytes);
+        }
+        const incoming = {
+            schema: HARNERY_INBOX_RECORD_SCHEMA,
+            kind: "message",
+            message_id: opaqueId(record.message_id, "message"),
+            sender_instance_id: senderId(record.sender_instance_id),
+            sender_display_name: boundedDisplay(record.sender_display_name),
+            ...(record.sender_machine ? { sender_machine: boundedDisplay(record.sender_machine) } : {}),
+            recipient_instance_id: recipient,
+            recipient_display_name: boundedDisplay(record.recipient_display_name),
+            created_at: record.created_at,
+            body: record.body,
+            body_bytes: record.body_bytes,
+        };
+        validateRecord(incoming);
+        const path = inboxPath(this.#options.coord_root, recipient);
+        return updateInboxHistory(path, readOptions(limits), (records) => {
+            const projection = project(records);
+            const existing = records.find((item) => item.kind === "message" && item.message_id === incoming.message_id);
+            if (existing) {
+                assertSameMessage(existing, incoming);
+                return { result: "duplicate" };
+            }
+            capacityCheck(projection, incoming, path, limits);
+            return { append: [incoming], result: "received" };
+        });
+    }
     records(recipientInstanceId) {
         const records = readCrashSafeJsonlFile(inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")), readOptions(this.#options.limits));
         for (const record of records)
@@ -125,6 +191,20 @@ export class HarneryInboxService {
         }
     }
 }
+function assertSameMessage(existing, incoming) {
+    const fields = [
+        "sender_instance_id",
+        "sender_display_name",
+        "sender_machine",
+        "recipient_instance_id",
+        "recipient_display_name",
+        "body",
+        "body_bytes",
+    ];
+    if (fields.some((field) => existing[field] !== incoming[field])) {
+        throw new HarneryInboxMessageConflictError(incoming.message_id);
+    }
+}
 /** The shared writer refuses an occupied lease before invoking the update.
  * Briefly retry only that exact refusal so concurrent peer senders both get
  * a chance to append. All validation, authority and I/O failures still fail

package/dist/core/inbox/targets.d.ts

@@ -1,6 +1,9 @@
+import { type CoordinationViewV3 } from "../events/v3/coordination-view.js";
 export interface MessageTargetInput {
     name?: string;
     instanceId?: string;
+    /** Refuse a later generation of the same immutable instance. */
+    generationId?: string;
     requireLive?: boolean;
     now?: Date;
 }
@@ -9,14 +12,25 @@ export type MessageTargetResult = {
     target: {
         instance_id: string;
         name: string;
-        delivery: "written-live" | "queued";
+        delivery: "written-live" | "queued" | "remote";
+        /** Set when the recipient lives on another machine (ADR 0222). */
+        machine?: string;
     };
 } | {
     ok: false;
-    code: "no_peer" | "ambiguous_peer" | "not_live" | "authority_unsafe";
+    code: "no_peer" | "ambiguous_peer" | "not_live" | "authority_unsafe" | "generation_mismatch";
     message: string;
     candidates?: string[];
 };
 /** Resolve one immutable recipient without extending presence or claiming attention. */
-export declare function resolveMessageTarget(coordRoot: string, input: MessageTargetInput): MessageTargetResult;
+export declare function resolveMessageTarget(coordRoot: string, input: MessageTargetInput, options?: {
+    view?: CoordinationViewV3;
+}): MessageTargetResult;
+/**
+ * Resolve a recipient on another machine, for a name or instance this
+ * machine's ledger has never seen. Candidates come from peer presence (live
+ * or stale) and from senders this machine has received mail from. Returns
+ * null when nothing matches, so the caller can report the local miss.
+ */
+export declare function resolveRemoteMessageTarget(coordRoot: string, input: MessageTargetInput): MessageTargetResult | null;
 //# sourceMappingURL=targets.d.ts.map

package/dist/core/inbox/targets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/targets.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,mBAAmB,GAC3B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,cAAc,GAAG,QAAQ,CAAA;KAAE,CAAC;CACpF,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,SAAS,GAAG,gBAAgB,GAAG,UAAU,GAAG,kBAAkB,CAAC;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEN,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,CAwFrB"}
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/targets.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,kBAAkB,EAGxB,MAAM,mCAAmC,CAAC;AAS3C,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,mBAAmB,GAC3B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAC/C,kEAAkE;QAClE,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,SAAS,GAAG,gBAAgB,GAAG,UAAU,GAAG,kBAAkB,GAAG,qBAAqB,CAAC;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEN,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,kBAAkB,CAAA;CAAO,GAC1C,mBAAmB,CAkGrB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,GAAG,IAAI,CA2D5B"}

package/dist/core/inbox/targets.js

@@ -2,8 +2,10 @@ import { resolveName } from "../agents/state/names.js";
 import { coordFreshnessSeconds } from "../config.js";
 import { readCoordinationViewV3, requireAuthoritySafeCoordinationViewV3, } from "../events/v3/coordination-view.js";
 import { liveInstanceIdV3, nativeInstanceIdV3, observeLiveEventLedgerRouteV3, } from "../events/v3/live-route-observer.js";
+import { readRemoteMachines } from "../presence/index.js";
+import { knownRemoteSenders } from "../presence/mail.js";
 /** Resolve one immutable recipient without extending presence or claiming attention. */
-export function resolveMessageTarget(coordRoot, input) {
+export function resolveMessageTarget(coordRoot, input, options = {}) {
     const requestedName = normalizeName(input.name);
     const requestedInstance = input.instanceId?.trim();
     if (!requestedName && !requestedInstance) {
@@ -17,7 +19,7 @@ export function resolveMessageTarget(coordRoot, input) {
         if (observeLiveEventLedgerRouteV3(coordRoot).state === "blocked") {
             return unsafe("The event ledger cannot establish message recipient authority.");
         }
-        view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+        view = requireAuthoritySafeCoordinationViewV3(options.view ?? readCoordinationViewV3(coordRoot));
         if (!view.source_complete)
             return unsafe("The event ledger read is incomplete.");
     }
@@ -50,6 +52,7 @@ export function resolveMessageTarget(coordRoot, input) {
             {
                 instanceId,
                 name,
+                generationId: generation.generation_id,
                 safe: !diagnostics.some((diagnostic) => diagnostic.authority_blocking),
                 fresh: generation.phase === "live" && Number.isFinite(age) && age >= 0 && age <= freshnessMs,
             },
@@ -76,6 +79,13 @@ export function resolveMessageTarget(coordRoot, input) {
         };
     }
     const target = selected[0];
+    if (input.generationId && input.generationId !== target.generationId) {
+        return {
+            ok: false,
+            code: "generation_mismatch",
+            message: "The recipient generation differs from the exact requested generation.",
+        };
+    }
     if (input.requireLive && !target.fresh) {
         return {
             ok: false,
@@ -92,6 +102,71 @@ export function resolveMessageTarget(coordRoot, input) {
         },
     };
 }
+/**
+ * Resolve a recipient on another machine, for a name or instance this
+ * machine's ledger has never seen. Candidates come from peer presence (live
+ * or stale) and from senders this machine has received mail from. Returns
+ * null when nothing matches, so the caller can report the local miss.
+ */
+export function resolveRemoteMessageTarget(coordRoot, input) {
+    const requestedName = normalizeName(input.name);
+    const requestedInstance = input.instanceId?.trim();
+    if (!requestedName && !requestedInstance)
+        return null;
+    // Presence/mail names do not prove an exact V3 generation.
+    if (input.generationId)
+        return null;
+    const live = new Set(readRemoteMachines(coordRoot).flatMap(({ agents }) => agents.map((a) => a.instance_id)));
+    const known = new Map();
+    for (const { machine, agents } of readRemoteMachines(coordRoot, { includeStale: true })) {
+        for (const agent of agents) {
+            if (agent.name)
+                known.set(agent.instance_id, { instanceId: agent.instance_id, name: agent.name, machine });
+        }
+    }
+    for (const sender of knownRemoteSenders(coordRoot)) {
+        if (!known.has(sender.instance_id)) {
+            known.set(sender.instance_id, {
+                instanceId: sender.instance_id,
+                name: sender.name,
+                machine: sender.machine,
+            });
+        }
+    }
+    const candidates = [...known.values()]
+        .filter(({ instanceId }) => !requestedInstance || instanceId === requestedInstance)
+        .filter(({ name }) => !requestedName || normalizeName(name) === requestedName)
+        .map((candidate) => ({ ...candidate, fresh: live.has(candidate.instanceId) }));
+    if (candidates.length === 0)
+        return null;
+    const fresh = candidates.filter(({ fresh }) => fresh);
+    const selected = requestedInstance ? candidates : fresh.length > 0 ? fresh : candidates;
+    if (selected.length !== 1) {
+        return {
+            ok: false,
+            code: "ambiguous_peer",
+            message: "Several agent instances on other machines hold that exact name; specify --instance-id.",
+            candidates: selected.map(({ instanceId, machine }) => `${instanceId} (${machine})`).sort(),
+        };
+    }
+    const target = selected[0];
+    if (input.requireLive && !target.fresh) {
+        return {
+            ok: false,
+            code: "not_live",
+            message: "That agent is on another machine and outside live presence; omit --require-live to queue its message.",
+        };
+    }
+    return {
+        ok: true,
+        target: {
+            instance_id: target.instanceId,
+            name: target.name,
+            delivery: "remote",
+            machine: target.machine,
+        },
+    };
+}
 function laterPosition(left, right) {
     return (left.source_position.segment_ordinal > right.source_position.segment_ordinal ||
         (left.source_position.segment_ordinal === right.source_position.segment_ordinal &&

package/dist/core/presence/git.d.ts

@@ -1,5 +1,6 @@
 /**
- * Git plumbing for the cross-machine presence transport (ADR 0016).
+ * Git plumbing for the cross-machine presence transport (ADR 0016) and the
+ * mail refs that ride on it (ADR 0222).
  *
  * Presence blobs travel as parentless commits (empty tree, JSON message)
  * force-pushed to `refs/harnery/presence/<machine>` on the host repo's own
@@ -12,9 +13,12 @@
  * detached (hook path: never block a turn) or synchronously (CLI path: the
  * user wants to see errors).
  */
-/** The ref namespace. Hardcoded — never interpolated from config — so the
- * publisher is structurally unable to touch refs/heads/* (ADR 0016). */
+/** The ref namespaces. Hardcoded — never interpolated from config — so the
+ * publisher is structurally unable to touch refs/heads/* (ADR 0016). Mail
+ * refs carry cross-machine peer messages on the same transport (ADR 0222). */
 export declare const PRESENCE_REF_PREFIX = "refs/harnery/presence/";
+export declare const MAIL_REF_PREFIX = "refs/harnery/mail/";
+type HarneryRefPrefix = typeof PRESENCE_REF_PREFIX | typeof MAIL_REF_PREFIX;
 /** Does the repo have an `origin` remote to rendezvous on? */
 export declare function hasOrigin(root: string): boolean;
 /** The origin remote URL, or null. Input to relay room derivation. */
@@ -34,25 +38,26 @@ export declare function sanitizeRefComponent(label: string): string;
  * Returns the commit sha, or null on failure. Local-only, fast (~10ms). */
 export declare function writePresenceCommit(root: string, message: string): string | null;
 /**
- * Force-push a presence commit to `refs/harnery/presence/<machine>`.
- * `sync: true` (CLI/tests) waits and reports; default is detached fire-and-
- * forget (hook path — a slow or credential-less push must not block a turn).
+ * Force-push a commit to `<prefix><machine>` (presence or mail). `sync: true`
+ * (CLI/tests) waits and reports; default is detached fire-and-forget (hook
+ * path — a slow or credential-less push must not block a turn).
  */
-export declare function pushPresenceRef(root: string, machine: string, sha: string, opts?: {
+export declare function pushMachineRef(root: string, prefix: HarneryRefPrefix, machine: string, sha: string, opts?: {
     sync?: boolean;
 }): {
     ok: boolean;
     error?: string;
 };
-/** Fetch every peer presence ref from origin into the local ref namespace. */
-export declare function fetchPresenceRefs(root: string, opts?: {
+/** Fetch every peer presence and mail ref from origin into the local ref
+ * namespace, in one round trip. A namespace with no refs is not an error. */
+export declare function fetchMachineRefs(root: string, opts?: {
     sync?: boolean;
 }): {
     ok: boolean;
     error?: string;
 };
-/** Read every locally-known presence ref → [{ref, machine, message}]. */
-export declare function readPresenceRefs(root: string): Array<{
+/** Read every locally-known ref under `prefix` → [{machine, message}]. */
+export declare function readMachineRefs(root: string, prefix?: HarneryRefPrefix): Array<{
     machine: string;
     message: string;
 }>;
@@ -61,8 +66,9 @@ export declare function readPresenceRefs(root: string): Array<{
  * Records are %01-terminated (contents may contain newlines); refname and
  * contents are %00-separated. Exported for unit tests.
  */
-export declare function parseForEachRefOutput(out: string): Array<{
+export declare function parseForEachRefOutput(out: string, prefix?: HarneryRefPrefix): Array<{
     machine: string;
     message: string;
 }>;
+export {};
 //# sourceMappingURL=git.d.ts.map

package/dist/core/presence/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../../src/core/presence/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;wEACwE;AACxE,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAwC5D,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASzD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOhF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAcjC;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAcjC;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ1F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAe9F"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../../src/core/presence/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;8EAE8E;AAC9E,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAC5D,eAAO,MAAM,eAAe,uBAAuB,CAAC;AACpD,KAAK,gBAAgB,GAAG,OAAO,mBAAmB,GAAG,OAAO,eAAe,CAAC;AAwC5E,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASzD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOhF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAGjC;AAED;6EAC6E;AAC7E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAGjC;AAwBD,0EAA0E;AAC1E,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,gBAAsC,GAC7C,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAI7C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,gBAAsC,GAC7C,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAe7C"}

package/dist/core/presence/git.js

@@ -1,5 +1,6 @@
 /**
- * Git plumbing for the cross-machine presence transport (ADR 0016).
+ * Git plumbing for the cross-machine presence transport (ADR 0016) and the
+ * mail refs that ride on it (ADR 0222).
  *
  * Presence blobs travel as parentless commits (empty tree, JSON message)
  * force-pushed to `refs/harnery/presence/<machine>` on the host repo's own
@@ -13,9 +14,11 @@
  * user wants to see errors).
  */
 import { spawn, spawnSync } from "node:child_process";
-/** The ref namespace. Hardcoded — never interpolated from config — so the
- * publisher is structurally unable to touch refs/heads/* (ADR 0016). */
+/** The ref namespaces. Hardcoded — never interpolated from config — so the
+ * publisher is structurally unable to touch refs/heads/* (ADR 0016). Mail
+ * refs carry cross-machine peer messages on the same transport (ADR 0222). */
 export const PRESENCE_REF_PREFIX = "refs/harnery/presence/";
+export const MAIL_REF_PREFIX = "refs/harnery/mail/";
 /** Well-known SHA of git's empty tree; `git mktree` below guarantees the
  * object exists in the local odb before we build a commit on it. */
 const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
@@ -99,36 +102,31 @@ export function writePresenceCommit(root, message) {
     return r.ok && r.stdout.trim() ? r.stdout.trim() : null;
 }
 /**
- * Force-push a presence commit to `refs/harnery/presence/<machine>`.
- * `sync: true` (CLI/tests) waits and reports; default is detached fire-and-
- * forget (hook path — a slow or credential-less push must not block a turn).
+ * Force-push a commit to `<prefix><machine>` (presence or mail). `sync: true`
+ * (CLI/tests) waits and reports; default is detached fire-and-forget (hook
+ * path — a slow or credential-less push must not block a turn).
  */
-export function pushPresenceRef(root, machine, sha, opts = {}) {
-    const refspec = `+${sha}:${PRESENCE_REF_PREFIX}${sanitizeRefComponent(machine)}`;
-    const args = ["-C", root, "push", "--quiet", "--no-verify", "origin", refspec];
-    if (opts.sync) {
-        const r = runGit(root, args.slice(2));
-        return r.ok ? { ok: true } : { ok: false, error: r.stderr.trim().slice(0, 300) };
-    }
-    try {
-        const child = spawn("git", args, { detached: true, stdio: "ignore", env: gitEnv() });
-        child.unref();
-        return { ok: true };
-    }
-    catch {
-        return { ok: false, error: "spawn failed" };
-    }
+export function pushMachineRef(root, prefix, machine, sha, opts = {}) {
+    const refspec = `+${sha}:${prefix}${sanitizeRefComponent(machine)}`;
+    return runNetworkGit(root, ["push", "--quiet", "--no-verify", "origin", refspec], opts);
 }
-/** Fetch every peer presence ref from origin into the local ref namespace. */
-export function fetchPresenceRefs(root, opts = {}) {
-    const refspec = `+${PRESENCE_REF_PREFIX}*:${PRESENCE_REF_PREFIX}*`;
-    const args = ["-C", root, "fetch", "--quiet", "--no-tags", "origin", refspec];
+/** Fetch every peer presence and mail ref from origin into the local ref
+ * namespace, in one round trip. A namespace with no refs is not an error. */
+export function fetchMachineRefs(root, opts = {}) {
+    const refspecs = [PRESENCE_REF_PREFIX, MAIL_REF_PREFIX].map((p) => `+${p}*:${p}*`);
+    return runNetworkGit(root, ["fetch", "--quiet", "--no-tags", "origin", ...refspecs], opts);
+}
+function runNetworkGit(root, args, opts) {
     if (opts.sync) {
-        const r = runGit(root, args.slice(2));
+        const r = runGit(root, args);
         return r.ok ? { ok: true } : { ok: false, error: r.stderr.trim().slice(0, 300) };
     }
     try {
-        const child = spawn("git", args, { detached: true, stdio: "ignore", env: gitEnv() });
+        const child = spawn("git", ["-C", root, ...args], {
+            detached: true,
+            stdio: "ignore",
+            env: gitEnv(),
+        });
         child.unref();
         return { ok: true };
     }
@@ -136,23 +134,19 @@ export function fetchPresenceRefs(root, opts = {}) {
         return { ok: false, error: "spawn failed" };
     }
 }
-/** Read every locally-known presence ref → [{ref, machine, message}]. */
-export function readPresenceRefs(root) {
-    const r = runGit(root, [
-        "for-each-ref",
-        "--format=%(refname)%00%(contents)%01",
-        `${PRESENCE_REF_PREFIX}*`,
-    ]);
+/** Read every locally-known ref under `prefix` → [{machine, message}]. */
+export function readMachineRefs(root, prefix = PRESENCE_REF_PREFIX) {
+    const r = runGit(root, ["for-each-ref", "--format=%(refname)%00%(contents)%01", `${prefix}*`]);
     if (!r.ok)
         return [];
-    return parseForEachRefOutput(r.stdout);
+    return parseForEachRefOutput(r.stdout, prefix);
 }
 /**
  * Parse `for-each-ref --format='%(refname)%00%(contents)%01'` output.
  * Records are %01-terminated (contents may contain newlines); refname and
  * contents are %00-separated. Exported for unit tests.
  */
-export function parseForEachRefOutput(out) {
+export function parseForEachRefOutput(out, prefix = PRESENCE_REF_PREFIX) {
     const rows = [];
     for (const rec of out.split("\u0001")) {
         const trimmed = rec.replace(/^\n+/, "");
@@ -162,10 +156,10 @@ export function parseForEachRefOutput(out) {
         if (sep === -1)
             continue;
         const refname = trimmed.slice(0, sep).trim();
-        if (!refname.startsWith(PRESENCE_REF_PREFIX))
+        if (!refname.startsWith(prefix))
             continue;
         rows.push({
-            machine: refname.slice(PRESENCE_REF_PREFIX.length),
+            machine: refname.slice(prefix.length),
             message: trimmed.slice(sep + 1).trim(),
         });
     }

package/dist/core/presence/index.d.ts

@@ -17,7 +17,7 @@
 import { type PresenceAgent } from "./blob.js";
 export type { PresenceAgent, PresenceBlob } from "./blob.js";
 export { buildPresenceBlob } from "./blob.js";
-export { PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent } from "./git.js";
+export { MAIL_REF_PREFIX, PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent, } from "./git.js";
 export { ensureRelayDaemon, relayDaemonStatus, runRelayDaemon } from "./relay-client.js";
 export type PublishResult = {
     status: "published";
@@ -49,7 +49,7 @@ export declare function publishPresence(coordRoot: string, opts?: {
     force?: boolean;
     sync?: boolean;
 }): PublishResult;
-/** Throttled fetch of peer presence refs from origin. */
+/** Throttled fetch of peer presence and mail refs from origin. */
 export declare function fetchPresence(coordRoot: string, opts?: {
     force?: boolean;
     sync?: boolean;

package/dist/core/presence/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/presence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgBH,OAAO,EAAqB,KAAK,aAAa,EAAqB,MAAM,WAAW,CAAC;AAUrF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAYzF,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAwCvC;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7C,aAAa,CA2Cf;AAED,yDAAyD;AACzD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7C,WAAW,CAsCb;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D,aAAa,EAAE,CAuDjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/presence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgBH,OAAO,EAAqB,KAAK,aAAa,EAAqB,MAAM,WAAW,CAAC;AAWrF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAYzF,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAwCvC;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7C,aAAa,CA6Cf;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7C,WAAW,CAsCb;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D,aAAa,EAAE,CAuDjB"}

package/dist/core/presence/index.js

@@ -20,9 +20,9 @@ import { coordEnv } from "../../lib/env.js";
 import { resolveMachineLabel } from "../../lib/machine.js";
 import { presenceEnabled } from "../config.js";
 import { buildPresenceBlob } from "./blob.js";
-import { fetchPresenceRefs, hasOrigin, pushPresenceRef, readPresenceRefs, sanitizeRefComponent, writePresenceCommit, } from "./git.js";
+import { fetchMachineRefs, hasOrigin, PRESENCE_REF_PREFIX, pushMachineRef, readMachineRefs, sanitizeRefComponent, writePresenceCommit, } from "./git.js";
 export { buildPresenceBlob } from "./blob.js";
-export { PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent } from "./git.js";
+export { MAIL_REF_PREFIX, PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent, } from "./git.js";
 export { ensureRelayDaemon, relayDaemonStatus, runRelayDaemon } from "./relay-client.js";
 /** Re-push at least this often while sessions are live, so peers can treat a
  * blob older than ~3x this as "machine offline" rather than "no change". */
@@ -95,7 +95,9 @@ export function publishPresence(coordRoot, opts = {}) {
         const sha = writePresenceCommit(coordRoot, json);
         if (!sha)
             return { status: "error", error: "commit-tree failed" };
-        const push = pushPresenceRef(coordRoot, blob.machine, sha, { sync: opts.sync });
+        const push = pushMachineRef(coordRoot, PRESENCE_REF_PREFIX, blob.machine, sha, {
+            sync: opts.sync,
+        });
         if (!push.ok)
             return { status: "error", error: push.error ?? "push failed" };
         // Optimistic on the detached path: a failed background push self-heals at
@@ -111,7 +113,7 @@ export function publishPresence(coordRoot, opts = {}) {
         return { status: "error", error: e instanceof Error ? e.message : String(e) };
     }
 }
-/** Throttled fetch of peer presence refs from origin. */
+/** Throttled fetch of peer presence and mail refs from origin. */
 export function fetchPresence(coordRoot, opts = {}) {
     try {
         if (!presenceEnabled(coordRoot))
@@ -144,7 +146,7 @@ export function fetchPresence(coordRoot, opts = {}) {
         catch {
             /* best-effort */
         }
-        const r = fetchPresenceRefs(coordRoot, { sync: opts.sync });
+        const r = fetchMachineRefs(coordRoot, { sync: opts.sync });
         if (!r.ok)
             return { status: "error", error: r.error ?? "fetch failed" };
         return { status: "fetched" };
@@ -178,7 +180,7 @@ export function readRemoteMachines(coordRoot, opts = {}) {
                 return;
             byMachine.set(machine, blob);
         };
-        for (const { machine, message } of readPresenceRefs(coordRoot)) {
+        for (const { machine, message } of readMachineRefs(coordRoot, PRESENCE_REF_PREFIX)) {
             try {
                 consider(machine, JSON.parse(message));
             }