@pellux/goodvibes-daemon 1.28.0

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

@@ -0,0 +1,448 @@
+/**
+ * The unattended startup reconcile for the redundant install-script
+ * `goodvibes-daemon.service` unit — split out of `legacy-daemon-migration.ts`
+ * (which owns the shared unit definition, detection, and the CONSENTED
+ * `migrate-service` engine) so each module stays within the architecture
+ * gate's file-size cap. Same layer (`src/runtime/`), same injectable-seam
+ * discipline; see the sibling module's banner for the naming and layering
+ * rationale.
+ */
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import {
+  defaultActionRunner,
+  defaultPortProbe,
+  legacyUnitPath,
+  parseMainPid,
+  LEGACY_SERVICE_UNIT_NAME,
+  SYSTEMCTL_TIMEOUT_MS,
+  type ManagedServiceActionRunner,
+} from './legacy-daemon-migration.ts';
+
+type ManagedServiceActionResult = ReturnType<ManagedServiceActionRunner>;
+
+/**
+ * The exact marker string scripts/install.sh writes into every unit it
+ * creates (as a `# managed by goodvibes install.sh` comment). The reconcile
+ * check below keys on it to tell an installer-created legacy unit — safe to
+ * auto-retire — apart from a hand-written one that must only ever be reported.
+ * Kept in lockstep with `INSTALLER_MARKER` in scripts/install.sh.
+ */
+export const INSTALLER_UNIT_MARKER = 'managed by goodvibes install.sh';
+
+
+
+/**
+ * CUMULATIVE ceiling on the reconcile's whole boot-path pass. Per-call
+ * timeouts alone still allow ~5 sequential slow-but-completing calls to stack
+ * up (a degraded — not wedged — user bus), blocking the already-listening
+ * daemon's event loop for tens of seconds. One overall deadline covers the
+ * pass: once it is exceeded, every remaining call is skipped (reported as
+ * `status: null`, which the guards treat as unknown → refusal) and the result
+ * carries a notice saying so.
+ */
+export const RECONCILE_DEADLINE_MS = 8_000;
+
+
+
+/**
+ * Wrap a runner with the reconcile's cumulative deadline: calls after the
+ * deadline are skipped outright; calls near it get only the remaining budget
+ * as their per-call timeout (default runner only — injected runners are test
+ * fakes that answer instantly).
+ */
+function makeDeadlineBoundRunner(
+  injected: ManagedServiceActionRunner | undefined,
+  perCallTimeoutMs: number,
+  deadlineMs: number,
+): { run: ManagedServiceActionRunner; deadlineHit: () => boolean } {
+  const startedAt = Date.now();
+  let hit = false;
+  const run: ManagedServiceActionRunner = (command, args) => {
+    const remaining = deadlineMs - (Date.now() - startedAt);
+    if (remaining <= 0) {
+      hit = true;
+      return { status: null, stdout: '', stderr: 'reconcile time budget exceeded — call skipped' } as ManagedServiceActionResult;
+    }
+    if (injected) return injected(command, args);
+    return defaultActionRunner(Math.min(perCallTimeoutMs, remaining))(command, args);
+  };
+  return { run, deadlineHit: () => hit };
+}
+
+
+
+export interface ReconcileRedundantLegacyUnitInput {
+  readonly homeDir: string;
+  /** The unit name this tool manages (e.g. 'goodvibes'). */
+  readonly trackedServiceName: string;
+  /**
+   * The endpoint CLIENTS resolve from settings.json (no runtime flag
+   * overrides). When provided, the reconcile requires this endpoint to be
+   * answering before it retires anything: a canonical daemon that is alive on
+   * some other port must never retire the unit clients actually reach.
+   */
+  readonly configuredEndpoint?: { readonly host: string; readonly port: number } | undefined;
+  /** Injectable probe of the configured endpoint. Defaults to `defaultPortProbe`. */
+  readonly endpointProbe?: ((host: string, port: number) => boolean | Promise<boolean>) | undefined;
+  /** Injectable existsSync so tests never touch the host filesystem. */
+  readonly legacyUnitFileExists?: ((path: string) => boolean) | undefined;
+  /** Injectable unit-file read for the installer-marker check. */
+  readonly legacyUnitFileRead?: ((path: string) => string) | undefined;
+  /** Injectable removal of the legacy unit file. Defaults to a real `rmSync`. */
+  readonly legacyUnitFileRemove?: ((path: string) => void) | undefined;
+  /** Injectable systemctl runner (is-active/MainPID probes + disable/daemon-reload). */
+  readonly actionRunner?: ManagedServiceActionRunner | undefined;
+  /** Injectable liveness check for unit MainPIDs. Defaults to a signal-0 probe. */
+  readonly processAlive?: ((pid: number) => boolean) | undefined;
+  /** This process's pid, for the self-supervision guard. Defaults to `process.pid`. */
+  readonly ownPid?: number | undefined;
+  /** Injectable /proc/self/cgroup read, for the self-supervision guard. */
+  readonly readOwnCgroup?: (() => string) | undefined;
+  /** Timeout applied to the DEFAULT systemctl runner only. Defaults to SYSTEMCTL_TIMEOUT_MS. */
+  readonly systemctlTimeoutMs?: number | undefined;
+  /**
+   * Program the DEFAULT runner executes. Defaults to `systemctl` (resolved on
+   * PATH). Tests that deliberately exercise the default (non-injected) runner
+   * point this at an absolute stub path: Bun resolves a spawned program from
+   * the PATH captured at process start, so mutating `process.env.PATH` inside
+   * a test cannot redirect the call and the host's real systemctl would answer.
+   */
+  readonly systemctlCommand?: string | undefined;
+  /** Cumulative budget for the whole pass. Defaults to RECONCILE_DEADLINE_MS. */
+  readonly deadlineMs?: number | undefined;
+}
+
+export type ReconcileRedundantLegacyUnitReason =
+  | 'no-legacy-unit'
+  | 'canonical-not-active'
+  | 'canonical-mainpid-not-alive'
+  | 'self-supervised-by-legacy'
+  | 'legacy-state-unknown'
+  | 'legacy-running'
+  | 'configured-endpoint-unserved'
+  | 'hand-written'
+  | 'marker-unreadable'
+  | 'disable-failed'
+  | 'disable-timeout'
+  | 'retired';
+
+export interface ReconcileRedundantLegacyUnitResult {
+  /**
+   * 'removed' = legacy unit auto-retired; 'notice' = left alone with a printed
+   * hint (hand-written, or unreadable); 'failed' = retirement was attempted but
+   * a destructive step failed or its outcome could not be confirmed (this tool
+   * removed nothing); 'noop' = guard refused or nothing to do.
+   */
+  readonly action: 'removed' | 'notice' | 'noop' | 'failed';
+  /** Machine-readable why, so callers can leave a breadcrumb for every refusal. */
+  readonly reason: ReconcileRedundantLegacyUnitReason;
+  readonly lines: readonly string[];
+}
+
+function defaultProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultReadOwnCgroup(): string {
+  try {
+    return readFileSync('/proc/self/cgroup', 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Cheap, unattended startup reconcile for the exact host state the production
+ * incident surfaced: an installer-managed legacy `goodvibes-daemon.service`
+ * unit sitting ENABLED alongside the canonical `goodvibes.service` that is
+ * ENABLED + ACTIVE. Nothing ever disabled the redundant legacy unit, so a
+ * bare-args second daemon could boot and fight the real one for the port.
+ *
+ * This runs on daemon startup (no user invocation needed) and, guard-railed:
+ *   - Only acts when the canonical unit is CONFIRMED serving: `is-active`
+ *     reports active AND its MainPID resolves to a live process. `is-active`
+ *     alone is not proof — a Type=simple unit reports active from fork onward,
+ *     including the pre-bind window of a daemon that is about to crash-loop.
+ *   - NEVER acts from inside the legacy unit itself: if this process IS the
+ *     legacy unit's MainPID, or /proc/self/cgroup names the legacy unit,
+ *     running `disable --now` would SIGTERM the very daemon executing this
+ *     code (mid-boot, from inside a blocking spawnSync). Refuses instead.
+ *   - NEVER stops a RUNNING legacy daemon: if the legacy unit's MainPID is a
+ *     live process, it may be the daemon serving the endpoint clients are
+ *     configured to reach (the wrong-port two-daemon state) — the unattended
+ *     path only retires enabled-but-NOT-running legacy units; a running one
+ *     gets a notice pointing at the consented migrate-service.
+ *   - Requires the CONFIGURED endpoint (the one clients resolve from
+ *     settings.json, no runtime overrides) to be answering before retiring —
+ *     a canonical daemon alive on some other port proves nothing about the
+ *     endpoint clients use.
+ *   - AUTO-RETIRES only an installer-MARKER-managed legacy unit, and only
+ *     removes its unit file AFTER `disable --now` reports success. A NONZERO
+ *     exit leaves everything in place and says so; a TIMED-OUT disable
+ *     (status null) has an UNKNOWN outcome — the enablement state is
+ *     re-inspected before anything is printed, and the receipt states what
+ *     was actually confirmed, never a blanket claim.
+ *   - A hand-written legacy unit (no marker) is never touched — a one-line
+ *     actionable notice. An UNREADABLE unit file is reported as unreadable,
+ *     never misdiagnosed as hand-written.
+ *   - The whole pass shares ONE cumulative time budget (RECONCILE_DEADLINE_MS)
+ *     on top of the per-call timeout, so even a degraded-but-completing user
+ *     bus cannot stack five slow calls into a half-minute boot stall.
+ * Every side effect goes through the same injectable seams the migration engine
+ * uses, so tests exercise it deterministically and never touch a real service.
+ */
+export async function reconcileRedundantLegacyUnit(
+  input: ReconcileRedundantLegacyUnitInput,
+): Promise<ReconcileRedundantLegacyUnitResult> {
+  const path = legacyUnitPath(input.homeDir);
+  const fileExists = input.legacyUnitFileExists ?? existsSync;
+  if (!fileExists(path)) return { action: 'noop', reason: 'no-legacy-unit', lines: [] };
+
+  const { run, deadlineHit } = makeDeadlineBoundRunner(
+    input.actionRunner,
+    input.systemctlTimeoutMs ?? SYSTEMCTL_TIMEOUT_MS,
+    input.deadlineMs ?? RECONCILE_DEADLINE_MS,
+  );
+  const systemctl = input.systemctlCommand ?? 'systemctl';
+  const canonicalUnit = `${input.trackedServiceName}.service`;
+  const legacyUnit = `${LEGACY_SERVICE_UNIT_NAME}.service`;
+  const deadlineNote = (): string[] =>
+    deadlineHit()
+      ? ['note: the reconcile hit its overall time budget — remaining checks were skipped; it will re-run at the next daemon start.']
+      : [];
+
+  // Guard 1: the canonical unit must report active. (A timed-out, skipped, or
+  // failed probe — e.g. a wedged user bus — lands here too and refuses.)
+  const probe = run(systemctl, ['--user', 'is-active', canonicalUnit]);
+  const canonicalActive = (probe.status ?? 1) === 0 && (probe.stdout ?? '').trim() === 'active';
+  if (!canonicalActive) {
+    return {
+      action: 'noop',
+      reason: 'canonical-not-active',
+      lines: [
+        `legacy-unit reconcile: a ${legacyUnit} unit file exists at ${path} but ${canonicalUnit} is not confirmably active — ` +
+          'left untouched (it may be the only daemon).',
+        ...deadlineNote(),
+      ],
+    };
+  }
+
+  // Guard 2: 'active' alone does not prove the canonical unit is the daemon
+  // actually serving (Type=simple reports active from fork onward). Require
+  // its MainPID to resolve and be a live process.
+  const canonicalPid = parseMainPid(run(systemctl, ['--user', 'show', '-p', 'MainPID', '--value', canonicalUnit]));
+  const alive = input.processAlive ?? defaultProcessAlive;
+  if (canonicalPid === undefined || !alive(canonicalPid)) {
+    return {
+      action: 'noop',
+      reason: 'canonical-mainpid-not-alive',
+      lines: [
+        `legacy-unit reconcile: ${canonicalUnit} reports active but its MainPID could not be confirmed alive — ` +
+          `left the ${legacyUnit} unit untouched.`,
+        ...deadlineNote(),
+      ],
+    };
+  }
+
+  // Guard 3: never disable the unit that launched THIS process. `disable
+  // --now` on our own supervising unit would SIGTERM this daemon's whole
+  // cgroup mid-boot, from inside the blocking systemctl call.
+  //
+  // The legacy MainPID probe is TRI-STATE, exactly like guards 1-2: a reply
+  // whose status is non-zero or null (bus flap, timeout, skipped-by-deadline)
+  // does NOT mean "MainPID=0, unit affirmatively stopped" — reading it that
+  // way let one transient systemctl failure on exactly this call authorize
+  // `disable --now` against a LIVE legacy daemon (and guard 5 cannot catch
+  // it: in the wrong-port state the legacy daemon itself answers the
+  // configured-endpoint probe). Unknown refuses.
+  const ownPid = input.ownPid ?? process.pid;
+  const legacyPidReply = run(systemctl, ['--user', 'show', '-p', 'MainPID', '--value', legacyUnit]);
+  const legacyPidKnown = (legacyPidReply.status ?? 1) === 0;
+  const legacyPid = parseMainPid(legacyPidReply);
+  const ownCgroup = (input.readOwnCgroup ?? defaultReadOwnCgroup)();
+  if (legacyPid === ownPid || ownCgroup.includes(legacyUnit)) {
+    return {
+      action: 'noop',
+      reason: 'self-supervised-by-legacy',
+      lines: [
+        `legacy-unit reconcile: this daemon appears to be running UNDER ${legacyUnit} itself — refusing to disable ` +
+          `the unit supervising the current process. Migrate from the canonical side instead: goodvibes-daemon migrate-service`,
+      ],
+    };
+  }
+  if (!legacyPidKnown) {
+    return {
+      action: 'noop',
+      reason: 'legacy-state-unknown',
+      lines: [
+        `legacy-unit reconcile: could not determine whether ${legacyUnit} has a running daemon (the MainPID query ` +
+          'failed or timed out) — refusing to act on a guess; it will be re-checked at the next daemon start.',
+        ...deadlineNote(),
+      ],
+    };
+  }
+
+  // Guard 4: never stop a RUNNING legacy daemon from the unattended path. A
+  // live legacy MainPID means a second daemon is actually serving something —
+  // possibly the endpoint clients resolve from settings.json (the wrong-port
+  // two-daemon state). Retiring an enabled-but-idle unit needs no --now kill;
+  // stopping a serving one needs consent. (A KNOWN reply of MainPID=0 is the
+  // affirmative "stopped" that permits proceeding.)
+  if (legacyPid !== undefined && alive(legacyPid)) {
+    return {
+      action: 'noop',
+      reason: 'legacy-running',
+      lines: [
+        `legacy-unit reconcile: ${legacyUnit} has a live main process (pid ${legacyPid}) — a second daemon is ` +
+          'actually running, and it may be the one serving the endpoint your clients are configured to reach. ' +
+          'Refusing to stop it unattended; migrate deliberately with: goodvibes-daemon migrate-service',
+      ],
+    };
+  }
+
+  // Guard 5: the endpoint clients resolve from settings.json must be answered
+  // before anything is retired. The canonical daemon being alive proves only
+  // that A daemon runs — not that the configured endpoint is served (its unit
+  // may pin different launch args).
+  if (input.configuredEndpoint) {
+    const endpointProbe = input.endpointProbe ?? defaultPortProbe;
+    const served = await endpointProbe(input.configuredEndpoint.host, input.configuredEndpoint.port);
+    if (!served) {
+      return {
+        action: 'noop',
+        reason: 'configured-endpoint-unserved',
+        lines: [
+          `legacy-unit reconcile: nothing is answering on the CONFIGURED endpoint ` +
+            `${input.configuredEndpoint.host}:${input.configuredEndpoint.port} — the canonical daemon is alive but not ` +
+            `provably serving what clients resolve from settings. Left the ${legacyUnit} unit untouched; check the ` +
+            "canonical unit's launch arguments against the controlPlane settings.",
+        ],
+      };
+    }
+  }
+
+  const readFile = input.legacyUnitFileRead ?? ((p: string) => readFileSync(p, 'utf-8'));
+  let marked = false;
+  let readError: string | undefined;
+  try {
+    marked = readFile(path).includes(INSTALLER_UNIT_MARKER);
+  } catch (error) {
+    readError = summarizeError(error);
+  }
+
+  if (readError !== undefined) {
+    // Fail closed, and say what actually happened: the file could not be READ.
+    // Asserting "hand-written (no installer marker)" here would be a false
+    // provenance claim about a file whose contents were never established.
+    return {
+      action: 'notice',
+      reason: 'marker-unreadable',
+      lines: [
+        `note: ${canonicalUnit} is active and a separate ${legacyUnit} exists at ${path}, but its unit file could not ` +
+          `be read (${readError}) — left untouched. Inspect it yourself; if it is redundant, retire it with: ` +
+          `systemctl --user disable --now ${legacyUnit} && rm ${path} && systemctl --user daemon-reload`,
+      ],
+    };
+  }
+
+  if (!marked) {
+    return {
+      action: 'notice',
+      reason: 'hand-written',
+      lines: [
+        `note: ${canonicalUnit} is active but a separate ${legacyUnit} also exists at ${path}. ` +
+          'It is hand-written (no installer marker) so it was left untouched; retire it yourself to stop two daemons ' +
+          `competing for the same port: systemctl --user disable --now ${legacyUnit} && rm ${path} && ` +
+          'systemctl --user daemon-reload',
+      ],
+    };
+  }
+
+  // Installer-marker-managed and redundant: disable first, and only remove the
+  // unit file if the disable actually succeeded — otherwise the enablement
+  // symlink dangles at a deleted file and this tool can never repair it (the
+  // next pass no-ops at the file-exists check).
+  const disableResult = run(systemctl, ['--user', 'disable', '--now', legacyUnit]);
+  const disableStatus = disableResult.status ?? 1;
+  if (disableStatus !== 0) {
+    if (disableResult.status === null) {
+      // TIMED OUT: the outcome is UNKNOWN, not failed — `disable --now`
+      // removes the enablement symlinks synchronously BEFORE waiting on the
+      // stop job, so the disable may well have taken effect even though the
+      // client was killed. Re-inspect instead of printing a blanket denial.
+      const reinspect = run(systemctl, ['--user', 'is-enabled', legacyUnit]);
+      const reinspectOut = (reinspect.stdout ?? '').trim();
+      const confirmedDisabled = (reinspect.status !== null)
+        && (reinspectOut === 'disabled' || reinspectOut === 'not-found');
+      if (confirmedDisabled) {
+        // The disable took effect; only the client timed out waiting on the
+        // stop job. Proceed as success, saying exactly that.
+        const removeFileAfterTimeout = input.legacyUnitFileRemove ?? ((p: string) => rmSync(p, { force: true }));
+        let removeErrorAfterTimeout: string | undefined;
+        try {
+          removeFileAfterTimeout(path);
+        } catch (error) {
+          removeErrorAfterTimeout = summarizeError(error);
+        }
+        run(systemctl, ['--user', 'daemon-reload']);
+        const lines = [
+          `reconciled: the disable command timed out waiting on the stop job, but re-inspection confirms the ` +
+            `installer-managed ${legacyUnit} is no longer enabled${removeErrorAfterTimeout ? '' : ` — its unit file was removed (${path})`}. ` +
+            'Its stop may still be completing.',
+        ];
+        if (removeErrorAfterTimeout) {
+          lines.push(`note: could not remove ${path}: ${removeErrorAfterTimeout} — remove it by hand.`);
+        }
+        lines.push(...deadlineNote());
+        return { action: 'removed', reason: 'retired', lines };
+      }
+      return {
+        action: 'failed',
+        reason: 'disable-timeout',
+        lines: [
+          `legacy-unit reconcile: the disable of ${legacyUnit} timed out and its outcome is UNKNOWN — the enablement ` +
+            `state could not be re-confirmed. This tool removed nothing; the unit file at ${path} was left in place ` +
+            'and will be re-checked at the next daemon start.',
+          `Verify it yourself: systemctl --user is-enabled ${legacyUnit}`,
+          ...deadlineNote(),
+        ],
+      };
+    }
+    const detail = (disableResult.stderr ?? disableResult.stdout ?? '').trim() || 'no output';
+    return {
+      action: 'failed',
+      reason: 'disable-failed',
+      lines: [
+        `legacy-unit reconcile: the disable of the redundant installer-managed ${legacyUnit} reported failure ` +
+          `(${detail}) — this tool removed nothing; the unit file at ${path} was left in place.`,
+        `Verify its state and retire it yourself: systemctl --user is-enabled ${legacyUnit} ; ` +
+          `systemctl --user disable --now ${legacyUnit} && rm ${path} && systemctl --user daemon-reload`,
+      ],
+    };
+  }
+
+  const removeFile = input.legacyUnitFileRemove ?? ((p: string) => rmSync(p, { force: true }));
+  let removeError: string | undefined;
+  try {
+    removeFile(path);
+  } catch (error) {
+    removeError = summarizeError(error);
+  }
+  run(systemctl, ['--user', 'daemon-reload']);
+
+  const lines = [
+    `reconciled: ${canonicalUnit} is active and serving, so the redundant installer-managed ${legacyUnit} ` +
+      `was disabled${removeError ? '' : ` and removed (${path})`}.`,
+  ];
+  if (removeError) {
+    lines.push(`note: could not remove ${path}: ${removeError} — remove it by hand.`);
+  }
+  lines.push(...deadlineNote());
+  return { action: 'removed', reason: 'retired', lines };
+}

package/src/runtime/mail-composition.ts

@@ -0,0 +1,65 @@
+/**
+ * mail-composition.ts
+ *
+ * The deps that let the platform register this daemon's `email.*` verbs.
+ *
+ * `calendar.*` and `email.*` are served by the platform now, not by handlers in
+ * this repository — those were deleted when the platform gained an
+ * implementation the daemon could call. What is left for a product to supply is
+ * the wiring, and it is not optional: without `homeDirectory` the calendar
+ * composition returns null, without these deps the mail one does, and either way
+ * the verbs stay cataloged-but-unhandled while every surface reports the daemon
+ * unreachable on a daemon that is working perfectly.
+ *
+ * Extracted from services.ts rather than living there, because that file sits at
+ * the 800-line architecture cap and a composition step is exactly the kind of
+ * thing the cap exists to push into a module of its own.
+ */
+
+import {
+  withSurfaceEmailConfig,
+  describeSurfaceEmailConfigProblem,
+  describeSenderClaimNeutrally,
+  type EmailServiceDeps,
+  type SurfaceEmailConfigProblem,
+} from '@pellux/goodvibes-sdk/platform/email';
+import { nodeEmailTransport } from '@pellux/goodvibes-sdk/platform/email/node';
+
+/** The narrow slices this composition needs; the real managers satisfy them. */
+interface MailCompositionInput {
+  readonly configManager: { get(key: never): unknown };
+  readonly secretsManager: { get(key: string): Promise<string | null> };
+}
+
+/**
+ * Build the mail deps and the not-configured describer that go to
+ * `registerGatewayVerbGroups`.
+ *
+ * The settings come from the daemon's own `surfaces.email.*` keys through
+ * `withSurfaceEmailConfig`, so the keys an operator has already set — and that
+ * the settings modal now shows — keep working unchanged, and a not-configured
+ * answer names the keys THIS operator actually has rather than the ones the
+ * service validates internally.
+ */
+export function composeMailDeps(input: MailCompositionInput): {
+  readonly emailServiceDeps: EmailServiceDeps;
+  readonly describeEmailConfigProblem: () => Promise<SurfaceEmailConfigProblem | null>;
+} {
+  const getConfig = (key: string): unknown => input.configManager.get(key as never);
+  const emailServiceDeps = withSurfaceEmailConfig({
+    getConfig,
+    secretsManager: input.secretsManager,
+    transport: nodeEmailTransport,
+    // The daemon has no wording of its own for a sender line, so it takes the
+    // platform's rather than growing a second implementation of a rule that is
+    // security-relevant: a From: header is a claim, sender authentication
+    // raises display confidence only, and commandAuthority is the literal
+    // 'none'.
+    describeSenderClaim: describeSenderClaimNeutrally,
+  } as never);
+  return {
+    emailServiceDeps,
+    describeEmailConfigProblem: () =>
+      describeSurfaceEmailConfigProblem(getConfig, input.secretsManager),
+  };
+}

package/src/runtime/notification-dispatch.ts

@@ -0,0 +1,86 @@
+/**
+ * notification-dispatch.ts — how this daemon dispatches notices without a screen.
+ *
+ * The SDK's NotificationRouter decides where a domain notification goes and
+ * collapses bursts and batches. Its three targets — `conversation`,
+ * `status_bar`, `panel_only` — are all SCREEN targets: an inline conversation
+ * line, a status bar, a panel. There is no channel member in that type, and
+ * there never was. Which means the router is a surface mechanism end to end,
+ * and this process has no screen.
+ *
+ * This module used to wire the router to every curated domain anyway, writing
+ * into a bounded ring whose `list()` had no caller anywhere in this repository.
+ * Six domains of events, for the daemon's whole lifetime, into a buffer nobody
+ * read — and the type declaring it still described the ring as "the panel's
+ * live producer", for a product with no panels. That silent-success failure
+ * class is exactly what this module removes: the producer goes.
+ *
+ * What a headless process CAN do with a notice is send it, and the daemon
+ * already does that on the paths that are genuinely channel-shaped: automation
+ * failure notices through the delivery manager, occasion nudges through the
+ * channel delivery router, and the WebhookNotifier attached to the runtime bus
+ * at boot for agent and workflow outcomes.
+ *
+ * One notice had no such path: memory pressure. The MemoryGovernor measures the
+ * process it runs in, so the daemon's pressure is the daemon's own and no
+ * surface can report it — and the daemon that ran out of memory is exactly the
+ * one that cannot tell you afterwards. It now goes out over the operator's
+ * configured notice destination (`notifications.webhookUrls`, the same list the
+ * bus bridge uses), and says so at its own level in the activity log when no
+ * destination is configured. Sent, or written down; never dropped.
+ */
+
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { RuntimeEventBus } from '@/runtime/index.ts';
+import { memoryPressureLine, memoryPressureLevel, type MemoryPressurePayload } from '@pellux/goodvibes-sdk/platform/runtime/memory';
+
+/**
+ * Where a channel-shaped notice leaves the daemon.
+ *
+ * The WebhookNotifier's own shape, narrowed to the two members this needs, so a
+ * test can drive it without an HTTP client and so the composition can pass the
+ * one instance the notification verbs and the bus bridge already share.
+ */
+export interface DaemonNoticeChannel {
+  isConfigured(): boolean;
+  send(text: string): Promise<unknown>;
+}
+
+/**
+ * Send the daemon's own memory-pressure notice to the operator's configured
+ * notice destination. Returns an unsubscribe function.
+ *
+ * The MemoryGovernor emits OPS_MEMORY_PRESSURE on the 'ops' domain when the
+ * pressure tier changes or the leak tripwire fires. That domain also carries
+ * high-churn audit and metric events, which is why this is a targeted bridge on
+ * one event type rather than a subscription to the domain: the tier change is
+ * the operator's business and the churn is not.
+ *
+ * Delivery failure is logged, never thrown — a webhook endpoint being down is
+ * not a reason for the process reporting memory pressure to also crash.
+ */
+export function wireMemoryPressureChannelNotice(
+  runtimeBus: RuntimeEventBus,
+  channel: DaemonNoticeChannel,
+): () => void {
+  return runtimeBus.onDomain('ops', (envelope) => {
+    if (envelope.type !== 'OPS_MEMORY_PRESSURE') return;
+    const payload = envelope.payload as MemoryPressurePayload;
+    const level = memoryPressureLevel(payload);
+    const line = memoryPressureLine(payload);
+    if (!channel.isConfigured()) {
+      // No destination configured. The notice still exists — at its own
+      // severity, where the operator looks when the daemon misbehaves.
+      if (level === 'critical') logger.error(line);
+      else if (level === 'warning') logger.warn(line);
+      else logger.info(line);
+      return;
+    }
+    void Promise.resolve(channel.send(line)).catch((error: unknown) => {
+      logger.warn('Memory pressure notice could not be delivered', {
+        error: error instanceof Error ? error.message : String(error),
+        notice: line,
+      });
+    });
+  });
+}