@adhdev/daemon-core 0.9.82-rc.43 → 0.9.82-rc.430

package/src/commands/high-family/types.ts

@@ -0,0 +1,76 @@
+/**
+ * RF-ROUTER HIGH family — shared types for the extracted high-coupling command
+ * handlers. Like the LOW and MED families, each handler is a function of
+ * (context, args) that returns the exact CommandRouterResult the original
+ * `executeDaemonCommand` switch case returned, so the router facade is unchanged.
+ *
+ * HIGH handlers are the most router-coupled of the three families: in addition to
+ * the MED collaborators (mesh resolution, owner gating, inline-cache), they reach
+ * the router's aggregate-status memory cache and running-refine-job table — state
+ * the router owns and the `mesh_status` aggregate render and `get_mesh_review_inbox`
+ * re-entry both depend on. The router binds those onto HighFamilyContext at
+ * dispatch; they are NOT reachable from `deps`.
+ *
+ * Registry dispatch: DaemonCommandRouter.executeDaemonCommand looks up the cmd in
+ * highFamilyRegistry AFTER the LOW and MED registries and BEFORE its remaining
+ * switch; a hit returns the handler result, a miss falls through to the switch
+ * (and ultimately CommandHandler delegation).
+ */
+import type {
+    CommandRouterDeps,
+    CommandRouterResult,
+    MeshGitProbeCache,
+    MeshRefineJobHandle,
+} from '../router.js';
+import type { ResolvedMeshForCommand } from '../med-family/types.js';
+
+/**
+ * Router-private collaborators injected at dispatch. Each is a bound method or
+ * field of DaemonCommandRouter; handlers that don't need a given collaborator
+ * simply ignore it. The router owns this instance state (inline-mesh cache,
+ * aggregate-status memory cache, running-refine-job table, git-probe cache), so
+ * it cannot be read from `deps` — the registry receives bound references instead.
+ */
+export interface HighFamilyContext {
+    deps: CommandRouterDeps;
+
+    /** Bound `DaemonCommandRouter.getMeshForCommand`. */
+    getMeshForCommand: (
+        meshId: string,
+        inlineMesh?: unknown,
+        options?: { preferInline?: boolean },
+    ) => Promise<ResolvedMeshForCommand>;
+
+    /** Bound `DaemonCommandRouter.getCachedAggregateMeshStatus`. */
+    getCachedAggregateMeshStatus: (
+        meshId: string,
+        mesh?: any,
+        options?: { requireDirectPeerTruth?: boolean },
+    ) => any | null;
+
+    /** Bound `DaemonCommandRouter.rememberAggregateMeshStatus`. */
+    rememberAggregateMeshStatus: (meshId: string, snapshot: any, refreshReason: string) => any;
+
+    /**
+     * Bound `DaemonCommandRouter.execute`. `get_mesh_review_inbox` re-enters the
+     * router with a `mesh_status` refresh to obtain computed node fields; this is
+     * the same self-call the inlined case made.
+     */
+    execute: (cmd: string, args: any, source?: string) => Promise<CommandRouterResult>;
+
+    /** Router's aggregate-status memory cache (`.has()` probe in mesh_status). */
+    aggregateMeshStatusCache: Map<string, { builtAt: number; snapshot: any; queueRevision: string }>;
+
+    /** Router's running-refine-job table (surfaced as activeRefineJobs in mesh_status). */
+    runningRefineJobs: Map<string, MeshRefineJobHandle>;
+
+    /** Router's inline-mesh cache (launch_mesh_coordinator caches cloud inline mesh). */
+    inlineMeshCache: Map<string, any>;
+
+    /** Router's mesh git-probe cache (shared probe dedup for mesh_status). */
+    meshGitProbeCache: MeshGitProbeCache;
+}
+
+export type HighFamilyHandler = (ctx: HighFamilyContext, args: any) => Promise<CommandRouterResult | null>;
+
+export type HighFamilyRegistry = Map<string, HighFamilyHandler>;

package/src/commands/low-family/coordinator-prompt.ts

@@ -0,0 +1,72 @@
+/**
+ * RF-ROUTER LOW family — coordinator-prompt override/append file commands.
+ *
+ * Extracted verbatim from DaemonCommandRouter.executeDaemonCommand. Both handlers
+ * read/write only the on-disk ~/.adhdev/coordinator-prompts directory (no router
+ * instance state) and return the same CommandRouterResult the inlined cases did.
+ */
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+export const coordinatorPromptHandlers: Record<string, LowFamilyHandler> = {
+    list_coordinator_prompts: async (_ctx: LowFamilyContext, _args: any) => {
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        const os = await import('node:os');
+        const dir = path.join(os.homedir(), '.adhdev', 'coordinator-prompts');
+        const entries: Record<string, { override: string; append: string }> = {};
+        try {
+            if (fs.existsSync(dir)) {
+                for (const name of fs.readdirSync(dir)) {
+                    // Bucket files into <key>.{md|append.md}; ignore others
+                    // so a stray README or .DS_Store doesn't show up.
+                    const matchOverride = name.match(/^([a-zA-Z0-9_.-]+)\.md$/);
+                    const matchAppend = name.match(/^([a-zA-Z0-9_.-]+)\.append\.md$/);
+                    // append-pattern wins when both match (file is `.append.md`).
+                    const m = matchAppend || matchOverride;
+                    if (!m) continue;
+                    const isAppend = !!matchAppend;
+                    const key = m[1];
+                    const full = path.join(dir, name);
+                    let content = '';
+                    try { content = fs.readFileSync(full, 'utf8'); } catch { /* skip */ }
+                    if (!entries[key]) entries[key] = { override: '', append: '' };
+                    if (isAppend) entries[key].append = content;
+                    else entries[key].override = content;
+                }
+            }
+        } catch (error: any) {
+            return { success: false, error: error?.message || String(error) };
+        }
+        return { success: true, dir, entries };
+    },
+
+    write_coordinator_prompt: async (_ctx: LowFamilyContext, args: any) => {
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        const os = await import('node:os');
+        const key = typeof args?.key === 'string' ? args.key.trim() : '';
+        const kind = args?.kind === 'append' ? 'append' : 'override';
+        const content = typeof args?.content === 'string' ? args.content : '';
+        // Whitelist key chars so a malicious caller can't write
+        // ../../etc/passwd. Same charset readUserPromptFile accepts.
+        if (!key || !/^[a-zA-Z0-9_.-]+$/.test(key)) {
+            return { success: false, error: 'key must match [a-zA-Z0-9_.-]+' };
+        }
+        const dir = path.join(os.homedir(), '.adhdev', 'coordinator-prompts');
+        const filename = kind === 'append' ? `${key}.append.md` : `${key}.md`;
+        const full = path.join(dir, filename);
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            if (content.trim()) {
+                fs.writeFileSync(full, content, { encoding: 'utf8', mode: 0o600 });
+            } else if (fs.existsSync(full)) {
+                // Empty content = "reset to default" — delete the file
+                // so the daemon's readUserPromptFile path falls through.
+                fs.unlinkSync(full);
+            }
+            return { success: true, path: full, kind, key };
+        } catch (error: any) {
+            return { success: false, error: error?.message || String(error) };
+        }
+    },
+};

package/src/commands/low-family/daemon-lifecycle.ts

@@ -0,0 +1,107 @@
+/**
+ * RF-ROUTER LOW family — daemon self-upgrade + machine-settings commands.
+ *
+ * Extracted verbatim from DaemonCommandRouter.executeDaemonCommand. The
+ * release-channel helpers (ReleaseChannel / CHANNEL_* / normalizeReleaseChannel /
+ * resolveUpgradeChannel) were router module-locals used only by daemon_upgrade, so
+ * they are relocated here unchanged. Handlers read only ctx.deps.packageName /
+ * ctx.deps.statusVersion plus process-global config + npm/upgrade helpers, and
+ * return the same CommandRouterResult the inlined cases did.
+ */
+import { loadConfig, updateConfig } from '../../config/config.js';
+import { execNpmCommandSync, resolveCurrentGlobalInstallSurface, spawnDetachedDaemonUpgradeHelper } from '../upgrade-helper.js';
+import { LOG } from '../../logging/logger.js';
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+type ReleaseChannel = 'stable' | 'preview';
+const CHANNEL_NPM_TAG: Record<ReleaseChannel, 'latest' | 'next'> = { stable: 'latest', preview: 'next' };
+const CHANNEL_SERVER_URL: Record<ReleaseChannel, string> = {
+    stable: 'https://api.adhf.dev',
+    preview: 'https://api-preview.adhf.dev',
+};
+
+function normalizeReleaseChannel(value: unknown): ReleaseChannel | null {
+    if (typeof value !== 'string') return null;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'stable' || normalized === 'latest') return 'stable';
+    if (normalized === 'preview' || normalized === 'next') return 'preview';
+    return null;
+}
+
+function resolveUpgradeChannel(args: any): ReleaseChannel {
+    return normalizeReleaseChannel(args?.channel)
+        || normalizeReleaseChannel(args?.updatePolicy?.channel)
+        || normalizeReleaseChannel(args?.npmTag)
+        || normalizeReleaseChannel(loadConfig().updateChannel)
+        || 'stable';
+}
+
+export const daemonLifecycleHandlers: Record<string, LowFamilyHandler> = {
+    daemon_upgrade: async (ctx: LowFamilyContext, args: any) => {
+        LOG.info('Upgrade', 'Remote upgrade requested from dashboard');
+        try {
+            // Detect package name for upgrade
+            const isStandalone = ctx.deps.packageName === '@adhdev/daemon-standalone'
+                || process.argv[1]?.includes('daemon-standalone');
+            const pkgName = isStandalone ? '@adhdev/daemon-standalone' : 'adhdev';
+            const npmSurface = resolveCurrentGlobalInstallSurface({ packageName: pkgName });
+            const channel = resolveUpgradeChannel(args);
+            const npmTag = CHANNEL_NPM_TAG[channel];
+
+            // Check channel-pinned dist-tag and resolve it to a concrete install version.
+            const latest = String(execNpmCommandSync(['view', `${pkgName}@${npmTag}`, 'version'], { encoding: 'utf-8', timeout: 10000 }, npmSurface)).trim();
+            LOG.info('Upgrade', `Latest ${pkgName}@${npmTag}: v${latest}`);
+            updateConfig({ updateChannel: channel, serverUrl: CHANNEL_SERVER_URL[channel] } as any);
+            let currentInstalled: string | null = null;
+            try {
+                const currentJson = String(execNpmCommandSync(['ls', '-g', pkgName, '--depth=0', '--json'], {
+                    encoding: 'utf-8',
+                    timeout: 10000,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                }, npmSurface)).trim();
+                const parsed = JSON.parse(currentJson);
+                currentInstalled = parsed?.dependencies?.[pkgName]?.version || null;
+            } catch {
+                // ignore ls failures; upgrade can still proceed
+            }
+
+            const runningVersion = typeof ctx.deps.statusVersion === 'string'
+                ? ctx.deps.statusVersion.trim().replace(/^v/, '')
+                : null;
+            if (currentInstalled === latest && runningVersion === latest) {
+                LOG.info('Upgrade', `Already on ${channel} channel version v${latest}; skipping install`);
+                return { success: true, upgraded: false, alreadyLatest: true, version: latest, channel, npmTag };
+            }
+            if (currentInstalled === latest && runningVersion && runningVersion !== latest) {
+                LOG.info('Upgrade', `Installed package is v${latest}, but running daemon is v${runningVersion}; scheduling restart`);
+            }
+
+            spawnDetachedDaemonUpgradeHelper({
+                packageName: pkgName,
+                targetVersion: latest,
+                parentPid: process.pid,
+                restartArgv: process.argv.slice(1),
+                cwd: process.cwd(),
+                sessionHostAppName: process.env.ADHDEV_SESSION_HOST_NAME || 'adhdev',
+            });
+            LOG.info('Upgrade', `Scheduled detached ${channel} upgrade to v${latest}`);
+
+            // Exit after the command response has been sent so the helper can replace the package cleanly.
+            setTimeout(() => {
+                LOG.info('Upgrade', 'Exiting daemon so detached upgrader can continue...');
+                process.exit(0);
+            }, 3000);
+
+            return { success: true, upgraded: true, version: latest, restarting: true, channel, npmTag };
+        } catch (e: any) {
+            LOG.error('Upgrade', `Failed: ${e.message}`);
+            return { success: false, error: e.message };
+        }
+    },
+
+    set_machine_nickname: async (_ctx: LowFamilyContext, args: any) => {
+        const nickname = args?.nickname;
+        updateConfig({ machineNickname: nickname || null });
+        return { success: true };
+    },
+};

package/src/commands/low-family/diagnostics.ts

@@ -0,0 +1,57 @@
+/**
+ * RF-ROUTER LOW family — diagnostics read commands.
+ *
+ * Extracted verbatim from DaemonCommandRouter.executeDaemonCommand. Both handlers
+ * read only process-global logging buffers (ring buffer + file fallback + debug
+ * trace) — no router instance state — and return the same CommandRouterResult the
+ * inlined cases did.
+ */
+import * as fs from 'fs';
+import { getRecentLogs, LOG_PATH } from '../../logging/logger.js';
+import { getRecentDebugTrace } from '../../logging/debug-trace.js';
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+export const diagnosticsHandlers: Record<string, LowFamilyHandler> = {
+    get_logs: async (_ctx: LowFamilyContext, args: any) => {
+        const count = parseInt(args?.count) || parseInt(args?.lines) || 100;
+        const minLevel = args?.minLevel || 'info';
+        const sinceTs = args?.since || 0;
+
+        try {
+            // Priority 1: ring buffer (fast and structured)
+            let logs = getRecentLogs(count, minLevel);
+            if (sinceTs > 0) {
+                logs = logs.filter((l: any) => l.ts > sinceTs);
+            }
+            if (logs.length > 0) {
+                return { success: true, logs, totalBuffered: logs.length };
+            }
+            // Incremental polling must not fall back to unfiltered file text: the file
+            // format is not timestamp-filterable, and returning its tail makes the UI
+            // replace structured logs with old raw fallback lines when nothing new exists.
+            if (sinceTs > 0) {
+                return { success: true, logs: [], totalBuffered: 0 };
+            }
+            // Priority 2: file fallback
+            if (fs.existsSync(LOG_PATH)) {
+                const content = fs.readFileSync(LOG_PATH, 'utf-8');
+                const allLines = content.split('\n');
+                const recent = allLines.slice(-count).join('\n');
+                return { success: true, logs: recent, totalLines: allLines.length };
+            }
+            return { success: true, logs: [], totalBuffered: 0 };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+
+    get_debug_trace: async (_ctx: LowFamilyContext, args: any) => {
+        const count = parseInt(args?.count) || parseInt(args?.limit) || 100;
+        const sinceTs = Number(args?.since) || 0;
+        const interactionId = typeof args?.interactionId === 'string' ? args.interactionId : undefined;
+        const category = typeof args?.category === 'string' ? args.category : undefined;
+        const trace = getRecentDebugTrace({ interactionId, category, limit: count })
+            .filter((entry) => !sinceTs || entry.ts > sinceTs);
+        return { success: true, trace, count: trace.length };
+    },
+};

package/src/commands/low-family/index.ts

@@ -0,0 +1,37 @@
+/**
+ * RF-ROUTER LOW family — command registry.
+ *
+ * Aggregates the low-coupling command handlers extracted from
+ * DaemonCommandRouter.executeDaemonCommand into a single cmd → handler map.
+ * The router consults this registry before its switch (registry hit → return the
+ * handler result; miss → fall through to the remaining switch / CommandHandler
+ * delegation), so the facade and dispatch semantics are unchanged.
+ */
+import { sessionHostHandlers } from './session-host.js';
+import { specProviderDevHandlers } from './spec-providerdev.js';
+import { refineConfigHandlers } from './refine-config.js';
+import { diagnosticsHandlers } from './diagnostics.js';
+import { statusMetaHandlers } from './status-meta.js';
+import { coordinatorPromptHandlers } from './coordinator-prompt.js';
+import { notificationHandlers } from './notification.js';
+import { daemonLifecycleHandlers } from './daemon-lifecycle.js';
+import { meshLedgerHandlers } from './mesh-ledger.js';
+import { meshNodeLogsHandlers } from './mesh-node-logs.js';
+import type { LowFamilyRegistry } from './types.js';
+
+export type { LowFamilyContext, LowFamilyHandler, LowFamilyRegistry } from './types.js';
+
+export const lowFamilyRegistry: LowFamilyRegistry = new Map(
+    Object.entries({
+        ...sessionHostHandlers,
+        ...specProviderDevHandlers,
+        ...refineConfigHandlers,
+        ...diagnosticsHandlers,
+        ...statusMetaHandlers,
+        ...coordinatorPromptHandlers,
+        ...notificationHandlers,
+        ...daemonLifecycleHandlers,
+        ...meshLedgerHandlers,
+        ...meshNodeLogsHandlers,
+    }),
+);

package/src/commands/low-family/mesh-ledger.ts

@@ -0,0 +1,62 @@
+/**
+ * RF-ROUTER LOW family — mesh ledger read / slice / import commands.
+ *
+ * Extracted verbatim from DaemonCommandRouter.executeDaemonCommand. Each handler
+ * touches only the on-disk mesh ledger (dynamically imported mesh-ledger module)
+ * keyed by meshId — no router instance state — and returns the same
+ * CommandRouterResult the inlined cases did.
+ */
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+export const meshLedgerHandlers: Record<string, LowFamilyHandler> = {
+    get_mesh_ledger: async (_ctx: LowFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        try {
+            const { readLedgerEntries, getLedgerSummary } = await import('../../mesh/mesh-ledger.js');
+            const tail = typeof args?.tail === 'number' ? args.tail : 20;
+            const since = typeof args?.since === 'string' ? args.since : undefined;
+            const kind = Array.isArray(args?.kind) ? args.kind.filter((k: any) => typeof k === 'string') : undefined;
+            const entries = readLedgerEntries(meshId, { tail, since, kind });
+            const summary = getLedgerSummary(meshId);
+            return { success: true, entries, summary };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+
+    get_mesh_ledger_slice: async (_ctx: LowFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        try {
+            const { readLedgerSlice } = await import('../../mesh/mesh-ledger.js');
+            const kind = Array.isArray(args?.kind) ? args.kind.filter((k: any) => typeof k === 'string') : undefined;
+            const slice = readLedgerSlice(meshId, {
+                afterId: typeof args?.afterId === 'string' ? args.afterId : undefined,
+                since: typeof args?.since === 'string' ? args.since : undefined,
+                kind,
+                limit: typeof args?.limit === 'number' ? args.limit : undefined,
+            });
+            return { success: true, slice };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+
+    import_mesh_ledger_slice: async (_ctx: LowFamilyContext, args: any) => {
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        if (!meshId) return { success: false, error: 'meshId required' };
+        try {
+            const { appendRemoteLedgerEntries, getLedgerSummary } = await import('../../mesh/mesh-ledger.js');
+            const entries = Array.isArray(args?.entries)
+                ? args.entries as any[]
+                : Array.isArray(args?.slice?.entries)
+                    ? args.slice.entries as any[]
+                    : [];
+            const result = appendRemoteLedgerEntries(meshId, entries as any);
+            return { success: true, result, summary: getLedgerSummary(meshId) };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+};

package/src/commands/low-family/mesh-node-logs.ts

@@ -0,0 +1,87 @@
+/**
+ * RF-ROUTER LOW family — coordinator-driven remote daemon log fetch.
+ *
+ * Extracted verbatim from DaemonCommandRouter.executeDaemonCommand. Unlike the
+ * other LOW handlers this one resolves a node's owning daemonId from the router's
+ * inline-mesh cache, so it consumes the router-bound `ctx.getMeshForCommand`
+ * helper (mesh state is router instance state, not reconstructable from deps). The
+ * forward/local-read/redact logic is otherwise unchanged; returns the same
+ * CommandRouterResult the inlined case did.
+ */
+import { daemonIdsEquivalent, meshNodeIdMatches } from '@adhdev/mesh-shared';
+import { readDaemonLogTail, MAX_TAIL_BYTES } from '../../logging/log-tail-reader.js';
+import { redactLogLines } from '../../logging/log-redactor.js';
+import type { CommandRouterResult } from '../router.js';
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+export const meshNodeLogsHandlers: Record<string, LowFamilyHandler> = {
+    get_mesh_node_logs: async (ctx: LowFamilyContext, args: any) => {
+        // Coordinator-driven remote log fetch: read a (possibly remote)
+        // daemon's recent log tail over P2P instead of opening a session
+        // and grepping the file by hand. Mirrors fast_forward_mesh_node's
+        // forward pattern — resolve the node, forward to its owning daemon
+        // when remote, otherwise read locally. The reply tail is HARD
+        // byte-bounded and secret-redacted before it leaves the machine.
+        const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+        const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+        let nodeDaemonId: string | undefined;
+        if (meshId && nodeId && ctx.getMeshForCommand) {
+            const meshRecord = await ctx.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+            const node = meshRecord?.mesh?.nodes?.find((n: any) => meshNodeIdMatches(n, nodeId));
+            nodeDaemonId = typeof node?.daemonId === 'string' ? node.daemonId.trim() : undefined;
+        }
+        // _meshDirectDispatch prevents re-forwarding (and P2P self-dial)
+        // once the call lands on the owning daemon — that daemon then reads
+        // its own logs even if the stored daemonId uses a legacy form.
+        const selfDaemonId = ctx.deps.statusInstanceId;
+        // daemonIdsEquivalent: a legacy-form daemonId resolving to this machine's core is
+        // local — read locally instead of forwarding. Equivalent → local.
+        const isRemote = nodeDaemonId && selfDaemonId && !daemonIdsEquivalent(nodeDaemonId, selfDaemonId);
+        if (isRemote && ctx.deps.dispatchMeshCommand && !args?._meshDirectDispatch) {
+            const forwarded = await ctx.deps.dispatchMeshCommand(nodeDaemonId!, 'get_mesh_node_logs', {
+                ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
+                _meshDirectDispatch: true,
+            });
+            return (forwarded ?? { success: false, error: 'no response from remote node' }) as CommandRouterResult;
+        }
+
+        // Local read on the owning daemon.
+        const rawTailBytes = Number(args?.tailBytes);
+        const tail = readDaemonLogTail({
+            date: typeof args?.date === 'string' ? args.date : undefined,
+            tailBytes: Number.isFinite(rawTailBytes) ? Math.min(rawTailBytes, MAX_TAIL_BYTES) : undefined,
+            grep: typeof args?.grep === 'string' ? args.grep : undefined,
+            sinceMs: Number.isFinite(Number(args?.sinceMs)) ? Number(args?.sinceMs) : undefined,
+        });
+        if (!tail.success) {
+            return {
+                success: false,
+                error: tail.error || 'failed to read daemon log tail',
+                nodeId,
+                logPath: tail.logPath,
+                platform: tail.platform,
+            } as CommandRouterResult;
+        }
+        // SECURITY: redact secrets from every line before returning over P2P.
+        const redactedLines = redactLogLines(tail.lines);
+        return {
+            success: true,
+            nodeId,
+            daemonId: selfDaemonId,
+            logPath: tail.logPath,
+            platform: tail.platform,
+            lines: redactedLines,
+            lineCount: redactedLines.length,
+            truncated: tail.truncated,
+            filtered: tail.filtered,
+            bytesReturned: tail.bytesReturned,
+            // Transparency meta — lets the coordinator see that a full-file grep
+            // ran past the recent tail window, and how much was scanned/excluded.
+            fullScan: tail.fullScan,
+            scannedBytes: tail.scannedBytes,
+            matchedLineCount: tail.matchedLineCount,
+            excludedByFilter: tail.excludedByFilter,
+            ...(tail.grep ? { grep: tail.grep } : {}),
+        } as CommandRouterResult;
+    },
+};

package/src/commands/low-family/notification.ts

@@ -0,0 +1,116 @@
+/**
+ * RF-ROUTER LOW family — session notification / seen-state commands.
+ *
+ * Extracted verbatim from DaemonCommandRouter.executeDaemonCommand. Each handler
+ * mutates only the persisted recent-activity state store (loadState/saveState) and
+ * fires ctx.deps.onStatusChange; session lookup is rebuilt from deps the router
+ * already holds. Returns the same CommandRouterResult the inlined cases did.
+ */
+import { loadState, saveState } from '../../config/state-store.js';
+import { markSessionSeen, dismissSessionNotification, markSessionNotificationUnread } from '../../config/recent-activity.js';
+import { buildSessionEntries } from '../../status/builders.js';
+import { getSessionCompletionMarker } from '../../status/snapshot.js';
+import { LOG } from '../../logging/logger.js';
+import type { LowFamilyContext, LowFamilyHandler } from './types.js';
+
+const READ_DEBUG_ENABLED = process.argv.includes('--dev') || process.env.ADHDEV_READ_DEBUG === '1';
+
+export const notificationHandlers: Record<string, LowFamilyHandler> = {
+    mark_session_seen: async (ctx: LowFamilyContext, args: any) => {
+        const sessionId = args?.sessionId;
+        if (!sessionId || typeof sessionId !== 'string') {
+            return { success: false, error: 'sessionId is required' };
+        }
+        const currentState = loadState();
+        const prevSeenAt = currentState.sessionReads?.[sessionId] || 0;
+        const sessionEntries = buildSessionEntries(
+            ctx.deps.instanceManager.collectAllStates(),
+            ctx.deps.cdpManagers,
+        );
+        const targetSession = sessionEntries.find((entry) => entry.id === sessionId);
+        const requestedCompletionMarker = typeof args?.completionMarker === 'string'
+            ? args.completionMarker.trim()
+            : '';
+        const completionMarker = requestedCompletionMarker || (targetSession ? getSessionCompletionMarker(targetSession) : '');
+        const requestedProviderSessionId = typeof args?.providerSessionId === 'string'
+            ? args.providerSessionId.trim()
+            : '';
+        const providerSessionId = requestedProviderSessionId || targetSession?.providerSessionId;
+        const next = markSessionSeen(
+            currentState,
+            sessionId,
+            typeof args?.seenAt === 'number' ? args.seenAt : Date.now(),
+            completionMarker,
+            providerSessionId,
+        );
+        if (READ_DEBUG_ENABLED) {
+            LOG.info('RecentRead', `mark_session_seen sessionId=${sessionId} seenAt=${String(args?.seenAt || '')} prevSeenAt=${String(prevSeenAt)} nextSeenAt=${String(next.sessionReads?.[sessionId] || 0)} marker=${completionMarker || '-'}`);
+        }
+        saveState(next);
+        ctx.deps.onStatusChange?.();
+        return {
+            success: true,
+            sessionId,
+            seenAt: next.sessionReads?.[sessionId] || Date.now(),
+            completionMarker,
+        };
+    },
+
+    delete_notification: async (ctx: LowFamilyContext, args: any) => {
+        const sessionId = args?.sessionId;
+        const notificationId = typeof args?.notificationId === 'string' ? args.notificationId.trim() : '';
+        if (!sessionId || typeof sessionId !== 'string') {
+            return { success: false, error: 'sessionId is required' };
+        }
+        if (!notificationId) {
+            return { success: false, error: 'notificationId is required' };
+        }
+        const sessionEntries = buildSessionEntries(
+            ctx.deps.instanceManager.collectAllStates(),
+            ctx.deps.cdpManagers,
+        );
+        const targetSession = sessionEntries.find((entry) => entry.id === sessionId);
+        const next = dismissSessionNotification(
+            loadState(),
+            sessionId,
+            notificationId,
+            targetSession?.providerSessionId,
+        );
+        saveState(next);
+        ctx.deps.onStatusChange?.();
+        return {
+            success: true,
+            sessionId,
+            notificationId,
+        };
+    },
+
+    mark_notification_unread: async (ctx: LowFamilyContext, args: any) => {
+        const sessionId = args?.sessionId;
+        const notificationId = typeof args?.notificationId === 'string' ? args.notificationId.trim() : '';
+        if (!sessionId || typeof sessionId !== 'string') {
+            return { success: false, error: 'sessionId is required' };
+        }
+        if (!notificationId) {
+            return { success: false, error: 'notificationId is required' };
+        }
+        const sessionEntries = buildSessionEntries(
+            ctx.deps.instanceManager.collectAllStates(),
+            ctx.deps.cdpManagers,
+        );
+        const targetSession = sessionEntries.find((entry) => entry.id === sessionId);
+        const next = markSessionNotificationUnread(
+            loadState(),
+            sessionId,
+            notificationId,
+            targetSession?.providerSessionId,
+        );
+        saveState(next);
+        ctx.deps.onStatusChange?.();
+        return {
+            success: true,
+            sessionId,
+            notificationId,
+        };
+    },
+};