@adhdev/daemon-core 0.9.82-rc.361 → 0.9.82-rc.363

package/dist/mesh/mesh-events-utils.d.ts

@@ -52,6 +52,7 @@ export declare function resolveMeshSurfacedSessionPreview(metadataEvent: Record<
     role: 'assistant';
     receivedAt: number;
 } | undefined;
+export declare function isWeakCompletionMetadata(metadataEvent: Record<string, unknown>): boolean;
 export declare function buildMeshSystemMessage(args: {
     event: string;
     nodeLabel: string;

package/dist/providers/cli-provider-instance.d.ts

@@ -183,6 +183,8 @@ export declare class CliProviderInstance implements ProviderInstance {
     private hasAdapterPendingResponse;
     private shouldSuppressStaleParsedBusyStatus;
     private getCompletedFinalizationBlock;
+    private hasApprovalResolutionEvidence;
+    private approvalResolutionFinalizationBlock;
     private scheduleCompletedDebounceFlush;
     private isMeshWorkerSession;
     private meshTraceCtx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.361",
+  "version": "0.9.82-rc.363",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.361",
+    "@adhdev/mesh-shared": "0.9.82-rc.363",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/cli-adapters/cli-state-engine.ts

@@ -126,7 +126,13 @@ export class CliStateEngine {
      * seq) is always a real, distinct approval and must be written.
      */
     approvalEntrySeq = 0;
-    private lastResolvedEntrySeq = -1;
+    // Records which approval entry the last resolveModal() handled. Set unconditionally on
+    // every resolveModal (auto-approve fire, dashboard/mesh_approve, dev-cli-debug), so
+    // `lastResolvedEntrySeq >= approvalEntrySeq` is positive, ADHDev-side proof that the
+    // current/latest approval entry was actually resolved. Exposed via getStatus so the
+    // completion finalization gate (FALSEIDLE-a) can require resolution evidence before
+    // confirming a waiting_approval→idle transition. Public (read-only by convention).
+    lastResolvedEntrySeq = -1;
     /**
      * When the engine previously held a modal but the latest parse failed
      * to extract one, we record the timestamp here and only drop the modal

package/src/cli-adapters/provider-cli-adapter.ts

@@ -967,6 +967,7 @@ export class ProviderCliAdapter implements CliAdapter {
             workingDir: this.workingDir,
             activeModal: effectiveModal,
             approvalEntrySeq: this.engine.approvalEntrySeq,
+            lastResolvedEntrySeq: this.engine.lastResolvedEntrySeq,
             pendingOutboundCount: this.pendingOutboundQueue.length,
             pendingOutboundMessages: this.pendingOutboundQueue.map((message) => ({
                 id: message.id,

package/src/cli-adapters/provider-cli-shared.ts

@@ -38,6 +38,16 @@ export interface CliSessionStatus {
      * seq is the only reliable discriminator.
      */
     approvalEntrySeq?: number;
+    /**
+     * The approval entry seq that the engine's last resolveModal() handled. When
+     * `lastResolvedEntrySeq >= approvalEntrySeq` (and approvalEntrySeq > 0) it is positive
+     * evidence that the current/latest approval entry was resolved through ADHDev (auto-approve
+     * fire, dashboard / mesh_approve, or dev-cli-debug — all route through resolveModal). The
+     * completion finalization gate uses this to avoid confirming a waiting_approval→idle
+     * transition for which no resolution actually occurred (a false idle: the spec's text-based
+     * approval→idle rule tripped while the modal is still on screen).
+     */
+    lastResolvedEntrySeq?: number;
     activeInteractivePrompt?: InteractivePrompt | null;
     pendingOutboundCount?: number;
     pendingOutboundMessages?: Array<{

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

@@ -10,6 +10,13 @@
 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';
@@ -19,5 +26,12 @@ export const lowFamilyRegistry: LowFamilyRegistry = new Map(
         ...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,81 @@
+/**
+ * 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,
+            ...(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,
+        };
+    },
+};