@pellux/goodvibes-daemon 1.28.19 → 1.28.21

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.
  */
@@ -20,6 +20,8 @@ import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { ClusterCoordinator } from '@pellux/goodvibes-sdk/platform/cluster';
 import type { GatewayMethodCatalog } from '@pellux/goodvibes-sdk/platform/control-plane';
 import type { SecretsManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ChannelDeliveryRouter } from '@pellux/goodvibes-sdk/platform/channels';
+import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
 import { registerDaemonHandlers, type DaemonHandlerSurfaces } from '../daemon/handlers/index.ts';
 import type { HandlerContext, HandlerLogger } from '../daemon/handlers/context.ts';
 import { createDaemonCredentialStore } from '../daemon/handlers/credentials.ts';
@@ -28,7 +30,10 @@ 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';
+import type { BrowserCheckoutSeamHolder } from './browser-checkout-seam-holder.ts';
 
 export interface DaemonHandlerCompositionOptions {
   readonly gatewayMethods: GatewayMethodCatalog;
@@ -36,12 +41,23 @@ 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
    * composition root; the poller is never started outside it.
    */
   readonly clusterCoordinator: ClusterCoordinator;
+  /**
+   * Where `payments.checkout.*` reads the browser-checkout seam, filled later
+   * by services.ts's own `onBrowserCheckout`. See
+   * runtime/browser-checkout-seam-holder.ts and payments-composition.ts's
+   * header for why this has to be a getter rather than the seam itself.
+   */
+  readonly checkoutSeam: BrowserCheckoutSeamHolder['get'];
+  readonly channelDeliveryRouter: Pick<ChannelDeliveryRouter, 'deliver'>;
+  readonly providerRegistry: Pick<ProviderRegistry, 'getCurrentModel' | 'getForModel'>;
 }
 
 export function createDaemonHandlerComposition(
@@ -65,12 +81,53 @@ 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 the
+    // full checkout composition (address store, notifier, merchant judge,
+    // browser-checkout seam).
+    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 it. Checkout is now
+      // wired (payments.checkout.begin/.fillCard), but registering a gate whose
+      // start() does nothing would STILL put a fake consumer in the election and
+      // in `cluster status`; a real election is a separate piece of work, left
+      // for a later pass, not something wiring the checkout pair itself needed.
+      //
+      // So the honest reading of the topology stays what it was: 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.
+      isPaymentsLeader: () => !options.clusterCoordinator.enabled,
+      checkoutSeam: options.checkoutSeam,
+      channelDeliveryRouter: options.channelDeliveryRouter,
+      providerRegistry: options.providerRegistry,
+    }).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 {

package/src/runtime/disposal-wiring.ts

@@ -3,8 +3,8 @@
  *
  * Teardown for every poller the daemon's runtime graph starts.
  *
- * The mechanics — the ordered, best-effort, idempotent scope and the
- * all-required owner list — live in the SDK (`platform/runtime/disposal`), so
+ * The mechanics, the ordered, best-effort, idempotent scope and the
+ * all-required owner list, live in the SDK (`platform/runtime/disposal`), so
  * the daemon and the SDK's own composition root cannot drift into two different
  * ideas of what "stop the graph" means. What lives here is only the mapping from
  * the daemon's assembled graph onto that list, plus the four pollers the daemon
@@ -19,7 +19,7 @@
  * Ownership note, and the reason any of this exists: this product builds the
  * graph and hands the SAME object to `DaemonServer`. The SDK facade disposes
  * only a graph it constructed itself, so it deliberately leaves this one alone
- * — nothing upstream will ever stop these pollers. The shutdown paths in
+ *, nothing upstream will ever stop these pollers. The shutdown paths in
  * daemon/cli.ts and the one-shot CLI commands are the only things that can.
  *
  * The owner type below is declared structurally rather than imported from
@@ -44,7 +44,7 @@ export interface DaemonRuntimePollerOwners extends Omit<RuntimePollerOwners, 'st
   /**
    * Daemon-only: the wake-word recovery sweep and a pending boot provision
    * Started only when an entrypoint opted into boot
-   * provisioning, and a no-op otherwise — but it is on this list unconditionally,
+   * provisioning, and a no-op otherwise, but it is on this list unconditionally,
    * because "the graph did not start it this time" is not a reason for the
    * teardown path to have no way to stop it.
    */
@@ -53,7 +53,7 @@ export interface DaemonRuntimePollerOwners extends Omit<RuntimePollerOwners, 'st
    * Daemon-only: the product handler surfaces (daemon-handler-composition.ts).
    *
    * `unregister()` detaches the gateway handlers AND stops the two pollers this
-   * product's inbox surface owns — the retention sweep inside `InboxCursorStore`
+   * product's inbox surface owns, the retention sweep inside `InboxCursorStore`
    * and the per-provider `InboundPoller` intervals. The SDK does not know either
    * exists, so if this surface does not stop them nothing does.
    */
@@ -68,7 +68,7 @@ export interface DaemonRuntimePollerOwners extends Omit<RuntimePollerOwners, 'st
 
 /**
  * The poller owners this daemon holds that are NOT reachable from the
- * assembled graph — handles the factory keeps as locals.
+ * assembled graph, handles the factory keeps as locals.
  */
 export interface RuntimeDisposalExtras {
   /** Handle returned by `ConfigManager.watchConfigFiles()`. */
@@ -79,7 +79,7 @@ export interface RuntimeDisposalExtras {
  * Register the stop call for every poller the graph started.
  *
  * `services` is the fully-assembled graph, which already exposes each poller
- * owner as a field — so a poller whose owner reaches the public surface is
+ * owner as a field, so a poller whose owner reaches the public surface is
  * wired by name rather than by threading another local out of the factory.
  */
 export function registerDaemonRuntimePollers(
@@ -93,7 +93,7 @@ export function registerDaemonRuntimePollers(
   registry.add('wake-word housekeeping', services.stopWakeHousekeeping);
   // Registered LAST so it tears down FIRST (the scope unwinds in reverse), which
   // is the order daemon/cli.ts already used by hand: release the handler surfaces
-  // — closing the inbox store and stopping its poll timers — before the pollers
+  //, closing the inbox store and stopping its poll timers, before the pollers
   // the rest of the graph owns. Being on this list is what makes a plain
   // `dispose()` total: every shutdown path stops these, not just the one that
   // remembered to call `unregister()` itself.

package/src/runtime/fleet-needs-input-push.ts

@@ -1,10 +1,10 @@
 /**
- * fleet-needs-input-push.ts — wires the fleet "needs-input" browser-push fan-out
+ * fleet-needs-input-push.ts, wires the fleet "needs-input" browser-push fan-out
  * that the SDK's registerGatewayVerbGroups (reached through the terminal-shell's
  * attachWsOnlyGatewayVerbHandlers wrapper) gates on two deps: `runtimeBus` and
  * `sessionPresence` (see push/service.ts's attachFleetNeedsInputSource). When a
  * fleet node blocks on the operator, it pushes an "Input needed" notification
- * carrying the session/node deep link to every registered device — suppressed
+ * carrying the session/node deep link to every registered device, suppressed
  * while an operator surface is already attached to that node's session.
  *
  * TWO seams have to be live for a real push, not just descriptor presence:
@@ -12,8 +12,8 @@
  *     runtime bus's 'fleet' domain in the first place. That is
  *     attachFleetEmitBridge, diffing the process registry's own coalesced
  *     snapshot tick into per-node lifecycle events. The terminal-shell package's
- *     createArchivableFleetRegistry only builds the registry — it does not
- *     attach the bridge — so the composition root that owns both the registry
+ *     createArchivableFleetRegistry only builds the registry, it does not
+ *     attach the bridge, so the composition root that owns both the registry
  *     and the bus (this file) is the one place responsible for it. The SDK's
  *     own daemon composition (platform/runtime/services.ts) attaches this same
  *     bridge right after building its process registry.

package/src/runtime/fleet-services.ts

@@ -1,5 +1,5 @@
 /**
- * fleet-services.ts — the shared, archive-aware fleet registry construction,
+ * fleet-services.ts, the shared, archive-aware fleet registry construction,
  * lifted out of services.ts so the composition root stays under the file-size
  * cap. Mirrors the sibling create*Services helpers (durability, code-index,
  * workstream): a single dependency-injected call that services.ts makes once.

package/src/runtime/hosted-session-composition.ts

@@ -1,11 +1,11 @@
 /**
- * hosted-session-composition.ts — what this daemon states so it may host
+ * hosted-session-composition.ts, what this daemon states so it may host
  * conversation loops.
  *
  * The engine is the SDK's (`@pellux/goodvibes-sdk/platform/hosted-sessions`):
  * lifecycle, the detach policy, the bounded disk state, the verbs, the
  * lifecycle channel. It is off until a product says how a workspace FLOOR is
- * built, and that is deliberate — the floor's `requestApproval` seam is where a
+ * built, and that is deliberate, the floor's `requestApproval` seam is where a
  * product's trust posture lives, and no default can stand in for a decision
  * about who may write files and run commands in a directory a client named over
  * the wire.
@@ -20,8 +20,8 @@
  * session hosted in another directory has to be gated by that directory's
  * decision, not by the daemon's.
  *
- * Everything else in a floor comes from `createClientRuntimeServices` — the
- * same composition a terminal runs — so a hosted turn's tools, hooks, plugins
+ * Everything else in a floor comes from `createClientRuntimeServices`, the
+ * same composition a terminal runs, so a hosted turn's tools, hooks, plugins
  * and model stack are the ones the platform already has, not a second set.
  *
  * ── The exec posture a hosted turn runs under ──────────────────────────────
@@ -29,15 +29,15 @@
  * "The same composition a terminal runs" is what BUILDS the exec tool, and it
  * builds it the same way here: the `sandbox.*` config and the `exec-sandbox`
  * gate this daemon already reads produce the same bubblewrap boundary a local
- * exec gets — network, PID, UTS and IPC namespaced, the system read-only, /tmp
+ * exec gets, network, PID, UTS and IPC namespaced, the system read-only, /tmp
  * and $HOME masked, the workspace writable, and `sandbox.egressAllowlist` the
- * one way network comes back — with the self-labelling note on every result.
+ * one way network comes back, with the self-labelling note on every result.
  *
  * What was NOT the same was the fallback. When no boundary could be applied,
  * the exec tool ran the command on the host and said so, which is right for a
  * terminal (a person asked, a person is reading) and wrong for a turn nobody is
  * watching. A hosted conversational turn reached the whole host that way: the
- * full process table, the owner's /proc, and his tmux session — where it typed.
+ * full process table, the owner's /proc, and his tmux session, where it typed.
  *
  * So this daemon states the posture rather than inheriting a default:
  *
@@ -46,8 +46,8 @@
  *    REQUIRED: a command that cannot be contained is refused, naming why, and
  *    running on the host is not a fallback available to it. The owner's
  *    terminal is denied outright, at the exec guard, regardless of boundary.
- *  - WORKSTREAM — a real work chain the owner authorized, which may genuinely
- *    need the machine itself — is a per-spawn grant this composition makes
+ *  - WORKSTREAM, a real work chain the owner authorized, which may genuinely
+ *    need the machine itself, is a per-spawn grant this composition makes
  *    explicitly. There is no such spawn today, so the function below never
  *    returns it; when there is one, the grant is written HERE, in the daemon's
  *    own composition, where a reader can see which spawns hold it. Nothing on
@@ -75,13 +75,13 @@ function hostedSystemPrompt(input: { readonly workspaceRoot: string }): string {
     [
       'You are a GoodVibes session hosted by the daemon rather than by a terminal.',
       `Your working directory is ${input.workspaceRoot}.`,
-      'Someone may be attached and watching this turn, or may have detached and read it later —',
+      'Someone may be attached and watching this turn, or may have detached and read it later;',
       'write for both. Say what you did and why; never report work you did not do.',
       'Tool permissions are decided by whoever is attached: an ask you raise may take a while to be',
       'answered, and an unanswered one is a refusal, not a reason to find another way round.',
     ].join(' '),
     // The same contract every other conversational turn is held to, from the
-    // SDK rather than restated here — a second copy is a copy that drifts.
+    // SDK rather than restated here, a second copy is a copy that drifts.
     CONVERSATIONAL_DIAGNOSIS_SECTION,
   ].join('\n\n');
 }
@@ -92,7 +92,7 @@ function hostedSystemPrompt(input: { readonly workspaceRoot: string }): string {
  * Every session this daemon hosts is a conversation, so every one of them is
  * contained (see the module header). Stated on the floor rather than left to
  * the engine's default so that the day a workstream spawn exists, the grant is
- * a visible change to THIS function and not an option someone set elsewhere —
+ * a visible change to THIS function and not an option someone set elsewhere,
  * and it sits beside the trust gate, which is the other statement this daemon
  * makes about how much authority a hosted run carries.
  */
@@ -162,7 +162,7 @@ export function createHostedSessionOptions(services: RuntimeServices): DaemonHos
       // boot (the persisted discovery cache) and from the LAN scan; a floor
       // builds its own registry and would otherwise be the only place on this
       // box where they are not routable. Servers found by a scan that finishes
-      // AFTER a floor is built reach the next floor, not this one — stated
+      // AFTER a floor is built reach the next floor, not this one, stated
       // rather than hidden, because a wrong claim here would look like a model
       // that exists everywhere except in hosted sessions.
       const discovered = services.providerRegistry.listDiscoveredServers();

package/src/runtime/index.ts

@@ -15,7 +15,7 @@
 // Type-only: the runtime namespace objects must never be READ at module scope.
 // An eager `export const X = ns.X` compiles to a top-level property read off a
 // lazy namespace object, and Bun's single-file compiler orders module bodies
-// nondeterministically — on some builds the read lands before the defining
+// nondeterministically, on some builds the read lands before the defining
 // module and the binary dies at load. Values below are grouped live re-exports
 // from the SDK's registered subpaths instead; the toolchain post-build-smoke
 // scans compiled artifacts for the eager pattern and fails the build if one

package/src/runtime/knowledge-services.ts

@@ -1,11 +1,11 @@
 // ---------------------------------------------------------------------------
-// knowledge-services.ts — the knowledge/wiki + home-graph stack
+// knowledge-services.ts, the knowledge/wiki + home-graph stack
 //
 // Constructs the three KnowledgeStores (regular wiki, agent, home-graph), their
 // semantic services, the ingest services, the home-graph service, and the
 // project-planning + work-plan stores. Extracted into its own module rather
 // than built inline in services.ts, which sits at the architecture check's
-// 800-line cap (scripts/check-architecture.ts) — new/large construction blocks
+// 800-line cap (scripts/check-architecture.ts), new/large construction blocks
 // get their own module and a single wiring call there (mirrors
 // createWorkstreamServices / createDurabilityServices / createCodeIndexServices).
 //