@pellux/goodvibes-daemon 1.28.19 → 1.28.20

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

@@ -1,6 +1,6 @@
 /**
  * The unattended startup reconcile for the redundant install-script
- * `goodvibes-daemon.service` unit — split out of `legacy-daemon-migration.ts`
+ * `goodvibes-daemon.service` unit, split out of `legacy-daemon-migration.ts`
  * (which owns the shared unit definition, detection, and the CONSENTED
  * `migrate-service` engine) so each module stays within the architecture
  * gate's file-size cap. Same layer (`src/runtime/`), same injectable-seam
@@ -24,8 +24,8 @@ type ManagedServiceActionResult = ReturnType<ManagedServiceActionRunner>;
 /**
  * The exact marker string scripts/install.sh writes into every unit it
  * creates (as a `# managed by goodvibes install.sh` comment). The reconcile
- * check below keys on it to tell an installer-created legacy unit — safe to
- * auto-retire — apart from a hand-written one that must only ever be reported.
+ * check below keys on it to tell an installer-created legacy unit, safe to
+ * auto-retire, apart from a hand-written one that must only ever be reported.
  * Kept in lockstep with `INSTALLER_MARKER` in scripts/install.sh.
  */
 export const INSTALLER_UNIT_MARKER = 'managed by goodvibes install.sh';
@@ -35,7 +35,7 @@ export const INSTALLER_UNIT_MARKER = 'managed by goodvibes install.sh';
 /**
  * CUMULATIVE ceiling on the reconcile's whole boot-path pass. Per-call
  * timeouts alone still allow ~5 sequential slow-but-completing calls to stack
- * up (a degraded — not wedged — user bus), blocking the already-listening
+ * up (a degraded, not wedged, user bus), blocking the already-listening
  * daemon's event loop for tens of seconds. One overall deadline covers the
  * pass: once it is exceeded, every remaining call is skipped (reported as
  * `status: null`, which the guards treat as unknown → refusal) and the result
@@ -48,7 +48,7 @@ export const RECONCILE_DEADLINE_MS = 8_000;
 /**
  * Wrap a runner with the reconcile's cumulative deadline: calls after the
  * deadline are skipped outright; calls near it get only the remaining budget
- * as their per-call timeout (default runner only — injected runners are test
+ * as their per-call timeout (default runner only, injected runners are test
  * fakes that answer instantly).
  */
 function makeDeadlineBoundRunner(
@@ -62,7 +62,7 @@ function makeDeadlineBoundRunner(
     const remaining = deadlineMs - (Date.now() - startedAt);
     if (remaining <= 0) {
       hit = true;
-      return { status: null, stdout: '', stderr: 'reconcile time budget exceeded — call skipped' } as ManagedServiceActionResult;
+      return { status: null, stdout: '', stderr: 'reconcile time budget exceeded; call skipped' } as ManagedServiceActionResult;
     }
     if (injected) return injected(command, args);
     return defaultActionRunner(Math.min(perCallTimeoutMs, remaining))(command, args);
@@ -167,7 +167,7 @@ function defaultReadOwnCgroup(): string {
  * This runs on daemon startup (no user invocation needed) and, guard-railed:
  *   - Only acts when the canonical unit is CONFIRMED serving: `is-active`
  *     reports active AND its MainPID resolves to a live process. `is-active`
- *     alone is not proof — a Type=simple unit reports active from fork onward,
+ *     alone is not proof, a Type=simple unit reports active from fork onward,
  *     including the pre-bind window of a daemon that is about to crash-loop.
  *   - NEVER acts from inside the legacy unit itself: if this process IS the
  *     legacy unit's MainPID, or /proc/self/cgroup names the legacy unit,
@@ -175,20 +175,20 @@ function defaultReadOwnCgroup(): string {
  *     code (mid-boot, from inside a blocking spawnSync). Refuses instead.
  *   - NEVER stops a RUNNING legacy daemon: if the legacy unit's MainPID is a
  *     live process, it may be the daemon serving the endpoint clients are
- *     configured to reach (the wrong-port two-daemon state) — the unattended
+ *     configured to reach (the wrong-port two-daemon state), the unattended
  *     path only retires enabled-but-NOT-running legacy units; a running one
  *     gets a notice pointing at the consented migrate-service.
  *   - Requires the CONFIGURED endpoint (the one clients resolve from
- *     settings.json, no runtime overrides) to be answering before retiring —
+ *     settings.json, no runtime overrides) to be answering before retiring,
  *     a canonical daemon alive on some other port proves nothing about the
  *     endpoint clients use.
  *   - AUTO-RETIRES only an installer-MARKER-managed legacy unit, and only
  *     removes its unit file AFTER `disable --now` reports success. A NONZERO
  *     exit leaves everything in place and says so; a TIMED-OUT disable
- *     (status null) has an UNKNOWN outcome — the enablement state is
+ *     (status null) has an UNKNOWN outcome, the enablement state is
  *     re-inspected before anything is printed, and the receipt states what
  *     was actually confirmed, never a blanket claim.
- *   - A hand-written legacy unit (no marker) is never touched — a one-line
+ *   - A hand-written legacy unit (no marker) is never touched, a one-line
  *     actionable notice. An UNREADABLE unit file is reported as unreadable,
  *     never misdiagnosed as hand-written.
  *   - The whole pass shares ONE cumulative time budget (RECONCILE_DEADLINE_MS)
@@ -214,11 +214,11 @@ export async function reconcileRedundantLegacyUnit(
   const legacyUnit = `${LEGACY_SERVICE_UNIT_NAME}.service`;
   const deadlineNote = (): string[] =>
     deadlineHit()
-      ? ['note: the reconcile hit its overall time budget — remaining checks were skipped; it will re-run at the next daemon start.']
+      ? ['note: the reconcile hit its overall time budget: remaining checks were skipped; it will re-run at the next daemon start.']
       : [];
 
   // Guard 1: the canonical unit must report active. (A timed-out, skipped, or
-  // failed probe — e.g. a wedged user bus — lands here too and refuses.)
+  // failed probe, e.g. a wedged user bus, lands here too and refuses.)
   const probe = run(systemctl, ['--user', 'is-active', canonicalUnit]);
   const canonicalActive = (probe.status ?? 1) === 0 && (probe.stdout ?? '').trim() === 'active';
   if (!canonicalActive) {
@@ -226,7 +226,7 @@ export async function reconcileRedundantLegacyUnit(
       action: 'noop',
       reason: 'canonical-not-active',
       lines: [
-        `legacy-unit reconcile: a ${legacyUnit} unit file exists at ${path} but ${canonicalUnit} is not confirmably active — ` +
+        `legacy-unit reconcile: a ${legacyUnit} unit file exists at ${path} but ${canonicalUnit} is not confirmably active; ` +
           'left untouched (it may be the only daemon).',
         ...deadlineNote(),
       ],
@@ -243,7 +243,7 @@ export async function reconcileRedundantLegacyUnit(
       action: 'noop',
       reason: 'canonical-mainpid-not-alive',
       lines: [
-        `legacy-unit reconcile: ${canonicalUnit} reports active but its MainPID could not be confirmed alive — ` +
+        `legacy-unit reconcile: ${canonicalUnit} reports active but its MainPID could not be confirmed alive; ` +
           `left the ${legacyUnit} unit untouched.`,
         ...deadlineNote(),
       ],
@@ -256,7 +256,7 @@ export async function reconcileRedundantLegacyUnit(
   //
   // The legacy MainPID probe is TRI-STATE, exactly like guards 1-2: a reply
   // whose status is non-zero or null (bus flap, timeout, skipped-by-deadline)
-  // does NOT mean "MainPID=0, unit affirmatively stopped" — reading it that
+  // does NOT mean "MainPID=0, unit affirmatively stopped", reading it that
   // way let one transient systemctl failure on exactly this call authorize
   // `disable --now` against a LIVE legacy daemon (and guard 5 cannot catch
   // it: in the wrong-port state the legacy daemon itself answers the
@@ -271,7 +271,7 @@ export async function reconcileRedundantLegacyUnit(
       action: 'noop',
       reason: 'self-supervised-by-legacy',
       lines: [
-        `legacy-unit reconcile: this daemon appears to be running UNDER ${legacyUnit} itself — refusing to disable ` +
+        `legacy-unit reconcile: this daemon appears to be running UNDER ${legacyUnit} itself; refusing to disable ` +
           `the unit supervising the current process. Migrate from the canonical side instead: goodvibes-daemon migrate-service`,
       ],
     };
@@ -282,14 +282,14 @@ export async function reconcileRedundantLegacyUnit(
       reason: 'legacy-state-unknown',
       lines: [
         `legacy-unit reconcile: could not determine whether ${legacyUnit} has a running daemon (the MainPID query ` +
-          'failed or timed out) — refusing to act on a guess; it will be re-checked at the next daemon start.',
+          'failed or timed out), refusing to act on a guess; it will be re-checked at the next daemon start.',
         ...deadlineNote(),
       ],
     };
   }
 
   // Guard 4: never stop a RUNNING legacy daemon from the unattended path. A
-  // live legacy MainPID means a second daemon is actually serving something —
+  // live legacy MainPID means a second daemon is actually serving something,
   // possibly the endpoint clients resolve from settings.json (the wrong-port
   // two-daemon state). Retiring an enabled-but-idle unit needs no --now kill;
   // stopping a serving one needs consent. (A KNOWN reply of MainPID=0 is the
@@ -299,7 +299,7 @@ export async function reconcileRedundantLegacyUnit(
       action: 'noop',
       reason: 'legacy-running',
       lines: [
-        `legacy-unit reconcile: ${legacyUnit} has a live main process (pid ${legacyPid}) — a second daemon is ` +
+        `legacy-unit reconcile: ${legacyUnit} has a live main process (pid ${legacyPid}); a second daemon is ` +
           'actually running, and it may be the one serving the endpoint your clients are configured to reach. ' +
           'Refusing to stop it unattended; migrate deliberately with: goodvibes-daemon migrate-service',
       ],
@@ -308,7 +308,7 @@ export async function reconcileRedundantLegacyUnit(
 
   // Guard 5: the endpoint clients resolve from settings.json must be answered
   // before anything is retired. The canonical daemon being alive proves only
-  // that A daemon runs — not that the configured endpoint is served (its unit
+  // that A daemon runs, not that the configured endpoint is served (its unit
   // may pin different launch args).
   if (input.configuredEndpoint) {
     const endpointProbe = input.endpointProbe ?? defaultPortProbe;
@@ -319,7 +319,7 @@ export async function reconcileRedundantLegacyUnit(
         reason: 'configured-endpoint-unserved',
         lines: [
           `legacy-unit reconcile: nothing is answering on the CONFIGURED endpoint ` +
-            `${input.configuredEndpoint.host}:${input.configuredEndpoint.port} — the canonical daemon is alive but not ` +
+            `${input.configuredEndpoint.host}:${input.configuredEndpoint.port}; the canonical daemon is alive but not ` +
             `provably serving what clients resolve from settings. Left the ${legacyUnit} unit untouched; check the ` +
             "canonical unit's launch arguments against the controlPlane settings.",
         ],
@@ -345,7 +345,7 @@ export async function reconcileRedundantLegacyUnit(
       reason: 'marker-unreadable',
       lines: [
         `note: ${canonicalUnit} is active and a separate ${legacyUnit} exists at ${path}, but its unit file could not ` +
-          `be read (${readError}) — left untouched. Inspect it yourself; if it is redundant, retire it with: ` +
+          `be read (${readError}). Left untouched. Inspect it yourself; if it is redundant, retire it with: ` +
           `systemctl --user disable --now ${legacyUnit} && rm ${path} && systemctl --user daemon-reload`,
       ],
     };
@@ -365,14 +365,14 @@ export async function reconcileRedundantLegacyUnit(
   }
 
   // Installer-marker-managed and redundant: disable first, and only remove the
-  // unit file if the disable actually succeeded — otherwise the enablement
+  // unit file if the disable actually succeeded, otherwise the enablement
   // symlink dangles at a deleted file and this tool can never repair it (the
   // next pass no-ops at the file-exists check).
   const disableResult = run(systemctl, ['--user', 'disable', '--now', legacyUnit]);
   const disableStatus = disableResult.status ?? 1;
   if (disableStatus !== 0) {
     if (disableResult.status === null) {
-      // TIMED OUT: the outcome is UNKNOWN, not failed — `disable --now`
+      // TIMED OUT: the outcome is UNKNOWN, not failed, `disable --now`
       // removes the enablement symlinks synchronously BEFORE waiting on the
       // stop job, so the disable may well have taken effect even though the
       // client was killed. Re-inspect instead of printing a blanket denial.
@@ -393,11 +393,11 @@ export async function reconcileRedundantLegacyUnit(
         run(systemctl, ['--user', 'daemon-reload']);
         const lines = [
           `reconciled: the disable command timed out waiting on the stop job, but re-inspection confirms the ` +
-            `installer-managed ${legacyUnit} is no longer enabled${removeErrorAfterTimeout ? '' : ` — its unit file was removed (${path})`}. ` +
+            `installer-managed ${legacyUnit} is no longer enabled${removeErrorAfterTimeout ? '' : `, its unit file was removed (${path})`}. ` +
             'Its stop may still be completing.',
         ];
         if (removeErrorAfterTimeout) {
-          lines.push(`note: could not remove ${path}: ${removeErrorAfterTimeout} — remove it by hand.`);
+          lines.push(`note: could not remove ${path}: ${removeErrorAfterTimeout}; remove it by hand.`);
         }
         lines.push(...deadlineNote());
         return { action: 'removed', reason: 'retired', lines };
@@ -406,7 +406,7 @@ export async function reconcileRedundantLegacyUnit(
         action: 'failed',
         reason: 'disable-timeout',
         lines: [
-          `legacy-unit reconcile: the disable of ${legacyUnit} timed out and its outcome is UNKNOWN — the enablement ` +
+          `legacy-unit reconcile: the disable of ${legacyUnit} timed out and its outcome is UNKNOWN; the enablement ` +
             `state could not be re-confirmed. This tool removed nothing; the unit file at ${path} was left in place ` +
             'and will be re-checked at the next daemon start.',
           `Verify it yourself: systemctl --user is-enabled ${legacyUnit}`,
@@ -420,7 +420,7 @@ export async function reconcileRedundantLegacyUnit(
       reason: 'disable-failed',
       lines: [
         `legacy-unit reconcile: the disable of the redundant installer-managed ${legacyUnit} reported failure ` +
-          `(${detail}) — this tool removed nothing; the unit file at ${path} was left in place.`,
+          `(${detail}); this tool removed nothing; the unit file at ${path} was left in place.`,
         `Verify its state and retire it yourself: systemctl --user is-enabled ${legacyUnit} ; ` +
           `systemctl --user disable --now ${legacyUnit} && rm ${path} && systemctl --user daemon-reload`,
       ],
@@ -441,7 +441,7 @@ export async function reconcileRedundantLegacyUnit(
       `was disabled${removeError ? '' : ` and removed (${path})`}.`,
   ];
   if (removeError) {
-    lines.push(`note: could not remove ${path}: ${removeError} — remove it by hand.`);
+    lines.push(`note: could not remove ${path}: ${removeError}; remove it by hand.`);
   }
   lines.push(...deadlineNote());
   return { action: 'removed', reason: 'retired', lines };

package/src/runtime/mail-composition.ts

@@ -4,7 +4,7 @@
  * The deps that let the platform register this daemon's `email.*` verbs.
  *
  * `calendar.*` and `email.*` are served by the platform now, not by handlers in
- * this repository — those were deleted when the platform gained an
+ * this repository, those were deleted when the platform gained an
  * implementation the daemon could call. What is left for a product to supply is
  * the wiring, and it is not optional: without `homeDirectory` the calendar
  * composition returns null, without these deps the mail one does, and either way
@@ -27,7 +27,7 @@ import { nodeEmailTransport } from '@pellux/goodvibes-sdk/platform/email/node';
 
 /** The narrow slices this composition needs; the real managers satisfy them. */
 interface MailCompositionInput {
-  readonly configManager: { get(key: never): unknown };
+  readonly configManager: { get(key: string): unknown };
   readonly secretsManager: { get(key: string): Promise<string | null> };
 }
 
@@ -36,8 +36,8 @@ interface MailCompositionInput {
  * `registerGatewayVerbGroups`.
  *
  * The settings come from the daemon's own `surfaces.email.*` keys through
- * `withSurfaceEmailConfig`, so the keys an operator has already set — and that
- * the settings modal now shows — keep working unchanged, and a not-configured
+ * `withSurfaceEmailConfig`, so the keys an operator has already set, and that
+ * the settings modal now shows, keep working unchanged, and a not-configured
  * answer names the keys THIS operator actually has rather than the ones the
  * service validates internally.
  */
@@ -45,7 +45,7 @@ export function composeMailDeps(input: MailCompositionInput): {
   readonly emailServiceDeps: EmailServiceDeps;
   readonly describeEmailConfigProblem: () => Promise<SurfaceEmailConfigProblem | null>;
 } {
-  const getConfig = (key: string): unknown => input.configManager.get(key as never);
+  const getConfig = (key: string): unknown => input.configManager.get(key);
   const emailServiceDeps = withSurfaceEmailConfig({
     getConfig,
     secretsManager: input.secretsManager,
@@ -56,7 +56,7 @@ export function composeMailDeps(input: MailCompositionInput): {
     // raises display confidence only, and commandAuthority is the literal
     // 'none'.
     describeSenderClaim: describeSenderClaimNeutrally,
-  } as never);
+  });
   return {
     emailServiceDeps,
     describeEmailConfigProblem: () =>

package/src/runtime/notification-dispatch.ts

@@ -1,9 +1,9 @@
 /**
- * notification-dispatch.ts — how this daemon dispatches notices without a screen.
+ * notification-dispatch.ts, how this daemon dispatches notices without a screen.
  *
  * The SDK's NotificationRouter decides where a domain notification goes and
- * collapses bursts and batches. Its three targets — `conversation`,
- * `status_bar`, `panel_only` — are all SCREEN targets: an inline conversation
+ * collapses bursts and batches. Its three targets, `conversation`,
+ * `status_bar`, `panel_only`, are all SCREEN targets: an inline conversation
  * line, a status bar, a panel. There is no channel member in that type, and
  * there never was. Which means the router is a surface mechanism end to end,
  * and this process has no screen.
@@ -11,7 +11,7 @@
  * This module used to wire the router to every curated domain anyway, writing
  * into a bounded ring whose `list()` had no caller anywhere in this repository.
  * Six domains of events, for the daemon's whole lifetime, into a buffer nobody
- * read — and the type declaring it still described the ring as "the panel's
+ * read, and the type declaring it still described the ring as "the panel's
  * live producer", for a product with no panels. That silent-success failure
  * class is exactly what this module removes: the producer goes.
  *
@@ -23,7 +23,7 @@
  *
  * One notice had no such path: memory pressure. The MemoryGovernor measures the
  * process it runs in, so the daemon's pressure is the daemon's own and no
- * surface can report it — and the daemon that ran out of memory is exactly the
+ * surface can report it, and the daemon that ran out of memory is exactly the
  * one that cannot tell you afterwards. It now goes out over the operator's
  * configured notice destination (`notifications.webhookUrls`, the same list the
  * bus bridge uses), and says so at its own level in the activity log when no
@@ -56,7 +56,7 @@ export interface DaemonNoticeChannel {
  * one event type rather than a subscription to the domain: the tier change is
  * the operator's business and the churn is not.
  *
- * Delivery failure is logged, never thrown — a webhook endpoint being down is
+ * Delivery failure is logged, never thrown, a webhook endpoint being down is
  * not a reason for the process reporting memory pressure to also crash.
  */
 export function wireMemoryPressureChannelNotice(
@@ -69,7 +69,7 @@ export function wireMemoryPressureChannelNotice(
     const level = memoryPressureLevel(payload);
     const line = memoryPressureLine(payload);
     if (!channel.isConfigured()) {
-      // No destination configured. The notice still exists — at its own
+      // No destination configured. The notice still exists, at its own
       // severity, where the operator looks when the daemon misbehaves.
       if (level === 'critical') logger.error(line);
       else if (level === 'warning') logger.warn(line);

package/src/runtime/payments-composition.ts

@@ -0,0 +1,143 @@
+/**
+ * payments-composition.ts, the payment capability inside THIS daemon.
+ *
+ * ── What was wrong ────────────────────────────────────────────────────────
+ *
+ * All seven `payments.*` verbs were cataloged, advertised with a real HTTP
+ * route, and answered 501 NOT_INVOKABLE to every caller. The route existed, the
+ * descriptor was honest about its shape, and nothing was attached, so the webui
+ * and the desktop app could read the contract and never use it. The terminal app
+ * did not paper over this: it has no payments handlers either; what it has is a
+ * settings surface (`/payments card`) that writes four flat config keys, which
+ * is a per-surface stopgap, not a served capability.
+ *
+ * ── What this composes ────────────────────────────────────────────────────
+ *
+ * The SDK owns the capability (`platform/payments`) and states, in
+ * card-material.ts, that the store behind it "is implemented by the daemon
+ * against its own secret store". It ships no such implementation. So this
+ * composes the two stores that were missing, from paths the daemon already owns:
+ *
+ *   - card metadata at `<home>/.goodvibes/<surface>/control-plane/payments-cards.json`,
+ *     through `controlPlaneStorePath`, the one resolver every control-plane
+ *     store path goes through, so it lands beside pairing-tokens.json rather
+ *     than in the unscoped orphan directory that resolver exists to prevent;
+ *   - card MATERIAL one field per key in the DAEMON secret tier, written with an
+ *     explicit `scope: 'daemon'`. Explicit because a payments card key is not in
+ *     the SDK's daemon-needed registry, so an omitted scope would file the
+ *     material in the surface tier while the daemon reads the daemon tier, the
+ *     exact split secret-config.ts's `defaultSecretBackedScope` documents as the
+ *     mailbox-password failure and names "the same shape of failure at purchase
+ *     time" for a card;
+ *   - the purchase audit ledger beside the card file.
+ *
+ * ── The budget ledger is in-process, and that is a statement ──────────────
+ *
+ * `BudgetLedger` is constructed empty here and never persisted. That is correct
+ * ONLY while checkout is unattached: the sole writer of a spend record is the
+ * checkout flow, so there is nothing to persist, and a state file nothing writes
+ * would be decoration. It stops being correct the moment `payments.checkout.begin`
+ * is wired, and the failure would be silent and expensive, a daemon restarted at
+ * noon would hand back a daily budget it had already spent. Making this ledger
+ * durable is part of wiring checkout.
+ *
+ * ── What is NOT composed ──────────────────────────────────────────────────
+ *
+ * `payments.checkout.begin` and `payments.checkout.fillCard` stay unattached and
+ * keep answering 501. They need a `CheckoutPageDriver` over an open browser
+ * page, and this composition has no way to obtain one: the SDK builds its
+ * browser engine inside `registerGatewayVerbGroups`
+ * (control-plane/routes/browser-composition.ts), hands back only the
+ * `BrowserGatewayService` slice, which exposes no page handle and no
+ * `fillSecret`, and constructs it with no `cardFieldGuard`, which its own
+ * secret-fill path refuses without. There is also no adapter anywhere from a
+ * browser session to a `CheckoutPageDriver`. Writing one here would put the
+ * card-into-page seam in this repository, and card-material.ts is explicit that
+ * exactly one module in the platform may produce card material. So the two verbs
+ * refuse honestly instead.
+ */
+import { controlPlaneStorePath } from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { GatewayMethodCatalog } from '@pellux/goodvibes-sdk/platform/control-plane';
+import { BudgetLedger, readCvvHandling } from '@pellux/goodvibes-sdk/platform/payments';
+import type { PaymentsConfigReader } from '@pellux/goodvibes-sdk/platform/payments';
+import type { ConfigManager, SecretsManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ShellPathService } from '@/runtime/index.ts';
+import {
+  DaemonCardStore,
+  DaemonPurchaseLedger,
+  registerPaymentsMethods,
+  type PaymentsSecretStore,
+} from '../daemon/handlers/payments/index.ts';
+import { GOODVIBES_DAEMON_SURFACE_ROOT } from '../config/surface.ts';
+
+export interface PaymentsCompositionOptions {
+  readonly configManager: ConfigManager;
+  readonly shellPaths: ShellPathService;
+  readonly secretsManager: SecretsManager;
+  /** Binding the catalog is what turns the family from a 501 facade into handlers. */
+  readonly gatewayMethods: GatewayMethodCatalog;
+  /**
+   * Whether this node is the one currently allowed to spend.
+   *
+   * Reported by `payments.budget.status` and never defaulted, see the SDK's
+   * gates.ts: on a clustered install the wrong answer is a double-spend.
+   */
+  readonly isPaymentsLeader: () => boolean;
+}
+
+export interface PaymentsServices {
+  readonly cards: DaemonCardStore;
+  readonly purchases: DaemonPurchaseLedger;
+  readonly budget: BudgetLedger;
+  /** Detaches the handlers. Held by the runtime disposal scope. */
+  readonly unregister: () => void;
+}
+
+/**
+ * The narrow secret port the card store gets: three operations over the daemon
+ * tier, and no way to reach any other credential in the process. The same
+ * treatment cluster-group-composition.ts gives the group key.
+ */
+function daemonScopedSecrets(secretsManager: SecretsManager): PaymentsSecretStore {
+  return {
+    get: (key) => secretsManager.get(key),
+    set: async (key, value) => {
+      await secretsManager.set(key, value, { scope: 'daemon', medium: 'secure' });
+    },
+    delete: async (key) => {
+      await secretsManager.delete(key, { scope: 'daemon' });
+    },
+  };
+}
+
+/** Read live, per call: a budget raised five minutes ago applies to the next read. */
+function livePaymentsConfig(configManager: ConfigManager): PaymentsConfigReader {
+  return { get: (key: string) => configManager.get(key as Parameters<ConfigManager['get']>[0]) };
+}
+
+/**
+ * Build the payment stores and bind the answerable verbs to them.
+ *
+ * Constructing this touches no disk: both stores read lazily and write only when
+ * a verb asks them to, so composing a runtime in a test creates no files.
+ */
+export function createPaymentsServices(options: PaymentsCompositionOptions): PaymentsServices {
+  const config = livePaymentsConfig(options.configManager);
+  const cards = new DaemonCardStore({
+    filePath: controlPlaneStorePath(options.shellPaths, GOODVIBES_DAEMON_SURFACE_ROOT, 'payments-cards.json'),
+    secrets: daemonScopedSecrets(options.secretsManager),
+    cvvHandling: () => readCvvHandling(config),
+  });
+  const purchases = new DaemonPurchaseLedger({
+    filePath: controlPlaneStorePath(options.shellPaths, GOODVIBES_DAEMON_SURFACE_ROOT, 'payments-purchases.json'),
+  });
+  const budget = new BudgetLedger();
+  const unregister = registerPaymentsMethods(options.gatewayMethods, {
+    cards,
+    purchases,
+    budget,
+    config,
+    isPaymentsLeader: options.isPaymentsLeader,
+  });
+  return { cards, purchases, budget, unregister };
+}

package/src/runtime/plugin-composition.ts

@@ -1,9 +1,9 @@
 /**
- * plugin-composition.ts — what a plugin dropped into the plugin directory gets
+ * plugin-composition.ts, what a plugin dropped into the plugin directory gets
  * to register when the host loading it is the daemon.
  *
  * A plugin registers into whatever registries the host hands its loader. Two
- * hosts load a plugin today — the terminal app and this daemon — and neither
+ * hosts load a plugin today, the terminal app and this daemon, and neither
  * holds every registry a plugin might want. The design (see
  * goodvibes-tui/docs/decisions/2026-07-30-plugin-registrations-split-verb-side-and-surface-side.md)
  * is: one plugin package, loaded by both hosts, each loading the registrations
@@ -22,7 +22,7 @@
  *
  * The two surface-side kinds are the ones this host cannot serve. The SDK's
  * PluginLoaderDeps has no optional members and its API guards nothing, so a
- * host that passes nothing for a registry does not decline that kind — it
+ * host that passes nothing for a registry does not decline that kind, it
  * throws a TypeError inside the plugin's own init, which the loader catches by
  * dropping THE WHOLE PLUGIN, including the halves this host could have run.
  * "Ignores the rest" therefore has to be a real registry that accepts the
@@ -67,8 +67,8 @@ export function createUnservedCommandRegistry(): CommandRegistryLike {
  *
  * The runs this daemon hosts build their tools through the agent orchestrator's
  * own registry, not this one, so a plugin tool registered here is cataloged and
- * unhandled. That is the recorded classification — `registerTool` is on the
- * surface-side list — and it was written when the daemon hosted no runs of its
+ * unhandled. That is the recorded classification, `registerTool` is on the
+ * surface-side list, and it was written when the daemon hosted no runs of its
  * own; the round that moves session hosting daemon-side is the one that
  * re-examines it. Until then, a registration here is honest rather than quiet.
  */
@@ -84,8 +84,8 @@ export class UnservedToolRegistry extends ToolRegistry {
 /**
  * Build the loader dependencies for this host.
  *
- * The delivery router is deliberately the manager's own — the one replies leave
- * through — so a registered strategy is a strategy that sends. Handing over a
+ * The delivery router is deliberately the manager's own, the one replies leave
+ * through, so a registered strategy is a strategy that sends. Handing over a
  * second router built from the same arguments is how a registration succeeds
  * and reaches nothing, which is the shape this whole seam is about.
  */

package/src/runtime/runtime-services-types.ts

@@ -1,12 +1,12 @@
 /**
- * runtime-services-types.ts — the public contract createRuntimeServices() takes
+ * runtime-services-types.ts, the public contract createRuntimeServices() takes
  * and returns.
  *
  * Split out of services.ts (the composition root that builds every one of
  * these fields) so the construction logic can stay under the repo's
  * architecture line-count gate without trimming 35 arbitrary lines to clear
  * the number. This module owns ONLY the shape of the input options and the
- * output surface — no runtime code, no wiring order, nothing that constructs
+ * output surface, no runtime code, no wiring order, nothing that constructs
  * anything. services.ts re-exports both types from here, so no import site
  * anywhere else in the app had to change.
  */
@@ -76,7 +76,7 @@ export interface RuntimeServicesOptions {
    * Threaded into `SecretsManager` so the override MOVES the daemon-scoped
    * credential store; without it a daemon told to run out of a temp tree still
    * read the real home's daemon secrets, so an "isolated" test daemon held the
-   * owner's live credentials. One name for one thing — `resolveGoodVibesHomeOwnership`
+   * owner's live credentials. One name for one thing, `resolveGoodVibesHomeOwnership`
    * is the single reader that produces it.
    */
   readonly daemonHomeDirectory?: string | undefined;
@@ -104,7 +104,7 @@ export interface RuntimeServices {
   readonly homeDirectory: string;
   /**
    * The `.goodvibes/<surface root>/` segment this daemon's own state lives
-   * under — always GOODVIBES_DAEMON_SURFACE_ROOT here (config/surface.ts).
+   * under, always GOODVIBES_DAEMON_SURFACE_ROOT here (config/surface.ts).
    * Declared so a consumer ASKS for it instead of deriving a second one; the
    * unscoped pre-split control-plane store is what deriving it twice produced.
    */
@@ -162,7 +162,7 @@ export interface RuntimeServices {
   readonly hookWorkbench: HookWorkbench;
   readonly pluginManager: PluginManager;
   readonly workflow: WorkflowServices;
-  /** Stream watchers, on-exit process triggers and condition checks, supervised as one — see trigger-services.ts. */
+  /** Stream watchers, on-exit process triggers and condition checks, supervised as one, see trigger-services.ts. */
   readonly triggerManager: TriggerManager;
   readonly voiceProviders: VoiceProviderRegistry;
   readonly voiceService: VoiceService;
@@ -219,13 +219,13 @@ export interface RuntimeServices {
   readonly contextAccountingHolder: ContextAccountingHolder; // bound at bootstrap.ts; see context-accounting-source.ts
   readonly wrfcController: WrfcController;
   readonly processManager: ProcessManager;
-  /** The phase/work-item orchestration engine — the SDK's platform/orchestration. */
+  /** The phase/work-item orchestration engine, the SDK's platform/orchestration. */
   readonly orchestrationEngine: OrchestrationEngine;
   readonly workstreamCommands: WorkstreamCommandService;
   /** The repo source-tree code index. */
   readonly codeIndexStore: CodeIndexStore;
   readonly codeIndexReindexScheduler: CodeIndexReindexScheduler; // tool-site reindex
-  /** Daily snapshots of every SQLite store this runtime writes, with bounded retention; unref'd timers (mirrors the SDK composition — hosts that tear down a runtime stop() it themselves). */
+  /** Daily snapshots of every SQLite store this runtime writes, with bounded retention; unref'd timers (mirrors the SDK composition, hosts that tear down a runtime stop() it themselves). */
   readonly storeSnapshotScheduler: StoreSnapshotScheduler;
   readonly appendOnlyRetentionScheduler: operations.DurabilityServices['appendOnlyRetentionScheduler']; // periodic append-only sweep; unref'd timers, stop() on teardown
   /** Stops the recurring crash-residue sweep; idempotent, unref'd timer (hosts that tear a runtime down call it). */
@@ -241,7 +241,7 @@ export interface RuntimeServices {
   /** Controller the governor uses to pause/resume the deferrable background jobs under pressure. */
   readonly pauseController: PauseController;
   readonly sessionLiveTurnControls: SessionLiveTurnControlsHolder;
-  /** Unified live process registry (agents, WRFC chains, workflows, watchers, background processes) backing the Fleet panel; archive-aware — finished subtrees can be moved to the session archive view. */
+  /** Unified live process registry (agents, WRFC chains, workflows, watchers, background processes) backing the Fleet panel; archive-aware, finished subtrees can be moved to the session archive view. */
   readonly processRegistry: ArchivableProcessRegistry;
   readonly modeManager: ModeManager;
   readonly fileUndoManager: FileUndoManager;
@@ -250,7 +250,7 @@ export interface RuntimeServices {
   readonly checkpointsCurrentlyAllowed: () => boolean;
   /** Surface-scoped continuity reads (recovery-file presence, last-session pointer). */
   readonly integrationHelpers: IntegrationHelperService;
-  /** Per-workspace trust gate — restricts write/execute/delegate tools until the workspace is trusted. */
+  /** Per-workspace trust gate, restricts write/execute/delegate tools until the workspace is trusted. */
   readonly workspaceTrustManager: operations.WorkspaceTrustManager;
   /**
    * The permission manager the runs this daemon hosts ask through. Its ask seam