@adhdev/daemon-core 0.9.82-rc.456 → 0.9.82-rc.458

package/src/mesh/mesh-fast-forward.ts

@@ -1,6 +1,7 @@
 import type { GitRepoStatus, GitSubmoduleStatus } from '../git/git-types.js';
 import { getGitRepoStatus } from '../git/git-status.js';
 import { GitCommandError, runGit } from '../git/git-executor.js';
+import { resolveSubmoduleDefaultBranch } from './worktree-bootstrap-config.js';
 
 export interface MeshFastForwardNodeArgs {
   nodeId?: string;
@@ -521,31 +522,43 @@ async function resolveSubmodulePushes(
       results.push({ ...base, code: 'submodule_status_incomplete' });
       continue;
     }
-    // Refresh the submodule's origin/main, then require it to be an ancestor of
+    // Generalize the submodule's default branch (F18): '.gitmodules' branch →
+    // local remote HEAD → remote-advertised HEAD → 'main'. On a main-default
+    // submodule this resolves to 'main', keeping every ref below byte-identical.
+    const remoteBranch = await resolveSubmoduleDefaultBranch({
+      submoduleRepoPath: repoPath,
+      superprojectWorkspace: status.repoRoot ?? status.workspace,
+      submodulePath: submodule.path,
+      timeoutMs,
+    });
+    base.remoteBranch = remoteBranch;
+    const remoteRef = `refs/remotes/origin/${remoteBranch}`;
+    const fetchRefspec = `refs/heads/${remoteBranch}:${remoteRef}`;
+    // Refresh the submodule's origin/<branch>, then require it to be an ancestor of
     // the gitlink commit (strict ff-only).
     try {
-      await runGit(repoPath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', 'refs/heads/main:refs/remotes/origin/main'], { timeoutMs: timeoutMs ?? 30_000 });
+      await runGit(repoPath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', fetchRefspec], { timeoutMs: timeoutMs ?? 30_000 });
     } catch (error) {
       results.push({ ...base, code: 'submodule_fetch_failed', error: formatGitError(error) });
       continue;
     }
     let alreadyReachable = false;
     try {
-      await runGit(repoPath, ['merge-base', '--is-ancestor', submodule.commit, 'refs/remotes/origin/main'], { timeoutMs: timeoutMs ?? 15_000 });
+      await runGit(repoPath, ['merge-base', '--is-ancestor', submodule.commit, remoteRef], { timeoutMs: timeoutMs ?? 15_000 });
       alreadyReachable = true;
-    } catch { /* not yet on origin/main — candidate for push */ }
+    } catch { /* not yet on origin/<branch> — candidate for push */ }
     if (alreadyReachable) {
       results.push({ ...base, pushed: false, skipped: true, code: 'submodule_already_reachable' });
       continue;
     }
-    // Strict ff-only: origin/main must be an ancestor of the commit we publish.
+    // Strict ff-only: origin/<branch> must be an ancestor of the commit we publish.
     try {
-      await runGit(repoPath, ['merge-base', '--is-ancestor', 'refs/remotes/origin/main', submodule.commit], { timeoutMs: timeoutMs ?? 15_000 });
+      await runGit(repoPath, ['merge-base', '--is-ancestor', remoteRef, submodule.commit], { timeoutMs: timeoutMs ?? 15_000 });
     } catch (error) {
       results.push({ ...base, pushed: false, skipped: false, code: 'submodule_non_fast_forward', error: formatGitError(error) });
       continue;
     }
-    const refspec = `${submodule.commit}:refs/heads/main`;
+    const refspec = `${submodule.commit}:refs/heads/${remoteBranch}`;
     if (!execute) {
       results.push({ ...base, pushed: false, skipped: false, code: 'submodule_push_available', refspec });
       continue;
@@ -553,8 +566,8 @@ async function resolveSubmodulePushes(
     try {
       await runGit(repoPath, ['push', 'origin', refspec], { timeoutMs: timeoutMs ?? 30_000 });
       // Verify reachability after the push.
-      await runGit(repoPath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', 'refs/heads/main:refs/remotes/origin/main'], { timeoutMs: timeoutMs ?? 30_000 });
-      await runGit(repoPath, ['merge-base', '--is-ancestor', submodule.commit, 'refs/remotes/origin/main'], { timeoutMs: timeoutMs ?? 15_000 });
+      await runGit(repoPath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', fetchRefspec], { timeoutMs: timeoutMs ?? 30_000 });
+      await runGit(repoPath, ['merge-base', '--is-ancestor', submodule.commit, remoteRef], { timeoutMs: timeoutMs ?? 15_000 });
       results.push({ ...base, pushed: true, skipped: false, code: 'submodule_pushed', refspec });
     } catch (error) {
       results.push({ ...base, pushed: false, skipped: false, code: 'submodule_push_failed', refspec, error: formatGitError(error) });

package/src/mesh/mesh-refine-gates.ts

@@ -16,7 +16,7 @@ import { getGitRepoStatus } from '../git/git-status.js';
 import * as yaml from 'js-yaml';
 import { loadMeshRefineConfig, resolveMeshRefineValidationPlan } from '../mesh/refine-config.js';
 import type { MeshRefineValidationCommandPlan } from '../mesh/refine-config.js';
-import { evaluateWorktreeBootstrapState, loadMeshWorktreeBootstrapConfig, runMeshWorktreeBootstrap } from '../mesh/worktree-bootstrap-config.js';
+import { evaluateWorktreeBootstrapState, loadMeshWorktreeBootstrapConfig, runMeshWorktreeBootstrap, resolveSubmoduleDefaultBranch } from '../mesh/worktree-bootstrap-config.js';
 import type { WorktreeBootstrapState } from '../mesh/worktree-bootstrap-config.js';
 import { basename as pathBasename, join as pathJoin, resolve as pathResolve } from 'path';
 import * as fs from 'fs';
@@ -1295,6 +1295,10 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                 commit: gitlink.commit,
                 reachable: false,
             };
+            // Resolved lazily once the submodule checkout/remote are confirmed; defaults
+            // to 'main' so error messages emitted before resolution stay byte-identical
+            // to the pre-generalization behavior on a main-default repo.
+            let submoduleDefaultBranch = 'main';
             try {
                 if (!fs.existsSync(submodulePath)) {
                     entry.error = `Submodule checkout missing at ${gitlink.path}`;
@@ -1350,9 +1354,18 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                         entries.push(entry);
                         continue;
                     }
-                    entry.remoteMainBranch = 'main';
+                    // Generalize the submodule's default branch (F18): '.gitmodules'
+                    // branch → local remote HEAD → remote-advertised HEAD → 'main'. On a
+                    // main-default submodule this resolves to 'main' and every ref target
+                    // below is byte-identical to the prior hardcoded path.
+                    submoduleDefaultBranch = await resolveSubmoduleDefaultBranch({
+                        submoduleRepoPath: submodulePath,
+                        superprojectWorkspace: repoRoot,
+                        submodulePath: gitlink.path,
+                    });
+                    entry.remoteMainBranch = submoduleDefaultBranch;
                     try {
-                        await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, 'main');
+                        await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, submoduleDefaultBranch);
                         entry.fetchedFromOrigin = true;
                         entry.remoteReachable = true;
                         entry.remoteMainReachable = true;
@@ -1362,17 +1375,17 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                         entry.remoteMainReachable = false;
                         entry.publishRequired = true;
                         const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
-                        entry.error = `Submodule remote main reachability check failed for origin/main: ${details}`;
+                        entry.error = `Submodule remote main reachability check failed for origin/${submoduleDefaultBranch}: ${details}`;
                         if (options.allowAutoPublishSubmoduleMainCommits === true && entry.localReachable === true) {
                             entry.autoPublishAllowed = true;
                             entry.autoPublishAttempted = true;
                             try {
-                                const publish = await publishCommitToRemoteMain(submodulePath, gitlink.commit, 'main');
+                                const publish = await publishCommitToRemoteMain(submodulePath, gitlink.commit, submoduleDefaultBranch);
                                 entry.autoPublishRefspec = publish.refspec;
                                 entry.publishStdout = truncateValidationOutput(publish.stdout);
                                 entry.publishStderr = truncateValidationOutput(publish.stderr);
                                 entry.autoPublishSucceeded = true;
-                                await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, 'main');
+                                await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, submoduleDefaultBranch);
                                 entry.fetchedFromOrigin = true;
                                 entry.remoteReachable = true;
                                 entry.remoteMainReachable = true;
@@ -1384,13 +1397,13 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                                 entry.autoPublishSucceeded = false;
                                 entry.autoPublishVerified = false;
                                 const publishDetails = truncateValidationOutput(publishError?.stderr || publishError?.message || String(publishError));
-                                entry.error = `Submodule auto-publish to origin/main failed or could not be verified: ${publishDetails}`;
+                                entry.error = `Submodule auto-publish to origin/${submoduleDefaultBranch} failed or could not be verified: ${publishDetails}`;
                             }
                         } else if (options.allowAutoPublishSubmoduleMainCommits === true) {
                             entry.autoPublishAllowed = true;
                             entry.autoPublishAttempted = false;
                             entry.autoPublishSkippedReason = entry.autoPublishSkippedReason
-                                || 'candidate commit is not reachable in the source checkout or worktree submodule, so Refinery cannot push it to origin/main';
+                                || `candidate commit is not reachable in the source checkout or worktree submodule, so Refinery cannot push it to origin/${submoduleDefaultBranch}`;
                         }
                     }
                 } catch (e: any) {
@@ -1398,7 +1411,7 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                     entry.remoteMainReachable = false;
                     entry.publishRequired = true;
                     const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
-                    entry.error = `Submodule remote main reachability check failed for origin/main: ${details}`;
+                    entry.error = `Submodule remote main reachability check failed for origin/${submoduleDefaultBranch}: ${details}`;
                 }
             } catch (e: any) {
                 entry.error = truncateValidationOutput(e?.message || String(e));

package/src/mesh/preview-freshness.ts

@@ -23,6 +23,46 @@ export interface PreviewFreshness {
 
 const PREVIEW_DEPLOY_RECORD = '.adhdev/preview-deploy.json';
 
+// Repo-relative driver scripts that indicate this repository actually ships the
+// preview-deploy pipeline. Presence of any one of these (or the deploy record,
+// or a `deploy:preview` npm script) means the private release-pipeline guidance
+// carried by buildPreviewFreshness is relevant here. In every other repo the
+// pipeline is not configured and the guidance must NOT leak (F15).
+const PREVIEW_PIPELINE_SCRIPTS = [
+    'scripts/preview-freshness.mjs',
+    'scripts/smoke-preview-web.mjs',
+    'scripts/deploy-preview-local.mjs',
+] as const;
+
+function hasDeployPreviewNpmScript(repoRoot: string): boolean {
+    const pkgPath = resolve(repoRoot, 'package.json');
+    if (!existsSync(pkgPath)) return false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, unknown> };
+        return typeof pkg?.scripts?.['deploy:preview'] === 'string';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Gate: does this repository actually configure the preview-deploy pipeline?
+ *
+ * The preview-freshness surface embeds this project's private release-pipeline
+ * instructions (`npm run deploy:preview`, smoke preview, …). Those are only
+ * meaningful in a repo that ships the pipeline. An external repo joined to a
+ * mesh must not have that guidance leak into its coordinator prompt, so this
+ * gate keeps the surface off unless a concrete pipeline artifact is present.
+ */
+export function isPreviewPipelineConfigured(repoRoot: string): boolean {
+    // Strongest signal: the repo has produced a preview-deploy record before.
+    if (existsSync(resolve(repoRoot, PREVIEW_DEPLOY_RECORD))) return true;
+    // Otherwise the pipeline's own driver scripts are enough.
+    if (PREVIEW_PIPELINE_SCRIPTS.some((rel) => existsSync(resolve(repoRoot, rel)))) return true;
+    // Or the `deploy:preview` npm script that fronts the pipeline.
+    return hasDeployPreviewNpmScript(repoRoot);
+}
+
 function runGit(repoRoot: string, args: readonly string[]): string {
     try {
         return execFileSync('git', args, {
@@ -86,7 +126,12 @@ function readCurrentMainCommit(repoRoot: string): Pick<PreviewFreshness, 'curren
     return { currentMainCommit: null, currentMainCommitSource: 'unknown' };
 }
 
-export function buildPreviewFreshness(repoRoot: string): PreviewFreshness {
+export function buildPreviewFreshness(repoRoot: string): PreviewFreshness | null {
+    // F15 gate: only surface preview-freshness (and its private pipeline
+    // guidance) in repos that actually configure the preview-deploy pipeline.
+    // Unconfigured repos return null so the caller omits the field entirely.
+    if (!isPreviewPipelineConfigured(repoRoot)) return null;
+
     const current = readCurrentMainCommit(repoRoot);
     const record = readRecord(repoRoot);
     const lastPreviewCommit = normalizeCommit(record?.lastPreviewCommit);

package/src/mesh/worktree-bootstrap-config.ts

@@ -69,7 +69,7 @@ export const WORKTREE_BOOTSTRAP_STALE_RUNNING_MS = 10 * 60 * 1000;
  * trailing slash stripped. Returns an empty set when there are no submodules or the
  * lookup fails — callers must then treat any change as dirty (conservative).
  */
-function getRegisteredSubmodulePaths(workspace: string): Set<string> {
+export function getRegisteredSubmodulePaths(workspace: string): Set<string> {
     const paths = new Set<string>();
     try {
         const out = execFileSync(
@@ -92,6 +92,136 @@ function getRegisteredSubmodulePaths(workspace: string): Set<string> {
     return paths;
 }
 
+/**
+ * Read each registered submodule's configured `branch` from `.gitmodules`, keyed
+ * by the submodule's normalized path (matching {@link getRegisteredSubmodulePaths}).
+ *
+ * `.gitmodules` stores `submodule.<name>.path` and (optionally)
+ * `submodule.<name>.branch`; this joins the two on `<name>`. The special branch
+ * value `.` ("track the superproject's branch") is deliberately OMITTED so callers
+ * fall through to remote-HEAD detection instead of treating `.` as a literal branch
+ * name. Returns an empty map when there are no submodules, no `.gitmodules`, or the
+ * lookup fails (conservative — callers then detect or fall back).
+ */
+export function getSubmoduleConfiguredBranches(workspace: string): Map<string, string> {
+    const branchesByPath = new Map<string, string>();
+    try {
+        const out = execFileSync(
+            resolveWin32Executable('git'),
+            ['config', '--file', '.gitmodules', '--list'],
+            { cwd: workspace, encoding: 'utf8', timeout: 10_000, windowsHide: true },
+        );
+        // Join `submodule.<name>.path` with `submodule.<name>.branch` on <name>.
+        const pathByName = new Map<string, string>();
+        const branchByName = new Map<string, string>();
+        for (const line of String(out).split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            const eq = trimmed.indexOf('=');
+            if (eq < 0) continue;
+            const key = trimmed.slice(0, eq);
+            const value = trimmed.slice(eq + 1).trim();
+            // key: submodule.<name>.<field>; <name> may itself contain dots, so match
+            // the leading `submodule.` and trailing `.<field>` and take the middle.
+            const match = /^submodule\.(.+)\.(path|branch)$/.exec(key);
+            if (!match) continue;
+            const name = match[1];
+            if (match[2] === 'path') {
+                const norm = value.replace(/\\/g, '/').replace(/\/+$/, '');
+                if (norm) pathByName.set(name, norm);
+            } else if (value) {
+                branchByName.set(name, value);
+            }
+        }
+        for (const [name, submodulePath] of pathByName) {
+            const branch = branchByName.get(name);
+            if (branch && branch !== '.') branchesByPath.set(submodulePath, branch);
+        }
+    } catch {
+        // No .gitmodules / git error → no configured branches.
+    }
+    return branchesByPath;
+}
+
+/** Fallback submodule branch when no configured/detected default can be resolved. */
+export const SUBMODULE_DEFAULT_BRANCH_FALLBACK = 'main';
+
+function isPlausibleBranchName(name: unknown): name is string {
+    return typeof name === 'string' && name.length > 0 && !/\s/.test(name) && name !== 'HEAD';
+}
+
+/**
+ * Resolve the default branch a submodule's commits are published to / checked for
+ * reachability against. Generalizes the previously hardcoded `main` so a submodule
+ * whose default branch is `master`/`trunk`/etc. is handled. Priority (each tier
+ * falls through to the next on miss/error):
+ *
+ *   1. `.gitmodules` `submodule.<name>.branch` (via {@link getSubmoduleConfiguredBranches};
+ *      `.` is ignored) — an explicit, local, zero-cost declaration.
+ *   2. the submodule checkout's LOCAL remote HEAD: `git symbolic-ref --short
+ *      refs/remotes/<remote>/HEAD` → strip the `<remote>/` prefix (no network).
+ *   3. the submodule remote's advertised HEAD: `git ls-remote --symref <remote> HEAD`
+ *      → `ref: refs/heads/<branch>` (one network round-trip).
+ *   4. fallback {@link SUBMODULE_DEFAULT_BRANCH_FALLBACK} (`'main'`).
+ *
+ * Because the final fallback is `'main'` and every earlier tier that resolves `'main'`
+ * yields the same string, a repo whose submodules default to `main` (the common case)
+ * produces byte-identical downstream fetch/merge-base/push ref targets — only a
+ * read-only resolution probe is added.
+ */
+export async function resolveSubmoduleDefaultBranch(opts: {
+    /** The submodule's local checkout — cwd for symbolic-ref / ls-remote. */
+    submoduleRepoPath: string;
+    /** The superproject workspace — for the `.gitmodules` branch lookup (tier 1). */
+    superprojectWorkspace?: string;
+    /** The submodule's path relative to the superproject (key into `.gitmodules`). */
+    submodulePath?: string;
+    /** Remote name (default `origin`). */
+    remote?: string;
+    /** Timeout for the local probe (tier 2); the network probe (tier 3) gets max(this, 30s). */
+    timeoutMs?: number;
+}): Promise<string> {
+    const remote = opts.remote?.trim() || 'origin';
+    const localTimeout = opts.timeoutMs ?? 10_000;
+    const git = resolveWin32Executable('git');
+    const execFileAsync = promisify(execFile);
+
+    // Tier 1: .gitmodules configured branch (local, zero-cost).
+    if (opts.superprojectWorkspace && opts.submodulePath) {
+        try {
+            const normalized = opts.submodulePath.replace(/\\/g, '/').replace(/\/+$/, '');
+            const configured = getSubmoduleConfiguredBranches(opts.superprojectWorkspace).get(normalized);
+            if (isPlausibleBranchName(configured)) return configured;
+        } catch { /* fall through */ }
+    }
+
+    // Tier 2: the local remote HEAD (no network) — set by clone/`git remote set-head`.
+    try {
+        const { stdout } = await execFileAsync(
+            git,
+            ['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`],
+            { cwd: opts.submoduleRepoPath, encoding: 'utf8', timeout: localTimeout, windowsHide: true },
+        );
+        const short = String(stdout || '').trim();
+        const prefix = `${remote}/`;
+        const branch = short.startsWith(prefix) ? short.slice(prefix.length) : short;
+        if (isPlausibleBranchName(branch)) return branch;
+    } catch { /* fall through */ }
+
+    // Tier 3: the remote's advertised HEAD (one network round-trip).
+    try {
+        const { stdout } = await execFileAsync(
+            git,
+            ['ls-remote', '--symref', remote, 'HEAD'],
+            { cwd: opts.submoduleRepoPath, encoding: 'utf8', timeout: Math.max(localTimeout, 30_000), windowsHide: true },
+        );
+        const match = /^ref:\s+refs\/heads\/(\S+)\s+HEAD/m.exec(String(stdout || ''));
+        if (match && isPlausibleBranchName(match[1])) return match[1];
+    } catch { /* fall through */ }
+
+    return SUBMODULE_DEFAULT_BRANCH_FALLBACK;
+}
+
 /**
  * True when `git status --porcelain` output represents a worktree that is clean
  * EXCEPT for submodule-gitlink-pointer moves. A worktree task that commits inside a

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

@@ -22,6 +22,8 @@ import type { PtyRuntimeMetadata, PtyTransportFactory } from '../cli-adapters/pt
 import { StatusMonitor } from './status-monitor.js';
 import { ChatHistoryWriter, isNativeSourceCanonicalHistory, materializeProviderNativeHistory, readChatHistory, readProviderChatHistory } from '../config/chat-history.js';
 import { LOG } from '../logging/logger.js';
+import { recordDebugTrace } from '../logging/debug-trace.js';
+import { shouldCollectTraceCategory } from '../logging/debug-config.js';
 import { traceMeshEventStage, traceMeshEventDrop } from '../mesh/mesh-event-trace.js';
 import type { ChatMessage } from '../types.js';
 import { buildPersistedProviderEffectMessage, normalizeProviderEffects } from './control-effects.js';
@@ -1526,9 +1528,23 @@ export class CliProviderInstance implements ProviderInstance {
     }
 
     private completionFinalAssistantEvidence(parsedMessages: unknown, turnStartedAt?: number): CompletionFinalAssistantEvidence {
+        // (FALSEIDLE FixB) UPPER-BOUND turn-end evidence. completionHasFinalAssistantMessage is a
+        // pure message-content check ("does the last visible bubble read as a finalized assistant
+        // reply, post-dating the turn start?"). That LOWER bound alone treated the FIRST assistant
+        // bubble of a turn that is STILL running — a tool call in flight between two assistant
+        // bubbles — as proof the turn ended (RCA cases a & b). Require in ADDITION that the turn is
+        // genuinely OVER: hasAdapterPendingResponse() folds the three upper-bound discriminators
+        // into one — currentTurnScope closed, no in-flight tool (isProcessing false), and no partial
+        // response buffer. So a mid-turn point-sample (short-gen / fast-collapse inline paths that
+        // do NOT route through getCompletedFinalizationBlock) yields present=false and is held/settled
+        // rather than fired. A genuinely-finished turn (adapter idle, no pending) is unaffected — the
+        // gate stays open and the completion fires exactly as before. This mirrors the established
+        // `completionHasFinalAssistantMessage(...) && !hasAdapterPendingResponse()` pairing already
+        // used by the no-progress monitor reconcile path.
+        const turnClosed = !this.hasAdapterPendingResponse();
         if (this.completionHasFinalAssistantMessage(parsedMessages, turnStartedAt)) {
             return {
-                present: true,
+                present: turnClosed,
                 messages: Array.isArray(parsedMessages) ? parsedMessages : [],
                 source: 'parsed',
             };
@@ -1537,7 +1553,7 @@ export class CliProviderInstance implements ProviderInstance {
         const externalMessages = this.readExternalCompletionMessages();
         if (externalMessages) {
             return {
-                present: this.completionHasFinalAssistantMessage(externalMessages, turnStartedAt),
+                present: turnClosed && this.completionHasFinalAssistantMessage(externalMessages, turnStartedAt),
                 messages: externalMessages,
                 source: 'external-native',
             };
@@ -1690,11 +1706,21 @@ export class CliProviderInstance implements ProviderInstance {
 
         const adapterAny = this.adapter as any;
         const approvalResolvedIdle = pending.previousStatus === 'waiting_approval';
-        if (!approvalResolvedIdle) {
-            if (adapterAny?.isWaitingForResponse === true) return { reason: 'adapter_waiting_for_response', terminal: true };
-            if (adapterAny?.currentTurnScope) return { reason: 'adapter_turn_scope_active', terminal: true };
-            if (this.hasAdapterPendingResponse()) return { reason: 'adapter_pending_response', terminal: true };
-        }
+        // (FALSEIDLE-a FixA) The adapter pending-response checks run UNCONDITIONALLY.
+        // Previously they were SKIPPED when approvalResolvedIdle, on the assumption that
+        // a waiting_approval→idle transition proved the approval's turn was over. But
+        // auto-approve RESOLVES the modal and the agent RESUMES the same turn — currentTurnScope
+        // / isWaitingForResponse stay set, or a tool runs — so skipping the guard let the FIRST
+        // assistant bubble of the still-running turn be mistaken for the last and fired an early
+        // completion the coordinator could never correct (RCA case a). Keep the guard live for the
+        // approval path too: when the resumed turn genuinely ends these clear and the completion
+        // fires. Approval-resolved holds are NON-terminal (bounded by COMPLETED_FINALIZATION_MAX_WAIT_MS)
+        // so a provider that never closes its turn-scope still force-fires a weak completion rather
+        // than wedging; the non-approval path keeps its terminal hold (a genuinely-busy adapter must
+        // never force a completion out).
+        if (adapterAny?.isWaitingForResponse === true) return { reason: 'adapter_waiting_for_response', terminal: !approvalResolvedIdle };
+        if (adapterAny?.currentTurnScope) return { reason: 'adapter_turn_scope_active', terminal: !approvalResolvedIdle };
+        if (this.hasAdapterPendingResponse()) return { reason: 'adapter_pending_response', terminal: !approvalResolvedIdle };
 
         const partial = typeof this.adapter.getPartialResponse === 'function'
             ? this.adapter.getPartialResponse()
@@ -1891,6 +1917,40 @@ export class CliProviderInstance implements ProviderInstance {
         };
     }
 
+    // COMPLETION-EARLYNOTIFY instrumentation. A session-keyed FSM-transition +
+    // completion-gate snapshot recorded into the shared debug-trace ring buffer
+    // (secret-safe, length/role/pattern-name only — never screen or bubble text).
+    // Retrieved via getRecentDebugTrace (chat_debug_bundle). Both categories are a
+    // no-op unless collectDebugTrace is on AND the category is selected, so the
+    // hot-path guards below (completionTraceOn / fsmTraceOn) keep production cost
+    // at a single boolean check.
+    private completionTraceOn(): boolean {
+        return shouldCollectTraceCategory('completion-gate');
+    }
+    private fsmTraceOn(): boolean {
+        return shouldCollectTraceCategory('fsm-transition');
+    }
+    private recordCompletionGateTrace(stage: string, payload: Record<string, unknown>): void {
+        recordDebugTrace({
+            category: 'completion-gate',
+            stage,
+            level: 'debug',
+            sessionId: this.instanceId,
+            providerType: this.type,
+            payload,
+        });
+    }
+    private recordFsmTransitionTrace(payload: Record<string, unknown>): void {
+        recordDebugTrace({
+            category: 'fsm-transition',
+            stage: 'transition',
+            level: 'debug',
+            sessionId: this.instanceId,
+            providerType: this.type,
+            payload,
+        });
+    }
+
     private flushCompletedDebounceIfFinalized(): void {
         const pending = this.completedDebouncePending;
         if (!pending) {
@@ -1904,6 +1964,13 @@ export class CliProviderInstance implements ProviderInstance {
         LOG.debug('CLI', `[${this.type}] flush attempt: adapterStatus=${latestStatus.status} latestVisible=${latestVisibleStatus} 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})`);
+            if (this.completionTraceOn()) this.recordCompletionGateTrace('cancel', {
+                blockReason: 'resumed_status',
+                latestVisibleStatus,
+                previousStatus: pending.previousStatus,
+                busyEpochAtArm: pending.busyEpochAtArm,
+                busyEpoch: this.busyEpoch,
+            });
             this.completedDebouncePending = null;
             this.completedDebounceTimer = null;
             return;
@@ -1921,6 +1988,14 @@ export class CliProviderInstance implements ProviderInstance {
         // so shared behaviour for claude/codex/antigravity is strictly stricter, never looser.
         if (typeof pending.busyEpochAtArm === 'number' && this.busyEpoch !== pending.busyEpochAtArm) {
             LOG.info('CLI', `[${this.type}] cancelled pending completed (busy re-entry during settle: epoch ${pending.busyEpochAtArm}→${this.busyEpoch})`);
+            if (this.completionTraceOn()) this.recordCompletionGateTrace('cancel', {
+                blockReason: 'busy_reentry',
+                latestVisibleStatus,
+                previousStatus: pending.previousStatus,
+                busyEpochAtArm: pending.busyEpochAtArm,
+                busyEpoch: this.busyEpoch,
+                busyEpochDelta: this.busyEpoch - pending.busyEpochAtArm,
+            });
             this.completedDebouncePending = null;
             this.completedDebounceTimer = null;
             return;
@@ -1930,6 +2005,14 @@ export class CliProviderInstance implements ProviderInstance {
             && typeof latestOutputAt === 'number'
             && latestOutputAt > pending.lastOutputAtArm) {
             LOG.info('CLI', `[${this.type}] cancelled pending completed (new PTY output during settle: ${pending.lastOutputAtArm}→${latestOutputAt})`);
+            if (this.completionTraceOn()) this.recordCompletionGateTrace('cancel', {
+                blockReason: 'new_pty_output',
+                latestVisibleStatus,
+                previousStatus: pending.previousStatus,
+                lastOutputAtArm: pending.lastOutputAtArm,
+                lastOutputAt: latestOutputAt,
+                lastOutputAtDelta: latestOutputAt - pending.lastOutputAtArm,
+            });
             this.completedDebouncePending = null;
             this.completedDebounceTimer = null;
             return;
@@ -1975,6 +2058,17 @@ export class CliProviderInstance implements ProviderInstance {
                     if (this.isMeshWorkerSession()) {
                         traceMeshEventDrop('completion_gate_hold', this.meshTraceCtx(), `${blockReason} waited=${waitedMs}ms`);
                     }
+                    // COMPLETION-EARLYNOTIFY: a hold is the CORRECT outcome when the turn is not
+                    // yet proven done (the FixA/FixB gates route here); trace it so an early-notify
+                    // investigation can see the gate holding rather than firing.
+                    if (this.completionTraceOn()) this.recordCompletionGateTrace('hold', {
+                        blockReason,
+                        latestVisibleStatus,
+                        terminal: block.terminal === true,
+                        holdForTranscript: block.holdForTranscript === true,
+                        approvalResolvedIdle: pending.previousStatus === 'waiting_approval',
+                        waitedMs,
+                    });
                     pending.loggedBlockReason = blockReason;
                 }
                 this.scheduleCompletedDebounceFlush(COMPLETED_FINALIZATION_RETRY_MS);
@@ -1997,6 +2091,19 @@ export class CliProviderInstance implements ProviderInstance {
             if (this.isMeshWorkerSession()) {
                 traceMeshEventStage('fired', this.meshTraceCtx(), `forced after ${waitedMs}ms (${blockReason})`);
             }
+            if (this.completionTraceOn()) this.recordCompletionGateTrace('fire', {
+                path: isTranscriptEvidenceGate && !emittedAfterFinalizationTimeout ? 'canon_c_decoupled' : 'forced_timeout',
+                blockReason,
+                latestVisibleStatus,
+                approvalResolvedIdle: pending.previousStatus === 'waiting_approval',
+                finalAssistantPresent: (completionDiagnostic as any).finalAssistantPresent === true,
+                evidenceSource: (completionDiagnostic as any).finalAssistantEvidenceSource ?? null,
+                lastVisibleRole: (completionDiagnostic as any).lastVisibleRole ?? null,
+                lastVisibleContentLen: (completionDiagnostic as any).lastVisibleContentLength ?? null,
+                emittedAfterFinalizationTimeout,
+                waitedMs,
+                busyEpoch: this.busyEpoch,
+            });
             this.pushEvent({
                 event: 'agent:generating_completed',
                 chatTitle: pending.chatTitle,
@@ -2028,6 +2135,14 @@ export class CliProviderInstance implements ProviderInstance {
         if (this.isMeshWorkerSession()) {
             traceMeshEventStage('fired', this.meshTraceCtx(), `duration=${pending.duration}s`);
         }
+        if (this.completionTraceOn()) this.recordCompletionGateTrace('fire', {
+            path: 'clean',
+            latestVisibleStatus,
+            approvalResolvedIdle: pending.previousStatus === 'waiting_approval',
+            finalAssistantPresent: true,
+            duration: pending.duration,
+            busyEpoch: this.busyEpoch,
+        });
         this.pushEvent({
             event: 'agent:generating_completed',
             chatTitle: pending.chatTitle,
@@ -2424,6 +2539,22 @@ export class CliProviderInstance implements ProviderInstance {
         const previousStatus = this.lastStatus;
         if (newStatus !== this.lastStatus) {
             LOG.info('CLI', `[${this.type}] status: ${this.lastStatus} → ${newStatus}`);
+            // COMPLETION-EARLYNOTIFY: snapshot every FSM status transition (the arm/fire/cancel
+            // decisions downstream all hang off these edges). Guarded so production pays only a
+            // boolean check; payload carries the visibility/auto-approve flags and the continuity
+            // clocks (busyEpoch / lastOutputAt / lastScreenChangeAt) that the completion gate reads.
+            if (this.fsmTraceOn()) this.recordFsmTransitionTrace({
+                from: this.lastStatus,
+                to: newStatus,
+                rawStatus,
+                autoApproveActive,
+                autoApproveHoldIdle,
+                autoApproveBusy: this.autoApproveBusy,
+                hasPending: this.hasAdapterPendingResponse(),
+                busyEpoch: this.busyEpoch,
+                lastOutputAt: typeof adapterStatus?.lastOutputAt === 'number' ? adapterStatus.lastOutputAt : null,
+                lastScreenChangeAt: typeof adapterStatus?.lastScreenChangeAt === 'number' ? adapterStatus.lastScreenChangeAt : null,
+            });
             // GENERATING-MISSING (win32 fresh-worktree first-turn): a freshly-launched session
             // is in 'starting' until its startup-grace settles to idle. When the FIRST inject
             // lands inside that grace window, the adapter can report status DIRECTLY
@@ -2661,6 +2792,17 @@ export class CliProviderInstance implements ProviderInstance {
                         if (this.isMeshWorkerSession()) {
                             traceMeshEventStage('arm', this.meshTraceCtx(), `short-generating settle-arm (source=${shortEvidenceSource}, missingEvidence=${missingEvidence})`);
                         }
+                        if (this.completionTraceOn()) this.recordCompletionGateTrace('arm', {
+                            branch: 'short_generating',
+                            previousStatus: this.lastStatus,
+                            turnStartedAt: shortTurnStartedAt || null,
+                            busyEpochAtArm: this.busyEpoch,
+                            lastOutputAtArm: typeof adapterStatus?.lastOutputAt === 'number' ? adapterStatus.lastOutputAt : null,
+                            flushDelay: NATIVE_HISTORY_MESH_IDLE_SETTLE_MS,
+                            evidenceSource: shortEvidenceSource,
+                            missingEvidence,
+                            hasFinalSummary: !!shortFinalSummary,
+                        });
                         this.scheduleCompletedDebounceFlush(NATIVE_HISTORY_MESH_IDLE_SETTLE_MS);
                     } else if (missingEvidence) {
                         // NON-MESH, missing evidence: suppress the completion event entirely (the
@@ -2749,6 +2891,16 @@ export class CliProviderInstance implements ProviderInstance {
                         ? (meshSettleSession ? NATIVE_HISTORY_MESH_IDLE_SETTLE_MS : 0)
                         : 3000;
                     LOG.debug('CLI', `[${this.type}] set completedDebouncePending duration=${duration}s ownsExternalHistory=${ownsExternalHistory} meshSettle=${meshSettleSession} flushDelay=${flushDelay}ms generatingStartedAt=${this.generatingStartedAt}`);
+                    if (this.completionTraceOn()) this.recordCompletionGateTrace('arm', {
+                        branch: 'normal',
+                        previousStatus: this.completedDebouncePending.previousStatus,
+                        turnStartedAt: this.completedDebouncePending.turnStartedAt ?? null,
+                        busyEpochAtArm: this.completedDebouncePending.busyEpochAtArm ?? null,
+                        lastOutputAtArm: this.completedDebouncePending.lastOutputAtArm ?? null,
+                        flushDelay,
+                        ownsExternalHistory,
+                        meshSettle: meshSettleSession,
+                    });
                     this.scheduleCompletedDebounceFlush(flushDelay);
                 }
             } else if (newStatus === 'idle' && this.lastStatus === 'starting') {