@adhdev/daemon-core 0.9.82-rc.195 → 0.9.82-rc.196

package/src/mesh/{beads-db.ts → mesh-runtime-store.ts}

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, statSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'fs';
 import { dirname, join } from 'path';
 import { createRequire } from 'module';
 import { getLedgerDir } from './mesh-ledger.js';
@@ -26,8 +26,31 @@ function legacyQueuePath(meshId: string): string {
     return join(getLedgerDir(), `${safeMeshId(meshId)}.queue.json`);
 }
 
-export class BeadsDB {
-    private static instance: BeadsDB | undefined;
+function meshRuntimeStorePath(): string {
+    const dir = getLedgerDir();
+    const nextPath = join(dir, 'mesh-runtime.db');
+    if (existsSync(nextPath)) return nextPath;
+
+    const legacyPath = join(dir, 'beads.db');
+    if (!existsSync(legacyPath)) return nextPath;
+
+    try {
+        renameSync(legacyPath, nextPath);
+        for (const suffix of ['-wal', '-shm']) {
+            const legacyCompanion = `${legacyPath}${suffix}`;
+            if (existsSync(legacyCompanion)) {
+                renameSync(legacyCompanion, `${nextPath}${suffix}`);
+            }
+        }
+    } catch {
+        // Best-effort compatibility for existing installs. If migration fails,
+        // opening the new store will create a clean DB instead of blocking boot.
+    }
+    return nextPath;
+}
+
+export class MeshRuntimeStore {
+    private static instance: MeshRuntimeStore | undefined;
     private readonly db: DatabaseHandle;
     private readonly dbPath: string;
     private readonly migratedMeshIds = new Set<string>();
@@ -49,9 +72,9 @@ export class BeadsDB {
         this.migrate();
     }
 
-    static getInstance(): BeadsDB {
+    static getInstance(): MeshRuntimeStore {
         if (!this.instance) {
-            this.instance = new BeadsDB(join(getLedgerDir(), 'beads.db'));
+            this.instance = new MeshRuntimeStore(meshRuntimeStorePath());
         }
         return this.instance;
     }
@@ -149,13 +172,13 @@ export class BeadsDB {
     }
 
     private maybeCheckpointWal(): void {
-        if (++this.walWriteCounter < BeadsDB.WAL_CHECK_INTERVAL) return;
+        if (++this.walWriteCounter < MeshRuntimeStore.WAL_CHECK_INTERVAL) return;
         this.walWriteCounter = 0;
         try {
             const walPath = `${this.dbPath}-wal`;
             if (!existsSync(walPath)) return;
             const size = statSync(walPath).size;
-            if (size < BeadsDB.WAL_MAX_BYTES) return;
+            if (size < MeshRuntimeStore.WAL_MAX_BYTES) return;
             process.stderr.write(
                 `[adhdev-mesh] WAL file ${Math.round(size / 1024 / 1024)}MB exceeds threshold; forcing checkpoint\n`,
             );

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

@@ -1,7 +1,7 @@
 import { randomUUID } from 'crypto';
 import { requireMeshHostQueueOwner } from './mesh-host-ownership.js';
 import type { RepoMeshDaemonRole } from '../repo-mesh-types.js';
-import { BeadsDB } from './beads-db.js';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
 
 export type MeshTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed' | 'cancelled';
 export type MeshActiveTaskStatus = Extract<MeshTaskStatus, 'pending' | 'assigned'>;
@@ -145,15 +145,15 @@ export function nodeSatisfiesRequiredTags(requiredTags: unknown, capabilityTags:
 }
 
 function withQueueLock<T>(_meshId: string, fn: () => T): T {
-    return BeadsDB.getInstance().transaction(fn);
+    return MeshRuntimeStore.getInstance().transaction(fn);
 }
 
 function readQueue(meshId: string): MeshWorkQueueEntry[] {
-    return BeadsDB.getInstance().getQueueEntries(meshId);
+    return MeshRuntimeStore.getInstance().getQueueEntries(meshId);
 }
 
 function writeQueue(meshId: string, queue: MeshWorkQueueEntry[]): void {
-    BeadsDB.getInstance().replaceQueue(meshId, queue);
+    MeshRuntimeStore.getInstance().replaceQueue(meshId, queue);
 }
 
 /**
@@ -181,7 +181,7 @@ export function enqueueTask(
         createdAt: new Date().toISOString(),
         updatedAt: new Date().toISOString(),
     };
-    BeadsDB.getInstance().insertQueueEntry(entry);
+    MeshRuntimeStore.getInstance().insertQueueEntry(entry);
     return entry;
 }
 
@@ -189,18 +189,18 @@ export function enqueueTask(
  * Get all tasks in the queue, optionally filtered by status.
  */
 export function getQueue(meshId: string, opts?: { status?: MeshTaskStatus[] }): MeshWorkQueueEntry[] {
-    return BeadsDB.getInstance().getQueueEntries(meshId, opts?.status?.length ? opts.status : undefined);
+    return MeshRuntimeStore.getInstance().getQueueEntries(meshId, opts?.status?.length ? opts.status : undefined);
 }
 
 export function getMeshQueueRevision(meshId: string): string {
-    return BeadsDB.getInstance().getQueueRevision(meshId);
+    return MeshRuntimeStore.getInstance().getQueueRevision(meshId);
 }
 
 /**
  * Find the next pending task that this node is allowed to claim, and mark it as assigned.
  */
 export function claimNextTask(meshId: string, nodeId: string, sessionId: string, capabilityTags?: string[]): MeshWorkQueueEntry | null {
-    return BeadsDB.getInstance().claimNextQueueTask(meshId, nodeId, sessionId, capabilityTags);
+    return MeshRuntimeStore.getInstance().claimNextQueueTask(meshId, nodeId, sessionId, capabilityTags);
 }
 
 /**
@@ -215,10 +215,10 @@ export function updateTaskStatus(
 ): MeshWorkQueueEntry | null {
     requireMeshHostQueueOwner(opts);
     return withQueueLock(meshId, () => {
-        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        const entry = MeshRuntimeStore.getInstance().findQueueEntryById(meshId, taskId);
         if (!entry) return null;
         entry.status = status;
-        BeadsDB.getInstance().updateQueueEntry(entry);
+        MeshRuntimeStore.getInstance().updateQueueEntry(entry);
         return entry;
     });
 }
@@ -229,11 +229,11 @@ export function recordTaskAutoLaunch(
     autoLaunch: Omit<NonNullable<MeshWorkQueueEntry['autoLaunch']>, 'updatedAt'>,
 ): MeshWorkQueueEntry | null {
     return withQueueLock(meshId, () => {
-        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        const entry = MeshRuntimeStore.getInstance().findQueueEntryById(meshId, taskId);
         if (!entry) return null;
         const now = new Date().toISOString();
         entry.autoLaunch = { ...autoLaunch, updatedAt: now };
-        BeadsDB.getInstance().updateQueueEntry(entry);
+        MeshRuntimeStore.getInstance().updateQueueEntry(entry);
         return entry;
     });
 }
@@ -248,13 +248,13 @@ export function cancelTask(
 ): MeshWorkQueueEntry | null {
     requireMeshHostQueueOwner(opts);
     return withQueueLock(meshId, () => {
-        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        const entry = MeshRuntimeStore.getInstance().findQueueEntryById(meshId, taskId);
         if (!entry) return null;
         const now = new Date().toISOString();
         entry.status = 'cancelled';
         entry.cancelledAt = now;
         if (opts?.reason) entry.cancelReason = opts.reason;
-        BeadsDB.getInstance().updateQueueEntry(entry);
+        MeshRuntimeStore.getInstance().updateQueueEntry(entry);
         return entry;
     });
 }
@@ -276,7 +276,7 @@ export function requeueTask(
 ): MeshWorkQueueEntry | null {
     requireMeshHostQueueOwner(opts);
     return withQueueLock(meshId, () => {
-        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        const entry = MeshRuntimeStore.getInstance().findQueueEntryById(meshId, taskId);
         if (!entry) return null;
         entry.status = 'pending';
         delete entry.assignedNodeId;
@@ -290,7 +290,7 @@ export function requeueTask(
         entry.requeuedAt = new Date().toISOString();
         entry.requeueCount = (entry.requeueCount || 0) + 1;
         if (opts?.reason) entry.requeueReason = opts.reason;
-        BeadsDB.getInstance().updateQueueEntry(entry);
+        MeshRuntimeStore.getInstance().updateQueueEntry(entry);
         return entry;
     });
 }
@@ -306,10 +306,10 @@ export function updateSessionTaskStatus(
 ): MeshWorkQueueEntry | null {
     return withQueueLock(meshId, () => {
         const occurredAtIso = opts?.occurredAt ? new Date(opts.occurredAt).toISOString() : undefined;
-        const entry = BeadsDB.getInstance().findAssignedBySession(meshId, sessionId, occurredAtIso);
+        const entry = MeshRuntimeStore.getInstance().findAssignedBySession(meshId, sessionId, occurredAtIso);
         if (!entry) return null;
         entry.status = status;
-        BeadsDB.getInstance().updateQueueEntry(entry);
+        MeshRuntimeStore.getInstance().updateQueueEntry(entry);
         return entry;
     });
 }
@@ -339,7 +339,7 @@ export interface MeshWorkQueueStats {
  * Return aggregate queue statistics for the given mesh.
  */
 export function getMeshQueueStats(meshId: string): MeshWorkQueueStats {
-    const rows = BeadsDB.getInstance().getQueueStatsByStatus(meshId);
+    const rows = MeshRuntimeStore.getInstance().getQueueStatsByStatus(meshId);
     const counts: Record<string, number> = {};
     for (const r of rows) counts[r.status] = r.count;
     const pending = counts['pending'] ?? 0;
@@ -358,33 +358,33 @@ export function getMeshQueueStats(meshId: string): MeshWorkQueueStats {
         cancelled,
         activeCounts: { pending, assigned },
         historicalCounts: { completed, failed, cancelled },
-        activeAssignments: BeadsDB.getInstance().getActiveAssignmentDetails(meshId),
+        activeAssignments: MeshRuntimeStore.getInstance().getActiveAssignmentDetails(meshId),
     };
 }
 
 export function __replaceMeshQueueForTests(meshId: string, queue: MeshWorkQueueEntry[]): void {
-    BeadsDB.getInstance().transaction(() => {
-        BeadsDB.getInstance().replaceQueue(meshId, queue);
+    MeshRuntimeStore.getInstance().transaction(() => {
+        MeshRuntimeStore.getInstance().replaceQueue(meshId, queue);
     });
 }
 
 export function __clearMeshQueueForTests(meshId: string): void {
-    BeadsDB.getInstance().deleteQueue(meshId);
+    MeshRuntimeStore.getInstance().deleteQueue(meshId);
 }
 
 export function __clearDirectDispatchesForTests(meshId: string): void {
-    BeadsDB.getInstance().deleteDirectDispatches(meshId);
+    MeshRuntimeStore.getInstance().deleteDirectDispatches(meshId);
 }
 
-export function __resetBeadsDBForTests(): void {
-    BeadsDB.resetForTests();
+export function __resetMeshRuntimeStoreForTests(): void {
+    MeshRuntimeStore.resetForTests();
 }
 
 // ── Direct Dispatch Tracking ─────────────────────────────────────────────────
 // Persists direct (non-queue) task dispatches so buildMeshActiveWork can read
-// active work from BeadsDB instead of scanning ledger JSONL entries.
+// active work from MeshRuntimeStore instead of scanning ledger JSONL entries.
 
-export type DirectDispatchRecord = ReturnType<BeadsDB['getActiveDirectDispatches']>[number];
+export type DirectDispatchRecord = ReturnType<MeshRuntimeStore['getActiveDirectDispatches']>[number];
 
 export function insertDirectDispatch(
     meshId: string,
@@ -401,7 +401,7 @@ export function insertDirectDispatch(
     },
 ): void {
     try {
-        BeadsDB.getInstance().insertDirectDispatch({ ...data, meshId });
+        MeshRuntimeStore.getInstance().insertDirectDispatch({ ...data, meshId });
     } catch (e: any) {
         process.stderr.write(`[adhdev-mesh] insertDirectDispatch failed for task ${data.taskId}: ${e?.message || e}\n`);
     }
@@ -409,7 +409,7 @@ export function insertDirectDispatch(
 
 export function getActiveDirectDispatches(meshId: string): DirectDispatchRecord[] {
     try {
-        return BeadsDB.getInstance().getActiveDirectDispatches(meshId);
+        return MeshRuntimeStore.getInstance().getActiveDirectDispatches(meshId);
     } catch {
         return [];
     }
@@ -421,18 +421,18 @@ export function updateDirectDispatchStatus(
     status: 'acked' | 'completed' | 'failed' | 'stale',
 ): void {
     try {
-        BeadsDB.getInstance().updateDirectDispatchStatus(meshId, sessionId, status);
+        MeshRuntimeStore.getInstance().updateDirectDispatchStatus(meshId, sessionId, status);
     } catch { /* best-effort */ }
 }
 
 export function cleanupTerminalDirectDispatches(olderThanMs = 7 * 24 * 60 * 60_000): void {
     try {
-        BeadsDB.getInstance().cleanupTerminalDirectDispatches(olderThanMs);
+        MeshRuntimeStore.getInstance().cleanupTerminalDirectDispatches(olderThanMs);
     } catch { /* best-effort */ }
 }
 
 export function markStaleDirectDispatches(meshId: string, olderThanMs = 60 * 60_000): void {
     try {
-        BeadsDB.getInstance().markStaleDirectDispatches(meshId, olderThanMs);
+        MeshRuntimeStore.getInstance().markStaleDirectDispatches(meshId, olderThanMs);
     } catch { /* best-effort */ }
 }

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

@@ -724,16 +724,24 @@ export class CliProviderInstance implements ProviderInstance {
                 ? visibleStatus
                 : (suppressStaleParsedBusyStatus ? visibleStatus : (parsedChatStatus || visibleStatus)));
 
+        // If an AskUserQuestion prompt is awaiting user input, overlay status as
+        // waiting_choice. This is distinct from waiting_approval (tool-use consent)
+        // — the engine's isWaitingForResponse state is unchanged, so completion
+        // tracking continues normally once the user responds.
+        const hasInteractivePrompt = !!this.activeInteractivePrompt;
+        const finalStatus = hasInteractivePrompt ? 'waiting_choice' : visibleStatus;
+        const finalChatStatus = hasInteractivePrompt ? 'waiting_choice' : activeChatStatus;
+
         return {
             type: this.type,
             name: this.provider.name,
             category: 'cli',
-            status: visibleStatus,
+            status: finalStatus,
             mode: this.presentationMode,
             activeChat: {
                 id: activeChatId,
                 title: parsedStatus?.title || dirName,
-                status: activeChatStatus,
+                status: finalChatStatus,
                 messages: statusMessages,
                 activeModal: autoApproveActive ? null : (parsedStatus?.activeModal ?? adapterStatus.activeModal),
                 activeInteractivePrompt: this.activeInteractivePrompt,
@@ -1265,6 +1273,7 @@ export class CliProviderInstance implements ProviderInstance {
         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);
+        LOG.debug('CLI', `[${this.type}] finalAssistantEvidence: present=${finalAssistantEvidence.present} source=${finalAssistantEvidence.source} adapterOwnsMessagesElsewhere=${adapterOwnsMessagesElsewhere} parsedStatus=${parsedStatus}`);
         if (!finalAssistantEvidence.present) {
             if (adapterOwnsMessagesElsewhere) {
                 if (finalAssistantEvidence.source === 'external-native') {
@@ -1273,19 +1282,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;
                     }
+                    LOG.debug('CLI', `[${this.type}] external-native probe result: lastRole=${probe?.lastRole} contentLen=${probe?.contentLen}`);
+                    if (probe?.lastRole === 'assistant' && (probe.contentLen ?? 0) > 0) {
+                        return null;
+                    }
                     if (this.type === 'antigravity-cli') {
                         return null;
                     }
                     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, allowTimeout: allowMissingAssistantTimeout };
                 }
             } else {
+                LOG.debug('CLI', `[${this.type}] missing_final_assistant (not ownsExternal) requiresFinalAssistant=${!!(this.provider as any).requiresFinalAssistantBeforeIdle}`);
                 return {
                     reason: 'missing_final_assistant',
                     terminal: (this.provider as any).requiresFinalAssistantBeforeIdle === true,
@@ -1331,6 +1341,7 @@ export class CliProviderInstance implements ProviderInstance {
         const latestVisibleStatus = externalNativeFinal && isCliGeneratingLikeStatus(latestStatus.status)
             ? 'idle'
             : (latestAutoApproveActive ? 'generating' : latestStatus.status);
+        LOG.debug('CLI', `[${this.type}] flush attempt: adapterStatus=${latestStatus.status} latestVisible=${latestVisibleStatus} externalNativeFinal=${!!externalNativeFinal} generatingStartedAt=${this.generatingStartedAt} isWaitingForResponse=${!!(this.adapter as any)?.isWaitingForResponse} hasPartial=${!!this.adapter.getPartialResponse?.()}`);
         if (latestVisibleStatus !== 'idle') {
             LOG.info('CLI', `[${this.type}] cancelled pending completed (resumed ${latestVisibleStatus})`);
             this.completedDebouncePending = null;
@@ -1342,6 +1353,7 @@ export class CliProviderInstance implements ProviderInstance {
         if (block) {
             const blockReason = block.reason;
             const waitedMs = Date.now() - pending.firstObservedAt;
+            LOG.debug('CLI', `[${this.type}] finalization block: reason=${blockReason} terminal=${block.terminal} waitedMs=${waitedMs} maxWait=${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})`);
@@ -1485,10 +1497,18 @@ export class CliProviderInstance implements ProviderInstance {
         if (newStatus !== this.lastStatus) {
             LOG.info('CLI', `[${this.type}] status: ${this.lastStatus} → ${newStatus}`);
             if (this.lastStatus === 'idle' && newStatus === 'generating') {
+                // If a completion event is already pending and the turn has ended
+                // (generatingStartedAt===0), the PTY is painting its prompt area
+                // after completing. Ignore this blip — do not cancel the pending
+                // completion and do not advance lastStatus to generating.
+                if (this.completedDebouncePending && this.generatingStartedAt === 0) {
+                    LOG.debug('CLI', `[${this.type}] ignoring post-completion PTY generating blip (generatingStartedAt=0)`);
+                    return;
+                }
                 this.suppressIdleHistoryReplay = false;
                 // Cancel any pending completed event (multi-step: idle→generating resume)
                 if (this.completedDebouncePending) {
-                    LOG.info('CLI', `[${this.type}] cancelled pending completed (resumed generating)`);
+                    LOG.info('CLI', `[${this.type}] cancelled pending completed (resumed generating) generatingStartedAt=${this.generatingStartedAt} isWaitingForResponse=${!!(this.adapter as any)?.isWaitingForResponse}`);
                     if (this.completedDebounceTimer) { clearTimeout(this.completedDebounceTimer); this.completedDebounceTimer = null; }
                     this.completedDebouncePending = null;
                 }
@@ -1586,7 +1606,10 @@ export class CliProviderInstance implements ProviderInstance {
                         firstObservedAt: now,
                         previousStatus: this.lastStatus,
                     };
-                    this.scheduleCompletedDebounceFlush(3000);
+                    const ownsExternalHistory = !!(this.adapter as any)?.chatMessagesOwnedExternally;
+                    const flushDelay = ownsExternalHistory ? 0 : 3000;
+                    LOG.debug('CLI', `[${this.type}] set completedDebouncePending duration=${duration}s ownsExternalHistory=${ownsExternalHistory} flushDelay=${flushDelay}ms generatingStartedAt=${this.generatingStartedAt}`);
+                    this.scheduleCompletedDebounceFlush(flushDelay);
                 }
             } else if (newStatus === 'idle' && this.lastStatus === 'starting') {
                 this.pushEvent({ event: 'agent:ready', chatTitle, timestamp: now });

package/src/providers/provider-instance.ts

@@ -16,7 +16,7 @@ import type { InteractivePrompt } from './types/interactive-prompt.js';
 
 // ─── ProviderState — Discriminated union by category ─────────────
 
-export type ProviderStatus = 'idle' | 'generating' | 'waiting_approval' | 'error' | 'stopped' | 'starting';
+export type ProviderStatus = 'idle' | 'generating' | 'waiting_approval' | 'waiting_choice' | 'error' | 'stopped' | 'starting';
 
 export interface ProviderRuntimeWriteOwner {
     clientId: string;

package/src/providers/spec/driver.ts

@@ -41,6 +41,7 @@ import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
 import { evaluate, type SpecEvaluation, type TraceEntry } from './evaluator.js';
 import { loadSpec } from './loader.js';
 import type { CliSpec, Control, DelegateTrigger } from './types.js';
+import { LOG } from '../../logging/logger.js';
 
 export type DashboardEvent =
     | { kind: 'pty_data'; chunk: string }
@@ -148,10 +149,32 @@ export function matchesCompletionIdleRule(spec: CliSpec, ev: SpecEvaluation, scr
     }
 }
 
-export function matchesCompletionIdleTargetState(spec: CliSpec, ev: SpecEvaluation, screen: string): boolean {
+export function matchesCompletionIdleTargetState(
+    spec: CliSpec,
+    ev: SpecEvaluation,
+    screen: string,
+    cursor?: { row: number; col: number },
+): 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;
+    if (!target?.when) return false;
+
+    // Cursor-only idle: if the target state has cursor guards but no regex,
+    // treat a cursor match alone as sufficient.
+    const hasCursorGuard = target.when.cursor_row_min !== undefined
+        || target.when.cursor_row_max !== undefined
+        || target.when.cursor_col_min !== undefined
+        || target.when.cursor_col_max !== undefined;
+    if (hasCursorGuard && cursor !== undefined) {
+        const { cursor_row_min, cursor_row_max, cursor_col_min, cursor_col_max } = target.when;
+        const cursorOk = (cursor_row_min === undefined || cursor.row >= cursor_row_min)
+            && (cursor_row_max === undefined || cursor.row <= cursor_row_max)
+            && (cursor_col_min === undefined || cursor.col >= cursor_col_min)
+            && (cursor_col_max === undefined || cursor.col <= cursor_col_max);
+        if (cursorOk) return true;
+    }
+
+    if (!target.when.regex) return false;
     const haystack = target.when.section
         ? ev.sections.find(section => section.id === target.when.section)?.text ?? ''
         : screen;
@@ -314,6 +337,7 @@ export class SpecDriver {
         if (this.busyExpiryTimer) clearTimeout(this.busyExpiryTimer);
         this.busyExpiryTimer = setTimeout(() => {
             this.busyExpiryTimer = null;
+            LOG.debug('SpecDriver', `[${this.opts.specPath.split('/').slice(-3).join('/')}] busyExpiry fired holdMs=${holdMs}`);
             this.reevaluate();
         }, Math.max(holdMs + 50, 100));
     }
@@ -352,11 +376,18 @@ export class SpecDriver {
                 if (completionKey !== this.completionIdleKey) {
                     this.completionIdleKey = completionKey;
                     this.completionIdleFirstSeenAt = now;
+                    LOG.debug('SpecDriver', `[${this.opts.specPath.split('/').slice(-3).join('/')}] completion_idle_after matched: key="${completionKey}"`);
                 }
                 const holdMs = Math.max(0, completionIdleRule.hold_ms || 0);
+                const forceAfterMs = typeof completionIdleRule.force_after_ms === 'number'
+                    ? completionIdleRule.force_after_ms
+                    : null;
                 const ageMs = now - this.completionIdleFirstSeenAt;
                 if (ageMs >= holdMs) {
-                    if (matchesCompletionIdleTargetState(this.spec, ev, screen)) {
+                    const targetMatches = matchesCompletionIdleTargetState(this.spec, ev, screen, cursor);
+                    const forced = !targetMatches && forceAfterMs !== null && ageMs >= holdMs + forceAfterMs;
+                    LOG.debug('SpecDriver', `[${this.opts.specPath.split('/').slice(-3).join('/')}] completion_idle_after hold expired ageMs=${ageMs} targetState=${targetMatches} forced=${forced} screenTail="${screen.split(/\r?\n/).slice(-3).join('\\n').slice(-200)}"`);
+                    if (targetMatches || forced) {
                         const idle = this.spec.states.find(state => state.id === this.spec.default_state)
                             ?? this.spec.states.find(state => state.id === 'idle');
                         evState = idle

package/src/providers/spec/evaluator.ts

@@ -84,10 +84,39 @@ function resolveSections(spec: CliSpec, lines: string[]): ResolvedSection[] {
     for (const sec of spec.layout.sections) {
         let from = 0;
         let to = total;
-        if (sec.from_top !== undefined) {
+        if (sec.anchor_regex !== undefined) {
+            try {
+                const re = new RegExp(sec.anchor_regex, sec.anchor_flags ?? '');
+                const prevRe = sec.anchor_context?.prev !== undefined
+                    ? new RegExp(sec.anchor_context.prev, sec.anchor_context.prev_flags ?? '') : null;
+                const nextRe = sec.anchor_context?.next !== undefined
+                    ? new RegExp(sec.anchor_context.next, sec.anchor_context.next_flags ?? '') : null;
+                const matches = (i: number) => re.test(lines[i])
+                    && (prevRe === null || (i > 0 && prevRe.test(lines[i - 1])))
+                    && (nextRe === null || (i < total - 1 && nextRe.test(lines[i + 1])));
+                let idx = -1;
+                if (sec.anchor_last) {
+                    for (let i = total - 1; i >= 0; i--) { if (matches(i)) { idx = i; break; } }
+                } else {
+                    for (let i = 0; i < total; i++) { if (matches(i)) { idx = i; break; } }
+                }
+                if (idx !== -1) {
+                    from = idx;
+                    to = total;
+                    if (sec.until_regex !== undefined) {
+                        try {
+                            const ure = new RegExp(sec.until_regex, sec.until_regex_flags ?? '');
+                            const end = lines.findIndex((l, i) => i > idx && ure.test(l));
+                            if (end !== -1) to = end;
+                        } catch { /* bad until_regex — extend to end */ }
+                    } else if (sec.lines !== undefined) {
+                        to = Math.min(total, from + sec.lines);
+                    }
+                }
+            } catch { /* bad anchor_regex — fall through to defaults */ }
+        } else if (sec.from_top !== undefined) {
             from = resolveSize(sec.from_top, total);
-        }
-        if (sec.from_bottom !== undefined) {
+        } else if (sec.from_bottom !== undefined) {
             const sz = resolveSize(sec.from_bottom, total);
             from = total - sz;
             to = total;

package/src/providers/spec/schema.gen.ts

@@ -125,6 +125,9 @@ export const SCHEMA = {
             "type": "string",
             "minLength": 1
         },
+        "requiresFinalAssistantBeforeIdle": {
+            "type": "boolean"
+        },
         "debounce": {
             "type": "object",
             "additionalProperties": false,
@@ -139,7 +142,8 @@ export const SCHEMA = {
                         "section": { "type": "string", "minLength": 1 },
                         "regex": { "type": "string", "minLength": 1 },
                         "flags": { "type": "string" },
-                        "hold_ms": { "type": "integer", "minimum": 0 }
+                        "hold_ms": { "type": "integer", "minimum": 0 },
+                        "force_after_ms": { "type": "integer", "minimum": 0 }
                     }
                 }
             }
@@ -187,7 +191,23 @@ export const SCHEMA = {
                             "type": "string"
                         }
                     }
-                }
+                },
+                "anchor_regex": { "type": "string", "minLength": 1 },
+                "anchor_flags": { "type": "string" },
+                "anchor_last": { "type": "boolean" },
+                "anchor_context": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "prev": { "type": "string" },
+                        "prev_flags": { "type": "string" },
+                        "next": { "type": "string" },
+                        "next_flags": { "type": "string" }
+                    }
+                },
+                "lines": { "type": "integer", "minimum": 1 },
+                "until_regex": { "type": "string", "minLength": 1 },
+                "until_regex_flags": { "type": "string" }
             }
         },
         "sectionRegex": {

package/src/providers/spec/schema.json

@@ -61,6 +61,7 @@
         },
         "native_history": { "$ref": "#/definitions/nativeHistory" },
         "cli_version_range": { "type": "string", "minLength": 1 },
+        "requiresFinalAssistantBeforeIdle": { "type": "boolean" },
         "debounce": {
             "type": "object",
             "additionalProperties": false,

package/src/providers/spec/types.ts

@@ -13,6 +13,33 @@ export interface Section {
     from_top?: Size;
     from_bottom?: Size;
     until?: { section: string };
+    /** Scan the screen for the first (or last, if anchor_last=true) line
+     *  matching this regex and use that line as the section start.
+     *  Combine with `lines`, `until_regex`, or leave alone (defaults to
+     *  end-of-screen) to control how far it extends. */
+    anchor_regex?: string;
+    anchor_flags?: string;
+    /** If true, use the LAST matching line instead of the first. Useful
+     *  when the anchor pattern appears multiple times (e.g. separator
+     *  lines) and you want the one closest to the bottom. */
+    anchor_last?: boolean;
+    /** Optional neighbouring-line guards that must also match for the
+     *  anchor to be accepted. Reduces false positives when the anchor
+     *  pattern could appear elsewhere on screen (e.g. `>` in body text).
+     *  `prev` checks the line immediately above; `next` the line below. */
+    anchor_context?: {
+        prev?: string;
+        prev_flags?: string;
+        next?: string;
+        next_flags?: string;
+    };
+    /** When used with anchor_regex: take at most this many lines from the
+     *  anchor point. */
+    lines?: number;
+    /** When used with anchor_regex: extend until the first line matching
+     *  this regex (exclusive). Takes precedence over `lines`. */
+    until_regex?: string;
+    until_regex_flags?: string;
 }
 
 export interface SectionRegex {
@@ -224,6 +251,13 @@ export interface CliSpec {
     notifications?: NotificationRule[];
     delegate?: DelegateTrigger[];
     native_history?: NativeHistoryConfig;
+    /**
+     * When true, the daemon's completed-finalization gate will not emit
+     * `generating_completed` until native history confirms the last message
+     * role is `assistant`. Prevents PTY quiet-period from triggering idle
+     * before the CLI has finished writing its response to disk.
+     */
+    requiresFinalAssistantBeforeIdle?: boolean;
     /**
      * Per-spec debounce knobs. Defaults are conservative (busy_hold_ms
      * 6000) and live in SpecDriver. Spec authors override here when a
@@ -251,6 +285,11 @@ export interface CliSpec {
             regex: string;
             flags?: string;
             hold_ms: number;
+            /** If the target-state check still fails this many ms after hold_ms
+             *  expired, force an idle transition anyway. Guards against TUIs that
+             *  show transient UI (pickers, option lists) after the completion
+             *  marker appears, keeping the target-state regex from matching. */
+            force_after_ms?: number;
         };
     };
 }