@aitne/daemon 0.1.7 → 0.1.9

package/dist/messaging/final-confirm-system-message-sender.js

@@ -0,0 +1,165 @@
+/**
+ * Lite-final-confirm DM dispatcher — BROWSER_TASK_REDESIGN_PLAN.md §5 / §14.11.
+ *
+ * Parallel to `purchase-system-message-sender.ts` (B-4 purchase
+ * confirmations). The two coexist because:
+ *
+ *  - B-4 dispatches "Aitne purchase confirmation" templates gated by a
+ *    per-site config + amount + currency.
+ *  - The lite path dispatches a narrower "Aitne confirmation required"
+ *    template for any irreversible action the browser-task sub-agent
+ *    flagged via the final-confirm gate — no purchase amount, no
+ *    currency, no per-site B-4 config.
+ *
+ * Both share the `!~xxxxxxxx` envelope so the messaging adapter's
+ * inbound jti-prefix dispatcher (§14.11 Q#6) can route a single reply
+ * to whichever store holds the matching token. The DM header text
+ * intentionally differs ("Aitne confirmation required" vs "Aitne
+ * purchase confirmation") so the outbound purchase-guard's marker set
+ * does not falsely flag the lite path, and so the user can tell the two
+ * apart at a glance.
+ *
+ * Structural anti-spoofing mirrors B-4: every exported method asserts
+ * the unforgeable capability symbol minted in `final-confirm-handler.ts`
+ * — an agent tool that somehow obtains a reference to this sender still
+ * cannot mint the symbol and the dispatch throws.
+ */
+import { createLogger } from "../logging.js";
+import { MessageDeliveryError, } from "../adapters/message-hub.js";
+import { resolveScreenshotAttachment, } from "./browser-task-screenshot-attachment.js";
+import { parseChannelRef } from "../db/browser-automation-purchase-primary-channels-store.js";
+import { __aitneFinalConfirm_getCapability, } from "../services/browser-history/automation/final-confirm-handler.js";
+import { redactToken } from "../services/browser-history/automation/lite-final-confirm-tokens.js";
+const logger = createLogger("final-confirm-system-message-sender");
+/** Header marker line distinct from B-4's `PURCHASE_CONFIRMATION_HEADER`
+ *  so the agent-facing outbound guard's deny-list cannot collide. */
+export const FINAL_CONFIRM_REQUEST_HEADER = "Aitne confirmation required";
+function formatExpiry(expiresAtMs, nowMs) {
+    const remainingMs = Math.max(0, expiresAtMs - nowMs);
+    const minutes = Math.floor(remainingMs / 60000);
+    const seconds = Math.floor((remainingMs % 60000) / 1000);
+    return `${minutes}m ${seconds.toString().padStart(2, "0")}s`;
+}
+export function createFinalConfirmSystemMessageSender(deps) {
+    const expected = __aitneFinalConfirm_getCapability();
+    const now = deps.nowFn ?? (() => Date.now());
+    const paDataDir = deps.paDataDir ?? null;
+    function assertCapability(received) {
+        if (received !== expected) {
+            throw new Error("final-confirm-system-message-sender: capability mismatch — refusing dispatch");
+        }
+    }
+    // The pre-confirm screenshot is delivered as actual image bytes — native
+    // upload for messaging adapters, AttachmentStore ingest for the dashboard —
+    // never a loopback trace URL (a phone cannot reach it; a raw dashboard
+    // <img> cannot authenticate it). See `browser-task-screenshot-attachment`.
+    async function dispatch(ref, text, screenshotKey) {
+        const parsed = parseChannelRef(ref);
+        if (!parsed)
+            return { ok: false, reason: "invalid_ref" };
+        let attachments;
+        if (screenshotKey) {
+            const att = await resolveScreenshotAttachment({
+                platform: parsed.platform,
+                key: screenshotKey,
+                paDataDir,
+                ingestOutboundImage: deps.ingestOutboundImage,
+            });
+            if (att)
+                attachments = [att];
+        }
+        try {
+            await deps.messageHub.sendToPlatform(parsed.platform, parsed.channelId, text, undefined, attachments);
+            return { ok: true };
+        }
+        catch (err) {
+            const reason = err instanceof MessageDeliveryError
+                ? err.message
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            logger.warn({ ref, reason }, "lite-final-confirm system DM dispatch failed");
+            return { ok: false, reason };
+        }
+    }
+    return {
+        async deliverConfirmRequest(capability, input) {
+            assertCapability(capability);
+            const lines = [
+                `🔐 ${FINAL_CONFIRM_REQUEST_HEADER}`,
+                `Task: ${input.taskId}`,
+                `Action: ${input.actionSummary}`,
+                `Expires in ${formatExpiry(input.expiresAt, now())} — reply with the exact token below to confirm.`,
+                ``,
+                input.token,
+                ``,
+                `jti=${input.jti}`,
+            ].join("\n");
+            const screenshotKey = input.preScreenshotPath || undefined;
+            const delivered = [];
+            const failed = [];
+            for (const ref of input.channels) {
+                const result = await dispatch(ref, lines, screenshotKey);
+                if (result.ok)
+                    delivered.push(ref);
+                else
+                    failed.push(ref);
+            }
+            logger.info({
+                jti: input.jti,
+                taskId: input.taskId,
+                tokenRedacted: redactToken(input.token),
+                deliveredCount: delivered.length,
+                failedCount: failed.length,
+            }, "lite-final-confirm request DM dispatched");
+            return { delivered, failed };
+        },
+        async deliverPostConsumeFollowup(capability, input) {
+            assertCapability(capability);
+            const consumedMsg = `✅ Confirmed. Aitne is proceeding with the action now. jti=${input.jti}`;
+            const otherMsg = (consumedOn) => `✅ Confirmed on ${consumedOn} at ${new Date(now()).toISOString()}. No action needed here. jti=${input.jti}`;
+            for (const ref of input.deliveredChannels) {
+                const text = ref === input.consumedChannel
+                    ? consumedMsg
+                    : otherMsg(input.consumedChannel);
+                const result = await dispatch(ref, text);
+                if (!result.ok) {
+                    logger.warn({ jti: input.jti, ref, reason: result.reason }, "lite-final-confirm post-consume follow-up dispatch failed (continuing)");
+                }
+            }
+        },
+        async deliverCancellationFollowup(capability, input) {
+            assertCapability(capability);
+            const text = `⚠️ Confirmation cancelled (${describeLiteFinalConfirmCancelReason(input.reason)}). The pending action was NOT taken. jti=${input.jti}`;
+            for (const ref of input.deliveredChannels) {
+                const result = await dispatch(ref, text);
+                if (!result.ok) {
+                    logger.warn({ jti: input.jti, ref, reason: result.reason }, "lite-final-confirm cancellation follow-up dispatch failed (continuing)");
+                }
+            }
+        },
+    };
+}
+/**
+ * Human-readable cancel-reason renderer for the lite path. Mirrors
+ * `describeCancelReason` in `purchase-system-message-sender.ts` so the
+ * user sees consistent vocabulary across both surfaces.
+ */
+export function describeLiteFinalConfirmCancelReason(reason) {
+    switch (reason) {
+        case "user_reply":
+            return "you replied with non-token content";
+        case "wrong_token":
+            return "the token did not match";
+        case "wrong_channel":
+            return "the token was typed on a non-delivered channel";
+        case "timeout":
+            return "the 5-minute confirmation window elapsed";
+        case "explicit":
+            return "you issued an explicit cancel";
+        case "task_cancelled":
+            return "the parent task was cancelled or completed";
+        case "dashboard_cancel":
+            return "you clicked Cancel in the dashboard";
+    }
+}

package/dist/messaging/magic-phrase.d.ts

@@ -13,4 +13,19 @@ export declare function generateMagicPhrase(): string;
  * single message and brute-force the 24-bit search space in seconds.
  */
 export declare function buildPhraseMatcher(phrase: string): (text: string) => boolean;
-//# sourceMappingURL=magic-phrase.d.ts.map
+/**
+ * P2-23 — distinguish "wrong phrase" from "right phrase wrapped in extra
+ * text" so the operator gets a recoverable hint instead of silence. A
+ * legitimate user who types `"my phrase is apple-banana-cherry-date"`
+ * looks identical to an attacker submitting a random wrong phrase under
+ * the equality matcher — both fail; both get no response. This helper
+ * lets the adapter detect the wrapping case and reply with "Send the
+ * phrase by itself, no other text."
+ *
+ * The substring check leaks no secret: an attacker who could already
+ * generate a candidate containing the phrase wouldn't need this hint;
+ * they'd just submit the phrase alone. The length guard (`> 1.5×`)
+ * prevents probing — only meaningfully-wrapped inputs trigger the
+ * hint, not "phrase + one extra letter" fuzzing attempts.
+ */
+export declare function isPhraseWrappedInExtraText(phrase: string, candidate: string): boolean;

package/dist/messaging/magic-phrase.js

@@ -53,11 +53,16 @@ const WORDS = [
     "rain", "snow", "wind", "fire",
     "wave", "hill", "rock", "dust",
 ];
+// Compile-time-ish guard: if anyone edits the word list and breaks the
+// entropy assumption above, we want to know immediately at startup. The
+// body is unreachable from tests by design — the runtime invariant is
+// the point — so mark the throw as ignored for v8 coverage rather than
+// constructing a fake-import test that doesn't add signal.
+/* c8 ignore start */
 if (WORDS.length !== 64) {
-    // Compile-time-ish guard: if anyone edits the word list and breaks the
-    // entropy assumption above, we want to know immediately at startup.
     throw new Error(`magic-phrase word list must contain exactly 64 entries (got ${WORDS.length})`);
 }
+/* c8 ignore stop */
 const PHRASE_WORD_COUNT = 4;
 /**
  * Generate a random `apple-banana-cherry-date`-style phrase. Uses
@@ -76,6 +81,31 @@ export function generateMagicPhrase() {
  * the equality check so casing/punctuation/emoji in the inbound text
  * don't break a match — but the user must still send only the phrase,
  * not a sentence containing it.
+ *
+ * ASCII-only by design — the filter `[^a-z0-9]` deletes anything outside
+ * the basic Latin alphanumeric range. This has three security-relevant
+ * consequences worth documenting (pinned by `magic-phrase.test.ts` so
+ * any future regex change has to flip a test deliberately):
+ *
+ *   1. Homoglyph attacks REJECT. A Cyrillic `а` (U+0430) or Greek `α`
+ *      (U+03B1) substituted for ASCII `a` is fully deleted (not
+ *      transliterated), shrinking the normalized candidate's length
+ *      below the expected, and `timingSafeEqual` short-circuits.
+ *   2. Fullwidth / typographic look-alikes REJECT for the same reason —
+ *      `ａｐｐｌｅ` (U+FF41..) does not survive the filter.
+ *   3. Diacritics behave **asymmetrically** depending on Unicode form:
+ *      - **NFC** precomposed (e.g. `á` = U+00E1) is dropped wholesale →
+ *        normalized candidate is shorter → REJECTS.
+ *      - **NFD** decomposed (e.g. `a` + U+0301 combining acute) keeps
+ *        the base `a` and drops only the combining mark → normalized
+ *        candidate equals the expected → MATCHES.
+ *      This asymmetry is acceptable security-wise (both candidates need
+ *      exactly the right 16 ASCII letters/digits to match equality), but
+ *      surfaces in pairing UX: a user whose keyboard / clipboard emits
+ *      NFD will match through accented intermediates, NFC will not. Do
+ *      not "fix" this by normalizing input through `.normalize("NFD")` —
+ *      it would let homoglyph payloads survive if any future variant
+ *      decomposed to an ASCII base.
  */
 function normalize(input) {
     return input.toLowerCase().replace(/[^a-z0-9]/g, "");
@@ -100,4 +130,31 @@ export function buildPhraseMatcher(phrase) {
         return timingSafeEqual(candidate, expectedBuf);
     };
 }
-//# sourceMappingURL=magic-phrase.js.map
+/**
+ * P2-23 — distinguish "wrong phrase" from "right phrase wrapped in extra
+ * text" so the operator gets a recoverable hint instead of silence. A
+ * legitimate user who types `"my phrase is apple-banana-cherry-date"`
+ * looks identical to an attacker submitting a random wrong phrase under
+ * the equality matcher — both fail; both get no response. This helper
+ * lets the adapter detect the wrapping case and reply with "Send the
+ * phrase by itself, no other text."
+ *
+ * The substring check leaks no secret: an attacker who could already
+ * generate a candidate containing the phrase wouldn't need this hint;
+ * they'd just submit the phrase alone. The length guard (`> 1.5×`)
+ * prevents probing — only meaningfully-wrapped inputs trigger the
+ * hint, not "phrase + one extra letter" fuzzing attempts.
+ */
+export function isPhraseWrappedInExtraText(phrase, candidate) {
+    const expected = normalize(phrase);
+    const normalised = normalize(candidate);
+    if (!expected || !normalised)
+        return false;
+    // Equality case is handled by the matcher; only flag genuinely wrapped
+    // submissions. 1.5× is small enough that "phrase plus a stray emoji"
+    // still triggers the hint and large enough that random 16-char strings
+    // of the same length don't accidentally substring-match.
+    if (normalised.length <= Math.ceil(expected.length * 1.5))
+        return false;
+    return normalised.includes(expected);
+}

package/dist/messaging/owner-channels.d.ts

@@ -16,5 +16,44 @@ export declare function upsertOwnerChannel(db: Database.Database, params: {
     touchOutbound?: boolean;
 }): void;
 export declare function getOwnerChannel(db: Database.Database, platform: string): OwnerChannelRecord | null;
+/**
+ * Pick the "earliest-paired" platform from a set of currently-eligible
+ * candidates. Used by the boot-time primary-platform auto-resolver to
+ * honor the user's "first set up" intent when several messaging adapters
+ * are configured at once (rare in practice but spelled out in the spec).
+ *
+ * Why `rowid`: `owner_channels.platform` is a TEXT primary key, so each
+ * row carries an implicit autoincrementing `rowid` that captures
+ * insertion order. The first row inserted per platform comes from the
+ * first inbound owner DM (`upsertOwnerChannel` from
+ * dispatcher-message-handler.ts), which is the cleanest signal of "this
+ * platform completed setup and is usable". `ON CONFLICT(platform) DO
+ * UPDATE` preserves the original rowid across re-pairs, so the ordering
+ * stays stable.
+ *
+ * Behavior:
+ *  - `eligible` empty → null (caller treats as no-fallback)
+ *  - single eligible → return it
+ *  - multiple eligible → return the earliest-paired one
+ *  - multiple eligible but none have an `owner_channels` row (env-var
+ *    owner-id setup without ever DM'ing the bot) → return `eligible[0]`,
+ *    which preserves the canonical-order tie-break
+ */
+export declare function selectFirstPairedPlatform(db: Database.Database, eligible: readonly string[]): string | null;
+/**
+ * Resolve the owner's most-recently-active DM channel as
+ * `{ platform, channelId }`, or null when no owner channel is paired.
+ *
+ * Used by the browser-task originating-channel resolver as a fallback when
+ * no B-4 primary channel is registered (the common case — B-4 is opt-in /
+ * default-off): the sub-agent's `ask_user` / `finish` DMs then land on
+ * whichever channel the owner last messaged from — in practice the channel
+ * that triggered the task, since the triggering inbound DM stamps
+ * `last_inbound_at`. Ordering: most recent inbound, then most recent
+ * outbound, then earliest-paired (`rowid`) as a stable tiebreak.
+ */
+export declare function selectDefaultOwnerChannel(db: Database.Database): {
+    platform: string;
+    channelId: string;
+} | null;
 export {};
-//# sourceMappingURL=owner-channels.d.ts.map

package/dist/messaging/owner-channels.js

@@ -38,4 +38,62 @@ export function getOwnerChannel(db, platform) {
         .get(platform);
     return row ?? null;
 }
-//# sourceMappingURL=owner-channels.js.map
+/**
+ * Pick the "earliest-paired" platform from a set of currently-eligible
+ * candidates. Used by the boot-time primary-platform auto-resolver to
+ * honor the user's "first set up" intent when several messaging adapters
+ * are configured at once (rare in practice but spelled out in the spec).
+ *
+ * Why `rowid`: `owner_channels.platform` is a TEXT primary key, so each
+ * row carries an implicit autoincrementing `rowid` that captures
+ * insertion order. The first row inserted per platform comes from the
+ * first inbound owner DM (`upsertOwnerChannel` from
+ * dispatcher-message-handler.ts), which is the cleanest signal of "this
+ * platform completed setup and is usable". `ON CONFLICT(platform) DO
+ * UPDATE` preserves the original rowid across re-pairs, so the ordering
+ * stays stable.
+ *
+ * Behavior:
+ *  - `eligible` empty → null (caller treats as no-fallback)
+ *  - single eligible → return it
+ *  - multiple eligible → return the earliest-paired one
+ *  - multiple eligible but none have an `owner_channels` row (env-var
+ *    owner-id setup without ever DM'ing the bot) → return `eligible[0]`,
+ *    which preserves the canonical-order tie-break
+ */
+export function selectFirstPairedPlatform(db, eligible) {
+    if (eligible.length === 0)
+        return null;
+    if (eligible.length === 1)
+        return eligible[0];
+    const eligibleSet = new Set(eligible);
+    const rows = db
+        .prepare("SELECT platform FROM owner_channels ORDER BY rowid ASC")
+        .all();
+    for (const { platform } of rows) {
+        if (eligibleSet.has(platform))
+            return platform;
+    }
+    return eligible[0];
+}
+/**
+ * Resolve the owner's most-recently-active DM channel as
+ * `{ platform, channelId }`, or null when no owner channel is paired.
+ *
+ * Used by the browser-task originating-channel resolver as a fallback when
+ * no B-4 primary channel is registered (the common case — B-4 is opt-in /
+ * default-off): the sub-agent's `ask_user` / `finish` DMs then land on
+ * whichever channel the owner last messaged from — in practice the channel
+ * that triggered the task, since the triggering inbound DM stamps
+ * `last_inbound_at`. Ordering: most recent inbound, then most recent
+ * outbound, then earliest-paired (`rowid`) as a stable tiebreak.
+ */
+export function selectDefaultOwnerChannel(db) {
+    const row = db
+        .prepare(`SELECT platform, channel_id
+         FROM owner_channels
+        ORDER BY COALESCE(last_inbound_at, last_outbound_at, '') DESC, rowid ASC
+        LIMIT 1`)
+        .get();
+    return row ? { platform: row.platform, channelId: row.channel_id } : null;
+}

package/dist/messaging/purchase-system-message-sender.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Phase B-4 purchase-confirmation DM dispatcher.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.3 / §17.7 / §13 step 52.
+ *
+ * This module is the "sendSystemMessage" surface §17.7 specifies. The
+ * agent cannot reach it: every exported method requires the unforgeable
+ * capability symbol minted in `purchase-handler.ts`. The daemon
+ * bootstrap path acquires the symbol via the dedicated getter and
+ * passes it into both the handler and this sender; no other code path
+ * can mint it.
+ *
+ * The classifier `classifyPurchaseConfirmationTemplate` defends the
+ * other direction: any agent-tool-originated outbound message
+ * containing the reserved structural markers ("Aitne purchase
+ * confirmation", "[purchase-verify:", "Approved on …") is refused by
+ * the agent-facing outbound chokepoint
+ * (`safety/outbound-purchase-guard.ts`). Together, the two halves
+ * close the structural-anti-spoofing surface.
+ */
+import { type MessageHub } from "../adapters/message-hub.js";
+import { type IngestOutboundImage } from "./browser-task-screenshot-attachment.js";
+import { type PurchaseSystemMessageSender } from "../services/browser-history/automation/purchase-handler.js";
+import type { PurchaseCancelReason } from "../db/browser-automation-purchase-tokens-store.js";
+export interface CreatePurchaseSenderDeps {
+    messageHub: MessageHub;
+    /** Daemon data directory (`PA_DATA_DIR`). Resolves the pre-confirm
+     *  screenshot key to its on-disk trace file so the bytes are attached
+     *  inline (messaging native upload / dashboard ingest) rather than sent
+     *  as a loopback URL the user cannot reach. */
+    paDataDir?: string;
+    /** Ingest hook for the `dashboard` platform — see
+     *  `browser-task-screenshot-attachment.ts`. */
+    ingestOutboundImage?: IngestOutboundImage;
+    /** Override for tests; production uses Date.now. */
+    nowFn?: () => number;
+}
+/**
+ * Construct the credentialed sender. The factory grabs the capability
+ * via the private getter — there's no other way to obtain one, which is
+ * what makes the surface "module-level credential" §17.7 requires.
+ *
+ * Every method asserts the incoming `capability` matches the module's
+ * minted symbol. A mismatched / forged capability throws; the throw is
+ * the structural enforcement of "agent tools cannot mint this".
+ */
+export declare function createPurchaseSystemMessageSender(deps: CreatePurchaseSenderDeps): PurchaseSystemMessageSender;
+/**
+ * Convenience helper for the cancellation follow-up's audit message —
+ * exported so other daemon-internal cancel paths (the supervisor's
+ * orphan sweep, the dashboard's "cancel pending" action) format the
+ * cancel reason identically. Pure — no I/O.
+ */
+export declare function describeCancelReason(reason: PurchaseCancelReason): string;

package/dist/messaging/purchase-system-message-sender.js

@@ -0,0 +1,213 @@
+/**
+ * Phase B-4 purchase-confirmation DM dispatcher.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.3 / §17.7 / §13 step 52.
+ *
+ * This module is the "sendSystemMessage" surface §17.7 specifies. The
+ * agent cannot reach it: every exported method requires the unforgeable
+ * capability symbol minted in `purchase-handler.ts`. The daemon
+ * bootstrap path acquires the symbol via the dedicated getter and
+ * passes it into both the handler and this sender; no other code path
+ * can mint it.
+ *
+ * The classifier `classifyPurchaseConfirmationTemplate` defends the
+ * other direction: any agent-tool-originated outbound message
+ * containing the reserved structural markers ("Aitne purchase
+ * confirmation", "[purchase-verify:", "Approved on …") is refused by
+ * the agent-facing outbound chokepoint
+ * (`safety/outbound-purchase-guard.ts`). Together, the two halves
+ * close the structural-anti-spoofing surface.
+ */
+import { createLogger } from "../logging.js";
+import { MessageDeliveryError, } from "../adapters/message-hub.js";
+import { resolveScreenshotAttachment, } from "./browser-task-screenshot-attachment.js";
+import { parseChannelRef, } from "../db/browser-automation-purchase-primary-channels-store.js";
+import { __aitneB4_getPurchaseHandlerCapability, } from "../services/browser-history/automation/purchase-handler.js";
+import { PURCHASE_CONFIRMATION_HEADER, redactToken, } from "../services/browser-history/automation/purchase-tokens.js";
+const logger = createLogger("purchase-system-message-sender");
+/** ISO-4217 currencies with 0 decimal places (subset; mirrors the
+ *  purchase-handler's formatter). */
+const ZERO_DECIMAL_CURRENCIES = new Set([
+    "JPY", "KRW", "VND", "CLP", "ISK", "PYG", "RWF", "UGX",
+    "BIF", "DJF", "GNF", "KMF", "MGA", "XAF", "XOF", "XPF",
+]);
+function formatAmount(amountMinor, currency) {
+    const code = currency.toUpperCase();
+    const zeroDecimal = ZERO_DECIMAL_CURRENCIES.has(code);
+    const major = zeroDecimal
+        ? amountMinor.toLocaleString("en-US")
+        : (amountMinor / 100).toLocaleString("en-US", {
+            minimumFractionDigits: 2,
+            maximumFractionDigits: 2,
+        });
+    return code === "JPY" ? `¥${major}` : `${code} ${major}`;
+}
+function formatExpiry(expiresAtMs, nowMs) {
+    const remainingMs = Math.max(0, expiresAtMs - nowMs);
+    const minutes = Math.floor(remainingMs / 60000);
+    const seconds = Math.floor((remainingMs % 60000) / 1000);
+    return `${minutes}m ${seconds.toString().padStart(2, "0")}s`;
+}
+/**
+ * Construct the credentialed sender. The factory grabs the capability
+ * via the private getter — there's no other way to obtain one, which is
+ * what makes the surface "module-level credential" §17.7 requires.
+ *
+ * Every method asserts the incoming `capability` matches the module's
+ * minted symbol. A mismatched / forged capability throws; the throw is
+ * the structural enforcement of "agent tools cannot mint this".
+ */
+export function createPurchaseSystemMessageSender(deps) {
+    const expected = __aitneB4_getPurchaseHandlerCapability();
+    const now = deps.nowFn ?? (() => Date.now());
+    const paDataDir = deps.paDataDir ?? null;
+    function assertCapability(received) {
+        if (received !== expected) {
+            throw new Error("purchase-system-message-sender: capability mismatch — refusing dispatch");
+        }
+    }
+    // The pre-confirm screenshot is delivered as actual image bytes — native
+    // upload for messaging adapters, AttachmentStore ingest for the dashboard —
+    // never a loopback trace URL (a phone cannot reach it; a raw dashboard
+    // <img> cannot authenticate it). See `browser-task-screenshot-attachment`.
+    async function dispatch(ref, text, screenshotKey) {
+        const parsed = parseChannelRef(ref);
+        if (!parsed) {
+            return { ok: false, reason: "invalid_ref" };
+        }
+        let attachments;
+        if (screenshotKey) {
+            const att = await resolveScreenshotAttachment({
+                platform: parsed.platform,
+                key: screenshotKey,
+                paDataDir,
+                ingestOutboundImage: deps.ingestOutboundImage,
+            });
+            if (att)
+                attachments = [att];
+        }
+        try {
+            await deps.messageHub.sendToPlatform(parsed.platform, parsed.channelId, text, undefined, attachments);
+            return { ok: true };
+        }
+        catch (err) {
+            const reason = err instanceof MessageDeliveryError
+                ? err.message
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            logger.warn({ ref, reason }, "B-4 system DM dispatch failed");
+            return { ok: false, reason };
+        }
+    }
+    return {
+        async deliverPurchaseRequest(capability, input) {
+            assertCapability(capability);
+            const headerLine = `🔐 ${PURCHASE_CONFIRMATION_HEADER}`;
+            const lines = [
+                headerLine,
+                `Site: ${input.siteKey}`,
+                `Total: ${formatAmount(input.displayedTotalMinor, input.currency)}`,
+                input.notesForUser
+                    ? `Agent's rationale: ${input.notesForUser}`
+                    : null,
+                `Expires in ${formatExpiry(input.expiresAt, now())} — reply with the exact token below to confirm.`,
+                ``,
+                input.token,
+                ``,
+                `[purchase-verify: !verify ${input.token.slice(2)}] · [cancel: !cancel-purchase] · jti=${input.jti}`,
+            ]
+                .filter((s) => s !== null)
+                .join("\n");
+            const screenshotKey = input.preScreenshotPath || undefined;
+            const delivered = [];
+            const failed = [];
+            for (const ref of input.channels) {
+                const result = await dispatch(ref, lines, screenshotKey);
+                if (result.ok)
+                    delivered.push(ref);
+                else
+                    failed.push(ref);
+            }
+            logger.info({
+                jti: input.jti,
+                siteKey: input.siteKey,
+                tokenRedacted: redactToken(input.token),
+                deliveredCount: delivered.length,
+                failedCount: failed.length,
+            }, "B-4 purchase request DM dispatched");
+            return { delivered, failed };
+        },
+        async deliverPostConsumeFollowup(capability, input) {
+            assertCapability(capability);
+            const consumedMsg = `✅ Confirmed. Aitne is finalising the purchase now. jti=${input.jti}`;
+            const otherMsg = (consumedOn) => `✅ Approved on ${consumedOn} at ${new Date(now()).toISOString()}. No action needed here. jti=${input.jti}`;
+            for (const ref of input.deliveredChannels) {
+                const text = ref === input.consumedChannel
+                    ? consumedMsg
+                    : otherMsg(input.consumedChannel);
+                const result = await dispatch(ref, text);
+                if (!result.ok) {
+                    logger.warn({ jti: input.jti, ref, reason: result.reason }, "post-consume follow-up dispatch failed (continuing)");
+                }
+            }
+        },
+        async deliverCancellationFollowup(capability, input) {
+            assertCapability(capability);
+            const text = `⚠️ Purchase request cancelled (${input.reason}). No charge made. jti=${input.jti}`;
+            for (const ref of input.deliveredChannels) {
+                const result = await dispatch(ref, text);
+                if (!result.ok) {
+                    logger.warn({ jti: input.jti, ref, reason: result.reason }, "cancellation follow-up dispatch failed (continuing)");
+                }
+            }
+        },
+        async deliverVerifyReply(capability, input) {
+            assertCapability(capability);
+            const marker = input.ok ? "✅" : "⚠️";
+            const text = `${marker} ${input.detail}`;
+            const result = await dispatch(input.channel, text);
+            if (!result.ok) {
+                logger.warn({ jti: input.jti, channel: input.channel, reason: result.reason }, "verify reply dispatch failed");
+            }
+        },
+    };
+}
+/**
+ * Convenience helper for the cancellation follow-up's audit message —
+ * exported so other daemon-internal cancel paths (the supervisor's
+ * orphan sweep, the dashboard's "cancel pending" action) format the
+ * cancel reason identically. Pure — no I/O.
+ */
+export function describeCancelReason(reason) {
+    switch (reason) {
+        case "user_reply":
+            return "user replied with non-token content";
+        case "wrong_token":
+            return "user replied with a different token";
+        case "wrong_channel":
+            return "token typed on a non-delivered channel";
+        case "timeout":
+            return "5-minute confirmation window elapsed";
+        case "explicit":
+            return "user issued !cancel-purchase";
+        case "amount_mismatch":
+            return "cart total changed under the confirmation pause";
+        case "amount_exceeds_token":
+            return "displayed total exceeded the confirmed amount";
+        case "page_changed":
+            return "cart page mutated during the pause";
+        case "playwright_error":
+            return "browser-automation error before confirm";
+        case "daily_cap_exceeded":
+            return "per-day spend cap reached at resume";
+        case "b4_disabled":
+            return "B-4 master toggle was turned off";
+        case "site_not_enabled":
+            return "site B-4 was disabled mid-flight";
+        case "supervisor_orphan_sweep":
+            return "daemon restart cleaned up an in-flight token";
+        case "dashboard_cancel":
+            return "user clicked Cancel in the dashboard";
+    }
+}

package/dist/messaging/setup-welcome-dm.d.ts

@@ -27,4 +27,3 @@ export declare function sendSetupWelcomeDm(params: {
     db: Database.Database;
     messageHub: MessageHub;
 }): Promise<MessageDelivery[] | null>;
-//# sourceMappingURL=setup-welcome-dm.d.ts.map

package/dist/messaging/setup-welcome-dm.js

@@ -83,4 +83,3 @@ export async function sendSetupWelcomeDm(params) {
     logger.info({ platforms: deliveries.map((d) => d.platform) }, "Welcome DM sent");
     return deliveries;
 }
-//# sourceMappingURL=setup-welcome-dm.js.map

package/dist/messaging/url-extract.d.ts

@@ -5,4 +5,3 @@ export interface UrlExtractResult {
     urls: string[];
 }
 export declare function extractHttpUrls(input: string, limit?: number): UrlExtractResult;
-//# sourceMappingURL=url-extract.d.ts.map