@oneaddress/setup 2.3.0 → 2.5.0

package/dist/index.js

@@ -856,7 +856,7 @@ var _R = ["\u2588\u2588\u2588\u2588\u2588\u2588 ", "\u2588\u2588   \u2588\u2588"
 var _S = [" \u2588\u2588\u2588\u2588\u2588\u2588", "\u2588\u2588     ", "\u2588\u2588     ", " \u2588\u2588\u2588\u2588\u2588 ", "     \u2588\u2588", "     \u2588\u2588", "\u2588\u2588\u2588\u2588\u2588\u2588 "];
 var ONE_ROWS = Array.from({ length: 7 }, (_3, i) => [_O[i], _N[i], _E[i]].join(" "));
 var ADDR_ROWS = Array.from({ length: 7 }, (_3, i) => [_A[i], _D2[i], _D2[i], _R[i], _E[i], _S[i], _S[i]].join(" "));
-var WIZARD_VERSION = true ? "2.3.0" : "?";
+var WIZARD_VERSION = true ? "2.5.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -983,6 +983,7 @@ data.db-shm
     "headless": "node --disable-warning=ExperimentalWarning node_modules/tsx/dist/cli.mjs src/index.ts -- --headless",
     "build":    "tsup src/index.ts --format esm --no-dts --outDir dist",
     "type-check": "tsc --noEmit",
+    "show":     "tsx scripts/show.ts",
     "test":     "tsx scripts/test.ts"
   },
   "dependencies": {
@@ -1011,7 +1012,8 @@ data.db-shm
   "partnerId": "%%PARTNER_ID%%",
   "oneAddressApi": "%%ONEADDRESS_API%%",
   "verifiesAccountReference": %%VERIFIES_ACCOUNT_REFERENCE%%,
-  "mode": "%%RECEIVER_MODE%%"
+  "mode": "%%RECEIVER_MODE%%",
+  "publicUrl": "%%WEBHOOK_URL%%"
 }
 `
     },
@@ -1711,7 +1713,8 @@ import { formatLine, report, type ReportLine } from './report.js';
 // reads, with nothing here to change.
 import { store } from './store.js';
 import { pendingConfirmCount } from './confirm-queue.js';
-import { exportHeld, heldCount, heldSummary } from './quarantine.js';
+import { dismissHeld, exportHeld, heldCount, heldSummary } from './quarantine.js';
+import { reachability } from './reachable.js';
 
 /** blessed takes colours as strings; these mirror the site's palette. */
 const AMBER = HEX.amber.toLowerCase();
@@ -1870,6 +1873,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     // nor UNENCRYPTED is true and both would mislead. The receiver holds
     // ciphertext it cannot open; the customers live in the partner's own
     // database, behind their own controls.
+    const reach = reachability();
     const vault = inbox
       ? \`{\${AMBER}-fg}{bold}NONE (inbox){/}\`
       : store.encrypted
@@ -1883,7 +1887,16 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       // claim ("you have no customers") and would be a lie on a receiver
       // pointed at a real customer table, where counting every row forty times
       // a minute is the thing the store is right to refuse.
-      \`{\${DIM}-fg}on file{/} {\${CREAM}-fg}\${onFile === null ? '\u2014' : onFile.toLocaleString()}{/}\`,
+      \`{\${DIM}-fg}on file{/} {\${CREAM}-fg}\${onFile === null ? '\u2014' : onFile.toLocaleString()}{/}\`
+      // REACHABLE IS DRAWN ONLY WHEN IT IS KNOWN, and that is the point of the
+      // third state. A receiver with no publicUrl configured cannot answer the
+      // question, and a green tick or a red cross would both be inventing an
+      // answer. Silence is the honest rendering of "not checked".
+      + (reach.state === 'unknown'
+        ? ''
+        : reach.state === 'reachable'
+          ? \`   {\${DIM}-fg}reachable{/} {green-fg}{bold}YES{/}\`
+          : \`   {\${DIM}-fg}reachable{/} {red-fg}{bold}NO{/}\`),
     );
   }
 
@@ -1947,7 +1960,14 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
 
   function renderFaults(): void {
     const held = heldCount();
-    const show = held > 0;
+    const reach = reachability();
+    // UNREACHABLE IS A FAULT, and it belongs in this panel rather than only in
+    // the status bar, because it is the one failure where NOTHING ELSE MOVES.
+    // A wrong key at least produces held dispatches to look at; a stopped
+    // tunnel produces a receiver that looks perfectly healthy and simply never
+    // hears from anyone again.
+    const unreachable = reach.state === 'unreachable';
+    const show = held > 0 || unreachable;
     if (show === Boolean(faultBox.hidden)) {
       // Visibility is changing, so the panels above have to give back or take
       // back the rows. Assigning \`bottom\` is how blessed re-lays-out; it reads
@@ -1962,6 +1982,15 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     // Grouped, never one line per dispatch. The realistic shape of this table
     // is forty rows with ONE cause between them, and forty identical lines hide
     // the single fact that matters.
+    if (unreachable && held === 0) {
+      faultBox.setContent(
+        \`\\n  {bold}Nothing on the internet is reaching this receiver.{/bold}\\n\` +
+        \`  {red-fg}\${esc(reach.state === 'unreachable' ? reach.detail : '')}{/}\\n\` +
+        \`  {\${DIM}-fg}Dispatches cannot arrive while this is true. Check your tunnel is still running.{/}\`,
+      );
+      return;
+    }
+
     const lines = heldSummary().slice(0, 2).map((l) => \`  {red-fg}\${esc(l)}{/}\`);
     faultBox.setContent(
       \`\\n  {bold}\${held}{/bold} dispatch(es) arrived that this receiver could not open. \` +
@@ -1969,7 +1998,8 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       lines.join('\\n') + '\\n' +
       (replayNote
         ? \`  {\${AMBER}-fg}\${esc(replayNote)}{/}\`
-        : \`  {\${DIM}-fg}Fix the cause, then{/} {\${AMBER}-fg}[r]{/} {\${DIM}-fg}to apply,{/} {\${AMBER}-fg}[e]{/} {\${DIM}-fg}to export the list.{/}\`),
+        : \`  {\${DIM}-fg}Fix the cause, then{/} {\${AMBER}-fg}[r]{/} {\${DIM}-fg}to apply,{/} {\${AMBER}-fg}[e]{/} {\${DIM}-fg}to export,{/} \` +
+          \`{\${AMBER}-fg}[d]{/} {\${DIM}-fg}to dismiss.{/}\`),
     );
   }
 
@@ -2003,7 +2033,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       \`{red-fg}failed{/} {bold}\${failed}{/bold}   \` +
       awaitingYou +
       \`{\${awaitingColour}-fg}awaiting confirm{/} {bold}\${awaiting}{/bold}\` +
-      \`{|}{\${DIM}-fg}\${onReplay ? '[r] replay  ' : ''}[e] export  [q] quit{/}  \`,
+      \`{|}{\${DIM}-fg}\${onReplay ? '[r] replay  ' : ''}[e] export  [d] dismiss  [q] quit{/}  \`,
     );
   }
 
@@ -2079,6 +2109,58 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     redraw();
   });
 
+  // [d] DISMISSES. TWO PRESSES, and the first one only asks.
+  //
+  // WHY THIS KEY EXISTS AT ALL. The conformance suite deliberately sends a
+  // dispatch this receiver cannot open (check-11: a session key wrapped to a
+  // throwaway key pair) and passes the receiver for HOLDING it. So passing
+  // conformance leaves a red fault panel up permanently, on a receiver that is
+  // working correctly, with nothing on screen that clears it. Reported from a
+  // real run: "I do wish the conformance wouldn't come up as a fault."
+  //
+  // WHY THE RECEIVER DOES NOT JUST RECOGNISE THE PROBE. Everything that
+  // identifies one is chosen by the sender. See the \`dismissed_at\` docstring in
+  // \`quarantine.ts\`: suppressing a fault panel on a sender-supplied value hides
+  // real held dispatches from the one person whose job is to notice them.
+  //
+  // IRREVERSIBLE, SO IT IS CONFIRMED. Dismissal discards the held payload, which
+  // is the point (see \`dismissHeld\`) and also means a mistaken press cannot be
+  // undone by pressing [r]. The count is named in the question rather than after
+  // it, because "dismiss 47" and "dismiss 1" are different decisions.
+  //
+  // THE ARM REMEMBERS A COUNT, NOT A BOOLEAN, and that is the load-bearing part
+  // rather than a nicety. A boolean armed at 14:02 is still armed at 16:30, so a
+  // partner who armed it against one conformance probe and wandered off would
+  // come back and dismiss whatever real backlog had arrived in between - with a
+  // single keystroke, discarding the payloads. Confirming only the exact set
+  // that was described makes the question and the action the same question.
+  let dismissArmedFor: number | null = null;
+  screen.key(['d'], () => {
+    const held = heldCount();
+    if (held === 0) {
+      dismissArmedFor = null;
+      replayNote = 'Nothing held, so nothing to dismiss.';
+      redraw();
+      return;
+    }
+    if (dismissArmedFor !== held) {
+      const changed = dismissArmedFor !== null;
+      dismissArmedFor = held;
+      replayNote = (changed ? \`That changed: \${held} held now. \` : '') +
+        \`Press [d] again to dismiss \${held}: not applied, payloads discarded, cannot be undone.\`;
+      redraw();
+      return;
+    }
+    dismissArmedFor = null;
+    try {
+      const n = dismissHeld();
+      replayNote = \`Dismissed \${n}. Nothing left held.\`;
+    } catch (err) {
+      replayNote = \`Dismiss failed: \${err instanceof Error ? err.message : String(err)}\`;
+    }
+    redraw();
+  });
+
   screen.key(['q', 'C-c'], () => {
     detach();
     screen.destroy();
@@ -2136,6 +2218,15 @@ export function noteChange(facts: ChangeFacts): void {
  * \`--headless\` skips both: no prompt (a service has nobody to ask), no screen.
  */
 import { printBanner } from './brand.js';
+// Config only - NOT the server, the store or the database. Those derive keys on
+// import, which is the whole reason this file loads them dynamically below,
+// after the passphrase is resolved. \`config.js\` reads a JSON file and the
+// environment and touches neither.
+import { config } from './config.js';
+// Same rule as \`config.js\`: \`unlock.js\` deliberately does not import the
+// database, so it can be loaded statically here and still run before the keys
+// are derived. See its own header.
+import { ask, databaseIsLocked } from './unlock.js';
 import { PassphraseRequiredError, WrongPassphraseError } from './vault.js';
 
 /**
@@ -2158,122 +2249,6 @@ const headless =
   process.env.ONEADDRESS_HEADLESS === '1' ||
   !process.stdout.isTTY;
 
-/**
- * Has this database already been locked?
- *
- * Asked BEFORE the passphrase, and without one, so the prompt can say which of
- * two completely different things it is doing. \`db_meta.verifier\` is written the
- * first time a passphrase is set, so its presence is the whole answer.
- *
- * Read through its own connection rather than importing \`db.ts\`, which derives
- * its keys the moment it is imported and would therefore have to run BEFORE we
- * know what to ask for.
- */
-async function databaseIsLocked(): Promise<boolean> {
-  try {
-    const { DatabaseSync } = await import('node:sqlite');
-    const { join } = await import('node:path');
-    const path = process.env.DB_PATH ?? join(process.cwd(), 'data.db');
-    const db = new DatabaseSync(path, { readOnly: true });
-    try {
-      const row = db
-        .prepare("SELECT value FROM db_meta WHERE key = 'verifier'")
-        .get() as { value?: string } | undefined;
-      return Boolean(row?.value);
-    } finally {
-      db.close();
-    }
-  } catch {
-    // No file yet, or no db_meta table yet. Either way: not locked.
-    return false;
-  }
-}
-
-/**
- * Ask for a passphrase without echoing it to the screen.
- *
- * A passphrase typed in clear on a shared screen, in a screen-share, or into a
- * terminal that keeps scrollback is not much of a secret. readline echoes by
- * default, so its output hook is replaced for the duration of the question.
- *
- * Degrades to a visible prompt rather than failing: on a terminal where the
- * hook is not available, being asked in the clear beats not being asked.
- */
-async function ask(prompt: string): Promise<string> {
-  process.stdout.write(prompt);
-
-  // NO readline. Two versions of this used readline's \`_writeToOutput\` hook to
-  // mask the echo and BOTH ECHOED THE PASSPHRASE IN CLEAR, which was only found
-  // by driving a real terminal and reading what came back. The first filtered
-  // on whether the chunk contained the prompt, not knowing readline repaints
-  // prompt and input together on every keystroke, so the condition was always
-  // true. The second repainted the line and still leaked, because the echo was
-  // never coming from that hook at all.
-  //
-  // Reading the keys directly removes the guessing. Raw mode turns the
-  // terminal's own echo OFF, so the ONLY thing that can reach the screen is
-  // what is written below: one asterisk per character, which is what a partner
-  // asked for and what every other passphrase prompt does.
-  const stdin = process.stdin;
-  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
-    // No terminal to control. Being asked in the clear beats not being asked,
-    // and this path is only reached where nothing is watching anyway.
-    const { createInterface } = await import('node:readline/promises');
-    const rl = createInterface({ input: stdin, output: process.stdout });
-    try {
-      const answer = await rl.question('');
-      return answer.trim();
-    } finally { rl.close(); }
-  }
-
-  const wasRaw = stdin.isRaw === true;
-  stdin.setRawMode(true);
-  stdin.resume();
-  stdin.setEncoding('utf8');
-
-  return new Promise<string>((resolve) => {
-    let typed = '';
-    const restore = (): void => {
-      stdin.removeListener('data', onData);
-      stdin.setRawMode(wasRaw);
-      stdin.pause();
-    };
-    const onData = (chunk: string): void => {
-      for (const ch of chunk) {
-        if (ch === '\\r' || ch === '\\n') {
-          restore();
-          process.stdout.write('\\n');
-          resolve(typed.trim());
-          return;
-        }
-        if (ch === '\\u0003') {            // Ctrl+C
-          restore();
-          process.stdout.write('\\n');
-          process.exit(130);
-        }
-        if (ch === '\\u0004') {            // Ctrl+D on an empty line ends it
-          restore();
-          process.stdout.write('\\n');
-          resolve(typed.trim());
-          return;
-        }
-        if (ch === '\\u007f' || ch === '\\b') {
-          // Backspace has to move the asterisks too, or the mask stops matching
-          // what is actually in the buffer and the count misleads.
-          if (typed.length > 0) {
-            typed = typed.slice(0, -1);
-            process.stdout.write('\\b \\b');
-          }
-          continue;
-        }
-        if (ch < ' ') continue;          // ignore the rest of the control range
-        typed += ch;
-        process.stdout.write('*');
-      }
-    };
-    stdin.on('data', onData);
-  });
-}
 
 /**
  * Where the at-rest passphrase comes from.
@@ -2310,29 +2285,72 @@ async function resolvePassphrase(): Promise<string | null> {
     // Reported by exactly that partner: "there was no opportunity to set a
     // passphrase". Without this line the only options are guess or search the
     // internet, and the answer is one command.
-    process.stdout.write('\\n  This customer database is encrypted.\\n');
-    process.stdout.write('  If you do not know the passphrase, delete data.db and start\\n');
-    process.stdout.write('  again: it holds your demo roster and test dispatches, nothing\\n');
-    process.stdout.write('  OneAddress needs.\\n\\n');
-    const answer = await ask('  Passphrase to unlock: ');
+    process.stdout.write('\\n  This customer database is encrypted and needs its password.\\n\\n');
+    process.stdout.write('  It is the one you chose on this receiver. It is NOT your Webhook\\n');
+    process.stdout.write('  signing secret, NOT your ECDH private key, and NOT your\\n');
+    process.stdout.write('  OneAddress sign-in.\\n\\n');
+    process.stdout.write('  If you do not have it, delete data.db and start again: it holds\\n');
+    process.stdout.write('  your demo roster and test dispatches, nothing OneAddress needs.\\n\\n');
+    const answer = await ask('  Password to unlock: ');
     return answer || null;
   }
 
-  process.stdout.write('\\n  SET A PASSPHRASE to encrypt your customer records at rest.\\n');
-  process.stdout.write('  It is YOURS. It is not the OneAddress private key, and OneAddress\\n');
-  process.stdout.write('  never sees it and CANNOT RECOVER IT. Lose it and the records in\\n');
-  process.stdout.write('  data.db cannot be read again.\\n');
-  process.stdout.write('  Press Enter to skip and store records unencrypted.\\n\\n');
+  // SAYS WHAT IS BEING ASKED BEFORE IT WARNS ABOUT IT. The first version opened
+  // with SET A PASSPHRASE and four lines of consequence, which reads as an
+  // instruction to produce a passphrase you are assumed to already have - and
+  // this prompt arrives moments after the partner has pasted two real
+  // credentials, so assuming exactly that is the natural reading. Reported as
+  // confusing, and the confusion was ours.
+  //
+  // It therefore leads with the decision and says plainly that the answer is
+  // INVENTED HERE. It used to go on to name the three secrets it is NOT, which
+  // was accurate and was four more lines of denial in a prompt that is already
+  // the longest question in setup; reported as over-explained, and cut back to
+  // the three facts an answer depends on (new, what it protects, unrecoverable).
+  // The UNLOCK branch keeps its version of that list, because there the partner
+  // is being asked for a password they may not remember choosing and naming the
+  // wrong candidates is the whole help.
+  // NOT ASKED IN INBOX MODE, because the honest answer to "protect your customer
+  // records" is that there are none here: the connector holds them. The
+  // database in this mode carries dispatch ciphertext - already encrypted to a
+  // key this process does not have - and a queue of dispatch ids. Asking anyway
+  // is the confusing-prompt problem twice over: a question about data that is
+  // absent, put to somebody who has just been told this receiver cannot read
+  // anything.
+  //
+  // The UNLOCK branch above is deliberately NOT skipped. A database encrypted
+  // while the receiver ran write-through is still encrypted after a switch to
+  // inbox, and skipping the question there would refuse to open a file whose
+  // owner has the password.
+  if (config.mode === 'inbox') {
+    process.stdout.write('\\n  No password needed: in inbox mode this receiver holds no customer records.\\n');
+    process.stdout.write('  Your connector holds them, and the key.\\n\\n');
+    return null;
+  }
+
+  process.stdout.write('\\n  \u2500\u2500 Protect this receiver\\'s customer database? \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\n\\n');
+  process.stdout.write('  MAKE UP A NEW PASSWORD. Invented here, not one you already\\n');
+  process.stdout.write('  hold. It encrypts the customer records this receiver keeps in\\n');
+  process.stdout.write('  data.db. OneAddress never sees it and cannot reset it.\\n\\n');
+  process.stdout.write('  Optional. Press Enter to skip and leave the database readable.\\n');
+  // ACCURATE ABOUT "LATER", because the obvious reading is wrong. Setting a
+  // password afterwards works and the receiver reports itself encrypted, but
+  // rows written before it stay in the clear until something rewrites them -
+  // confirmed by finding a seeded customer name in the database file after
+  // exactly that sequence.
+  process.stdout.write('  You can set one later with ONEADDRESS_DB_PASSPHRASE, but records\\n');
+  process.stdout.write('  written before then stay readable until they change.\\n\\n');
 
   for (;;) {
-    const first = await ask('  New passphrase: ');
+    const first = await ask('  New password (or Enter to skip): ');
     if (!first) {
-      process.stdout.write('  Continuing WITHOUT encryption.\\n\\n');
+      process.stdout.write('  Continuing WITHOUT encryption: anyone who can read data.db can\\n');
+      process.stdout.write('  read your customer records.\\n\\n');
       return null;
     }
-    const again = await ask('  Confirm passphrase: ');
+    const again = await ask('  Type it again: ');
     if (first === again) {
-      process.stdout.write('  Passphrase set. Keep it somewhere you will still have it.\\n\\n');
+      process.stdout.write('  Password set. Keep it somewhere you will still have it.\\n\\n');
       return first;
     }
     process.stdout.write('  Those do not match. Try again.\\n\\n');
@@ -2471,6 +2489,22 @@ import type {
  * if anything awaited between the set and the read, which is why they are
  * adjacent and why this comment exists.
  */
+/**
+ * The connector could not be reached, so the question was never answered.
+ *
+ * A THROW RATHER THAN A VERDICT, because every value this function can return
+ * is a statement about the customer's record and none of them means "we could
+ * not ask". The handler turns this into a non-2xx, which the relay already
+ * classifies as \`unreachable\` and shows the consumer as a transient network
+ * problem rather than as a missing account.
+ */
+export class ConnectorUnreachableError extends Error {
+  constructor(public readonly kind: string) {
+    super(\`the connector could not be reached to answer \${kind}\`);
+    this.name = 'ConnectorUnreachableError';
+  }
+}
+
 let currentRawBody = '';
 
 export function setCurrentRawBody(raw: string): void {
@@ -2496,14 +2530,26 @@ export const connectorStore = {
   ): Promise<AccountVerdict> {
     const answer = await askConnector('account.verify', currentRawBody);
     if (!answer.reached) {
-      // NEVER GUESSED. A fabricated match authorises a stranger's address onto
-      // a customer's account. \`no_account\` is the safe answer and stops the
-      // consumer before they pay, which is the trade this design accepted.
+      // NEVER GUESSED: a fabricated match authorises a stranger's address onto
+      // a customer's account.
+      //
+      // BUT NOT \`no_account\` EITHER, which is what this returned. That is a
+      // POSITIVE CLAIM - the consumer is shown "\u2717 No account found / This
+      // service couldn't find an account with these details" and goes off to
+      // re-check an account number that was correct all along, or concludes
+      // they have no account with a provider they do.
+      //
+      // The trade was accepted for its safety, and the safety is real. What was
+      // missed is that it is available WITHOUT the false claim: the relay
+      // already classifies a failed check as \`unreachable\` and tells the
+      // consumer "we couldn't reach this service just now". That stops them
+      // before they pay AND is true. Throwing gets us there, because a
+      // non-2xx is exactly what the relay reads as unreachable.
       report.warn(
         \`[connector] account check for \${accountNumber ?? '(none)'} could not be answered; \` +
-        'refusing rather than guessing',
+        'reporting the service as unreachable rather than claiming no account exists',
       );
-      return 'no_account';
+      throw new ConnectorUnreachableError('account.verify');
     }
     const status = verdictOf(answer.body, 'status');
     if (status === 'match' || status === 'no_match' || status === 'no_account') return status;
@@ -2513,7 +2559,9 @@ export const connectorStore = {
 
   async verifyAddress(_customer: Customer, _incoming: Address): Promise<VerifyResult> {
     const answer = await askConnector('address.verify', currentRawBody);
-    if (!answer.reached) return 'not_found';
+    // Same reasoning as \`verifyAccount\`: \`not_found\` is a claim about the
+    // customer's record, and "we could not ask" is not that claim.
+    if (!answer.reached) throw new ConnectorUnreachableError('address.verify');
     const result = verdictOf(answer.body, 'result');
     if (result === 'match' || result === 'mismatch' || result === 'not_found') return result;
     report.warn(\`[connector] address.verify answered "\${result ?? '(nothing)'}", which is not a result\`);
@@ -2681,7 +2729,7 @@ import express, { type Request, type Response } from 'express';
 import rateLimit from 'express-rate-limit';
 import { timingSafeEqual } from 'node:crypto';
 import { report } from './report.js';
-import { acknowledge, drawable, markDrawn, type InboxOutcome } from './inbox.js';
+import { acknowledge, drawable, hold, markDrawn, type InboxOutcome } from './inbox.js';
 
 const TOKEN = process.env.CONNECTOR_TOKEN ?? '';
 /**
@@ -2774,18 +2822,41 @@ export function startDrawApi(): { port: number } | null {
    * confirm, which is the honest answer when the partner's own system refused
    * the change: the consumer is told it did not land rather than being told it
    * did.
+   *
+   * \`held\` QUEUES NOTHING, and that is the whole point of it. It means the
+   * connector could not OPEN the dispatch, which is a fact about a key rather
+   * than about the consumer's record - and a \`failed\` confirm is read as the
+   * latter all the way down: \`partner_failed\`, terminal, refund denied. The
+   * item stays unacknowledged so the next draw retries it once the key is
+   * fixed. See \`hold\` in inbox.ts for why nothing else recovers this.
    */
   app.post('/ack', (req: Request, res: Response) => {
     if (!authorised(req, res)) return;
     const body = req.body as { id?: unknown; outcome?: unknown; detail?: unknown };
     const id = typeof body.id === 'string' ? body.id : '';
-    const outcome: InboxOutcome | null =
-      body.outcome === 'applied' || body.outcome === 'failed' ? body.outcome : null;
+    const outcome: InboxOutcome | 'held' | null =
+      body.outcome === 'applied' || body.outcome === 'failed' || body.outcome === 'held'
+        ? body.outcome
+        : null;
     if (!id || !outcome) {
-      return res.status(400).json({ error: 'id and outcome (applied|failed) are required' });
+      return res.status(400).json({ error: 'id and outcome (applied|failed|held) are required' });
     }
     const detail = typeof body.detail === 'string' ? body.detail : null;
 
+    // HELD RETURNS BEFORE \`acknowledge\`, so there is no path from here to a
+    // confirm. Ordering rather than a flag: a held item that fell through to
+    // the code below would be stamped terminal and reported to OneAddress as
+    // the consumer's problem, which is the defect this exists to remove.
+    if (outcome === 'held') {
+      const heldResult = hold(id, detail, LEASE_SECONDS);
+      if (!heldResult) return res.status(404).json({ error: 'unknown or already acknowledged id' });
+      return res.json({
+        ok: true, held: true,
+        attempts: heldResult.attempts,
+        retryInSeconds: heldResult.retryInSeconds,
+      });
+    }
+
     const result = acknowledge(id, outcome, detail);
     if (!result) return res.status(404).json({ error: 'unknown id' });
     if (result.alreadyAcknowledged) {
@@ -2885,9 +2956,16 @@ export function setAcknowledgementHandler(
  * the claim has to become atomic, the way \`confirm-queue.ts\` already does it.
  * Written down because a lease LOOKS like it handles concurrency and does not.
  */
-import db from './db.js';
+import db, { ensureColumn } from './db.js';
 import { report } from './report.js';
 
+/**
+ * The connector's TERMINAL verdicts. Both end the item and both tell OneAddress.
+ *
+ * \`held\` is deliberately NOT one of these, and lives in its own function. See
+ * \`hold\` below for why a dispatch the connector could not OPEN must never
+ * become one of these two.
+ */
 export type InboxOutcome = 'applied' | 'failed';
 
 db.exec(\`
@@ -2906,6 +2984,30 @@ db.exec(\`
     ON inbox(applied_at, drawn_at, received_at);
 \`);
 
+/**
+ * Why a held item needs its own two columns, matching \`quarantine\`'s.
+ *
+ * A dispatch the connector cannot OPEN is not finished with, so it keeps
+ * \`applied_at IS NULL\` and stays in the undrawn count. But an operator then
+ * needs to know it is BLOCKED rather than merely queued, and by what: without
+ * these the dashboard can say a number and nothing else, and the connector's
+ * message - which names the exact environment variable to set - is only in a
+ * log somebody has to still have.
+ *
+ * Same names as the quarantine's, because it is the same idea one process over
+ * and a second vocabulary for it would be a second thing to learn.
+ */
+ensureColumn('inbox', 'attempts', 'INTEGER NOT NULL DEFAULT 0');
+ensureColumn('inbox', 'last_error', 'TEXT');
+
+/**
+ * First retry for a held item, multiplied by the attempt count and capped at
+ * the lease. Thirty seconds because the overwhelming case is a partner who has
+ * just corrected a key and restarted the connector, and making them wait out a
+ * lease built for crash recovery would be answering a question nobody asked.
+ */
+const HELD_RETRY_BASE_SECONDS = 30;
+
 export interface AcceptInput {
   key: string;
   dispatchId: string | null;
@@ -2987,6 +3089,110 @@ export function acknowledge(
   return { dispatchId: row.dispatch_id, alreadyAcknowledged: false };
 }
 
+/**
+ * The connector could not OPEN this one, so it is not finished with.
+ *
+ * ## Why this is not \`failed\`
+ *
+ * \`failed\` is a statement about the CONSUMER'S RECORD - the partner's system
+ * received the change and refused it - and OneAddress reads it exactly that
+ * way. \`/api/confirm\` resolves every non-success to \`partner_failed\`, that row
+ * is terminal (a later SUCCESSFUL confirm cannot overwrite it), and the refund
+ * classifier maps it to \`no_match\`: "the partner received it and said no", so
+ * the refund is DENIED and the consumer is emailed that it did not land.
+ *
+ * "I could not read it" is not that statement. It is a fact about the
+ * partner's key configuration and has nothing to do with the consumer. Sending
+ * it as \`failed\` charged a consumer five dollars, told them a provider had
+ * rejected them, and refused them a refund, because a key was wrong in a
+ * process they have never heard of.
+ *
+ * ## Why there is no retry to fall back on
+ *
+ * \`draw-loop.ts\` used to reason that "OneAddress's own retry of the dispatch is
+ * the recovery path". That is true in write-through, where an unopenable
+ * dispatch answers 422 and the dispatch row stays \`failed\` for the retry cron
+ * to pick up. It is FALSE here, for the reason this mode exists: the receiver
+ * already answered 200 at arrival, so the dispatch row is \`delivered\`, and
+ * \`retry-webhooks\` only ever re-sends rows that are \`pending\` or \`failed\`.
+ * Nothing retries. The confirm was the only remaining signal and it was being
+ * spent on a verdict that was not true.
+ *
+ * ## What happens instead
+ *
+ * The item stays unacknowledged, so it stays in the undrawn count, which the
+ * dashboard already reports as a fault - and that is the behaviour recorded in
+ * the new-matter register for this mode: an undrawn update is held INDEFINITELY
+ * and reported as a fault, deliberately unlike the quarantine's 30-day purge,
+ * because an undrawn update is a consumer whose address did not land and ageing
+ * it out loses it silently.
+ *
+ * Re-stamping \`drawn_at\` is the backoff and costs no new mechanism: \`drawable\`
+ * re-offers an item once its stamp is older than the lease, so the next attempt
+ * is one lease away and the poll loop cannot spin on a key that is still wrong.
+ * When the key is fixed the next draw applies it, with no operator command -
+ * which is the half that \`[r]\` has to be pressed for in write-through.
+ *
+ * Returns null for an unknown id or one already terminally acknowledged, the
+ * same tolerance \`acknowledge\` has and for the same reason.
+ */
+export function hold(
+  id: string,
+  detail: string | null,
+  leaseSeconds: number,
+): { attempts: number; retryInSeconds: number } | null {
+  const row = db.prepare(
+    'SELECT applied_at, attempts FROM inbox WHERE id = ?',
+  ).get(id) as { applied_at: string | null; attempts: number } | undefined;
+  if (!row) return null;
+  if (row.applied_at !== null) return null;
+
+  const attempts = (row.attempts ?? 0) + 1;
+  // \u2500\u2500 THE BACKOFF IS NOT THE LEASE, AND THAT IS THE POINT \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  //
+  // The lease is 300s and is generous ON PURPOSE: re-offering a DRAWN item too
+  // early risks applying the same update twice. A held item carries none of
+  // that risk, because nothing was applied - it could not even be opened. So
+  // reusing the lease would make a partner who has just fixed their key wait
+  // five minutes for a safety property that is not in play.
+  //
+  // \`drawable\` re-offers a row once \`drawn_at < now - lease\`, so a stamp of
+  // \`now - lease + backoff\` becomes drawable in exactly \`backoff\` seconds.
+  // That is the whole mechanism: no column, no second query, no timer. Pinned
+  // by a test that checks it is NOT drawable before the backoff and IS after,
+  // because arithmetic written backwards still produces a plausible timestamp.
+  //
+  // Capped at the lease so a repeatedly-failing item can never retry FASTER
+  // than a crashed connector's item, which would be the wrong way round.
+  const retryInSeconds = Math.min(HELD_RETRY_BASE_SECONDS * attempts, leaseSeconds);
+  const stamp = new Date(Date.now() - leaseSeconds * 1000 + retryInSeconds * 1000).toISOString();
+  db.prepare(
+    'UPDATE inbox SET attempts = ?, last_error = ?, drawn_at = ? WHERE id = ?',
+  ).run(attempts, detail?.slice(0, 500) ?? null, stamp, id);
+  report.warn(
+    \`[inbox] \${id} HELD after \${attempts} attempt(s), retrying in \${retryInSeconds}s, not failed: \` +
+    \`\${detail ?? 'the connector could not open it'}\`,
+  );
+  return { attempts, retryInSeconds };
+}
+
+/**
+ * The held items, for the dashboard's faults band.
+ *
+ * Separate from \`undrawnCount\` because the two mean different things to an
+ * operator: undrawn is "your connector has not got to it yet", held is "your
+ * connector tried and cannot". Only the second one needs somebody to do
+ * something, and it is the one carrying the message that says what.
+ */
+export function heldItems(): { id: string; attempts: number; lastError: string | null }[] {
+  return db.prepare(
+    \`SELECT id, attempts, last_error AS lastError
+       FROM inbox
+      WHERE applied_at IS NULL AND attempts > 0
+      ORDER BY received_at\`,
+  ).all() as unknown as { id: string; attempts: number; lastError: string | null }[];
+}
+
 /** How many updates are sitting here unapplied. Shown as a fault when non-zero. */
 export function undrawnCount(): number {
   const row = db.prepare(
@@ -3220,6 +3426,38 @@ export function dispatchKey(dispatchId: string | null, rawBody: string): string
  */
 ensureColumn('quarantine', 'attempts', 'INTEGER NOT NULL DEFAULT 0');
 
+/**
+ * When the operator decided this one is not going to be applied.
+ *
+ * ## Why a dashboard needs this at all
+ *
+ * The conformance suite sends a dispatch that CANNOT be opened, deliberately:
+ * check-11 wraps a session key to a throwaway key pair and passes only if the
+ * receiver reports the failure instead of answering \`200 { ok: true }\`. Holding
+ * it is the correct behaviour and is how the check is passed. The receiver then
+ * draws a red FAULTS panel about it for the rest of the database's life, and a
+ * partner who has just been told they passed is looking at a permanent fault
+ * they cannot clear. Reported from a real run.
+ *
+ * ## Why the receiver does NOT recognise the probe itself
+ *
+ * The tempting fix is to spot the probe and not count it. Everything that
+ * identifies one comes from the SENDER: the dispatch id is a header, and the
+ * ciphertext is opaque by construction. Suppressing an operator's fault panel on
+ * a value the sender chose is a way to hide a real held dispatch from the person
+ * whose job is to notice it, and it would be reachable by anyone holding the
+ * webhook secret. The signal stays; the OPERATOR gets a way to answer it.
+ *
+ * ## Why the payload goes with it
+ *
+ * Dismissing says "I am not applying this". A held payload is a consumer's
+ * encrypted address sitting on a third party's disk, kept only because applying
+ * it later is still on the table. Once it is not, the reason to keep it is gone,
+ * so \`raw_body\` is emptied in the same statement. That also makes dismissal
+ * mean what it says: \`[r]\` cannot quietly bring it back.
+ */
+ensureColumn('quarantine', 'dismissed_at', 'TEXT');
+
 export interface QuarantineInput {
   dispatchId: string | null;
   event: string;
@@ -3283,7 +3521,7 @@ export function heldDispatches(limit = 50): HeldDispatch[] {
     \`SELECT id, dispatch_id, event, reason, key_id, raw_body, detail,
             received_at, last_error, attempts
        FROM quarantine
-      WHERE replayed_at IS NULL
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL
       ORDER BY received_at
       LIMIT ?\`,
   ).all(limit) as unknown as HeldDispatch[];
@@ -3292,7 +3530,7 @@ export function heldDispatches(limit = 50): HeldDispatch[] {
 /** How many dispatches are held. Shown on the dashboard. */
 export function heldCount(): number {
   const row = db.prepare(
-    'SELECT count(*) AS n FROM quarantine WHERE replayed_at IS NULL',
+    'SELECT count(*) AS n FROM quarantine WHERE replayed_at IS NULL AND dismissed_at IS NULL',
   ).get() as { n: number };
   return row.n;
 }
@@ -3309,7 +3547,7 @@ export function heldSummary(): string[] {
     \`SELECT reason, key_id, count(*) AS n,
             max(attempts) AS tries, min(received_at) AS oldest
        FROM quarantine
-      WHERE replayed_at IS NULL
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL
       GROUP BY reason, key_id
       ORDER BY n DESC\`,
   ).all() as unknown as {
@@ -3353,6 +3591,38 @@ export function markReplayFailed(id: string, error: string): void {
     .run(error.slice(0, 500), id);
 }
 
+/**
+ * The operator's answer to the fault panel: not applying these, stop counting them.
+ *
+ * Takes everything currently held rather than one row, because the panel groups
+ * by cause and offers no way to point at a single dispatch. The realistic use is
+ * one decision about one cause, which is the shape the panel already shows.
+ *
+ * \`raw_body\` is emptied in the same statement. See the \`dismissed_at\` docstring
+ * for why: once the operator has said it will not be applied, a consumer's
+ * encrypted address is being kept for no reason, and a dismissal that leaves the
+ * payload behind is one \`[r]\` away from not being a dismissal.
+ *
+ * The row itself STAYS. It is the record that a dispatch arrived and was
+ * consciously dropped, which is the fact an audit wants, and \`purgeQuarantine\`
+ * ages it out on the same window as everything else.
+ */
+export function dismissHeld(): number {
+  const info = db.prepare(
+    \`UPDATE quarantine
+        SET dismissed_at = ?, raw_body = ''
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL\`,
+  ).run(new Date().toISOString());
+  const n = Number(info.changes ?? 0);
+  if (n > 0) {
+    report.warn(
+      \`[quarantine] dismissed \${n} held dispatch(es). They will NOT be applied and their \` +
+      'payloads have been discarded. OneAddress was already told each one failed.',
+    );
+  }
+  return n;
+}
+
 /**
  * Drop held payloads past the retention window, replayed or not.
  *
@@ -3838,6 +4108,16 @@ export type ReceiverConfig = {
   oneAddressApi:            string;
   verifiesAccountReference: boolean;
   mode:                     ReceiverMode;
+  /**
+   * The webhook URL registered with OneAddress: where dispatches actually
+   * arrive from the internet.
+   *
+   * Written by the wizard, which is the only thing that knows it - the receiver
+   * binds a local port and has no idea what hostname reaches it. Empty disables
+   * the reachability check rather than guessing, because a wrong URL here would
+   * report a healthy receiver as unreachable, which is worse than silence.
+   */
+  publicUrl:                string;
 };
 
 const DEFAULTS: ReceiverConfig = {
@@ -3852,6 +4132,8 @@ const DEFAULTS: ReceiverConfig = {
   // running and a key living somewhere else; a receiver that silently switched
   // into it would accept dispatches nothing ever collects.
   mode: 'write-through',
+  // No guess. See the field's docstring.
+  publicUrl: '',
 };
 
 function parseMode(value: unknown): ReceiverMode | undefined {
@@ -3870,6 +4152,7 @@ function loadConfigFile(): Partial<ReceiverConfig> {
     if (typeof parsed.partnerId === 'string')                out.partnerId = parsed.partnerId;
     if (typeof parsed.oneAddressApi === 'string')            out.oneAddressApi = parsed.oneAddressApi;
     if (typeof parsed.verifiesAccountReference === 'boolean') out.verifiesAccountReference = parsed.verifiesAccountReference;
+    if (typeof parsed.publicUrl === 'string')                 out.publicUrl = parsed.publicUrl;
     const mode = parseMode(parsed.mode);
     if (mode) out.mode = mode;
     return out;
@@ -3893,6 +4176,7 @@ export const config: ReceiverConfig = {
   // up as "not the mode I asked for" rather than as a receiver that will not
   // start. Silent is the thing to avoid, not strict.
   mode: parseMode(process.env.RECEIVER_MODE) ?? fromFile.mode ?? DEFAULTS.mode,
+  publicUrl: stripTrailingSlash(process.env.PUBLIC_URL || fromFile.publicUrl || DEFAULTS.publicUrl),
 };
 
 report.info(
@@ -3900,6 +4184,188 @@ report.info(
   ', oneAddressApi=' + config.oneAddressApi +
   ', verifiesAccountReference=' + config.verifiesAccountReference + ')',
 );
+`
+    },
+    {
+      name: "src/reachable.ts",
+      content: `/**
+ * IS ANYTHING ON THE INTERNET STILL REACHING THIS RECEIVER?
+ *
+ * ## The problem, and why the receiver cannot simply notice
+ *
+ * A partner running behind a tunnel stops the tunnel - closes the laptop, ends
+ * the terminal, lets the trial lapse - and the receiver notices nothing. That is
+ * not an oversight: the tunnel DIALS IN to this process. Nothing here holds a
+ * connection outward, so from inside, "the tunnel is down" and "nobody sent me
+ * anything" are the same observation, which is silence. And silence is not a
+ * fault: a small partner legitimately goes days between dispatches, so a
+ * watchdog that fired on quiet would cry wolf at exactly the partners least able
+ * to tell the difference.
+ *
+ * Meanwhile OneAddress is failing to deliver, marking the endpoint unhealthy,
+ * and the only place that says so is a portal nobody has open.
+ *
+ * ## How this answers it
+ *
+ * The receiver fetches ITS OWN PUBLIC URL and checks that a nonce minted at
+ * startup comes back. Only this running process knows that value, which is what
+ * makes the answer unambiguous.
+ *
+ * "DID ANYTHING ANSWER" IS NOT GOOD ENOUGH, and that is the whole reason for
+ * the nonce. A stopped Cloudflare tunnel does not refuse the connection: the
+ * edge is still there and serves an error page (1033, or a 502). That is a
+ * perfectly valid HTTP response, so a check written \`if (res.ok)\` - or even
+ * \`if (res.status < 500)\` - reports a dead tunnel as healthy. A check that
+ * demands the nonce cannot be satisfied by anything except this process.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not fail the receiver, retry aggressively, or call OneAddress. It is
+ * a statement on the dashboard and a log line. A receiver that shut itself down
+ * because it could not see itself would turn a DNS blip into an outage, and the
+ * failure it is reporting is one only a human can fix.
+ *
+ * It is also not a security control. The nonce proves identity of the process,
+ * not authorisation: the endpoint returns it to anyone who asks. It is a random
+ * value with no meaning outside this check, and knowing it grants nothing - the
+ * webhook still requires a valid HMAC.
+ */
+import { randomBytes } from 'node:crypto';
+import { config } from './config.js';
+import { report } from './report.js';
+
+/** Minted once per process. See the header: this is what makes the answer
+ *  unambiguous, and it is deliberately not a secret. */
+export const ALIVE_NONCE = randomBytes(16).toString('hex');
+
+/** The path the check hits. Deliberately NOT \`/webhook\`: that is POST-only and
+ *  would 404 or 405 through a perfectly healthy tunnel. */
+export const ALIVE_PATH = '/oa-receiver-alive';
+
+export type Reachability =
+  | { state: 'unknown';     detail: string }
+  | { state: 'reachable';   checkedAt: string }
+  | { state: 'unreachable'; detail: string; since: string };
+
+let current: Reachability = { state: 'unknown', detail: 'not checked yet' };
+
+/** What the dashboard renders. Never throws. */
+export function reachability(): Reachability {
+  return current;
+}
+
+/**
+ * The ORIGIN to probe, or null when there is nothing usable to probe.
+ *
+ * TWO THINGS THIS FIXES, both found by reading the value the wizard actually
+ * writes rather than the one this function wanted.
+ *
+ * 1. \`publicUrl\` is the REGISTERED WEBHOOK URL, so it ends in \`/webhook\`.
+ *    Appending the probe path to it gives \`\u2026/webhook/oa-receiver-alive\`, which
+ *    404s through a perfectly healthy tunnel and would report every working
+ *    receiver as unreachable. The origin is what is wanted.
+ * 2. The scaffold substitutes a PLACEHOLDER (\`<your-webhook-url>\`) when setup
+ *    ran without a registered URL. Probing that fails forever, so a partner who
+ *    skipped registration would get a permanent red panel about a fault they do
+ *    not have.
+ *
+ * Anything that is not an absolute http(s) URL therefore reads as NOT
+ * CONFIGURED rather than as unreachable: the failure mode to avoid here is
+ * crying wolf, since the whole value of the check is that it is believed.
+ */
+export function probeOrigin(raw: string): string | null {
+  if (!raw) return null;
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+    return u.origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One check. Returns the new state rather than only setting it, so a test can
+ * drive it directly without reaching into module state.
+ */
+export async function checkReachable(fetchImpl: typeof fetch = fetch): Promise<Reachability> {
+  const origin = probeOrigin(config.publicUrl);
+  if (!origin) {
+    current = {
+      state: 'unknown',
+      detail: config.publicUrl
+        ? 'publicUrl in oneaddress.config.json is not a usable http(s) URL'
+        : 'no publicUrl in oneaddress.config.json',
+    };
+    return current;
+  }
+
+  const url = \`\${origin}\${ALIVE_PATH}\`;
+  const since = current.state === 'unreachable' ? current.since : new Date().toISOString();
+
+  try {
+    const res = await fetchImpl(url, {
+      method: 'GET',
+      // Short: this is a liveness probe, not a download. A tunnel that takes
+      // longer than this to answer is already failing dispatches, which time
+      // out on OneAddress's side too.
+      signal: AbortSignal.timeout(10_000),
+      headers: { 'cache-control': 'no-cache' },
+    });
+    const body = await res.text().catch(() => '');
+    // THE NONCE, not the status. See the header: a stopped tunnel answers with
+    // a real HTTP response carrying an error page.
+    if (body.trim() === ALIVE_NONCE) {
+      current = { state: 'reachable', checkedAt: new Date().toISOString() };
+      return current;
+    }
+    current = {
+      state: 'unreachable',
+      detail: \`\${url} answered HTTP \${res.status} but not from this receiver (tunnel down, or the URL points elsewhere)\`,
+      since,
+    };
+  } catch (err) {
+    current = {
+      state: 'unreachable',
+      detail: \`\${url} could not be reached: \${err instanceof Error ? err.message : String(err)}\`,
+      since,
+    };
+  }
+  return current;
+}
+
+/**
+ * Check on a timer, and say so ONCE per transition rather than every tick.
+ *
+ * A line every five minutes for a tunnel that has been down all night is how a
+ * log stops being read. The transition is the news.
+ */
+export function startReachabilityWatch(everyMs = 5 * 60_000): NodeJS.Timeout | null {
+  if (!probeOrigin(config.publicUrl)) {
+    report.info('[reachable] no usable publicUrl configured, so this receiver cannot check whether the internet can reach it.');
+    return null;
+  }
+  let last: Reachability['state'] = 'unknown';
+  const tick = (): void => {
+    void checkReachable().then((r) => {
+      if (r.state === last) return;
+      last = r.state;
+      if (r.state === 'unreachable') {
+        report.error(\`[reachable] NOTHING IS REACHING THIS RECEIVER. \${r.detail}. Dispatches cannot arrive while this is true.\`);
+      } else if (r.state === 'reachable') {
+        report.info('[reachable] your public URL reaches this receiver.');
+      }
+    });
+  };
+  // A first check soon after startup, not immediately: a tunnel started
+  // alongside the receiver needs a moment before it answers, and reporting it
+  // down on second one would be wrong every single time.
+  const first = setTimeout(tick, 15_000);
+  first.unref?.();
+  const timer = setInterval(tick, everyMs);
+  timer.unref?.();
+  return timer;
+}
 `
     },
     {
@@ -4177,6 +4643,7 @@ export interface CustomerStore {
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { report } from './report.js';
+import { config } from './config.js';
 import db, { accountKey, dec, enc, encrypted, ensureColumn, isEncrypted, once } from './db.js';
 import type {
   AccountVerdict,
@@ -4356,8 +4823,30 @@ function loadRoster(): RosterEntry[] {
   }
 }
 
-const ROSTER = loadRoster();
-{
+/**
+ * IN INBOX MODE NOTHING IS SEEDED, and that is a privacy fix rather than a
+ * saving.
+ *
+ * This block runs on IMPORT, and \`server.ts\` imports this module in both modes
+ * because it picks the store at runtime. So an inbox receiver - the process that
+ * exists specifically so it cannot read what it holds - was writing a full
+ * customer roster to its own database on startup: names, account numbers and
+ * the address on file for each, in the clear.
+ *
+ * The dispatches were never the leak. Those are stored as the ciphertext they
+ * arrived as, and an end-to-end run confirms the new address appears nowhere in
+ * the receiver's database file. The ROSTER was, and it was there before a
+ * single dispatch arrived. Found by searching the receiver's database bytes for
+ * a customer name after that run, which is the only check that would have found
+ * it: every other one asks the receiver what it thinks it is holding.
+ *
+ * In inbox mode the connector owns the roster and answers every account
+ * question over the loopback channel, so the receiver needs none of it.
+ */
+const ROSTER = config.mode === 'inbox' ? [] : loadRoster();
+if (config.mode === 'inbox') {
+  report.info('[store] no roster held: in inbox mode your connector owns customer records');
+} else {
   const upsert = db.prepare(\`
     INSERT INTO customers (account_key, account_number, name, address)
     VALUES ($account_key, $account_number, $name, $address)
@@ -4431,6 +4920,66 @@ export function customerCount(): number {
   return (db.prepare('SELECT COUNT(*) AS n FROM customers').get() as { n: number }).n;
 }
 
+/** One applied change: what this receiver held before, and what it holds now. */
+export interface AddressChange {
+  account_number: string;
+  name: string;
+  prev_address: Address | null;
+  address: Address;
+  recorded_at: string;
+}
+
+/**
+ * The applied changes, newest first, decrypted and joined back to the customer.
+ *
+ * ## Why this is exported rather than left to \`sqlite3\`
+ *
+ * Because \`sqlite3 data.db\` cannot answer it. Every text column here is
+ * AES-GCM ciphertext whenever the database has a password, which is the state
+ * this receiver asks for on its first run and reports in green on the
+ * dashboard. So the one question a partner has after their first real dispatch
+ * - "show me it actually changed" - had no answer short of writing code against
+ * the store. The dashboard's LAST CHANGE panel shows the most recent one and
+ * nothing shows the rest.
+ *
+ * \`prev_address\` is NULL for a row written before the column existed
+ * (\`ensureColumn\` defaults it to \`'{}'\`, which decodes to an empty object, not
+ * to an address) and for the first change on an account that had no address on
+ * file. Those are different facts and both are honestly "nothing to compare
+ * against", so both come back as null rather than as an empty address.
+ */
+export function addressHistory(limit = 20): AddressChange[] {
+  const rows = db.prepare(
+    \`SELECT h.prev_address AS prev_address,
+            h.address      AS address,
+            h.recorded_at  AS recorded_at,
+            c.account_number AS account_number,
+            c.name           AS name
+       FROM address_history h
+       LEFT JOIN customers c ON c.account_key = h.account_key
+      ORDER BY h.id DESC
+      LIMIT ?\`,
+  ).all(limit) as unknown[];
+
+  return rows.map((raw) => {
+    const r = raw as Record<string, string | null>;
+    const prevJson = dec('address', r.prev_address);
+    let prev: Address | null = null;
+    try {
+      const parsed = prevJson ? JSON.parse(prevJson) as Address : null;
+      // \`{}\` is the column default, not an address anyone held.
+      prev = parsed && Object.keys(parsed).length > 0 ? parsed : null;
+    } catch { prev = null; }
+    return {
+      account_number: dec('account_number', r.account_number) ?? '(unknown)',
+      name:           dec('name', r.name) ?? '(unknown)',
+      prev_address:   prev,
+      address:        JSON.parse(dec('address', r.address) ?? '{}') as Address,
+      recorded_at:    r.recorded_at ?? '',
+    };
+  });
+}
+
 /** Is the file on disk protected? Surfaced in the dashboard, in both states. */
 export const storeEncrypted = encrypted;
 
@@ -4623,7 +5172,8 @@ import {
 // exporting a \`CustomerStore\` (see src/customer-store.ts) and nothing else in
 // the protocol layer changes.
 import { store as writeThroughStore } from './store.js';
-import { connectorStore, setCurrentRawBody } from './connector-store.js';
+import { ALIVE_NONCE, ALIVE_PATH, startReachabilityWatch } from './reachable.js';
+import { ConnectorUnreachableError, connectorStore, setCurrentRawBody } from './connector-store.js';
 import { noteChange } from './tui.js';
 import { config } from './config.js';
 import { safeOneAddressCallbackUrl } from './callback-url.js';
@@ -4761,12 +5311,22 @@ report.info(
 // lock out every install that has never set a passphrase - but choosing it by
 // not being asked is not a choice, so the absence is stated as loudly as the
 // presence.
+//
+// AND IN INBOX MODE IT SAYS SOMETHING ELSE, for the same reason the keys line
+// above does. There are no customer records in this mode - the connector holds
+// them - so "Customer records are readable by anyone who can read the file" was
+// alarming about data that is not here, and sent the partner to set a passphrase
+// protecting nothing. \`connectorStore.encrypted\` was already hardcoded false
+// with a comment saying exactly that; this line had simply never read it.
 report.info(
-  store.encrypted
-    ? \`[startup] store: \${store.name} (encrypted at rest)\`
-    : \`[startup] store: \${store.name} \u2014 NOT ENCRYPTED AT REST. \` +
-      'Customer records are readable by anyone who can read the file. ' +
-      'Set ONEADDRESS_DB_PASSPHRASE, or run \`npm start\` in a terminal to be asked.',
+  config.mode === 'inbox'
+    ? \`[startup] store: \${store.name} \u2014 no customer records here by design. This database holds \` +
+      'dispatch ciphertext your connector decrypts, and the confirm queue.'
+    : store.encrypted
+      ? \`[startup] store: \${store.name} (encrypted at rest)\`
+      : \`[startup] store: \${store.name} \u2014 NOT ENCRYPTED AT REST. \` +
+        'Customer records are readable by anyone who can read the file. ' +
+        'Set ONEADDRESS_DB_PASSPHRASE, or run \`npm start\` in a terminal to be asked.',
 );
 
 // In-memory dedup cache. Records a dispatch id only once it has been fully
@@ -4806,11 +5366,17 @@ async function confirmToOneAddress(dispatchId: number, status: ConfirmStatus): P
   // and it drops non-numeric dispatch ids, so by the time a row is drained it
   // is a real dispatch. Keeping a second copy of that rule would mean a probe
   // could be queued forever and silently skipped on every drain.
+  // REPORTED, not "Applied". The note is fixed text sent with EVERY confirm,
+  // including \`failed\` ones - so a dispatch the connector could not open, or
+  // one refused because the account reference matched nobody, arrived at
+  // OneAddress reading "Applied by the OneAddress webhook receiver". That is
+  // read by whoever is working out what happened, and it said the opposite of
+  // \`status\` sitting beside it.
   const bodyStr = JSON.stringify({
     dispatch_id: dispatchId,
     partner_id:  PARTNER_ID,
     status,
-    note:        'Applied by the OneAddress webhook receiver',
+    note:        'Reported by the OneAddress webhook receiver',
   });
   const ts  = String(Math.floor(Date.now() / 1000));
   const sig = createHmac('sha256', CONFIRM_SECRET).update(\`\${ts}.\${bodyStr}\`).digest('hex');
@@ -4961,7 +5527,19 @@ app.post('/webhook', async (req: Request, res: Response) => {
     // and the customer records, so it answers. \`connectorStore\` sends the raw
     // body; the arguments below are the contract's shape, not its source.
     if (config.mode === 'inbox') {
-      const status = await store.verifyAccount(null, '', []);
+      let status: Awaited<ReturnType<typeof store.verifyAccount>>;
+      try {
+        status = await store.verifyAccount(null, '', []);
+      } catch (err) {
+        // 503 RATHER THAN A VERDICT. Every verdict is a claim about the
+        // customer's record; "the connector is down" is not one of them. A
+        // non-2xx is what OneAddress reads as \`unreachable\`, which the consumer
+        // sees as a transient network problem instead of "no account found".
+        if (err instanceof ConnectorUnreachableError) {
+          return res.status(503).json({ ok: false, error: 'connector_unreachable' });
+        }
+        throw err;
+      }
       report.info(\`[webhook] account.verify \u2192 \${status} (answered by the connector)\`);
       return res.status(200).json({ status });
     }
@@ -5090,7 +5668,17 @@ app.post('/webhook', async (req: Request, res: Response) => {
   if (config.mode === 'inbox' && event === 'address.verify') {
     // The contract's arguments, not its source: \`connectorStore\` sends the raw
     // body it was parked with and ignores these.
-    const result = await store.verifyAddress({ email: null, name: '' }, {});
+    let result: Awaited<ReturnType<typeof store.verifyAddress>>;
+    try {
+      result = await store.verifyAddress({ email: null, name: '' }, {});
+    } catch (err) {
+      // As above, and the callback is deliberately NOT posted: a verdict posted
+      // here would be a claim about a record nobody read.
+      if (err instanceof ConnectorUnreachableError) {
+        return res.status(503).json({ ok: false, error: 'connector_unreachable' });
+      }
+      throw err;
+    }
     report.info(\`[webhook] address.verify \u2192 \${result} (answered by the connector)\`);
     const refused = await postVerifyVerdict(result);
     if (refused) return refused;
@@ -5380,9 +5968,26 @@ app.get('/health', (_req, res) => res.json({
   encryptedAtRest: store.encrypted,
 }));
 
-app.listen(PORT, () =>
-  report.info(\`[server] OneAddress webhook server \u2192 http://localhost:\${PORT}/webhook\`),
-);
+/**
+ * The reachability probe's target. Returns this process's startup nonce as
+ * plain text, and nothing else.
+ *
+ * WHY A NONCE AND NOT \`/health\`. A stopped Cloudflare tunnel still ANSWERS -
+ * the edge serves a 1033 or a 502 error page - so a check that accepts any HTTP
+ * response reports a dead tunnel as healthy. Only this running process knows
+ * this value, so receiving it back is proof the whole path is open. See
+ * \`src/reachable.ts\`.
+ *
+ * NOT A SECRET, and nothing is gated on it: it proves which process answered,
+ * not who asked. The webhook still requires a valid HMAC.
+ */
+app.get(ALIVE_PATH, (_req, res) => res.type('text/plain').send(ALIVE_NONCE));
+
+app.listen(PORT, () => {
+  report.info(\`[server] OneAddress webhook server \u2192 http://localhost:\${PORT}/webhook\`);
+  // Started AFTER listen, or the first probe races the server it is probing.
+  startReachabilityWatch();
+});
 
 /**
  * Drain the confirm queue, forever.
@@ -5425,121 +6030,343 @@ setInterval(() => {
  * dispatch is verified, parsed, decrypted, applied and confirmed by exactly the
  * code a live one is.
  *
- * The body is byte-for-byte what arrived; only the timestamp and signature are
- * new, because the original pair is outside the \xB15-minute window by the time
- * anyone has fixed anything. We hold the secret, so re-signing is not a bypass:
- * it is the same proof, re-stated now.
+ * The body is byte-for-byte what arrived; only the timestamp and signature are
+ * new, because the original pair is outside the \xB15-minute window by the time
+ * anyone has fixed anything. We hold the secret, so re-signing is not a bypass:
+ * it is the same proof, re-stated now.
+ */
+async function redeliver(rawBody: string, heldDispatchId: string | null): Promise<void> {
+  const ts  = String(Math.floor(Date.now() / 1000));
+  const sig = createHmac('sha256', WEBHOOK_SECRET).update(\`\${ts}.\${rawBody}\`).digest('hex');
+  // THE ID THE DISPATCH ARRIVED WITH, handed over by the row being replayed.
+  // Re-deriving it from the body is what made one held dispatch become two.
+  const dispatchId = (heldDispatchId ?? '').trim();
+
+  const res = await fetch(\`http://127.0.0.1:\${PORT}/webhook\`, {
+    method: 'POST',
+    headers: {
+      'Content-Type':           'application/json',
+      'X-OneAddress-Timestamp': ts,
+      'X-OneAddress-Signature': sig,
+      ...(dispatchId ? { 'X-OneAddress-Dispatch': dispatchId } : {}),
+    },
+    body: rawBody,
+  });
+  const text = (await res.text().catch(() => '')).slice(0, 200);
+  if (!res.ok) throw new Error(\`HTTP \${res.status} \${text}\`);
+  // A 200 is not on its own success here: the handler answers \`ok: false\` with
+  // 200 when it REFUSES a dispatch (an account reference matching nobody), and
+  // treating that as applied would clear the row for an update that was never
+  // stored.
+  if (!text.includes('"ok":true')) throw new Error(\`refused: \${text}\`);
+}
+
+/** Apply everything held. Bound to [r] on the dashboard and run once at boot. */
+export async function replayQuarantined(): Promise<{ applied: number; failed: number }> {
+  return replayHeld(redeliver);
+}
+
+/**
+ * Try the backlog once, a moment after boot.
+ *
+ * Because the realistic sequence is: a key is wrong, dispatches pile up, the
+ * partner edits \`.env\`, the partner restarts. Making them find a command after
+ * that is making the recovery depend on reading documentation at the exact
+ * moment they are least inclined to. The delay lets \`listen\` settle, since this
+ * goes back in through the port.
+ */
+// \u2500\u2500 The connector channel, in inbox mode only \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+//
+// Wired here rather than in draw-api.ts because this file owns the confirm
+// queue: an acknowledgement from the connector is the moment OneAddress gets
+// told, and that has to go through the same durable queue every other confirm
+// uses so a failure to reach OneAddress is retried rather than lost.
+if (config.mode === 'inbox') {
+  setAcknowledgementHandler((dispatchId, outcome) => {
+    queueConfirm(dispatchId, outcome === 'applied' ? 'confirmed' : 'failed');
+    recordOutcome(\`d:\${dispatchId}\`, outcome === 'applied' ? 'applied' : 'failed');
+  });
+  const started = startDrawApi();
+  if (!started) {
+    // AN INBOX WITH NO WAY TO DRAIN IT IS WORSE THAN NOT STARTING. In
+    // write-through mode a missing connector token is irrelevant and the
+    // receiver runs; here it means every dispatch would be accepted and held
+    // with nothing able to collect it, and the consumer would be told nothing
+    // for as long as that lasted.
+    report.error('[startup] mode is \`inbox\` but the connector channel could not open. Refusing to start.');
+    process.exit(1);
+  }
+}
+
+setTimeout(() => {
+  if (heldCount() === 0) return;
+  void replayQuarantined().catch((err: unknown) =>
+    report.error('[replay] could not run at startup:', err),
+  );
+}, 1_500).unref();
+
+// Held payloads age out whether or not they were ever applied, which is the
+// opposite of the confirm queue one block up. The reason is what the row holds:
+// a confirm record names a dispatch, a quarantined payload is a consumer's
+// encrypted address on someone else's disk.
+const QUARANTINE_KEEP_DAYS = Number(process.env.QUARANTINE_KEEP_DAYS ?? 30);
+setInterval(() => { purgeQuarantine(QUARANTINE_KEEP_DAYS); }, 3_600_000).unref();
+
+/** How many confirms are still owed, and how the dispatches went. Read by the dashboard. */
+export { pendingConfirmCount, tally };
+
+/**
+ * Everything the dashboard footer needs, in one call.
+ *
+ * One hook rather than three, because three would be three chances for the
+ * footer to show figures from different moments.
+ */
+export function dashboardStats(): {
+  received: number;
+  applied: number;
+  failed: number;
+  mode: string;
+  awaitingConnector: number;
+  oldestUndrawn: string | null;
+} {
+  const t = tally();
+  const inbox = config.mode === 'inbox'
+    ? { count: undrawnCount(), oldest: oldestUndrawn() }
+    : { count: 0, oldest: null };
+  return {
+    ...t,
+    mode: config.mode,
+    awaitingConnector: inbox.count,
+    oldestUndrawn: inbox.oldest,
+  };
+}
+
+// Read by src/index.ts to label the dashboard. Exported rather than re-derived
+// there, so the port the UI claims is the port the server actually bound.
+export { PORT };
+export const PARTNER_NAME = process.env.PARTNER_NAME?.trim() || 'Your receiver';
+`
+    },
+    {
+      name: "src/unlock.ts",
+      content: `/**
+ * Opening a locked database: is it locked, and asking for the password.
+ *
+ * ## Why these two live in their own file
+ *
+ * Both are needed by \`src/index.ts\` (which prompts before starting the
+ * receiver) and by \`scripts/show.ts\` (which prompts before reading the roster),
+ * and a second copy of a masked-input routine is the last thing this codebase
+ * needs: the comment inside \`ask\` records TWO earlier versions that echoed the
+ * passphrase in clear, neither of which was caught by reading the code. One
+ * implementation, driven by one test.
+ *
+ * NOTHING HERE IMPORTS \`db.ts\`, and that is a constraint rather than tidiness.
+ * Importing the database derives its keys on import, so anything asking WHICH
+ * QUESTION TO PUT has to run first. \`databaseIsLocked\` therefore opens its own
+ * read-only connection.
+ */
+/**
+ * Has this database already been locked?
+ *
+ * Asked BEFORE the passphrase, and without one, so the prompt can say which of
+ * two completely different things it is doing. \`db_meta.verifier\` is written the
+ * first time a passphrase is set, so its presence is the whole answer.
+ *
+ * Read through its own connection rather than importing \`db.ts\`, which derives
+ * its keys the moment it is imported and would therefore have to run BEFORE we
+ * know what to ask for.
+ */
+export async function databaseIsLocked(): Promise<boolean> {
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    const { join } = await import('node:path');
+    const path = process.env.DB_PATH ?? join(process.cwd(), 'data.db');
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+      const row = db
+        .prepare("SELECT value FROM db_meta WHERE key = 'verifier'")
+        .get() as { value?: string } | undefined;
+      return Boolean(row?.value);
+    } finally {
+      db.close();
+    }
+  } catch {
+    // No file yet, or no db_meta table yet. Either way: not locked.
+    return false;
+  }
+}
+
+/**
+ * Ask for a passphrase without echoing it to the screen.
+ *
+ * A passphrase typed in clear on a shared screen, in a screen-share, or into a
+ * terminal that keeps scrollback is not much of a secret. readline echoes by
+ * default, so its output hook is replaced for the duration of the question.
+ *
+ * Degrades to a visible prompt rather than failing: on a terminal where the
+ * hook is not available, being asked in the clear beats not being asked.
+ */
+export async function ask(prompt: string): Promise<string> {
+  process.stdout.write(prompt);
+
+  // NO readline. Two versions of this used readline's \`_writeToOutput\` hook to
+  // mask the echo and BOTH ECHOED THE PASSPHRASE IN CLEAR, which was only found
+  // by driving a real terminal and reading what came back. The first filtered
+  // on whether the chunk contained the prompt, not knowing readline repaints
+  // prompt and input together on every keystroke, so the condition was always
+  // true. The second repainted the line and still leaked, because the echo was
+  // never coming from that hook at all.
+  //
+  // Reading the keys directly removes the guessing. Raw mode turns the
+  // terminal's own echo OFF, so the ONLY thing that can reach the screen is
+  // what is written below: one asterisk per character, which is what a partner
+  // asked for and what every other passphrase prompt does.
+  const stdin = process.stdin;
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+    // No terminal to control. Being asked in the clear beats not being asked,
+    // and this path is only reached where nothing is watching anyway.
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: stdin, output: process.stdout });
+    try {
+      const answer = await rl.question('');
+      return answer.trim();
+    } finally { rl.close(); }
+  }
+
+  const wasRaw = stdin.isRaw === true;
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.setEncoding('utf8');
+
+  return new Promise<string>((resolve) => {
+    let typed = '';
+    const restore = (): void => {
+      stdin.removeListener('data', onData);
+      stdin.setRawMode(wasRaw);
+      stdin.pause();
+    };
+    const onData = (chunk: string): void => {
+      for (const ch of chunk) {
+        if (ch === '\\r' || ch === '\\n') {
+          restore();
+          process.stdout.write('\\n');
+          resolve(typed.trim());
+          return;
+        }
+        if (ch === '\\u0003') {            // Ctrl+C
+          restore();
+          process.stdout.write('\\n');
+          process.exit(130);
+        }
+        if (ch === '\\u0004') {            // Ctrl+D on an empty line ends it
+          restore();
+          process.stdout.write('\\n');
+          resolve(typed.trim());
+          return;
+        }
+        if (ch === '\\u007f' || ch === '\\b') {
+          // Backspace has to move the asterisks too, or the mask stops matching
+          // what is actually in the buffer and the count misleads.
+          if (typed.length > 0) {
+            typed = typed.slice(0, -1);
+            process.stdout.write('\\b \\b');
+          }
+          continue;
+        }
+        if (ch < ' ') continue;          // ignore the rest of the control range
+        typed += ch;
+        process.stdout.write('*');
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+`
+    },
+    {
+      name: "scripts/show.ts",
+      content: `/**
+ * Show what this receiver holds: the roster, and every change it has applied.
+ *
+ * Usage:
+ *   npm run show          \u2014 the roster and the last 20 changes
+ *   npm run show 100      \u2014 the last 100 changes
+ *
+ * ## Why this script exists
+ *
+ * The obvious way to check that a dispatch really landed is \`sqlite3 data.db\`,
+ * and it does not work: the roster and the history are AES-GCM ciphertext
+ * whenever the database has a password, which is what this receiver asks for on
+ * its first run. Reported from a real run, immediately after a first successful
+ * dispatch: "where do I look to prove it end to end?" The dashboard's LAST
+ * CHANGE panel shows one change and nothing showed the rest.
+ *
+ * It prompts for the password for the same reason \`src/index.ts\` does, and for
+ * the same reason it must do so BEFORE importing the store: the database
+ * derives its keys on import.
+ *
+ * IN INBOX MODE THERE IS NOTHING HERE TO SHOW, and saying so is the answer
+ * rather than printing an empty table. This receiver holds no key and no
+ * customer records in that mode; the connector holds both, and the change is
+ * in the connector's own store.
  */
-async function redeliver(rawBody: string, heldDispatchId: string | null): Promise<void> {
-  const ts  = String(Math.floor(Date.now() / 1000));
-  const sig = createHmac('sha256', WEBHOOK_SECRET).update(\`\${ts}.\${rawBody}\`).digest('hex');
-  // THE ID THE DISPATCH ARRIVED WITH, handed over by the row being replayed.
-  // Re-deriving it from the body is what made one held dispatch become two.
-  const dispatchId = (heldDispatchId ?? '').trim();
+import 'dotenv/config';
+import { config } from '../src/config.js';
+import { ask, databaseIsLocked } from '../src/unlock.js';
 
-  const res = await fetch(\`http://127.0.0.1:\${PORT}/webhook\`, {
-    method: 'POST',
-    headers: {
-      'Content-Type':           'application/json',
-      'X-OneAddress-Timestamp': ts,
-      'X-OneAddress-Signature': sig,
-      ...(dispatchId ? { 'X-OneAddress-Dispatch': dispatchId } : {}),
-    },
-    body: rawBody,
-  });
-  const text = (await res.text().catch(() => '')).slice(0, 200);
-  if (!res.ok) throw new Error(\`HTTP \${res.status} \${text}\`);
-  // A 200 is not on its own success here: the handler answers \`ok: false\` with
-  // 200 when it REFUSES a dispatch (an account reference matching nobody), and
-  // treating that as applied would clear the row for an update that was never
-  // stored.
-  if (!text.includes('"ok":true')) throw new Error(\`refused: \${text}\`);
+function fmt(a: Record<string, string> | null): string {
+  if (!a) return '(nothing on file)';
+  const parts = [a.street, a.suburb, a.state, a.postcode, a.country].filter(Boolean);
+  return parts.join(', ') || '(empty)';
 }
 
-/** Apply everything held. Bound to [r] on the dashboard and run once at boot. */
-export async function replayQuarantined(): Promise<{ applied: number; failed: number }> {
-  return replayHeld(redeliver);
+async function askPassword(): Promise<void> {
+  if (process.env.ONEADDRESS_DB_PASSPHRASE?.trim()) return;
+  if (!process.stdin.isTTY) return;
+  if (!(await databaseIsLocked())) return;
+  const answer = await ask('  Password to unlock: ');
+  if (answer) process.env.ONEADDRESS_DB_PASSPHRASE = answer;
 }
 
-/**
- * Try the backlog once, a moment after boot.
- *
- * Because the realistic sequence is: a key is wrong, dispatches pile up, the
- * partner edits \`.env\`, the partner restarts. Making them find a command after
- * that is making the recovery depend on reading documentation at the exact
- * moment they are least inclined to. The delay lets \`listen\` settle, since this
- * goes back in through the port.
- */
-// \u2500\u2500 The connector channel, in inbox mode only \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-//
-// Wired here rather than in draw-api.ts because this file owns the confirm
-// queue: an acknowledgement from the connector is the moment OneAddress gets
-// told, and that has to go through the same durable queue every other confirm
-// uses so a failure to reach OneAddress is retried rather than lost.
-if (config.mode === 'inbox') {
-  setAcknowledgementHandler((dispatchId, outcome) => {
-    queueConfirm(dispatchId, outcome === 'applied' ? 'confirmed' : 'failed');
-    recordOutcome(\`d:\${dispatchId}\`, outcome === 'applied' ? 'applied' : 'failed');
-  });
-  const started = startDrawApi();
-  if (!started) {
-    // AN INBOX WITH NO WAY TO DRAIN IT IS WORSE THAN NOT STARTING. In
-    // write-through mode a missing connector token is irrelevant and the
-    // receiver runs; here it means every dispatch would be accepted and held
-    // with nothing able to collect it, and the consumer would be told nothing
-    // for as long as that lasted.
-    report.error('[startup] mode is \`inbox\` but the connector channel could not open. Refusing to start.');
-    process.exit(1);
+async function main(): Promise<void> {
+  if (config.mode === 'inbox') {
+    console.log('\\n  This receiver is in inbox mode: it holds no customer records and no key.');
+    console.log('  Your connector applied the change and holds the result. Look there.\\n');
+    return;
   }
-}
 
-setTimeout(() => {
-  if (heldCount() === 0) return;
-  void replayQuarantined().catch((err: unknown) =>
-    report.error('[replay] could not run at startup:', err),
-  );
-}, 1_500).unref();
+  await askPassword();
 
-// Held payloads age out whether or not they were ever applied, which is the
-// opposite of the confirm queue one block up. The reason is what the row holds:
-// a confirm record names a dispatch, a quarantined payload is a consumer's
-// encrypted address on someone else's disk.
-const QUARANTINE_KEEP_DAYS = Number(process.env.QUARANTINE_KEEP_DAYS ?? 30);
-setInterval(() => { purgeQuarantine(QUARANTINE_KEEP_DAYS); }, 3_600_000).unref();
+  const limit = Number(process.argv[2]) > 0 ? Number(process.argv[2]) : 20;
+  const store = await import('../src/store.js');
 
-/** How many confirms are still owed, and how the dispatches went. Read by the dashboard. */
-export { pendingConfirmCount, tally };
+  const roster = store.allCustomers();
+  console.log(\`\\n  ON FILE (\${roster.length})\\n\`);
+  for (const c of roster) {
+    let addr: Record<string, string> | null = null;
+    try { addr = JSON.parse(c.address) as Record<string, string>; } catch { addr = null; }
+    console.log(\`  \${c.account_number.padEnd(14)} \${c.name.padEnd(24)} \${fmt(addr)}\`);
+  }
 
-/**
- * Everything the dashboard footer needs, in one call.
- *
- * One hook rather than three, because three would be three chances for the
- * footer to show figures from different moments.
- */
-export function dashboardStats(): {
-  received: number;
-  applied: number;
-  failed: number;
-  mode: string;
-  awaitingConnector: number;
-  oldestUndrawn: string | null;
-} {
-  const t = tally();
-  const inbox = config.mode === 'inbox'
-    ? { count: undrawnCount(), oldest: oldestUndrawn() }
-    : { count: 0, oldest: null };
-  return {
-    ...t,
-    mode: config.mode,
-    awaitingConnector: inbox.count,
-    oldestUndrawn: inbox.oldest,
-  };
+  const changes = store.addressHistory(limit);
+  console.log(\`\\n  APPLIED CHANGES (\${changes.length}, newest first)\\n\`);
+  if (changes.length === 0) {
+    console.log('  None yet. Send a dispatch and run this again.\\n');
+    return;
+  }
+  for (const h of changes) {
+    console.log(\`  \${h.recorded_at}  \${h.account_number}  \${h.name}\`);
+    console.log(\`      was: \${fmt(h.prev_address as unknown as Record<string, string> | null)}\`);
+    console.log(\`      now: \${fmt(h.address as unknown as Record<string, string>)}\`);
+  }
+  console.log('');
 }
 
-// Read by src/index.ts to label the dashboard. Exported rather than re-derived
-// there, so the port the UI claims is the port the server actually bound.
-export { PORT };
-export const PARTNER_NAME = process.env.PARTNER_NAME?.trim() || 'Your receiver';
+void main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});
 `
     },
     {
@@ -5554,6 +6381,7 @@ export const PARTNER_NAME = process.env.PARTNER_NAME?.trim() || 'Your receiver';
 import 'dotenv/config';
 import { createPrivateKey, createPublicKey } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 
 const secret    = process.env.WEBHOOK_SECRET          ?? '';
 const partnerId = process.env.PARTNER_ID              ?? '%%PARTNER_ID%%';
@@ -5561,21 +6389,73 @@ const keyPem    = (process.env.PARTNER_PRIVATE_KEY_PEM ?? '').replace(/\\\\n/g,
 const port      = process.env.PORT ?? '3001';
 const targetUrl = process.argv[2] ?? \`http://localhost:\${port}/webhook\`;
 
-if (!secret || !partnerId || !keyPem) {
-  console.error('[test] Missing required env vars. Check your .env file.');
+/**
+ * Which shape of receiver is this?
+ *
+ * Read from the same config file the server reads, so the two cannot disagree.
+ * An inbox receiver holds NO private key - that is the property it exists for -
+ * so this runner used to die on its own env gate with "Missing required env
+ * vars. Check your .env file", telling the partner to fix a file that was
+ * exactly as the wizard wrote it. It was never run in that mode.
+ */
+let receiverMode = 'write-through';
+try {
+  const cfg = JSON.parse(readFileSync(new URL('../oneaddress.config.json', import.meta.url), 'utf8'));
+  if (cfg && typeof cfg.mode === 'string') receiverMode = cfg.mode;
+} catch {
+  // No config, or unreadable: treat it as the default, which is what every
+  // scaffold before the mode existed was.
+}
+const isInbox = receiverMode === 'inbox';
+
+if (!secret || !partnerId) {
+  console.error('[test] Missing WEBHOOK_SECRET or PARTNER_ID. Check your .env file.');
   process.exit(1);
 }
 
-let publicKeyB64: string;
-try {
-  const priv = createPrivateKey({ key: keyPem, format: 'pem' });
-  const pub  = createPublicKey(priv);
-  publicKeyB64 = pub.export({ type: 'spki', format: 'der' }).toString('base64');
-} catch (err) {
-  console.error('[test] Failed to derive public key from PARTNER_PRIVATE_KEY_PEM:', err);
+/**
+ * The public key the conformance suite encrypts to.
+ *
+ * Write-through derives it from the private key it already holds. Inbox mode
+ * has no private key to derive from, so it takes the PUBLIC half directly:
+ * a public key is not a secret, and keeping one here does not give this process
+ * the ability to read anything.
+ *
+ * Copy it from partners.oneaddress.io -> My Profile.
+ */
+const publicKeyFromEnv = (process.env.PARTNER_PUBLIC_KEY_B64 ?? '').trim();
+
+if (isInbox && !publicKeyFromEnv) {
+  console.log('[test] Inbox mode: this receiver holds no private key, so the encrypted checks');
+  console.log('[test] cannot be built here. Two ways to run them:');
+  console.log('[test]');
+  console.log('[test]   1. Set PARTNER_PUBLIC_KEY_B64 in .env (copy it from My Profile in the');
+  console.log('[test]      portal). It is a public value and safe to keep on this machine.');
+  console.log('[test]   2. Or run conformance from your connector host, which has the key.');
+  console.log('[test]');
+  console.log('[test] Signing and replay are covered by the wizard\\'s own checks either way.');
+  process.exit(0);
+}
+
+if (!isInbox && !keyPem) {
+  console.error('[test] Missing PARTNER_PRIVATE_KEY_PEM. Check your .env file.');
   process.exit(1);
 }
 
+let publicKeyB64: string;
+if (publicKeyFromEnv) {
+  publicKeyB64 = publicKeyFromEnv;
+} else {
+  try {
+    const priv = createPrivateKey({ key: keyPem, format: 'pem' });
+    const pub  = createPublicKey(priv);
+    publicKeyB64 = pub.export({ type: 'spki', format: 'der' }).toString('base64');
+  } catch (err) {
+    console.error('[test] Failed to derive public key from PARTNER_PRIVATE_KEY_PEM:', err);
+    process.exit(1);
+  }
+}
+
 console.log(\`[test] Running conformance against \${targetUrl}\\n\`);
 
 /**
@@ -5596,9 +6476,14 @@ console.log(\`[test] Running conformance against \${targetUrl}\\n\`);
  * the check would be asking a question your code is not the one answering.
  */
 const verifiesAccountReference =
-  process.env.OA_VERIFIES_ACCOUNT_REFERENCE === '1' ||
-  process.env.OA_VERIFIES_ACCOUNT_REFERENCE === 'true' ||
-  %%VERIFIES_ACCOUNT_REFERENCE%%;
+  // NEVER in inbox mode. The receiver cannot read an account reference there,
+  // so check-14 asks it a question only the connector can answer, and a
+  // correctly built system fails a check it was never the subject of.
+  !isInbox && (
+    process.env.OA_VERIFIES_ACCOUNT_REFERENCE === '1' ||
+    process.env.OA_VERIFIES_ACCOUNT_REFERENCE === 'true' ||
+    %%VERIFIES_ACCOUNT_REFERENCE%%
+  );
 
 const result = spawnSync(
   'npx',
@@ -5662,14 +6547,36 @@ computes the LOA reference with \`d5LoaRef\`, and hands it to your store as
 
 \`\`\`sql
 -- Your customer roster: who you know + the address you hold on file today.
--- Keyed on the account number. Seeded on startup from customers.json (edit that
--- file, or point loadRoster in src/store.ts at your real customer table).
-customers(account_number, name, address JSON, updated_at)
+-- Seeded on startup from customers.json (edit that file, or point loadRoster in
+-- src/store.ts at your real customer table).
+--
+-- account_key is how a row is FOUND: a blind index of the account number when
+-- the database has a password, the lower-cased number when it does not. It is
+-- the key rather than the number itself because AES-GCM uses a fresh IV per
+-- write, so two encryptions of one account number differ and a primary key over
+-- the ciphertext would enforce nothing while looking like it did.
+customers(account_key, account_number, name, address JSON, updated_at)
 
 -- Full history of every address change you apply (append-only audit trail).
-address_history(id, account_number, address JSON, recorded_at)
+-- BOTH SIDES of each change, so you can show what an address REPLACED and not
+-- only what it became.
+address_history(id, account_key, prev_address JSON, address JSON, recorded_at)
+\`\`\`
+
+### Seeing what changed
+
+\`\`\`bash
+npm run show        # the roster, and the last 20 changes (was: / now:)
+npm run show 100    # the last 100
 \`\`\`
 
+\`sqlite3 data.db\` will NOT answer this once the database has a password: every
+text column is ciphertext, which is the point. \`npm run show\` prompts for the
+same password \`npm start\` does and prints the decrypted rows.
+
+In **inbox mode** there is nothing here to show. This receiver holds no key and
+no customer records; your connector applied the change and holds the result.
+
 ## Swapping to a production database
 
 Open \`src/store.ts\` and replace the \`db\` calls with your ORM/driver of choice:
@@ -6310,7 +7217,7 @@ async def _confirm_to_oneaddress(dispatch: str, status: str) -> None:
         "dispatch_id": dispatch_id,
         "partner_id":  PARTNER_ID,
         "status":      status,
-        "note":        "Applied by the OneAddress webhook receiver",
+        "note":        "Reported by the OneAddress webhook receiver",
     })
     ts  = str(int(time.time()))
     sig = hmac_lib.new(CONFIRM_SECRET.encode(), f"{ts}.{body_str}".encode(), hashlib.sha256).hexdigest()
@@ -7325,7 +8232,7 @@ public class OneAddressWebhookController {
                 confirmBody.put("dispatch_id", dispatchId);
                 confirmBody.put("partner_id", partnerId);
                 confirmBody.put("status", status);
-                confirmBody.put("note", "Applied by the OneAddress webhook receiver");
+                confirmBody.put("note", "Reported by the OneAddress webhook receiver");
                 String bodyStr = MAPPER.writeValueAsString(confirmBody);
                 String ts = String.valueOf(System.currentTimeMillis() / 1000L);
                 String sig = OneAddressVerifier.sign(ts + "." + bodyStr, confirmSecret);
@@ -8371,7 +9278,7 @@ async Task ConfirmToOneAddress(string oneAddressApi, string confirmSecret, strin
         dispatch_id = dispatchId,
         partner_id  = pid,
         status,
-        note        = "Applied by the OneAddress webhook receiver",
+        note        = "Reported by the OneAddress webhook receiver",
     });
     var ts  = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
     var sig = Convert.ToHexString(
@@ -9473,7 +10380,7 @@ func confirmToOneAddress(oneAddressAPI, confirmSecret, partnerID, dispatch, stat
 		"dispatch_id": dispatchID,
 		"partner_id":  partnerID,
 		"status":      status,
-		"note":        "Applied by the OneAddress webhook receiver",
+		"note":        "Reported by the OneAddress webhook receiver",
 	})
 	bodyStr := string(bodyBytes)
 	ts := strconv.FormatInt(time.Now().Unix(), 10)
@@ -10257,7 +11164,7 @@ function oaConfirmToOneAddress(string $oneAddressApi, string $confirmSecret, str
         'dispatch_id' => (int) $dispatch,
         'partner_id'  => $partnerId,
         'status'      => $status,
-        'note'        => 'Applied by the OneAddress webhook receiver',
+        'note'        => 'Reported by the OneAddress webhook receiver',
     ]);
     $ts  = (string) time();
     $sig = hash_hmac('sha256', $ts . '.' . $bodyStr, $confirmSecret);
@@ -10735,10 +11642,11 @@ npx @oneaddress/conformance test %%WEBHOOK_URL%%
 };
 
 // src/scaffold.ts
-function applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken) {
+function applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken, port) {
   const filled = content.replaceAll("%%PARTNER_ID%%", partnerId).replaceAll("%%WEBHOOK_SECRET%%", webhookSecret).replaceAll("%%WEBHOOK_URL%%", webhookUrl || "<your-webhook-url>").replaceAll("%%PRIVATE_KEY%%", privateKey || "<paste your PKCS8 PEM private key here>").replaceAll("%%ONEADDRESS_API%%", oneAddressApi || "https://oneaddress.io").replaceAll("%%VERIFIES_ACCOUNT_REFERENCE%%", verifiesAccountReference ? "true" : "false").replaceAll("%%RECEIVER_MODE%%", mode === "inbox" ? "inbox" : "write-through");
-  if (mode !== "inbox") return filled;
-  const withReadme = filled.replace(
+  const withPort = applyPort(filled, port);
+  if (mode !== "inbox") return withPort;
+  const withReadme = withPort.replace(
     "## Architecture",
     `## Inbox mode
 
@@ -10773,11 +11681,17 @@ hand somebody your customers' addresses.
 CONNECTOR_TOKEN=${connectorToken || generateConnectorToken()}`
   );
 }
+function applyPort(content, port) {
+  if (!Number.isInteger(port) || port === DEFAULT_PORT) return content;
+  return content.replace(/^PORT=\d+$/m, `PORT=${port}`);
+}
+var DEFAULT_PORT = 3001;
+var RESERVED_PORTS = [3002, 3003];
 function generateConnectorToken() {
   return (0, import_node_crypto.randomBytes)(24).toString("hex");
 }
 var SENSITIVE_FILES = /* @__PURE__ */ new Set([".env"]);
-async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUrl, privateKey = "", verifiesAccountReference = false, oneAddressApi = "https://oneaddress.io", mode = "write-through", connectorToken = "") {
+async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUrl, privateKey = "", verifiesAccountReference = false, oneAddressApi = "https://oneaddress.io", mode = "write-through", connectorToken = "", port = DEFAULT_PORT) {
   const templates = TEMPLATES[platform];
   if (!templates) throw new Error(`Unknown platform: ${platform}`);
   const written = [];
@@ -10787,7 +11701,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
     if (!(0, import_node_fs.existsSync)(dir)) {
       await (0, import_promises.mkdir)(dir, { recursive: true });
     }
-    const filled = applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken);
+    const filled = applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken, port);
     const isSensitive = SENSITIVE_FILES.has((0, import_node_path.basename)(name));
     await (0, import_promises.writeFile)(dest, filled, { encoding: "utf8", mode: isSensitive ? 384 : 420 });
     if (isSensitive && process.platform !== "win32") {
@@ -10803,7 +11717,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto2 = require("crypto");
-var PKG_VERSION = true ? "2.3.0" : "dev";
+var PKG_VERSION = true ? "2.5.0" : "dev";
 var REGISTER_URL = "https://partners.oneaddress.io/api/partner/installs";
 function hmacSha256(secret, message) {
   return (0, import_node_crypto2.createHmac)("sha256", secret).update(message).digest("hex");
@@ -11054,15 +11968,17 @@ Timed out after 5 minutes.`.trim(),
 
 // src/autostart.ts
 var import_node_child_process2 = require("child_process");
-var COMMANDS2 = {
-  "ts-node": { cmd: "npx", args: ["tsx", "src/server.ts"] },
-  "python": { cmd: "uvicorn", args: ["app:app", "--port", "3001"] },
-  "go-http": { cmd: "go", args: ["run", "."] },
-  "php-laravel": { cmd: "php", args: ["artisan", "serve", "--port=3001"] },
-  "csharp-aspnet": { cmd: "dotnet", args: ["run"] },
-  "java-spring": { cmd: "mvn", args: ["spring-boot:run"] }
-  // no mvnw wrapper is scaffolded
-};
+function commandsFor(port) {
+  return {
+    "ts-node": { cmd: "npx", args: ["tsx", "src/server.ts"] },
+    "python": { cmd: "uvicorn", args: ["app:app", "--port", String(port)] },
+    "go-http": { cmd: "go", args: ["run", "."] },
+    "php-laravel": { cmd: "php", args: ["artisan", "serve", `--port=${port}`] },
+    "csharp-aspnet": { cmd: "dotnet", args: ["run"] },
+    "java-spring": { cmd: "mvn", args: ["spring-boot:run"] }
+    // no mvnw wrapper is scaffolded
+  };
+}
 var DASHBOARD_COMMANDS = {
   "ts-node": { cmd: "npx", args: ["tsx", "src/index.ts"] }
 };
@@ -11164,13 +12080,13 @@ async function pollHealth(port, timeoutMs) {
   return false;
 }
 async function startServer(platform, outputDir, port = 3001, secrets = {}) {
-  const spec = COMMANDS2[platform];
+  const spec = commandsFor(port)[platform];
   if (!spec) {
     return { ok: false, output: `No start command defined for platform: ${platform}`, manualCommand: "" };
   }
   serverOutput = "";
   const manualCommand = `cd ${outputDir} && ${spec.cmd} ${spec.args.join(" ")}`;
-  serverProcess = spawnReceiver(spec, outputDir, ["ignore", "pipe", "pipe"], secrets);
+  serverProcess = spawnReceiver(spec, outputDir, ["ignore", "pipe", "pipe"], { ...secrets, PORT: String(port) });
   serverProcess.stdout?.on("data", (d3) => {
     serverOutput += d3.toString();
   });
@@ -11217,7 +12133,7 @@ async function handOverTerminal(platform, outputDir, port, secrets = {}) {
     }
   }
   process.stdin.pause();
-  const child = spawnReceiver(spec, outputDir, "inherit", secrets);
+  const child = spawnReceiver(spec, outputDir, "inherit", { ...secrets, PORT: String(port) });
   serverProcess = child;
   return new Promise((resolve2) => {
     child.once("error", (err) => {
@@ -11747,6 +12663,25 @@ function validatePrivateKey(pem) {
 function stripControlChars(line) {
   return line.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, "");
 }
+function validatePortChoice(v2) {
+  const raw = (v2 ?? "").trim();
+  if (!raw) return void 0;
+  if (!/^\d+$/.test(raw)) return `Enter a port number, or leave blank for ${DEFAULT_PORT}`;
+  const n = Number(raw);
+  if (n < 1024 || n > 65535) return "Choose a port between 1024 and 65535";
+  if (RESERVED_PORTS.includes(n)) {
+    return `${n} is used by the connector channel. Choose another port.`;
+  }
+  return void 0;
+}
+function childEnvForMode(mode, v2) {
+  return {
+    WEBHOOK_SECRET: v2.secret,
+    PARTNER_ID: v2.partnerId,
+    VERIFIES_ACCOUNT_REFERENCE: String(v2.verifiesAccountReference),
+    ...mode === "inbox" ? { CONNECTOR_TOKEN: v2.connectorToken } : { PARTNER_PRIVATE_KEY_PEM: v2.privateKey }
+  };
+}
 async function main() {
   printHeader();
   Ie("OneAddress Partner Setup");
@@ -11796,23 +12731,6 @@ async function main() {
       "The portal rejected that secret (HTTP 401): it does not match the one on your profile.\nRegenerate it at partners.oneaddress.io -> Webhook -> Webhook signing secret\n(use Revoke and regenerate, not Rotate), copy the value shown once, and paste it here."
     );
   }
-  const privateKeyRaw = await he({
-    message: "Your ECDH Private Key",
-    placeholder: "Paste the base64 key body from My Profile, or enter a path to the .pem file",
-    validate: (v2) => {
-      if (!v2.trim()) return "Private key is required";
-      const { pem, error } = normalisePrivateKey(v2);
-      if (error) return error;
-      return validatePrivateKey(pem);
-    }
-  });
-  assertNotCancelled(privateKeyRaw);
-  const normalised = normalisePrivateKey(privateKeyRaw.trim());
-  if (normalised.error) {
-    xe(`Private key parse failed unexpectedly: ${normalised.error}`);
-    process.exit(1);
-  }
-  const privateKey = normalised.pem;
   const platform = await ve({
     message: "Which platform?",
     options: [
@@ -11829,29 +12747,6 @@ async function main() {
     ]
   });
   assertNotCancelled(platform);
-  let outDir;
-  for (; ; ) {
-    const outputDir = await he({
-      message: "Where to write the files?",
-      placeholder: "./oneaddress-webhook",
-      defaultValue: "./oneaddress-webhook"
-    });
-    assertNotCancelled(outputDir);
-    outDir = outputDir.trim() || "./oneaddress-webhook";
-    if (!(0, import_node_fs3.existsSync)(outDir) || (0, import_node_fs3.readdirSync)(outDir).length === 0) break;
-    const overwrite = await ye({
-      message: `${outDir} already has files \u2014 overwrite?`,
-      initialValue: false
-    });
-    assertNotCancelled(overwrite);
-    if (overwrite) break;
-    M2.info(`Keeping the files in ${outDir}. Enter a different directory to write into.`);
-  }
-  let accountRefReason = "";
-  const accountRefDeclaration = await getVerifiesAccountReference(pid, secret, (r2) => {
-    accountRefReason = r2;
-  });
-  const verifiesAccountReference = accountRefDeclaration === true;
   const modeChoice = platform !== "ts-node" ? "write-through" : await ve({
     message: "How should this receiver handle updates?",
     options: [
@@ -11885,6 +12780,69 @@ not your webhook secret and not your confirm secret, because those are shared wi
 OneAddress and a leak of either must not also hand somebody your customers' addresses.`
     );
   }
+  let privateKey = "";
+  if (receiverMode === "inbox") {
+    M2.info(
+      "No private key is collected for an inbox receiver. It belongs in your connector,\nwhich is the only process that decrypts. This one is meant never to hold one, and\nit refuses to start if it finds one in its environment."
+    );
+  } else {
+    const privateKeyRaw = await he({
+      message: "Your ECDH Private Key",
+      placeholder: "Paste the base64 key body from My Profile, or enter a path to the .pem file",
+      validate: (v2) => {
+        if (!v2.trim()) return "Private key is required";
+        const { pem, error } = normalisePrivateKey(v2);
+        if (error) return error;
+        return validatePrivateKey(pem);
+      }
+    });
+    assertNotCancelled(privateKeyRaw);
+    const normalised = normalisePrivateKey(privateKeyRaw.trim());
+    if (normalised.error) {
+      xe(`Private key parse failed unexpectedly: ${normalised.error}`);
+      process.exit(1);
+    }
+    privateKey = normalised.pem;
+  }
+  const portAnswer = await he({
+    message: "Which port should the receiver listen on?",
+    placeholder: String(DEFAULT_PORT),
+    defaultValue: String(DEFAULT_PORT),
+    initialValue: String(DEFAULT_PORT),
+    validate: validatePortChoice
+  });
+  assertNotCancelled(portAnswer);
+  const chosenPort = Number(String(portAnswer).trim() || DEFAULT_PORT);
+  if (!await isPortFree(chosenPort)) {
+    M2.warn(
+      `Port ${chosenPort} looks busy. Free it (lsof -i :${chosenPort} on macOS or Linux,
+netstat -ano | findstr :${chosenPort} on Windows), or change PORT in the generated
+.env afterwards. Setup will carry on either way.`
+    );
+  }
+  let outDir;
+  for (; ; ) {
+    const outputDir = await he({
+      message: "Where to write the files?",
+      placeholder: "./oneaddress-webhook",
+      defaultValue: "./oneaddress-webhook"
+    });
+    assertNotCancelled(outputDir);
+    outDir = outputDir.trim() || "./oneaddress-webhook";
+    if (!(0, import_node_fs3.existsSync)(outDir) || (0, import_node_fs3.readdirSync)(outDir).length === 0) break;
+    const overwrite = await ye({
+      message: `${outDir} already has files \u2014 overwrite?`,
+      initialValue: false
+    });
+    assertNotCancelled(overwrite);
+    if (overwrite) break;
+    M2.info(`Keeping the files in ${outDir}. Enter a different directory to write into.`);
+  }
+  let accountRefReason = "";
+  const accountRefDeclaration = await getVerifiesAccountReference(pid, secret, (r2) => {
+    accountRefReason = r2;
+  });
+  const verifiesAccountReference = accountRefDeclaration === true;
   if (accountRefDeclaration === void 0) {
     M2.warn(
       "Could not read your account-reference declaration from the portal.\n" + (accountRefReason ? "Reason: " + accountRefReason + "\n" : "") + "Conformance check-14 has been left out of the generated `npm test`, so a\npassing run does NOT mean your receiver matches account references correctly.\nSet it at partners.oneaddress.io \u2192 My Profile, then re-run this wizard."
@@ -11905,7 +12863,8 @@ OneAddress and a leak of either must not also hand somebody your customers' addr
       verifiesAccountReference,
       void 0,
       receiverMode,
-      connectorToken
+      connectorToken,
+      chosenPort
     );
     s1.stop(`Scaffolded ${written.length} files in ${outDir}`);
     for (const f of written) M2.success(`  ${f}`);
@@ -11942,22 +12901,18 @@ OneAddress and a leak of either must not also hand somebody your customers' addr
     }
     if (choice === "skip") break;
   }
-  const SERVER_PORT = 3001;
-  const portFree = await isPortFree(SERVER_PORT);
-  if (!portFree) {
-    M2.warn(
-      `Port ${SERVER_PORT} is in use. Free it (lsof -i :${SERVER_PORT} on macOS/Linux, netstat -ano | findstr :${SERVER_PORT} on Windows) and re-run the wizard, or change the PORT in ${outDir}/.env after setup completes.`
-    );
-  }
+  const childSecrets = childEnvForMode(receiverMode, {
+    secret,
+    partnerId: pid,
+    verifiesAccountReference,
+    privateKey,
+    connectorToken
+  });
+  const SERVER_PORT = chosenPort;
   const s3 = Y2();
   s3.start(`Starting server (waiting up to 15 s for /health on :${SERVER_PORT})`);
   onCleanup(stopServer);
-  const start = await startServer(platform, outDir, SERVER_PORT, {
-    WEBHOOK_SECRET: secret,
-    PARTNER_ID: pid,
-    PARTNER_PRIVATE_KEY_PEM: privateKey,
-    VERIFIES_ACCOUNT_REFERENCE: String(verifiesAccountReference)
-  });
+  const start = await startServer(platform, outDir, SERVER_PORT, childSecrets);
   let serverRunning = false;
   if (start.ok) {
     s3.stop(`Server is healthy on port ${SERVER_PORT}`);
@@ -12031,7 +12986,7 @@ Continuing will overwrite it.`
       s4.start("Starting Cloudflare Tunnel");
       onCleanup(stopTunnel);
       try {
-        let tunnel = await startTunnel(3001);
+        let tunnel = await startTunnel(SERVER_PORT);
         webhookUrl = `${tunnel.url}/webhook`;
         tunnelBase = tunnel.url;
         s4.stop(`Tunnel active: ${tunnel.url}`);
@@ -12044,7 +12999,7 @@ Continuing will overwrite it.`
         if (!webhookReady) {
           s4b.stop("First tunnel is slow to route, trying a fresh one");
           stopTunnel();
-          tunnel = await startTunnel(3001);
+          tunnel = await startTunnel(SERVER_PORT);
           webhookUrl = `${tunnel.url}/webhook`;
           tunnelBase = tunnel.url;
           const s4c = Y2();
@@ -12057,7 +13012,7 @@ Continuing will overwrite it.`
         if (!webhookReady) {
           M2.warn(
             `The tunnel edge is still not routing after a retry. This is almost always
-one of two things, and neither is your server (it is running on :3001):
+one of two things, and neither is your server (it is running on :${SERVER_PORT}):
   1. Open ${tunnel.url}/health in a browser. If it never loads, your network
      is blocking cloudflared and no wait will fix it, so try a different network.
   2. The tunnel only lives while this wizard runs, so keep this window open.`
@@ -12067,7 +13022,8 @@ one of two things, and neither is your server (it is running on :3001):
         s4.stop("Tunnel setup failed");
         M2.warn(`Could not start tunnel: ${err instanceof Error ? err.message : String(err)}`);
         M2.warn(
-          "To get a public URL manually, try: npx cloudflared tunnel --url http://localhost:3001\nOr deploy to any server and set the URL in partners.oneaddress.io \u2192 My Profile."
+          `To get a public URL manually, try: npx cloudflared tunnel --url http://localhost:${SERVER_PORT}
+Or deploy to any server and set the URL in partners.oneaddress.io \u2192 My Profile.`
         );
       }
     }
@@ -12105,7 +13061,7 @@ one of two things, and neither is your server (it is running on :3001):
     if (!webhookReady) {
       M2.warn(
         `Skipping the conformance checks: the tunnel edge is not routing.
-Your server is fine, it is running on :3001. This is either your network
+Your server is fine, it is running on :${SERVER_PORT}. This is either your network
 blocking cloudflared (open ${tunnelBase}/health in a browser to check) or the
 tunnel needing this wizard to stay open. Re-run once that URL loads in a browser.`
       );
@@ -12116,18 +13072,28 @@ tunnel needing this wizard to stay open. Re-run once that URL loads in a browser
       await new Promise((r2) => setTimeout(r2, 200));
       s6.stop("Conformance checks:");
       await runConformance(webhookUrl, pid, secret);
-      await runDecryptCheck(secret, pid);
-      if (verifiesAccountReference) {
+      if (receiverMode === "inbox") {
+        M2.info(
+          "Decrypt check skipped: this receiver holds no private key, which is what inbox\nmode is for. Your connector is the process that decrypts, so prove the key there:\nstart it against this receiver and confirm it draws and applies a dispatch."
+        );
+      } else {
+        await runDecryptCheck(secret, pid);
+      }
+      if (verifiesAccountReference && receiverMode !== "inbox") {
         M2.info(
           "You have declared that your receiver matches the account reference itself.\nRun `npm test` to include check-14, which sends an account reference that matches\nnothing and fails a receiver that reports it as applied. The three checks above\ncover signing and replay only."
         );
+      } else if (verifiesAccountReference) {
+        M2.info(
+          "You have declared that your receiver matches the account reference itself.\nIn inbox mode your CONNECTOR does that, before it applies anything, and it\nrefuses a dispatch whose reference matches none of your records. The three checks\nabove cover signing and replay only."
+        );
       }
     }
   }
   const summary = [
     `Partner ID:   ${pid}`,
     `Webhook URL:  ${webhookUrl || "(not set \u2014 update in portal)"}`,
-    `Server port:  3001`,
+    `Server port:  ${SERVER_PORT}`,
     `Files in:     ${outDir}`
   ].join("\n");
   const nextSteps = [
@@ -12142,12 +13108,7 @@ tunnel needing this wizard to stay open. Re-run once that URL loads in a browser
   if (serverRunning) {
     const openDashboard = platformHasDashboard(platform) ? await ye({ message: "Open the receiver dashboard now?", initialValue: true }) : false;
     if (openDashboard === true) {
-      const handover = await handOverTerminal(platform, outDir, SERVER_PORT, {
-        WEBHOOK_SECRET: secret,
-        PARTNER_ID: pid,
-        PARTNER_PRIVATE_KEY_PEM: privateKey,
-        VERIFIES_ACCOUNT_REFERENCE: String(verifiesAccountReference)
-      });
+      const handover = await handOverTerminal(platform, outDir, SERVER_PORT, childSecrets);
       if (!handover.ok) {
         M2.warn(
           `${handover.reason ?? "The dashboard could not start."}
@@ -12161,7 +13122,7 @@ Your receiver is set up and working. Start it yourself with:
     console.log("");
     console.log(`  ${DIM2}\u250C${"\u2500".repeat(BOX_WIDTH)}\u2510${R3}`);
     for (const inner of [
-      `  ${GRN}\u25C8${R3}  ${CRM2}Server live${R3} ${MID2}on http://localhost:3001/webhook${R3}`,
+      `  ${GRN}\u25C8${R3}  ${CRM2}Server live${R3} ${MID2}on http://localhost:${SERVER_PORT}/webhook${R3}`,
       `  ${AMB2}\u25C8${R3}  ${MID2}Edit ${CRM2}src/store.ts${R3} ${MID2}to wire your database${R3}`,
       `     ${MID2}Press Ctrl+C to stop the server and exit.${R3}`,
       ...platformHasDashboard(platform) ? [`     ${MID2}Run ${CRM2}npm start${R3} ${MID2}here any time for the dashboard.${R3}`] : []