@adhdev/daemon-core 0.9.77-rc.40 → 0.9.77-rc.42

package/dist/providers/cli-provider-instance.d.ts

@@ -100,6 +100,12 @@ export declare class CliProviderInstance implements ProviderInstance {
     private completedDebounceTimer;
     private completedDebouncePending;
     private enforceFreshSessionLaunchIfNeeded;
+    private completionHasFinalAssistantMessage;
+    private hasAdapterPendingResponse;
+    private shouldSuppressStaleParsedBusyStatus;
+    private getCompletedFinalizationBlockReason;
+    private scheduleCompletedDebounceFlush;
+    private flushCompletedDebounceIfFinalized;
     private maybeAutoApproveStatus;
     private detectStatusTransition;
     private pushEvent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.77-rc.40",
+  "version": "0.9.77-rc.42",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli-adapters/provider-cli-adapter.ts

@@ -225,7 +225,7 @@ export class ProviderCliAdapter implements CliAdapter {
         currentTurnScope: TurnParseScope | null;
         recentOutputBuffer: string;
         accumulatedBuffer: string;
-        accumulatedRawBuffer: string;
+        accumulatedRawBufferKey: string;
         screenText: string;
         currentStatus: CliSessionStatus['status'];
         activeModal: { message: string; buttons: string[] } | null;
@@ -300,15 +300,23 @@ export class ProviderCliAdapter implements CliAdapter {
         this.lastScreenSnapshotReadAt = Number.NEGATIVE_INFINITY;
     }
 
+    private getAccumulatedRawBufferCacheKey(): string {
+        return this.accumulatedRawBuffer
+            .replace(/\x1B\][^\x07]*(?:\x07|\x1B\\)/g, '')
+            .replace(/\x1B[P^_X][\s\S]*?(?:\x07|\x1B\\)/g, '')
+            .replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
+    }
+
     private getFreshParsedStatusCache(): any | null {
         const cached = this.parsedStatusCache;
+        const accumulatedRawBufferKey = this.getAccumulatedRawBufferCacheKey();
         if (
             cached
             && cached.responseBuffer === this.responseBuffer
             && cached.currentTurnScope === this.currentTurnScope
             && cached.recentOutputBuffer === this.recentOutputBuffer
             && cached.accumulatedBuffer === this.accumulatedBuffer
-            && cached.accumulatedRawBuffer === this.accumulatedRawBuffer
+            && cached.accumulatedRawBufferKey === accumulatedRawBufferKey
             && cached.screenText === this.lastScreenText
             && cached.currentStatus === this.currentStatus
             && cached.activeModal === this.activeModal
@@ -452,6 +460,7 @@ export class ProviderCliAdapter implements CliAdapter {
 
         // Scripts are required — loaded by ProviderLoader via compatibility array
         this.cliScripts = provider.scripts || {};
+        this.scriptState = typeof this.cliScripts.createState === 'function' ? (this.cliScripts.createState() ?? null) : null;
         const scriptNames = listCliScriptNames(this.cliScripts);
         if (scriptNames.length > 0) {
             LOG.info('CLI', `[${this.cliType}] CLI scripts: [${scriptNames.join(', ')}]`);
@@ -483,7 +492,7 @@ export class ProviderCliAdapter implements CliAdapter {
         this.parseErrorMessage = null;
         // Initialize per-session state: createState() is called once here and on script reload.
         // The returned object lives until the PTY exits (scriptState = null on exit).
-        this.scriptState = typeof scripts.createState === 'function' ? scripts.createState() : null;
+        this.scriptState = typeof scripts.createState === 'function' ? (scripts.createState() ?? null) : null;
         const scriptNames = listCliScriptNames(scripts);
         LOG.info('CLI', `[${this.cliType}] CLI scripts injected: [${scriptNames.join(', ')}]`);
     }
@@ -1589,13 +1598,14 @@ export class ProviderCliAdapter implements CliAdapter {
         const screenText = this.readTerminalScreenText();
         const parseScreenText = this.getParseScreenText(screenText);
         const cached = this.parsedStatusCache;
+        const accumulatedRawBufferKey = this.getAccumulatedRawBufferCacheKey();
         if (
             cached
             && cached.responseBuffer === this.responseBuffer
             && cached.currentTurnScope === this.currentTurnScope
             && cached.recentOutputBuffer === this.recentOutputBuffer
             && cached.accumulatedBuffer === this.accumulatedBuffer
-            && cached.accumulatedRawBuffer === this.accumulatedRawBuffer
+            && cached.accumulatedRawBufferKey === accumulatedRawBufferKey
             && cached.screenText === parseScreenText
             && cached.currentStatus === this.currentStatus
             && cached.activeModal === this.activeModal
@@ -1635,7 +1645,7 @@ export class ProviderCliAdapter implements CliAdapter {
             currentTurnScope: this.currentTurnScope,
             recentOutputBuffer: this.recentOutputBuffer,
             accumulatedBuffer: this.accumulatedBuffer,
-            accumulatedRawBuffer: this.accumulatedRawBuffer,
+            accumulatedRawBufferKey,
             screenText: parseScreenText,
             currentStatus: this.currentStatus,
             activeModal: this.activeModal,
@@ -1661,7 +1671,7 @@ export class ProviderCliAdapter implements CliAdapter {
             scope: this.currentTurnScope,
             runtimeSettings: this.runtimeSettings,
         });
-        return await Promise.resolve(fn(this.scriptState, {
+        return await Promise.resolve(this.invokeCliScript(fn, {
             ...input,
             args: args && typeof args === 'object' ? { ...args } : {},
         }));

package/src/commands/router.ts

@@ -154,6 +154,35 @@ function loadHermesCoordinatorBaseConfig(targetConfigPath: string): { config: Re
     return { config: baseConfig, sourceHome, sourceConfigPath };
 }
 
+function stripHermesCoordinatorTempModelProviderOverrides(config: Record<string, any>): Record<string, any> {
+    const {
+        model: _model,
+        provider: _provider,
+        default_model: _defaultModel,
+        defaultProvider: _defaultProvider,
+        default_provider: _defaultProviderSnake,
+        modelProvider: _modelProvider,
+        model_provider: _modelProviderSnake,
+        ...sanitized
+    } = config;
+    const delegation = sanitized.delegation;
+    if (delegation && typeof delegation === 'object' && !Array.isArray(delegation)) {
+        const {
+            model: _delegationModel,
+            provider: _delegationProvider,
+            modelProvider: _delegationModelProvider,
+            model_provider: _delegationModelProviderSnake,
+            ...delegationRest
+        } = delegation;
+        if (Object.keys(delegationRest).length > 0) {
+            sanitized.delegation = delegationRest;
+        } else {
+            delete sanitized.delegation;
+        }
+    }
+    return sanitized;
+}
+
 function copyHermesCoordinatorCredentialFiles(sourceHome: string, targetHome: string) {
     if (pathResolve(sourceHome) === pathResolve(targetHome)) return;
     for (const fileName of ['.env', 'auth.json']) {
@@ -388,6 +417,103 @@ export class DaemonCommandRouter {
         return false;
     }
 
+    private async cleanupLocalWorktreeNode(args: {
+        mesh: any;
+        node: any;
+        nodeId: string;
+    }): Promise<{ success: true; skipped?: boolean; removedPath?: string; repoRoot?: string; reason?: string } | { success: false; code: string; error: string; recoveryHint: string }> {
+        const workspace = typeof args.node?.workspace === 'string' ? args.node.workspace.trim() : '';
+        if (!workspace) {
+            return {
+                success: false,
+                code: 'mesh_worktree_cleanup_missing_workspace',
+                error: `Worktree node '${args.nodeId}' is missing workspace metadata`,
+                recoveryHint: 'Inspect the mesh node record before removing it, or remove stale metadata manually only after confirming no managed worktree remains.',
+            };
+        }
+
+        const worktreeExists = fs.existsSync(workspace);
+        const sourceNode = args.node?.clonedFromNodeId
+            ? args.mesh?.nodes?.find((n: any) => n.id === args.node.clonedFromNodeId || n.nodeId === args.node.clonedFromNodeId)
+            : args.mesh?.nodes?.find((n: any) => !n.isLocalWorktree);
+        const repoRoot = typeof sourceNode?.repoRoot === 'string' && sourceNode.repoRoot.trim()
+            ? sourceNode.repoRoot.trim()
+            : typeof sourceNode?.workspace === 'string' && sourceNode.workspace.trim()
+                ? sourceNode.workspace.trim()
+                : '';
+
+        if (!worktreeExists) {
+            return { success: true, skipped: true, removedPath: workspace, repoRoot: repoRoot || undefined, reason: 'worktree_path_missing' };
+        }
+        if (!repoRoot || !fs.existsSync(repoRoot)) {
+            return {
+                success: false,
+                code: 'mesh_worktree_cleanup_missing_source_repo',
+                error: `Refusing to remove worktree '${workspace}' because the source repo root is unavailable`,
+                recoveryHint: 'Run mesh_remove_node from the machine that owns the source repo, or verify the source node metadata before retrying.',
+            };
+        }
+        if (typeof args.node?.worktreeBranch !== 'string' || !args.node.worktreeBranch.trim()) {
+            return {
+                success: false,
+                code: 'mesh_worktree_cleanup_missing_branch',
+                error: `Refusing to remove worktree '${workspace}' because worktreeBranch metadata is missing`,
+                recoveryHint: 'Confirm this is an ADHDev-managed worktree before removing it manually; managed worktree nodes include worktreeBranch metadata.',
+            };
+        }
+
+        const { resolveWorktreePath, listWorktrees, removeWorktree } = await import('../git/git-worktree.js');
+        const normalizePath = (value: string) => {
+            const resolved = pathResolve(value);
+            try { return fs.realpathSync(resolved); } catch { return resolved; }
+        };
+        const expectedPath = normalizePath(resolveWorktreePath(repoRoot, String(args.mesh?.name || args.mesh?.id || 'mesh'), args.node.worktreeBranch));
+        const actualPath = normalizePath(workspace);
+        if (actualPath !== expectedPath) {
+            return {
+                success: false,
+                code: 'mesh_worktree_cleanup_unexpected_path',
+                error: `Refusing to remove worktree '${workspace}' because it is not at the expected managed path '${expectedPath}'`,
+                recoveryHint: 'Use git worktree list/status to inspect the path. Retry only after confirming the mesh node metadata points to an ADHDev-managed worktree.',
+            };
+        }
+
+        const entries = await listWorktrees(repoRoot);
+        const managedEntry = entries.find(entry => normalizePath(entry.path) === actualPath);
+        if (!managedEntry) {
+            return {
+                success: false,
+                code: 'mesh_worktree_cleanup_not_registered',
+                error: `Refusing to remove '${workspace}' because it is not registered in git worktree list for '${repoRoot}'`,
+                recoveryHint: 'Inspect git worktree list --porcelain from the source repo. If the path was already removed, prune git worktrees before retrying.',
+            };
+        }
+        if (managedEntry.branch && managedEntry.branch !== args.node.worktreeBranch) {
+            return {
+                success: false,
+                code: 'mesh_worktree_cleanup_branch_mismatch',
+                error: `Refusing to remove '${workspace}' because git reports branch '${managedEntry.branch}', expected '${args.node.worktreeBranch}'`,
+                recoveryHint: 'Inspect the worktree branch and mesh metadata before retrying cleanup.',
+            };
+        }
+
+        try {
+            const result = await removeWorktree(repoRoot, workspace, { requireClean: true });
+            return { success: true, removedPath: result.removedPath, repoRoot };
+        } catch (e: any) {
+            const message = String(e?.message || e || 'worktree cleanup failed');
+            const dirty = message.includes('dirty worktree') || message.includes('local changes');
+            return {
+                success: false,
+                code: dirty ? 'mesh_worktree_cleanup_dirty' : 'mesh_worktree_cleanup_failed',
+                error: message,
+                recoveryHint: dirty
+                    ? 'Commit, stash, or intentionally discard the worktree changes before retrying mesh_remove_node. The mesh registry entry is preserved until cleanup is safe.'
+                    : 'Inspect git worktree status/list from the source repo and retry after resolving the reported cleanup failure.',
+            };
+        }
+    }
+
     private isCompletedHostedSession(record: any): boolean {
         return record?.lifecycle === 'stopped' || record?.lifecycle === 'failed' || record?.lifecycle === 'interrupted';
     }
@@ -1537,21 +1663,21 @@ export class DaemonCommandRouter {
                         if (sessionCleanup.success === false) return { success: false, removed: false, sessionCleanup };
                     }
 
-                    // If this is a worktree node, clean up the git worktree first
-                    if (node?.isLocalWorktree && node.workspace) {
-                        try {
-                            const sourceNode = node.clonedFromNodeId
-                                ? mesh?.nodes.find((n: any) => n.id === node.clonedFromNodeId || n.nodeId === node.clonedFromNodeId)
-                                : mesh?.nodes.find((n: any) => !n.isLocalWorktree);
-                            const repoRoot = sourceNode?.repoRoot || sourceNode?.workspace;
-                            if (repoRoot) {
-                                const { removeWorktree } = await import('../git/git-worktree.js');
-                                await removeWorktree(repoRoot, node.workspace);
-                            }
-                        } catch (e: any) {
-                            LOG.warn('MeshNode', `Worktree cleanup failed for ${nodeId}: ${e.message}`);
-                            // Continue with node removal even if worktree cleanup fails
+                    let worktreeCleanup: Record<string, unknown> | undefined;
+                    if (node?.isLocalWorktree) {
+                        const cleanupResult = await this.cleanupLocalWorktreeNode({ mesh, node, nodeId });
+                        if (cleanupResult.success === false) {
+                            return {
+                                success: false,
+                                removed: false,
+                                code: cleanupResult.code,
+                                error: cleanupResult.error,
+                                recoveryHint: cleanupResult.recoveryHint,
+                                ...(sessionCleanup ? { sessionCleanup } : {}),
+                                worktreeCleanup: cleanupResult,
+                            };
                         }
+                        worktreeCleanup = cleanupResult;
                     }
 
                     let removed = false;
@@ -1580,7 +1706,7 @@ export class DaemonCommandRouter {
                         } catch { /* ledger append is best-effort */ }
                     }
 
-                    return { success: true, removed, ...(sessionCleanup ? { sessionCleanup } : {}) };
+                    return { success: true, removed, ...(sessionCleanup ? { sessionCleanup } : {}), ...(worktreeCleanup ? { worktreeCleanup } : {}) };
                 } catch (e: any) {
                     return { success: false, error: e.message };
                 }
@@ -1958,7 +2084,10 @@ export class DaemonCommandRouter {
                     if (hadExistingMcpConfig) {
                         try {
                             const parsedExistingMcpConfig = parseMeshCoordinatorMcpConfig(readFileSync(mcpConfigPath, 'utf-8'), configFormat);
-                            existingMcpConfig = { ...existingMcpConfig, ...parsedExistingMcpConfig };
+                            const existingCoordinatorConfig = hermesManualFallback
+                                ? stripHermesCoordinatorTempModelProviderOverrides(parsedExistingMcpConfig)
+                                : parsedExistingMcpConfig;
+                            existingMcpConfig = { ...existingMcpConfig, ...existingCoordinatorConfig };
                             copyFileSync(mcpConfigPath, mcpConfigPath + '.backup');
                         } catch (error: any) {
                             LOG.error('MeshCoordinator', `Failed to parse existing MCP config ${mcpConfigPath}: ${error?.message || error}`);

package/src/git/git-worktree.ts

@@ -49,6 +49,11 @@ export interface WorktreeEntry {
     bare: boolean;
 }
 
+export interface WorktreeRemoveOptions {
+    /** Refuse to remove a worktree with uncommitted or untracked changes. */
+    requireClean?: boolean;
+}
+
 export interface WorktreeRemoveResult {
     success: true;
     removedPath: string;
@@ -120,17 +125,30 @@ export async function createWorktree(opts: WorktreeCreateOptions): Promise<Workt
 /**
  * Remove a git worktree and clean up the directory.
  *
- * Runs: git worktree remove <worktreePath> --force
+ * Runs: git worktree remove <worktreePath>
  */
-export async function removeWorktree(repoRoot: string, worktreePath: string): Promise<WorktreeRemoveResult> {
+export async function removeWorktree(repoRoot: string, worktreePath: string, opts: WorktreeRemoveOptions = {}): Promise<WorktreeRemoveResult> {
     if (!existsSync(worktreePath)) {
         // Already gone — just prune
         await pruneWorktrees(repoRoot);
         return { success: true, removedPath: worktreePath };
     }
 
+    if (opts.requireClean) {
+        const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
+            cwd: worktreePath,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: GIT_MAX_BUFFER,
+            windowsHide: true,
+        });
+        if (stdout.trim()) {
+            throw new Error(`Refusing to remove dirty worktree: ${worktreePath}`);
+        }
+    }
+
     try {
-        await execFileAsync('git', ['worktree', 'remove', worktreePath, '--force'], {
+        await execFileAsync('git', ['worktree', 'remove', worktreePath], {
             cwd: repoRoot,
             encoding: 'utf8',
             timeout: GIT_TIMEOUT_MS,

package/src/mesh/coordinator-prompt.ts

@@ -138,6 +138,7 @@ const TOOLS_SECTION = `## Available Tools
 | \`mesh_checkpoint\` | Create a git checkpoint on a node |
 | \`mesh_approve\` | Approve/reject a pending agent action |
 | \`mesh_clone_node\` | Create a worktree node for isolated parallel branch work |
+| \`mesh_refine_node\` | Validate and merge a completed worktree node back into its base branch |
 | \`mesh_remove_node\` | Remove a node (cleans up worktree if applicable) |`;
 
 const TOOL_EXPOSURE_PREFLIGHT_SECTION = `## Tool Exposure Preflight
@@ -156,8 +157,9 @@ const WORKFLOW_SECTION = `## Orchestration Workflow
 4. **Monitor** — Prefer event-driven completion/status notifications. Do **not** poll \`mesh_read_chat\` repeatedly. Use \`mesh_view_queue\` to see the status of all pending, assigned, completed, and failed tasks. Do not call \`mesh_read_chat\` again within a few seconds for the same generating session. Use at most one compact \`mesh_read_chat\` check after a completion/approval signal. Handle approvals via \`mesh_approve\`.
 5. **Verify** — When a task reports completion or git work is visible, call \`mesh_git_status\` to verify changes were made.
 6. **Checkpoint** — Call \`mesh_checkpoint\` to save the work.
-7. **Clean up** — Remove worktree nodes via \`mesh_remove_node\` after their work is merged or no longer needed.
-8. **Report** — Summarize what was done, what changed, and any issues.
+7. **Converge branches** — Before marking any task complete, classify every touched node/branch into exactly one final state: \`merged_to_main\`, \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\`. Use \`mesh_status\` branchConvergenceSummary and \`mesh_refine_node\` for clean worktree branches when safe. A task that remains on a non-main branch is not fully complete unless the final report names the follow-up state and next step.
+8. **Clean up** — Remove worktree nodes via \`mesh_remove_node\` after their work is merged or no longer needed.
+9. **Report** — Summarize what was done, what changed, any issues, and the branch convergence state.
 
 ## Failure Recovery
 
@@ -191,5 +193,6 @@ function buildRulesSection(coordinatorCliType?: string): string {
 - **Respect node capabilities.** Don't send build tasks to read-only nodes. Don't push from nodes that aren't allowed to.
 - **Never fabricate tool results.** Always call the actual tool; never pretend you did.
 - **Clean up worktree nodes.** After a worktree task completes and its changes are merged or checkpointed, call \`mesh_remove_node\` to free resources.
+- **Do not strand completed branches.** A checkpointed or clean feature/worktree branch is not done by itself. Merge/refine it to the mesh default branch, or explicitly report one of \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\` with the next action.
 - **Name worktree branches meaningfully.** Use descriptive names like \`feat/auth-refactor\` or \`fix/build-123\`.${coordinatorNote}`;
 }

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

@@ -35,6 +35,17 @@ type PersistableCliHistoryMessage = {
     receivedAt?: number;
 };
 
+type CompletedDebouncePending = {
+    chatTitle: string;
+    duration: number;
+    timestamp: number;
+    firstObservedAt: number;
+    loggedBlockReason?: string;
+};
+
+const COMPLETED_FINALIZATION_RETRY_MS = 1000;
+const COMPLETED_FINALIZATION_MAX_WAIT_MS = 30_000;
+
 const IMAGE_MIME_EXTENSIONS: Record<string, string> = {
     'image/png': '.png',
     'image/jpeg': '.jpg',
@@ -103,6 +114,15 @@ function cleanupStaleMaterializedImages(dir: string): void {
     } catch { /* dir may not exist or be inaccessible */ }
 }
 
+function hasNonEmptyCliModalButtons(activeModal: unknown): boolean {
+    const buttons = (activeModal as any)?.buttons;
+    return Array.isArray(buttons) && buttons.some((button) => String(button || '').trim().length > 0);
+}
+
+function isCliGeneratingLikeStatus(status: unknown): boolean {
+    return status === 'generating' || status === 'streaming' || status === 'long_generating' || status === 'starting';
+}
+
 export function buildCliStructuredInputPrompt(
     input: InputEnvelope,
     options: { materializeDir?: string } = {},
@@ -511,6 +531,10 @@ export class CliProviderInstance implements ProviderInstance {
         const canonicalBackedHistory = this.syncCanonicalSavedHistoryIfNeeded();
 
         const dirName = this.workingDir.split('/').filter(Boolean).pop() || 'session';
+        const parsedChatStatus = typeof parsedStatus?.status === 'string' && parsedStatus.status.trim()
+            ? parsedStatus.status.trim()
+            : undefined;
+        const suppressStaleParsedBusyStatus = this.shouldSuppressStaleParsedBusyStatus(parsedStatus, adapterStatus);
 
         if (parsedMessages.length > 0) {
             const shouldSkipReplayPersist =
@@ -518,7 +542,7 @@ export class CliProviderInstance implements ProviderInstance {
                 && adapterStatus.status === 'idle'
                 && parsedStatus?.status === 'idle';
             let messagesToSave = parsedMessages;
-            if ((parsedStatus?.status === 'generating' || parsedStatus?.status === 'long_generating')) {
+            if (!suppressStaleParsedBusyStatus && (parsedChatStatus === 'generating' || parsedChatStatus === 'long_generating')) {
                 const lastIdx = messagesToSave.length - 1;
                 if (lastIdx >= 0 && messagesToSave[lastIdx]?.role === 'assistant') {
                     messagesToSave = messagesToSave.slice(0, lastIdx);
@@ -553,6 +577,13 @@ export class CliProviderInstance implements ProviderInstance {
             summaryMetadata: this.summaryMetadata as any,
             controlValues: this.controlValues,
         });
+        const activeChatStatus = parseErrorMessage
+            ? 'error'
+            : autoApproveActive && parsedStatus?.status === 'waiting_approval'
+            ? 'generating'
+            : (adapterStatus.status !== 'idle'
+                ? visibleStatus
+                : (suppressStaleParsedBusyStatus ? visibleStatus : (parsedChatStatus || visibleStatus)));
 
         return {
             type: this.type,
@@ -563,13 +594,7 @@ export class CliProviderInstance implements ProviderInstance {
             activeChat: {
                 id: `${this.type}_${this.workingDir}`,
                 title: parsedStatus?.title || dirName,
-                status: parseErrorMessage
-                    ? 'error'
-                    : autoApproveActive && parsedStatus?.status === 'waiting_approval'
-                    ? 'generating'
-                    : (adapterStatus.status !== 'idle'
-                        ? visibleStatus
-                        : (parsedStatus?.status || visibleStatus)),
+                status: activeChatStatus,
                 messages: mergedMessages,
                 activeModal: autoApproveActive ? null : (parsedStatus?.activeModal ?? adapterStatus.activeModal),
                 inputContent: '',
@@ -680,7 +705,7 @@ export class CliProviderInstance implements ProviderInstance {
     }
 
     private completedDebounceTimer: NodeJS.Timeout | null = null;
-    private completedDebouncePending: { chatTitle: string; duration: number; timestamp: number } | null = null;
+    private completedDebouncePending: CompletedDebouncePending | null = null;
 
     private async enforceFreshSessionLaunchIfNeeded(): Promise<void> {
         const scriptName = getForcedNewSessionScriptName(this.provider, this.launchMode);
@@ -709,6 +734,119 @@ export class CliProviderInstance implements ProviderInstance {
         this.applyProviderResponse(parsed.payload, { phase: 'immediate' });
     }
 
+    private completionHasFinalAssistantMessage(messages: unknown): boolean {
+        const visibleMessages = (Array.isArray(messages) ? messages : [])
+            .filter((message: any) => isUserFacingChatMessage(message as ChatMessage));
+        const lastVisible = visibleMessages[visibleMessages.length - 1] as ChatMessage | undefined;
+        const role = typeof lastVisible?.role === 'string' ? lastVisible.role.trim().toLowerCase() : '';
+        const content = lastVisible ? flattenContent(lastVisible.content).trim() : '';
+        return role === 'assistant' && !!content;
+    }
+
+    private hasAdapterPendingResponse(): boolean {
+        const adapterAny = this.adapter as any;
+        if (adapterAny?.isWaitingForResponse === true) return true;
+        if (adapterAny?.currentTurnScope) return true;
+        try {
+            if (typeof this.adapter.isProcessing === 'function' && this.adapter.isProcessing()) return true;
+        } catch { /* defensive: status rendering must not fail because of adapter diagnostics */ }
+        try {
+            const partial = typeof this.adapter.getPartialResponse === 'function'
+                ? this.adapter.getPartialResponse()
+                : '';
+            if (typeof partial === 'string' && partial.trim()) return true;
+        } catch { /* defensive: missing partial means no pending response evidence */ }
+        return false;
+    }
+
+    private shouldSuppressStaleParsedBusyStatus(parsedStatus: any, adapterStatus: any): boolean {
+        const parsedRawStatus = typeof parsedStatus?.status === 'string' ? parsedStatus.status.trim() : '';
+        const adapterRawStatus = typeof adapterStatus?.status === 'string' ? adapterStatus.status.trim() : '';
+        if (!isCliGeneratingLikeStatus(parsedRawStatus)) return false;
+        if (adapterRawStatus !== 'idle') return false;
+        if (hasNonEmptyCliModalButtons(parsedStatus?.activeModal ?? parsedStatus?.modal)) return false;
+        return !this.hasAdapterPendingResponse();
+    }
+
+    private getCompletedFinalizationBlockReason(latestVisibleStatus: string): string | null {
+        if (latestVisibleStatus !== 'idle') return `status:${latestVisibleStatus}`;
+
+        const adapterAny = this.adapter as any;
+        if (adapterAny?.isWaitingForResponse === true) return 'adapter_waiting_for_response';
+        if (adapterAny?.currentTurnScope) return 'adapter_turn_scope_active';
+
+        const partial = typeof this.adapter.getPartialResponse === 'function'
+            ? this.adapter.getPartialResponse()
+            : '';
+        if (typeof partial === 'string' && partial.trim()) return 'partial_response_pending';
+
+        let parsed: any;
+        try {
+            parsed = this.adapter.getScriptParsedStatus();
+        } catch (error: any) {
+            return `parse_error:${error?.message || String(error)}`;
+        }
+
+        const parsedStatus = typeof parsed?.status === 'string' ? parsed.status : 'unknown';
+        if (parsedStatus !== 'idle') return `parsed_status:${parsedStatus}`;
+        if (parsed?.activeModal || parsed?.modal) return 'parsed_modal_active';
+        if (!this.completionHasFinalAssistantMessage(parsed?.messages)) return 'missing_final_assistant';
+
+        return null;
+    }
+
+    private scheduleCompletedDebounceFlush(delayMs: number): void {
+        if (this.completedDebounceTimer) clearTimeout(this.completedDebounceTimer);
+        this.completedDebounceTimer = setTimeout(() => this.flushCompletedDebounceIfFinalized(), delayMs);
+    }
+
+    private flushCompletedDebounceIfFinalized(): void {
+        const pending = this.completedDebouncePending;
+        if (!pending) {
+            this.completedDebounceTimer = null;
+            return;
+        }
+
+        const latestStatus = this.adapter.getStatus({ allowParse: false });
+        const latestAutoApproveActive = latestStatus.status === 'waiting_approval' && this.shouldAutoApprove();
+        const latestVisibleStatus = latestAutoApproveActive ? 'generating' : latestStatus.status;
+        if (latestVisibleStatus !== 'idle') {
+            LOG.info('CLI', `[${this.type}] cancelled pending completed (resumed ${latestVisibleStatus})`);
+            this.completedDebouncePending = null;
+            this.completedDebounceTimer = null;
+            return;
+        }
+
+        const blockReason = this.getCompletedFinalizationBlockReason(latestVisibleStatus);
+        if (blockReason) {
+            const waitedMs = Date.now() - pending.firstObservedAt;
+            if (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;
+                }
+                this.scheduleCompletedDebounceFlush(COMPLETED_FINALIZATION_RETRY_MS);
+                return;
+            }
+            LOG.warn('CLI', `[${this.type}] suppressed completed event after ${waitedMs}ms without finalized assistant turn (${blockReason})`);
+            this.completedDebouncePending = null;
+            this.completedDebounceTimer = null;
+            this.generatingStartedAt = 0;
+            return;
+        }
+
+        LOG.info('CLI', `[${this.type}] completed in ${pending.duration}s`);
+        this.pushEvent({
+            event: 'agent:generating_completed',
+            chatTitle: pending.chatTitle,
+            duration: pending.duration,
+            timestamp: pending.timestamp,
+        });
+        this.completedDebouncePending = null;
+        this.completedDebounceTimer = null;
+        this.generatingStartedAt = 0;
+    }
+
     private maybeAutoApproveStatus(adapterStatus: any, now = Date.now()): boolean {
         const autoApproveActive = adapterStatus?.status === 'waiting_approval' && this.shouldAutoApprove();
         // Guard re-entry: onStatusChange/getState can observe the same modal multiple
@@ -811,27 +949,10 @@ export class CliProviderInstance implements ProviderInstance {
                     this.generatingDebouncePending = null;
                     this.generatingStartedAt = 0;
                 } else {
-                    // Debounce completed — wait 3s, if still idle then emit
-                    if (this.completedDebounceTimer) clearTimeout(this.completedDebounceTimer);
-                    this.completedDebouncePending = { chatTitle, duration, timestamp: now };
-                    this.completedDebounceTimer = setTimeout(() => {
-                        if (this.completedDebouncePending) {
-                            const latestStatus = this.adapter.getStatus({ allowParse: false });
-                            const latestAutoApproveActive = latestStatus.status === 'waiting_approval' && this.shouldAutoApprove();
-                            const latestVisibleStatus = latestAutoApproveActive ? 'generating' : latestStatus.status;
-                            if (latestVisibleStatus !== 'idle') {
-                                LOG.info('CLI', `[${this.type}] cancelled pending completed (resumed ${latestVisibleStatus})`);
-                                this.completedDebouncePending = null;
-                                this.completedDebounceTimer = null;
-                                return;
-                            }
-                            LOG.info('CLI', `[${this.type}] completed in ${this.completedDebouncePending.duration}s`);
-                            this.pushEvent({ event: 'agent:generating_completed', ...this.completedDebouncePending });
-                            this.completedDebouncePending = null;
-                            this.generatingStartedAt = 0;
-                        }
-                        this.completedDebounceTimer = null;
-                    }, 3000);
+                    // Debounce completed, then require the rich transcript path that read_chat
+                    // uses to show an idle turn whose last user-facing message is assistant.
+                    this.completedDebouncePending = { chatTitle, duration, timestamp: now, firstObservedAt: now };
+                    this.scheduleCompletedDebounceFlush(3000);
                 }
             } else if (newStatus === 'idle' && this.lastStatus === 'starting') {
                 this.pushEvent({ event: 'agent:ready', chatTitle, timestamp: now });