harnery 0.42.0 → 0.44.0

package/dist/core/hooks/shell-tokens.js

@@ -0,0 +1,97 @@
+/** Shared, deliberately small shell lexer for PreToolUse command guards. */
+/** Keep quoted arguments opaque, including examples and heredoc bodies. */
+export function tokenize(source) {
+    const out = [];
+    const heredocs = [];
+    for (let i = 0; i < source.length;) {
+        const ch = source[i];
+        if (ch === "\\" && source[i + 1] === "\n") {
+            i += 2;
+            continue;
+        }
+        if (ch === "\n") {
+            out.push({ value: ";", quoted: false, operator: true });
+            i++;
+            for (const doc of heredocs.splice(0)) {
+                while (i < source.length) {
+                    const end = source.indexOf("\n", i);
+                    const stop = end === -1 ? source.length : end;
+                    const line = source.slice(i, stop);
+                    i = end === -1 ? source.length : end + 1;
+                    if ((doc.tabs ? line.replace(/^\t+/, "") : line) === doc.end)
+                        break;
+                }
+            }
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        if (ch === "#") {
+            const end = source.indexOf("\n", i);
+            i = end === -1 ? source.length : end;
+            continue;
+        }
+        if (";|&(){}<>".includes(ch)) {
+            const op = source.slice(i).match(/^(?:<<-?|>>|&&|\|\||[;|&(){}<>])/)[0];
+            out.push({ value: op, quoted: false, operator: true });
+            i += op.length;
+            continue;
+        }
+        let value = "";
+        let quoted = false;
+        while (i < source.length && !/[\s;|&(){}<>]/.test(source[i])) {
+            const next = source[i++];
+            if (next === "'" || next === '"' || next === "`") {
+                quoted = true;
+                while (i < source.length && source[i] !== next) {
+                    if (source[i] === "\\" && next !== "'" && i + 1 < source.length)
+                        i++;
+                    value += source[i++];
+                }
+                if (source[i] === next)
+                    i++;
+            }
+            else if (next === "\\" && i < source.length) {
+                const escaped = source[i++];
+                if (escaped !== "\n")
+                    value += escaped;
+            }
+            else {
+                value += next;
+            }
+        }
+        const previous = out.at(-1)?.value;
+        if (previous === "<<" || previous === "<<-") {
+            heredocs.push({ end: value, tabs: previous === "<<-" });
+        }
+        out.push({ value, quoted });
+    }
+    return out;
+}
+export function basename(value) {
+    return value.split(/[\\/]/).at(-1) ?? value;
+}
+/** The command string of a Bash-style tool call, or null for any other tool. */
+export function shellCommandFromTool(toolName, toolInput) {
+    if (typeof toolName !== "string")
+        return null;
+    const name = toolName.toLowerCase().replace(/^functions\./, "");
+    if (!["bash", "shell", "shell_command", "exec_command"].includes(name))
+        return null;
+    let input = toolInput;
+    if (typeof input === "string") {
+        try {
+            input = JSON.parse(input);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!input || typeof input !== "object")
+        return null;
+    const args = input;
+    const command = args.command ?? args.cmd;
+    return typeof command === "string" ? command : null;
+}

package/dist/core/hooks/shell-waiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell-waiter.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/shell-waiter.ts"],"names":[],"mappings":"AAqJA,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgBtF"}
+{"version":3,"file":"shell-waiter.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/shell-waiter.ts"],"names":[],"mappings":"AA2EA,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGtF"}

package/dist/core/hooks/shell-waiter.js

@@ -1,83 +1,10 @@
+import { basename, shellCommandFromTool, tokenize } from "./shell-tokens.js";
 /** Recognize inline waiters; this is not a proof of arbitrary shell termination. */
 const REASON = "Inline shell waiter blocked: polling loops and delayed log-only checks can outlive the job " +
     "and accumulate as background tasks. Read the existing task output now, or wait on its " +
     "existing task handle. If polling is necessary, use a reviewed script with a hard deadline, " +
     "nonzero timeout exit, and producer-exit/failure detection. Do not create another waiter " +
     "to check progress or infer completion from a broad pgrep -f pattern.";
-/** Keep quoted arguments opaque, including examples and heredoc bodies. */
-function tokenize(source) {
-    const out = [];
-    const heredocs = [];
-    for (let i = 0; i < source.length;) {
-        const ch = source[i];
-        if (ch === "\\" && source[i + 1] === "\n") {
-            i += 2;
-            continue;
-        }
-        if (ch === "\n") {
-            out.push({ value: ";", quoted: false, operator: true });
-            i++;
-            for (const doc of heredocs.splice(0)) {
-                while (i < source.length) {
-                    const end = source.indexOf("\n", i);
-                    const stop = end === -1 ? source.length : end;
-                    const line = source.slice(i, stop);
-                    i = end === -1 ? source.length : end + 1;
-                    if ((doc.tabs ? line.replace(/^\t+/, "") : line) === doc.end)
-                        break;
-                }
-            }
-            continue;
-        }
-        if (/\s/.test(ch)) {
-            i++;
-            continue;
-        }
-        if (ch === "#") {
-            const end = source.indexOf("\n", i);
-            i = end === -1 ? source.length : end;
-            continue;
-        }
-        if (";|&(){}<>".includes(ch)) {
-            const op = source.slice(i).match(/^(?:<<-?|>>|&&|\|\||[;|&(){}<>])/)[0];
-            out.push({ value: op, quoted: false, operator: true });
-            i += op.length;
-            continue;
-        }
-        let value = "";
-        let quoted = false;
-        while (i < source.length && !/[\s;|&(){}<>]/.test(source[i])) {
-            const next = source[i++];
-            if (next === "'" || next === '"' || next === "`") {
-                quoted = true;
-                while (i < source.length && source[i] !== next) {
-                    if (source[i] === "\\" && next !== "'" && i + 1 < source.length)
-                        i++;
-                    value += source[i++];
-                }
-                if (source[i] === next)
-                    i++;
-            }
-            else if (next === "\\" && i < source.length) {
-                const escaped = source[i++];
-                if (escaped !== "\n")
-                    value += escaped;
-            }
-            else {
-                value += next;
-            }
-        }
-        const previous = out.at(-1)?.value;
-        if (previous === "<<" || previous === "<<-") {
-            heredocs.push({ end: value, tabs: previous === "<<-" });
-        }
-        out.push({ value, quoted });
-    }
-    return out;
-}
-function basename(value) {
-    return value.split(/[\\/]/).at(-1) ?? value;
-}
 function isWaiter(source, depth = 0) {
     if (depth > 8)
         return false;
@@ -151,23 +78,6 @@ function isWaiter(source, depth = 0) {
         commands.every((name) => harmless.has(name)));
 }
 export function shellWaiterReason(toolName, toolInput) {
-    if (typeof toolName !== "string")
-        return null;
-    const name = toolName.toLowerCase().replace(/^functions\./, "");
-    if (!["bash", "shell", "shell_command", "exec_command"].includes(name))
-        return null;
-    let input = toolInput;
-    if (typeof input === "string") {
-        try {
-            input = JSON.parse(input);
-        }
-        catch {
-            return null;
-        }
-    }
-    if (!input || typeof input !== "object")
-        return null;
-    const args = input;
-    const command = args.command ?? args.cmd;
-    return typeof command === "string" && isWaiter(command) ? REASON : null;
+    const command = shellCommandFromTool(toolName, toolInput);
+    return command !== null && isWaiter(command) ? REASON : null;
 }

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

@@ -17,7 +17,8 @@ export interface HarneryInboxMessageRecordV1 {
     schema: typeof HARNERY_INBOX_RECORD_SCHEMA;
     kind: "message";
     message_id: string;
-    sender_instance_id: string;
+    /** A required null identifies an operator; strings identify real agent instances. */
+    sender_instance_id: string | null;
     sender_display_name: string;
     recipient_instance_id: string;
     recipient_display_name: string;

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,kBAAkB,EAAE,MAAM,CAAC;IAC3B,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":"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"}

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

@@ -1,5 +1,7 @@
 export * from "./contract.js";
 export * from "./lifecycle.js";
+export * from "./peer-messages.js";
 export * from "./service.js";
+export * from "./targets.js";
 export * from "./watcher.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/core/inbox/index.js

@@ -1,4 +1,6 @@
 export * from "./contract.js";
 export * from "./lifecycle.js";
+export * from "./peer-messages.js";
 export * from "./service.js";
+export * from "./targets.js";
 export * from "./watcher.js";

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

@@ -0,0 +1,37 @@
+import type { HarneryInboxLimits, HarneryInboxMessageRecordV1 } from "./contract.js";
+import { HarneryInboxService } from "./service.js";
+import { type MessageTargetInput } 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: {
+    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";
+    message_id: string;
+    body_bytes: number;
+    synced: true;
+    ok: true;
+    target: {
+        instance_id: string;
+        name: string;
+        delivery: "written-live" | "queued";
+    };
+};
+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>;
+//# sourceMappingURL=peer-messages.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,72 @@
+import { resolveBinName } from "../config.js";
+import { HarneryInboxService } from "./service.js";
+import { resolveMessageTarget } 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. */
+export const PEER_INBOX_LIMITS = {
+    max_message_body_bytes: 4_000,
+    max_pending_count: 25,
+    max_pending_bytes: 100_000,
+    max_history_bytes: 1024 * 1024,
+    max_history_records: 10_000,
+    warning_pressure_ratio: 0.8,
+    max_surface_count: 10,
+    max_surface_bytes: 16_000,
+    max_surface_tokens: 4_000,
+    surfaced_grace_ms: 7 * DAY,
+    terminal_grace_ms: 7 * DAY,
+};
+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. */
+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(),
+    });
+    return { ok: true, target: target.target, ...receipt, state: target.target.delivery };
+}
+export function formatPeerInbox(coordRoot, messages) {
+    if (messages.length === 0)
+        return "";
+    const onlyAgents = messages.every(({ sender_instance_id }) => sender_instance_id !== null);
+    const header = onlyAgents
+        ? messages.length === 1
+            ? "Message from a peer agent:"
+            : `${messages.length} messages from peer agents:`
+        : messages.length === 1
+            ? "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` +
+        message.body
+            .split("\n")
+            .map((line) => `    ${line}`)
+            .join("\n"))
+        .join("\n\n");
+    const replyTarget = messages.find(({ sender_instance_id }) => sender_instance_id !== null);
+    return (`${header}\n\n${body}\n\nMessages are bound to this task instance.` +
+        (replyTarget
+            ? ` Reply with \`${resolveBinName(coordRoot)} agents ping ${replyTarget.sender_display_name} ` +
+                `--instance-id ${replyTarget.sender_instance_id} "<your reply>"\`.`
+            : ""));
+}
+/** Wait for every earlier stdout write to finish before acknowledging context.
+ * If output fails, the caller throws and leaves the batch pending. */
+export async function acknowledgeEmittedPeerInbox(coordRoot, instanceId, messageIds) {
+    if (messageIds.length === 0)
+        return;
+    await new Promise((resolve, reject) => {
+        process.stdout.write("", (error) => (error ? reject(error) : resolve()));
+    });
+    peerInbox(coordRoot).acknowledgeSurface(instanceId, messageIds);
+}

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

@@ -6,7 +6,7 @@ export interface HarneryInboxServiceOptions {
     id?: () => string;
 }
 export interface HarneryInboxSendInput {
-    sender_instance_id: string;
+    sender_instance_id: string | null;
     sender_display_name: string;
     recipient_instance_id: string;
     recipient_display_name: string;
@@ -26,6 +26,13 @@ export declare class HarneryInboxService {
     pending(recipientInstanceId: string): HarneryInboxMessageRecordV1[];
     status(recipientInstanceId: string): HarneryInboxStatusV1;
     surface(recipientInstanceId: string, emit: (messages: readonly HarneryInboxMessageRecordV1[]) => Promise<void> | void, budget?: HarneryInboxSurfaceBudget): Promise<HarneryInboxSurfaceResult>;
+    /** Preparing prompt text is read-only. A failed or abandoned emission must
+     * leave the same messages pending for the recipient's next prompt. */
+    prepareSurface(recipientInstanceId: string, budget?: HarneryInboxSurfaceBudget): HarneryInboxMessageRecordV1[];
+    /** Call only after the selected IDs have actually been emitted. A message
+     * appended while output is in flight remains pending rather than being
+     * included in an acknowledgement of an older batch. */
+    acknowledgeSurface(recipientInstanceId: string, messageIds: readonly string[]): void;
 }
 export declare function inboxPath(coordRoot: string, recipientInstanceId: string): string;
 export declare function project(records: readonly HarneryInboxRecordV1[]): {

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":"AAIA,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,CAAC;IAC3B,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;IAO5D,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;CAoCtC;AAED,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,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"}

package/dist/core/inbox/service.js

@@ -1,7 +1,7 @@
 import { 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 { readCrashSafeJsonlFile, updateCrashSafeJsonlFile, } from "../storage/durable-history.js";
 import { HARNERY_INBOX_RECORD_SCHEMA, HARNERY_INBOX_STATUS_SCHEMA, HarneryInboxCapacityError, } from "./contract.js";
 export class HarneryInboxService {
     #options;
@@ -20,7 +20,7 @@ export class HarneryInboxService {
             schema: HARNERY_INBOX_RECORD_SCHEMA,
             kind: "message",
             message_id: `msg_${this.#options.id?.() ?? randomUUID()}`,
-            sender_instance_id: opaqueId(input.sender_instance_id, "sender instance"),
+            sender_instance_id: senderId(input.sender_instance_id),
             sender_display_name: boundedDisplay(input.sender_display_name),
             recipient_instance_id: recipient,
             recipient_display_name: boundedDisplay(input.recipient_display_name),
@@ -29,7 +29,7 @@ export class HarneryInboxService {
             body_bytes: bodyBytes,
         };
         const path = inboxPath(this.#options.coord_root, recipient);
-        return updateCrashSafeJsonlFile(path, readOptions(limits), (records) => {
+        return updateInboxHistory(path, readOptions(limits), (records) => {
             const projection = project(records);
             capacityCheck(projection, record, path, limits);
             return {
@@ -44,7 +44,10 @@ export class HarneryInboxService {
         });
     }
     records(recipientInstanceId) {
-        return readCrashSafeJsonlFile(inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")), readOptions(this.#options.limits));
+        const records = readCrashSafeJsonlFile(inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")), readOptions(this.#options.limits));
+        for (const record of records)
+            validateRecord(record);
+        return records;
     }
     pending(recipientInstanceId) {
         return project(this.records(recipientInstanceId)).pending;
@@ -75,18 +78,42 @@ export class HarneryInboxService {
         max_bytes: this.#options.limits.max_surface_bytes,
         max_tokens: this.#options.limits.max_surface_tokens,
     }) {
-        validateSurfaceBudget(budget);
         const recipient = opaqueId(recipientInstanceId, "recipient instance");
-        const selected = selectOldestFitting(this.pending(recipient), budget);
+        const selected = this.prepareSurface(recipient, budget);
         await emit(selected);
-        if (selected.length > 0) {
+        this.acknowledgeSurface(recipient, selected.map(({ message_id }) => message_id));
+        const remaining = this.pending(recipient);
+        return {
+            emitted: selected,
+            remaining_pending_count: remaining.length,
+            remaining_pending_bytes: remaining.reduce((sum, record) => sum + record.body_bytes, 0),
+            repeated_after_crash_possible: true,
+        };
+    }
+    /** Preparing prompt text is read-only. A failed or abandoned emission must
+     * leave the same messages pending for the recipient's next prompt. */
+    prepareSurface(recipientInstanceId, budget = {
+        max_count: this.#options.limits.max_surface_count,
+        max_bytes: this.#options.limits.max_surface_bytes,
+        max_tokens: this.#options.limits.max_surface_tokens,
+    }) {
+        validateSurfaceBudget(budget);
+        return selectOldestFitting(this.pending(recipientInstanceId), budget);
+    }
+    /** Call only after the selected IDs have actually been emitted. A message
+     * appended while output is in flight remains pending rather than being
+     * included in an acknowledgement of an older batch. */
+    acknowledgeSurface(recipientInstanceId, messageIds) {
+        const recipient = opaqueId(recipientInstanceId, "recipient instance");
+        const selected = new Set(messageIds);
+        if (selected.size > 0) {
             const surfacedAt = now(this.#options).toISOString();
-            updateCrashSafeJsonlFile(inboxPath(this.#options.coord_root, recipient), readOptions(this.#options.limits), (records) => {
+            updateInboxHistory(inboxPath(this.#options.coord_root, recipient), readOptions(this.#options.limits), (records) => {
                 const stillPending = new Set(project(records).pending.map(({ message_id }) => message_id));
                 return {
-                    append: selected
-                        .filter(({ message_id }) => stillPending.has(message_id))
-                        .map(({ message_id }) => ({
+                    append: [...selected]
+                        .filter((message_id) => stillPending.has(message_id))
+                        .map((message_id) => ({
                         schema: HARNERY_INBOX_RECORD_SCHEMA,
                         kind: "surfaced",
                         message_id,
@@ -96,13 +123,26 @@ export class HarneryInboxService {
                 };
             });
         }
-        const remaining = this.pending(recipient);
-        return {
-            emitted: selected,
-            remaining_pending_count: remaining.length,
-            remaining_pending_bytes: remaining.reduce((sum, record) => sum + record.body_bytes, 0),
-            repeated_after_crash_possible: true,
-        };
+    }
+}
+/** 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
+ * immediately, and an occupied live lease is never removed or overridden. */
+function updateInboxHistory(path, options, update) {
+    const deadline = performance.now() + 2_000;
+    const pause = new Int32Array(new SharedArrayBuffer(4));
+    while (true) {
+        try {
+            return updateCrashSafeJsonlFile(path, options, update);
+        }
+        catch (error) {
+            if (!(error instanceof Error) ||
+                error.message !== `durable history lease busy: ${path}.lease` ||
+                performance.now() >= deadline)
+                throw error;
+            Atomics.wait(pause, 0, 0, Math.min(10, deadline - performance.now()));
+        }
     }
 }
 export function inboxPath(coordRoot, recipientInstanceId) {
@@ -174,10 +214,13 @@ function now(options) {
     return options.now?.() ?? new Date();
 }
 function opaqueId(value, field) {
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value))
+    if (typeof value !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value))
         throw new Error(`invalid ${field} id`);
     return value;
 }
+function senderId(value) {
+    return value === null ? null : opaqueId(value, "sender instance");
+}
 function boundedDisplay(value) {
     const result = value.trim();
     if (result.length === 0 || Buffer.byteLength(result) > 256)
@@ -187,8 +230,11 @@ function boundedDisplay(value) {
 function validateRecord(record) {
     if (record.schema !== HARNERY_INBOX_RECORD_SCHEMA)
         throw new Error("unknown inbox record schema");
-    if (record.kind === "message" && Buffer.byteLength(record.body) !== record.body_bytes) {
-        throw new Error(`inbox message ${record.message_id} has invalid body_bytes`);
+    if (record.kind === "message") {
+        senderId(record.sender_instance_id);
+        if (Buffer.byteLength(record.body) !== record.body_bytes) {
+            throw new Error(`inbox message ${record.message_id} has invalid body_bytes`);
+        }
     }
 }
 function validateLimits(limits) {

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

@@ -0,0 +1,22 @@
+export interface MessageTargetInput {
+    name?: string;
+    instanceId?: string;
+    requireLive?: boolean;
+    now?: Date;
+}
+export type MessageTargetResult = {
+    ok: true;
+    target: {
+        instance_id: string;
+        name: string;
+        delivery: "written-live" | "queued";
+    };
+} | {
+    ok: false;
+    code: "no_peer" | "ambiguous_peer" | "not_live" | "authority_unsafe";
+    message: string;
+    candidates?: string[];
+};
+/** Resolve one immutable recipient without extending presence or claiming attention. */
+export declare function resolveMessageTarget(coordRoot: string, input: MessageTargetInput): MessageTargetResult;
+//# sourceMappingURL=targets.d.ts.map

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

@@ -0,0 +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"}