@pellux/goodvibes-daemon 1.28.21 → 1.28.22

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to the GoodVibes daemon.
 
+## [1.28.22] - 2026-08-21
+
+### Changes
+
+- **Interrupted checkouts are disclosed at boot.** sdk 2.0.20's
+  `registerPaymentsGatewayMethods` runs a recovery sweep over the durable
+  checkout journal before attaching the payment verbs: a checkout the last
+  process died holding is settled by its journaled phase (`not-submitted`
+  released, `possibly-submitted` disclosed to the owner once, `submitted`
+  reconciled against the purchase ledger) instead of being forgotten. The
+  daemon's five local handlers now attach after that sweep through the new
+  `{ ready, unregister }` registration shape, so the sdk's deferred attach can
+  never replace them, and a teardown that runs before attachment completes
+  leaves no handler behind. Recovery outcomes land on the daemon log through
+  the sdk's `onRecoveryFailure`/`onRecoverySettled` hooks.
+- **Approving a purchase is a real recorded act.** The new
+  `payments.checkout.approve` verb (ws-only, confirm-gated, owner-direct from
+  its own code path) mints a single-use, content-bound approval with a
+  five-minute TTL, persisted in `payments-approvals.json`; `checkout.begin`
+  spends exactly one or refuses with `OWNER_APPROVAL_REQUIRED` naming the
+  verb. Approvals ride sdk 2.0.20's `checkOwnerApproval`, which now compares
+  the content fingerprint whenever one is present and the caller names the
+  content in question, independent of taint clearing.
+- **In-flight checkouts survive restarts.** The checkout registry writes
+  every phase to `payments-checkout-journal.json` before proceeding — the
+  `submit-pending` flush lands on disk before the merchant submit — so a
+  crash in the one ambiguous window leaves a record the boot sweep can
+  disclose instead of nothing. Unknown journal fields round-trip untouched.
+- **Help text tells the truth** about update checks and auth file paths.
+
 ## [1.28.21] - 2026-08-21
 
 ### Changes

package/README.md

@@ -2,10 +2,10 @@
 
 [![CI](https://github.com/mgd34msu/goodvibes-daemon/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-daemon/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-1.28.20-blue.svg)](https://github.com/mgd34msu/goodvibes-daemon)
+[![Version](https://img.shields.io/badge/version-1.28.21-blue.svg)](https://github.com/mgd34msu/goodvibes-daemon)
 
-The GoodVibes daemon: one long-running process per machine that holds the control plane every
-GoodVibes client talks to. It:
+The GoodVibes daemon is the one long-running process per machine that holds the control plane
+every GoodVibes client talks to. It:
 
 - answers the operator verb families over HTTP
 - reads and replies on your channels
@@ -13,6 +13,8 @@ GoodVibes client talks to. It:
   shared inbox
 - runs scheduled and triggered work
 - keeps the session, memory, knowledge and code-index stores
+- serves the payment verbs, with stored cards, a daily budget that survives a restart,
+  and checkouts driven through the browser it operates
 - provisions the local voice and wake-word models
 - updates itself at an idle moment, with a rollback if the new binary will not start
 
@@ -25,11 +27,23 @@ here.
 A **product** over `@pellux/goodvibes-sdk`, exactly like the TUI and the agent are:
 
 - the composition root that builds the daemon's service graph,
-- the product handlers the SDK does not own (inbox, triage, drafts, routing, remote peers,
-  credentials),
-- the CLI (`send`, `cluster`, `webui`, `provision-wake-model`, `install-service` and friends),
+- the product handler families the SDK does not own, tabled below,
+- the CLI, every command of which is documented in
+  [docs/commands-reference.md](docs/commands-reference.md),
 - packaging: the compiled `goodvibes-daemon-<os>-<arch>` binaries.
 
+The handler families under `src/daemon/handlers/`:
+
+| Family | What it serves |
+| --- | --- |
+| inbox | `channels.inbox.list`, the unified inbound-message list, with provider adapters for Slack, Discord and email |
+| triage | the email auto-tag and spam-triage pass that decorates the inbox list with persisted triage metadata |
+| drafts | `channels.drafts.*`, daemon-mirrored channel drafts for cross-device sync, webhook values stored redacted |
+| routing | `channels.routing.*`, the daemon-persisted channel-to-profile routing table |
+| remote | `remote.peers.*`, the peer registry and the dispatcher routing work to docker, ssh, cloud-terminal and local-process backends |
+| credentials | the daemon credential store that resolves `goodvibes://secrets/...` references for the other handlers |
+| payments | the `payments.*` verbs: cards, budget, purchase ledger, owner approvals and browser checkout |
+
 Every engine (the facade, the routes, the brokers, the updater, the channel adapters, the
 schedulers) lives in the SDK and is consumed from the published package. Nothing was moved out of
 the SDK to build this repository, and nothing should be: a capability that both a client and the
@@ -37,7 +51,8 @@ daemon need belongs in the SDK, not here.
 
 ## Version line
 
-The daemon's version is **1.28.0**. Live installs already carry a settings reader-floor
+The daemon versions on the continuous **1.28** line; this release is **1.28.21**. Live
+installs already carry a settings reader-floor
 (`$goodvibes.minReaderVersion`), the update handover compares versions monotonically, and the
 rejected-version record is keyed by version. Those three mechanics all depend on the version
 line staying continuous and monotonically increasing.
@@ -50,7 +65,8 @@ curl -fsSL https://goodvibes.sh/install.sh | sh
 
 This installs the whole GoodVibes suite (the daemon, the terminal app, the
 agent, and the browser operator surface) from checksum-verified binaries,
-with no package manager involved.
+with no package manager involved. The product-by-product table of what
+lands from where is in [docs/getting-started.md](docs/getting-started.md#install).
 
 The browser surface is not a fourth binary and not a fourth service: the bundle
 unpacks to `<install dir>/webui/<version>` and this daemon serves it on its own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-daemon",
-  "version": "1.28.21",
+  "version": "1.28.22",
   "description": "The GoodVibes daemon \u2014 the one long-running host for the control plane, channels, cluster membership, scheduled work, knowledge and memory stores, and the verb families every GoodVibes client calls.",
   "type": "module",
   "main": "src/daemon/cli.ts",
@@ -67,8 +67,8 @@
     "@anthropic-ai/bedrock-sdk": "^0.28.1",
     "@anthropic-ai/sdk": "^0.82.0",
     "@ast-grep/napi": "^0.42.0",
-    "@pellux/goodvibes-sdk": "2.0.19",
-    "@pellux/goodvibes-terminal-shell": "2.0.19",
+    "@pellux/goodvibes-sdk": "2.0.20",
+    "@pellux/goodvibes-terminal-shell": "2.0.20",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/cli/command-catalog.ts

@@ -134,7 +134,7 @@ export const GLOBAL_FLAGS: readonly DaemonCommandFlagSpec[] = [
     field: 'daemonHome',
     kind: 'string',
     valueName: 'dir',
-    summary: "The daemon's own identity directory (operator tokens, auth users, daemon settings).",
+    summary: "The daemon's own identity directory (operator tokens, daemon settings).",
   },
   {
     tokens: ['--working-dir', '--cd', '-C'],
@@ -554,16 +554,17 @@ export const DAEMON_COMMANDS: readonly DaemonCommandSpec[] = [
       'updates and restarts, the version an automatic rollback rejected (if any), and',
       'whether a rollback is currently in force.',
       '',
-      '--check asks the daemon to look for a new release now. The daemon checks hourly',
-      'on its own and swaps only at an idle moment; this command exists for the case',
-      'where you do not want to wait for the next hour.',
+      '--check is honest about a gap: the control plane publishes no verb to trigger',
+      'an update check early, so it says so plainly and names the two things that do',
+      'work: waiting for the hourly check, or restarting the service, which checks on',
+      'the way up.',
       '',
       'The rollback and receipt lines are read from files the daemon writes on its own',
       'host, so they are reported for a local daemon and named as unavailable for a',
       'remote one.',
     ],
     flags: [
-      { tokens: ['--check'], field: 'check', kind: 'boolean', summary: 'Ask for an update check now instead of waiting for the hourly one.' },
+      { tokens: ['--check'], field: 'check', kind: 'boolean', summary: 'Explain that no early-check verb exists, and name the two paths that work.' },
       JSON_FLAG,
       ...REMOTE_TARGET_FLAGS,
     ],

package/src/daemon/cli.ts

@@ -74,7 +74,7 @@ type DaemonCliOwnership = {
   readonly workingDirectory: string;
   /** The GoodVibes tree root, settings, workspace, and discovery all hang off this. */
   readonly homeDirectory: string;
-  /** The daemon's OWN identity home (auth users, operator tokens, daemon settings). */
+  /** The daemon's OWN identity home (operator tokens, daemon settings). */
   readonly daemonHomeDirectory: string;
   /** True when GOODVIBES_HOME or GOODVIBES_DAEMON_HOME named an override, see goodvibes-home.ts. */
   readonly isOverridden: boolean;
@@ -91,7 +91,7 @@ type DaemonCliTokens = {
  * Two different directories that used to be one.
  *
  * `GOODVIBES_DAEMON_HOME` names the DAEMON's home, the identity directory
- * holding auth-users.json, operator-tokens.json, and daemon-settings.json. That
+ * holding operator-tokens.json and the daemon tier's settings.json. That
  * is what the name says and what the SDK's `resolveDaemonHomeDir()` has always
  * meant by it. This function used to read it as the GoodVibes tree ROOT, so
  * setting it relocated settings, workspace, and every discovery root as well,
@@ -372,7 +372,7 @@ async function main(): Promise<void> {
   // derivation: `daemonHomeDirectory` is this process's own resolution of
   // `--daemon-home`/`GOODVIBES_DAEMON_HOME`, and the two must agree so the
   // daemon's config reads and writes the same file its identity state
-  // (operator-tokens.json, auth-users.json) already lives beside.
+  // (operator-tokens.json) already lives beside.
   const config = new ConfigManager({
     workingDir,
     homeDir: homeDirectory,

package/src/daemon/handlers/payments/approval-store.ts

@@ -0,0 +1,275 @@
+/**
+ * approval-store.ts, the persisted owner approvals a checkout spends.
+ *
+ * ── What this holds ───────────────────────────────────────────────────────
+ *
+ * `OwnerApproval` records the SDK's own factory minted (`grantOwnerApproval`,
+ * platform/security/owner-approval.ts), one per purchase the owner has
+ * approved and `payments.checkout.begin` has not yet consumed. The SDK's
+ * `OwnerApprovalStore` keeps them in process memory, which is right for a
+ * surface whose gesture and action share a process. This daemon's approve
+ * verb and its begin verb are separate control-plane calls that may straddle
+ * a daemon restart, so the records live in a file, the same convention every
+ * other payments store here follows (`payments-cards.json` and friends,
+ * composed by runtime/payments-composition.ts).
+ *
+ * ── The four properties, kept ─────────────────────────────────────────────
+ *
+ * The SDK's ruling names four properties and this store must not weaken any:
+ *
+ *  1. Owner-direct only: `grant` passes `surface: 'owner-direct'` from ITS
+ *     OWN code path, never from an argument, so nothing a caller sends can
+ *     name a different surface. The verb that calls `grant` is itself behind
+ *     this daemon's confirmation gate (`assertConfirmed`, register.ts).
+ *  2. Content-bound: the fingerprint is the SDK's, over the exact fields the
+ *     owner approved, and `take` matches with `checkOwnerApproval`, never by
+ *     action id alone.
+ *  3. Short-lived: TTL is the SDK's `OWNER_APPROVAL_TTL_MS` (five minutes),
+ *     not configurable through the wire, and expired records are swept on
+ *     every access and at load.
+ *  4. Single use: `take` removes what it returns, and the removal is
+ *     persisted before the approval is handed back, so a taken approval
+ *     cannot be respent after a restart. A persist that fails rolls the
+ *     removal back and throws, leaving the approval intact rather than in a
+ *     state where memory and disk disagree about whether it is spendable.
+ *
+ * ── Durability conventions ────────────────────────────────────────────────
+ *
+ * Same as `DurableBudgetLedger` (budget-store.ts): a missing file is the
+ * ordinary first-boot case and starts empty silently; a file that exists but
+ * cannot be parsed, or does not hold this store's shape, is data loss for a
+ * store that authorizes spending, so it is logged as a warning naming the
+ * file and the store starts empty; entries that fail the record checks are
+ * dropped with a warning rather than trusted. Writes are atomic
+ * (`atomicWriteFileSync`, mode 0600).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { atomicWriteFileSync } from '@pellux/goodvibes-sdk/platform/config';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import {
+  checkOwnerApproval,
+  grantOwnerApproval,
+  type ApprovalMismatch,
+  type OwnerApproval,
+} from '@pellux/goodvibes-sdk/platform/security';
+
+const APPROVALS_FILE_VERSION = 1;
+
+/**
+ * Bounded the way the SDK's own store is: a caller that mints without
+ * spending must not grow the file without limit. The oldest grant is evicted
+ * to make room, which is also the least spendable one, since TTLs expire in
+ * grant order.
+ */
+const MAX_PENDING_APPROVALS = 16;
+
+interface ApprovalsFile {
+  readonly version: number;
+  readonly approvals: readonly OwnerApproval[];
+}
+
+function isOwnerApproval(value: unknown): value is OwnerApproval {
+  if (typeof value !== 'object' || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return typeof record['action'] === 'string'
+    && typeof record['grantedAt'] === 'string'
+    && typeof record['expiresAt'] === 'string'
+    && Number.isFinite(Date.parse(record['expiresAt'] as string))
+    && record['surface'] === 'owner-direct'
+    && (record['contentFingerprint'] === null || typeof record['contentFingerprint'] === 'string');
+}
+
+/** Read the persisted approvals, or an empty list for "start empty". */
+function loadInitialApprovals(filePath: string): OwnerApproval[] {
+  if (!existsSync(filePath)) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (error) {
+    logger.warn(
+      'Owner-approval file could not be read; starting with no pending approvals rather than guessing. '
+      + 'Any approval granted before this must be granted again.',
+      { filePath, error: error instanceof Error ? error.message : String(error) },
+    );
+    return [];
+  }
+  if (
+    typeof parsed !== 'object'
+    || parsed === null
+    || !Array.isArray((parsed as Partial<ApprovalsFile>).approvals)
+  ) {
+    logger.warn(
+      'Owner-approval file does not hold the expected shape; starting with no pending approvals rather than guessing.',
+      { filePath },
+    );
+    return [];
+  }
+  const rows = (parsed as ApprovalsFile).approvals;
+  const approvals = rows.filter(isOwnerApproval);
+  if (approvals.length !== rows.length) {
+    logger.warn(
+      'Owner-approval file held entries that do not match the approval record shape; those entries were '
+      + 'dropped rather than trusted.',
+      { filePath },
+    );
+  }
+  return approvals;
+}
+
+/** What `take` reports when nothing matched, so the refusal can say which way it missed. */
+export interface ApprovalTakeMiss {
+  readonly approval: null;
+  readonly mismatch: ApprovalMismatch;
+}
+
+export interface ApprovalTakeHit {
+  readonly approval: OwnerApproval;
+}
+
+/**
+ * The persisted, single-use, content-bound approvals this daemon's checkout
+ * spends. See the module header for the properties this must keep.
+ */
+export class DaemonApprovalStore {
+  private approvals: OwnerApproval[];
+
+  constructor(
+    private readonly filePath: string,
+    private readonly now: () => Date = () => new Date(),
+  ) {
+    this.approvals = loadInitialApprovals(filePath);
+    // Load-time sweep: an approval that expired while the daemon was down is
+    // not spendable and not worth carrying. Quiet, and only writes when it
+    // actually dropped something.
+    if (this.sweep()) this.persist();
+  }
+
+  /**
+   * Record an approval the owner has just given.
+   *
+   * `surface: 'owner-direct'` is supplied HERE, from the code path, which is
+   * the property the SDK's factory exists to enforce; no argument of this
+   * method can name a surface. Throws when the record cannot be persisted,
+   * rolling the in-memory grant back first: an approval the disk never saw
+   * must not be spendable from memory, or a restart changes what the owner
+   * authorized.
+   */
+  grant(input: {
+    readonly action: string;
+    readonly content: Readonly<Record<string, string | undefined>>;
+  }): OwnerApproval {
+    this.sweep();
+    const approval = grantOwnerApproval({
+      action: input.action,
+      surface: 'owner-direct',
+      content: input.content,
+      now: this.now,
+    });
+    // Unreachable through this class (the surface above is fixed), kept as a
+    // thrown error rather than a narrowing cast so a future SDK change that
+    // makes the factory refuse for a new reason fails loudly here.
+    if (approval === null) throw new Error('grantOwnerApproval refused an owner-direct grant');
+    const evicted = this.approvals.length >= MAX_PENDING_APPROVALS ? this.approvals.shift() : undefined;
+    this.approvals.push(approval);
+    try {
+      this.persist();
+    } catch (error) {
+      this.approvals.pop();
+      if (evicted) this.approvals.unshift(evicted);
+      throw error;
+    }
+    if (evicted) {
+      logger.warn(
+        'Owner-approval store was full; the oldest pending approval was evicted to record this one.',
+        { filePath: this.filePath, evictedAction: evicted.action, evictedGrantedAt: evicted.grantedAt },
+      );
+    }
+    return approval;
+  }
+
+  /**
+   * Spend the one approval matching this action and payload, if one is held.
+   *
+   * Removes what it returns, and persists the removal BEFORE returning, so a
+   * spent approval is spent on disk too. A miss reports the closest mismatch
+   * so the refusal can tell the owner whether to approve again (expired,
+   * none) or to check what they approved (different content).
+   */
+  take(input: {
+    readonly action: string;
+    readonly content: Readonly<Record<string, string | undefined>>;
+  }): ApprovalTakeHit | ApprovalTakeMiss {
+    let closest: ApprovalMismatch = 'none';
+    for (let index = 0; index < this.approvals.length; index += 1) {
+      const candidate = this.approvals[index]!;
+      const verdict = checkOwnerApproval({
+        approval: candidate,
+        action: input.action,
+        contentInQuestion: input.content,
+        // Deliberately `true` even though no taint finding is being cleared:
+        // the SDK's check only compares the content fingerprint under this
+        // flag (`checkOwnerApproval`, owner-approval.ts), and without the
+        // comparison an unexpired approval authorizes by ACTION ID alone,
+        // which is exactly the "matching on the verb, not on the deed"
+        // failure the ruling names. Setting it also refuses the weak,
+        // fingerprint-less form (`no-content-binding`), which this store
+        // never mints but must not honor if one appears in the file.
+        clearingContentTaint: true,
+        now: this.now,
+      });
+      if (verdict.authorized) {
+        this.approvals.splice(index, 1);
+        try {
+          this.persist();
+        } catch (error) {
+          this.approvals.splice(index, 0, candidate);
+          throw error;
+        }
+        return { approval: candidate };
+      }
+      closest = closerMismatch(closest, verdict.mismatch);
+    }
+    // Swept AFTER matching, not before: an approval that expired must be
+    // reported as `expired` (the owner approves again), not silently dropped
+    // first and reported as `none` (the owner is told nothing was approved).
+    // The sweep still runs on every miss, so expired records do not linger.
+    if (this.sweep()) this.persist();
+    return { approval: null, mismatch: closest };
+  }
+
+  /** Whether anything is currently spendable, for a status line or a test. */
+  pendingCount(): number {
+    this.sweep();
+    return this.approvals.length;
+  }
+
+  /** Drop expired records. Returns true when it dropped any. */
+  private sweep(): boolean {
+    const nowMs = this.now().getTime();
+    const before = this.approvals.length;
+    this.approvals = this.approvals.filter((approval) => Date.parse(approval.expiresAt) > nowMs);
+    return this.approvals.length !== before;
+  }
+
+  private persist(): void {
+    const contents: ApprovalsFile = { version: APPROVALS_FILE_VERSION, approvals: this.approvals };
+    atomicWriteFileSync(this.filePath, `${JSON.stringify(contents, null, 2)}\n`, { mode: 0o600, mkdirp: true });
+  }
+}
+
+/**
+ * Which mismatch is the more useful one to name, when several records each
+ * missed differently. Content mismatches beat expiry beats wrong-action beats
+ * nothing-held, because each earlier one implies the owner did something
+ * closer to approving THIS purchase.
+ */
+function closerMismatch(current: ApprovalMismatch, candidate: ApprovalMismatch): ApprovalMismatch {
+  const rank: Record<ApprovalMismatch, number> = {
+    'none': 0,
+    'different-action': 1,
+    'expired': 2,
+    'no-content-binding': 3,
+    'different-content': 4,
+  };
+  return rank[candidate] > rank[current] ? candidate : current;
+}

package/src/daemon/handlers/payments/budget-store.ts

@@ -177,8 +177,9 @@ function loadInitialState(filePath: string): BudgetStateSnapshot | undefined {
       { filePath },
     );
   }
-  // Named, not just counted: there is no durable journal for a reservation
-  // (unlike the checkout journal's own disclosed gap, see register.ts), so this
+  // Named, not just counted: a reservation has no per-purchase narrative of
+  // its own here (the checkout journal, checkout-journal-store.ts, records
+  // the purchase's phases; this file records only the pools), so this
   // log line is the only record an operator has, at restart, of money that is
   // currently held against the daily limit for a purchase that may or may not
   // still be in flight. Reconciling it against what the merchant actually

package/src/daemon/handlers/payments/checkout-handlers.ts

@@ -40,6 +40,7 @@ import type { UntrustedContentLedger } from '@pellux/goodvibes-sdk/platform/secu
 import type { BrowserCheckoutSeam } from '../contracts.ts';
 import { HandlerError } from '../errors.ts';
 import type { TypedHandler } from '../register.ts';
+import type { DaemonApprovalStore } from './approval-store.ts';
 import type { DaemonCardStore } from './card-store.ts';
 import type { PaymentsHandlerDeps } from './register.ts';
 
@@ -70,6 +71,20 @@ export interface CheckoutComposition {
   readonly merchantJudge: MerchantJudgePort;
   /** The process-wide ledger; see routes/browser-composition.ts's header for why it must be shared, not private. */
   readonly untrusted: UntrustedContentLedger;
+  /**
+   * The persisted, single-use approvals `payments.checkout.approve` mints and
+   * `payments.checkout.begin` spends. See approval-store.ts for the four
+   * properties the store keeps, and `checkoutBeginHandler` below for where
+   * one is consumed.
+   */
+  readonly approvals: DaemonApprovalStore;
+  /**
+   * The journal the shared service's in-flight registry writes through. The
+   * real daemon composes `DurableCheckoutJournal`
+   * (checkout-journal-store.ts) so a `submit-pending` record survives a
+   * restart; tests may compose the SDK's `MemoryCheckoutJournal`.
+   */
+  readonly journal: CheckoutJournal;
 }
 
 function invalid(field: string, requirement: string): HandlerError {
@@ -386,6 +401,128 @@ const CHECKOUT_UNAVAILABLE_MESSAGE =
   + 'configured, or the browser composition has not finished starting). Retry once the daemon has finished '
   + 'booting; if this persists, the daemon was started without a home directory to keep browser profiles in.';
 
+/**
+ * The action an owner approval authorizes: one `payments.checkout.begin`.
+ * The approve verb mints against this constant and `begin` spends against it,
+ * so the two can never drift into approving one verb and spending on another.
+ */
+export const CHECKOUT_APPROVAL_ACTION = 'payments.checkout.begin';
+
+/**
+ * The exact fields an approval binds, built the same way on both sides.
+ *
+ * On the approve side the values are what the owner typed; on the begin side
+ * they are read from the begin call itself (`merchantDomain`, `item`,
+ * `requestedMax`). One builder for both is what makes the fingerprint a
+ * comparison of the deed rather than two modules' ideas of it.
+ */
+export function checkoutApprovalContent(input: {
+  readonly merchantDomain: string;
+  readonly item: string;
+  readonly amount: string | undefined;
+}): Readonly<Record<string, string | undefined>> {
+  return { merchant: input.merchantDomain, item: input.item, amount: input.amount };
+}
+
+/** How a begin call names the approve verb when it refuses, per mismatch. */
+function approvalRefusalMessage(mismatch: string): string {
+  if (mismatch === 'expired') {
+    return 'The owner approval for this purchase has expired. Approvals last five minutes: call '
+      + 'payments.checkout.approve again with the same merchantDomain, item and amount, then begin promptly.';
+  }
+  if (mismatch === 'different-content' || mismatch === 'no-content-binding') {
+    return 'The owner approval on file was for a different purchase: its merchant, item or amount does not '
+      + 'match this begin call (the amount is compared against requestedMax). Call payments.checkout.approve '
+      + 'with exactly what this begin call names, then begin again.';
+  }
+  return 'This purchase has no owner approval on file. A human approves it first, out of band from this '
+    + 'call: invoke payments.checkout.approve with this purchase\'s merchantDomain, item and amount (the '
+    + 'begin call\'s requestedMax), then begin within five minutes.';
+}
+
+/**
+ * Spend the one approval matching this begin call, or refuse naming the
+ * approve verb. Consuming before the service runs is the sdk store's own
+ * safe direction: an approval taken for a begin that then refuses on a later
+ * gate is spent, never silently reusable.
+ */
+function consumeCheckoutApproval(
+  approvals: DaemonApprovalStore,
+  input: { readonly merchantDomain: string; readonly item: string; readonly requestedMax?: string | undefined },
+): void {
+  let taken: ReturnType<DaemonApprovalStore['take']>;
+  try {
+    taken = approvals.take({
+      action: CHECKOUT_APPROVAL_ACTION,
+      content: checkoutApprovalContent({
+        merchantDomain: input.merchantDomain,
+        item: input.item,
+        amount: input.requestedMax,
+      }),
+    });
+  } catch (error) {
+    // A store that could not persist the removal rolled it back and threw
+    // (approval-store.ts): the approval is still on file and nothing was
+    // submitted. Contained: the raw error can name the store path.
+    void error;
+    throw new HandlerError(
+      'Recording the spent approval failed. The approval was not consumed and nothing was submitted.',
+      'INTERNAL_ERROR',
+      500,
+    );
+  }
+  if (taken.approval === null) {
+    throw new HandlerError(approvalRefusalMessage(taken.mismatch), 'OWNER_APPROVAL_REQUIRED', 403);
+  }
+}
+
+/**
+ * `payments.checkout.approve`.
+ *
+ * The distinct act the sdk's owner-approval ruling requires: a HUMAN, on a
+ * surface with command authority, names one purchase and approves it. The
+ * registration (register.ts) puts this handler behind the same confirmation
+ * gate every destructive verb in this daemon uses (`confirm: true` in the
+ * body AND the explicit-user-request context flag), and the handler passes
+ * `surface: 'owner-direct'` from its own code path, never from an argument,
+ * which is the property `grantOwnerApproval` exists to enforce.
+ *
+ * The minted record is persisted (approval-store.ts), single-use, bound to
+ * the exact merchant + item + amount fields named here, and expires in five
+ * minutes. `payments.checkout.begin` spends it; see `checkoutBeginHandler`.
+ */
+export function checkoutApproveHandler(deps: PaymentsHandlerDeps): TypedHandler<unknown, Record<string, unknown>> {
+  return async ({ body }) => {
+    const params = asRecord(body);
+    const merchantDomain = requireString(params['merchantDomain'], 'merchantDomain');
+    const item = requireString(params['item'], 'item');
+    const amount = requireString(params['amount'], 'amount');
+    let approval;
+    try {
+      approval = deps.checkout.approvals.grant({
+        action: CHECKOUT_APPROVAL_ACTION,
+        content: checkoutApprovalContent({ merchantDomain, item, amount }),
+      });
+    } catch (error) {
+      // Contained for the same reason as `consumeCheckoutApproval`: the raw
+      // write failure can name the store path, and an approval that never
+      // reached disk was deliberately rolled back rather than left spendable.
+      void error;
+      throw new HandlerError('Recording the approval failed. Nothing was approved.', 'INTERNAL_ERROR', 500);
+    }
+    // Named fields, never a spread, the same containment rule as every other
+    // response in this family.
+    return {
+      approved: true,
+      action: CHECKOUT_APPROVAL_ACTION,
+      merchantDomain,
+      item,
+      amount,
+      expiresAt: approval.expiresAt,
+    };
+  };
+}
+
 /** The sdk's own explicit nine-field projection (routes/payments.ts's `createPaymentsCheckoutBeginHandler`), not a spread. */
 function beginResultView(result: Awaited<ReturnType<PaymentsGatewayServiceImpl['beginCheckout']>>): Record<string, unknown> {
   return {
@@ -417,29 +554,34 @@ function beginResultView(result: Awaited<ReturnType<PaymentsGatewayServiceImpl['
  * (`security/turn-boundary.ts`), a second, separate effect of the same
  * caller-set claim, not something this handler arranges.
  *
- * This composition used to also arm `seam.armSubmitApproval` here, minting an
- * `OwnerApproval` for a `'payments.checkout.submit'` action whenever
- * `explicitUserRequest` was true. That mechanism has been deleted: it never
- * actually did anything. The browser engine only ever checks an armed
- * approval's action against the literal string `'browser.submit'`
- * (browser-engine.ts), so an approval minted for `'payments.checkout.submit'`
- * never matched it and the check always fell through to `different-action`.
- * Even with the names made to agree, an approval minted here with no
- * `content` argument carries `contentFingerprint: null`, the WEAK form
- * (`owner-approval.ts`), which clears only a refusal that was itself made
- * without content and never a content-derivation finding, so repairing the
- * name would still not have cleared anything real. A distinct, genuine
- * owner-approval record for a purchase, minted from a separate interactive
- * act and bound to the exact payload approved, is real future work (see
- * `.goodvibes/memory/decisions.json`), and a mechanism that LOOKED like that
- * record while clearing nothing was worse than having none.
+ * ── The genuine owner-approval record, consumed here ───────────────────────
+ *
+ * Behind that outer gate sits the distinct-act approval the sdk's
+ * owner-approval ruling describes (platform/security/owner-approval.ts): a
+ * persisted record that a human called `payments.checkout.approve`, out of
+ * band from whatever conversation produced this begin call, naming ONE
+ * purchase by merchant, item and amount. This handler spends exactly one
+ * matching record per begin (`DaemonApprovalStore.take`, approval-store.ts:
+ * single-use, content-bound via the sdk's own fingerprint, five-minute TTL)
+ * and refuses, naming the approve verb, when none matches. The record is
+ * consumed BEFORE the service runs, which is the sdk store's own safe
+ * direction: a taken approval whose begin then refuses on a later gate is
+ * spent, never quietly retried.
+ *
+ * The binding fields are `merchantDomain`, `item` and `requestedMax`, read
+ * from THIS begin call and fingerprinted the same way the approve verb
+ * fingerprinted what the owner typed, so a begin whose merchant, item or
+ * amount differs from what was approved is `different-content`, not a match.
+ * An earlier mechanism that armed `seam.armSubmitApproval` with a
+ * content-free approval was deleted rather than shipped, because an approval
+ * with no content binding clears nothing real; this record is the strong
+ * form, minted with the exact fields.
  *
- * The real money controls, downstream of this gate, are the sdk's own
- * checkout ladder: the budget ledger (RESERVE, step 5), the purchase notices
- * and their approval/veto decision windows (NOTICE + WINDOW, step 6), and the
- * card-material guard (`cardFieldGuard`, armed only immediately before
- * typing, never before). See `checkout-flow.ts`'s own header for the full
- * order.
+ * The money controls downstream of both gates are unchanged: the budget
+ * ledger (RESERVE, step 5), the purchase notices and their approval/veto
+ * decision windows (NOTICE + WINDOW, step 6), and the card-material guard
+ * (`cardFieldGuard`, armed only immediately before typing, never before).
+ * See `checkout-flow.ts`'s own header for the full order.
  */
 export function checkoutBeginHandler(deps: PaymentsHandlerDeps, holder: CheckoutServiceHolder): TypedHandler<unknown, Record<string, unknown>> {
   return async ({ body, context }) => {
@@ -451,6 +593,16 @@ export function checkoutBeginHandler(deps: PaymentsHandlerDeps, holder: Checkout
       throw new HandlerError(CHECKOUT_UNAVAILABLE_MESSAGE, 'FAILED_PRECONDITION', 409);
     }
 
+    // The approval is only consulted INSIDE the outer explicitUserRequest
+    // layer: a call that never claimed to be owner-direct falls through to
+    // the service, whose own gate refuses it `refused:not-owner-request`
+    // exactly as before this record existed. Consuming an approval for a
+    // call that outer layer was always going to refuse would spend the
+    // owner's answer on nothing.
+    if (context.explicitUserRequest) {
+      consumeCheckoutApproval(deps.checkout.approvals, input);
+    }
+
     const [usableCard, shippingAddress] = await Promise.all([
       hasUsableCard(deps.cards, input.cardId),
       hasShippingAddress(deps.checkout.addresses),

package/src/daemon/handlers/payments/checkout-journal-store.ts

@@ -0,0 +1,162 @@
+/**
+ * checkout-journal-store.ts, the in-flight checkout journal, durable across a
+ * restart.
+ *
+ * ── The defect this closes ────────────────────────────────────────────────
+ *
+ * The composition used to hand `PaymentsGatewayServiceImpl` the SDK's own
+ * `MemoryCheckoutJournal`, documented "durable across nothing". The phase
+ * ladder in checkout-registry.ts exists for exactly one ambiguous moment: a
+ * crash between the `submit-pending` flush and the merchant's response. With
+ * an in-memory journal that flush kept nothing, so a restart could never say
+ * "this purchase may already have been submitted, do not resubmit it". This
+ * file is the durable journal that record was waiting for.
+ *
+ * ── The contract this implements ──────────────────────────────────────────
+ *
+ * The SDK's `CheckoutJournal` (checkout-registry.ts): `put` must not return
+ * until the record would survive a power cut, `remove` drops one by
+ * purchaseId, `list` returns what is held. `put` here writes through
+ * `atomicWriteFileSync` (a synchronous rename-into-place) before resolving,
+ * which is the flush the `submit-pending` guarantee rides on; a `put` whose
+ * write fails THROWS, because a journal that reports durable-and-was-not
+ * turns that guarantee into a comment.
+ *
+ * `remove` is the one deliberate asymmetry: its write failure is logged and
+ * swallowed rather than thrown. By the time `remove` runs the checkout is
+ * finished or abandoned; failing the caller would turn a completed purchase's
+ * report into an error over a cleanup write, and the stale record it leaves
+ * on disk fails in the safe direction, a restart discloses a checkout that
+ * needs checking rather than forgetting one that does. The in-memory removal
+ * stands either way, and the next successful `put`/`remove` rewrites the file
+ * without the stale record.
+ *
+ * ── Unknown fields ride along untouched ───────────────────────────────────
+ *
+ * Records are persisted and reloaded as the objects they arrive as, not
+ * projected through this module's idea of the record shape. Only
+ * `purchaseId` (the removal key) is checked at load; every other field,
+ * including fields added by an SDK this build has never seen, round-trips
+ * byte-for-byte. The repin that teaches
+ * the SDK to recover these records must find everything its writer put here,
+ * not everything this file knew to keep.
+ *
+ * ── Corruption is a warning, not a crash ──────────────────────────────────
+ *
+ * Same conventions as `DurableBudgetLedger` (budget-store.ts): a missing file
+ * starts empty silently; a file that exists but cannot be parsed or does not
+ * hold this shape is logged as a warning naming the file, and the journal
+ * starts empty rather than taking the daemon down. Entries without a string
+ * `purchaseId` are dropped with a warning, since nothing could ever remove
+ * them.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { atomicWriteFileSync } from '@pellux/goodvibes-sdk/platform/config';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { CheckoutJournal, InFlightCheckout } from '@pellux/goodvibes-sdk/platform/payments';
+
+const JOURNAL_FILE_VERSION = 1;
+
+interface JournalFile {
+  readonly version: number;
+  readonly records: readonly Record<string, unknown>[];
+}
+
+/** The two fields this module actually reads; everything else is opaque cargo. */
+function hasJournalKeys(value: unknown): value is Record<string, unknown> & { purchaseId: string } {
+  return typeof value === 'object'
+    && value !== null
+    && !Array.isArray(value)
+    && typeof (value as Record<string, unknown>)['purchaseId'] === 'string';
+}
+
+/** Read the persisted records, keyed by purchaseId, or empty for "start empty". */
+function loadInitialRecords(filePath: string): Map<string, Record<string, unknown>> {
+  const records = new Map<string, Record<string, unknown>>();
+  if (!existsSync(filePath)) return records;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (error) {
+    logger.warn(
+      'Checkout journal file could not be read; starting with no in-flight checkouts rather than guessing. '
+      + 'If a purchase was mid-submit when this daemon last stopped, check that merchant\'s order history by hand.',
+      { filePath, error: error instanceof Error ? error.message : String(error) },
+    );
+    return records;
+  }
+  if (
+    typeof parsed !== 'object'
+    || parsed === null
+    || !Array.isArray((parsed as Partial<JournalFile>).records)
+  ) {
+    logger.warn(
+      'Checkout journal file does not hold the expected shape; starting with no in-flight checkouts rather than guessing.',
+      { filePath },
+    );
+    return records;
+  }
+  const rows = (parsed as JournalFile).records;
+  for (const row of rows) {
+    if (hasJournalKeys(row)) {
+      records.set(row.purchaseId, row);
+    }
+  }
+  if (records.size !== rows.length) {
+    logger.warn(
+      'Checkout journal file held entries with no purchaseId; those entries were dropped rather than trusted, '
+      + 'since nothing could ever remove them.',
+      { filePath },
+    );
+  }
+  return records;
+}
+
+/**
+ * The durable `CheckoutJournal` this daemon composes. See the module header
+ * for the contract and the conventions.
+ */
+export class DurableCheckoutJournal implements CheckoutJournal {
+  private readonly records: Map<string, Record<string, unknown>>;
+
+  constructor(private readonly filePath: string) {
+    this.records = loadInitialRecords(filePath);
+  }
+
+  /** Durable before it resolves; throws when the write does not land. */
+  async put(record: InFlightCheckout): Promise<void> {
+    const previous = this.records.get(record.purchaseId);
+    this.records.set(record.purchaseId, record as unknown as Record<string, unknown>);
+    try {
+      this.persist();
+    } catch (error) {
+      if (previous === undefined) this.records.delete(record.purchaseId);
+      else this.records.set(record.purchaseId, previous);
+      throw error;
+    }
+  }
+
+  /** Removes in memory always; a failed cleanup write is logged, never thrown. See the header. */
+  async remove(purchaseId: string): Promise<void> {
+    if (!this.records.delete(purchaseId)) return;
+    try {
+      this.persist();
+    } catch (error) {
+      logger.warn(
+        'Checkout journal could not be rewritten after removing a finished checkout. The stale record stays on '
+        + 'disk until the next journal write lands; at worst a restart reports a checkout that needs checking '
+        + 'when it was already complete, never the reverse.',
+        { filePath: this.filePath, purchaseId, error: error instanceof Error ? error.message : String(error) },
+      );
+    }
+  }
+
+  async list(): Promise<readonly InFlightCheckout[]> {
+    return [...this.records.values()] as unknown as readonly InFlightCheckout[];
+  }
+
+  private persist(): void {
+    const contents: JournalFile = { version: JOURNAL_FILE_VERSION, records: [...this.records.values()] };
+    atomicWriteFileSync(this.filePath, `${JSON.stringify(contents, null, 2)}\n`, { mode: 0o600, mkdirp: true });
+  }
+}

package/src/daemon/handlers/payments/index.ts

@@ -26,6 +26,13 @@ export type { DaemonPurchaseLedgerOptions, PurchaseListQuery, StoredPurchase } f
 
 export { DurableBudgetLedger } from './budget-store.ts';
 
+export { DaemonApprovalStore } from './approval-store.ts';
+export type { ApprovalTakeHit, ApprovalTakeMiss } from './approval-store.ts';
+
+export { DurableCheckoutJournal } from './checkout-journal-store.ts';
+
+export { CHECKOUT_APPROVAL_ACTION, checkoutApprovalContent } from './checkout-handlers.ts';
+
 export { configBackedAddressStore } from './address-store.ts';
 export { channelBackedPaymentNotifier } from './notifier.ts';
 export { createProviderBackedMerchantJudgeModel } from './merchant-judge.ts';

package/src/daemon/handlers/payments/register.ts

@@ -77,8 +77,8 @@
  * from a call that had material in its arguments.
  */
 import type { BudgetLedger, PaymentsConfigReader } from '@pellux/goodvibes-sdk/platform/payments';
-import { MemoryCheckoutJournal, readDefaultCardId, readPaymentsEnabled, readPaymentsServiceConfig } from '@pellux/goodvibes-sdk/platform/payments';
-import type { CardMetadata, CheckoutJournal } from '@pellux/goodvibes-sdk/platform/payments';
+import { readDefaultCardId, readPaymentsEnabled, readPaymentsServiceConfig } from '@pellux/goodvibes-sdk/platform/payments';
+import type { CardMetadata } from '@pellux/goodvibes-sdk/platform/payments';
 import {
   registerPaymentsGatewayMethods,
   type GatewayMethodCatalog,
@@ -88,7 +88,7 @@ import {
 } from '../contracts.ts';
 import { HandlerError } from '../errors.ts';
 import { registerCatalogHandlers, type TypedHandler, type Unregister } from '../register.ts';
-import { CheckoutServiceHolder, checkoutBeginHandler, checkoutFillCardHandler, type CheckoutComposition } from './checkout-handlers.ts';
+import { CheckoutServiceHolder, checkoutApproveHandler, checkoutBeginHandler, checkoutFillCardHandler, type CheckoutComposition } from './checkout-handlers.ts';
 import { CardStoreUnreadableError, type DaemonCardStore } from './card-store.ts';
 import { MAX_PURCHASE_LIST_LIMIT, type DaemonPurchaseLedger, type StoredPurchase } from './purchase-ledger.ts';
 
@@ -101,10 +101,65 @@ export const ATTACHED_PAYMENTS_METHOD_IDS: readonly string[] = [
   'payments.cards.create',
   'payments.cards.delete',
   'payments.purchases.list',
+  'payments.checkout.approve',
   'payments.checkout.begin',
   'payments.checkout.fillCard',
 ];
 
+/**
+ * The one descriptor in this family this PRODUCT authors, because the id is
+ * product-owned: the SDK's catalog holds the seven `payments.*` verbs it
+ * ships and no `payments.checkout.approve`, and the approve act is this
+ * daemon's own composition (its store, its confirmation gate, its wire
+ * shape). contracts.ts's never-author-a-descriptor rule is about not
+ * RE-declaring an SDK id, which this is not; the parity test
+ * (gateway-verb-family-parity.test.ts) pins this id the same way it pins the
+ * rest, so it cannot drift in silently.
+ */
+const CHECKOUT_APPROVE_DESCRIPTOR: GatewayMethodDescriptor = {
+  id: 'payments.checkout.approve',
+  title: 'Approve One Purchase',
+  description:
+    'Record that a human approves one specific purchase, out of band from the conversation that will run '
+    + 'it: the merchant\'s registrable domain, the item, and the amount (the same string a later begin call '
+    + 'passes as requestedMax). Mints a persisted, single-use approval bound to exactly those fields, '
+    + 'expiring in five minutes; payments.checkout.begin consumes it and refuses without one. Requires '
+    + 'confirm: true and the explicit-user-request context, the same confirmation gate every destructive '
+    + 'verb on this daemon uses. The response never carries card material; this verb never touches a card '
+    + 'at all. ws-only invoke verb; no REST binding: the gateway REST table is the daemon-sdk\'s and this '
+    + 'product cannot add rows to it, the same shape sessions.hosted.* already has.',
+  category: 'payments',
+  source: 'builtin',
+  access: 'admin',
+  transport: ['ws'],
+  scopes: ['write:payments'],
+  dangerous: true,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      confirm: { type: 'boolean' },
+      merchantDomain: { type: 'string' },
+      item: { type: 'string' },
+      amount: { type: 'string' },
+    },
+    required: ['confirm', 'merchantDomain', 'item', 'amount'],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      approved: { type: 'boolean' },
+      action: { type: 'string' },
+      merchantDomain: { type: 'string' },
+      item: { type: 'string' },
+      amount: { type: 'string' },
+      expiresAt: { type: 'string' },
+    },
+    required: ['approved', 'action', 'merchantDomain', 'item', 'amount', 'expiresAt'],
+    additionalProperties: false,
+  },
+};
+
 /**
  * Kept, empty, rather than deleted: `gateway-payments-verbs.test.ts` and
  * `register.test.ts` iterate this to assert the unattached set, and an empty
@@ -378,8 +433,27 @@ function buildPaymentsGatewayService(deps: PaymentsHandlerDeps): PaymentsGateway
 // ---------------------------------------------------------------------------
 
 /**
- * Attach the seven `payments.*` handlers to the descriptors the SDK catalog
- * already holds. Returns the teardown.
+ * What `registerPaymentsMethods` returns now that attachment has an async
+ * phase. `unregister` is valid immediately, including before `ready` settles.
+ * `ready` resolves once every handler is attached and REJECTS if attaching the
+ * local handlers failed, so the caller that drops it must handle the
+ * rejection (daemon-handler-composition.ts logs it; tests await it).
+ */
+export interface PaymentsRegistration {
+  readonly ready: Promise<void>;
+  readonly unregister: Unregister;
+}
+
+/**
+ * Attach the eight `payments.*` handlers: seven to the descriptors the SDK
+ * catalog already holds, and `payments.checkout.approve` to the one
+ * descriptor this product authors (see `CHECKOUT_APPROVE_DESCRIPTOR` above).
+ *
+ * The SDK's `registerPaymentsGatewayMethods` runs its boot recovery sweep
+ * before attaching, so it returns a promise and attaches a beat after this
+ * function returns. This module's five local handlers MUST attach after that,
+ * or the SDK's deferred attach would replace them, so they are chained on the
+ * SDK's promise and `ready` is how a caller observes the whole sequence.
  *
  * NOT gated on `payments.enabled`. That key defaults to false, and
  * `payments.cards.*` is how a surface CONFIGURES the capability, so gating
@@ -392,7 +466,7 @@ function buildPaymentsGatewayService(deps: PaymentsHandlerDeps): PaymentsGateway
 export function registerPaymentsMethods(
   catalog: GatewayMethodCatalog,
   deps: PaymentsHandlerDeps,
-): Unregister {
+): PaymentsRegistration {
   // Every descriptor this module attaches to, captured BEFORE any
   // registration runs. `registerCatalogHandlers`' own teardown (used below for
   // four of these) removes the DESCRIPTOR from the catalog entirely rather
@@ -410,34 +484,39 @@ export function registerPaymentsMethods(
 
   const service = buildPaymentsGatewayService(deps);
 
-  // Attaches all seven `payments.*` descriptors. budget/list/delete stay
-  // attached through this; create/purchases-list/checkout-begin/checkout-
-  // fillCard are all transiently attached here and immediately replaced below
-  // with this daemon's own local handlers. See the header comment for why
-  // each group needs its own wrapper.
-  registerPaymentsGatewayMethods(catalog, service);
+  // Attaches all seven `payments.*` descriptors once its boot recovery sweep
+  // finishes. budget/list/delete stay attached through this; create/purchases-
+  // list/checkout-begin/checkout-fillCard are transiently attached and then
+  // replaced with this daemon's own local handlers in the chain below. The
+  // hook payloads are the SDK's designed audit records: the failure callback
+  // never carries a notice body and the sweep envelope exists to be logged.
+  const sdkAttach = registerPaymentsGatewayMethods(catalog, service, {
+    onRecoveryFailure: (error) => {
+      console.error('payments boot recovery failed', { error });
+    },
+    onRecoverySettled: (sweep) => {
+      console.info('payments boot recovery settled', { sweep });
+    },
+  });
 
   // The journal backing this registration's checkout pair's in-flight
   // registry (the SDK's own `CheckoutRegistry`, built inside
   // `PaymentsGatewayServiceImpl`'s constructor from whatever `CheckoutJournal`
-  // it is handed, see checkout-handlers.ts's `buildCheckoutService`; this
-  // value here is the journal, not the registry itself). `MemoryCheckoutJournal`
-  // (the sdk's own, checkout-registry.ts, documented "durable across nothing")
-  // is a deliberate choice for THIS pass, not an oversight: a durable journal
-  // is real work (a file or store write on every `registry.advance`, including
-  // the `submit-pending` flush checkout-flow.ts's step 9 makes right before the
-  // merchant submit) that has not been done yet. The gap it leaves is exactly
-  // the one that flush exists to close: if this process crashes between that
-  // `submit-pending` write and seeing the merchant's response, a restart with a
-  // durable journal could tell the owner "this purchase may already have been
-  // submitted, do not resubmit it"; with this in-memory journal, that record is
-  // gone the moment the process is, and a restart has no way to know the
-  // purchase was ever in flight at all. Recorded as future work in
-  // `.goodvibes/memory/decisions.json`, not implied to be solved here.
-  const checkoutJournal: CheckoutJournal = new MemoryCheckoutJournal();
-  // The ONE checkout service instance this registration's begin/fillCard pair
-  // share for their whole life; see checkout-handlers.ts's own header.
-  const checkoutServiceHolder = new CheckoutServiceHolder(deps, checkoutJournal);
+  // it is handed, see checkout-handlers.ts's `buildCheckoutService`). It comes
+  // from the composition (`deps.checkout.journal`), which in the real daemon
+  // is `DurableCheckoutJournal` (checkout-journal-store.ts): every phase write
+  // the registry makes, including the `submit-pending` flush checkout-flow.ts's
+  // step 9 issues right before the merchant submit, lands on disk before the
+  // submit happens, so a restart after a crash in that window can tell the
+  // owner "this purchase may already have been submitted, do not resubmit it"
+  // instead of having no record the purchase was ever in flight. Tests compose
+  // the SDK's `MemoryCheckoutJournal` here instead, which is what the seam in
+  // `CheckoutComposition` is for.
+  //
+  // The ONE checkout service instance this registration's approve/begin/
+  // fillCard verbs share for their whole life; see checkout-handlers.ts's own
+  // header.
+  const checkoutServiceHolder = new CheckoutServiceHolder(deps, deps.checkout.journal);
 
   const cardsCreate: TypedHandler<unknown, Record<string, unknown>> = async ({ body }) => {
     const params = asRecord(body);
@@ -492,27 +571,61 @@ export function registerPaymentsMethods(
     });
   };
 
-  const localTeardown = registerCatalogHandlers(catalog, [
-    { id: 'payments.cards.create', handler: cardsCreate as TypedHandler<unknown, unknown> },
-    { id: 'payments.purchases.list', handler: purchasesList as TypedHandler<unknown, unknown> },
-    { id: 'payments.checkout.begin', handler: checkoutBeginHandler(deps, checkoutServiceHolder) as TypedHandler<unknown, unknown> },
-    { id: 'payments.checkout.fillCard', handler: checkoutFillCardHandler(deps, checkoutServiceHolder) as TypedHandler<unknown, unknown> },
-  ]);
-
-  return () => {
-    localTeardown();
-    // Restores EVERY descriptor this module attached to, handler-less, not
-    // only the three `registerPaymentsGatewayMethods` still holds a live
-    // handler on. The other four had their descriptor removed outright by
-    // `localTeardown()` above (see the `descriptors` capture at the top of
-    // this function for why), so without this a re-registration on the SAME
-    // catalog (a second `registerPaymentsMethods` call, as a restart-without-
-    // recompose test does) would find those four ids gone from the catalog
-    // and throw `METHOD_NOT_FOUND` trying to attach to them, rather than
-    // finding the SDK's own builtin descriptor there to replace, exactly as
-    // it would on a catalog this module had never touched.
+  // Restores EVERY descriptor this module attached to, handler-less, not
+  // only the three `registerPaymentsGatewayMethods` still holds a live
+  // handler on. The other four have their descriptor removed outright by
+  // `localTeardown()` (see the `descriptors` capture at the top of this
+  // function for why), so without this a re-registration on the SAME catalog
+  // (a second `registerPaymentsMethods` call, as a restart-without-recompose
+  // test does) would find those four ids gone from the catalog and throw
+  // `METHOD_NOT_FOUND` trying to attach to them, rather than finding the
+  // SDK's own builtin descriptor there to replace, exactly as it would on a
+  // catalog this module had never touched.
+  const restoreDescriptors = (): void => {
     for (const [, descriptor] of descriptors) {
       catalog.register(descriptor, undefined, { replace: true });
     }
   };
+
+  let torn = false;
+  let localTeardown: Unregister | undefined;
+
+  const ready = sdkAttach.then(() => {
+    // Teardown already ran: the SDK's attach (which resolved just before this
+    // callback) put live handlers back on descriptors the teardown had
+    // restored handler-less, so restore them again instead of attaching the
+    // local handlers to a surface that was already released.
+    if (torn) {
+      restoreDescriptors();
+      return;
+    }
+    // The approve descriptor is product-authored (see its declaration above),
+    // so it is placed on the catalog here, handler-less, exactly where the
+    // SDK's own descriptors already sit, and then attached through the same
+    // `registerCatalogHandlers` path as the other local wrappers. `replace:
+    // true` so a registration over a catalog that already carries it (a
+    // recompose that skipped teardown) replaces rather than throws.
+    catalog.register(CHECKOUT_APPROVE_DESCRIPTOR, undefined, { replace: true });
+
+    localTeardown = registerCatalogHandlers(catalog, [
+      { id: 'payments.cards.create', handler: cardsCreate as TypedHandler<unknown, unknown> },
+      { id: 'payments.purchases.list', handler: purchasesList as TypedHandler<unknown, unknown> },
+      // The confirmation gate (`confirm: true` AND the explicit-user-request
+      // context) is what makes this verb owner-direct: the handler then passes
+      // `surface: 'owner-direct'` from its own code path. See
+      // checkout-handlers.ts's `checkoutApproveHandler`.
+      { id: 'payments.checkout.approve', handler: checkoutApproveHandler(deps) as TypedHandler<unknown, unknown>, options: { confirm: true } },
+      { id: 'payments.checkout.begin', handler: checkoutBeginHandler(deps, checkoutServiceHolder) as TypedHandler<unknown, unknown> },
+      { id: 'payments.checkout.fillCard', handler: checkoutFillCardHandler(deps, checkoutServiceHolder) as TypedHandler<unknown, unknown> },
+    ]);
+  });
+
+  return {
+    ready,
+    unregister: () => {
+      torn = true;
+      localTeardown?.();
+      restoreDescriptors();
+    },
+  };
 }

package/src/runtime/daemon-handler-composition.ts

@@ -92,7 +92,8 @@ export function createDaemonHandlerComposition(
     // provider only carries the teardown. See payments-composition.ts for the
     // full checkout composition (address store, notifier, merchant judge,
     // browser-checkout seam).
-    registerPayments: () => createPaymentsServices({
+    registerPayments: () => {
+      const payments = createPaymentsServices({
       gatewayMethods: options.gatewayMethods,
       configManager: options.configManager,
       secretsManager: options.secretsManager,
@@ -127,7 +128,15 @@ export function createDaemonHandlerComposition(
       checkoutSeam: options.checkoutSeam,
       channelDeliveryRouter: options.channelDeliveryRouter,
       providerRegistry: options.providerRegistry,
-    }).unregister,
+      });
+      // The payments verbs attach a beat after composition (the SDK's boot
+      // recovery sweep runs first); this composition stays synchronous, so
+      // the rejection path is handled here rather than awaited.
+      payments.ready.catch((error) => {
+        handlerLogger.error('payments handler attach failed', { error });
+      });
+      return payments.unregister;
+    },
     registerRemote: (ctx) => registerRemoteSurface(ctx, { manager: options.distributedRuntime }),
   });
 }

package/src/runtime/legacy-daemon-migration.ts

@@ -162,7 +162,7 @@ export function buildManagedDaemonServiceManager(params: BuildManagedDaemonServi
     workingDirectory,
     command: params.binaryPath,
     // `--daemon-home` names the daemon's own STATE directory, the one holding
-    // operator-tokens.json, auth-users.json and daemon-settings.json, which is
+    // operator-tokens.json and the daemon tier's settings.json, which is
     // `<home>/.goodvibes/daemon`. This baked the USER HOME, so a serviced
     // daemon filed its identity a level above where every reader in this
     // repository looks: the SDK's platform/config goodvibes-home resolves the flag AS the state

package/src/runtime/payments-composition.ts

@@ -80,9 +80,11 @@ import type { ChannelDeliveryRouter } from '@pellux/goodvibes-sdk/platform/chann
 import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
 import type { ShellPathService } from '@/runtime/index.ts';
 import {
+  DaemonApprovalStore,
   DaemonCardStore,
   DaemonPurchaseLedger,
   DurableBudgetLedger,
+  DurableCheckoutJournal,
   channelBackedPaymentNotifier,
   configBackedAddressStore,
   createProviderBackedMerchantJudgeModel,
@@ -118,6 +120,13 @@ export interface PaymentsServices {
   readonly cards: DaemonCardStore;
   readonly purchases: DaemonPurchaseLedger;
   readonly budget: BudgetLedger;
+  /**
+   * Resolves once every payments verb is attached; the SDK runs its boot
+   * recovery sweep first, so attachment lands a beat after composition.
+   * Rejects if attaching the daemon's local handlers failed, so whoever drops
+   * this promise must handle that (daemon-handler-composition.ts logs it).
+   */
+  readonly ready: Promise<void>;
   /** Detaches the handlers. Held by the runtime disposal scope. */
   readonly unregister: () => void;
 }
@@ -174,8 +183,22 @@ export function createPaymentsServices(options: PaymentsCompositionOptions): Pay
     notifier: channelBackedPaymentNotifier(config, options.channelDeliveryRouter),
     merchantJudge: createModelMerchantJudge(createProviderBackedMerchantJudgeModel(options.providerRegistry)),
     untrusted: getProcessUntrustedContentLedger(),
+    // The persisted owner approvals `payments.checkout.approve` mints and
+    // `begin` spends, beside the other payments stores. Constructing it reads
+    // the file once, synchronously, the same one-touch boot cost the budget
+    // ledger already pays.
+    approvals: new DaemonApprovalStore(
+      controlPlaneStorePath(options.shellPaths, GOODVIBES_DAEMON_SURFACE_ROOT, 'payments-approvals.json'),
+    ),
+    // The durable in-flight checkout journal. Every phase write the registry
+    // makes, the `submit-pending` flush before the merchant submit included,
+    // lands here before the flow proceeds, so a crash in the one ambiguous
+    // window leaves a record a restart can disclose instead of nothing.
+    journal: new DurableCheckoutJournal(
+      controlPlaneStorePath(options.shellPaths, GOODVIBES_DAEMON_SURFACE_ROOT, 'payments-checkout-journal.json'),
+    ),
   };
-  const unregister = registerPaymentsMethods(options.gatewayMethods, {
+  const registration = registerPaymentsMethods(options.gatewayMethods, {
     cards,
     purchases,
     budget,
@@ -183,5 +206,5 @@ export function createPaymentsServices(options: PaymentsCompositionOptions): Pay
     isPaymentsLeader: options.isPaymentsLeader,
     checkout,
   });
-  return { cards, purchases, budget, unregister };
+  return { cards, purchases, budget, ready: registration.ready, unregister: registration.unregister };
 }