@scrylog/cli 0.1.4 → 0.3.0

package/src/daemon/store.ts

@@ -4,6 +4,22 @@ import { NOOP_LOGGER } from "../shared/logger";
 import type { CollectorStatus, DaemonState, SessionInfo, SessionModel, StoreEvent } from "../shared/types";
 import type { RetentionConfig } from "../shared/config";
 
+/**
+ * Returns true when an incoming claude-hook "working" event represents an explicit
+ * user response to a pending attention (permission or question), so the attention
+ * can be cleared. Background working events (unrelated subagent activity) return false.
+ */
+function resolvesAttention(existing: SessionModel, incoming: SessionModel): boolean {
+  const evt = incoming.claude?.hookEventType;
+  if (evt === "UserPromptSubmit" || evt === "PermissionDenied") return true;
+  if (
+    (evt === "PreToolUse" || evt === "PostToolUse")
+    && existing.claude?.attentionKind === "permission"
+    && incoming.claude?.toolName === existing.claude.toolName
+  ) return true;
+  return false;
+}
+
 /**
  * In-memory state store for the daemon.
  * Maintains all session data and emits typed StoreEvent events on changes.
@@ -108,6 +124,24 @@ export class DaemonStore extends EventEmitter {
     // enrichment fields. This prevents the opencode SDK/DB/cluade collectors from
     // wiping out tmux enrichment on every poll/SSE cycle.
     let session = incoming;
+    if (
+      existing?.source === "herdr"
+      && existing.herdr
+      && incoming.detectionSource !== "herdr"
+      && incoming.source !== "tmux"
+      && !incoming.tmux
+      && !incoming.legacyPaneId
+    ) {
+      session = {
+        ...incoming,
+        source: "herdr",
+        herdr: existing.herdr,
+        project: incoming.project ?? existing.project,
+        currentPath: incoming.currentPath ?? existing.currentPath,
+        currentCommand: incoming.currentCommand ?? existing.currentCommand,
+        paneTitle: incoming.paneTitle ?? existing.paneTitle,
+      };
+    }
     if (existing?.legacyPaneId && !incoming.legacyPaneId) {
       const stableForMs = existing.state !== incoming.state ? 0 : existing.stableForMs;
       session = {
@@ -143,6 +177,18 @@ export class DaemonStore extends EventEmitter {
       });
     }
 
+    // For all sessions: preserve a previously-resolved project/currentPath when
+    // the incoming model lacks them. Project resolution can transiently fail
+    // (Claude slug decode returning null, OpenCode directory not yet populated),
+    // and once resolved the association must not oscillate back to undefined.
+    // An incoming model that carries a non-empty project still wins.
+    if (existing && !session.project && existing.project) {
+      session = { ...session, project: existing.project };
+    }
+    if (existing && !session.currentPath && existing.currentPath) {
+      session = { ...session, currentPath: existing.currentPath };
+    }
+
     // Preserve stateChangedAt from the stored session when the incoming model
     // doesn't carry it (e.g. built by processTranscript from file state only).
     if (existing && !session.stateChangedAt && existing.stateChangedAt) {
@@ -163,25 +209,50 @@ export class DaemonStore extends EventEmitter {
         session = { ...session, state: existing.state, stateChangedAt: existing.stateChangedAt };
       } else {
         this.suppressedIdle.delete(session.id);
-        const isGracePeriodIdleToWorking = existing.state === "idle"
+
+        // For hook-managed Claude sessions: pending attention (waiting-input +
+        // hasAttention) takes precedence over concurrent background working events
+        // until the user explicitly responds. Background subagent activity must not
+        // clear the permission/question from the dashboard.
+        const pendingAttention = existing.state === "waiting-input"
+          && existing.hasAttention === true
           && session.state === "working"
-          && existing.lastChildActiveAt
-          && (now - existing.lastChildActiveAt) < 1500;
+          && session.detectionSource === "claude-hook"
+          && !resolvesAttention(existing, session);
 
-        if (session.state === "working") {
+        if (pendingAttention) {
+          // Revert to waiting-input, advancing only the claude metadata (hookSeq etc.)
+          // so subsequent events are not rejected as stale.
           session = {
             ...session,
-            stableForMs: 0,
-            stateChangedAt: now,
-            lastWorkingChangedAt: isGracePeriodIdleToWorking
-              ? (existing.lastWorkingChangedAt ?? now)
-              : now,
+            state: "waiting-input" as SessionModel["state"],
+            hasAttention: true,
+            summary: existing.summary,
+            activeTool: existing.activeTool,
+            stateChangedAt: existing.stateChangedAt,
+            stableForMs: existing.stableForMs,
           };
         } else {
-          session = { ...session, stableForMs: 0, stateChangedAt: now };
+          const isGracePeriodIdleToWorking = existing.state === "idle"
+            && session.state === "working"
+            && existing.lastChildActiveAt
+            && (now - existing.lastChildActiveAt) < 1500;
+
+          if (session.state === "working") {
+            session = {
+              ...session,
+              stableForMs: 0,
+              stateChangedAt: now,
+              lastWorkingChangedAt: isGracePeriodIdleToWorking
+                ? (existing.lastWorkingChangedAt ?? now)
+                : now,
+            };
+          } else {
+            session = { ...session, stableForMs: 0, stateChangedAt: now };
 
-          if (session.state === "waiting-input" || session.state === "error") {
-            session = { ...session, lastWorkingChangedAt: undefined, lastChildActiveAt: undefined };
+            if (session.state === "waiting-input" || session.state === "error") {
+              session = { ...session, lastWorkingChangedAt: undefined, lastChildActiveAt: undefined };
+            }
           }
         }
       }
@@ -366,6 +437,29 @@ export class DaemonStore extends EventEmitter {
     };
   }
 
+  /** Remove herdr location while retaining native collector session data. */
+  clearHerdrBinding(sessionId: string): void {
+    const existing = this.state.sessions.find((session) => session.id === sessionId);
+    if (!existing || existing.source !== "herdr" || !existing.herdr || existing.detectionSource === "herdr") {
+      return;
+    }
+
+    const session: SessionModel = {
+      ...existing,
+      source: "standalone",
+      herdr: undefined,
+      currentCommand: undefined,
+      paneTitle: undefined,
+    };
+    this.state = {
+      ...this.state,
+      sessions: this.state.sessions.map((item) => item.id === sessionId ? session : item),
+      refreshedAt: Date.now(),
+    };
+    this.emit("store:event", { type: "session:updated", session } satisfies StoreEvent);
+    this.emit("store:event", { type: "state:refreshed", timestamp: this.state.refreshedAt } satisfies StoreEvent);
+  }
+
   /** Update usage state and emit event */
   setUsage(usage: import("../usage/types").UsageState): void {
     this.state = { ...this.state, usage };
@@ -465,9 +559,10 @@ export class DaemonStore extends EventEmitter {
     const maxSessions = retention.maxSessions;
     if (maxSessions > 0) {
       const survivors = this.state.sessions.filter((session) => !removeIds.has(session.id));
-      const overflow = survivors.length - maxSessions;
+      const counted = survivors.filter((session) => session.source === "standalone" && session.tool !== "unknown");
+      const overflow = counted.length - maxSessions;
       if (overflow > 0) {
-        const candidates = survivors
+        const candidates = counted
           .filter((session) => !active(session))
           .sort((a, b) => a.lastActivity - b.lastActivity);
         for (const session of candidates.slice(0, overflow)) {

package/src/postinstall.cjs

@@ -0,0 +1,11 @@
+const message = [
+  "scrylog installed or updated.",
+  "If scrylogd is already running, activate this version with:",
+  "  scrylog daemon restart",
+  "For a foreground or unsupported service, stop it and run:",
+  "  scrylogd",
+  "Hooks use the installed binaries and do not need reinstallation.",
+  "If integrations misbehave, run: scrylog setup",
+].join("\n");
+
+process.stdout.write(`${message}\n`);

package/src/shared/config.ts

@@ -91,8 +91,20 @@ export interface TuiConfig {
   standaloneMaxAgeHours: number;
   /** Debounce window in ms for coalescing push-event bursts into a single refresh (default: 120, 0 = disabled) */
   pushDebounceMs: number;
+  /**
+   * Provider icon rendering mode (default: blocks):
+   * - "blocks": terminal pixel art, works everywhere including tmux
+   * - "graphics": full artwork negotiated automatically (kitty → sixel → blocks)
+   * - "kitty" / "sixel": force a specific native graphics protocol, ignoring detection
+   * - "text": colored provider initials
+   */
+  providerIcons: "blocks" | "graphics" | "kitty" | "sixel" | "text";
 }
 
+type ProviderIconsMode = TuiConfig["providerIcons"];
+
+const PROVIDER_ICON_MODES: readonly ProviderIconsMode[] = ["blocks", "graphics", "kitty", "sixel", "text"];
+
 export interface McpConfig {
   /** Whether the local stdio MCP binary should be allowed (default: true) */
   stdioEnabled: boolean;
@@ -142,6 +154,14 @@ export interface UsageOpenCodeGoConfig {
   serverFnId: string;
 }
 
+export interface UsageAuthConfig {
+  /**
+   * Whether background usage polls may read foreign Keychain secrets (macOS).
+   * `false` keeps the daemon prompt-free but disables Keychain-backed credential sources.
+   */
+  allowKeychainPrompts: boolean;
+}
+
 export interface UsageConfig {
   /** Whether usage collection is enabled (default: true) */
   enabled: boolean;
@@ -152,6 +172,7 @@ export interface UsageConfig {
   claude: UsageClaudeConfig;
   codex: UsageCodexConfig;
   opencodeGo: UsageOpenCodeGoConfig;
+  auth: UsageAuthConfig;
 }
 
 export interface RetentionConfig {
@@ -233,6 +254,7 @@ export const CONFIG_DEFAULTS: ScrylogConfig = {
     usePushUpdates: true,
     standaloneMaxAgeHours: 6,
     pushDebounceMs: 120,
+    providerIcons: "blocks",
   },
   mcp: {
     stdioEnabled: true,
@@ -254,6 +276,9 @@ export const CONFIG_DEFAULTS: ScrylogConfig = {
     opencodeGo: {
       serverFnId: "def39973159c7f0483d8793a822b8dbb10d067e12c65455fcb4608459ba0234f",
     },
+    auth: {
+      allowKeychainPrompts: true,
+    },
   },
   retention: {
     maxSessions: 500,
@@ -456,10 +481,18 @@ function normalizeOperationalConfig(config: ScrylogConfig): ScrylogConfig {
       refreshMs: clampNumber(config.tui.refreshMs, 500, 300_000, CONFIG_DEFAULTS.tui.refreshMs),
       standaloneMaxAgeHours: clampNumber(config.tui.standaloneMaxAgeHours, 0, 8_760, CONFIG_DEFAULTS.tui.standaloneMaxAgeHours),
       pushDebounceMs: clampNumber(config.tui.pushDebounceMs, 0, 2_000, CONFIG_DEFAULTS.tui.pushDebounceMs),
+      providerIcons: PROVIDER_ICON_MODES.includes(config.tui.providerIcons)
+        ? config.tui.providerIcons
+        : CONFIG_DEFAULTS.tui.providerIcons,
     },
     usage: {
       ...config.usage,
       pollIntervalMs: clampNumber(config.usage.pollIntervalMs, 60_000, 3_600_000, CONFIG_DEFAULTS.usage.pollIntervalMs),
+      auth: {
+        allowKeychainPrompts: typeof config.usage.auth?.allowKeychainPrompts === "boolean"
+          ? config.usage.auth.allowKeychainPrompts
+          : CONFIG_DEFAULTS.usage.auth.allowKeychainPrompts,
+      },
     },
     retention: {
       ...config.retention,

package/src/shared/session-exclusions.ts

@@ -0,0 +1,5 @@
+const CLAUDE_PROBE_PATH = /(?:^|[\\/-])codexbar[\\/-]claudeprobe(?:$|[\\/-])/i;
+
+export function isKnownClaudeProbePath(path?: string): boolean {
+  return typeof path === "string" && CLAUDE_PROBE_PATH.test(path);
+}

package/src/shared/session-view.ts

@@ -15,6 +15,18 @@ export interface SessionListTmuxInfo {
   session: string;
   window: string;
   pane: string;
+  windowName?: string;
+}
+
+export interface SessionListHerdrInfo {
+  paneId: string;
+  terminalId?: string;
+  workspaceId?: string;
+  workspace?: string;
+  tabId?: string;
+  tab?: string;
+  name?: string;
+  agent?: string;
 }
 
 export interface SessionListItem {
@@ -28,8 +40,11 @@ export interface SessionListItem {
   hasAttention?: boolean;
   detectionSource?: SessionModel["detectionSource"];
   parentSessionId?: string;
+  /** Human label for the session row: pane title > window/tab name > tmux session name */
+  displayName?: string;
   project?: SessionListProjectInfo;
   tmux?: SessionListTmuxInfo;
+  herdr?: SessionListHerdrInfo;
   currentPath?: string;
   activeTool?: string;
   childCount?: number;
@@ -54,6 +69,10 @@ export interface SessionView {
   sessions: SessionTreeItem[];
 }
 
+export interface SessionViewOptions {
+  includeUnknown?: boolean;
+}
+
 function makeStateCounts(): Record<SessionState, number> {
   return {
     working: 0,
@@ -90,7 +109,16 @@ function isEphemeralCodexRootSession(session: SessionModel, now: number): boolea
     && now - session.lastActivity > CODEX_ROOT_EPHEMERAL_GRACE_MS;
 }
 
-function isCanonicallyVisible(session: SessionModel, config: ScrylogConfig, now: number): boolean {
+function isCanonicallyVisible(
+  session: SessionModel,
+  config: ScrylogConfig,
+  now: number,
+  options: SessionViewOptions,
+): boolean {
+  if (session.tool === "unknown" && !options.includeUnknown) {
+    return false;
+  }
+
   if (session.parentSessionId) {
     return session.state === "working" || session.state === "waiting-input";
   }
@@ -125,6 +153,23 @@ function toProject(project?: ProjectInfo): SessionListProjectInfo | undefined {
 
 const GRACE_PERIOD_MS = 1500;
 
+function resolveDisplayName(session: SessionModel): string | undefined {
+  if (session.tmux) {
+    return session.paneTitle?.trim()
+      || session.tmux.windowName?.trim()
+      || session.tmux.session?.trim()
+      || undefined;
+  }
+  if (session.herdr) {
+    return session.herdr.name?.trim()
+      || session.herdr.tab?.trim()
+      || session.herdr.agent?.trim()
+      || session.herdr.paneId
+      || undefined;
+  }
+  return undefined;
+}
+
 function effectiveState(session: SessionModel, activeChildCount: number, now: number): SessionState {
   if (session.state === "idle" && !session.parentSessionId) {
     if (activeChildCount > 0) {
@@ -160,8 +205,19 @@ function toListItem(session: SessionModel, childCount: number, activeChildCount:
     hasAttention: session.hasAttention,
     detectionSource: session.detectionSource,
     parentSessionId: session.parentSessionId,
+    displayName: resolveDisplayName(session),
     project: toProject(session.project),
-    tmux: session.tmux,
+    tmux: session.tmux ? { ...session.tmux } : undefined,
+    herdr: session.herdr ? {
+      paneId: session.herdr.paneId,
+      terminalId: session.herdr.terminalId,
+      workspaceId: session.herdr.workspaceId,
+      workspace: session.herdr.workspace,
+      tabId: session.herdr.tabId,
+      tab: session.herdr.tab,
+      name: session.herdr.name,
+      agent: session.herdr.agent,
+    } : undefined,
     currentPath: session.currentPath,
     activeTool: session.activeTool,
     childCount,
@@ -179,7 +235,12 @@ export function flattenSessionTree(sessions: SessionTreeItem[]): SessionListItem
   return flat;
 }
 
-export function buildSessionView(sessions: SessionModel[], config: ScrylogConfig, now = Date.now()): SessionView {
+export function buildSessionView(
+  sessions: SessionModel[],
+  config: ScrylogConfig,
+  now = Date.now(),
+  options: SessionViewOptions = {},
+): SessionView {
   const byId = new Map(sessions.map((session) => [session.id, session]));
   const allChildren = new Map<string, SessionModel[]>();
   const visibleChildren = new Map<string, SessionModel[]>();
@@ -191,20 +252,20 @@ export function buildSessionView(sessions: SessionModel[], config: ScrylogConfig
       arr.push(session);
       allChildren.set(session.parentSessionId, arr);
 
-      if (isCanonicallyVisible(session, config, now)) {
+      if (isCanonicallyVisible(session, config, now, options)) {
         const visibleArr = visibleChildren.get(session.parentSessionId) ?? [];
         visibleArr.push(session);
         visibleChildren.set(session.parentSessionId, visibleArr);
 
         const parent = byId.get(session.parentSessionId);
-        if (parent) {
+        if (parent && isCanonicallyVisible(parent, config, now, options)) {
           visibleRoots.set(parent.id, parent);
         }
       }
       continue;
     }
 
-    if (isCanonicallyVisible(session, config, now)) {
+    if (isCanonicallyVisible(session, config, now, options)) {
       visibleRoots.set(session.id, session);
     }
   }

package/src/shared/terminal-capabilities.ts

@@ -0,0 +1,130 @@
+import { stdin as input, stdout as output } from "node:process";
+
+/**
+ * Non-invasive terminal capability probes used by `scrylog doctor` to explain
+ * how provider icons negotiate graphics. Mirrors the response formats OpenTUI's
+ * detector expects, but never enters the alternate screen and always restores
+ * the terminal to its original state (`finally`).
+ */
+
+export interface TerminalGraphicsCapabilities {
+  /** Terminal identification from XTVERSION (e.g. "ghostty(1.2.3)"), if answered. */
+  terminalName: string | null;
+  /** Outer multiplexer detected from the environment ("tmux" | "zellij" | "none"). */
+  multiplexer: "tmux" | "zellij" | "none";
+  /** Terminal answered a kitty graphics protocol query. */
+  kittyGraphics: boolean;
+  /** DA1 primary response advertises sixel (attribute 4). */
+  sixel: boolean;
+  /** Window pixel resolution from `CSI 14t`. */
+  pixelResolution: { width: number; height: number } | null;
+  /** stdin was not a TTY (SSH without tty, pipes) or raw mode was unavailable. */
+  probeFailed: boolean;
+  /** Why the probe did not run or answer. */
+  probeFailedReason: "not-a-tty" | "raw-unavailable" | "no-answer" | null;
+  /** TERM value, useful for manual triage. */
+  term: string | null;
+}
+
+const PROBE_TIMEOUT_MS = 300;
+
+const XTVERSION_PROBE = "\x1bP>0q\x1b\\";
+const DA1_PROBE = "\x1b[c";
+const KITTY_PROBE = "\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\";
+const PIXEL_RES_PROBE = "\x1b[14t";
+
+/** Visible attributes in a DA1 primary response (e.g. `ESC[?6;22;4c`). Sixel is attribute 4. */
+const DA1_RESPONSE = /\x1b\[\?(\d+(?:;\d+)*)c/g;
+const XTVERSION_RESPONSE = /\x1bP>[|]([^\x1b]+)\x1b\\/;
+const KITTY_RESPONSE = /\x1b_Gi=31;([^\x1b]*)\x1b\\/;
+const PIXEL_RES_RESPONSE = /\x1b\[4;(\d+);(\d+)t/;
+
+export function detectMultiplexer(): "tmux" | "zellij" | "none" {
+  if (process.env["TMUX"]) return "tmux";
+  if (process.env["ZELLIJ"]) return "zellij";
+  return "none";
+}
+
+export function parseResponses(sequence: string): Partial<TerminalGraphicsCapabilities> {
+  const result: Partial<TerminalGraphicsCapabilities> = {};
+  const version = sequence.match(XTVERSION_RESPONSE)?.[1];
+  if (version) result.terminalName = version.trim();
+  for (const da1 of sequence.matchAll(DA1_RESPONSE)) {
+    if (da1[1]!.split(";").includes("4")) result.sixel = true;
+  }
+  const kitty = sequence.match(KITTY_RESPONSE);
+  if (kitty) result.kittyGraphics = !(kitty[1] ?? "").startsWith("E:");
+  const res = sequence.match(PIXEL_RES_RESPONSE);
+  if (res) result.pixelResolution = { width: Number(res[2]), height: Number(res[1]) };
+  return result;
+}
+
+export function probeTerminalGraphics(): Promise<TerminalGraphicsCapabilities> {
+  const probe: TerminalGraphicsCapabilities = {
+    terminalName: null,
+    multiplexer: detectMultiplexer(),
+    kittyGraphics: false,
+    sixel: false,
+    pixelResolution: null,
+    probeFailed: true,
+    probeFailedReason: null,
+    term: process.env["TERM"] ?? null,
+  };
+
+  if (!input.isTTY || typeof input.setRawMode !== "function") {
+    return Promise.resolve({ ...probe, probeFailedReason: "not-a-tty" });
+  }
+
+  return new Promise((resolve) => {
+    const rawActive = input.isRaw === true;
+    const restore = () => {
+      try { input.setRawMode(rawActive); } catch { /* restore best effort */ }
+    };
+    let buffer = "";
+    let settleTimeout: ReturnType<typeof setTimeout> | null = null;
+    let done = false;
+    const stop = () => {
+      if (done) return;
+      done = true;
+      clearTimeout(settleTimeout!);
+      input.removeListener("data", onData);
+      restore();
+    };
+    const settle = () => {
+      stop();
+      const parsed = parseResponses(buffer);
+      const failed = Object.keys(parsed).length === 0;
+      resolve({
+        ...probe,
+        ...parsed,
+        probeFailed: failed,
+        probeFailedReason: failed ? "no-answer" : null,
+      });
+    };
+    const onData = (chunk: Buffer | string) => {
+      buffer += typeof chunk === "string" ? chunk : chunk.toString("latin1");
+      clearTimeout(settleTimeout!);
+      settleTimeout = setTimeout(settle, 80);
+    };
+    try {
+      input.setRawMode(true);
+    } catch {
+      resolve({ ...probe, probeFailedReason: "raw-unavailable" });
+      return;
+    }
+    input.on("data", onData);
+    settleTimeout = setTimeout(settle, PROBE_TIMEOUT_MS);
+    output.write(XTVERSION_PROBE + DA1_PROBE + KITTY_PROBE + PIXEL_RES_PROBE);
+  });
+}
+
+export type ProviderIconAdvice = "graphics" | "kitty" | "sixel" | "blocks";
+
+/** Maps probed capabilities to the recommended `tui.providerIcons` value. */
+export function adviseProviderIcons(capabilities: TerminalGraphicsCapabilities): ProviderIconAdvice {
+  if (capabilities.multiplexer === "tmux" || capabilities.multiplexer === "zellij") return "blocks";
+  if (capabilities.kittyGraphics) return "graphics";
+  if (capabilities.sixel && capabilities.pixelResolution) return "graphics";
+  if (capabilities.sixel) return "sixel";
+  return "blocks";
+}

package/src/shared/types.ts

@@ -131,7 +131,7 @@ export interface AppOptions extends CollectorOptions {
 // ── New unified session model ─────────────────────────────────────────────────
 
 /** How the agent session was detected */
-export type SessionSource = "tmux" | "standalone";
+export type SessionSource = "tmux" | "herdr" | "standalone";
 
 /** The tool type — extended with "claude" and "error" variants */
 export type SessionTool = "opencode" | "claude" | "codex" | "copilotcli" | "shell" | "unknown";
@@ -190,6 +190,23 @@ export interface CodexSessionMeta {
   forkedFromId?: string;
 }
 
+/** Herdr pane and agent metadata */
+export interface HerdrSessionMeta {
+  paneId: string;
+  terminalId?: string;
+  workspaceId?: string;
+  workspace?: string;
+  tabId?: string;
+  tab?: string;
+  /** Explicit pane name — undefined when herdr only derived it from the agent name */
+  name?: string;
+  focused?: boolean;
+  providerSource: "socket" | "cli";
+  agent?: string;
+  agentStatus?: string;
+  agentSessionId?: string;
+}
+
 /** Unified session model used throughout daemon, API, MCP, and TUI */
 export interface SessionModel {
   id: string;
@@ -201,6 +218,8 @@ export interface SessionModel {
     session: string;
     window: string;
     pane: string;
+    /** tmux window (tab) name, used as display-name fallback */
+    windowName?: string;
   };
   summary: string;
   lastActivity: number;
@@ -212,10 +231,12 @@ export interface SessionModel {
   claude?: ClaudeSessionMeta;
   /** Populated when detected via Codex JSONL transcript or hooks */
   codex?: CodexSessionMeta;
+  /** Populated for panes discovered through herdr */
+  herdr?: HerdrSessionMeta;
   /** Populated when detected via legacy heuristics */
   legacyPaneId?: string;
   /** Data source description for UI display */
-  detectionSource?: "opencode-sdk" | "opencode-hook" | "claude-transcript" | "claude-hook" | "codex-transcript" | "codex-hook" | "fallback-detection" | "opencode-db";
+  detectionSource?: "opencode-sdk" | "opencode-hook" | "claude-transcript" | "claude-hook" | "codex-transcript" | "codex-hook" | "fallback-detection" | "opencode-db" | "herdr";
   /** ID of the parent session when this is a sub-agent session spawned by another session */
   parentSessionId?: string;
   /** IDs of direct child sessions spawned by this session (populated on parent sessions) */
@@ -278,6 +299,16 @@ export interface DaemonState {
   refreshedAt: number;
 }
 
+export interface HealthResponse {
+  ok: true;
+  version: string;
+  startedAt: number;
+  refreshedAt: number;
+  collectors: Record<string, CollectorStatus>;
+}
+
+export type DaemonHealth = Pick<HealthResponse, "ok"> & Partial<Omit<HealthResponse, "ok">>;
+
 export interface CollectorStatus {
   name: string;
   running: boolean;

package/src/shared/version.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface DaemonVersionMismatch {
+  cliVersion: string;
+  daemonVersion?: string;
+}
+
+function readInstalledVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8")) as { version?: unknown };
+    return typeof pkg.version === "string" && pkg.version.length > 0 ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+const INSTALLED_VERSION = readInstalledVersion();
+
+export function getInstalledVersion(): string {
+  return INSTALLED_VERSION;
+}
+
+export function getDaemonVersionMismatch(cliVersion: string, daemonVersion?: string): DaemonVersionMismatch | undefined {
+  if (cliVersion === "unknown") return undefined;
+  if (!daemonVersion || daemonVersion === "unknown") return { cliVersion };
+  if (daemonVersion === cliVersion) return undefined;
+  return { cliVersion, daemonVersion };
+}
+
+export function formatVersionDiagnostics(cliVersion: string, daemonVersion?: string): string {
+  const normalizedDaemonVersion = daemonVersion && daemonVersion !== "unknown" ? daemonVersion : "unknown";
+  const mismatch = getDaemonVersionMismatch(cliVersion, daemonVersion);
+  const lines = [
+    `CLI version: ${cliVersion}`,
+    `Daemon version: ${normalizedDaemonVersion}`,
+    `Version match: ${mismatch ? "false" : "true"}`,
+  ];
+  if (mismatch) {
+    lines.push("Action: scrylog daemon restart");
+    lines.push("Fallback: stop the running daemon and run scrylogd");
+  }
+  return `${lines.join("\n")}\n`;
+}