@tpsdev-ai/agent 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/bun.lock +27 -15
  2. package/bunfig.toml +17 -0
  3. package/dist/bin.js +4 -3
  4. package/dist/bin.js.map +1 -1
  5. package/dist/config.d.ts +8 -1
  6. package/dist/config.d.ts.map +1 -1
  7. package/dist/config.js +38 -3
  8. package/dist/config.js.map +1 -1
  9. package/dist/home.d.ts +3 -0
  10. package/dist/home.d.ts.map +1 -0
  11. package/dist/home.js +18 -0
  12. package/dist/home.js.map +1 -0
  13. package/dist/index.d.ts +16 -3
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +12 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/io/flair.d.ts +1 -10
  18. package/dist/io/flair.d.ts.map +1 -1
  19. package/dist/io/flair.js +29 -28
  20. package/dist/io/flair.js.map +1 -1
  21. package/dist/io/mail.d.ts +184 -30
  22. package/dist/io/mail.d.ts.map +1 -1
  23. package/dist/io/mail.js +944 -185
  24. package/dist/io/mail.js.map +1 -1
  25. package/dist/lib/agent-keys.d.ts +106 -0
  26. package/dist/lib/agent-keys.d.ts.map +1 -0
  27. package/dist/lib/agent-keys.js +298 -0
  28. package/dist/lib/agent-keys.js.map +1 -0
  29. package/dist/lib/bridge-identity.d.ts +10 -0
  30. package/dist/lib/bridge-identity.d.ts.map +1 -0
  31. package/dist/lib/bridge-identity.js +56 -0
  32. package/dist/lib/bridge-identity.js.map +1 -0
  33. package/dist/lib/mail-lock-namespace.d.ts +19 -0
  34. package/dist/lib/mail-lock-namespace.d.ts.map +1 -0
  35. package/dist/lib/mail-lock-namespace.js +58 -0
  36. package/dist/lib/mail-lock-namespace.js.map +1 -0
  37. package/dist/lib/mail-lock.d.ts +81 -0
  38. package/dist/lib/mail-lock.d.ts.map +1 -0
  39. package/dist/lib/mail-lock.js +319 -0
  40. package/dist/lib/mail-lock.js.map +1 -0
  41. package/dist/lib/mailbox-filename.d.ts +2 -0
  42. package/dist/lib/mailbox-filename.d.ts.map +1 -0
  43. package/dist/lib/mailbox-filename.js +4 -0
  44. package/dist/lib/mailbox-filename.js.map +1 -0
  45. package/dist/lib/mailbox-policy.d.ts +245 -0
  46. package/dist/lib/mailbox-policy.d.ts.map +1 -0
  47. package/dist/lib/mailbox-policy.js +949 -0
  48. package/dist/lib/mailbox-policy.js.map +1 -0
  49. package/dist/lib/public-key.d.ts +6 -0
  50. package/dist/lib/public-key.d.ts.map +1 -0
  51. package/dist/lib/public-key.js +45 -0
  52. package/dist/lib/public-key.js.map +1 -0
  53. package/dist/lib/registry-key.d.ts +2 -0
  54. package/dist/lib/registry-key.d.ts.map +1 -0
  55. package/dist/lib/registry-key.js +10 -0
  56. package/dist/lib/registry-key.js.map +1 -0
  57. package/dist/lib/relay-lock.d.ts +7 -0
  58. package/dist/lib/relay-lock.d.ts.map +1 -0
  59. package/dist/lib/relay-lock.js +19 -0
  60. package/dist/lib/relay-lock.js.map +1 -0
  61. package/dist/lib/signEnvelope.d.ts +12 -0
  62. package/dist/lib/signEnvelope.d.ts.map +1 -1
  63. package/dist/lib/signEnvelope.js.map +1 -1
  64. package/dist/lib/signing-key.d.ts +2 -0
  65. package/dist/lib/signing-key.d.ts.map +1 -0
  66. package/dist/lib/signing-key.js +9 -0
  67. package/dist/lib/signing-key.js.map +1 -0
  68. package/dist/lib/topic-recipient.d.ts +2 -0
  69. package/dist/lib/topic-recipient.d.ts.map +1 -0
  70. package/dist/lib/topic-recipient.js +2 -0
  71. package/dist/lib/topic-recipient.js.map +1 -0
  72. package/dist/llm/provider.d.ts.map +1 -1
  73. package/dist/llm/provider.js +9 -7
  74. package/dist/llm/provider.js.map +1 -1
  75. package/dist/runtime/agent.d.ts.map +1 -1
  76. package/dist/runtime/agent.js +32 -25
  77. package/dist/runtime/agent.js.map +1 -1
  78. package/dist/runtime/event-loop.d.ts +21 -2
  79. package/dist/runtime/event-loop.d.ts.map +1 -1
  80. package/dist/runtime/event-loop.js +199 -54
  81. package/dist/runtime/event-loop.js.map +1 -1
  82. package/dist/runtime/types.d.ts +11 -0
  83. package/dist/runtime/types.d.ts.map +1 -1
  84. package/dist/runtime/types.js +13 -1
  85. package/dist/runtime/types.js.map +1 -1
  86. package/package.json +3 -4
  87. package/src/bin.ts +4 -3
  88. package/src/config.ts +46 -3
  89. package/src/home.ts +18 -0
  90. package/src/index.ts +33 -2
  91. package/src/io/flair.ts +23 -28
  92. package/src/io/mail.ts +1007 -200
  93. package/src/lib/agent-keys.ts +308 -0
  94. package/src/lib/bridge-identity.ts +49 -0
  95. package/src/lib/mail-lock-namespace.ts +64 -0
  96. package/src/lib/mail-lock.ts +337 -0
  97. package/src/lib/mailbox-filename.ts +3 -0
  98. package/src/lib/mailbox-policy.ts +1085 -0
  99. package/src/lib/public-key.ts +49 -0
  100. package/src/lib/registry-key.ts +8 -0
  101. package/src/lib/relay-lock.ts +20 -0
  102. package/src/lib/signEnvelope.ts +12 -0
  103. package/src/lib/signing-key.ts +8 -0
  104. package/src/lib/topic-recipient.ts +1 -0
  105. package/src/llm/provider.ts +9 -7
  106. package/src/runtime/agent.ts +30 -27
  107. package/src/runtime/event-loop.ts +221 -68
  108. package/src/runtime/types.ts +14 -0
  109. package/test/config.test.ts +85 -2
  110. package/test/core-loop.test.ts +6 -4
  111. package/test/governance.test.ts +4 -1
  112. package/test/helpers/event-loop-child.mjs +50 -0
  113. package/test/helpers/mail-delivery-worker.mjs +16 -0
  114. package/test/helpers/mail-kill-child.mjs +104 -0
  115. package/test/helpers/signed-relay-record.ts +31 -0
  116. package/test/home-per-call.test.ts +72 -0
  117. package/test/io.test.ts +81 -14
  118. package/test/mail-client-lock-namespace.test.ts +155 -0
  119. package/test/mail-client-repoint-root.test.ts +368 -0
  120. package/test/mail-delivery-at-least-once.test.ts +1238 -0
  121. package/test/mail-event-loop-delivery.test.ts +769 -0
  122. package/test/mail-intent-phases.test.ts +304 -0
  123. package/test/mail-interrupted-recovery.test.ts +393 -0
  124. package/test/mail-lock-pid-state.test.ts +238 -0
  125. package/test/mail-lock.test.ts +96 -0
  126. package/test/mail-partial-flair.test.ts +102 -0
  127. package/test/mail-placement-replay.test.ts +116 -0
  128. package/test/mail-promote-guard.test.ts +305 -21
  129. package/test/mail-relay-reservation.test.ts +60 -0
  130. package/test/mailbox-filename.test.ts +16 -0
  131. package/test/public-key.test.ts +108 -0
  132. package/test/runtime-key-encoding.test.ts +105 -0
  133. package/test/runtime-pending-key.test.ts +117 -0
  134. package/test/security/mail-trust.test.ts +406 -109
package/src/io/mail.ts CHANGED
@@ -1,17 +1,40 @@
1
- import { existsSync, mkdirSync, readdirSync, renameSync, readFileSync, writeFileSync } from "node:fs";
1
+ import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, renameSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
2
+ import { isMailboxMessageFile } from "../lib/mailbox-filename.js";
2
3
  import { join } from "node:path";
4
+ import { randomUUID } from "node:crypto";
3
5
  import type { EventLogger } from "../telemetry/events.js";
4
6
  import { sanitizeError } from "../telemetry/events.js";
5
- import { verifyEnvelope, type FlairClient } from "../lib/signEnvelope.js";
7
+ import { signEnvelope, type ChainEntry, type Envelope, type FlairClient } from "../lib/signEnvelope.js";
8
+ import { PublicKeyFormatError } from "../lib/public-key.js";
9
+ import { agentKeyCandidates, readAgentPrivateKey } from "../lib/agent-keys.js";
10
+ import { tryAcquireRelayMoveLock } from "../lib/relay-lock.js";
11
+ import { canonicalMailboxRoot, canonicalMailRoot } from "../lib/mail-lock-namespace.js";
12
+ import { acquireMailLock, acquireMailLockSync, type MailLock, processIsGone, processStartToken } from "../lib/mail-lock.js";
13
+ import {
14
+ DELIVERY_PRESENTATION_TTL_MS,
15
+ PlacementDurabilityError,
16
+ decideEnvelopeForMailbox,
17
+ type MailboxPolicyRejectClass,
18
+ mailboxReplayStore,
19
+ parseSignedEnvelope,
20
+ pendingPlacementEntries,
21
+ type PlacementPhase,
22
+ placeCurRecord, fileIdentity, matchesFileIdentity,
23
+ type PresentationClaim,
24
+ } from "../lib/mailbox-policy.js";
25
+ import { verifiedMailTier } from "../lib/bridge-identity.js";
6
26
 
7
27
  export interface MailMessage {
8
28
  filename: string;
9
29
  body: string;
10
30
  receivedAt: Date;
11
- /** Trust/routing headers from bridge envelope */
31
+ /** Untrusted transport metadata. Never grants authority. */
12
32
  headers: Record<string, string>;
13
- /** Sender agent ID */
33
+ /** Sender from the verified envelope when received through MailClient. */
14
34
  from: string;
35
+ /** Present only after signature and mailbox policy both passed. */
36
+ verifiedEnvelope?: Envelope;
37
+ trustTier?: "user" | "internal" | "external";
15
38
  }
16
39
 
17
40
  /**
@@ -22,21 +45,151 @@ export interface MailMessage {
22
45
  * dead-lettered (the record stays in `new/`), so no retryable class is written
23
46
  * here.
24
47
  */
25
- type MailboxRejectClass = "invalid" | "unresolvable-principal" | "wrong-recipient";
48
+ type MailboxRejectClass = MailboxPolicyRejectClass;
26
49
 
27
- type VerifyOutcome =
28
- | { pass: true }
29
- | { pass: false; class: MailboxRejectClass; reason: string; from?: string };
50
+ /** A handoff token issued by deliverNext(); pass it to completeDelivery() or releaseDelivery(). */
51
+ export interface MailDelivery {
52
+ readonly message: MailMessage;
53
+ /** JSON-encoded [canonical mailbox path, messageId]; stable across presentations at that path. */
54
+ readonly deliveryKey: string;
55
+ /** This hand-over's presentation number; 1 for the first. */
56
+ readonly presentation: number;
57
+ }
30
58
 
31
59
  /**
32
- * The stable reason string `verifyEnvelope` returns when an agent-kind chain
33
- * entry or `envelope.from` cannot be resolved from the LOCAL Flair. An ABSENT
34
- * principal is a topology condition, not a forgery verdict, so it is labelled
35
- * `unresolvable-principal` rather than `invalid`. Duplicated from the shared
36
- * promotion boundary because `@tpsdev-ai/agent` cannot import `packages/cli`
37
- * (the dependency runs the other way: cli → agent).
60
+ * Why deliverNext() handed nothing over although work may be waiting:
61
+ * - `lock-busy`: the mailbox lock was unavailable.
62
+ * - `active`: this module copy holds the token, or another copy/process has
63
+ * a claim whose process is not provably gone and whose lease has not expired.
64
+ * No presentation is counted.
65
+ * - `cli-record`: a `placing` record verifies only as CLI-promoted.
66
+ * The CLI lease sweep requires an expired or absent checkout; direct bridge
67
+ * and plugin startup recovery does not check lease expiry.
68
+ * - `pending-record-invalid` / `pending-record-ambiguous`: a `placing` record
69
+ * verified as neither format or both, was quarantined and its intent cleared.
70
+ * - `verification-failed` / `verification-unavailable`: the pending cur/ copy
71
+ * did not re-verify, or it verified but its envelope names a different message
72
+ * than the intent; or the verifier (or the trust-tier read) did not answer.
73
+ * - `record-changed`: the pending cur/ copy is missing (a `placing` intent whose
74
+ * copy is gone can instead be resolved as gone), its recorded identity is
75
+ * absent or mismatched, or its bytes changed during re-verification.
76
+ * - `storage-error`: resolving roots or listing new/ threw, or a history, cur/, quarantine or
77
+ * placement-state operation threw while pending placements were processed.
78
+ * Quarantine may have moved the payload and unlinked the intent before sync failed.
79
+ * - `new-mail-deferred`: one new/ file's attempt did not complete: reading it,
80
+ * verifying it (including the verifier or trust-tier read not answering), a
81
+ * history read or a commit operation threw, or a placement appeared before
82
+ * its commit lock. A storage failure may follow a commit. A listed file that
83
+ * disappears before it is read is skipped, and the scan continues.
38
84
  */
39
- const UNRESOLVABLE_PRINCIPAL_REASON_RE = /^agent (.+) not found in Flair$/;
85
+ export type DeliveryDeferral =
86
+ | "lock-busy"
87
+ | "active"
88
+ | "cli-record"
89
+ | "pending-record-invalid"
90
+ | "pending-record-ambiguous"
91
+ | "verification-failed"
92
+ | "verification-unavailable"
93
+ | "record-changed"
94
+ | "storage-error"
95
+ | "new-mail-deferred";
96
+
97
+ /** What MailClient.deliverNext() returns (cli#617 slice b). */
98
+ export type DeliverNextResult =
99
+ | { status: "delivered"; delivery: MailDelivery }
100
+ /** No deliverable mail found during this scan; rejected mail may have been moved to `dlq/`. */
101
+ | { status: "idle" }
102
+ /** Work may be waiting; nothing was handed over. */
103
+ | { status: "deferred"; reason: DeliveryDeferral; detail: string; file?: string };
104
+
105
+ /** What MailClient.completeDelivery() returns (cli#617 slice b). */
106
+ export type DeliveryCompletion =
107
+ /** This call removed the message's `in_progress` intent. */
108
+ | { status: "completed" }
109
+ /** An earlier call with this delivery removed it. */
110
+ | { status: "already-completed" }
111
+ | { status: "quarantined" }
112
+ | { status: "deferred"; reason: "lock-busy" | "storage-error"; detail: string }
113
+ /**
114
+ * Not this hand-over's to finalize: a refusal finalizes no intent (one may
115
+ * already be absent). Only a locally issued `stale` or `identity` refusal
116
+ * releases the client's local token (its issued state becomes `released`);
117
+ * a `foreign` refusal changes no local state. `foreign`: not a
118
+ * delivery this MailClient issued. `stale`: no matching live intent and claim
119
+ * in the currently resolved mailbox. `identity`:
120
+ * recorded cur/ identity is absent or mismatched.
121
+ */
122
+ | { status: "refused"; reason: "foreign" | "stale" | "identity"; detail: string };
123
+
124
+ export type DeliveryRelease =
125
+ | { status: "released" }
126
+ | { status: "quarantined" }
127
+ | { status: "refused"; reason: "foreign" | "stale" }
128
+ | { status: "deferred"; reason: "lock-busy" | "storage-error"; detail: string };
129
+
130
+ type DeferredResult = Extract<DeliverNextResult, { status: "deferred" }>;
131
+ /** A pending placement this call resolved without presenting (gone, terminal, or another writer's phase). */
132
+ type PendingOutcome = DeliverNextResult | { status: "resolved" };
133
+ const RESOLVED: PendingOutcome = { status: "resolved" };
134
+
135
+ function report(fn: () => void): void {
136
+ try { fn(); } catch {}
137
+ }
138
+
139
+ function deferred(reason: DeliveryDeferral, detail: string, file?: string): DeferredResult {
140
+ return { status: "deferred", reason, detail, ...(file === undefined ? {} : { file }) };
141
+ }
142
+
143
+ /**
144
+ * Tokens held by the MailClients of this module copy. Other copies in the same
145
+ * process are treated as live until process exit or lease expiry.
146
+ */
147
+ const activePresentations = new Set<string>();
148
+ const moduleNonce = randomUUID();
149
+ let ownStartToken: string | null | undefined;
150
+
151
+ function ownClaim(token: string): PresentationClaim {
152
+ if (ownStartToken === undefined) ownStartToken = processStartToken(process.pid);
153
+ return { token, pid: process.pid, start: ownStartToken, moduleNonce };
154
+ }
155
+
156
+ function claimIsLive(claim: PresentationClaim | undefined, firstPresentedAt: string | undefined): boolean {
157
+ if (!claim) return false;
158
+ const own = ownClaim(claim.token);
159
+ if (claim.pid === own.pid && claim.start === own.start) {
160
+ if (claim.moduleNonce === moduleNonce) return activePresentations.has(claim.token);
161
+ return firstPresentedAt === undefined || Date.now() - Date.parse(firstPresentedAt) <= DELIVERY_PRESENTATION_TTL_MS;
162
+ }
163
+ if (firstPresentedAt !== undefined && Date.now() - Date.parse(firstPresentedAt) > DELIVERY_PRESENTATION_TTL_MS) return false;
164
+ return !processIsGone(claim.pid, claim.start);
165
+ }
166
+
167
+ function isCliPromotedRecord(record: unknown): record is {
168
+ id: string; from: string; to: string; body: string; timestamp: string; read: boolean;
169
+ envelopeId: string; envelope: Envelope; trustTier?: string;
170
+ checkedOutAt: string; checkedOutBy: string; deliveryAttempts: number; replyToId?: string;
171
+ } {
172
+ if (record === null || typeof record !== "object" || Array.isArray(record)) return false;
173
+ const r = record as Record<string, unknown>;
174
+ return typeof r.id === "string" && r.id.length > 0 &&
175
+ typeof r.from === "string" && typeof r.to === "string" && typeof r.body === "string" &&
176
+ typeof r.timestamp === "string" && typeof r.read === "boolean" &&
177
+ typeof r.envelopeId === "string" && r.envelopeId.length > 0 &&
178
+ r.envelope !== null && typeof r.envelope === "object" && !Array.isArray(r.envelope) &&
179
+ parseSignedEnvelope(JSON.stringify(r.envelope)).ok &&
180
+ (r.trustTier === undefined || r.trustTier === "user" || r.trustTier === "internal" || r.trustTier === "external") &&
181
+ typeof r.checkedOutAt === "string" && typeof r.checkedOutBy === "string" &&
182
+ Number.isInteger(r.deliveryAttempts) && (r.deliveryAttempts as number) >= 1 &&
183
+ (r.replyToId === undefined || typeof r.replyToId === "string");
184
+ }
185
+
186
+ function isMissing(err: unknown): boolean {
187
+ return (err as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
188
+ }
189
+
190
+ type VerifyOutcome =
191
+ | { pass: true; envelope: Envelope }
192
+ | { pass: false; class: MailboxRejectClass; reason: string; from?: string };
40
193
 
41
194
  /**
42
195
  * Write the dlq sidecar for a TERMINAL rejection.
@@ -58,92 +211,125 @@ function writeRejectSidecar(dlqDir: string, filename: string, cls: MailboxReject
58
211
  );
59
212
  }
60
213
 
214
+ function sameFileIdentity(a: string, b: string): boolean {
215
+ const sa = lstatOrAbsent(a);
216
+ const sb = lstatOrAbsent(b);
217
+ return sa !== null && sb !== null && sa.isFile() && sb.isFile()
218
+ && matchesFileIdentity(sa, fileIdentity(sb, readFileSync(b)), readFileSync(a));
219
+ }
220
+
221
+ /**
222
+ * cli#617 slice (a): recovery resumes only an intent whose phase resolves to
223
+ * `placing` (phaseOf). One that resolves to any other phase (`in_progress`, or
224
+ * `unknown`: an unsupported value in a recognized field) is never presented or
225
+ * finished. A phase seen in the listing skips the record before its payload
226
+ * is read, and the under-lock recheck catches a phase that changed after the
227
+ * payload was read and verified.
228
+ *
229
+ * This is the BATCH reader (`checkNewMail`), which stays at-most-once until
230
+ * slice (c) wires the per-message delivery API. Slice (b)'s `deliverNext`
231
+ * presents an `in_progress` intent again through its own completion-gated path
232
+ * (`presentPending`), not this one.
233
+ */
234
+ function resumableOnRecovery(phase: PlacementPhase | null): boolean {
235
+ return phase === "placing";
236
+ }
237
+
238
+ /**
239
+ * cli#636: resolve both roots to canonical path strings once per operation;
240
+ * derive subsequent paths, including locks, by joining those strings.
241
+ */
242
+ interface OperationRoots {
243
+ /** Canonical mail-root string: bridge-principal trust, acceptance stripes, recipient inboxes. */
244
+ readonly mailRoot: string;
245
+ /** Canonical mailbox string: the mailbox lock, maildir paths and replay state. */
246
+ readonly mailbox: string;
247
+ }
248
+
249
+ function lstatOrAbsent(path: string): import("node:fs").BigIntStats | null {
250
+ try {
251
+ return lstatSync(path, { bigint: true });
252
+ } catch (err) {
253
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
254
+ throw err;
255
+ }
256
+ }
257
+
61
258
  /**
62
259
  * Maildir-compatible mail client.
63
260
  * Reads from mailDir/inbox/new and moves processed messages to mailDir/inbox/cur.
64
261
  * Writes outgoing mail to mailDir/outbox/new.
65
262
  */
66
263
  export class MailClient {
67
- private inboxNew: string;
68
- private inboxCur: string;
69
- private inboxDlq: string;
70
- private outboxNew: string;
71
- /** One-shot guard so a misconfigured (verifier-less) mailbox warns once, not per poll. */
72
- private warnedNoVerifier = false;
264
+ private readonly flairClient: FlairClient;
265
+ /** cli#617 slice (b): the deliveries this client issued, keyed by the delivery object itself. */
266
+ private readonly issued = new WeakMap<MailDelivery, {
267
+ token: string;
268
+ messageId: string;
269
+ file: string;
270
+ mailbox: string;
271
+ state: "active" | "released" | "completed";
272
+ }>();
73
273
 
74
274
  constructor(
75
275
  public readonly mailDir: string,
76
276
  private readonly events?: EventLogger,
77
277
  private readonly agentId = "unknown",
78
- private readonly flairClient?: FlairClient,
278
+ flairClient?: FlairClient,
279
+ /** Configured Flair signing key, checked against both standard locations. */
280
+ private readonly signingKeyPath?: string,
79
281
  ) {
80
- this.inboxNew = join(mailDir, agentId, "new");
81
- this.inboxCur = join(mailDir, agentId, "cur");
82
- this.inboxDlq = join(mailDir, agentId, "dlq");
83
- this.outboxNew = join(mailDir, agentId, "outbox");
84
- for (const dir of [this.inboxNew, this.inboxCur, this.inboxDlq, this.outboxNew]) {
85
- mkdirSync(dir, { recursive: true });
282
+ // cli#380: construction without a verifier throws.
283
+ if (!flairClient) {
284
+ throw new Error(
285
+ `MailClient requires a Flair verifier for "${agentId}": refusing to construct a mailbox that ` +
286
+ `could promote unverified mail (cli#380).`,
287
+ );
86
288
  }
289
+ this.flairClient = flairClient;
290
+ // cli#636: no resolved canonical root is cached at construction.
291
+ this.operationRoots();
87
292
  }
88
293
 
89
294
  /**
90
- * Return all messages in inbox/new and move them to inbox/cur/.
91
- *
92
- * Verification is MANDATORY — a record is promoted ONLY after its signed
93
- * envelope verifies against the local Flair. There is no unverified path:
94
- * - NO verifier configured → refuse; the record stays in new/ (an absent
95
- * client must never mean "promote without verifying");
96
- * - the verifier THROWS (Flair unreachable) → refuse; the record stays in
97
- * new/ for a later check (a throw must never mean "pass");
98
- * - the verifier REJECTS → dead-letter to dlq/ with a `.reason` sidecar.
99
- * Unverified input must never reach the tool-holding model.
295
+ * Resolve `mailDir` and `<mail root>/<agentId>` to canonical path strings;
296
+ * create maildir subdirectories beneath the mailbox string.
100
297
  */
101
- async checkNewMail(): Promise<MailMessage[]> {
102
- if (!existsSync(this.inboxNew)) return [];
298
+ private operationRoots(): OperationRoots {
299
+ const mailRoot = canonicalMailRoot(this.mailDir);
300
+ // Create the mailbox with the default mode first (canonicalMailboxRoot
301
+ // would create it 0700); resolving it then creates nothing.
302
+ mkdirSync(join(mailRoot, this.agentId), { recursive: true });
303
+ const mailbox = canonicalMailboxRoot(join(mailRoot, this.agentId));
304
+ for (const dir of ["new", "cur", "dlq", "outbox"]) mkdirSync(join(mailbox, dir), { recursive: true });
305
+ return { mailRoot, mailbox };
306
+ }
103
307
 
104
- const files = readdirSync(this.inboxNew).filter((f) => !f.startsWith(".") && !f.includes("/") && !f.includes("\\"));
308
+ async checkNewMail(): Promise<MailMessage[]> {
105
309
  const messages: MailMessage[] = [];
310
+ const roots = this.operationRoots();
311
+ await this.recoverInterruptedPlacements(messages, roots);
312
+ const inboxNew = join(roots.mailbox, "new");
313
+ if (!existsSync(inboxNew)) return messages;
106
314
 
107
- // No verifier → NOTHING is promotable. Refuse (never rename into cur/) and
108
- // leave the records in new/ so a later check with a verifier — or the
109
- // shared promote() path — can process them.
110
- if (!this.flairClient) {
111
- if (files.length === 0) return [];
112
- this.events?.emit({
113
- type: "mail.receive",
114
- agent: this.agentId,
115
- status: "rejected",
116
- from: "unknown",
117
- durationMs: 0,
118
- error: "no verifier configured — refusing to promote unverified mail",
119
- });
120
- if (!this.warnedNoVerifier) {
121
- this.warnedNoVerifier = true;
122
- console.error(
123
- `[MailClient] no Flair verifier configured for "${this.agentId}": refusing to promote ` +
124
- `${files.length} unverified message(s) from new/. Unverified input must never reach the ` +
125
- `model — configure flair (url + key) or promote through the shared promote() lifecycle.`,
126
- );
127
- }
128
- return [];
129
- }
315
+ const files = readdirSync(inboxNew).filter(isMailboxMessageFile);
130
316
 
131
317
  for (const file of files) {
132
318
  const started = Date.now();
133
- const srcPath = join(this.inboxNew, file);
319
+ const srcPath = join(inboxNew, file);
134
320
 
135
321
  let body: string;
136
322
  try {
137
323
  body = readFileSync(srcPath, "utf-8");
138
324
  } catch (err) {
139
- this.events?.emit({
325
+ report(() => this.events?.emit({
140
326
  type: "mail.receive",
141
327
  agent: this.agentId,
142
328
  status: "error",
143
329
  from: "unknown",
144
330
  durationMs: Date.now() - started,
145
331
  error: sanitizeError(err),
146
- });
332
+ }));
147
333
  continue; // leave in new/ — a later check retries
148
334
  }
149
335
 
@@ -154,115 +340,811 @@ export class MailClient {
154
340
  verifyResult = await this.verifyMailBody(body);
155
341
  } catch (err) {
156
342
  const detail = sanitizeError(err);
157
- this.events?.emit({
343
+ report(() => this.events?.emit({
158
344
  type: "mail.receive",
159
345
  agent: this.agentId,
160
346
  status: "error",
161
347
  from: "unknown",
162
348
  durationMs: Date.now() - started,
163
349
  error: detail,
164
- });
165
- console.error(`[MailClient] verification could not run for ${file} — NOT promoting: ${detail}`);
350
+ }));
351
+ report(() => console.error(`[MailClient] verification could not run for ${file} — NOT promoting: ${detail}`));
166
352
  continue; // leave in new/
167
353
  }
168
354
 
169
355
  if (!verifyResult.pass) {
170
- const dlqPath = join(this.inboxDlq, file);
171
- try {
172
- if (srcPath !== dlqPath) renameSync(srcPath, dlqPath);
173
- writeRejectSidecar(this.inboxDlq, file, verifyResult.class, verifyResult.reason);
174
- } catch (err) {
175
- console.error(`[MailClient] failed to dead-letter ${file}: ${sanitizeError(err)}`);
176
- }
177
- this.events?.emit({
356
+ this.deadLetter(file, srcPath, verifyResult, started, roots);
357
+ continue;
358
+ }
359
+
360
+ let trustTier: MailMessage["trustTier"];
361
+ try {
362
+ trustTier = verifiedMailTier(verifyResult.envelope, roots.mailRoot);
363
+ } catch (err) {
364
+ const detail = sanitizeError(err);
365
+ report(() => this.events?.emit({
178
366
  type: "mail.receive",
179
367
  agent: this.agentId,
180
- status: "rejected",
181
- from: verifyResult.from ?? "unknown",
368
+ status: "error",
369
+ from: verifyResult.envelope.from,
182
370
  durationMs: Date.now() - started,
183
- error: verifyResult.reason,
184
- });
185
- continue;
371
+ error: detail,
372
+ }));
373
+ report(() => console.error(`[MailClient] trust tier could not be resolved for ${file} — NOT promoting: ${detail}`));
374
+ continue; // leave in new/
186
375
  }
187
376
 
188
- // Promote to cur/ — verified, and addressed to this mailbox.
189
377
  try {
190
- const dstPath = join(this.inboxCur, file);
191
- renameSync(srcPath, dstPath);
192
- let headers: Record<string, string> = {};
193
- let from = "unknown";
194
- try {
195
- const parsed = JSON.parse(body);
196
- headers = parsed.headers ?? {};
197
- from = parsed.from ?? "unknown";
198
- } catch {}
199
- messages.push({ filename: file, body, receivedAt: new Date(), headers, from });
200
- this.events?.emit({
378
+ const committed = await this.commitToCur(roots, file, srcPath, body, verifyResult.envelope);
379
+ // "live-placement" is returned only to the delivery API (a claim was passed).
380
+ if (committed === "already-delivered" || committed === "live-placement") continue;
381
+ if (committed) {
382
+ this.deadLetter(file, srcPath, { ...committed, from: verifyResult.envelope.from }, started, roots);
383
+ continue;
384
+ }
385
+ const from = verifyResult.envelope.from;
386
+ messages.push({
387
+ filename: file, body, receivedAt: new Date(), headers: {}, from,
388
+ verifiedEnvelope: verifyResult.envelope,
389
+ trustTier,
390
+ });
391
+ report(() => this.events?.emit({
201
392
  type: "mail.receive",
202
393
  agent: this.agentId,
203
394
  status: "ok",
204
395
  from,
205
396
  durationMs: Date.now() - started,
206
- });
397
+ }));
207
398
  } catch (err) {
208
- this.events?.emit({
399
+ report(() => this.events?.emit({
209
400
  type: "mail.receive",
210
401
  agent: this.agentId,
211
402
  status: "error",
212
403
  from: "unknown",
213
404
  durationMs: Date.now() - started,
214
405
  error: sanitizeError(err),
215
- });
406
+ }));
216
407
  }
217
408
  }
218
409
 
219
410
  return messages;
220
411
  }
221
412
 
413
+ /**
414
+ * Present verified, unclaimed pending work before committing new mail.
415
+ * Unresolved placing/in_progress work defers deliverNext() commits. The token
416
+ * set covers MailClients of this module copy; claims from other copies in the
417
+ * same process are treated as live until process exit or lease expiry.
418
+ * Retry deferred completion or release on the same hand-over.
419
+ */
420
+ async deliverNext(): Promise<DeliverNextResult> {
421
+ let roots: OperationRoots;
422
+ try {
423
+ roots = this.operationRoots();
424
+ } catch (err) {
425
+ this.emitRecoveryError(err);
426
+ return deferred("storage-error", `mailbox roots unavailable: ${sanitizeError(err)}`);
427
+ }
428
+ let pending: Array<{ messageId: string; file: string; phase: PlacementPhase }>;
429
+ const listing = await this.lockOrDefer(roots, "pending placements not listed");
430
+ if ("status" in listing) return listing;
431
+ try {
432
+ pending = pendingPlacementEntries(roots.mailbox);
433
+ } catch (err) {
434
+ this.emitRecoveryError(err);
435
+ return deferred("storage-error", `pending placements unavailable: ${sanitizeError(err)}`);
436
+ } finally {
437
+ listing.release();
438
+ }
439
+ pending.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
440
+ let firstDeferral: DeferredResult | null = null;
441
+ for (const { messageId, file, phase } of pending) {
442
+ if (phase === "unknown") continue; // another writer's phase: preserved, never presented (slice a)
443
+ let outcome: PendingOutcome;
444
+ try {
445
+ outcome = await this.presentPending(roots, messageId, file);
446
+ } catch (err) {
447
+ this.emitRecoveryError(err);
448
+ outcome = deferred("storage-error", sanitizeError(err), file);
449
+ }
450
+ if (outcome.status === "delivered") return outcome;
451
+ if (outcome.status === "deferred") firstDeferral ??= outcome;
452
+ }
453
+ if (firstDeferral) return firstDeferral;
454
+ return this.commitNextForDelivery(roots);
455
+ }
456
+
457
+ /** Finalize only this client's issued claim, with its recorded cur/ file identity, under the mailbox lock. */
458
+ async completeDelivery(delivery: MailDelivery): Promise<DeliveryCompletion> {
459
+ const issued = this.issued.get(delivery);
460
+ if (!issued) return { status: "refused", reason: "foreign", detail: "not a delivery this MailClient handed over" };
461
+ if (issued.state === "completed") return { status: "already-completed" };
462
+ let roots: OperationRoots;
463
+ try {
464
+ roots = this.operationRoots();
465
+ } catch (err) {
466
+ this.emitRecoveryError(err);
467
+ return { status: "deferred", reason: "storage-error", detail: `mailbox roots unavailable (${sanitizeError(err)}); delivery not finalized` };
468
+ }
469
+ const lock = await this.lockOrDefer(roots, "delivery not finalized; intent state unknown, retry");
470
+ if ("status" in lock) return { status: "deferred", reason: "lock-busy", detail: lock.detail };
471
+ let result: ReturnType<ReturnType<typeof mailboxReplayStore>["completePlacement"]>;
472
+ try {
473
+ if (this.expireIssuedDelivery(roots.mailbox, issued)) return { status: "quarantined" };
474
+ result = mailboxReplayStore(roots.mailbox).completePlacement(issued.messageId, issued.file, issued.token);
475
+ } catch (err) {
476
+ this.emitRecoveryError(err);
477
+ const detail = err instanceof PlacementDurabilityError
478
+ ? err.message
479
+ : err instanceof Error && err.name === "MalformedPlacementIntentError"
480
+ ? "quarantined placement intent needs repair before a retry can complete"
481
+ : `placement state unavailable (${sanitizeError(err)}); completion state unknown`;
482
+ return { status: "deferred", reason: "storage-error", detail };
483
+ } finally {
484
+ lock.release();
485
+ }
486
+ activePresentations.delete(issued.token);
487
+ if (result === "completed") {
488
+ issued.state = "completed";
489
+ return { status: "completed" };
490
+ }
491
+ issued.state = "released";
492
+ if (result === "identity") {
493
+ return { status: "refused", reason: "identity", detail: `cur/${issued.file} recorded identity is absent or mismatched; not finalized` };
494
+ }
495
+ return {
496
+ status: "refused",
497
+ reason: "stale",
498
+ detail: `message ${issued.messageId}: no matching live intent and claim in the currently resolved mailbox`,
499
+ };
500
+ }
501
+
502
+ /** Persist matching claim release under the issued mailbox's lock; contention and storage errors defer. */
503
+ releaseDelivery(delivery: MailDelivery): DeliveryRelease {
504
+ const issued = this.issued.get(delivery);
505
+ if (!issued) return { status: "refused", reason: "foreign" };
506
+ if (issued.state !== "active") return { status: "refused", reason: "stale" };
507
+ try {
508
+ const lock = acquireMailLockSync(issued.mailbox, { timeoutMs: 0 });
509
+ if (!lock) return { status: "deferred", reason: "lock-busy", detail: "delivery not released; retry" };
510
+ let released: boolean;
511
+ try {
512
+ if (this.expireIssuedDelivery(issued.mailbox, issued)) return { status: "quarantined" };
513
+ released = mailboxReplayStore(issued.mailbox).releasePlacement(issued.messageId, issued.file, issued.token);
514
+ } finally {
515
+ lock.release();
516
+ }
517
+ if (!released) return { status: "refused", reason: "stale" };
518
+ issued.state = "released";
519
+ activePresentations.delete(issued.token);
520
+ return { status: "released" };
521
+ } catch (err) {
522
+ this.emitRecoveryError(err);
523
+ return { status: "deferred", reason: "storage-error", detail: `release persistence failed (${sanitizeError(err)}); retry` };
524
+ }
525
+ }
526
+
527
+ /** Called under the mailbox lock; only this issued claim may hit the deadline. */
528
+ private expireIssuedDelivery(mailbox: string, issued: { messageId: string; file: string; token: string; state: string }): boolean {
529
+ const replay = mailboxReplayStore(mailbox);
530
+ const state = replay.placementState(issued.file);
531
+ if (state?.claim?.token !== issued.token) return false;
532
+ const expiry = replay.expireOverdue(issued.messageId, issued.file, new Date().toISOString());
533
+ if (expiry.status !== "failed") return false;
534
+ issued.state = "released";
535
+ activePresentations.delete(issued.token);
536
+ this.logQuarantine(issued.messageId, expiry.presentations, "deadline");
537
+ return true;
538
+ }
539
+
540
+ /** Record a hand-over: the token is already held in this module copy; bind it to the delivery object. */
541
+ private issue(roots: OperationRoots, token: string, messageId: string, file: string, presentation: number, message: MailMessage): MailDelivery {
542
+ const delivery: MailDelivery = Object.freeze({ message, deliveryKey: JSON.stringify([roots.mailbox, messageId]), presentation });
543
+ this.issued.set(delivery, { token, messageId, file, mailbox: roots.mailbox, state: "active" });
544
+ return delivery;
545
+ }
546
+
547
+ /**
548
+ * Present one pending placement: inspect it under the lock, re-verify its
549
+ * cur/ copy outside the lock, then re-check and advance under the lock.
550
+ */
551
+ private async presentPending(roots: OperationRoots, messageId: string, file: string): Promise<PendingOutcome> {
552
+ const inspected = await this.inspectPending(roots, messageId, file);
553
+ if (inspected.status !== "read") return inspected;
554
+ let outcome: VerifyOutcome;
555
+ try {
556
+ if (inspected.phase === "placing") {
557
+ const classified = await this.classifyPending(inspected.bytes);
558
+ if (classified.kind === "cli") return deferred("cli-record", `cur/${file} verifies only as CLI-promoted; awaiting CLI recovery`, file);
559
+ if (classified.kind === "pending-record-invalid" || classified.kind === "pending-record-ambiguous") {
560
+ return this.quarantinePending(roots, messageId, file, inspected.bytes, classified.kind);
561
+ }
562
+ outcome = classified.outcome;
563
+ } else {
564
+ outcome = await this.verifyMailBody(inspected.bytes.toString("utf8"));
565
+ }
566
+ } catch (err) {
567
+ return deferred("verification-unavailable", `re-verification could not run: ${sanitizeError(err)}`, file);
568
+ }
569
+ if (!outcome.pass) return deferred("verification-failed", `the cur/ copy did not re-verify (${outcome.class}): ${outcome.reason}`, file);
570
+ if (outcome.envelope.messageId !== messageId) {
571
+ return deferred("verification-failed", "the cur/ copy's envelope names another message than the intent", file);
572
+ }
573
+ let trustTier: MailMessage["trustTier"];
574
+ try {
575
+ trustTier = verifiedMailTier(outcome.envelope, roots.mailRoot);
576
+ } catch (err) {
577
+ return deferred("verification-unavailable", `trust tier unavailable: ${sanitizeError(err)}`, file);
578
+ }
579
+ return this.presentUnderLock(roots, messageId, file, inspected.bytes, outcome.envelope, trustTier);
580
+ }
581
+
582
+ private async classifyPending(bytes: Buffer): Promise<
583
+ | { kind: "raw"; outcome: Extract<VerifyOutcome, { pass: true }> }
584
+ | { kind: "cli" }
585
+ | { kind: "pending-record-invalid" }
586
+ | { kind: "pending-record-ambiguous" }
587
+ > {
588
+ const body = bytes.toString("utf8");
589
+ const raw = await this.verifyMailBody(body);
590
+ let record: unknown;
591
+ try { record = JSON.parse(body); } catch { record = null; }
592
+ let cli: VerifyOutcome | undefined;
593
+ if (isCliPromotedRecord(record)) {
594
+ const env = record.envelope;
595
+ if (record.from === env.from && record.to === env.to && record.body === env.body &&
596
+ record.timestamp === env.timestamp && record.envelopeId === env.messageId && record.replyToId === env.replyToId) {
597
+ cli = await this.verifyMailBody(JSON.stringify({ from: record.from, body: JSON.stringify(env) }));
598
+ }
599
+ }
600
+ if (raw.pass && cli?.pass) return { kind: "pending-record-ambiguous" };
601
+ if (raw.pass) return { kind: "raw", outcome: raw };
602
+ if (cli?.pass) return { kind: "cli" };
603
+ return { kind: "pending-record-invalid" };
604
+ }
605
+
606
+ private async quarantinePending(
607
+ roots: OperationRoots,
608
+ messageId: string, file: string, bytes: Buffer,
609
+ reason: "pending-record-invalid" | "pending-record-ambiguous",
610
+ ): Promise<PendingOutcome> {
611
+ const lock = await this.lockOrDefer(roots, "pending record not quarantined", file);
612
+ if ("status" in lock) return lock;
613
+ try {
614
+ const replay = mailboxReplayStore(roots.mailbox);
615
+ const state = replay.placementState(file);
616
+ if (!state || state.messageId !== messageId || state.phase !== "placing") return RESOLVED;
617
+ if (!replay.ownsPendingPlacement(messageId, file) || !readFileSync(join(roots.mailbox, "cur", file)).equals(bytes)) {
618
+ return deferred("record-changed", `cur/${file} identity absent or mismatched, or bytes changed; not quarantined`, file);
619
+ }
620
+ mkdirSync(join(roots.mailbox, "dlq"), { recursive: true });
621
+ writeRejectSidecar(join(roots.mailbox, "dlq"), file, "invalid", reason);
622
+ renameSync(join(roots.mailbox, "cur", file), join(roots.mailbox, "dlq", file));
623
+ replay.finishPlacement(messageId, file);
624
+ return deferred(reason, `cur/${file} quarantined: ${reason}; intent cleared`, file);
625
+ } finally {
626
+ lock.release();
627
+ }
628
+ }
629
+
630
+ private async inspectPending(roots: OperationRoots, messageId: string, file: string): Promise<PendingOutcome | { status: "read"; bytes: Buffer; phase: PlacementPhase }> {
631
+ const lock = await this.lockOrDefer(roots, "pending placement not inspected", file);
632
+ if ("status" in lock) return lock;
633
+ try {
634
+ const replay = mailboxReplayStore(roots.mailbox);
635
+ const state = replay.placementState(file);
636
+ if (!state || state.messageId !== messageId || state.phase === "failed" || state.phase === "unknown") return RESOLVED;
637
+ if (state.phase === "in_progress") {
638
+ if (claimIsLive(state.claim, state.firstPresentedAt)) {
639
+ return deferred("active", `message ${messageId} has an active claim (this module copy holds the token, or another copy/process has an unexpired claim)`, file);
640
+ }
641
+ const expiry = replay.expireOverdue(messageId, file, new Date().toISOString());
642
+ if (expiry.status === "absent") return RESOLVED;
643
+ if (expiry.status === "failed") {
644
+ this.logQuarantine(messageId, expiry.presentations, "deadline");
645
+ return RESOLVED;
646
+ }
647
+ }
648
+ const curPath = join(roots.mailbox, "cur", file);
649
+ let bytes: Buffer;
650
+ try {
651
+ bytes = readFileSync(curPath);
652
+ } catch (err) {
653
+ if (!isMissing(err)) throw err;
654
+ if (state.phase === "placing" && lstatOrAbsent(curPath) === null) {
655
+ replay.finishPlacement(messageId, file);
656
+ return RESOLVED;
657
+ }
658
+ return deferred("record-changed", `cur/${file} is missing for a ${state.phase} intent`, file);
659
+ }
660
+ return { status: "read", bytes, phase: state.phase };
661
+ } finally {
662
+ lock.release();
663
+ }
664
+ }
665
+
666
+ /**
667
+ * Re-read the intent, its claim, the recorded identity and the raw bytes
668
+ * under the lock (all may have changed during re-verification), then advance
669
+ * the presentation with a new claim and hand the message over. A bound hit
670
+ * writes the terminal `failed` phase and presents nothing.
671
+ */
672
+ private async presentUnderLock(
673
+ roots: OperationRoots,
674
+ messageId: string,
675
+ file: string,
676
+ bytes: Buffer,
677
+ envelope: Envelope,
678
+ trustTier: MailMessage["trustTier"],
679
+ ): Promise<PendingOutcome> {
680
+ const lock = await this.lockOrDefer(roots, "pending placement not presented", file);
681
+ if ("status" in lock) return lock;
682
+ try {
683
+ const replay = mailboxReplayStore(roots.mailbox);
684
+ const state = replay.placementState(file);
685
+ if (!state || state.messageId !== messageId || state.phase === "failed" || state.phase === "unknown") return RESOLVED;
686
+ if (state.phase === "in_progress" && claimIsLive(state.claim, state.firstPresentedAt)) {
687
+ return deferred("active", `message ${messageId} has an active claim (this module copy holds the token, or another copy/process has an unexpired claim)`, file);
688
+ }
689
+ if (!replay.ownsPendingPlacement(messageId, file)) {
690
+ return deferred("record-changed", `cur/${file} recorded identity is absent or mismatched`, file);
691
+ }
692
+ let current: Buffer;
693
+ try {
694
+ current = readFileSync(join(roots.mailbox, "cur", file));
695
+ } catch (err) {
696
+ if (isMissing(err)) return deferred("record-changed", `cur/${file} disappeared during re-verification`, file);
697
+ throw err;
698
+ }
699
+ if (!current.equals(bytes)) return deferred("record-changed", `cur/${file} changed during re-verification`, file);
700
+ if (!replay.isConsumed(messageId, file)) replay.recordConsumed(messageId);
701
+ const token = randomUUID();
702
+ const advance = replay.advancePresentation(messageId, file, new Date().toISOString(), ownClaim(token));
703
+ if (advance.status === "absent") return RESOLVED;
704
+ if (advance.status === "failed") {
705
+ this.logQuarantine(messageId, advance.presentations, "count");
706
+ return RESOLVED;
707
+ }
708
+ // Hold the token before releasing the lock so another local call defers.
709
+ activePresentations.add(token);
710
+ const message: MailMessage = {
711
+ filename: file,
712
+ body: bytes.toString("utf8"),
713
+ receivedAt: new Date(),
714
+ headers: {},
715
+ from: envelope.from,
716
+ verifiedEnvelope: envelope,
717
+ trustTier,
718
+ };
719
+ return { status: "delivered", delivery: this.issue(roots, token, messageId, file, advance.presentations, message) };
720
+ } finally {
721
+ lock.release();
722
+ }
723
+ }
724
+
725
+ /**
726
+ * The bound's log line. It is written after the durable `failed` write, so a
727
+ * kill between the two leaves the `failed` intent (the durable record) and
728
+ * no line.
729
+ */
730
+ private logQuarantine(messageId: string, presentations: number, cause: "count" | "deadline"): void {
731
+ const why = cause === "deadline"
732
+ ? `the deadline (${DELIVERY_PRESENTATION_TTL_MS / 3_600_000} h after the first presentation) passed`
733
+ : "the presentation bound was reached";
734
+ report(() => console.warn(
735
+ `[MailClient] placement quarantined for mailbox ${this.agentId}: message ${messageId} not completed ` +
736
+ `after ${presentations} presentation(s); ${why}; failure transition does not delete an existing payload`,
737
+ ));
738
+ }
739
+
740
+ /**
741
+ * Commit the next verifiable new/ message to cur/ with a live `in_progress`
742
+ * intent. Under the commit lock it re-checks that no `placing` or
743
+ * `in_progress` placement is pending, so a concurrent call cannot add a
744
+ * second message in flight.
745
+ */
746
+ private async commitNextForDelivery(roots: OperationRoots): Promise<DeliverNextResult> {
747
+ let files: string[];
748
+ try {
749
+ files = existsSync(join(roots.mailbox, "new"))
750
+ ? readdirSync(join(roots.mailbox, "new")).filter(isMailboxMessageFile).sort()
751
+ : [];
752
+ } catch (err) {
753
+ this.emitRecoveryError(err);
754
+ return deferred("storage-error", `new/ unavailable: ${sanitizeError(err)}`);
755
+ }
756
+ let skipped: { file: string; detail: string } | null = null;
757
+ for (const file of files) {
758
+ const started = Date.now();
759
+ const srcPath = join(roots.mailbox, "new", file);
760
+ let body: string;
761
+ try {
762
+ body = readFileSync(srcPath, "utf-8");
763
+ } catch (err) {
764
+ if (!isMissing(err)) {
765
+ this.emitRecoveryError(err);
766
+ skipped ??= { file, detail: `unreadable: ${sanitizeError(err)}` };
767
+ }
768
+ continue;
769
+ }
770
+ let verifyResult: VerifyOutcome;
771
+ try {
772
+ verifyResult = await this.verifyMailBody(body);
773
+ } catch (err) {
774
+ this.emitRecoveryError(err); // left in new/ for a later call
775
+ skipped ??= { file, detail: `verification could not run: ${sanitizeError(err)}` };
776
+ continue;
777
+ }
778
+ if (!verifyResult.pass) {
779
+ this.deadLetter(file, srcPath, verifyResult, started, roots);
780
+ continue;
781
+ }
782
+ let trustTier: MailMessage["trustTier"];
783
+ try {
784
+ trustTier = verifiedMailTier(verifyResult.envelope, roots.mailRoot);
785
+ } catch (err) {
786
+ this.emitRecoveryError(err);
787
+ skipped ??= { file, detail: `trust tier unavailable: ${sanitizeError(err)}` };
788
+ continue;
789
+ }
790
+ const token = randomUUID();
791
+ // Live before the commit writes the claim (see presentUnderLock).
792
+ activePresentations.add(token);
793
+ let delivered = false;
794
+ try {
795
+ const committed = await this.commitToCur(roots, file, srcPath, body, verifyResult.envelope, ownClaim(token));
796
+ if (committed === "already-delivered") continue;
797
+ if (committed === "live-placement") {
798
+ return deferred("new-mail-deferred", "a placement became pending before the commit; nothing committed", file);
799
+ }
800
+ if (committed) {
801
+ this.deadLetter(file, srcPath, { ...committed, from: verifyResult.envelope.from }, started, roots);
802
+ continue;
803
+ }
804
+ const from = verifyResult.envelope.from;
805
+ report(() => this.events?.emit({
806
+ type: "mail.receive", agent: this.agentId, status: "ok", from, durationMs: Date.now() - started,
807
+ }));
808
+ delivered = true;
809
+ const message: MailMessage = {
810
+ filename: file, body, receivedAt: new Date(), headers: {}, from,
811
+ verifiedEnvelope: verifyResult.envelope, trustTier,
812
+ };
813
+ return { status: "delivered", delivery: this.issue(roots, token, verifyResult.envelope.messageId, file, 1, message) };
814
+ } catch (err) {
815
+ this.emitRecoveryError(err);
816
+ skipped ??= { file, detail: `delivery attempt failed: ${sanitizeError(err)}` };
817
+ } finally {
818
+ if (!delivered) activePresentations.delete(token);
819
+ }
820
+ }
821
+ return skipped ? deferred("new-mail-deferred", `new/${skipped.file} ${skipped.detail}`, skipped.file) : { status: "idle" };
822
+ }
823
+
824
+ /** The mailbox lock, or a `lock-busy` deferral (contention, or an acquisition that threw). */
825
+ private async lockOrDefer(roots: OperationRoots, what: string, file?: string): Promise<MailLock | DeferredResult> {
826
+ try {
827
+ return (await acquireMailLock(roots.mailbox)) ?? deferred("lock-busy", `mailbox lock busy; ${what}`, file);
828
+ } catch (err) {
829
+ return deferred("lock-busy", `mailbox lock unavailable (${sanitizeError(err)}); ${what}`, file);
830
+ }
831
+ }
832
+
833
+ private emitRecoveryError(err: unknown): void {
834
+ report(() => this.events?.emit({
835
+ type: "mail.receive", agent: this.agentId, status: "error", from: "unknown", durationMs: 0, error: sanitizeError(err),
836
+ }));
837
+ }
838
+
839
+ /** Commit under the mailbox lock; attempt placement rollback on append failure. */
840
+ private async commitToCur(
841
+ roots: OperationRoots,
842
+ file: string,
843
+ srcPath: string,
844
+ body: string,
845
+ envelope: Envelope,
846
+ /** cli#617 slice (b): the delivery API's presentation claim; absent for the batch checkNewMail() path. */
847
+ claim?: PresentationClaim,
848
+ ): Promise<{ pass: false; class: MailboxRejectClass; reason: string } | "already-delivered" | "live-placement" | null> {
849
+ const lock: MailLock | null = await acquireMailLock(roots.mailbox);
850
+ if (!lock) throw new Error("mailbox lock busy; not promoted");
851
+ let relayLock: MailLock | null;
852
+ try { relayLock = tryAcquireRelayMoveLock(JSON.parse(body), roots.mailRoot); }
853
+ catch (error) { lock.release(); throw error; }
854
+ if (!relayLock) { lock.release(); throw new Error("relay acceptance busy; not promoted"); }
855
+ try {
856
+ if (readFileSync(srcPath, "utf-8") !== body) throw new Error("source changed during promotion; not promoted");
857
+ const replay = mailboxReplayStore(roots.mailbox);
858
+ if (replay.hasPendingFile(file)) throw new Error(`pending placement unresolved: ${file}`);
859
+ if (claim && pendingPlacementEntries(roots.mailbox).some((e) => e.phase === "placing" || e.phase === "in_progress")) {
860
+ return "live-placement";
861
+ }
862
+ const dstPath = join(roots.mailbox, "cur", file);
863
+ if (sameFileIdentity(srcPath, dstPath)) {
864
+ replay.isConsumed(envelope.messageId);
865
+ unlinkSync(srcPath);
866
+ return "already-delivered";
867
+ }
868
+ const consumed = replay.isConsumed(envelope.messageId);
869
+ if (consumed) {
870
+ return { pass: false, class: "replay", reason: `replay (envelope messageId ${envelope.messageId} already consumed)` };
871
+ }
872
+ const sourceFd = openSync(srcPath, constants.O_RDONLY | constants.O_NOFOLLOW);
873
+ try {
874
+ replay.beginPlacement(envelope.messageId, file, sourceFd);
875
+ const placement = placeCurRecord(srcPath, dstPath);
876
+ if (placement.status === "exists") {
877
+ replay.finishPlacement(envelope.messageId, file);
878
+ throw new Error(`destination already exists: ${file}`);
879
+ }
880
+ try {
881
+ unlinkSync(srcPath);
882
+ } catch (err) {
883
+ unlinkSync(dstPath);
884
+ replay.finishPlacement(envelope.messageId, file);
885
+ throw err;
886
+ }
887
+ try {
888
+ if (!replay.ownsPendingPlacement(envelope.messageId, file)) throw new Error("placement identity changed");
889
+ replay.recordConsumed(envelope.messageId);
890
+ } catch (err) {
891
+ try {
892
+ renameSync(dstPath, srcPath);
893
+ replay.finishPlacement(envelope.messageId, file);
894
+ } catch (rollbackErr) {
895
+ throw new AggregateError([err, rollbackErr],
896
+ `mail commit failed: ${sanitizeError(err)}; rollback failed: ${sanitizeError(rollbackErr)}`);
897
+ }
898
+ throw err;
899
+ }
900
+ if (claim) {
901
+ const advance = replay.advancePresentation(envelope.messageId, file, new Date().toISOString(), claim);
902
+ if (advance.status !== "presented") throw new Error(`placement not advanced after commit: ${advance.status}`);
903
+ } else {
904
+ replay.finishPlacement(envelope.messageId, file);
905
+ }
906
+ return null;
907
+ } finally { closeSync(sourceFd); }
908
+ } finally {
909
+ relayLock.release();
910
+ lock.release();
911
+ }
912
+ }
913
+
914
+ /**
915
+ * Recover verified cur copies matching the intent's recorded identity (cli#600).
916
+ * Verification or lock failure defers recovery. A present mismatched copy,
917
+ * including an older intent without identity, leaves the intent pending and
918
+ * withholds delivery; the new/ scan cannot replace that intent.
919
+ */
920
+ private async recoverInterruptedPlacements(messages: MailMessage[], roots: OperationRoots): Promise<void> {
921
+ const root = roots.mailbox;
922
+ let pending: Array<{ messageId: string; file: string; phase: PlacementPhase }>;
923
+ let listing: MailLock | null = null;
924
+ try {
925
+ listing = await acquireMailLock(root);
926
+ if (!listing) return; // lock unavailable; defer recovery
927
+ pending = pendingPlacementEntries(root);
928
+ } catch (err) {
929
+ report(() => this.events?.emit({
930
+ type: "mail.receive",
931
+ agent: this.agentId,
932
+ status: "error",
933
+ from: "unknown",
934
+ durationMs: 0,
935
+ error: sanitizeError(err),
936
+ }));
937
+ return; // a later check retries
938
+ } finally {
939
+ listing?.release();
940
+ }
941
+
942
+ for (const { messageId, file, phase } of pending) {
943
+ if (!resumableOnRecovery(phase)) continue;
944
+ const curPath = join(root, "cur", file);
945
+ try {
946
+ let bytes: Buffer;
947
+ try {
948
+ bytes = readFileSync(curPath);
949
+ } catch (err) {
950
+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
951
+ // Observed absent; re-check under the lock before finishing the intent.
952
+ await this.finishUnlinkedPlacement(messageId, file, root);
953
+ continue;
954
+ }
955
+ const classified = await this.classifyPending(bytes);
956
+ if (classified.kind === "cli") continue;
957
+ if (classified.kind === "pending-record-invalid" || classified.kind === "pending-record-ambiguous") {
958
+ await this.quarantinePending(roots, messageId, file, bytes, classified.kind);
959
+ continue;
960
+ }
961
+ const outcome = classified.outcome;
962
+ const trustTier = verifiedMailTier(outcome.envelope, roots.mailRoot);
963
+ const delivered = await this.completeInterruptedPlacement(messageId, file, root, bytes, outcome.envelope, trustTier);
964
+ if (delivered) messages.push(delivered);
965
+ } catch (err) {
966
+ report(() => this.events?.emit({
967
+ type: "mail.receive",
968
+ agent: this.agentId,
969
+ status: "error",
970
+ from: "unknown",
971
+ durationMs: 0,
972
+ error: sanitizeError(err),
973
+ }));
974
+ }
975
+ }
976
+ }
977
+
978
+ /** Finish a still-pending intent only when cur/ is absent under the lock. */
979
+ private async finishUnlinkedPlacement(messageId: string, file: string, root: string): Promise<void> {
980
+ const lock = await acquireMailLock(root);
981
+ if (!lock) return;
982
+ try {
983
+ const replay = mailboxReplayStore(root);
984
+ if (!replay.hasPendingPlacement(messageId, file)) return;
985
+ if (!resumableOnRecovery(replay.placementPhase(file))) return;
986
+ if (lstatOrAbsent(join(root, "cur", file)) !== null) return;
987
+ replay.finishPlacement(messageId, file);
988
+ } finally {
989
+ lock.release();
990
+ }
991
+ }
992
+
993
+ /**
994
+ * Re-check the intent, recorded identity and raw bytes under the lock.
995
+ */
996
+ private async completeInterruptedPlacement(
997
+ messageId: string,
998
+ file: string,
999
+ root: string,
1000
+ bytes: Buffer,
1001
+ envelope: Envelope,
1002
+ trustTier: MailMessage["trustTier"],
1003
+ ): Promise<MailMessage | null> {
1004
+ const lock = await acquireMailLock(root);
1005
+ if (!lock) throw new Error("mailbox lock busy; interrupted placement recovery deferred");
1006
+ try {
1007
+ const replay = mailboxReplayStore(root);
1008
+ // Match the intent, recorded identity and pre-verification raw bytes.
1009
+ if (!replay.hasPendingPlacement(messageId, file)) return null;
1010
+ if (!resumableOnRecovery(replay.placementPhase(file))) return null;
1011
+ if (envelope.messageId !== messageId) return null;
1012
+ if (!replay.ownsPendingPlacement(messageId, file)) return null;
1013
+ let current: Buffer;
1014
+ try {
1015
+ current = readFileSync(join(root, "cur", file));
1016
+ } catch (err) {
1017
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
1018
+ throw err;
1019
+ }
1020
+ if (!current.equals(bytes)) return null;
1021
+ if (!replay.isConsumed(messageId, file)) replay.recordConsumed(messageId);
1022
+ replay.finishPlacement(messageId, file);
1023
+ return {
1024
+ filename: file,
1025
+ body: bytes.toString("utf8"),
1026
+ receivedAt: new Date(),
1027
+ headers: {},
1028
+ from: envelope.from,
1029
+ verifiedEnvelope: envelope,
1030
+ trustTier,
1031
+ };
1032
+ } finally {
1033
+ lock.release();
1034
+ }
1035
+ }
1036
+
1037
+ /** Attempt the dlq/ move and sidecar write, then emit the rejection. */
1038
+ private deadLetter(
1039
+ file: string,
1040
+ srcPath: string,
1041
+ rejected: { class: MailboxRejectClass; reason: string; from?: string },
1042
+ started: number,
1043
+ roots: OperationRoots,
1044
+ ): void {
1045
+ const dlqDir = join(roots.mailbox, "dlq");
1046
+ const dlqPath = join(dlqDir, file);
1047
+ let relayLock: MailLock | null = null;
1048
+ try {
1049
+ let record: unknown;
1050
+ try { record = JSON.parse(readFileSync(srcPath, "utf-8")); } catch {}
1051
+ relayLock = tryAcquireRelayMoveLock(record, roots.mailRoot);
1052
+ if (!relayLock) return;
1053
+ if (srcPath !== dlqPath) renameSync(srcPath, dlqPath);
1054
+ writeRejectSidecar(dlqDir, file, rejected.class, rejected.reason);
1055
+ } catch (err) {
1056
+ report(() => console.error(`[MailClient] failed to dead-letter ${file}: ${sanitizeError(err)}`));
1057
+ } finally { relayLock?.release(); }
1058
+ report(() => this.events?.emit({
1059
+ type: "mail.receive",
1060
+ agent: this.agentId,
1061
+ status: "rejected",
1062
+ from: rejected.from ?? "unknown",
1063
+ durationMs: Date.now() - started,
1064
+ error: rejected.reason,
1065
+ }));
1066
+ }
1067
+
222
1068
  /** Write a message to outbox/new for relay delivery. */
223
1069
  async sendMail(to: string, body: string): Promise<void> {
224
1070
  const started = Date.now();
225
1071
  try {
1072
+ const { mailbox } = this.operationRoots();
226
1073
  const { writeFileSync } = await import("node:fs");
1074
+ // Sign the body as this agent — the v1 envelope a promote() reader
1075
+ // verifies. signMailBody THROWS when no key exists, so an unsigned body
1076
+ // is never written.
1077
+ const signed = this.signMailBody(to, body);
227
1078
  const filename = `${Date.now()}-${Math.random().toString(36).slice(2)}.json`;
228
1079
  writeFileSync(
229
- join(this.outboxNew, filename),
230
- JSON.stringify({ to, body, sentAt: new Date().toISOString() }, null, 2),
1080
+ join(mailbox, "outbox", filename),
1081
+ JSON.stringify({ from: this.agentId, to, body: signed, sentAt: new Date().toISOString() }, null, 2),
231
1082
  "utf-8"
232
1083
  );
233
- this.events?.emit({
1084
+ report(() => this.events?.emit({
234
1085
  type: "mail.send",
235
1086
  agent: this.agentId,
236
1087
  to,
237
1088
  status: "ok",
238
1089
  durationMs: Date.now() - started,
239
- });
1090
+ }));
240
1091
  } catch (err) {
241
- this.events?.emit({
1092
+ report(() => this.events?.emit({
242
1093
  type: "mail.send",
243
1094
  agent: this.agentId,
244
1095
  to,
245
1096
  status: "error",
246
1097
  durationMs: Date.now() - started,
247
1098
  error: sanitizeError(err),
248
- });
1099
+ }));
249
1100
  throw err;
250
1101
  }
251
1102
  }
252
1103
 
1104
+ /**
1105
+ * Sign `body` as this agent into a v1 signed envelope. Throws a named error
1106
+ * when no signing key exists — the same refusal condition as the CLI path,
1107
+ * so an unsigned body a promote() reader would dead-letter is never written.
1108
+ */
1109
+ private signMailBody(to: string, body: string): string {
1110
+ const seed = readAgentPrivateKey(this.agentId, this.signingKeyPath);
1111
+ if (!seed) {
1112
+ const paths = this.signingKeyPath ? [this.signingKeyPath] : agentKeyCandidates(this.agentId);
1113
+ throw new Error(`no Ed25519 private key for agent "${this.agentId}" — refusing to send unsigned mail. Looked at ${paths.join(", then ")}. Provision the agent's key.`);
1114
+ }
1115
+ const now = new Date().toISOString();
1116
+ const chain: ChainEntry[] = [
1117
+ { agent: "system", kind: "human", timestamp: now, rationale: "agent runtime sendMail", signature: null },
1118
+ { agent: this.agentId, kind: "agent", timestamp: now, rationale: `agent ${this.agentId} sendMail`, signature: null },
1119
+ ];
1120
+ const envelope: Envelope = {
1121
+ v: 1,
1122
+ from: this.agentId,
1123
+ to,
1124
+ subject: `mail to ${to}`,
1125
+ body,
1126
+ messageId: randomUUID(),
1127
+ timestamp: now,
1128
+ delegationChain: chain,
1129
+ };
1130
+ return JSON.stringify(signEnvelope(envelope, { [this.agentId]: Buffer.from(seed) }));
1131
+ }
1132
+
253
1133
  /** Deliver all messages in outbox to recipient inboxes (local relay). */
254
1134
  deliverOutbox(): void {
255
- if (!existsSync(this.outboxNew)) return;
256
- const files = readdirSync(this.outboxNew).filter(f => !f.startsWith("."));
1135
+ const roots = this.operationRoots();
1136
+ const outboxNew = join(roots.mailbox, "outbox");
1137
+ if (!existsSync(outboxNew)) return;
1138
+ const files = readdirSync(outboxNew).filter(f => !f.startsWith("."));
257
1139
  for (const file of files) {
258
- const srcPath = join(this.outboxNew, file);
1140
+ const srcPath = join(outboxNew, file);
259
1141
  try {
260
1142
  const raw = readFileSync(srcPath, "utf-8");
261
1143
  const msg = JSON.parse(raw) as { to: string; body: string; sentAt: string };
262
1144
  if (!msg.to || !/^[a-zA-Z0-9_-]{1,64}$/.test(msg.to)) {
263
1145
  continue; // skip invalid recipients
264
1146
  }
265
- const recipientInbox = join(this.mailDir, msg.to, "new");
1147
+ const recipientInbox = join(roots.mailRoot, msg.to, "new");
266
1148
  mkdirSync(recipientInbox, { recursive: true });
267
1149
  const destFile = `${msg.sentAt.replace(/[:.]/g, "-")}-${file}`;
268
1150
  renameSync(srcPath, join(recipientInbox, destFile));
@@ -273,108 +1155,33 @@ export class MailClient {
273
1155
  }
274
1156
 
275
1157
  /**
276
- * Verify a mail body against the v1 signed envelope spec AND this mailbox's
277
- * policy: signature, wrapper→envelope `from` binding, recipient binding
278
- * (`envelope.to` must be this mailbox's agent), and `messageId`/`timestamp`
279
- * shape. These are the checks the shared `promote()` applies, so this path
280
- * cannot present mail the shared path would reject.
281
- *
1158
+ * Parse a mail file and run the shared mailbox policy on its signed envelope.
282
1159
  * Returns a terminal `{ pass: false, class, reason }` on a deterministic
283
- * rejection. Called ONLY when a verifier is configured; a THROW (Flair
284
- * unreachable) is a refusal the caller acts on, never a pass.
1160
+ * rejection; a THROW (Flair unreachable) is a refusal the caller acts on,
1161
+ * never a pass.
285
1162
  */
286
1163
  private async verifyMailBody(body: string): Promise<VerifyOutcome> {
287
- const client = this.flairClient!;
288
-
289
- // 1. Parse the mail file as JSON
290
1164
  let mailMsg: { from?: string; body: string };
291
1165
  try {
292
1166
  mailMsg = JSON.parse(body);
1167
+ if (mailMsg === null || typeof mailMsg !== "object" || Array.isArray(mailMsg) || typeof mailMsg.body !== "string") {
1168
+ return { pass: false, class: "invalid", reason: "invalid raw mail wrapper" };
1169
+ }
293
1170
  } catch {
294
1171
  return { pass: false, class: "invalid", reason: "json parse error: invalid JSON" };
295
1172
  }
296
1173
 
297
- if (!mailMsg.body || typeof mailMsg.body !== "string") {
298
- return { pass: false, class: "invalid", reason: "json parse error: missing body field" };
299
- }
300
-
301
- // 2. Parse the body field as an envelope
302
- let envelope: unknown;
303
- try {
304
- envelope = JSON.parse(mailMsg.body);
305
- } catch {
306
- return { pass: false, class: "invalid", reason: "json parse error: invalid envelope body", from: mailMsg.from };
307
- }
308
-
309
- if (envelope == null || typeof envelope !== "object" || Array.isArray(envelope)) {
310
- return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
311
- }
312
-
313
- const env = envelope as Record<string, unknown>;
314
- if (
315
- typeof env.v !== "number" ||
316
- !Array.isArray(env.delegationChain) ||
317
- typeof env.signature !== "string"
318
- ) {
319
- return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
320
- }
321
-
322
- // 3. Verify the signature. A THROW here (Flair unreachable) is NOT a pass —
323
- // it propagates to checkNewMail(), which refuses to promote and leaves
324
- // the record in new/ for a later check. The verifier adapter throws on an
325
- // outage, so an outage is RETRYABLE rather than a terminal "not found".
326
- const vr = await verifyEnvelope(env as any, client);
327
- if (!vr.ok) {
328
- const cls: MailboxRejectClass = UNRESOLVABLE_PRINCIPAL_REASON_RE.test(vr.reason)
329
- ? "unresolvable-principal"
330
- : "invalid";
331
- return { pass: false, class: cls, reason: vr.reason, from: mailMsg.from };
332
- }
1174
+ const parsed = parseSignedEnvelope(mailMsg.body);
1175
+ if (!parsed.ok) return { pass: false, class: parsed.class, reason: parsed.reason, from: mailMsg.from };
333
1176
 
334
- // 4. The wrapper `from` is what consumers route by, and it is unverified; a
335
- // wrapper/envelope mismatch is itself a reject.
336
- if (mailMsg.from !== env.from) {
337
- return {
338
- pass: false,
339
- class: "invalid",
340
- reason: `wrapper/envelope from mismatch (wrapper.from=${String(mailMsg.from)}, envelope.from=${String(env.from)})`,
341
- from: mailMsg.from,
342
- };
343
- }
344
-
345
- // 5. Recipient binding. A signature is NOT recipient-bound, so a correctly
346
- // signed envelope addressed to another principal must not be presented
347
- // here (deliverOutbox writes into any recipient's new/).
348
- if (env.to !== this.agentId) {
349
- return {
350
- pass: false,
351
- class: "wrong-recipient",
352
- reason: `wrong-recipient (envelope.to=${String(env.to)}, mailbox=${this.agentId})`,
353
- from: mailMsg.from,
354
- };
355
- }
356
-
357
- // 6. `messageId` shape.
358
- if (typeof env.messageId !== "string" || env.messageId.trim() === "") {
359
- return {
360
- pass: false,
361
- class: "invalid",
362
- reason: `invalid messageId (must be a non-empty string, got ${JSON.stringify(env.messageId)})`,
363
- from: mailMsg.from,
364
- };
365
- }
366
-
367
- // 7. `timestamp` shape — a malformed/absent timestamp must not be silently
368
- // accepted (the shared path rejects it too).
369
- if (typeof env.timestamp !== "string" || Number.isNaN(Date.parse(env.timestamp))) {
370
- return {
371
- pass: false,
372
- class: "invalid",
373
- reason: `invalid timestamp (must be an ISO-8601 string, got ${JSON.stringify(env.timestamp)})`,
374
- from: mailMsg.from,
375
- };
376
- }
377
-
378
- return { pass: true };
1177
+ const decision = await decideEnvelopeForMailbox(this.agentId, parsed.envelope, mailMsg.from, this.flairClient)
1178
+ .catch((err: unknown) => {
1179
+ if (err instanceof PublicKeyFormatError) {
1180
+ return { ok: false as const, class: "invalid" as const, reason: `signature verification failed: ${err.message}` };
1181
+ }
1182
+ throw err;
1183
+ });
1184
+ if (!decision.ok) return { pass: false, class: decision.class, reason: decision.reason, from: mailMsg.from };
1185
+ return { pass: true, envelope: decision.envelope };
379
1186
  }
380
1187
  }