@adhdev/daemon-core 0.9.82-rc.185 → 0.9.82-rc.187

package/src/mesh/mesh-events.ts

@@ -608,6 +608,166 @@ function hasUnterminalDirectDispatchLedgerEntry(meshId: string, sessionId: strin
     return false;
 }
 
+function findDirectDispatchLedgerEntry(args: {
+    meshId: string;
+    taskId: string;
+    sessionId?: string;
+}): { id: string; timestamp: string; nodeId?: string; sessionId?: string; providerType?: string; payload: Record<string, unknown> } | null {
+    const entries = readLedgerEntries(args.meshId, { tail: 500 });
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (entry.kind !== 'task_dispatched') continue;
+        const payloadTaskId = readNonEmptyString(entry.payload?.taskId);
+        if (payloadTaskId !== args.taskId) continue;
+        if (args.sessionId && entry.sessionId && entry.sessionId !== args.sessionId) continue;
+        return {
+            id: entry.id,
+            timestamp: entry.timestamp,
+            nodeId: entry.nodeId,
+            sessionId: entry.sessionId,
+            providerType: entry.providerType,
+            payload: entry.payload || {},
+        };
+    }
+    return null;
+}
+
+function hasTerminalLedgerAfterDispatch(args: {
+    meshId: string;
+    taskId: string;
+    sessionId?: string;
+    dispatchEntryId?: string;
+    dispatchTimestamp?: string;
+}): boolean {
+    const entries = readLedgerEntries(args.meshId, { tail: 500 });
+    let afterDispatch = !args.dispatchEntryId && !args.dispatchTimestamp;
+    const dispatchTime = args.dispatchTimestamp ? new Date(args.dispatchTimestamp).getTime() : Number.NaN;
+    for (const entry of entries) {
+        if (!afterDispatch) {
+            if (args.dispatchEntryId && entry.id === args.dispatchEntryId) {
+                afterDispatch = true;
+                continue;
+            }
+            if (!args.dispatchEntryId && Number.isFinite(dispatchTime)) {
+                const entryTime = new Date(entry.timestamp).getTime();
+                if (Number.isFinite(entryTime) && entryTime >= dispatchTime) afterDispatch = true;
+            }
+            if (!afterDispatch) continue;
+        }
+        if (entry.kind !== 'task_completed' && entry.kind !== 'task_failed' && entry.kind !== 'task_stalled') continue;
+        const terminalTaskId = readNonEmptyString(entry.payload?.taskId);
+        if (terminalTaskId && terminalTaskId === args.taskId) return true;
+        if (terminalTaskId && terminalTaskId !== args.taskId) continue;
+        if (args.sessionId && entry.sessionId === args.sessionId) return true;
+    }
+    return false;
+}
+
+export function reconcileDirectDispatchCompletionFromTranscript(args: {
+    meshId: string;
+    nodeId?: string;
+    sessionId: string;
+    providerType?: string;
+    providerSessionId?: string;
+    taskId: string;
+    finalSummary: string;
+    transcriptMessageAt?: string;
+    completedAt?: string;
+    targetCoordinatorDaemonId?: string;
+    source?: string;
+}): { reconciled: boolean; kind?: MeshLedgerKind; alreadyTerminal?: boolean; workerResult?: unknown; ledgerEntryId?: string; reason?: string } {
+    const finalSummary = readNonEmptyString(args.finalSummary);
+    if (!args.meshId || !args.taskId || !args.sessionId || !finalSummary) {
+        return { reconciled: false, reason: 'missing_required_completion_evidence' };
+    }
+
+    const dispatch = findDirectDispatchLedgerEntry({
+        meshId: args.meshId,
+        taskId: args.taskId,
+        sessionId: args.sessionId,
+    });
+    if (hasTerminalLedgerAfterDispatch({
+        meshId: args.meshId,
+        taskId: args.taskId,
+        sessionId: args.sessionId,
+        dispatchEntryId: dispatch?.id,
+        dispatchTimestamp: dispatch?.timestamp,
+    })) {
+        return { reconciled: false, alreadyTerminal: true, reason: 'terminal_ledger_entry_exists' };
+    }
+
+    const nodeId = readNonEmptyString(args.nodeId) || dispatch?.nodeId;
+    const providerType = readNonEmptyString(args.providerType) || dispatch?.providerType || readNonEmptyString(dispatch?.payload.providerType);
+    const completedAt = args.completedAt || new Date().toISOString();
+    const evidence = buildTaskCompletionEvidence({
+        event: 'agent:generating_completed',
+        nodeId: nodeId || 'unknown',
+        sessionId: args.sessionId,
+        providerType,
+        providerSessionId: readNonEmptyString(args.providerSessionId),
+        finalSummary,
+        completedAt,
+    });
+    const workerResult = evidence.workerResult;
+    const dispatchTime = dispatch?.timestamp ? new Date(dispatch.timestamp).getTime() : Number.NaN;
+    const transcriptTime = args.transcriptMessageAt ? new Date(args.transcriptMessageAt).getTime() : Number.NaN;
+    const transcriptAfterDispatch = Number.isFinite(dispatchTime) && Number.isFinite(transcriptTime) && transcriptTime >= dispatchTime;
+    if (workerResult.source !== 'final_summary_json' && !transcriptAfterDispatch) {
+        return { reconciled: false, reason: 'transcript_not_proven_after_dispatch' };
+    }
+    const workerFailed = workerResult.status === 'failed' || (workerResult.status !== 'completed' && workerResult.errors.length > 0);
+    const kind: MeshLedgerKind = workerFailed ? 'task_failed' : 'task_completed';
+
+    const entry = appendLedgerEntry(args.meshId, {
+        kind,
+        nodeId: nodeId || undefined,
+        sessionId: args.sessionId,
+        providerType: providerType || undefined,
+        payload: {
+            event: 'agent:generating_completed',
+            source: args.source || 'direct_task_transcript_reconciliation',
+            taskId: args.taskId,
+            providerSessionId: readNonEmptyString(args.providerSessionId),
+            finalSummary,
+            workerResult,
+            completionDiagnostic: {
+                reason: 'direct_task_transcript_reconciliation',
+                dispatchEntryId: dispatch?.id,
+                dispatchTimestamp: dispatch?.timestamp,
+                transcriptMessageAt: readNonEmptyString(args.transcriptMessageAt),
+                transcriptFinalAssistantPresent: true,
+            },
+            evidence,
+        },
+    });
+    updateDirectDispatchStatus(args.meshId, args.sessionId, kind === 'task_completed' ? 'completed' : 'failed');
+    setImmediate(() => cleanupTerminalDirectDispatches());
+    queuePendingMeshCoordinatorEvent({
+        event: kind === 'task_completed' ? 'agent:generating_completed' : 'agent:stopped',
+        meshId: args.meshId,
+        nodeLabel: nodeId ? `Node '${nodeId}'` : 'Remote agent',
+        nodeId: nodeId || undefined,
+        metadataEvent: {
+            targetSessionId: args.sessionId,
+            providerType: providerType || undefined,
+            providerSessionId: readNonEmptyString(args.providerSessionId),
+            finalSummary,
+            taskId: args.taskId,
+            workerResult,
+            completionDiagnostic: {
+                reason: 'direct_task_transcript_reconciliation',
+                terminalLedgerKind: kind,
+                terminalLedgerId: entry.id,
+            },
+        },
+        coordinatorMessage: undefined,
+        queuedAt: Date.now(),
+        ...(readNonEmptyString(args.targetCoordinatorDaemonId) ? { targetCoordinatorDaemonId: readNonEmptyString(args.targetCoordinatorDaemonId) } : {}),
+    });
+
+    return { reconciled: true, kind, workerResult, ledgerEntryId: entry.id };
+}
+
 function buildLongGeneratingCompletionReconciliation(args: {
     meshId: string;
     nodeId?: string;
@@ -1019,13 +1179,69 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
     return false;
 }
 
+export interface MeshQueueTriggerResult {
+    success: true;
+    meshId: string;
+    pendingBefore: number;
+    assignedBefore: number;
+    pendingAfter: number;
+    assignedAfter: number;
+    claimed: boolean;
+    newlyAssignedTasks: Array<{
+        id: string;
+        nodeId?: string;
+        sessionId?: string;
+    }>;
+    localIdleSessionsChecked: number;
+    remoteIdleSessionsChecked: number;
+    skippedSessions: Array<{
+        nodeId?: string;
+        sessionId?: string;
+        reason: string;
+        status?: string;
+    }>;
+    autoLaunchStarted: boolean;
+    noIdleMeshSessionAvailable?: boolean;
+}
+
+function countQueueStatus(meshId: string, status: 'pending' | 'assigned'): number {
+    return getQueue(meshId, { status: [status] as any }).length;
+}
+
+function getQueueStatusById(meshId: string): Map<string, string> {
+    return new Map(getQueue(meshId).map(task => [task.id, task.status]));
+}
+
 /**
  * Triggers a queue check for all nodes in the mesh.
  * Called when a new task is enqueued, in case nodes are already idle.
  */
-export async function triggerMeshQueue(components: DaemonComponents, meshId: string): Promise<void> {
+export async function triggerMeshQueue(components: DaemonComponents, meshId: string): Promise<MeshQueueTriggerResult> {
     const mesh = getMeshWithCache(components, meshId);
-    if (!mesh) return;
+    const pendingBefore = countQueueStatus(meshId, 'pending');
+    const assignedBefore = countQueueStatus(meshId, 'assigned');
+    const beforeStatus = getQueueStatusById(meshId);
+    const skippedSessions: MeshQueueTriggerResult['skippedSessions'] = [];
+    let localIdleSessionsChecked = 0;
+    let remoteIdleSessionsChecked = 0;
+    let autoLaunchStarted = false;
+    if (!mesh) {
+        return {
+            success: true,
+            meshId,
+            pendingBefore,
+            assignedBefore,
+            pendingAfter: pendingBefore,
+            assignedAfter: assignedBefore,
+            claimed: false,
+            newlyAssignedTasks: [],
+            localIdleSessionsChecked,
+            remoteIdleSessionsChecked,
+            skippedSessions: [{ reason: 'mesh_not_found' }],
+            autoLaunchStarted,
+            noIdleMeshSessionAvailable: true,
+        };
+    }
 
     // Find all CLI instances that belong to this mesh and are idle
     const cliInstances = components.instanceManager.getByCategory('cli');
@@ -1042,14 +1258,30 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
         // Only genuinely idle live sessions can pull work. Restored/stopped
         // records are kept for transcript/recovery visibility, but assigning
         // queue items to them strands tasks in assigned/pending without chat.
-        if (!isIdleSessionState(state)) continue;
+        if (!isIdleSessionState(state)) {
+            const status = readNonEmptyString(state.status).toLowerCase();
+            skippedSessions.push({
+                nodeId,
+                sessionId: readNonEmptyString(state.instanceId),
+                reason: isTerminalSessionStatus(status) ? 'terminal_session' : 'session_not_idle',
+                status: status || undefined,
+            });
+            continue;
+        }
 
         const sessionId = state.instanceId;
         const providerType = state.type || readNonEmptyString(settings.providerType);
         
         if (providerType) {
             // Try to assign a task to this idle node
+            localIdleSessionsChecked += 1;
             tryAssignQueueTask(components, meshId, nodeId, sessionId, providerType);
+        } else {
+            skippedSessions.push({
+                nodeId,
+                sessionId,
+                reason: 'provider_type_missing',
+            });
         }
     }
 
@@ -1058,6 +1290,7 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
         // Find if this node is in the same mesh
         const node = mesh.nodes.find((n: any) => n.id === idle.nodeId);
         if (node) {
+            remoteIdleSessionsChecked += 1;
             const assigned = tryAssignQueueTask(components, meshId, idle.nodeId, idle.sessionId, idle.providerType);
             if (assigned) {
                 remoteIdleSessions.delete(key);
@@ -1065,7 +1298,34 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
         }
     }
 
-    await maybeAutoLaunchOneQueueSession(components, meshId, mesh);
+    autoLaunchStarted = await maybeAutoLaunchOneQueueSession(components, meshId, mesh);
+    const afterQueue = getQueue(meshId);
+    const pendingAfter = afterQueue.filter(task => task.status === 'pending').length;
+    const assignedAfter = afterQueue.filter(task => task.status === 'assigned').length;
+    const newlyAssignedTasks = afterQueue
+        .filter(task => task.status === 'assigned' && beforeStatus.get(task.id) !== 'assigned')
+        .map(task => ({
+            id: task.id,
+            nodeId: task.assignedNodeId,
+            sessionId: task.assignedSessionId,
+        }));
+    return {
+        success: true,
+        meshId,
+        pendingBefore,
+        assignedBefore,
+        pendingAfter,
+        assignedAfter,
+        claimed: newlyAssignedTasks.length > 0,
+        newlyAssignedTasks,
+        localIdleSessionsChecked,
+        remoteIdleSessionsChecked,
+        skippedSessions,
+        autoLaunchStarted,
+        ...(pendingAfter > 0 && newlyAssignedTasks.length === 0 && localIdleSessionsChecked === 0 && remoteIdleSessionsChecked === 0 && !autoLaunchStarted
+            ? { noIdleMeshSessionAvailable: true }
+            : {}),
+    };
 }
 
 async function maybeAutoFastForwardIdleNode(components: DaemonComponents, args: {

package/src/mesh/mesh-work-queue.ts

@@ -372,6 +372,10 @@ export function __clearMeshQueueForTests(meshId: string): void {
     BeadsDB.getInstance().deleteQueue(meshId);
 }
 
+export function __clearDirectDispatchesForTests(meshId: string): void {
+    BeadsDB.getInstance().deleteDirectDispatches(meshId);
+}
+
 export function __resetBeadsDBForTests(): void {
     BeadsDB.resetForTests();
 }

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

@@ -64,6 +64,7 @@ function getMessageTime(message: unknown): number {
 type CompletedFinalizationBlock = {
     reason: string;
     terminal?: boolean;
+    allowTimeout?: boolean;
 };
 
 type CompletionFinalAssistantEvidence = {
@@ -613,7 +614,12 @@ export class CliProviderInstance implements ProviderInstance {
         if (suppressFreshLaunchStartupReplay) {
             parsedMessages = [];
         }
-        const activeChatId = this.providerSessionId || runtime?.runtimeId || this.instanceId;
+        // Adapter runtime metadata is transport-owned and is not guaranteed to
+        // identify this conversation. Spec adapters historically exposed the
+        // provider spec id (for example "codex-cli") as runtimeId, which made
+        // concurrent sessions share one activeChat identity until their native
+        // provider session ids were discovered.
+        const activeChatId = this.providerSessionId || this.instanceId;
         const historyMessageCount = Number.isFinite(parsedStatus?.historyMessageCount)
             ? Math.max(0, Number(parsedStatus.historyMessageCount))
             : null;
@@ -1164,6 +1170,7 @@ export class CliProviderInstance implements ProviderInstance {
         if (parsed?.activeModal || parsed?.modal) return { reason: 'parsed_modal_active', terminal: true };
         const adapterOwnsMessagesElsewhere = (this.adapter as any)?.chatMessagesOwnedExternally === true;
         const finalAssistantEvidence = this.completionFinalAssistantEvidence(parsed?.messages);
+        const allowMissingAssistantTimeout = !!(this.settings.meshNodeFor || this.settings.meshActiveTaskId || this.settings.launchedByCoordinator);
         if (!finalAssistantEvidence.present) {
             if (adapterOwnsMessagesElsewhere) {
                 if (finalAssistantEvidence.source === 'external-native') {
@@ -1172,19 +1179,20 @@ export class CliProviderInstance implements ProviderInstance {
                         LOG.info('CLI', `[${this.type}] external transcript probe: msgCount=${probe.msgCount} lastRole=${probe.lastRole || 'none'} lastKind=${probe.lastKind || 'none'} contentLen=${probe.contentLen} sourceMtime=${probe.sourceMtimeMs ?? 'unknown'} mtimeAge=${probe.mtimeAgeMs ?? 'unknown'}ms`);
                         pending.loggedTranscriptProbe = true;
                     }
-                    return { reason: 'missing_final_assistant', terminal: true };
+                    return { reason: 'missing_final_assistant', terminal: true, allowTimeout: allowMissingAssistantTimeout };
                 }
                 // SpecCliAdapter never populates parsed.messages — chat history flows
                 // through the daemon's native-history pipeline, not the status hook.
                 // If that pipeline is unavailable, keep the old skip behavior for
                 // providers that have not opted into strict final-assistant evidence.
                 if ((this.provider as any).requiresFinalAssistantBeforeIdle === true) {
-                    return { reason: 'missing_final_assistant', terminal: true };
+                    return { reason: 'missing_final_assistant', terminal: true, allowTimeout: allowMissingAssistantTimeout };
                 }
             } else {
                 return {
                     reason: 'missing_final_assistant',
                     terminal: (this.provider as any).requiresFinalAssistantBeforeIdle === true,
+                    allowTimeout: allowMissingAssistantTimeout,
                 };
             }
         }
@@ -1234,7 +1242,7 @@ export class CliProviderInstance implements ProviderInstance {
         if (block) {
             const blockReason = block.reason;
             const waitedMs = Date.now() - pending.firstObservedAt;
-            if (block.terminal || waitedMs < COMPLETED_FINALIZATION_MAX_WAIT_MS) {
+            if ((block.terminal && !block.allowTimeout) || waitedMs < COMPLETED_FINALIZATION_MAX_WAIT_MS) {
                 if (pending.loggedBlockReason !== blockReason) {
                     LOG.info('CLI', `[${this.type}] waiting to emit completed until transcript finalizes (${blockReason})`);
                     pending.loggedBlockReason = blockReason;

package/src/providers/contracts.ts

@@ -390,7 +390,7 @@ export interface ProviderMeshCoordinatorConfig {
     requiresRestart?: boolean;
     /** User-facing setup explanation for manual modes. */
     instructions?: string;
-    /** Copyable setup template. Supports {{meshId}}, {{adhdevMcpCommand}}, {{workspace}}, {{serverName}}. */
+    /** Copyable setup template. Supports {{meshId}}, {{adhdevMcpCommand}}, {{adhdevMcpArgs}}, {{workspace}}, {{serverName}}. */
     template?: string;
   };
   /**

package/src/providers/native-history/dispatcher.ts

@@ -27,6 +27,7 @@ export interface NativeHistoryInput {
     providerSessionId?: string;
     historySessionId?: string;
     workspace?: string;
+    sessionStartedAtMs?: number;
     format?: string;
     watchPath?: string;
     forceRefresh?: boolean;
@@ -34,7 +35,7 @@ export interface NativeHistoryInput {
 }
 
 export interface NativeHistoryResult {
-    messages: Array<{ role: string; content: string; receivedAt?: number; kind?: string }>;
+    messages: Array<{ role: string; content: string; receivedAt?: number; kind?: string; workspace?: string }>;
     providerSessionId?: string;
     sourcePath: string;
     sourceMtimeMs: number;
@@ -53,7 +54,12 @@ export function createNativeHistoryDispatcher(reader: ReaderId): (input: NativeH
         // shows up before I type anything" on every provider).
         const requestedProviderSid = input.providerSessionId || '';
 
-        const sourcePath = resolveSourcePath(reader, workspace, sessionId);
+        const sessionStartedAtMs = typeof input.sessionStartedAtMs === 'number'
+            ? input.sessionStartedAtMs
+            : typeof input.args?.sessionStartedAtMs === 'number'
+                ? input.args.sessionStartedAtMs
+                : 0;
+        const sourcePath = resolveSourcePath(reader, workspace, sessionId, sessionStartedAtMs);
         if (!sourcePath) return null;
         if (input.forceRefresh === true || input.args?.forceRefresh === true) {
             try { fs.statSync(sourcePath); } catch { /* best-effort metadata refresh */ }
@@ -72,6 +78,7 @@ export function createNativeHistoryDispatcher(reader: ReaderId): (input: NativeH
                 content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
                 receivedAt: typeof m.receivedAt === 'number' ? m.receivedAt : Date.parse(m.timestamp || '') || Date.now(),
                 kind: typeof m.kind === 'string' ? m.kind : 'standard',
+                workspace: typeof m.workspace === 'string' ? m.workspace : workspace || undefined,
             })),
             providerSessionId: session.providerSessionId,
             sourcePath: session.sourcePath,
@@ -85,10 +92,10 @@ export function createNativeHistoryDispatcher(reader: ReaderId): (input: NativeH
 // Per-provider path resolution
 // ────────────────────────────────────────────────────────────────────────────
 
-function resolveSourcePath(reader: ReaderId, workspace: string, sessionId: string): string | null {
+function resolveSourcePath(reader: ReaderId, workspace: string, sessionId: string, sessionStartedAtMs: number): string | null {
     switch (reader) {
         case 'claude-cli':   return resolveClaudePath(workspace, sessionId);
-        case 'codex-cli':    return resolveCodexPath(workspace);
+        case 'codex-cli':    return resolveCodexPath(workspace, sessionId, sessionStartedAtMs);
         case 'antigravity-cli': return resolveAntigravityPath(workspace);
         case 'hermes-cli':   return resolveHermesPath(workspace, sessionId);
     }
@@ -112,21 +119,111 @@ function resolveClaudePath(workspace: string, sessionId: string): string | null
     return null;
 }
 
-function resolveCodexPath(workspace: string): string | null {
-    void workspace;
+function resolveCodexPath(workspace: string, sessionId: string, sessionStartedAtMs: number): string | null {
     // codex stores by UTC date: ~/.codex/sessions/<year>/<month>/<day>/<file>.jsonl
-    const now = new Date();
-    const dir = path.join(
-        os.homedir(), '.codex', 'sessions',
-        String(now.getUTCFullYear()),
-        String(now.getUTCMonth() + 1).padStart(2, '0'),
-        String(now.getUTCDate()).padStart(2, '0'),
-    );
-    if (fs.existsSync(dir)) {
-        const f = newestRecentFile(dir, /\.jsonl$/);
-        if (f) return f;
+    const root = codexSessionsRoot();
+    if (sessionId && isUuidLikeSessionId(sessionId)) {
+        return findCodexPathBySessionId(root, sessionId);
     }
-    return null;
+    return findCodexPathByRuntime(root, workspace, sessionStartedAtMs);
+}
+
+function findCodexPathBySessionId(root: string, sessionId: string): string | null {
+    if (!fs.existsSync(root)) return null;
+    const needle = sessionId.toLowerCase();
+    const matches: Array<{ p: string; mtime: number }> = [];
+    const stack: string[] = [root];
+    while (stack.length > 0) {
+        const current = stack.pop()!;
+        let entries: fs.Dirent[] = [];
+        try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { continue; }
+        for (const entry of entries) {
+            const entryPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(entryPath);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+            if (!entry.name.toLowerCase().includes(needle)) continue;
+            if (!isSafeFilename(entry.name.replace('.jsonl', ''))) continue;
+            matches.push({ p: entryPath, mtime: safeMtime(entryPath) });
+        }
+    }
+    matches.sort((a, b) => b.mtime - a.mtime);
+    return matches[0]?.p ?? null;
+}
+
+const CODEX_SPAWN_BIND_GRACE_MS = 10_000;
+
+function findCodexPathByRuntime(root: string, workspace: string, sessionStartedAtMs: number): string | null {
+    if (!fs.existsSync(root) || !workspace) return null;
+    const workspaceResolved = resolveRealPath(workspace);
+    const cutoff = Date.now() - RECENT_WINDOW_MS;
+    const matches: Array<{ p: string; mtime: number; diff: number }> = [];
+    const stack: string[] = [root];
+
+    while (stack.length > 0) {
+        const current = stack.pop()!;
+        let entries: fs.Dirent[] = [];
+        try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { continue; }
+        for (const entry of entries) {
+            const entryPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(entryPath);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+            const mtime = safeMtime(entryPath);
+            if (mtime < cutoff) continue;
+            const meta = readCodexSessionMeta(entryPath);
+            if (!meta?.cwd || resolveRealPath(meta.cwd) !== workspaceResolved) continue;
+            const diff = sessionStartedAtMs > 0 && meta.timestampMs != null
+                ? Math.abs(meta.timestampMs - sessionStartedAtMs)
+                : 0;
+            if (sessionStartedAtMs > 0 && (meta.timestampMs == null || diff > CODEX_SPAWN_BIND_GRACE_MS)) continue;
+            matches.push({ p: entryPath, mtime, diff });
+        }
+    }
+
+    matches.sort((a, b) => sessionStartedAtMs > 0
+        ? a.diff - b.diff || b.mtime - a.mtime
+        : b.mtime - a.mtime);
+    return matches[0]?.p ?? null;
+}
+
+function readCodexSessionMeta(filePath: string): { cwd?: string; timestampMs?: number } | null {
+    try {
+        const fd = fs.openSync(filePath, 'r');
+        try {
+            const buffer = Buffer.alloc(8192);
+            const bytes = fs.readSync(fd, buffer, 0, buffer.length, 0);
+            if (bytes <= 0) return null;
+            const text = buffer.subarray(0, bytes).toString('utf8');
+            const firstLine = text.slice(0, text.indexOf('\n') >= 0 ? text.indexOf('\n') : text.length).trim();
+            if (!firstLine) return null;
+            const record = JSON.parse(firstLine) as Record<string, unknown>;
+            if (record.type !== 'session_meta' || !record.payload || typeof record.payload !== 'object') return null;
+            const payload = record.payload as Record<string, unknown>;
+            const timestampRaw = payload.timestamp;
+            const timestampMs = typeof timestampRaw === 'string'
+                ? Date.parse(timestampRaw)
+                : typeof timestampRaw === 'number'
+                    ? (timestampRaw < 1e12 ? timestampRaw * 1000 : timestampRaw)
+                    : NaN;
+            return {
+                cwd: typeof payload.cwd === 'string' ? payload.cwd : undefined,
+                timestampMs: Number.isFinite(timestampMs) ? timestampMs : undefined,
+            };
+        } finally {
+            fs.closeSync(fd);
+        }
+    } catch {
+        return null;
+    }
+}
+
+function resolveRealPath(value: string): string {
+    try { return fs.realpathSync(value); } catch { return value; }
 }
 
 function resolveAntigravityPath(workspace: string): string | null {
@@ -187,6 +284,18 @@ function cwdAsDashes(cwd: string): string {
     return cwd.replace(/\//g, '-');
 }
 
+function codexSessionsRoot(): string {
+    return path.join(os.homedir(), '.codex', 'sessions');
+}
+
+function isUuidLikeSessionId(sessionId: string): boolean {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId);
+}
+
+function isSafeFilename(name: string): boolean {
+    return /^[A-Za-z0-9._:-]+$/.test(name) && !name.includes('..');
+}
+
 function newestFile(dir: string, pattern: RegExp): string | null {
     try {
         const entries = fs.readdirSync(dir, { withFileTypes: true })

package/src/providers/provider-loader.ts

@@ -36,6 +36,9 @@ import {
 } from './external-sources.js';
 import type { ProviderSourceMode } from '../config/config.js';
 import type { ProviderSourceConfigSnapshot, ProviderUserDirSource } from '../config/provider-source-config.js';
+import { loadSpec } from './spec/loader.js';
+import { executeNativeHistory } from './spec/native-history-executor.js';
+import { createNativeHistoryDispatcher, type ReaderId } from './native-history/dispatcher.js';
 
 /**
  * Adds a provider-script root to the require whitelist. Wrapped in a
@@ -1244,8 +1247,6 @@ export class ProviderLoader {
           // Hand the resolved spec path off to route.ts via a hidden field
           // so the routing layer doesn't have to repeat the candidate walk.
           (resolved as any)._resolvedSpecPath = specPath;
-          // eslint-disable-next-line @typescript-eslint/no-var-requires
-          const { loadSpec } = require('./spec/loader.js');
           const r = loadSpec(specPath);
           // Stub each control_bar entry as a provider.scripts.<id>. The
           // upstream invoke_provider_script gate checks that the script
@@ -1274,8 +1275,6 @@ export class ProviderLoader {
             let format = 'spec';
 
             if (nh.source) {
-              // eslint-disable-next-line @typescript-eslint/no-var-requires
-              const { executeNativeHistory } = require('./spec/native-history-executor.js');
               format = `spec-${nh.source.kind}`;
               reader = (input: any) => executeNativeHistory(nh, input);
             } else if (nh.override_path) {
@@ -1294,9 +1293,7 @@ export class ProviderLoader {
                 } catch { /* fall through — leave native unavailable */ }
               }
             } else if (nh.reader) {
-              // eslint-disable-next-line @typescript-eslint/no-var-requires
-              const { createNativeHistoryDispatcher } = require('./native-history/dispatcher.js');
-              const dispatch = createNativeHistoryDispatcher(nh.reader);
+              const dispatch = createNativeHistoryDispatcher(nh.reader as ReaderId);
               format = nh.reader;
               reader = (input: any) => dispatch(input);
             }