harnery 0.45.2 → 0.46.0

package/dist/core/hooks/shell-commit-tree.js

@@ -0,0 +1,104 @@
+import { basename, shellCommandFromTool, tokenize } from "./shell-tokens.js";
+/**
+ * Deny `git commit-tree` in an agent's shell command. In a checkout shared by
+ * several agents, a peer's commit can hold the Git index lock for minutes
+ * while its pre-commit checks run. An agent that builds its own commit from a
+ * separate index with `git commit-tree` and pushes it gets around that lock,
+ * and with it every pre-commit check and the commit-time claim guard. The
+ * right move is to wait for the peer's commit to finish.
+ *
+ * A guardrail against the reflex, not a security boundary: it reads command
+ * positions only (so quoted examples and other tools pass), skips Git's
+ * global options, and looks inside `bash -c '...'`.
+ * HARNERY_ALLOW_COMMIT_TREE=1 on the command is the deliberate override.
+ */
+const OVERRIDE = "HARNERY_ALLOW_COMMIT_TREE=1";
+const SEPARATORS = new Set([";", "|", "||", "&", "&&", "(", ")", "{", "}"]);
+const KEYWORDS = new Set(["do", "if", "then", "elif", "else", "!", "while", "until", "time"]);
+const WRAPPERS = new Set(["command", "exec", "builtin", "nohup", "sudo", "doas", "env", "nice"]);
+// Git global options that consume the following token as their value.
+const GIT_VALUE_OPTIONS = new Set([
+    "-C",
+    "-c",
+    "--git-dir",
+    "--work-tree",
+    "--namespace",
+    "--exec-path",
+]);
+function gitSubcommand(args) {
+    for (let j = 0; j < args.length; j++) {
+        const arg = args[j];
+        if (arg.operator)
+            return null;
+        if (arg.value.startsWith("-")) {
+            if (GIT_VALUE_OPTIONS.has(arg.value))
+                j++;
+            continue;
+        }
+        return arg.value;
+    }
+    return null;
+}
+function invokesCommitTree(source, depth = 0) {
+    if (depth > 8)
+        return false;
+    const tokens = tokenize(source);
+    if (tokens.some((t) => !t.quoted && t.value === OVERRIDE))
+        return false;
+    let start = true;
+    let afterWrapper = false;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.operator) {
+            if (SEPARATORS.has(token.value)) {
+                start = true;
+                afterWrapper = false;
+            }
+            continue;
+        }
+        if (!start)
+            continue;
+        if (!token.quoted) {
+            if (KEYWORDS.has(token.value))
+                continue;
+            if (/^[A-Za-z_][A-Za-z_0-9]*=/.test(token.value))
+                continue;
+            if (afterWrapper && token.value.startsWith("-"))
+                continue;
+        }
+        const name = basename(token.value);
+        if (WRAPPERS.has(name)) {
+            afterWrapper = true;
+            continue;
+        }
+        start = false;
+        afterWrapper = false;
+        if (token.quoted)
+            continue;
+        if (name === "git" && gitSubcommand(tokens.slice(i + 1)) === "commit-tree")
+            return true;
+        if (name === "git-commit-tree")
+            return true;
+        if (["bash", "sh", "dash", "zsh", "ksh"].includes(name)) {
+            for (let j = i + 1; j < tokens.length && !tokens[j].operator; j++) {
+                if (/^-[a-z]*c[a-z]*$/.test(tokens[j].value)) {
+                    const script = tokens[j + 1];
+                    if (script && !script.operator && invokesCommitTree(script.value, depth + 1))
+                        return true;
+                    break;
+                }
+            }
+        }
+    }
+    return false;
+}
+export function shellCommitTreeReason(toolName, toolInput, binName) {
+    const command = shellCommandFromTool(toolName, toolInput);
+    if (command === null || !invokesCommitTree(command))
+        return null;
+    return (`git commit-tree blocked: building a commit by hand gets around the Git index lock, and with ` +
+        `it every pre-commit check and the claim guard. When a peer's commit holds the lock, wait ` +
+        `for it to finish (\`${binName} admission status\` shows whether its checks are queued for a ` +
+        `slot), then commit normally. If you genuinely need plumbing, prefix the command with ` +
+        `${OVERRIDE}.`);
+}

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

@@ -20,6 +20,8 @@ export interface HarneryInboxMessageRecordV1 {
     /** A required null identifies an operator; strings identify real agent instances. */
     sender_instance_id: string | null;
     sender_display_name: string;
+    /** Set only on a message imported from another machine (ADR 0222). */
+    sender_machine?: string;
     recipient_instance_id: string;
     recipient_display_name: string;
     created_at: string;
@@ -51,6 +53,16 @@ export declare class HarneryInboxCapacityError extends Error {
     readonly limit: number;
     constructor(reason_code: HarneryInboxCapacityReason, current: number, limit: number);
 }
+export declare class HarneryInboxMessageConflictError extends Error {
+    readonly message_id: string;
+    readonly reason_code = "message_identity_conflict";
+    constructor(message_id: string);
+}
+export declare class HarneryInboxMessageHistoryMissingError extends Error {
+    readonly message_id: string;
+    readonly reason_code = "message_history_unknown";
+    constructor(message_id: string);
+}
 export interface HarneryInboxSurfaceBudget {
     max_count: number;
     max_bytes: number;

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

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/contract.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,EAAG,yBAAkC,CAAC;AAC9E,eAAO,MAAM,2BAA2B,EAAG,yBAAkC,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,OAAO,2BAA2B,CAAC;IAC3C,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,OAAO,2BAA2B,CAAC;IAC3C,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAAG,2BAA2B,GAAG,4BAA4B,CAAC;AAE9F,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,2BAA2B,CAAC;IAC3C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IAC7C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,0BAA0B,GAClC,oBAAoB,GACpB,qBAAqB,GACrB,qBAAqB,GACrB,qBAAqB,CAAC;AAE1B,qBAAa,yBAA0B,SAAQ,KAAK;IAEhD,QAAQ,CAAC,WAAW,EAAE,0BAA0B;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAFb,WAAW,EAAE,0BAA0B,EACvC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM;CAMzB;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAChD,uBAAuB,EAAE,MAAM,CAAC;IAChC,uBAAuB,EAAE,MAAM,CAAC;IAChC,6BAA6B,EAAE,IAAI,CAAC;CACrC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/contract.ts"],"names":[],"mappings":"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"}

package/dist/core/inbox/contract.js

@@ -11,3 +11,19 @@ export class HarneryInboxCapacityError extends Error {
         this.limit = limit;
     }
 }
+export class HarneryInboxMessageConflictError extends Error {
+    message_id;
+    reason_code = "message_identity_conflict";
+    constructor(message_id) {
+        super(`inbox message identity conflict: ${message_id}`);
+        this.message_id = message_id;
+    }
+}
+export class HarneryInboxMessageHistoryMissingError extends Error {
+    message_id;
+    reason_code = "message_history_unknown";
+    constructor(message_id) {
+        super(`inbox message history unknown: ${message_id}`);
+        this.message_id = message_id;
+    }
+}

package/dist/core/inbox/peer-messages.d.ts

@@ -1,37 +1,62 @@
-import type { HarneryInboxLimits, HarneryInboxMessageRecordV1 } from "./contract.js";
+import { type AgentParentReference } from "../agents/state/parent-reference.js";
+import { type HarneryInboxLimits, type HarneryInboxMessageRecordV1 } from "./contract.js";
 import { HarneryInboxService } from "./service.js";
-import { type MessageTargetInput } from "./targets.js";
+import { type MessageTargetInput, type MessageTargetResult } from "./targets.js";
 /** Preserve the existing ping body/count bounds. Pending messages have no TTL;
  * the lifecycle planner protects them through the idle finalization window. */
 export declare const PEER_INBOX_LIMITS: HarneryInboxLimits;
 export declare function peerInbox(coordRoot: string): HarneryInboxService;
 /** CLI and web use this one path. A receipt proves a synced append, never that
  * a process is awake or that the recipient has noticed the message. */
-export declare function sendPeerMessage(input: {
+export interface PeerMessageInput {
     coordRoot: string;
     target: MessageTargetInput;
     senderInstanceId: string | null;
     senderName: string;
     body: string;
-}): {
-    ok: false;
-    code: "no_peer" | "ambiguous_peer" | "not_live" | "authority_unsafe";
-    message: string;
-    candidates?: string[];
-} | {
-    state: "queued" | "written-live";
+    /** Reuse the same caller-owned ID after a crash, with identical intent. */
+    operationId?: string;
+    /** A caller with an ambiguous prior dispatch must not create a new plan. */
+    operationReplayOnly?: boolean;
+}
+type PeerTarget = Extract<MessageTargetResult, {
+    ok: true;
+}>["target"];
+export type PeerRecipientResult = {
+    ok: true;
+    target: PeerTarget;
+    state: "written-live" | "queued" | "remote" | "duplicate";
     message_id: string;
     body_bytes: number;
     synced: true;
-    ok: true;
-    target: {
-        instance_id: string;
-        name: string;
-        delivery: "written-live" | "queued";
-    };
+    published?: boolean;
+    publish_error?: string;
+    delivery_state?: "pending" | "delivered" | "expired";
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    target?: PeerTarget;
+    candidates?: string[];
+    failure_stage?: "addressing" | "transport" | "operation";
+};
+type ParentCopyResult = PeerRecipientResult | {
+    state: "skipped";
+    reason: string;
+};
+export type PeerMessageResult = PeerRecipientResult & {
+    operation_id: string;
+    child: PeerRecipientResult;
+    parent_reference: AgentParentReference;
+    parent_copy: ParentCopyResult;
+    complete: boolean;
 };
+/** One frozen routing intent, child first, then at most its direct parent.
+ * Receipts establish durable writes, never attention or a process wake. */
+export declare function sendPeerMessage(input: PeerMessageInput): PeerMessageResult;
 export declare function formatPeerInbox(coordRoot: string, messages: readonly HarneryInboxMessageRecordV1[]): string;
 /** Wait for every earlier stdout write to finish before acknowledging context.
  * If output fails, the caller throws and leaves the batch pending. */
 export declare function acknowledgeEmittedPeerInbox(coordRoot: string, instanceId: string, messageIds: readonly string[]): Promise<void>;
+export {};
 //# sourceMappingURL=peer-messages.d.ts.map

package/dist/core/inbox/peer-messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"peer-messages.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/peer-messages.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,kBAAkB,EAAwB,MAAM,cAAc,CAAC;AAI7E;+EAC+E;AAC/E,eAAO,MAAM,iBAAiB,EAAE,kBAY/B,CAAC;AAEF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAEhE;AAED;uEACuE;AACvE,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;;;;;;;;;;;;;;;;EAWA;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,2BAA2B,EAAE,GAC/C,MAAM,CA4BR;AAED;sEACsE;AACtE,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"peer-messages.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/peer-messages.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,qCAAqC,CAAC;AAM7C,OAAO,EAEL,KAAK,kBAAkB,EAGvB,KAAK,2BAA2B,EACjC,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAwB,MAAM,cAAc,CAAC;AACzE,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EAGzB,MAAM,cAAc,CAAC;AAItB;+EAC+E;AAC/E,eAAO,MAAM,iBAAiB,EAAE,kBAY/B,CAAC;AAEF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAEhE;AAED;uEACuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,KAAK,UAAU,GAAG,OAAO,CAAC,mBAAmB,EAAE;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;AACvE,MAAM,MAAM,mBAAmB,GAC3B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;CACtD,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,YAAY,GAAG,WAAW,GAAG,WAAW,CAAC;CAC1D,CAAC;AACN,KAAK,gBAAgB,GAAG,mBAAmB,GAAG;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AACnF,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,GAAG;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,gBAAgB,EAAE,oBAAoB,CAAC;IACvC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAuBF;2EAC2E;AAC3E,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CA8P1E;AAoKD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,2BAA2B,EAAE,GAC/C,MAAM,CA6BR;AAED;sEACsE;AACtE,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/core/inbox/peer-messages.js

@@ -1,6 +1,14 @@
+import { createHash, randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { resolveAgentParentReference, } from "../agents/state/parent-reference.js";
 import { resolveBinName } from "../config.js";
-import { HarneryInboxService } from "./service.js";
-import { resolveMessageTarget } from "./targets.js";
+import { readCoordinationViewV3 } from "../events/v3/coordination-view.js";
+import { liveInstanceIdV3 } from "../events/v3/live-route-observer.js";
+import { publishMail, queueMail } from "../presence/mail.js";
+import { updateCrashSafeJsonlFile } from "../storage/durable-history.js";
+import { HarneryInboxCapacityError, HarneryInboxMessageConflictError, HarneryInboxMessageHistoryMissingError, } from "./contract.js";
+import { HarneryInboxService, stableInboxMessageId } from "./service.js";
+import { resolveMessageTarget, resolveRemoteMessageTarget, } from "./targets.js";
 const DAY = 24 * 60 * 60_000;
 /** Preserve the existing ping body/count bounds. Pending messages have no TTL;
  * the lifecycle planner protects them through the idle finalization window. */
@@ -20,20 +28,368 @@ export const PEER_INBOX_LIMITS = {
 export function peerInbox(coordRoot) {
     return new HarneryInboxService({ coord_root: coordRoot, limits: PEER_INBOX_LIMITS });
 }
-/** CLI and web use this one path. A receipt proves a synced append, never that
- * a process is awake or that the recipient has noticed the message. */
+const OPERATION_LIMITS = { max_record_bytes: 24_000, max_records: 5 };
+/** One frozen routing intent, child first, then at most its direct parent.
+ * Receipts establish durable writes, never attention or a process wake. */
 export function sendPeerMessage(input) {
-    const target = resolveMessageTarget(input.coordRoot, input.target);
-    if (!target.ok)
-        return target;
-    const receipt = peerInbox(input.coordRoot).send({
-        sender_instance_id: input.senderInstanceId,
-        sender_display_name: input.senderName,
-        recipient_instance_id: target.target.instance_id,
-        recipient_display_name: target.target.name,
-        body: input.body.trim(),
+    const operationId = input.operationId ?? randomUUID();
+    const unknown = { state: "unknown", reason: "original_target_unresolved" };
+    const refused = (code, message) => {
+        const child = { ok: false, code, message };
+        return {
+            ...child,
+            child,
+            operation_id: operationId,
+            parent_reference: unknown,
+            parent_copy: { state: "skipped", reason: "original_target_unresolved" },
+            complete: false,
+        };
+    };
+    if (!/^[A-Za-z0-9._:-]{1,160}$/.test(operationId))
+        return refused("invalid_operation_id", "Supply a bounded opaque operation ID.");
+    if (input.operationReplayOnly && !input.operationId)
+        return refused("invalid_operation_id", "Replay-only requires the original operation ID.");
+    if (!input.body.trim())
+        return refused("empty_message", "message is required (and non-empty)");
+    const request = hash(JSON.stringify({
+        target: {
+            name: input.target.name ?? null,
+            instance: input.target.instanceId ?? null,
+            generation: input.target.generationId ?? null,
+            require_live: input.target.requireLive ?? false,
+        },
+        sender: input.senderInstanceId,
+        sender_name: input.senderName,
+        body: input.body,
+    }));
+    const path = join(input.coordRoot, ".harnery", "peer-operations", `${hash(operationId)}.jsonl`);
+    let plan;
+    try {
+        const prepared = updateCrashSafeJsonlFile(path, OPERATION_LIMITS, (records) => {
+            if (records.length) {
+                validateOperationRecords(records, operationId);
+                const existing = records[0];
+                if (existing?.kind !== "plan" || existing.schema !== "harnery.peer-routing/v1")
+                    throw new Error("routing operation has no valid frozen plan");
+                if (existing.request_sha256 !== request)
+                    return {
+                        result: {
+                            ok: false,
+                            code: "operation_conflict",
+                            message: "Operation ID already binds different sender, body or target intent.",
+                        },
+                    };
+                return { result: existing };
+            }
+            if (input.operationReplayOnly)
+                return {
+                    result: {
+                        ok: false,
+                        code: "message_history_unknown",
+                        message: "The original routing plan is unavailable; no recipient was resubmitted.",
+                    },
+                };
+            const view = readCoordinationViewV3(input.coordRoot);
+            let target = resolveMessageTarget(input.coordRoot, input.target, { view });
+            if (!target.ok && target.code === "no_peer") {
+                target = resolveRemoteMessageTarget(input.coordRoot, input.target) ?? target;
+            }
+            if (!target.ok)
+                return { result: target };
+            const generation = selectedGeneration(view, target.target.instance_id);
+            const reference = target.target.machine
+                ? { state: "unknown", reason: "remote_parent_evidence_unavailable" }
+                : resolveAgentParentReference(input.coordRoot, { instance_id: target.target.instance_id, generation_id: generation?.generation_id }, { view });
+            const child = {
+                target: target.target,
+                generation_id: generation?.generation_id,
+                body: input.body,
+            };
+            let parent = {
+                state: "skipped",
+                reason: reference.state === "verified" ? "parent_not_addressable" : reference.reason,
+            };
+            if (reference.state === "verified" && reference.addressable) {
+                const parentTarget = resolveMessageTarget(input.coordRoot, {
+                    instanceId: reference.parent_v3_instance_id,
+                    generationId: reference.parent_generation_id ?? undefined,
+                    requireLive: input.target.requireLive,
+                    now: input.target.now,
+                }, { view });
+                const body = `[Parent copy for agent-${target.target.name} (${target.target.instance_id})]\n${input.body}`;
+                parent = !parentTarget.ok
+                    ? parentTarget
+                    : Buffer.byteLength(body) > PEER_INBOX_LIMITS.max_message_body_bytes
+                        ? {
+                            ok: false,
+                            code: "parent_copy_overflow",
+                            message: "The parent marker and unchanged message exceed the 4000-byte message limit.",
+                            target: parentTarget.target,
+                        }
+                        : {
+                            target: parentTarget.target,
+                            generation_id: reference.parent_generation_id ?? undefined,
+                            body,
+                        };
+            }
+            const created = {
+                kind: "plan",
+                schema: "harnery.peer-routing/v1",
+                request_sha256: request,
+                sender_instance_id: input.senderInstanceId,
+                sender_name: input.senderName,
+                require_live: input.target.requireLive ?? false,
+                child,
+                parent_reference: reference,
+                parent,
+            };
+            return { append: [created], result: created };
+        });
+        if (!("kind" in prepared))
+            return {
+                ...prepared,
+                child: prepared,
+                operation_id: operationId,
+                parent_reference: unknown,
+                parent_copy: { state: "skipped", reason: "original_target_unresolved" },
+                complete: false,
+            };
+        plan = prepared;
+    }
+    catch (error) {
+        return refused("operation_unavailable", error instanceof Error ? error.message : "Routing plan unavailable.");
+    }
+    const resolvePlanned = (recipient) => recipient.target.machine
+        ? resolveRemoteMessageTarget(input.coordRoot, {
+            instanceId: recipient.target.instance_id,
+            requireLive: plan.require_live,
+            now: input.target.now,
+        })
+        : resolveMessageTarget(input.coordRoot, {
+            instanceId: recipient.target.instance_id,
+            generationId: recipient.generation_id,
+            requireLive: plan.require_live,
+            now: input.target.now,
+        });
+    const deliver = (role, recipient, childOutcome) => {
+        try {
+            // Persist intent before transport. An interrupted prior attempt is only
+            // reconcilable from retained transport history, never from its absence.
+            const started = updateCrashSafeJsonlFile(path, OPERATION_LIMITS, (records) => {
+                validateOperationRecords(records, operationId);
+                const prior = records.find((r) => r.kind === "result" && r.recipient === role);
+                if (prior?.kind === "result")
+                    return { result: prior.result };
+                // Historical receipts win; a new parent append requires the original
+                // child identity to remain safely addressable now.
+                if (role === "parent") {
+                    const currentChild = resolvePlanned(plan.child);
+                    if ((childOutcome && !childOutcome.ok && childOutcome.failure_stage !== "transport") ||
+                        !currentChild?.ok ||
+                        currentChild.target.machine !== plan.child.target.machine) {
+                        return {
+                            result: {
+                                ok: false,
+                                target: recipient.target,
+                                failure_stage: "addressing",
+                                code: "parent_copy_suppressed",
+                                message: "Parent copy suppressed because the original task lost safe addressing.",
+                            },
+                        };
+                    }
+                }
+                if (records.some((r) => r.kind === "started" && r.recipient === role))
+                    return { result: { replay: true } };
+                return { append: [{ kind: "started", recipient: role }], result: { replay: false } };
+            });
+            if ("ok" in started)
+                return started;
+            return updateCrashSafeJsonlFile(path, OPERATION_LIMITS, (records) => {
+                validateOperationRecords(records, operationId);
+                const frozen = records[0];
+                if (frozen?.kind !== "plan" || frozen.request_sha256 !== request)
+                    throw new Error("routing operation plan changed");
+                const prior = records.find((r) => r.kind === "result" && r.recipient === role);
+                if (prior?.kind === "result")
+                    return { result: prior.result };
+                const current = resolvePlanned(recipient);
+                let result;
+                if (!current?.ok || current.target.machine !== recipient.target.machine) {
+                    result =
+                        current && !current.ok
+                            ? { ...current, target: recipient.target, failure_stage: "addressing" }
+                            : {
+                                ok: false,
+                                target: recipient.target,
+                                code: "recipient_changed",
+                                failure_stage: "addressing",
+                                message: "The frozen recipient is no longer safely addressable on the same machine.",
+                            };
+                }
+                else {
+                    try {
+                        result = deliverPeerRecipient(input.coordRoot, plan, recipient, operationId, current.target.delivery, started.replay);
+                    }
+                    catch (error) {
+                        result = recipientError(error, recipient.target);
+                    }
+                }
+                // A concurrent first attempt may still finish. Retain the start and
+                // report uncertainty, without turning absence into a permanent result.
+                if (!result.ok && result.code === "message_history_unknown")
+                    return { result };
+                return { append: [{ kind: "result", recipient: role, result }], result };
+            });
+        }
+        catch (error) {
+            return recipientError(error, recipient.target, "operation");
+        }
+    };
+    const child = deliver("child", plan.child);
+    const parent = "body" in plan.parent ? deliver("parent", plan.parent, child) : plan.parent;
+    return {
+        ...child,
+        child,
+        operation_id: operationId,
+        parent_reference: plan.parent_reference,
+        parent_copy: parent,
+        complete: child.ok && (!("ok" in parent) || parent.ok),
+    };
+}
+function selectedGeneration(view, instance) {
+    const id = liveInstanceIdV3(instance);
+    return (view.instances[id] ??
+        Object.values(view.terminal_generations)
+            .filter((row) => row.instance_id === id)
+            .sort((a, b) => b.source_position.segment_ordinal - a.source_position.segment_ordinal ||
+            b.source_position.byte_offset - a.source_position.byte_offset)[0]);
+}
+function hash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function validateOperationRecords(records, operationId) {
+    const plan = records[0];
+    if (plan?.kind !== "plan" ||
+        plan.schema !== "harnery.peer-routing/v1" ||
+        typeof plan.request_sha256 !== "string" ||
+        typeof plan.sender_name !== "string" ||
+        (plan.sender_instance_id !== null && typeof plan.sender_instance_id !== "string") ||
+        typeof plan.require_live !== "boolean")
+        throw new Error("Invalid routing operation plan.");
+    const validRecipient = (r) => typeof r.body === "string" &&
+        r.target &&
+        typeof r.target.instance_id === "string" &&
+        typeof r.target.name === "string" &&
+        (r.generation_id === undefined || typeof r.generation_id === "string");
+    const validParent = "body" in plan.parent
+        ? validRecipient(plan.parent)
+        : "ok" in plan.parent
+            ? plan.parent.ok === false &&
+                typeof plan.parent.code === "string" &&
+                typeof plan.parent.message === "string"
+            : plan.parent.state === "skipped" && typeof plan.parent.reason === "string";
+    if (!validRecipient(plan.child) || !validParent)
+        throw new Error("Invalid frozen recipient plan.");
+    const started = new Set();
+    const completed = new Set();
+    for (const row of records.slice(1)) {
+        if (row.kind === "plan" || !["child", "parent"].includes(row.recipient))
+            throw new Error("Invalid routing operation record.");
+        if (row.kind === "started") {
+            if (started.has(row.recipient))
+                throw new Error("Duplicate recipient start.");
+            started.add(row.recipient);
+            continue;
+        }
+        if (row.kind !== "result" || !started.has(row.recipient) || completed.has(row.recipient))
+            throw new Error("Invalid recipient result sequence.");
+        completed.add(row.recipient);
+        const recipient = row.recipient === "child" ? plan.child : plan.parent;
+        const result = row.result;
+        if (!("body" in recipient) || !result || typeof result.ok !== "boolean")
+            throw new Error("Invalid recipient result.");
+        if (result.ok) {
+            if (result.target?.instance_id !== recipient.target.instance_id ||
+                result.message_id !== stableInboxMessageId(operationId, recipient.target.instance_id) ||
+                result.body_bytes !== Buffer.byteLength(recipient.body) ||
+                result.synced !== true ||
+                !["written-live", "queued", "remote", "duplicate"].includes(result.state))
+                throw new Error("Recipient receipt does not match frozen intent.");
+        }
+        else if (typeof result.code !== "string" || typeof result.message !== "string") {
+            throw new Error("Invalid recipient failure.");
+        }
+    }
+}
+function recipientError(error, target, failureStage = "transport") {
+    return {
+        ok: false,
+        target,
+        failure_stage: failureStage,
+        code: error instanceof HarneryInboxCapacityError
+            ? `inbox_${error.reason_code}`
+            : error instanceof HarneryInboxMessageHistoryMissingError ||
+                error instanceof HarneryInboxMessageConflictError
+                ? error.reason_code
+                : "recipient_delivery_failed",
+        message: error instanceof Error ? error.message : "Recipient delivery failed.",
+    };
+}
+function deliverPeerRecipient(coordRoot, plan, recipient, operationId, delivery, replayOnly) {
+    const target = recipient.target;
+    const messageId = stableInboxMessageId(operationId, target.instance_id);
+    if (target.machine) {
+        // Cross-machine (ADR 0222): queue in this machine's mail ref and push it
+        // now. A failed push keeps the message queued for the next hook publish.
+        const queued = queueMail(coordRoot, {
+            messageId,
+            replayOnly,
+            toMachine: target.machine,
+            senderInstanceId: plan.sender_instance_id,
+            senderName: plan.sender_name,
+            recipientInstanceId: target.instance_id,
+            recipientName: target.name,
+            body: recipient.body,
+            maxBodyBytes: PEER_INBOX_LIMITS.max_message_body_bytes,
+        });
+        const envelope = queued.envelope;
+        if (queued.delivery_state === "expired")
+            return {
+                ok: false,
+                target,
+                code: "remote_message_expired",
+                message: "The original remote message expired; it was not republished.",
+            };
+        const published = queued.delivery_state === "delivered"
+            ? null
+            : publishMail(coordRoot, { sync: true, force: true });
+        return {
+            ok: true,
+            target,
+            state: queued.state === "duplicate" ? "duplicate" : "remote",
+            message_id: envelope.message_id,
+            body_bytes: envelope.body_bytes,
+            synced: true,
+            delivery_state: queued.delivery_state,
+            published: published?.status === "published",
+            ...(published?.status === "error" ? { publish_error: published.error } : {}),
+        };
+    }
+    const receipt = peerInbox(coordRoot).send({
+        message_id: messageId,
+        replay_only: replayOnly,
+        sender_instance_id: plan.sender_instance_id,
+        sender_display_name: plan.sender_name,
+        recipient_instance_id: target.instance_id,
+        recipient_display_name: target.name,
+        body: recipient.body,
     });
-    return { ok: true, target: target.target, ...receipt, state: target.target.delivery };
+    return {
+        ok: true,
+        target,
+        ...receipt,
+        state: receipt.state === "duplicate" ? "duplicate" : delivery,
+    };
 }
 export function formatPeerInbox(coordRoot, messages) {
     if (messages.length === 0)
@@ -47,7 +403,8 @@ export function formatPeerInbox(coordRoot, messages) {
             ? "Message for this task:"
             : `${messages.length} messages for this task:`;
     const body = messages
-        .map((message) => `  ${message.message_id} from ${message.sender_instance_id === null ? "Operator" : `agent-${message.sender_display_name}`} (${message.created_at}):\n` +
+        .map((message) => `  ${message.message_id} from ${message.sender_instance_id === null ? "Operator" : `agent-${message.sender_display_name}`}` +
+        `${message.sender_machine ? ` on ${message.sender_machine}` : ""} (${message.created_at}):\n` +
         message.body
             .split("\n")
             .map((line) => `    ${line}`)