@pellux/goodvibes-daemon 1.28.19 → 1.28.21

package/src/daemon/handlers/remote/peer-registry.ts

@@ -27,7 +27,7 @@ export interface SshBackendConfig {
   sshHost: string;
   sshPort?: number;
   sshUser: string;
-  /** goodvibes://secrets/ reference to the private key — never the raw key. */
+  /** goodvibes://secrets/ reference to the private key, never the raw key. */
   identityRef: string;
 }
 
@@ -71,7 +71,7 @@ export interface PeerRegistrationInput {
 }
 
 // ---------------------------------------------------------------------------
-// Validation helpers — backendConfig must hold ONLY secret refs for any
+// Validation helpers, backendConfig must hold ONLY secret refs for any
 // credential-bearing field. Raw secrets are rejected outright.
 // ---------------------------------------------------------------------------
 
@@ -111,9 +111,9 @@ function requireSecretRef(value: unknown, field: string): string {
 function assertDockerHostSafe(value: string | undefined, field: string): void {
   // A dockerHost is accepted in exactly two shapes, mirroring how docker.ts
   // resolves it (docker.ts: `startsWith('goodvibes://') ? resolveRef(...) : raw`):
-  //   1. A goodvibes://secrets/ reference — resolved from the credential store.
+  //   1. A goodvibes://secrets/ reference, resolved from the credential store.
   //   2. A credential-free local/plain address (unix:// socket, or a bare
-  //      tcp/host with no embedded userinfo) — used verbatim.
+  //      tcp/host with no embedded userinfo), used verbatim.
   // Enforcement here must match that resolution so no credential-bearing or
   // unresolvable value slips through to docker.ts.
   if (value === undefined) return;
@@ -123,7 +123,7 @@ function assertDockerHostSafe(value: string | undefined, field: string): void {
 
   // A `goodvibes://` value that is NOT a well-formed secret ref would be handed
   // to credentials.resolveRef() and fail opaquely (REMOTE_BACKEND_CREDENTIAL_MISSING)
-  // — or, worse, a near-miss could be treated as a literal host. Reject it at
+  //, or, worse, a near-miss could be treated as a literal host. Reject it at
   // registration so the misconfiguration surfaces immediately.
   if (isMalformedGoodVibesSecretReferenceValue(value)) {
     throw new PeerRegistryValidationError(
@@ -132,7 +132,7 @@ function assertDockerHostSafe(value: string | undefined, field: string): void {
   }
 
   // Embedded userinfo credentials (e.g. tcp://user:pass@host) must never be
-  // stored raw — docker.ts would pass them verbatim as DOCKER_HOST.
+  // stored raw, docker.ts would pass them verbatim as DOCKER_HOST.
   if (value.includes('@')) {
     throw new PeerRegistryValidationError(
       `Field '${field}' appears to embed credentials; pass a goodvibes://secrets/ reference instead.`,
@@ -226,7 +226,7 @@ export function normalizeBackendConfig(
 }
 
 // ---------------------------------------------------------------------------
-// Peer registry — persisted via HandlerSqliteStore (peer-registry.sqlite)
+// Peer registry, persisted via HandlerSqliteStore (peer-registry.sqlite)
 // ---------------------------------------------------------------------------
 
 const PEER_REGISTRY_FILE = 'peer-registry.sqlite';
@@ -247,21 +247,62 @@ interface PeerRow {
   backendConfig: string;
 }
 
-const VALID_BACKEND_KINDS: ReadonlySet<BackendKind> = new Set([
+// Typed ReadonlySet<string> (not ReadonlySet<BackendKind>) so isBackendKind
+// below can call .has() with a plain string and let the function's own `value
+// is BackendKind` signature do the narrowing, instead of casting the set.
+const VALID_BACKEND_KINDS: ReadonlySet<string> = new Set<BackendKind>([
   'docker',
   'ssh',
   'cloud-terminal',
   'local-process',
 ]);
 
+/** True when `value` is one of the four known backend kinds; narrows to BackendKind. */
+function isBackendKind(value: string): value is BackendKind {
+  return VALID_BACKEND_KINDS.has(value);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Turn a stored row back into a typed PeerRecord. backendConfig is written
+ * only by register() through normalizeBackendConfig(), but a row read back
+ * from disk is untrusted the same way a fresh registration's raw input is: a
+ * hand-edited database file, a row left over from a schema this file no
+ * longer writes, or on-disk corruption can all put something here that was
+ * never actually normalized. Re-running it through normalizeBackendConfig
+ * catches that at the read boundary instead of handing a malformed object to
+ * a caller that assumes register()'s guarantees already hold.
+ */
 function rowToRecord(row: PeerRow): PeerRecord {
-  const backendKind = row.backendKind as BackendKind;
-  const parsed = JSON.parse(row.backendConfig) as BackendConfig;
+  if (!isBackendKind(row.backendKind)) {
+    throw new PeerRegistryValidationError(
+      `Peer '${row.peerId}' has an unknown backendKind '${row.backendKind}'; the row is corrupt or from an unsupported version.`,
+    );
+  }
+  const backendKind = row.backendKind;
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(row.backendConfig);
+  } catch {
+    throw new PeerRegistryValidationError(
+      `Peer '${row.peerId}' has a backendConfig that is not valid JSON; the row is corrupt.`,
+    );
+  }
+  if (!isPlainObject(raw)) {
+    throw new PeerRegistryValidationError(
+      `Peer '${row.peerId}' has a backendConfig that is not an object; the row is corrupt.`,
+    );
+  }
+
   return {
     peerId: row.peerId,
     displayName: row.displayName,
     backendKind,
-    backendConfig: parsed,
+    backendConfig: normalizeBackendConfig(backendKind, raw),
   };
 }
 
@@ -335,10 +376,18 @@ export class PeerRegistry {
     return rows.map(rowToRecord);
   }
 
-  /** Remove a peer. Returns true when a row was deleted. */
+  /**
+   * Remove a peer. Returns true when a row was deleted. Existence is checked
+   * without row validation so a corrupt row (which get() rejects) can still
+   * be removed.
+   */
   async remove(peerId: string): Promise<boolean> {
     this.requireInit();
-    const existed = this.get(peerId) !== null;
+    const row = this.store.all<{ peerId: string }>(
+      'SELECT peerId FROM peers WHERE peerId = ?',
+      [peerId],
+    );
+    const existed = row.length > 0;
     if (existed) {
       this.store.run('DELETE FROM peers WHERE peerId = ?', [peerId]);
       await this.store.save();

package/src/daemon/handlers/routing/inbox-bridge.ts

@@ -9,22 +9,22 @@
 // `getProfileForChannel(surfaceKind, routeId?)` applies the canonical
 // resolution order:
 //
-//   1. exact     — surfaceKind AND routeId both match
-//   2. surface   — surfaceKind matches, route has no routeId
-//   3. wildcard  — a route with surfaceKind === 'any' (no routeId)
+//   1. exact    , surfaceKind AND routeId both match
+//   2. surface  , surfaceKind matches, route has no routeId
+//   3. wildcard , a route with surfaceKind === 'any' (no routeId)
 //
 // This module bridges the two shapes. The bridge maps an inbound item's
 // `provider` to the routing `surfaceKind` and forwards an optional `routeId`
 // refinement; `fromDigest`/`kind` are NOT used as routing keys (the routing
 // store is keyed by surfaceKind + optional routeId only, never by sender digest
-// or message kind — see RoutingChannelRoute). When no binding matches the
+// or message kind, see RoutingChannelRoute). When no binding matches the
 // resolver returns null and the bridge yields `undefined`, so the adapter falls
 // back to leaving the item unrouted (offline/default behaviour intact). The
 // bridge NEVER throws: the underlying resolver is a pure in-memory lookup.
 //
 // The inbox surface is a separate follow-up module, so this bridge declares the
 // minimal `RouteResolver` seam locally rather than importing a sibling that the
-// routing slice does not own — keeping the routing handler layer free of any
+// routing slice does not own, keeping the routing handler layer free of any
 // cross-surface import edge.
 // ---------------------------------------------------------------------------
 

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

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// Channel routing surface — HANDLERS for the SDK-defined methods
+// Channel routing surface, HANDLERS for the SDK-defined methods
 //   - channels.routing.list   (read-only)
 //   - channels.routing.assign (admin, confirmation-gated)
 //   - channels.routing.delete (admin, dangerous, confirmation-gated)

package/src/daemon/handlers/routing/route-store.ts

@@ -96,7 +96,7 @@ const SCHEMA: string[] = [
     updatedAt TEXT NOT NULL
   )`,
   `CREATE INDEX IF NOT EXISTS idx_routes_surface_route ON routes (surfaceKind, routeId)`,
-  // Enforce one assignment per channel — the upsert path relies on this.
+  // Enforce one assignment per channel, the upsert path relies on this.
   `CREATE UNIQUE INDEX IF NOT EXISTS idx_routes_channel ON routes (channelId)`,
 ];
 

package/src/daemon/handlers/routing/routing-resolver.ts

@@ -9,9 +9,9 @@ export const WILDCARD_SURFACE = 'any';
  * order as the agent-side `getProfileForChannel()` so offline and online
  * routing produce identical results:
  *
- *   1. exact match    — surfaceKind AND routeId both match
- *   2. surface-only   — surfaceKind matches, route has no routeId
- *   3. wildcard       — a route with surfaceKind === 'any' (no routeId)
+ *   1. exact match   , surfaceKind AND routeId both match
+ *   2. surface-only  , surfaceKind matches, route has no routeId
+ *   3. wildcard      , a route with surfaceKind === 'any' (no routeId)
  *
  * Returns the matching profileId, or `null` when nothing matches.
  */

package/src/daemon/handlers/sqlite-store.ts

@@ -1,6 +1,6 @@
 /// <reference types="@pellux/goodvibes-sdk/sql-js" />
 // `sql.js` ships no types. The declaration is SDK-owned and reaches here
-// through that reference — there is no local copy to keep in step.
+// through that reference, there is no local copy to keep in step.
 
 import { mkdir, rename, writeFile } from 'node:fs/promises';
 import { readFileSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs';
@@ -23,7 +23,7 @@ export interface SqliteStoreOptions {
 
 /**
  * The 16 bytes every SQLite file begins with ("SQLite format 3" + NUL). A file
- * that does not start with these is not a database, whatever its extension —
+ * that does not start with these is not a database, whatever its extension,
  * which is exactly what a crash mid-create, a zero-fill, or a partially
  * restored backup leaves behind.
  */
@@ -93,7 +93,7 @@ export class HandlerSqliteStore {
   /**
    * Move a database file that cannot be opened aside instead of deleting it, so
    * an operator still has something to salvage, and return the quarantine path.
-   * Returns null when the move itself failed — in which case the caller starts
+   * Returns null when the move itself failed, in which case the caller starts
    * fresh in memory and the bad file is left exactly where it was rather than
    * being overwritten on the next save.
    */
@@ -110,8 +110,8 @@ export class HandlerSqliteStore {
   /**
    * Bound the quarantine directory: drop `.corrupt-*` copies of THIS store that
    * are past the TTL or beyond the keep-newest count. Best-effort and
-   * idempotent — a file another process already removed is success, not an
-   * error — so two daemons opening the same store at once cannot fight.
+   * idempotent, a file another process already removed is success, not an
+   * error, so two daemons opening the same store at once cannot fight.
    * Returns how many were reclaimed.
    */
   private reapCorruptQuarantines(nowMs: number): number {
@@ -158,7 +158,7 @@ export class HandlerSqliteStore {
 
     // Validate the file by its CONTENT, not by existsSync. `save()` writes
     // through a pid-and-timestamp temp file and an atomic rename, so it cannot
-    // itself leave a half-written database — but a zero-filled file recovered
+    // itself leave a half-written database, but a zero-filled file recovered
     // by a filesystem, a truncated restore, or a copy interrupted by something
     // outside this process all produce a path that exists and holds no usable
     // database. Handing those bytes to `new SQL.Database(...)` throws out of
@@ -200,7 +200,7 @@ export class HandlerSqliteStore {
         }
       } catch (error) {
         // Header present but the body does not hold up: a truncated or damaged
-        // database. Same treatment — set aside, disclose, start clean.
+        // database. Same treatment, set aside, disclose, start clean.
         quarantineReason = `database would not open: ${error instanceof Error ? error.message : String(error)}`;
         this.db = null;
         quarantined = this.quarantineUnreadable();
@@ -215,7 +215,7 @@ export class HandlerSqliteStore {
     // Disclosure: starting a store from scratch is data loss from the user's
     // point of view, so it is never allowed to happen quietly.
     if (quarantineReason) {
-      logger.warn('daemon store could not be opened — starting a fresh one', {
+      logger.warn('daemon store could not be opened; starting a fresh one', {
         store: this.options.fileName,
         path: this.resolvedPath,
         reason: quarantineReason,
@@ -266,7 +266,7 @@ export class HandlerSqliteStore {
    * saves of the same store in the SAME millisecond produced the same temp path
    * before it did: both wrote it, the first rename moved it away, and the
    * second failed with ENOENT on a file it had just written. That is not a
-   * hypothetical race — the inbox poller flushes once per provider and polls
+   * hypothetical race, the inbox poller flushes once per provider and polls
    * every provider concurrently, so it hit on an ordinary two-provider startup,
    * and the failure surfaced as a provider reporting a filesystem error for its
    * feed. Every store on this base shares the hazard, so the counter lives here.

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

@@ -5,7 +5,7 @@
 // runtime composition root calls. It DECORATES the inbox surface's
 // `channels.inbox.list` handler (overlaying persisted triage metadata) and
 // returns the poller-facing pipeline + tagger. inbox.triage.* are NOT published
-// catalog methods — this surface registers no triage method id.
+// catalog methods, this surface registers no triage method id.
 // ---------------------------------------------------------------------------
 
 export {

package/src/daemon/handlers/triage/integration.ts

@@ -12,12 +12,12 @@
 //      overlaid with the persisted triageScore/triageTags via
 //      enrichItemsWithTriage(). Every other registration passes straight
 //      through to the real catalog. The inbox descriptor/schema/id is never
-//      re-authored — only its handler is wrapped.
+//      re-authored, only its handler is wrapped.
 //   2. It exposes the triage pipeline + tagger (`runInboxTriage`, `tagger`) for
 //      the daemon-internal poller, which scores items and persists them to the
 //      co-located inbox-triage.sqlite store the decorator reads from.
 //   3. inbox.triage.* are intentionally NOT registered on the catalog (they are
-//      a daemon-internal pipeline, not published methods) — so this module
+//      a daemon-internal pipeline, not published methods), so this module
 //      makes ZERO catalog.register call for any triage id.
 //
 // Reads in the decorator are best-effort and degrade to the raw item when no
@@ -51,7 +51,7 @@ import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 /**
  * Canonical id of the inbox list method whose handler we decorate. This is the
- * SDK's published id — referenced as a plain string for matching during
+ * SDK's published id, referenced as a plain string for matching during
  * registration; no descriptor or schema is authored here.
  */
 export const INBOX_LIST_METHOD_ID = 'channels.inbox.list';

package/src/daemon/handlers/triage/pipeline.ts

@@ -57,7 +57,7 @@ export interface RunInboxTriageOptions {
   scorer?: TriageScorerOptions;
   /** Inject a store (tests). When omitted, a triage store is opened/closed. */
   store?: HandlerSqliteStore;
-  /** When true, do not persist — only compute (used by inbox.triage.list). */
+  /** When true, do not persist, only compute (used by inbox.triage.list). */
   dryRun?: boolean;
   /** Clock injection for deterministic updatedAt in tests. */
   now?: () => Date;
@@ -254,7 +254,7 @@ export function enrichItemsWithTriage<T extends { id: string }>(
   items: readonly T[],
 ): Array<T & TriageOverlay> {
   if (items.length === 0) return [];
-  // Single batched read (`WHERE id IN (...)`) instead of one SELECT per item —
+  // Single batched read (`WHERE id IN (...)`) instead of one SELECT per item,
   // this is a hot read path (every channels.inbox.list call), so the N+1 is
   // collapsed to one query keyed by id.
   const byId = readTriageMetadataBatch(

package/src/daemon/handlers/triage/scorer.ts

@@ -3,7 +3,7 @@
 //
 // Pure, dependency-free heuristic + naive-Bayes-style spam/priority scoring
 // over an InboundChannelItem's textual surface (subject + snippet). No I/O,
-// no credentials, no network — safe to run on every polled item.
+// no credentials, no network, safe to run on every polled item.
 //
 // The score is a normalized 0..1 confidence in the assigned label. The label
 // is one of 'spam' | 'priority' | 'normal'. Scoring is deterministic so the
@@ -247,7 +247,7 @@ export function scoreInboundItem(
   // A trailing question mark suggests an awaited answer.
   if (/\?\s*$/.test(raw)) priorityLL += 0.5;
 
-  // Spam strongly suppresses priority — promotional text is rarely urgent.
+  // Spam strongly suppresses priority, promotional text is rarely urgent.
   priorityLL -= spam * 2.5;
 
   const priority = clamp01(sigmoid(priorityLL));

package/src/daemon/handlers/triage/tagger/discord.ts

@@ -1,10 +1,10 @@
 // ---------------------------------------------------------------------------
-// Triage tagger — Discord provider.
+// Triage tagger, Discord provider.
 //
 // Two paths, in priority order:
 //   1. REAL thread tags: when the item targets a forum/media-channel thread and
 //      a forum-tag mapping resolves >=1 tag id, PATCH the thread's applied_tags
-//      (read-then-merge — never blind overwrite). Exact fidelity to the
+//      (read-then-merge, never blind overwrite). Exact fidelity to the
 //      contract's "Discord thread tags".
 //   2. Reaction analog: Discord has no arbitrary per-message tags, so otherwise
 //      add a unicode reaction (PUT .../reactions/{emoji}/@me).
@@ -114,7 +114,7 @@ async function applyDiscordThreadTags(
   // DATA-LOSS GUARD: we PATCH the thread's full applied_tags array, so we must
   // first read the EXISTING tags and merge. If that read fails (network error
   // OR a non-ok HTTP status), we have no idea what tags are currently on the
-  // thread — PATCHing with only our new ids would silently destroy whatever
+  // thread, PATCHing with only our new ids would silently destroy whatever
   // forum tags were already applied. Abort instead of overwriting.
   const existing = await fetchDiscordAppliedTags(url, token, fetchImpl, ctx);
   if (existing === null) {

package/src/daemon/handlers/triage/tagger/imap.ts

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// Triage tagger — IMAP provider.
+// Triage tagger, IMAP provider.
 //
 // Applies a triage label as an IMAP keyword flag (STORE +FLAGS) over a minimal
 // IMAP4rev1-over-TLS client. Credentials are resolved per-apply from the daemon
@@ -63,7 +63,7 @@ export type ImapConnect = (opts: {
   servername: string;
 }) => ImapSocketLike;
 
-/** Production connector — a real IMAP4rev1-over-TLS socket via node:tls. */
+/** Production connector, a real IMAP4rev1-over-TLS socket via node:tls. */
 export const tlsImapConnect: ImapConnect = (opts) =>
   tlsConnect(opts, () => {
     /* greeting handled in the data pump */
@@ -128,7 +128,7 @@ export class ImapStoreError extends Error {
  * in a value destined for an IMAP command line. CR/LF are the dangerous ones:
  * an unescaped CRLF would terminate the current command and let an attacker
  * inject a second IMAP command (CRLF injection). IMAP's quoted-string syntax
- * has no escape for these control chars — backslash only escapes `\` and `"` —
+ * has no escape for these control chars, backslash only escapes `\` and `"`,
  * so the only safe handling is to refuse the value outright.
  */
 function assertImapSafe(value: string, field: string): void {
@@ -155,8 +155,8 @@ function quoteImap(value: string): string {
 // A concrete UID sequence-set: one or more comma-separated single UIDs or
 // numeric ranges (`12`, `3:9`, `1,4,7:9`). RFC 3501 also permits `*` (the
 // largest UID in the mailbox) and ranges to `*`, but a wildcard would let a
-// single value like `1:*` apply the flag to the ENTIRE mailbox — never the
-// intent when tagging one triaged item — so `*` is rejected outright.
+// single value like `1:*` apply the flag to the ENTIRE mailbox, never the
+// intent when tagging one triaged item, so `*` is rejected outright.
 const IMAP_UID_SET = /^[0-9]+(:[0-9]+)?(,[0-9]+(:[0-9]+)?)*$/;
 
 // An IMAP flag: an optional leading `\` (system flag, e.g. `\Seen`) followed by
@@ -187,7 +187,7 @@ function assertImapUid(value: string): void {
  * UNQUOTED into the `+FLAGS (...)` list. assertImapSafe only blocks control
  * chars; a flag containing a space (e.g. `\Seen Junk`) would still pass that
  * guard and inject a second flag atom. This is the boundary check that
- * prevents it — independent of any upstream normalizer.
+ * prevents it, independent of any upstream normalizer.
  */
 function assertImapFlag(value: string): void {
   if (!IMAP_FLAG.test(value)) {
@@ -313,7 +313,7 @@ export function imapStoreFlagOverTls(
           finish();
         }
       } else {
-        // NO/BAD: deterministic protocol rejection — do not retry.
+        // NO/BAD: deterministic protocol rejection, do not retry.
         current.reject(new ImapStoreError(`IMAP command failed: ${status}`, false));
       }
     };

package/src/daemon/handlers/triage/tagger/index.ts

@@ -159,7 +159,7 @@ export function createTriageTagger(
         return { ...base, reason: 'autotag-disabled' };
       }
 
-      // Provider-side mutation is effectful — require explicit confirmation.
+      // Provider-side mutation is effectful, require explicit confirmation.
       if (request.confirm !== true || request.explicitUserRequest !== true) {
         throw new HandlerError(
           'Provider-side triage tagging requires explicit user confirmation.',

package/src/daemon/handlers/triage/tagger/shared.ts

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// Triage tagger — shared types and provider-agnostic helpers.
+// Triage tagger, shared types and provider-agnostic helpers.
 //
 // Provider config shapes, the apply request/result contract, and the tag
 // normalization helpers used by the IMAP/Slack/Discord modules. No I/O here.
@@ -17,7 +17,7 @@ export interface TaggerProviderConfig {
    * optional forum-tag mapping. When `forumTagIds` maps a GoodVibes triage tag
    * (e.g. 'GoodVibes/Spam') to a forum tag SNOWFLAKE id, items that target a
    * forum/media-channel thread get that REAL thread tag applied (PATCH
-   * applied_tags) — exact fidelity to the contract's "Discord thread tags".
+   * applied_tags), exact fidelity to the contract's "Discord thread tags".
    * Without a mapping (or for non-thread messages) tagging degrades to a
    * unicode reaction analog.
    */
@@ -29,7 +29,7 @@ export interface ApplyTagsRequest {
   /** Provider-side tags to apply. Defaults to [labelToTag(label)] when omitted. */
   tags?: readonly string[];
   label?: TriageLabel;
-  /** Must be true — provider-side mutation requires explicit confirmation. */
+  /** Must be true, provider-side mutation requires explicit confirmation. */
   confirm?: boolean;
   /** Mirror of the operator invocation context flag. */
   explicitUserRequest?: boolean;

package/src/daemon/handlers/triage/tagger/slack.ts

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// Triage tagger — Slack provider.
+// Triage tagger, Slack provider.
 //
 // Applies a triage label as a Slack message reaction (reactions.add). The bot
 // token is resolved per-apply from the daemon credential store and is never

package/src/daemon/handlers/triage/types.ts

@@ -5,7 +5,7 @@
 // and the triage pipeline scores. It is NOT an SDK catalog contract: the
 // published `channels.inbox.list` output schema (CHANNEL_INBOX_ITEM_SCHEMA) is
 // owned by the SDK and never re-declared here. This is the internal poller
-// item per the handoff doc — it carries `fromDigest` (never a raw sender id),
+// item per the handoff doc, it carries `fromDigest` (never a raw sender id),
 // `subjectPreview`/`bodyPreview` (PII-stripped, length-bounded) and an opaque
 // `metadata` bag the tagger reads provider targeting from (imapUid, channelId,
 // Slack ts, Discord messageId/threadId).
@@ -31,7 +31,7 @@ export interface InboundChannelItem {
   /** Handoff-facing provider id ("slack" | "discord" | "email" | ...). */
   readonly provider?: string;
   readonly kind?: 'dm' | 'thread' | 'mention' | 'reaction';
-  /** SHA-256 first-N of sender external id — NEVER a raw identifier. */
+  /** SHA-256 first-N of sender external id, NEVER a raw identifier. */
   readonly fromDigest?: string;
   /** Conversation id (Slack/Discord channel, IMAP mailbox-scoped). */
   readonly conversationId?: string;

package/src/daemon/lifecycle.ts

@@ -1,5 +1,5 @@
 /**
- * lifecycle.ts — resolve THIS binary's update-artifact identity for the SDK
+ * lifecycle.ts, resolve THIS binary's update-artifact identity for the SDK
  * DaemonServer facade's auto-update lifecycle.
  *
  * The SDK facade now runs the entire self-update loop itself when handed a
@@ -7,12 +7,12 @@
  * version against the release tags (no longer the version-blind sdk-package
  * comparison that used to restart-loop), swaps only at an idle moment, keeps
  * the outgoing file at `<path>.previous`, and leaves a receipt in the store it
- * serves on /status. When the artifact is ABSENT, updates are host-managed —
+ * serves on /status. When the artifact is ABSENT, updates are host-managed,
  * the facade runs no loop (the safe embedded default).
  *
  * The one guard the facade does NOT apply is install-kind: it must never swap a
  * dev `bun run daemon` interpreter or a bun-global package install. This helper
- * is that guard — it hands the facade an artifact ONLY for a compiled binary
+ * is that guard, it hands the facade an artifact ONLY for a compiled binary
  * install, so a dev run resolves to `undefined` (host-managed, no loop) and
  * only a real self-contained binary self-updates.
  */
@@ -23,13 +23,13 @@ import { detectInstallKind } from '../runtime/update-check.ts';
 export interface ResolveDaemonUpdateArtifactOptions {
   /** The executable to identify; defaults to process.execPath. */
   readonly execPath?: string;
-  /** Injectable so tests pin a fixture version — never the live build VERSION. */
+  /** Injectable so tests pin a fixture version, never the live build VERSION. */
   readonly version?: string;
 }
 
 /**
  * The update-artifact identity to hand the DaemonServer facade, or `undefined`
- * for a non-binary install (dev/source or bun-global package) — in which case
+ * for a non-binary install (dev/source or bun-global package), in which case
  * the facade keeps updates host-managed and runs no swap loop.
  */
 export function resolveDaemonUpdateArtifact(

package/src/daemon/local-daemon-state.ts

@@ -1,5 +1,5 @@
 /**
- * local-daemon-state.ts — the two files a daemon writes about ITSELF.
+ * local-daemon-state.ts, the two files a daemon writes about ITSELF.
  *
  * `status` and `update` want to report things no control-plane verb answers:
  * how long the daemon has been up, whether the last start followed a crash,
@@ -11,7 +11,7 @@
  *   <control-plane config dir>/control-plane/daemon-receipts.json
  *
  * They are READ here and never written, and the receipts are never marked
- * delivered — `/status?receipts=consume` hands each receipt to the first
+ * delivered, `/status?receipts=consume` hands each receipt to the first
  * consuming reader exactly once, and a status command that quietly consumed
  * them would take them away from the surface they were written for.
  *
@@ -22,7 +22,7 @@
  * The SDK owns the writers (`platform/daemon/lifecycle-marker.ts`,
  * `platform/daemon/receipts.ts`) and its readers are not exported from the
  * published package this repository pins, so the readers below are this
- * repository's own — bounded and content-validated the same way, and no more
+ * repository's own, bounded and content-validated the same way, and no more
  * trusting of the file than the SDK is. The shared-piece lane can re-point them
  * at the SDK's own readers once those are exported.
  */
@@ -42,7 +42,7 @@ export interface DaemonLifecycleMarker {
   readonly pid: number | undefined;
   readonly failedStarts: number;
   readonly version: string | undefined;
-  /** The version an automatic rollback moved AWAY from — the build that crash looped. */
+  /** The version an automatic rollback moved AWAY from, the build that crash looped. */
   readonly rejectedVersion: string | undefined;
   /** When an automatic rollback last restored the kept previous binary. */
   readonly autoRollbackAt: number | undefined;
@@ -164,7 +164,7 @@ export function readDaemonReceipts(
 }
 
 export interface LocalDaemonState {
-  /** False when the caller asked about another machine — nothing below was read. */
+  /** False when the caller asked about another machine, nothing below was read. */
   readonly available: boolean;
   /** Why it is unavailable, when it is. */
   readonly unavailableReason: string | undefined;
@@ -195,7 +195,7 @@ export function describeLocalDaemonState(input: DescribeLocalDaemonStateInput):
     return {
       available: false,
       unavailableReason:
-        'the uptime, update receipts and rollback state are read from files on the daemon\'s own host — '
+        'the uptime, update receipts and rollback state are read from files on the daemon\'s own host; '
         + 'run this command on that machine to see them',
       marker: null,
       receipts: [],
@@ -219,7 +219,7 @@ export function describeLocalDaemonState(input: DescribeLocalDaemonStateInput):
   };
 }
 
-/** `3d 4h`, `4h 12m`, `12m 3s`, `9s` — two units, never more. */
+/** `3d 4h`, `4h 12m`, `12m 3s`, `9s`, two units, never more. */
 export function formatDuration(milliseconds: number): string {
   const totalSeconds = Math.max(0, Math.floor(milliseconds / 1000));
   const days = Math.floor(totalSeconds / 86_400);