@pellux/goodvibes-daemon 1.28.19 → 1.28.20

package/src/daemon/status-command.ts

@@ -1,9 +1,9 @@
 /**
- * status-command.ts — `goodvibes-daemon status` and `goodvibes-daemon update`.
+ * status-command.ts, `goodvibes-daemon status` and `goodvibes-daemon update`.
  *
  * The question a headless box's operator asks first: is it up, what version, on
  * what address, is anything unhealthy, and what did it do to itself while I was
- * not looking. Before this, the binary answered none of that — `status` fell
+ * not looking. Before this, the binary answered none of that, `status` fell
  * through the parser and started a SECOND daemon in the foreground.
  *
  * WHERE EACH LINE COMES FROM
@@ -13,11 +13,11 @@
  * established: `/status` for identity, `/api/health` for the health roll-up and
  * the address it actually bound, `/api/channels/status` for the channels, and
  * `/api/cluster/status` for this machine's place in its group. Hosted sessions
- * are a ws-only verb family, so they go through `callDaemonWsVerb` — same
+ * are a ws-only verb family, so they go through `callDaemonWsVerb`, same
  * target, same token, different transport.
  *
- * Everything about the daemon's own HISTORY — uptime, the receipts it wrote,
- * the version an automatic rollback rejected — comes from files on the daemon's
+ * Everything about the daemon's own HISTORY, uptime, the receipts it wrote,
+ * the version an automatic rollback rejected, comes from files on the daemon's
  * host, because no verb reports them. That makes those lines local-only, and
  * they say so for a remote target instead of being guessed at.
  *
@@ -76,8 +76,8 @@ export interface RemoteCommandDeps {
  *
  * It carries a `cluster` block the operator contract does not list, and that
  * block is where this daemon's ROLE in its group comes from. `cluster.uptimeMs`
- * is the coordinator's, not the daemon's — it reads 0 on a daemon that has been
- * up for hours — so the uptime line comes from the lifecycle marker instead.
+ * is the coordinator's, not the daemon's, it reads 0 on a daemon that has been
+ * up for hours, so the uptime line comes from the lifecycle marker instead.
  */
 interface ControlStatusPayload {
   readonly status?: string;
@@ -179,7 +179,7 @@ function optionalLine(label: string, value: string | undefined): string[] {
  *
  * `/status` reports `version` from the platform package while the cluster block
  * it carries reports the DAEMON build's version, and against a live daemon
- * those disagreed — 1.21.0 against 1.28.0. Printing one of them silently would
+ * those disagreed, 1.21.0 against 1.28.0. Printing one of them silently would
  * put a number on this page that is wrong for whichever question the reader had
  * in mind, so both are printed and labelled until the daemon states one.
  */
@@ -210,7 +210,7 @@ function localStateLines(state: LocalDaemonState): string[] {
   }
   if (state.marker?.rejectedVersion !== undefined) {
     lines.push(
-      `  rejected: ${state.marker.rejectedVersion} crash looped and was rolled back — `
+      `  rejected: ${state.marker.rejectedVersion} crash looped and was rolled back; `
       + 'the update loop will not install that version again',
     );
   }
@@ -229,7 +229,7 @@ function localStateLines(state: LocalDaemonState): string[] {
 }
 
 function healthLines(outcome: DaemonVerbOutcome<HealthPayload>): string[] {
-  if (!outcome.ok) return [`  health:   could not read — ${outcome.error}`];
+  if (!outcome.ok) return [`  health:   could not read: ${outcome.error}`];
   const health = outcome.data;
   const lines = [`  health:   ${health.overall ?? 'unknown'}`];
   const binding = health.network?.controlPlane;
@@ -250,12 +250,12 @@ function healthLines(outcome: DaemonVerbOutcome<HealthPayload>): string[] {
  *
  * Only a channel that is switched ON and not healthy is named. Every channel
  * the daemon knows about appears in this payload, and a daemon with one
- * configured channel ships sixteen more in state `disabled` — listing those as
+ * configured channel ships sixteen more in state `disabled`, listing those as
  * problems produced a seventeen-line wall under a healthy daemon and buried the
  * one line that meant something.
  */
 function channelLines(outcome: DaemonVerbOutcome<ChannelsPayload>): string[] {
-  if (!outcome.ok) return [`  channels: could not read — ${outcome.error}`];
+  if (!outcome.ok) return [`  channels: could not read: ${outcome.error}`];
   const channels = outcome.data.channels ?? [];
   if (channels.length === 0) return ['  channels: none configured'];
   const on = channels.filter((channel) => channel.enabled !== false);
@@ -276,7 +276,7 @@ function channelLines(outcome: DaemonVerbOutcome<ChannelsPayload>): string[] {
  * Two sources, because neither answers the whole question: `/status` carries
  * the ROLE this node currently holds, and `/api/cluster/status` carries the
  * GROUP it holds that role in. A daemon with sharing switched off says so and
- * stops — a role inside no group is not information.
+ * stops, a role inside no group is not information.
  */
 function clusterLines(
   identity: ControlStatusPayload,
@@ -284,18 +284,18 @@ function clusterLines(
 ): string[] {
   const role = identity.cluster?.role;
   if (identity.cluster?.enabled === false) {
-    return ['  cluster:  off — this machine handles its own inbound work'];
+    return ['  cluster:  off, this machine handles its own inbound work'];
   }
   if (!outcome.ok) {
     return [
       role === undefined
-        ? `  cluster:  could not read — ${outcome.error}`
-        : `  cluster:  ${role} (the group view could not be read — ${outcome.error})`,
+        ? `  cluster:  could not read: ${outcome.error}`
+        : `  cluster:  ${role} (the group view could not be read: ${outcome.error})`,
     ];
   }
   const cluster = outcome.data;
   if (cluster.membership === 'no-group') {
-    return ['  cluster:  in no group yet — `goodvibes-daemon cluster create` starts one'];
+    return ['  cluster:  in no group yet, `goodvibes-daemon cluster create` starts one'];
   }
   const group = cluster.groupName ?? cluster.groupId ?? 'its group';
   const members = cluster.memberCount === undefined ? '' : ` of ${cluster.memberCount}`;
@@ -303,7 +303,7 @@ function clusterLines(
 }
 
 function hostedSessionLines(outcome: DaemonVerbOutcome<HostedSessionsPayload>): string[] {
-  if (!outcome.ok) return [`  sessions: could not read — ${outcome.error}`];
+  if (!outcome.ok) return [`  sessions: could not read: ${outcome.error}`];
   const sessions = outcome.data.sessions ?? [];
   return [`  sessions: ${sessions.length} hosted by this daemon`];
 }
@@ -317,7 +317,7 @@ export interface RunStatusCommandInput extends RemoteCommandDeps {
  *
  * Exit 0 when the daemon answered its identity call, 1 when it could not be
  * reached. Every other sub-question that fails is one line inside a successful
- * report — a daemon with a broken channel is up, and saying otherwise would be
+ * report, a daemon with a broken channel is up, and saying otherwise would be
  * the kind of wrong that makes an operator distrust the whole page.
  */
 export async function runStatusCommand(input: RunStatusCommandInput): Promise<DaemonCommandResult> {
@@ -407,8 +407,8 @@ export interface RunUpdateCommandInput extends RemoteCommandDeps {
  * rejected, and whether a rollback is in force.
  *
  * --check is honest about a gap. The daemon runs the whole self-update loop
- * itself — it checks hourly, swaps at an idle moment and keeps the outgoing
- * binary — but the control plane publishes NO verb to trigger that check early:
+ * itself, it checks hourly, swaps at an idle moment and keeps the outgoing
+ * binary, but the control plane publishes NO verb to trigger that check early:
  * the operator contract this build was written against has no update method of
  * any kind (no `update.*`, no `admin.update`, nothing under `control.` that
  * checks). Rather than invent a verb this daemon does not answer, --check says
@@ -439,7 +439,7 @@ export async function runUpdateCommand(input: RunUpdateCommandInput): Promise<Da
       '',
       'update --check: this daemon publishes no verb to trigger an update check early.',
       '  It checks once an hour on its own and swaps only at an idle moment.',
-      '  To make it check now, restart it — it checks on the way up:',
+      '  To make it check now, restart it; it checks on the way up:',
       '    goodvibes-daemon restart-service',
     ]
     : [];

package/src/daemon/webui-command.ts

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// webui-command.ts — `goodvibes-daemon webui enable|disable|status`.
+// webui-command.ts, `goodvibes-daemon webui enable|disable|status`.
 //
 // WHAT THIS IS FOR
 //
@@ -8,7 +8,7 @@
 // serve such a directory: with `controlPlane.webui.serve` on, its own HTTP
 // router answers `/` from `controlPlane.webui.bundleDir` and falls back to
 // index.html for app routes. So installing the web UI is two config writes and
-// a directory on disk — and this is the command that makes those writes, so the
+// a directory on disk, and this is the command that makes those writes, so the
 // curl installer does not have to know the key names, the file format, or which
 // of the three settings tiers a daemon-owned key belongs in. Same reason
 // `provision-wake-model` exists: the installer runs the binary it just placed
@@ -17,12 +17,12 @@
 // WHERE IT IS SERVED, AND WHY THE URL SAYS WHAT IT SAYS
 //
 // The bundle is served BY THE CONTROL-PLANE LISTENER, same origin as the API
-// (that is the whole point — a same-origin bundle makes the browser's
+// (that is the whole point, a same-origin bundle makes the browser's
 // same-origin policy a non-issue and needs no CORS allowlist). So the URL that
 // opens the web UI is the control-plane origin: `http://<host>:<controlPlane.port>`,
 // not `web.port`. `web.port` is the surface's DECLARED endpoint, used for links
-// and for `tailscale serve`; nothing binds it. This command therefore reports —
-// and, when it is still sitting on the shipped placeholder, writes —
+// and for `tailscale serve`; nothing binds it. This command therefore reports,
+// and, when it is still sitting on the shipped placeholder, writes,
 // `web.publicBaseUrl` as the origin that actually answers, so the printed URL,
 // the pairing deep link and the running server all agree.
 //
@@ -41,7 +41,7 @@ import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { resolveRuntimeEndpointBinding } from '@pellux/goodvibes-terminal-shell';
 import { probeStableHostInputs, stableUrlHostForBindHost, type StableHostInputs } from '@pellux/goodvibes-sdk/platform/pairing';
 
-/** The shipped `web.publicBaseUrl` placeholder — a port nothing binds. */
+/** The shipped `web.publicBaseUrl` placeholder, a port nothing binds. */
 const SHIPPED_PUBLIC_BASE_URL = 'http://127.0.0.1:3423';
 
 export interface WebuiCommandResult {
@@ -175,13 +175,13 @@ function postureLines(origin: string, loopback: boolean): string[] {
     ];
   }
   return [
-    `  reachable from your network at ${origin} — the control-plane listener is bound to all interfaces.`,
+    `  reachable from your network at ${origin}; the control-plane listener is bound to all interfaces.`,
     '  To take it back to this machine only:  goodvibes-daemon webui enable --loopback',
   ];
 }
 
 /**
- * Run the command and report it. Never throws for an ordinary refusal — a bad
+ * Run the command and report it. Never throws for an ordinary refusal, a bad
  * argument, a missing bundle, an unwritable settings file all come back as an
  * exit code and lines, because the caller is often an installer reading both.
  */
@@ -212,14 +212,14 @@ export function runWebuiCommand(argv: readonly string[], deps: WebuiCommandDeps)
     try {
       config.set('controlPlane.webui.serve', false);
     } catch (error) {
-      return { exitCode: 1, lines: [`webui: could not write settings — ${message(error)}`] };
+      return { exitCode: 1, lines: [`webui: could not write settings: ${message(error)}`] };
     }
     const kept = readString(config, 'controlPlane.webui.bundleDir');
     return {
       exitCode: 0,
       lines: [
         'web UI: no longer served by the daemon.',
-        ...(kept ? [`  the bundle is left on disk at ${kept} — 'goodvibes-daemon webui enable' serves it again`] : []),
+        ...(kept ? [`  the bundle is left on disk at ${kept}; 'goodvibes-daemon webui enable' serves it again`] : []),
         '  Restart the daemon for this to take effect on a running process.',
       ],
     };
@@ -242,7 +242,7 @@ export function runWebuiCommand(argv: readonly string[], deps: WebuiCommandDeps)
     return {
       exitCode: 1,
       lines: [
-        `webui: refusing to serve ${bundleDir} — ${problem}.`,
+        `webui: refusing to serve ${bundleDir}: ${problem}.`,
         '  Nothing was changed.',
       ],
     };
@@ -260,7 +260,7 @@ export function runWebuiCommand(argv: readonly string[], deps: WebuiCommandDeps)
       config.set('web.hostMode', 'local');
     }
   } catch (error) {
-    return { exitCode: 1, lines: [`webui: could not write settings — ${message(error)}`] };
+    return { exitCode: 1, lines: [`webui: could not write settings: ${message(error)}`] };
   }
 
   const serving = servingOrigin(config, probe);
@@ -284,7 +284,7 @@ export function runWebuiCommand(argv: readonly string[], deps: WebuiCommandDeps)
   }
 
   if (!serving.recognized) {
-    lines.push('  note: controlPlane.hostMode is not one of local|network|custom — the daemon cannot bind until that is corrected.');
+    lines.push('  note: controlPlane.hostMode is not one of local|network|custom; the daemon cannot bind until that is corrected.');
   }
   lines.push(...postureLines(serving.origin, serving.loopback));
   lines.push('  Restart the daemon for this to take effect on a running process.');
@@ -324,7 +324,7 @@ function renderStatus(
   } else {
     const absoluteDir = deps.absolute(directory);
     const problem = describeBundleProblem(absoluteDir, deps.directoryExists, deps.fileExists);
-    lines.push(problem ? `  bundle (${source}): ${absoluteDir} — UNUSABLE: ${problem}` : `  bundle (${source}): ${absoluteDir}`);
+    lines.push(problem ? `  bundle (${source}): ${absoluteDir} (UNUSABLE: ${problem})` : `  bundle (${source}): ${absoluteDir}`);
   }
   const currentPublic = readString(config, 'web.publicBaseUrl');
   if (currentPublic && currentPublic !== serving.origin) {

package/src/runtime/boot-tasks.ts

@@ -98,7 +98,7 @@ export async function runDaemonBootTasks(services: RuntimeServices): Promise<voi
 
   // Load the plugins this host can serve. The manager was constructed by the
   // graph and never initialised, so it could list a plugin directory and never
-  // load anything out of it — `enable` persisted a flag that turned nothing on.
+  // load anything out of it, `enable` persisted a flag that turned nothing on.
   // Both hosts read the same directories; each takes the registrations it can
   // serve (plugin-composition.ts). Best-effort like everything else here: a
   // plugin that will not load is not a reason for the daemon not to start.

package/src/runtime/cluster-composition.ts

@@ -1,8 +1,8 @@
 /**
- * cluster-composition.ts — this daemon's seat in the LAN leader election.
+ * cluster-composition.ts, this daemon's seat in the LAN leader election.
  *
- * When the same goodvibes install runs more than once on one network — a
- * laptop and a desktop, or two processes on one machine — every copy
+ * When the same goodvibes install runs more than once on one network, a
+ * laptop and a desktop, or two processes on one machine, every copy
  * independently reads the shared inbox, so one message is picked up twice and
  * answered twice. The SDK's cluster coordinator elects exactly one node to be
  * responsible for inbound consumption; everything else stays warm and silent.
@@ -10,8 +10,8 @@
  * This file exists because this daemon does NOT get that for free from the
  * SDK facade. The facade gates the consumers IT owns (Telegram
  * ingress, the ntfy/Slack/Discord provider runtime), but this repository
- * composes an inbound consumer of its own — the Slack/Discord/email inbox
- * poller in daemon/handlers/inbox — and the facade knows nothing about it.
+ * composes an inbound consumer of its own, the Slack/Discord/email inbox
+ * poller in daemon/handlers/inbox, and the facade knows nothing about it.
  * A fix that only landed in the facade would leave the poller double-reading
  * on exactly the machine this product runs on.
  *
@@ -51,7 +51,7 @@ export interface GatedPollerControl {
  * Constructing it is inert: no socket is opened and no state is written until
  * `start()` runs, so composing a runtime in a test never joins a network.
  *
- * The version is THIS BINARY's version, not the SDK package's — the same
+ * The version is THIS BINARY's version, not the SDK package's, the same
  * distinction daemon/cli.ts already makes for the self-update artifact. It is
  * the first ranking tier, so getting it wrong would let a stale build hold the
  * role through an update.
@@ -62,7 +62,7 @@ export function createClusterComposition(options: {
    * `readClusterSettings` asks for. The daemon passes a whole ConfigManager;
    * the handler context carries only this slice, and a test standing in a
    * minimal config object should not have to fabricate the full fifty-odd
-   * members to compose a coordinator — a cast there would hide a real shape
+   * members to compose a coordinator, a cast there would hide a real shape
    * mismatch rather than document one.
    */
   readonly configManager: Pick<ConfigManager, 'getCategory'>;
@@ -75,7 +75,7 @@ export function createClusterComposition(options: {
    * the current group key. That is what stops a daemon belonging to somebody
    * else on the same network from taking part in this election at all.
    *
-   * Absent — the plain default — means the coordinator opens its own socket and
+   * Absent, the plain default, means the coordinator opens its own socket and
    * coordinates with anything that answers on the configured port.
    */
   readonly transport?: ClusterTransport | undefined;
@@ -96,7 +96,7 @@ export function createClusterComposition(options: {
  *
  * One gate per account, not one for the poller. Each inbox account is its own
  * surface in the election, so this laptop can hold the work Slack account
- * while the desktop holds the mailbox — and losing one machine moves only the
+ * while the desktop holds the mailbox, and losing one machine moves only the
  * accounts it was reading. A single gate covering the whole poller could not
  * express that: it would hand every account over together, and a node with a
  * credential for only one of them could never take part at all.

package/src/runtime/cluster-group-composition.ts

@@ -1,10 +1,10 @@
 /**
- * cluster-group-composition.ts — this machine's membership of a LAN group.
+ * cluster-group-composition.ts, this machine's membership of a LAN group.
  *
  * Leader election answers "which of us reads the inbox". This answers the
  * question underneath it: "which machines are US". Without a group, any daemon
- * that happened to be on the same network — a neighbour's, a colleague's, a
- * container someone left running — would join the same coordination and one of
+ * that happened to be on the same network, a neighbour's, a colleague's, a
+ * container someone left running, would join the same coordination and one of
  * you would silently stop receiving messages.
  *
  * The group layer owns the socket and the election rides on it: every
@@ -77,7 +77,7 @@ export function createClusterGroupComposition(options: {
    * The leader election's own answer to "am I the master".
    *
    * Config replication needs exactly one machine issuing revisions, and it must
-   * be the SAME machine leadership already picked — two notions of master in
+   * be the SAME machine leadership already picked, two notions of master in
    * one process would disagree the moment one of them changed.
    *
    * Late-bound because the coordinator is built from this composition's
@@ -91,7 +91,7 @@ export function createClusterGroupComposition(options: {
    * in `cluster status` and in /status. Late-bound for the same reason
    * `isMaster` is. Absent means the group layer reports that the information is
    * unavailable rather than reporting an empty list as though this machine held
-   * nothing — a distinction an operator diagnosing a silent inbox depends on.
+   * nothing, a distinction an operator diagnosing a silent inbox depends on.
    */
   readonly surfaceHoldings?: (() => readonly ClusterSurfaceHolding[]) | undefined;
 }): ClusterGroupComposition {
@@ -181,7 +181,7 @@ export function createClusterGroupComposition(options: {
  * through a closure because the coordinator does not exist yet when the group
  * layer is constructed.
  *
- * Constructing either is inert — no socket, no key material read — until
+ * Constructing either is inert, no socket, no key material read, until
  * `startCluster` runs.
  */
 export function createClusterServices(options: {
@@ -228,7 +228,7 @@ export async function startClusterServices(services: {
  * Ask the group to take this machine back, on start.
  *
  * This is the zero-touch return. A machine that has been switched off for
- * months — through many group-key rotations and possibly a join-key change —
+ * months, through many group-key rotations and possibly a join-key change,
  * comes up holding stale keys, says "it is still me" with a key that never
  * rotates, and is re-keyed to the current generation by whichever member
  * answers. The operator does nothing.

package/src/runtime/conversation-rewind-port.ts

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// conversation-rewind-port.ts — the daemon's RewindConversationPort for the
+// conversation-rewind-port.ts, the daemon's RewindConversationPort for the
 // SDK's unified rewind service.
 //
 // The SDK's UnifiedRewindService (platform/rewind) joins files rewind (workspace
@@ -9,7 +9,7 @@
 // truncation and captures the pre-/post-truncation snapshots so the reversal can
 // be undone and re-applied. The truncation boundary is the message count recorded
 // for the anchor's turnId at TURN_COMPLETED (the SDK's platform/rewind turn
-// anchors) — the same
+// anchors), the same
 // join key files rewind uses against the workspace checkpoint.
 //
 // This module is the daemon's implementation of that port, for sessions THIS
@@ -17,7 +17,7 @@
 // anchor.sessionId from the registry below.
 //
 // While conversation loops run in the surfaces, that registry is empty here, and
-// it used to answer an empty resolution with "0 messages to drop" — the same
+// it used to answer an empty resolution with "0 messages to drop", the same
 // answer a conversation already at the anchor gives, which is a confident wrong
 // answer rather than a missing one. It now reports the anchor as UNAVAILABLE
 // with the reason, which the SDK's rewind service turns into a plan warning.
@@ -25,7 +25,7 @@
 // The surfaces reach conversation rewind a different way now: they offer their
 // live conversation over the control plane (rewind.conversation.*), and the
 // SDK's host broker asks them directly. This port is the fallback the broker
-// falls through to for sessions no surface has offered — which is exactly the
+// falls through to for sessions no surface has offered, which is exactly the
 // case where the daemon hosts the conversation itself. Files-scope rewind,
 // entirely daemon-owned, was never affected either way.
 //
@@ -65,7 +65,7 @@ export interface ConversationRewindPort extends RewindConversationPort {
   restoreAfter(undoSnapshotId: string): boolean;
 }
 
-/** One truncation's captured state — the target conversation and its snapshots. */
+/** One truncation's captured state, the target conversation and its snapshots. */
 interface SnapshotPair {
   readonly conv: RewindableConversation;
   readonly before: ConversationJson;
@@ -80,7 +80,7 @@ const NO_LIVE_CONVERSATION =
  * Build a conversation rewind port. `resolveConversation` maps an anchor's
  * sessionId to the live conversation: the daemon looks the session up in the
  * registry below. A null resolution is reported as unavailable with the reason
- * — never as a count, because "nobody here is holding those messages" and
+ *, never as a count, because "nobody here is holding those messages" and
  * "there are no messages to drop" are different facts and only one of them is
  * true.
  */
@@ -139,7 +139,7 @@ export function createConversationRewindPort(
 }
 
 // ---------------------------------------------------------------------------
-// Live per-session conversation registry — the daemon-hosted mutable store the
+// Live per-session conversation registry, the daemon-hosted mutable store the
 // composed daemon's rewind.plan/apply verbs fall back to. A process INSIDE this
 // daemon that runs a conversation registers it here; a surface in another
 // process offers its conversation over the control plane instead
@@ -162,7 +162,7 @@ export function unregisterSessionConversation(sessionId: string): void {
 
 /**
  * The conversation rewind port the composed daemon threads into
- * registerGatewayVerbGroups — it resolves each anchor's live conversation from
+ * registerGatewayVerbGroups, it resolves each anchor's live conversation from
  * the registry above, so the daemon's own rewind verbs serve conversation scope
  * live in this process.
  */

package/src/runtime/credential-composition.ts

@@ -7,7 +7,7 @@
  * These are grouped because they share one fact, and it is the fact this round
  * had to fix: WHERE the daemon's own credentials live. `daemonHome` is threaded
  * rather than defaulted, because without it a daemon told to run out of a temp
- * tree moved its identity directory and nothing else — the credential store
+ * tree moved its identity directory and nothing else, the credential store
  * stayed in the real home, so an "isolated" test daemon held live credentials
  * and long-polled a real account. A default here would silently restore that.
  *
@@ -25,7 +25,7 @@ interface CredentialCompositionInput {
   readonly homeDirectory: string;
   /**
    * The daemon's state root when the host was told one. Absent means "not
-   * overridden" and must stay absent rather than being defaulted — see above.
+   * overridden" and must stay absent rather than being defaulted, see above.
    */
   readonly daemonHomeDirectory?: string | undefined;
   readonly configManager: ConstructorParameters<typeof SecretsManager>[0]['configManager'];

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

@@ -1,9 +1,9 @@
 /**
- * daemon-handler-composition.ts — the daemon's HOST-side handler surfaces.
+ * daemon-handler-composition.ts, the daemon's HOST-side handler surfaces.
  *
  * Attaches this repository's handlers to the SDK-auto-registered builtin
  * gateway descriptors (channels.* / email.* / calendar.*) via
- * catalog.register(descriptor, handler, { replace: true }) — the SDK owns
+ * catalog.register(descriptor, handler, { replace: true }), the SDK owns
  * every id, descriptor and schema; only the behaviour is ours. The remote
  * surface reuses the SAME DistributedRuntimeManager the SDK facade injects.
  *
@@ -12,7 +12,7 @@
  *
  * The one behavioural decision that lives here: the inbox poller is handed to
  * the cluster coordinator instead of being started eagerly. It is this
- * product's own inbound consumer — the SDK facade does not know it exists —
+ * product's own inbound consumer, the SDK facade does not know it exists,
  * so if it is not gated here it is not gated anywhere, and two goodvibes nodes
  * on one network each read the shared inbox and answer the same message twice.
  */
@@ -28,7 +28,9 @@ import { registerInboxMethods } from '../daemon/handlers/inbox/index.ts';
 import { registerTriagedInbox } from '../daemon/handlers/triage/index.ts';
 import { registerDraftMethods } from '../daemon/handlers/drafts/index.ts';
 import { registerRemoteSurface } from '../daemon/handlers/remote/index.ts';
+import { createPaymentsServices } from './payments-composition.ts';
 import { inboxPollerGate } from './cluster-composition.ts';
+import type { ShellPathService } from '@/runtime/index.ts';
 
 export interface DaemonHandlerCompositionOptions {
   readonly gatewayMethods: GatewayMethodCatalog;
@@ -36,6 +38,8 @@ export interface DaemonHandlerCompositionOptions {
   readonly configManager: ConfigManager;
   readonly workingDirectory: string;
   readonly homeDirectory: string;
+  /** Resolves the surface-scoped control-plane paths the payment stores live at. */
+  readonly shellPaths: ShellPathService;
   readonly distributedRuntime: NonNullable<Parameters<typeof registerRemoteSurface>[1]>['manager'];
   /**
    * Decides whether THIS node polls the shared inbox. Always supplied by the
@@ -65,12 +69,48 @@ export function createDaemonHandlerComposition(
     registerInbox: (ctx, routing) =>
       registerTriagedInbox(ctx, (inboxCtx) => registerInboxMethods(inboxCtx, routing, {
         // Hands polling to leadership. The `channels.inbox.list` read stays
-        // available on every node — a standby still SERVES the persisted feed,
+        // available on every node, a standby still SERVES the persisted feed,
         // it just does not FETCH into it.
         gatePolling: (providerId, control) =>
           options.clusterCoordinator.register(inboxPollerGate(providerId, control)),
       })).unregister,
     registerDrafts: (ctx) => registerDraftMethods(ctx),
+    // The payment stores need a path resolver and a daemon-scoped secret writer,
+    // neither of which is on HandlerContext, so they are built here and the
+    // provider only carries the teardown. See payments-composition.ts for which
+    // verbs this attaches and which two it deliberately leaves refusing.
+    registerPayments: () => createPaymentsServices({
+      gatewayMethods: options.gatewayMethods,
+      configManager: options.configManager,
+      secretsManager: options.secretsManager,
+      shellPaths: options.shellPaths,
+      // True only on a machine that is not clustered at all, and false on every
+      // node of a cluster.
+      //
+      // `isMaster` was the obvious answer and it is the wrong one: it means
+      // "this node holds at least one inbound surface", which two nodes sharing
+      // a mailbox and a Slack workspace both satisfy, so a two-node cluster
+      // would have answered true twice. The SDK's gates.ts is explicit that
+      // exactly one node may act and that the wrong answer here is a
+      // double-spend.
+      //
+      // The alternative was to register a payments surface with the coordinator
+      // and read holdsSurface(), which is this repo's per-surface idiom
+      // (inboxPollerGate). It is the right answer once there is something to
+      // elect over, and today there is not: ClusterConsumerGate.start() is
+      // specified to not resolve until consumption has actually begun, and this
+      // composition has no payments consumer to start, checkout is unattached.
+      // Registering a gate whose start() does nothing would put a fake consumer
+      // in the election and in `cluster status`.
+      //
+      // So the honest reading of the topology: clustering off means this is the
+      // only node, and it is trivially the one that would spend; clustering on
+      // means no payments election has been held and this node cannot claim to
+      // have won it. False on every node is also the safe direction, checkPaymentGates
+      // refuses on false. Wiring payments.checkout.* is what should replace this
+      // with a real gate and holdsSurface().
+      isPaymentsLeader: () => !options.clusterCoordinator.enabled,
+    }).unregister,
     registerRemote: (ctx) => registerRemoteSurface(ctx, { manager: options.distributedRuntime }),
   });
 }

package/src/runtime/device-posture-composition.ts

@@ -1,11 +1,11 @@
 /**
- * device-posture-composition.ts — the paired-phone feature inside THIS daemon.
+ * device-posture-composition.ts, the paired-phone feature inside THIS daemon.
  *
  * A phone pairs with whichever daemon the person runs. Until this module
  * existed this daemon had no device posture at all: `device.nodes.maxPaired`
  * was enforced at the pairing path (SDK-side) and `device.capabilities.mode`
  * was an onboarding toggle, while the other eleven `device.*` keys were
- * recorded, read back, and governed nothing — the capability service they
+ * recorded, read back, and governed nothing, the capability service they
  * describe was never built here, so there was nothing for them to govern.
  *
  * The feature itself is platform-owned (`platform/devices`): the settings→policy
@@ -13,16 +13,16 @@
  * confirmation flow, and the `phone` tool. This module supplies the three seams
  * that are actually ours and nothing else:
  *
- *   - the peer transport — the same DistributedRuntimeManager the remote surface
+ *   - the peer transport, the same DistributedRuntimeManager the remote surface
  *     pairs devices onto, so a phone paired here is a node here,
- *   - the approval path — the shared approval broker, so the confirmation
+ *   - the approval path, the shared approval broker, so the confirmation
  *     appears wherever the person is looking (terminal, web app, companion),
  *   - the storage root and the live config manager.
  *
  * Constructing this starts nothing. `startHousekeeping()` is called from the
  * bootstrap tail: grants and captures both outlive a restart, so a grant whose
  * phone is gone, or a capture torn by a crash, is reaped BEFORE the first
- * request of this run is served — and the periodic sweep after it is what keeps
+ * request of this run is served, and the periodic sweep after it is what keeps
  * a long-running daemon from going days without one. A failed sweep is logged
  * and the app still runs: housekeeping failing is a reason to say so, not a
  * reason to refuse to start.
@@ -52,8 +52,8 @@ export interface DevicePostureCompositionOptions {
   /**
    * Binding the catalog turns the whole devices.* family from
    * cataloged-but-unhandled into real handlers: nodes.list, grants.*,
-   * housekeeping.run, and — since a surface with no device runtime of its own
-   * could read the grants and never open a camera — capability.request and
+   * housekeeping.run, and, since a surface with no device runtime of its own
+   * could read the grants and never open a camera, capability.request and
    * artifacts.list/read. That is what makes the paired phone usable from the web
    * app and the companion rather than only through this process's own tool.
    *
@@ -85,8 +85,8 @@ export function createDevicePostureServices(options: DevicePostureCompositionOpt
 
 /**
  * Everything a host with a tool registry has to do once it is up: register the
- * `phone` tool — the only path that reaches the capability service, so without it
- * the posture keys govern nothing a session can observe — and start housekeeping.
+ * `phone` tool, the only path that reaches the capability service, so without it
+ * the posture keys govern nothing a session can observe, and start housekeeping.
  *
  * One call, because these two belong to the same feature and a host that did the
  * first and forgot the second would serve requests while never reaping a grant
@@ -103,7 +103,7 @@ export function installDevicePosture(
 /**
  * The recovery sweep plus the periodic timer. Separate from construction so
  * composing a runtime in a test starts no timer and touches no disk, and
- * separate from the call above so this daemon — which registers no tools —
+ * separate from the call above so this daemon, which registers no tools,
  * still sweeps.
  */
 export function startDeviceHousekeeping(devicePosture: DevicePostureRuntime): void {