@adhdev/daemon-core 0.9.82-rc.463 → 0.9.82-rc.465

package/src/providers/cli-provider-history-dedup.ts

@@ -0,0 +1,75 @@
+/**
+ * CLI provider persisted-history dedup — incremental append computation.
+ *
+ * Pure move out of cli-provider-instance.ts (no behavior change): the
+ * shared-prefix diff that turns a full parsed transcript into the newly-added
+ * tail to append to the persisted chat history. cli-provider-instance
+ * re-exports buildIncrementalHistoryAppendMessages so existing importers/tests
+ * keep their path.
+ */
+
+import { flattenContent } from './contracts.js';
+
+export type PersistableCliHistoryMessage = {
+    role: string;
+    content: string;
+    kind?: string;
+    senderName?: string;
+    receivedAt?: number;
+};
+
+function normalizePersistableCliHistoryContent(content: unknown): string {
+    return flattenContent(content as any).replace(/\s+/g, ' ').trim();
+}
+
+function buildPersistableCliHistorySignature(message: PersistableCliHistoryMessage): string {
+    return [
+        String(message.role || ''),
+        String(message.kind || ''),
+        String(message.senderName || ''),
+        normalizePersistableCliHistoryContent(message.content),
+    ].join('|');
+}
+
+function hasSamePersistableCliHistoryIdentity(a: PersistableCliHistoryMessage, b: PersistableCliHistoryMessage): boolean {
+    return String(a?.role || '') === String(b?.role || '')
+        && String(a?.kind || '') === String(b?.kind || '')
+        && String(a?.senderName || '') === String(b?.senderName || '')
+        && String(a?.content || '') === String(b?.content || '');
+}
+
+export function buildIncrementalHistoryAppendMessages(
+    previousMessages: PersistableCliHistoryMessage[],
+    currentMessages: PersistableCliHistoryMessage[],
+): PersistableCliHistoryMessage[] {
+    if (!Array.isArray(currentMessages) || currentMessages.length === 0) return [];
+    if (!Array.isArray(previousMessages) || previousMessages.length === 0) return currentMessages;
+
+    const comparableLength = Math.min(previousMessages.length, currentMessages.length);
+    let sharedPrefixLength = 0;
+    while (
+        sharedPrefixLength < comparableLength
+        && hasSamePersistableCliHistoryIdentity(previousMessages[sharedPrefixLength], currentMessages[sharedPrefixLength])
+    ) {
+        sharedPrefixLength += 1;
+    }
+
+    if (sharedPrefixLength === currentMessages.length) return [];
+    if (sharedPrefixLength === previousMessages.length) return currentMessages.slice(sharedPrefixLength);
+
+    // Rare fallback: preserve the older whitespace-normalized behavior only when
+    // the cheap identity check detects a changed prefix. Recomputing normalized
+    // signatures for the full transcript on every idle status poll was a CPU
+    // hot path for long CLI sessions.
+    while (
+        sharedPrefixLength < comparableLength
+        && buildPersistableCliHistorySignature(previousMessages[sharedPrefixLength])
+            === buildPersistableCliHistorySignature(currentMessages[sharedPrefixLength])
+    ) {
+        sharedPrefixLength += 1;
+    }
+
+    if (sharedPrefixLength === currentMessages.length) return [];
+    if (sharedPrefixLength === previousMessages.length) return currentMessages.slice(sharedPrefixLength);
+    return currentMessages;
+}

package/src/providers/cli-provider-input-prompt.ts

@@ -0,0 +1,133 @@
+/**
+ * CLI provider structured-input helpers — image materialization + prompt build.
+ *
+ * Pure move out of cli-provider-instance.ts (no behavior change): the input
+ * envelope → CLI prompt string construction and its image-materialization
+ * support. cli-provider-instance re-exports buildCliStructuredInputPrompt so
+ * existing importers/tests keep their path.
+ */
+
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import { type InputEnvelope, type InputPart } from './contracts.js';
+
+const IMAGE_MIME_EXTENSIONS: Record<string, string> = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/bmp': '.bmp',
+    'image/tiff': '.tiff',
+    'image/svg+xml': '.svg',
+};
+
+function filePathFromUri(uri: string): string | null {
+    if (!uri) return null;
+    if (uri.startsWith('file://')) {
+        try {
+            return decodeURIComponent(new URL(uri).pathname);
+        } catch {
+            return uri.slice('file://'.length);
+        }
+    }
+    if (path.isAbsolute(uri)) return uri;
+    return null;
+}
+
+function extensionForImageMime(mimeType: string): string {
+    return IMAGE_MIME_EXTENSIONS[mimeType.toLowerCase()] || '.img';
+}
+
+function safeInputImageBasename(index: number, mimeType: string): string {
+    const extension = extensionForImageMime(mimeType);
+    const suffix = crypto.randomBytes(6).toString('hex');
+    return `adhdev-input-image-${Date.now()}-${index}-${suffix}${extension}`;
+}
+
+function materializeImageDataPart(part: Extract<InputPart, { type: 'image' }>, index: number, dir: string): string | null {
+    if (!part.data) return null;
+    const rawData = part.data.includes(',') ? part.data.split(',').pop() || '' : part.data;
+    if (!rawData) return null;
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, safeInputImageBasename(index, part.mimeType));
+    fs.writeFileSync(filePath, Buffer.from(rawData, 'base64'));
+    cleanupStaleMaterializedImages(dir);
+    return filePath;
+}
+
+const MATERIALIZED_IMAGE_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+const MATERIALIZED_IMAGE_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+let lastMaterializedImageCleanupAt = 0;
+
+function cleanupStaleMaterializedImages(dir: string): void {
+    const now = Date.now();
+    if (now - lastMaterializedImageCleanupAt < MATERIALIZED_IMAGE_CLEANUP_INTERVAL_MS) return;
+    lastMaterializedImageCleanupAt = now;
+    try {
+        const entries = fs.readdirSync(dir);
+        for (const entry of entries) {
+            if (!entry.startsWith('adhdev-input-image-')) continue;
+            const fullPath = path.join(dir, entry);
+            try {
+                const stat = fs.statSync(fullPath);
+                if (now - stat.mtimeMs > MATERIALIZED_IMAGE_MAX_AGE_MS) {
+                    fs.unlinkSync(fullPath);
+                }
+            } catch { /* file may have been removed concurrently */ }
+        }
+    } catch { /* dir may not exist or be inaccessible */ }
+}
+
+export function buildCliStructuredInputPrompt(
+    input: InputEnvelope,
+    options: { materializeDir?: string } = {},
+): string {
+    const promptParts: string[] = [];
+    const imageRefs: string[] = [];
+    const resourceRefs: string[] = [];
+    const materializeDir = options.materializeDir || path.join(os.tmpdir(), 'adhdev-input-media');
+
+    input.parts.forEach((part, index) => {
+        if (part.type === 'text' && part.text.trim()) {
+            promptParts.push(part.text.trim());
+            return;
+        }
+
+        if (part.type === 'image') {
+            const localPath = typeof part.uri === 'string' ? filePathFromUri(part.uri) : null;
+            const materializedPath = !localPath && part.data ? materializeImageDataPart(part, index, materializeDir) : null;
+            const ref = localPath || materializedPath || part.uri || '';
+            if (ref) imageRefs.push(ref);
+            if (part.alt?.trim()) promptParts.push(part.alt.trim());
+            return;
+        }
+
+        if (part.type === 'resource_link') {
+            resourceRefs.push([part.title, part.name, part.description, part.uri].filter(Boolean).join('\n'));
+            return;
+        }
+
+        if (part.type === 'resource') {
+            resourceRefs.push([part.name, part.text, part.uri].filter(Boolean).join('\n'));
+        }
+    });
+
+    // Only use textFallback when no explicit text parts were collected — it is
+    // the flattened version of the same parts, so appending it alongside them
+    // would duplicate the content for multipart inputs.
+    const hasExplicitTextParts = input.parts.some((part) => part.type === 'text' && part.text.trim());
+    if (!hasExplicitTextParts && input.textFallback.trim()) {
+        promptParts.push(input.textFallback.trim());
+    }
+
+    const ordered = [
+        ...imageRefs,
+        ...promptParts,
+        ...resourceRefs,
+    ].filter((value, index, values) => value.trim().length > 0 && values.indexOf(value) === index);
+
+    return ordered.join('\n');
+}

package/src/providers/cli-provider-instance.ts

@@ -9,8 +9,7 @@ import * as os from 'os';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
-import { createRequire } from 'node:module';
-import { normalizeInputEnvelope, type ProviderModule, flattenContent, type InputEnvelope, type InputPart } from './contracts.js';
+import { normalizeInputEnvelope, type ProviderModule, flattenContent, type InputEnvelope } from './contracts.js';
 import { assertProviderSupportsDeclaredInput, getEffectiveMessageInputSupport } from './provider-input-support.js';
 import type { ProviderInstance, ProviderState, ProviderEvent, InstanceContext, ProviderErrorReason, HotChatSessionState, SessionModalState } from './provider-instance.js';
 import { normalizeInteractivePrompt, normalizeInteractivePromptResponse, type InteractivePrompt } from './types/interactive-prompt.js';
@@ -39,14 +38,28 @@ import {
 import { buildChatMessage, buildRuntimeSystemChatMessage, isUserFacingChatMessage, normalizeChatMessages, resolveChatMessageKind, extractFinalSummaryFromMessages, extractFinalSummaryFromMessagesAfter, readChatMessageTimestampMs } from './chat-message-normalization.js';
 import { workingDirBasename } from './working-dir.js';
 import { ManualAttendanceTracker } from './manual-attendance.js';
-
-type PersistableCliHistoryMessage = {
-    role: string;
-    content: string;
-    kind?: string;
-    senderName?: string;
-    receivedAt?: number;
-};
+import { buildCliStructuredInputPrompt } from './cli-provider-input-prompt.js';
+import { type PersistableCliHistoryMessage, buildIncrementalHistoryAppendMessages } from './cli-provider-history-dedup.js';
+import {
+    isIdleStatus,
+    getMessageTime,
+    hasNonEmptyCliModalButtons,
+    isCliGeneratingLikeStatus,
+    computeTurnAnchoredDurationMs,
+    getDatabaseSync,
+    getForcedNewSessionScriptName,
+    waitForCliAdapterReady,
+} from './cli-provider-status-helpers.js';
+
+// Re-export moved public symbols so existing importers (index.ts, tests) keep
+// their `./cli-provider-instance.js` path. Pure move — no behavior change.
+export { buildCliStructuredInputPrompt } from './cli-provider-input-prompt.js';
+export { buildIncrementalHistoryAppendMessages } from './cli-provider-history-dedup.js';
+export {
+    computeTurnAnchoredDurationMs,
+    getForcedNewSessionScriptName,
+    waitForCliAdapterReady,
+} from './cli-provider-status-helpers.js';
 
 // Status snapshots only ever surface the newest messages: the cloud 'live'
 // profile drops chat messages entirely (loaded lazily via read_chat on
@@ -94,19 +107,6 @@ type CompletedDebouncePending = {
     lastOutputAtArm?: number;
 };
 
-function isIdleStatus(value: unknown): boolean {
-    const status = typeof value === 'string' ? value.trim().toLowerCase() : '';
-    return !status || status === 'idle' || status === 'ready';
-}
-
-
-function getMessageTime(message: unknown): number {
-    if (!message || typeof message !== 'object') return 0;
-    const record = message as { receivedAt?: unknown; timestamp?: unknown };
-    const value = Number(record.receivedAt ?? record.timestamp ?? 0);
-    return Number.isFinite(value) ? value : 0;
-}
-
 type CompletedFinalizationBlock = {
     reason: string;
     terminal?: boolean;
@@ -189,278 +189,6 @@ const TERMINAL_MESH_EVENTS = new Set([
     'agent:ready',
 ]);
 
-const IMAGE_MIME_EXTENSIONS: Record<string, string> = {
-    'image/png': '.png',
-    'image/jpeg': '.jpg',
-    'image/jpg': '.jpg',
-    'image/gif': '.gif',
-    'image/webp': '.webp',
-    'image/bmp': '.bmp',
-    'image/tiff': '.tiff',
-    'image/svg+xml': '.svg',
-};
-
-function filePathFromUri(uri: string): string | null {
-    if (!uri) return null;
-    if (uri.startsWith('file://')) {
-        try {
-            return decodeURIComponent(new URL(uri).pathname);
-        } catch {
-            return uri.slice('file://'.length);
-        }
-    }
-    if (path.isAbsolute(uri)) return uri;
-    return null;
-}
-
-function extensionForImageMime(mimeType: string): string {
-    return IMAGE_MIME_EXTENSIONS[mimeType.toLowerCase()] || '.img';
-}
-
-function safeInputImageBasename(index: number, mimeType: string): string {
-    const extension = extensionForImageMime(mimeType);
-    const suffix = crypto.randomBytes(6).toString('hex');
-    return `adhdev-input-image-${Date.now()}-${index}-${suffix}${extension}`;
-}
-
-function materializeImageDataPart(part: Extract<InputPart, { type: 'image' }>, index: number, dir: string): string | null {
-    if (!part.data) return null;
-    const rawData = part.data.includes(',') ? part.data.split(',').pop() || '' : part.data;
-    if (!rawData) return null;
-    fs.mkdirSync(dir, { recursive: true });
-    const filePath = path.join(dir, safeInputImageBasename(index, part.mimeType));
-    fs.writeFileSync(filePath, Buffer.from(rawData, 'base64'));
-    cleanupStaleMaterializedImages(dir);
-    return filePath;
-}
-
-const MATERIALIZED_IMAGE_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
-const MATERIALIZED_IMAGE_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
-let lastMaterializedImageCleanupAt = 0;
-
-function cleanupStaleMaterializedImages(dir: string): void {
-    const now = Date.now();
-    if (now - lastMaterializedImageCleanupAt < MATERIALIZED_IMAGE_CLEANUP_INTERVAL_MS) return;
-    lastMaterializedImageCleanupAt = now;
-    try {
-        const entries = fs.readdirSync(dir);
-        for (const entry of entries) {
-            if (!entry.startsWith('adhdev-input-image-')) continue;
-            const fullPath = path.join(dir, entry);
-            try {
-                const stat = fs.statSync(fullPath);
-                if (now - stat.mtimeMs > MATERIALIZED_IMAGE_MAX_AGE_MS) {
-                    fs.unlinkSync(fullPath);
-                }
-            } catch { /* file may have been removed concurrently */ }
-        }
-    } catch { /* dir may not exist or be inaccessible */ }
-}
-
-function hasNonEmptyCliModalButtons(activeModal: unknown): boolean {
-    const buttons = (activeModal as any)?.buttons;
-    return Array.isArray(buttons) && buttons.some((button) => String(button || '').trim().length > 0);
-}
-
-function isCliGeneratingLikeStatus(status: unknown): boolean {
-    return status === 'generating' || status === 'streaming' || status === 'no_progress' || status === 'long_generating' || status === 'starting';
-}
-
-/**
- * NOTIF Defect-2a: the REPORTED short-generating duration, anchored on the IMMUTABLE turn
- * start. generatingStartedAt is reset to 0 on every mid-turn waiting_approval/idle blip and
- * re-armed on the next →generating, so a long turn that blips would otherwise measure only the
- * final 1.5-2.5s sliver. engine.currentTurnStartedAt (set once at onTurnStarted, surviving
- * mid-turn blips until the next turn starts) is preferred; generatingStartedAt is the fallback
- * for turns that never recorded an engine turn start. Returns 0 when neither anchor is set.
- * Pure / unit-testable.
- */
-export function computeTurnAnchoredDurationMs(
-    engineTurnStartedAt: number | undefined,
-    generatingStartedAt: number,
-    now: number,
-): { durationMs: number; anchor: 'turn-start' | 'generatingStartedAt' | 'none' } {
-    const engineStart = typeof engineTurnStartedAt === 'number' && Number.isFinite(engineTurnStartedAt)
-        ? engineTurnStartedAt
-        : 0;
-    if (engineStart > 0) return { durationMs: now - engineStart, anchor: 'turn-start' };
-    if (generatingStartedAt > 0) return { durationMs: now - generatingStartedAt, anchor: 'generatingStartedAt' };
-    return { durationMs: 0, anchor: 'none' };
-}
-
-export function buildCliStructuredInputPrompt(
-    input: InputEnvelope,
-    options: { materializeDir?: string } = {},
-): string {
-    const promptParts: string[] = [];
-    const imageRefs: string[] = [];
-    const resourceRefs: string[] = [];
-    const materializeDir = options.materializeDir || path.join(os.tmpdir(), 'adhdev-input-media');
-
-    input.parts.forEach((part, index) => {
-        if (part.type === 'text' && part.text.trim()) {
-            promptParts.push(part.text.trim());
-            return;
-        }
-
-        if (part.type === 'image') {
-            const localPath = typeof part.uri === 'string' ? filePathFromUri(part.uri) : null;
-            const materializedPath = !localPath && part.data ? materializeImageDataPart(part, index, materializeDir) : null;
-            const ref = localPath || materializedPath || part.uri || '';
-            if (ref) imageRefs.push(ref);
-            if (part.alt?.trim()) promptParts.push(part.alt.trim());
-            return;
-        }
-
-        if (part.type === 'resource_link') {
-            resourceRefs.push([part.title, part.name, part.description, part.uri].filter(Boolean).join('\n'));
-            return;
-        }
-
-        if (part.type === 'resource') {
-            resourceRefs.push([part.name, part.text, part.uri].filter(Boolean).join('\n'));
-        }
-    });
-
-    // Only use textFallback when no explicit text parts were collected — it is
-    // the flattened version of the same parts, so appending it alongside them
-    // would duplicate the content for multipart inputs.
-    const hasExplicitTextParts = input.parts.some((part) => part.type === 'text' && part.text.trim());
-    if (!hasExplicitTextParts && input.textFallback.trim()) {
-        promptParts.push(input.textFallback.trim());
-    }
-
-    const ordered = [
-        ...imageRefs,
-        ...promptParts,
-        ...resourceRefs,
-    ].filter((value, index, values) => value.trim().length > 0 && values.indexOf(value) === index);
-
-    return ordered.join('\n');
-}
-
-function normalizePersistableCliHistoryContent(content: unknown): string {
-    return flattenContent(content as any).replace(/\s+/g, ' ').trim();
-}
-
-function buildPersistableCliHistorySignature(message: PersistableCliHistoryMessage): string {
-    return [
-        String(message.role || ''),
-        String(message.kind || ''),
-        String(message.senderName || ''),
-        normalizePersistableCliHistoryContent(message.content),
-    ].join('|');
-}
-
-function hasSamePersistableCliHistoryIdentity(a: PersistableCliHistoryMessage, b: PersistableCliHistoryMessage): boolean {
-    return String(a?.role || '') === String(b?.role || '')
-        && String(a?.kind || '') === String(b?.kind || '')
-        && String(a?.senderName || '') === String(b?.senderName || '')
-        && String(a?.content || '') === String(b?.content || '');
-}
-
-export function buildIncrementalHistoryAppendMessages(
-    previousMessages: PersistableCliHistoryMessage[],
-    currentMessages: PersistableCliHistoryMessage[],
-): PersistableCliHistoryMessage[] {
-    if (!Array.isArray(currentMessages) || currentMessages.length === 0) return [];
-    if (!Array.isArray(previousMessages) || previousMessages.length === 0) return currentMessages;
-
-    const comparableLength = Math.min(previousMessages.length, currentMessages.length);
-    let sharedPrefixLength = 0;
-    while (
-        sharedPrefixLength < comparableLength
-        && hasSamePersistableCliHistoryIdentity(previousMessages[sharedPrefixLength], currentMessages[sharedPrefixLength])
-    ) {
-        sharedPrefixLength += 1;
-    }
-
-    if (sharedPrefixLength === currentMessages.length) return [];
-    if (sharedPrefixLength === previousMessages.length) return currentMessages.slice(sharedPrefixLength);
-
-    // Rare fallback: preserve the older whitespace-normalized behavior only when
-    // the cheap identity check detects a changed prefix. Recomputing normalized
-    // signatures for the full transcript on every idle status poll was a CPU
-    // hot path for long CLI sessions.
-    while (
-        sharedPrefixLength < comparableLength
-        && buildPersistableCliHistorySignature(previousMessages[sharedPrefixLength])
-            === buildPersistableCliHistorySignature(currentMessages[sharedPrefixLength])
-    ) {
-        sharedPrefixLength += 1;
-    }
-
-    if (sharedPrefixLength === currentMessages.length) return [];
-    if (sharedPrefixLength === previousMessages.length) return currentMessages.slice(sharedPrefixLength);
-    return currentMessages;
-}
-
-let CachedDatabaseSync: (new (path: string, options?: { readOnly?: boolean }) => {
-    prepare(sql: string): { get(...params: Array<string | number>): unknown };
-    close(): void;
-}) | null = null;
-
-function getDatabaseSync() {
-    if (CachedDatabaseSync) return CachedDatabaseSync;
-    const requireFn = typeof require === 'function'
-        ? require
-        : createRequire(path.join(process.cwd(), '__adhdev_sqlite_loader__.js'));
-    const sqliteModule = requireFn(`node:${'sqlite'}`) as {
-        DatabaseSync: typeof CachedDatabaseSync;
-    };
-    CachedDatabaseSync = sqliteModule.DatabaseSync;
-    if (!CachedDatabaseSync) {
-        throw new Error('node:sqlite DatabaseSync unavailable');
-    }
-    return CachedDatabaseSync;
-}
-
-export function getForcedNewSessionScriptName(
-    provider: ProviderModule | undefined,
-    launchMode: 'new' | 'resume' | 'manual',
-): string | null {
-    if (!provider || launchMode !== 'new') return null;
-    const resume = provider.resume;
-    if (!resume?.supported) return null;
-    if (Array.isArray(resume.newSessionArgs) && resume.newSessionArgs.length > 0) return null;
-
-    const controls = Array.isArray((provider as any).controls) ? (provider as any).controls : [];
-    for (const control of controls) {
-        if (control?.type !== 'action') continue;
-        if (typeof control?.confirmTitle === 'string' && control.confirmTitle.trim()) continue;
-        if (typeof control?.confirmMessage === 'string' && control.confirmMessage.trim()) continue;
-        if (typeof control?.confirmLabel === 'string' && control.confirmLabel.trim()) continue;
-        const invokeScript = typeof control?.invokeScript === 'string' ? control.invokeScript.trim() : '';
-        if (!invokeScript) continue;
-        const controlId = typeof control?.id === 'string' ? control.id.trim() : '';
-        if (controlId === 'new_session' || /^new.?session$/i.test(invokeScript)) {
-            return invokeScript;
-        }
-    }
-
-    return null;
-}
-
-export async function waitForCliAdapterReady(
-    adapter: { isReady?: () => boolean; getStatus?: () => { status?: string } },
-    options?: { timeoutMs?: number; pollMs?: number },
-): Promise<void> {
-    const timeoutMs = Math.max(100, options?.timeoutMs ?? 15_000);
-    const pollMs = Math.max(10, options?.pollMs ?? 50);
-    const deadline = Date.now() + timeoutMs;
-
-    while (Date.now() < deadline) {
-        if (adapter?.isReady?.()) return;
-        const status = adapter?.getStatus?.()?.status;
-        if (status === 'stopped') {
-            throw new Error('CLI runtime stopped before it became ready');
-        }
-        await new Promise((resolve) => setTimeout(resolve, pollMs));
-    }
-
-    throw new Error(`CLI runtime did not become ready within ${timeoutMs}ms`);
-}
-
 export class CliProviderInstance implements ProviderInstance {
     readonly type: string;
     readonly category = 'cli' as const;

package/src/providers/cli-provider-status-helpers.ts

@@ -0,0 +1,123 @@
+/**
+ * CLI provider status/launch pure helpers.
+ *
+ * Pure move out of cli-provider-instance.ts (no behavior change): the
+ * side-effect-free status predicates, the turn-anchored duration computation,
+ * the forced-new-session script resolver, the adapter-ready poll, and the lazy
+ * node:sqlite DatabaseSync loader. cli-provider-instance re-exports the
+ * public symbols (computeTurnAnchoredDurationMs, getForcedNewSessionScriptName,
+ * waitForCliAdapterReady) so existing importers/tests keep their path.
+ */
+
+import * as path from 'path';
+import { createRequire } from 'node:module';
+import type { ProviderModule } from './contracts.js';
+
+export function isIdleStatus(value: unknown): boolean {
+    const status = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return !status || status === 'idle' || status === 'ready';
+}
+
+export function getMessageTime(message: unknown): number {
+    if (!message || typeof message !== 'object') return 0;
+    const record = message as { receivedAt?: unknown; timestamp?: unknown };
+    const value = Number(record.receivedAt ?? record.timestamp ?? 0);
+    return Number.isFinite(value) ? value : 0;
+}
+
+export function hasNonEmptyCliModalButtons(activeModal: unknown): boolean {
+    const buttons = (activeModal as any)?.buttons;
+    return Array.isArray(buttons) && buttons.some((button) => String(button || '').trim().length > 0);
+}
+
+export function isCliGeneratingLikeStatus(status: unknown): boolean {
+    return status === 'generating' || status === 'streaming' || status === 'no_progress' || status === 'long_generating' || status === 'starting';
+}
+
+/**
+ * NOTIF Defect-2a: the REPORTED short-generating duration, anchored on the IMMUTABLE turn
+ * start. generatingStartedAt is reset to 0 on every mid-turn waiting_approval/idle blip and
+ * re-armed on the next →generating, so a long turn that blips would otherwise measure only the
+ * final 1.5-2.5s sliver. engine.currentTurnStartedAt (set once at onTurnStarted, surviving
+ * mid-turn blips until the next turn starts) is preferred; generatingStartedAt is the fallback
+ * for turns that never recorded an engine turn start. Returns 0 when neither anchor is set.
+ * Pure / unit-testable.
+ */
+export function computeTurnAnchoredDurationMs(
+    engineTurnStartedAt: number | undefined,
+    generatingStartedAt: number,
+    now: number,
+): { durationMs: number; anchor: 'turn-start' | 'generatingStartedAt' | 'none' } {
+    const engineStart = typeof engineTurnStartedAt === 'number' && Number.isFinite(engineTurnStartedAt)
+        ? engineTurnStartedAt
+        : 0;
+    if (engineStart > 0) return { durationMs: now - engineStart, anchor: 'turn-start' };
+    if (generatingStartedAt > 0) return { durationMs: now - generatingStartedAt, anchor: 'generatingStartedAt' };
+    return { durationMs: 0, anchor: 'none' };
+}
+
+let CachedDatabaseSync: (new (path: string, options?: { readOnly?: boolean }) => {
+    prepare(sql: string): { get(...params: Array<string | number>): unknown };
+    close(): void;
+}) | null = null;
+
+export function getDatabaseSync() {
+    if (CachedDatabaseSync) return CachedDatabaseSync;
+    const requireFn = typeof require === 'function'
+        ? require
+        : createRequire(path.join(process.cwd(), '__adhdev_sqlite_loader__.js'));
+    const sqliteModule = requireFn(`node:${'sqlite'}`) as {
+        DatabaseSync: typeof CachedDatabaseSync;
+    };
+    CachedDatabaseSync = sqliteModule.DatabaseSync;
+    if (!CachedDatabaseSync) {
+        throw new Error('node:sqlite DatabaseSync unavailable');
+    }
+    return CachedDatabaseSync;
+}
+
+export function getForcedNewSessionScriptName(
+    provider: ProviderModule | undefined,
+    launchMode: 'new' | 'resume' | 'manual',
+): string | null {
+    if (!provider || launchMode !== 'new') return null;
+    const resume = provider.resume;
+    if (!resume?.supported) return null;
+    if (Array.isArray(resume.newSessionArgs) && resume.newSessionArgs.length > 0) return null;
+
+    const controls = Array.isArray((provider as any).controls) ? (provider as any).controls : [];
+    for (const control of controls) {
+        if (control?.type !== 'action') continue;
+        if (typeof control?.confirmTitle === 'string' && control.confirmTitle.trim()) continue;
+        if (typeof control?.confirmMessage === 'string' && control.confirmMessage.trim()) continue;
+        if (typeof control?.confirmLabel === 'string' && control.confirmLabel.trim()) continue;
+        const invokeScript = typeof control?.invokeScript === 'string' ? control.invokeScript.trim() : '';
+        if (!invokeScript) continue;
+        const controlId = typeof control?.id === 'string' ? control.id.trim() : '';
+        if (controlId === 'new_session' || /^new.?session$/i.test(invokeScript)) {
+            return invokeScript;
+        }
+    }
+
+    return null;
+}
+
+export async function waitForCliAdapterReady(
+    adapter: { isReady?: () => boolean; getStatus?: () => { status?: string } },
+    options?: { timeoutMs?: number; pollMs?: number },
+): Promise<void> {
+    const timeoutMs = Math.max(100, options?.timeoutMs ?? 15_000);
+    const pollMs = Math.max(10, options?.pollMs ?? 50);
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        if (adapter?.isReady?.()) return;
+        const status = adapter?.getStatus?.()?.status;
+        if (status === 'stopped') {
+            throw new Error('CLI runtime stopped before it became ready');
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+
+    throw new Error(`CLI runtime did not become ready within ${timeoutMs}ms`);
+}