@pellux/goodvibes-daemon 1.28.20 → 1.28.22

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 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
+
+- **The checkout verbs answer.** `payments.checkout.begin` and
+  `payments.checkout.fillCard` attach through sdk 2.0.19's browser-checkout
+  seam: one payments service per registration holds the in-flight checkout
+  registry across both verbs, a second begin on a busy page refuses, and the
+  card-material guard is the engine's own instance end to end. Without a
+  merchant-response reader wired, purchase outcomes record honestly as
+  `submitted-unverified` and the owner report says so. `explicitUserRequest`
+  gates entry to `begin` and is documented as what it is: a caller assertion,
+  no stronger than a confirm flag; the money controls are the budget ledger,
+  the purchase notices and decision windows, and the card-material guard.
+- **The daily budget survives restarts.** Reservations and commits persist
+  atomically to `payments-budget.json` and reload at boot; corrupt or
+  malformed entries (including non-finite or out-of-range amounts and
+  timestamps) are dropped with a warning instead of poisoning the pools; a
+  commit whose disk write fails keeps the in-memory spend, logs the exposure
+  plainly, and retries on the next mutation, so a full disk cannot erase a
+  spend that already happened at the merchant; a failed reserve rolls back
+  rather than holding budget; old spend records prune at boot; loaded
+  reservations are disclosed at startup for reconciliation.
+- **Five payments verbs ride the sdk registrar.** `budget.status`,
+  `cards.list` and `cards.delete` attach through sdk 2.0.19's
+  `registerPaymentsGatewayMethods`; `cards.create` and `purchases.list` keep
+  thin local wrappers over the same service for stricter field-named
+  validation and query-string limits. Wire behavior for all five is pinned
+  byte-identical by the contract suites. Teardown restores all seven
+  descriptors to their pristine builtin state.
+- Platform runtime 2.0.19: the pin rides the checkout-seam and wake-fix
+  cycle; this daemon serves the repaired `voice.wake.model.get`, which fixes
+  wake-word model delivery for every surface that fetches models from it.
+
 ---
 
 ## [1.28.20] - 2026-08-21

package/README.md

@@ -2,14 +2,21 @@
 
 [![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.14-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 answers the operator verb families over HTTP, reads and replies on
-your channels, elects a leader among the machines you have grouped together so only one of them
-answers a shared inbox, runs scheduled and triggered work, keeps the session, memory, knowledge
-and code-index stores, provisions the local voice and wake-word models, and updates itself at an
-idle moment with a rollback if the new binary will not start.
+[![Version](https://img.shields.io/badge/version-1.28.21-blue.svg)](https://github.com/mgd34msu/goodvibes-daemon)
+
+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
+- elects a leader among the machines you have grouped together, so only one of them answers a
+  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
 
 The terminal app (`goodvibes`), the conversational agent (`goodvibes-agent`) and the web app are
 clients of this process. They render, they capture input, and they call verbs; the work happens
@@ -20,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
@@ -32,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.
@@ -45,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.20",
+  "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.18",
-    "@pellux/goodvibes-terminal-shell": "2.0.18",
+    "@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",
@@ -89,7 +89,7 @@
     "web-tree-sitter": "^0.26.7"
   },
   "devDependencies": {
-    "@pellux/goodvibes-toolchain": "2.0.18",
+    "@pellux/goodvibes-toolchain": "2.0.19",
     "@types/bun": "^1.3.10",
     "typescript": "^5.9.3"
   },

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/contracts.ts

@@ -17,6 +17,21 @@ export type {
   GatewayMethodHandler,
 } from '@pellux/goodvibes-sdk/platform/control-plane';
 
+// The SDK's own `payments.*` route module: the registrar and the service seam
+// it dispatches to. Exported by the SDK barrel as of 2.0.18 (CHANGELOG). Three
+// of the seven verbs attach through this unchanged; see
+// daemon/handlers/payments/register.ts and checkout-handlers.ts for why the
+// other four (`cards.create`, `purchases.list`, `checkout.begin`,
+// `checkout.fillCard`) stay local wrappers instead.
+export { registerPaymentsGatewayMethods } from '@pellux/goodvibes-sdk/platform/control-plane';
+export type { PaymentsGatewayService, PaymentPurchaseView } from '@pellux/goodvibes-sdk/platform/control-plane';
+
+// The browser-checkout seam a daemon composition receives through
+// `onBrowserCheckout` (sdk 2.0.19, platform/control-plane's
+// `composeDaemonBrowser`). See daemon/handlers/payments/register.ts for how
+// the checkout pair reads it.
+export type { BrowserCheckoutSeam } from '@pellux/goodvibes-sdk/platform/control-plane';
+
 // Channel domain types reused in handler signatures (read-only SDK interfaces; never re-declared).
 export type {
   ChannelIdentity,

package/src/daemon/handlers/index.ts

@@ -57,7 +57,7 @@ export interface DaemonHandlerSurfaceProviders {
   /** channels.drafts.* */
   readonly registerDrafts: SurfaceRegister;
   /**
-   * payments.budget.status / cards.* / purchases.list.
+   * payments.budget.status / cards.* / purchases.list / checkout.begin / checkout.fillCard.
    *
    * Its stores need a shell-path resolver and a scoped secret writer, neither of
    * which is on `HandlerContext`, so the composition root builds them and hands

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

@@ -0,0 +1,54 @@
+/**
+ * address-store.ts, the stored shipping and billing addresses, read from
+ * config.
+ *
+ * The SDK's `platform/config/schema-domain-payments.ts` already declares flat
+ * `payments.shippingAddress.*` / `payments.billingAddress.*` keys (name,
+ * line1, line2, city, region, postalCode, country each), settable through the
+ * owner profile and the settings surfaces; address.ts's own header names the
+ * defect this closes: "nothing in the checkout path read either." This is
+ * that read path, the daemon-owned counterpart to `DaemonCardStore` for the
+ * OTHER thing a checkout needs supplied rather than typed by the model.
+ *
+ * A field that is present but blank reads as absent (`''` is not a value any
+ * of these fields can honestly hold), so a half-set address is reported the
+ * same way a wholly-unset one is: `AddressStore.read` returns the address with
+ * whatever is there, and `checkAddress` (address.ts) is what decides whether
+ * that is complete enough to ship to, exactly as it already does for the SDK's
+ * own test doubles. Nothing here validates completeness; this module only
+ * reads what config holds.
+ */
+import type { AddressKind, AddressStore, PostalAddress, PaymentsConfigReader } from '@pellux/goodvibes-sdk/platform/payments';
+
+function readAddressField(config: PaymentsConfigReader, kind: AddressKind, field: string): string {
+  const value = config.get(`payments.${kind}Address.${field}`);
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/** Every field blank means "nothing stored", read back as `null` rather than an all-empty address. */
+function isEntirelyBlank(address: PostalAddress): boolean {
+  return address.name === ''
+    && address.line1 === ''
+    && address.line2 === ''
+    && address.city === ''
+    && address.region === ''
+    && address.postalCode === ''
+    && address.country === '';
+}
+
+export function configBackedAddressStore(config: PaymentsConfigReader): AddressStore {
+  return {
+    async read(kind: AddressKind): Promise<PostalAddress | null> {
+      const address: PostalAddress = {
+        name: readAddressField(config, kind, 'name'),
+        line1: readAddressField(config, kind, 'line1'),
+        line2: readAddressField(config, kind, 'line2'),
+        city: readAddressField(config, kind, 'city'),
+        region: readAddressField(config, kind, 'region'),
+        postalCode: readAddressField(config, kind, 'postalCode'),
+        country: readAddressField(config, kind, 'country'),
+      };
+      return isEntirelyBlank(address) ? null : address;
+    },
+  };
+}

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;
+}