@pellux/goodvibes-daemon 1.28.0

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

@@ -0,0 +1,184 @@
+// ---------------------------------------------------------------------------
+// Daemon-internal triage TAGGER (composition).
+//
+// Applies user-defined triage labels back on the provider side:
+//   - IMAP : STORE a keyword flag on the message (IMAP4rev1 over TLS).
+//   - Slack: reactions.add emoji on the source message.
+//   - Discord: real forum thread tags (PATCH applied_tags, merge) when a
+//     forum-tag mapping is configured, else a unicode reaction analog.
+//
+// Hard rules honored here:
+//   - All provider credentials come ONLY from the daemon credential store.
+//     They are never returned in results and never logged.
+//   - The whole tagger is gated behind a config flag (surfaces.triage.autoTag);
+//     when disabled, applyTags() is a no-op that reports skipped:true.
+//   - Provider-side writes are EFFECTFUL; callers must pass an explicitly
+//     confirmed request (confirm === true && explicitUserRequest === true).
+//     Unconfirmed calls throw HandlerError(REQUIRE_CONFIRM).
+//
+// Contract-fidelity note: the triage surface (`inbox.triage.*`) is daemon-
+// internal and NOT a published operator method, so there is no external
+// request/response schema to certify these tag shapes against. What is
+// guaranteed is the provider-side behavior: no silent data loss (Discord thread
+// tags are merged, never blindly overwritten) and no command injection (IMAP
+// quoting rejects control characters).
+// ---------------------------------------------------------------------------
+
+import type { HandlerContext } from '../../context.ts';
+import type { DaemonCredentialStore } from '../../credentials.ts';
+import { HandlerError, REQUIRE_CONFIRM } from '../../errors.ts';
+import { labelToTag } from '../scorer.ts';
+import { applyImap, imapStoreFlagOverTls, makeRetryingImapStoreFlag } from './imap.ts';
+import type { ImapRetryOptions, ImapStoreFlag } from './imap.ts';
+import { applySlack } from './slack.ts';
+import { applyDiscord } from './discord.ts';
+import type { ApplyTagsRequest, ApplyTagsResult, TaggerProviderConfig } from './shared.ts';
+
+export type {
+  ApplyTagsRequest,
+  ApplyTagsResult,
+  TaggerProviderConfig,
+} from './shared.ts';
+export type { ImapRetryOptions, ImapStoreArgs, ImapStoreFlag } from './imap.ts';
+
+export const TRIAGE_AUTOTAG_FLAG = 'surfaces.triage.autoTag';
+
+export interface TriageTaggerOptions {
+  credentials?: DaemonCredentialStore;
+  /** Override the autotag flag lookup (used in tests). */
+  autoTagEnabled?: boolean;
+  /** Per-surface provider config; usually derived from configManager. */
+  providers?: TaggerProviderConfig;
+  /** Injectable fetch (Slack/Discord HTTP). Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Injectable IMAP flag-setter (used in tests to avoid a live socket). */
+  imapStoreFlag?: ImapStoreFlag;
+  /**
+   * Transient-failure retry policy for the default IMAP store implementation.
+   * Ignored when imapStoreFlag is injected and succeeds first-try.
+   */
+  imapRetry?: ImapRetryOptions;
+}
+
+export interface TriageTagger {
+  /** Whether provider-side tagging is currently enabled. */
+  enabled(): boolean;
+  applyTags(request: ApplyTagsRequest): Promise<ApplyTagsResult>;
+}
+
+function readBoolFlag(
+  configManager: HandlerContext['configManager'],
+  key: string,
+): boolean {
+  try {
+    const value = configManager.get(key as never) as unknown;
+    return value === true || value === 'true' || value === 1;
+  } catch {
+    return false;
+  }
+}
+
+function safeGet(configManager: HandlerContext['configManager'], key: string): unknown {
+  try {
+    return configManager.get(key as never) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveProvidersFromConfig(
+  configManager: HandlerContext['configManager'],
+): TaggerProviderConfig {
+  const out: TaggerProviderConfig = {};
+  const slackToken = safeGet(configManager, 'surfaces.slack.botToken');
+  if (typeof slackToken === 'string' && slackToken.length > 0) {
+    out.slack = { tokenConfigKey: 'surfaces.slack.botToken' };
+  }
+  const discordToken = safeGet(configManager, 'surfaces.discord.botToken');
+  if (typeof discordToken === 'string' && discordToken.length > 0) {
+    out.discord = { tokenConfigKey: 'surfaces.discord.botToken' };
+  }
+  const imapHost = safeGet(configManager, 'surfaces.email.imap.host');
+  const imapUser = safeGet(configManager, 'surfaces.email.imap.user');
+  if (typeof imapHost === 'string' && imapHost.length > 0 && typeof imapUser === 'string') {
+    const portRaw = safeGet(configManager, 'surfaces.email.imap.port');
+    const mailbox = safeGet(configManager, 'surfaces.email.imap.mailbox');
+    out.imap = {
+      host: imapHost,
+      port: typeof portRaw === 'number' ? portRaw : 993,
+      user: imapUser,
+      passwordConfigKey: 'surfaces.email.imap.password',
+      mailbox: typeof mailbox === 'string' && mailbox.length > 0 ? mailbox : 'INBOX',
+    };
+  }
+  return out;
+}
+
+function resolveTags(request: ApplyTagsRequest): string[] {
+  if (request.tags && request.tags.length > 0) {
+    return [...new Set(request.tags.map((t) => t.trim()).filter((t) => t.length > 0))];
+  }
+  if (request.label) return [labelToTag(request.label)];
+  return [];
+}
+
+/**
+ * Create the triage tagger. Reads the autotag flag and provider config from the
+ * handler context; credentials are resolved lazily, per apply, from the daemon
+ * credential store.
+ */
+export function createTriageTagger(
+  ctx: HandlerContext,
+  options: TriageTaggerOptions = {},
+): TriageTagger {
+  const credentials = options.credentials ?? ctx.credentials;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const providers = options.providers ?? resolveProvidersFromConfig(ctx.configManager);
+  // Retry wraps whichever store impl is in use (default TLS client OR an
+  // injected one), so transient failures are retried uniformly.
+  const imapStoreFlag = makeRetryingImapStoreFlag(
+    options.imapStoreFlag ?? imapStoreFlagOverTls,
+    options.imapRetry,
+  );
+  const enabled = (): boolean =>
+    options.autoTagEnabled ?? readBoolFlag(ctx.configManager, TRIAGE_AUTOTAG_FLAG);
+
+  return {
+    enabled,
+    async applyTags(request: ApplyTagsRequest): Promise<ApplyTagsResult> {
+      const { item } = request;
+      const tags = resolveTags(request);
+      const base: ApplyTagsResult = {
+        surface: item.surface,
+        itemId: item.id,
+        appliedTags: [],
+        skipped: true,
+      };
+
+      if (!enabled()) {
+        return { ...base, reason: 'autotag-disabled' };
+      }
+
+      // 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.',
+          REQUIRE_CONFIRM,
+          403,
+        );
+      }
+
+      switch (item.surface) {
+        case 'email':
+        case 'imap':
+          return applyImap(item, tags, providers, credentials, imapStoreFlag, base);
+        case 'slack':
+          return applySlack(item, tags, providers, credentials, fetchImpl, ctx, base);
+        case 'discord':
+          return applyDiscord(item, tags, providers, credentials, fetchImpl, ctx, base);
+        default:
+          return { ...base, reason: `unsupported-surface:${item.surface}` };
+      }
+    },
+  };
+}

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

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+import type { InboundChannelItem, TriageLabel } from '../types.ts';
+
+export interface TaggerProviderConfig {
+  /** IMAP host:port (default port 993, TLS). Credentials resolved separately. */
+  imap?: { host: string; port?: number; user: string; passwordConfigKey: string; mailbox?: string };
+  /** Slack bot token config key (resolved from credential store). */
+  slack?: { tokenConfigKey: string };
+  /**
+   * Discord bot token config key (resolved from credential store), plus an
+   * 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".
+   * Without a mapping (or for non-thread messages) tagging degrades to a
+   * unicode reaction analog.
+   */
+  discord?: { tokenConfigKey: string; forumTagIds?: Record<string, string> };
+}
+
+export interface ApplyTagsRequest {
+  item: InboundChannelItem;
+  /** 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. */
+  confirm?: boolean;
+  /** Mirror of the operator invocation context flag. */
+  explicitUserRequest?: boolean;
+}
+
+export interface ApplyTagsResult {
+  surface: string;
+  itemId: string;
+  appliedTags: string[];
+  /** True when the autotag flag is disabled or no provider matched. */
+  skipped: boolean;
+  reason?: string;
+}
+
+/** IMAP keywords cannot contain spaces or '/'; normalize the canonical tag. */
+export function imapKeywordForTag(tag: string): string {
+  return tag.replace(/[^A-Za-z0-9_]+/g, '_');
+}
+
+export function slackEmojiForTag(tag: string): string {
+  const lower = tag.toLowerCase();
+  if (lower.includes('spam')) return 'no_entry_sign';
+  if (lower.includes('priority')) return 'rotating_light';
+  return 'inbox_tray';
+}
+
+export function discordEmojiForTag(tag: string): string {
+  const lower = tag.toLowerCase();
+  if (lower.includes('spam')) return '\u{1F6AB}';
+  if (lower.includes('priority')) return '\u{1F6A8}';
+  return '\u{1F4E5}';
+}
+
+/** Read a non-empty string from the item's opaque metadata bag. */
+export function stringMeta(item: InboundChannelItem, key: string): string | undefined {
+  const value = item.metadata?.[key];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

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

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// 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
+// logged or returned. `already_reacted` is treated as idempotent success.
+// ---------------------------------------------------------------------------
+
+import type { HandlerContext } from '../../context.ts';
+import type { DaemonCredentialStore } from '../../credentials.ts';
+import { HandlerError } from '../../errors.ts';
+import type { InboundChannelItem } from '../types.ts';
+import type { ApplyTagsResult, TaggerProviderConfig } from './shared.ts';
+import { slackEmojiForTag, stringMeta } from './shared.ts';
+
+export async function applySlack(
+  item: InboundChannelItem,
+  tags: string[],
+  providers: TaggerProviderConfig,
+  credentials: DaemonCredentialStore,
+  fetchImpl: typeof fetch,
+  ctx: HandlerContext,
+  base: ApplyTagsResult,
+): Promise<ApplyTagsResult> {
+  const cfg = providers.slack;
+  if (!cfg) return { ...base, reason: 'slack-not-configured' };
+  const channel = stringMeta(item, 'channelId') ?? item.conversationId;
+  const ts = stringMeta(item, 'ts') ?? stringMeta(item, 'messageTs');
+  if (!channel || !ts) return { ...base, reason: 'slack-missing-target' };
+  if (tags.length === 0) return { ...base, reason: 'no-tags' };
+
+  const token = await credentials.resolveConfigSecret(cfg.tokenConfigKey);
+  if (!token) return { ...base, reason: 'slack-no-credentials' };
+
+  const applied: string[] = [];
+  for (const tag of tags) {
+    const emoji = slackEmojiForTag(tag);
+    const response = await fetchImpl('https://slack.com/api/reactions.add', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json; charset=utf-8',
+      },
+      body: JSON.stringify({ channel, timestamp: ts, name: emoji }),
+    });
+    const payload = (await response.json().catch(() => ({}))) as {
+      ok?: boolean;
+      error?: string;
+    };
+    if (!response.ok) {
+      throw new HandlerError(
+        `Slack reactions.add HTTP ${response.status}`,
+        'TRIAGE_SLACK_TAG_FAILED',
+        502,
+      );
+    }
+    // 'already_reacted' is an idempotent success for our purposes.
+    if (payload.ok !== true && payload.error !== 'already_reacted') {
+      ctx.logger.warn('triage: slack reaction rejected', { error: payload.error });
+      throw new HandlerError(
+        `Slack reactions.add rejected: ${payload.error ?? 'unknown'}`,
+        'TRIAGE_SLACK_TAG_FAILED',
+        502,
+      );
+    }
+    applied.push(tag);
+  }
+  return { surface: item.surface, itemId: item.id, appliedTags: applied, skipped: false };
+}

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

@@ -0,0 +1,50 @@
+// ---------------------------------------------------------------------------
+// Daemon-internal triage domain types.
+//
+// `InboundChannelItem` is the daemon-internal shape the inbox poller produces
+// 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),
+// `subjectPreview`/`bodyPreview` (PII-stripped, length-bounded) and an opaque
+// `metadata` bag the tagger reads provider targeting from (imapUid, channelId,
+// Slack ts, Discord messageId/threadId).
+// ---------------------------------------------------------------------------
+
+/** Triage label assigned by the scorer. */
+export type TriageLabel = 'spam' | 'priority' | 'normal';
+
+/** 1:1 vs group/channel/thread conversation hint (priority signal). */
+export type ConversationKind = 'direct' | 'group' | 'channel' | 'thread' | 'service';
+
+/**
+ * Internal inbound feed item. Mirrors the handoff `InboundChannelItem` shape
+ * plus the optional fields the scorer/tagger consult. `surface` is the provider
+ * family ('email' | 'imap' | 'slack' | 'discord' | ...) the tagger dispatches
+ * on; `provider` is the handoff-facing provider id. They are usually equal.
+ */
+export interface InboundChannelItem {
+  /** Stable, provider-scoped dedup key. */
+  readonly id: string;
+  /** Provider family the tagger dispatches on (email/imap/slack/discord/...). */
+  readonly surface: string;
+  /** 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. */
+  readonly fromDigest?: string;
+  /** Conversation id (Slack/Discord channel, IMAP mailbox-scoped). */
+  readonly conversationId?: string;
+  readonly conversationKind?: ConversationKind;
+  /** Display subject (<= 200 chars). */
+  readonly subject?: string;
+  /** Display body preview (<= 500 chars, PII-stripped). Alias: bodyPreview. */
+  readonly snippet?: string;
+  /** Optional daemon route binding id. */
+  readonly routeId?: string;
+  /** Unix ms. */
+  readonly receivedAt?: number;
+  readonly unread?: boolean;
+  /** Opaque provider targeting bag (imapUid/uid, channelId, ts, messageId, threadId). */
+  readonly metadata?: Record<string, unknown>;
+}

package/src/daemon/lifecycle.ts

@@ -0,0 +1,41 @@
+/**
+ * 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
+ * DaemonUpdateArtifact ({version, execPath}): it compares the HOST binary's
+ * 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 —
+ * 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
+ * install, so a dev run resolves to `undefined` (host-managed, no loop) and
+ * only a real self-contained binary self-updates.
+ */
+import type { DaemonUpdateArtifact } from '@pellux/goodvibes-sdk/platform/daemon';
+import { VERSION } from '../version.ts';
+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. */
+  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
+ * the facade keeps updates host-managed and runs no swap loop.
+ */
+export function resolveDaemonUpdateArtifact(
+  options: ResolveDaemonUpdateArtifactOptions = {},
+): DaemonUpdateArtifact | undefined {
+  const execPath = options.execPath ?? process.execPath;
+  if (detectInstallKind(execPath) !== 'binary') return undefined;
+  return { version: options.version ?? VERSION, execPath };
+}

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

@@ -0,0 +1,233 @@
+/**
+ * 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,
+ * which version an automatic rollback rejected, and what the daemon has
+ * written receipts about. All of that lives on the daemon's own host, in two
+ * JSON files beside its control-plane state:
+ *
+ *   <control-plane config dir>/control-plane/daemon-lifecycle.json
+ *   <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
+ * consuming reader exactly once, and a status command that quietly consumed
+ * them would take them away from the surface they were written for.
+ *
+ * Which is also why this is honestly local-only: a `status --host other-box`
+ * has no access to that box's filesystem, and these lines are reported as
+ * unavailable rather than guessed at. See `describeLocalDaemonState`.
+ *
+ * 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
+ * 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.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Mirrors the SDK's own clamp: a hand-edited counter is bounded, not trusted. */
+const MAX_TRACKED_FAILED_STARTS = 32;
+/** Mirrors the SDK's own clamp on a persisted version string. */
+const MAX_TRACKED_VERSION_LENGTH = 64;
+/** Enough receipts to explain a restart; a status page is not a log viewer. */
+const MAX_REPORTED_RECEIPTS = 10;
+
+export interface DaemonLifecycleMarker {
+  readonly state: 'running' | 'clean-shutdown';
+  readonly at: number;
+  readonly pid: number | undefined;
+  readonly failedStarts: number;
+  readonly version: string | undefined;
+  /** 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;
+}
+
+export interface DaemonReceipt {
+  readonly id: string;
+  readonly text: string;
+  readonly at: number;
+  readonly deliveredAt: number | undefined;
+}
+
+export interface LocalDaemonStatePaths {
+  readonly markerPath: string;
+  readonly receiptsPath: string;
+}
+
+/** The two paths, derived the same way the daemon facade derives them. */
+export function localDaemonStatePaths(controlPlaneConfigDir: string): LocalDaemonStatePaths {
+  return {
+    markerPath: join(controlPlaneConfigDir, 'control-plane', 'daemon-lifecycle.json'),
+    receiptsPath: join(controlPlaneConfigDir, 'control-plane', 'daemon-receipts.json'),
+  };
+}
+
+export interface LocalStateIo {
+  read(path: string): string | null;
+}
+
+export const realLocalStateIo: LocalStateIo = {
+  read(path: string): string | null {
+    try {
+      return existsSync(path) ? readFileSync(path, 'utf-8') : null;
+    } catch {
+      return null;
+    }
+  },
+};
+
+function boundedString(value: unknown, max: number): string | undefined {
+  return typeof value === 'string' && value.length > 0 && value.length <= max ? value : undefined;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+/** The marker as it stands, or null when there is none or it does not validate. */
+export function readDaemonLifecycleMarker(
+  markerPath: string,
+  io: LocalStateIo = realLocalStateIo,
+): DaemonLifecycleMarker | null {
+  const raw = io.read(markerPath);
+  if (raw === null) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const record = parsed as Record<string, unknown>;
+  const state = record['state'];
+  if (state !== 'running' && state !== 'clean-shutdown') return null;
+  const at = finiteNumber(record['at']);
+  if (at === undefined) return null;
+  const failedStarts = finiteNumber(record['failedStarts']) ?? 0;
+  return {
+    state,
+    at,
+    pid: finiteNumber(record['pid']),
+    failedStarts: Math.max(0, Math.min(MAX_TRACKED_FAILED_STARTS, Math.trunc(failedStarts))),
+    version: boundedString(record['version'], MAX_TRACKED_VERSION_LENGTH),
+    rejectedVersion: boundedString(record['rejectedVersion'], MAX_TRACKED_VERSION_LENGTH),
+    autoRollbackAt: finiteNumber(record['autoRollbackAt']),
+  };
+}
+
+/**
+ * The receipts the daemon has written, newest last, capped.
+ *
+ * Read-only: nothing here marks a receipt delivered. The store's own
+ * consume path is what a surface uses when it means to claim them.
+ */
+export function readDaemonReceipts(
+  receiptsPath: string,
+  io: LocalStateIo = realLocalStateIo,
+): readonly DaemonReceipt[] {
+  const raw = io.read(receiptsPath);
+  if (raw === null) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  // The store persists either a bare array or `{ receipts: [...] }` depending
+  // on its version; both are read rather than one being assumed.
+  const list = Array.isArray(parsed)
+    ? parsed
+    : parsed && typeof parsed === 'object' && Array.isArray((parsed as { receipts?: unknown }).receipts)
+      ? (parsed as { receipts: unknown[] }).receipts
+      : [];
+  const receipts: DaemonReceipt[] = [];
+  for (const entry of list) {
+    if (!entry || typeof entry !== 'object') continue;
+    const record = entry as Record<string, unknown>;
+    const text = typeof record['text'] === 'string' ? record['text'] : undefined;
+    const at = finiteNumber(record['at']);
+    if (text === undefined || at === undefined) continue;
+    receipts.push({
+      id: typeof record['id'] === 'string' ? record['id'] : `${at}`,
+      text,
+      at,
+      deliveredAt: finiteNumber(record['deliveredAt']),
+    });
+  }
+  return receipts.slice(-MAX_REPORTED_RECEIPTS);
+}
+
+export interface LocalDaemonState {
+  /** 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;
+  readonly marker: DaemonLifecycleMarker | null;
+  readonly receipts: readonly DaemonReceipt[];
+  /** Milliseconds since the marker said the daemon started, when it says it is running. */
+  readonly uptimeMs: number | undefined;
+  /** True when an automatic rollback is in force and no clean start has cleared it. */
+  readonly rolledBack: boolean;
+}
+
+export interface DescribeLocalDaemonStateInput {
+  /** False for a remote target: nothing is read and the lines say why. */
+  readonly isLocal: boolean;
+  readonly controlPlaneConfigDir: string;
+  readonly now?: (() => number) | undefined;
+  readonly io?: LocalStateIo | undefined;
+}
+
+/**
+ * What this machine's own files say about the daemon.
+ *
+ * Never throws and never asserts: an absent marker is an absent marker, which
+ * is the ordinary state on a host where the daemon has not started yet.
+ */
+export function describeLocalDaemonState(input: DescribeLocalDaemonStateInput): LocalDaemonState {
+  if (!input.isLocal) {
+    return {
+      available: false,
+      unavailableReason:
+        '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: [],
+      uptimeMs: undefined,
+      rolledBack: false,
+    };
+  }
+  const io = input.io ?? realLocalStateIo;
+  const paths = localDaemonStatePaths(input.controlPlaneConfigDir);
+  const marker = readDaemonLifecycleMarker(paths.markerPath, io);
+  const receipts = readDaemonReceipts(paths.receiptsPath, io);
+  const now = input.now?.() ?? Date.now();
+  const uptimeMs = marker && marker.state === 'running' && marker.at <= now ? now - marker.at : undefined;
+  return {
+    available: true,
+    unavailableReason: undefined,
+    marker,
+    receipts,
+    uptimeMs,
+    rolledBack: marker?.autoRollbackAt !== undefined,
+  };
+}
+
+/** `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);
+  const hours = Math.floor((totalSeconds % 86_400) / 3_600);
+  const minutes = Math.floor((totalSeconds % 3_600) / 60);
+  const seconds = totalSeconds % 60;
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}