@adhdev/daemon-core 0.9.82-rc.360 → 0.9.82-rc.362

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

@@ -1,8 +1,6 @@
 import type { SessionRecoveryContext } from './mesh-ledger.js';
 export declare function readNonEmptyString(value: unknown): string;
 export declare function readRecord(value: unknown): Record<string, unknown> | undefined;
-export declare function canonicalDaemonId(value: unknown): string;
-export declare function sameDaemonId(a: unknown, b: unknown): boolean;
 /**
  * The relay-safety metadata a worker session must carry so that its completion /
  * generating events route back to the coordinator proactively (without waiting for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.360",
+  "version": "0.9.82-rc.362",
   "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.360",
+    "@adhdev/mesh-shared": "0.9.82-rc.362",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/commands/cli-manager.ts

@@ -148,6 +148,18 @@ function hasCompletedStartingLaunch(adapter: any): boolean {
     return hasFinalAssistantMessage(parsedStatus?.messages);
 }
 
+/**
+ * WTCLAIM (B): compare two workspace paths for node scoping. Normalizes separator
+ * style, trailing slashes, and case (Windows paths are case-insensitive; the
+ * coordinator-supplied node.workspace and the adapter's launch workingDir can
+ * differ only in those) so a base node and a worktree clone are still told apart
+ * by their distinct workspace roots.
+ */
+function normalizeDirForCompare(dir?: string): string {
+    if (typeof dir !== 'string') return '';
+    return dir.trim().replace(/[\\/]+/g, '/').replace(/\/+$/, '').toLowerCase();
+}
+
 function shouldSuppressStaleParsedBusyStatus(adapterStatus: string, parsedStatus: any, adapter: any): boolean {
     const parsedRawStatus = normalizeAgentStatus(parsedStatus?.status);
     if (!BUSY_AGENT_STATUSES.has(parsedRawStatus)) return false;
@@ -1142,6 +1154,40 @@ export class DaemonCliManager {
         return adapter ? { adapter, key: ik } : null;
     }
 
+    /**
+     * WTCLAIM (B): resolve the adapter for a mesh dispatch that named a node
+     * (meshContext.nodeId) but carried no explicit session. Matches by the
+     * instance's bound mesh node id (settings.meshNodeId, falling back to the
+     * sticky meshLastNodeId) first, then by the node workspace (workingDir).
+     *
+     * Unlike findAdapter's step-2 fuzzy fallback, this NEVER degrades to a
+     * provider-only first-match: on a daemon hosting BOTH a base node and a
+     * cloned worktree node (same daemonId), that fuzzy match could land a
+     * worktree-targeted task on the base session. Returns null when no session
+     * is bound to this node so the caller fails closed.
+     */
+    private findMeshNodeAdapter(agentType: string, nodeId: string, dir?: string): { adapter: CliAdapter; key: string } | null {
+        const instanceManager = this.deps.getInstanceManager();
+        const targetDir = normalizeDirForCompare(dir);
+        let workspaceMatch: { adapter: CliAdapter; key: string } | null = null;
+        for (const [k, a] of this.adapters) {
+            if (a.cliType !== agentType) continue;
+            const settings = (instanceManager?.getInstance(k) as any)?.getState?.()?.settings as Record<string, unknown> | undefined;
+            const boundNodeId = (typeof settings?.meshNodeId === 'string' && settings.meshNodeId.trim())
+                ? settings.meshNodeId.trim()
+                : (typeof settings?.meshLastNodeId === 'string' ? settings.meshLastNodeId.trim() : '');
+            // Exact node binding wins immediately (most precise).
+            if (boundNodeId && boundNodeId === nodeId) return { adapter: a, key: k };
+            // Workspace identity is the secondary signal for a session not (yet)
+            // stamped with a node id — a base node and a worktree clone always have
+            // distinct workspaces, so this still separates them.
+            if (!workspaceMatch && targetDir && normalizeDirForCompare(a.workingDir) === targetDir) {
+                workspaceMatch = { adapter: a, key: k };
+            }
+        }
+        return workspaceMatch;
+    }
+
  // ─── CLI command handling ────────────────────────────
 
     async handleCliCommand(cmd: string, args: any): Promise<CommandResult | null> {
@@ -1343,10 +1389,29 @@ export class DaemonCliManager {
                 const action = args?.action;
                 if (!agentType || !action) throw new Error('agentType and action required');
 
-                const found = this.findAdapter(agentType, {
-                    dir: args?.dir,
-                    instanceKey: args?.targetSessionId,
-                });
+                // WTCLAIM (B): a mesh dispatch that named a node (meshContext.nodeId)
+                // but resolved no explicit session must be scoped to THAT node's
+                // session — never routed by findAdapter's provider-only fuzzy fallback,
+                // which on a daemon hosting both a base node and a cloned worktree node
+                // (same daemonId) could land a worktree task on the base session. Fail
+                // closed when no session is bound to the node so the coordinator
+                // launches/retries instead of mis-landing the work.
+                const meshScopeNodeId = (() => {
+                    const mc = (args as any)?.meshContext;
+                    return mc && typeof mc === 'object' && typeof mc.nodeId === 'string' ? mc.nodeId.trim() : '';
+                })();
+                let found: { adapter: CliAdapter; key: string } | null;
+                if (meshScopeNodeId && !args?.targetSessionId) {
+                    found = this.findMeshNodeAdapter(agentType, meshScopeNodeId, args?.dir);
+                    if (!found) {
+                        throw new Error(`No mesh worker session bound to node '${meshScopeNodeId}' for agent '${agentType}' on this daemon; refusing provider-only fuzzy match to avoid cross-node dispatch`);
+                    }
+                } else {
+                    found = this.findAdapter(agentType, {
+                        dir: args?.dir,
+                        instanceKey: args?.targetSessionId,
+                    });
+                }
                 if (!found) throw new Error(`CLI agent not running: ${agentType}`);
                 const { adapter, key } = found;
 

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,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,
+        };
+    },
+};