@adhdev/daemon-core 0.9.82-rc.186 → 0.9.82-rc.188

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;
   };
   /**
@@ -403,8 +403,43 @@ export interface ProviderMeshCoordinatorConfig {
    * the CLI doesn't recognize).
    */
   systemPromptInjection?: MeshCoordinatorSystemPromptInjection;
+  /**
+   * How coordinator-launched worker sessions are isolated from coordinator-only
+   * MCP/tools/config. Provider-specific CLI quirks belong here, not in daemon
+   * launch code.
+   */
+  delegatedWorkerIsolation?: MeshCoordinatorDelegatedWorkerIsolation;
 }
 
+export interface MeshCoordinatorDelegatedWorkerIsolation {
+  /** Environment variables to unset for delegated worker sessions. */
+  env?: {
+    unset?: string[];
+  };
+  /** Spawn-argument rules applied before launching a delegated worker. */
+  args?: MeshCoordinatorDelegatedWorkerArgRule[];
+}
+
+export type MeshCoordinatorDelegatedWorkerArgRule =
+  | {
+      mode: 'empty_mcp_config';
+      /** CLI flag that points at an MCP config file, e.g. '--mcp-config'. */
+      flag: string;
+      /** Optional CLI flag that forces only the provided MCP config to be used. */
+      strictFlag?: string;
+    }
+  | {
+      mode: 'config_override';
+      /** CLI config flag, e.g. '-c' or '--config'. */
+      flag: string;
+      /** Config key to set for worker isolation. */
+      key: string;
+      /** Config value to set. */
+      value: string;
+      /** Optional broader key prefix used for duplicate detection. */
+      dedupeKey?: string;
+    };
+
 /**
  * Declarative description of how a CLI accepts a session-scoped system prompt.
  *

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);
             }

package/src/providers/provider-schema.ts

@@ -300,7 +300,11 @@ function validateMeshCoordinator(raw: unknown, errors: string[]): void {
     errors.push('meshCoordinator.reason must be a non-empty string when provided')
   }
 
-  const mcpConfig = meshCoordinator.mcpConfig
+  validateMeshCoordinatorMcpConfig(meshCoordinator.mcpConfig, errors)
+  validateMeshCoordinatorDelegatedWorkerIsolation(meshCoordinator.delegatedWorkerIsolation, errors)
+}
+
+function validateMeshCoordinatorMcpConfig(mcpConfig: unknown, errors: string[]): void {
   if (mcpConfig === undefined) return
   if (!mcpConfig || typeof mcpConfig !== 'object' || Array.isArray(mcpConfig)) {
     errors.push('meshCoordinator.mcpConfig must be an object')
@@ -348,6 +352,57 @@ function validateMeshCoordinator(raw: unknown, errors: string[]): void {
   }
 }
 
+function validateMeshCoordinatorDelegatedWorkerIsolation(raw: unknown, errors: string[]): void {
+  if (raw === undefined) return
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    errors.push('meshCoordinator.delegatedWorkerIsolation must be an object')
+    return
+  }
+  const isolation = raw as Record<string, unknown>
+  const env = isolation.env
+  if (env !== undefined) {
+    if (!env || typeof env !== 'object' || Array.isArray(env)) {
+      errors.push('meshCoordinator.delegatedWorkerIsolation.env must be an object')
+    } else {
+      const unset = (env as Record<string, unknown>).unset
+      if (unset !== undefined && (!Array.isArray(unset) || unset.some((key) => typeof key !== 'string' || !key.trim()))) {
+        errors.push('meshCoordinator.delegatedWorkerIsolation.env.unset must be an array of non-empty strings')
+      }
+    }
+  }
+  const args = isolation.args
+  if (args === undefined) return
+  if (!Array.isArray(args)) {
+    errors.push('meshCoordinator.delegatedWorkerIsolation.args must be an array')
+    return
+  }
+  for (const [index, rule] of args.entries()) {
+    const prefix = `meshCoordinator.delegatedWorkerIsolation.args[${index}]`
+    if (!rule || typeof rule !== 'object' || Array.isArray(rule)) {
+      errors.push(`${prefix} must be an object`)
+      continue
+    }
+    const item = rule as Record<string, unknown>
+    const mode = item.mode
+    if (mode !== 'empty_mcp_config' && mode !== 'config_override') {
+      errors.push(`${prefix}.mode must be one of: empty_mcp_config, config_override`)
+      continue
+    }
+    for (const key of mode === 'empty_mcp_config' ? ['flag'] : ['flag', 'key', 'value']) {
+      const value = item[key]
+      if (typeof value !== 'string' || !value.trim()) {
+        errors.push(`${prefix}.${key} must be a non-empty string`)
+      }
+    }
+    for (const key of ['strictFlag', 'dedupeKey']) {
+      const value = item[key]
+      if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
+        errors.push(`${prefix}.${key} must be a non-empty string when provided`)
+      }
+    }
+  }
+}
+
 function validateControl(control: ProviderControlDef, errors: string[]): void {
   if (!control || typeof control !== 'object') {
     errors.push('controls: each control must be an object')

package/src/providers/sdk/v1/schemas/cli/provider.schema.json

@@ -320,6 +320,52 @@
             { "type": "object", "additionalProperties": false, "required": ["mode", "name"],
               "properties": { "mode": { "const": "env_var" }, "name": { "type": "string" } } }
           ]
+        },
+        "delegatedWorkerIsolation": {
+          "description": "Provider-declared launch isolation for coordinator-spawned worker sessions. Keeps worker-only sessions from inheriting coordinator MCP/tools/config.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "env": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "unset": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 }
+                }
+              }
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["mode", "flag"],
+                    "properties": {
+                      "mode": { "const": "empty_mcp_config" },
+                      "flag": { "type": "string", "minLength": 1 },
+                      "strictFlag": { "type": "string", "minLength": 1 }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["mode", "flag", "key", "value"],
+                    "properties": {
+                      "mode": { "const": "config_override" },
+                      "flag": { "type": "string", "minLength": 1 },
+                      "key": { "type": "string", "minLength": 1 },
+                      "value": { "type": "string", "minLength": 1 },
+                      "dedupeKey": { "type": "string", "minLength": 1 }
+                    }
+                  }
+                ]
+              }
+            }
+          }
         }
       }
     },

package/src/providers/sdk/v1/types/common/index.ts

@@ -169,8 +169,27 @@ export interface McpConfigDef {
 export interface MeshCoordinatorDef {
   supported: boolean;
   mcpConfig?: McpConfigDef;
+  systemPromptInjection?: MeshCoordinatorSystemPromptInjectionDef;
+  delegatedWorkerIsolation?: MeshCoordinatorDelegatedWorkerIsolationDef;
 }
 
+export type MeshCoordinatorSystemPromptInjectionDef =
+  | { mode: 'cli_arg'; flag: string }
+  | { mode: 'config_override'; flag: string; template: string }
+  | { mode: 'context_file'; path: string; wrapper?: string }
+  | { mode: 'env_var'; name: string };
+
+export interface MeshCoordinatorDelegatedWorkerIsolationDef {
+  env?: {
+    unset?: ReadonlyArray<string>;
+  };
+  args?: ReadonlyArray<MeshCoordinatorDelegatedWorkerArgRuleDef>;
+}
+
+export type MeshCoordinatorDelegatedWorkerArgRuleDef =
+  | { mode: 'empty_mcp_config'; flag: string; strictFlag?: string }
+  | { mode: 'config_override'; flag: string; key: string; value: string; dedupeKey?: string };
+
 // ─── Compatibility ──────────────────────────────────────────────────────
 
 export interface CompatibilityEntryDef {

package/src/providers/spec/cli-adapter.ts

@@ -36,6 +36,14 @@ import {
     type InteractivePromptResponse,
 } from '../types/interactive-prompt.js';
 
+function stripAnsi(text: string): string {
+    // eslint-disable-next-line no-control-regex
+    return String(text || '')
+        .replace(/\x1B\][^\x07]*(?:\x07|\x1B\\)/g, '')
+        .replace(/\x1B[P^_X][\s\S]*?(?:\x07|\x1B\\)/g, '')
+        .replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
+}
+
 export class SpecCliAdapter implements CliAdapter {
     readonly cliType: string;
     readonly cliName: string;
@@ -129,15 +137,16 @@ export class SpecCliAdapter implements CliAdapter {
     }
 
     getStatus(): CliAdapterStatus {
-        if (this.exited) return { status: 'stopped', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt };
-        if (!this.spawned) return { status: 'starting', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt };
+        const sessionFields = this.providerSessionId ? { providerSessionId: this.providerSessionId } : {};
+        if (this.exited) return { status: 'stopped', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt, ...sessionFields };
+        if (!this.spawned) return { status: 'starting', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt, ...sessionFields };
 
         // Refresh native history lazily — the watch_path is cheap to stat,
         // but parsing a full session.jsonl every call would be wasteful.
         this.maybeRefreshNativeHistory();
 
         const state = this.latestState;
-        if (!state) return { status: 'starting', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt };
+        if (!state) return { status: 'starting', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt, ...sessionFields };
 
         const modal = this.latestModal;
         const lc = state.id.toLowerCase();
@@ -150,12 +159,13 @@ export class SpecCliAdapter implements CliAdapter {
                     buttons: modal.buttons.map(b => b.label),
                 },
                 activeInteractivePrompt: this.activeInteractivePrompt,
+                ...sessionFields,
             };
         }
         if (lc === 'busy' || lc === 'generating') {
-            return { status: 'generating', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt };
+            return { status: 'generating', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt, ...sessionFields };
         }
-        return { status: 'idle', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt };
+        return { status: 'idle', messages: [], activeModal: null, activeInteractivePrompt: this.activeInteractivePrompt, ...sessionFields };
     }
 
     private maybeRefreshNativeHistory(): void {
@@ -165,10 +175,13 @@ export class SpecCliAdapter implements CliAdapter {
     }
 
     getScriptParsedStatus(): unknown {
+        const providerSessionId = this.extractProviderSessionIdFromScreen();
+        if (providerSessionId) this.providerSessionId = providerSessionId;
         const status = this.getStatus();
         return {
             ...status,
             messages: this.readClaudeScreenAssistantMessages(),
+            ...(this.providerSessionId ? { providerSessionId: this.providerSessionId } : {}),
         };
     }
 
@@ -345,6 +358,7 @@ export class SpecCliAdapter implements CliAdapter {
             displayName: this.spec.name,
             spawnedAtMs: this.spawnedAtMs,
             spawnedEnv: this.spawnedEnv,
+            ...(this.providerSessionId ? { providerSessionId: this.providerSessionId } : {}),
         };
     }
     updateRuntimeMeta(meta?: Record<string, unknown>): void {
@@ -419,6 +433,19 @@ export class SpecCliAdapter implements CliAdapter {
         }
     }
 
+    private extractProviderSessionIdFromScreen(): string | undefined {
+        if (this.cliType !== 'codex-cli') return this.providerSessionId;
+        let screenText = '';
+        try {
+            screenText = this.driver.snapshot();
+        } catch {
+            return this.providerSessionId;
+        }
+        const clean = stripAnsi(screenText);
+        const match = clean.match(/(?:gpt-|o\d|codex-)[^\n·]*·[^\n·]*·\s*([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+        return match?.[1] || this.providerSessionId;
+    }
+
     private readClaudeScreenAssistantMessages(): ChatMessage[] {
         if (this.cliType !== 'claude-cli') return [];
         let screenText = '';

package/src/providers/spec/driver.ts

@@ -132,6 +132,37 @@ export function resolveSubmitDelayMs(specBeforeSubmit: number | undefined, text:
     return Math.max(spec, SUBMIT_DELAY_FLOOR_MS + linesBonus);
 }
 
+export function matchesCompletionIdleRule(spec: CliSpec, ev: SpecEvaluation, screen: string): string | null {
+    const rule = spec.debounce?.completion_idle_after;
+    if (!rule?.regex) return null;
+    const haystack = rule.section
+        ? ev.sections.find(section => section.id === rule.section)?.text ?? ''
+        : screen;
+    if (!haystack) return null;
+    try {
+        const regex = new RegExp(rule.regex, rule.flags || '');
+        const match = haystack.match(regex);
+        return match?.[0] || null;
+    } catch {
+        return null;
+    }
+}
+
+export function matchesCompletionIdleTargetState(spec: CliSpec, ev: SpecEvaluation, screen: string): boolean {
+    const target = spec.states.find(state => state.id === spec.default_state)
+        ?? spec.states.find(state => state.id === 'idle');
+    if (!target?.when?.regex) return false;
+    const haystack = target.when.section
+        ? ev.sections.find(section => section.id === target.when.section)?.text ?? ''
+        : screen;
+    if (!haystack) return false;
+    try {
+        return new RegExp(target.when.regex, target.when.flags || 'i').test(haystack);
+    } catch {
+        return false;
+    }
+}
+
 export class SpecDriver {
     private spec!: CliSpec;
     private adapter!: TerminalAdapter;
@@ -157,6 +188,8 @@ export class SpecDriver {
      *  because the evaluator already moved past busy by the time the hold
      *  kicks in. */
     private lastBusyState: SpecEvaluation['state'] | null = null;
+    private completionIdleFirstSeenAt = 0;
+    private completionIdleKey = '';
     /** Timer that re-runs evaluate() once the hold window expires. Needed
      *  because the PTY stops emitting once the agent finishes; without an
      *  explicit wake-up there's nothing to trigger the busy → idle
@@ -305,6 +338,40 @@ export class SpecDriver {
                 evState = this.lastBusyState ?? evState;
             }
         }
+        const completionIdleRule = this.spec.debounce?.completion_idle_after;
+        let busyWakeMs = busyHoldMs;
+        if (evState.id === 'busy' && completionIdleRule) {
+            const completionKey = matchesCompletionIdleRule(this.spec, ev, screen);
+            if (completionKey) {
+                const now = Date.now();
+                if (completionKey !== this.completionIdleKey) {
+                    this.completionIdleKey = completionKey;
+                    this.completionIdleFirstSeenAt = now;
+                }
+                const holdMs = Math.max(0, completionIdleRule.hold_ms || 0);
+                const ageMs = now - this.completionIdleFirstSeenAt;
+                if (ageMs >= holdMs) {
+                    if (matchesCompletionIdleTargetState(this.spec, ev, screen)) {
+                        const idle = this.spec.states.find(state => state.id === this.spec.default_state)
+                            ?? this.spec.states.find(state => state.id === 'idle');
+                        evState = idle
+                            ? { id: idle.id, label: idle.label, title: null }
+                            : { id: 'idle', label: 'Ready', title: null };
+                    } else {
+                        busyWakeMs = Math.min(busyWakeMs, 1000);
+                    }
+                } else {
+                    busyWakeMs = Math.min(busyWakeMs, Math.max(holdMs - ageMs, 0));
+                }
+            } else {
+                this.completionIdleKey = '';
+                this.completionIdleFirstSeenAt = 0;
+            }
+        } else if (evState.id !== 'busy') {
+            this.completionIdleKey = '';
+            this.completionIdleFirstSeenAt = 0;
+        }
+
         if (evState.id === 'busy') {
             this.lastBusyAt = Date.now();
             this.lastBusyState = evState;
@@ -313,7 +380,7 @@ export class SpecDriver {
             // footer settles), so without an explicit timer the driver
             // never wakes up to downshift to idle and the dashboard sees
             // status stuck at generating long after the turn ended.
-            this.scheduleBusyExpiry(busyHoldMs);
+            this.scheduleBusyExpiry(busyWakeMs);
         }
 
         const changed = forceEmit

package/src/providers/spec/evaluator.ts

@@ -231,8 +231,18 @@ export function evaluate(spec: CliSpec, screenText: string): SpecEvaluation {
     for (const st of spec.states) {
         const { matched, title } = matchState(st, sections, screenText, trace);
         if (!matched) continue;
+        const extractedModal = extractModal(st, sections, screenText, title, trace);
+        // If the state declares modal_buttons but extraction failed (button
+        // count below min_count, or text-was-mistaken-for-modal), do not
+        // promote the state. Otherwise we would surface a phantom approval
+        // built from arbitrary screen text — see claude-cli numbered-list
+        // false-positive on 2026-06-07.
+        if (st.modal_buttons && !extractedModal) {
+            trace.push({ kind: 'state_skip', text: `state[${st.id}] matched but modal_buttons extraction failed — not promoting` });
+            continue;
+        }
         activeState = { id: st.id, label: st.label, title };
-        modal = extractModal(st, sections, screenText, title, trace);
+        modal = extractedModal;
         break;
     }