@adhdev/daemon-core 0.9.82-rc.419 → 0.9.82-rc.420

package/dist/mesh/mesh-clone-grace.d.ts

@@ -0,0 +1,8 @@
+export declare const CLONE_BOOTSTRAP_GRACE_MS: number;
+/** Record that a worktree node id was just cloned, opening its transient grace window. */
+export declare function noteRecentlyClonedNode(nodeId: string | undefined | null, nowMs?: number): void;
+/** True when nodeId was cloned within the grace window (and the entry has not expired). */
+export declare function isWithinCloneBootstrapGrace(nodeId: string | undefined | null, nowMs?: number): boolean;
+/** Drop a node's grace entry (e.g. once it has fully resolved into the mesh view). */
+export declare function clearCloneBootstrapGrace(nodeId: string | undefined | null): void;
+export declare function __resetCloneBootstrapGraceForTests(): void;

package/dist/mesh/mesh-events-pending.d.ts

@@ -44,6 +44,20 @@ export declare function queuePendingMeshCoordinatorEvent(event: PendingMeshCoord
 export declare function drainPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string | ReadonlyArray<string>, opts?: {
     onlyEvents?: ReadonlySet<string>;
 }): PendingMeshCoordinatorEvent[];
+/**
+ * FALSE-BLOCKER-CLONE-QUEUE: retract any still-UNDELIVERED `mesh:dispatch_blocked`
+ * actionable-skip event for a task whose blocker has since resolved (the task was
+ * claimed, or its skip transitioned to a self-resolving transient reason). Without
+ * this, a `target_node_id_unmatched` blocker paged during the brief clone/bootstrap
+ * propagation window would linger in the coordinator's pending queue and surface as a
+ * false "actionable blocker — will NOT clear on its own" even after the task dispatched.
+ *
+ * Only removes events that have NOT yet been drained/delivered to the coordinator — an
+ * already-delivered message cannot be unsent, but de-dup re-arm (caller side) plus this
+ * retraction guarantee no NEW stale blocker accumulates. Best-effort across both the
+ * SQLite inbox and the JSONL legacy files (scoped + shared). Returns rows removed.
+ */
+export declare function retractPendingDispatchBlockedEvent(meshId: string | undefined, taskId: string | undefined, coordinatorDaemonId?: string): number;
 /** Peek at pending coordinator events without draining (non-destructive). */
 export declare function getPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string | ReadonlyArray<string>): readonly PendingMeshCoordinatorEvent[];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.419",
+  "version": "0.9.82-rc.420",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.419",
+    "@adhdev/mesh-shared": "0.9.82-rc.420",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/commands/med-family/mesh-crud.ts

@@ -18,6 +18,7 @@ import {
 } from '../../mesh/worktree-bootstrap-config.js';
 import { loadRepoSettings } from '../../config/repo-settings.js';
 import { handleMeshForwardEvent, queuePendingMeshCoordinatorEvent } from '../../mesh/mesh-events.js';
+import { noteRecentlyClonedNode } from '../../mesh/mesh-clone-grace.js';
 import { loadConfig } from '../../config/config.js';
 import {
     hydrateInlineMeshDirectTruth,
@@ -417,6 +418,39 @@ export const meshCrudHandlers: Record<string, MedFamilyHandler> = {
             const explicitSessionIds = Array.isArray(args?.sessionIds)
                 ? (args.sessionIds as unknown[]).filter((v): v is string => typeof v === 'string' && v.trim().length > 0).map(v => v.trim())
                 : undefined;
+            // Precheck-first: for a LOCAL worktree removal, validate removability
+            // with a purely non-destructive precheck BEFORE touching the session.
+            // The session cleanup below is destructive and irreversible
+            // (stop_and_delete), so a refusal that fires only AFTER it — as the old
+            // ordering did when removeWorktree rejected a dirty worktree — orphaned
+            // the delegated session. Running the precheck here means a refusal
+            // (dirty worktree, missing/mismatched metadata, etc.) returns with the
+            // session left fully intact. Remote-forwarded worktrees are prechecked
+            // on the owning daemon (it runs this same handler), so we only gate the
+            // local case here. Success/skip cases return ok:true and fall through to
+            // the unchanged normal flow.
+            if (node?.isLocalWorktree) {
+                const nodeDaemonId = typeof node.daemonId === 'string' ? node.daemonId.trim() : undefined;
+                const isRemoteWorktree = nodeDaemonId && !daemonIdsEquivalent(nodeDaemonId, ctx.deps.statusInstanceId) && ctx.deps.dispatchMeshCommand
+                    && !args?._meshDirectDispatch;
+                if (!isRemoteWorktree) {
+                    const precheck = await ctx.precheckLocalWorktreeRemovable({ mesh, node, nodeId, force: args?.force === true });
+                    if (precheck.ok === false) {
+                        return {
+                            success: false,
+                            removed: false,
+                            code: precheck.code,
+                            error: precheck.error,
+                            recoveryHint: precheck.recoveryHint,
+                            // No sessionCleanup key: the session was deliberately NOT
+                            // touched. worktreeCleanup mirrors the destructive path's
+                            // refusal shape so existing callers see the same code.
+                            worktreeCleanup: { success: false, code: precheck.code, error: precheck.error, recoveryHint: precheck.recoveryHint },
+                        };
+                    }
+                }
+            }
+
             let sessionCleanup: Record<string, unknown> | undefined;
             if (node && sessionCleanupMode !== 'preserve') {
                 sessionCleanup = await ctx.cleanupMeshSessions({
@@ -597,6 +631,13 @@ export const meshCrudHandlers: Record<string, MedFamilyHandler> = {
                     ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
                     _meshDirectDispatch: true,
                 });
+                // FALSE-BLOCKER-CLONE-QUEUE: open the transient grace window for the freshly
+                // cloned node on THIS coordinator daemon. The clone ran (and wrote the inline-
+                // cache node) on the remote source daemon; its inline entry has not propagated
+                // here yet, so a queue task pinned to it would transiently look like a permanent
+                // 'target_node_id_unmatched'. Recording its id marks the unmatch as transient.
+                const forwardedNodeId = (forwarded as { node?: { id?: unknown } } | null | undefined)?.node?.id;
+                if (typeof forwardedNodeId === 'string' && forwardedNodeId) noteRecentlyClonedNode(forwardedNodeId);
                 return (forwarded ?? { success: false, error: 'no response from remote node' }) as CommandRouterResult;
             }
 
@@ -654,6 +695,12 @@ export const meshCrudHandlers: Record<string, MedFamilyHandler> = {
                 ctx.invalidateAggregateMeshStatus(meshId);
             }
 
+            // FALSE-BLOCKER-CLONE-QUEUE: open the transient grace window for the freshly cloned
+            // node. A queue task pinned to it (target_node pin) enqueued before bootstrap
+            // completes / the inline-cache entry fully settles must be classified as a transient
+            // skip, not a permanent 'target_node_id_unmatched' actionable blocker.
+            if (typeof node?.id === 'string' && node.id) noteRecentlyClonedNode(node.id);
+
             const persistWorktreeSetupState = async (bootstrapState: WorktreeBootstrapState): Promise<void> => {
                 node.worktreeBootstrap = bootstrapState;
                 if (meshRecord.inline) {

package/src/commands/med-family/types.ts

@@ -31,6 +31,16 @@ export type CleanupLocalWorktreeNodeResult =
     | { success: true; skipped?: boolean; removedPath?: string; repoRoot?: string; reason?: string; fallback?: string; forced?: boolean; convergence?: Record<string, unknown>; recovered?: boolean; residue?: boolean; residueWarning?: string; residueError?: string }
     | { success: false; code: string; error: string; recoveryHint: string; convergence?: Record<string, unknown> };
 
+/**
+ * Result of the non-destructive local-worktree removability precheck. `ok:false`
+ * carries the same refusal `code`/`error`/`recoveryHint` that the destructive
+ * cleanup would have returned, so callers can refuse a removal BEFORE performing
+ * any irreversible step (e.g. stopping/deleting delegated sessions).
+ */
+export type WorktreeRemovalPrecheckResult =
+    | { ok: true }
+    | { ok: false; code: string; error: string; recoveryHint: string };
+
 /**
  * Router-private collaborators injected at dispatch. Each is a bound method or
  * field of DaemonCommandRouter; handlers that don't need a given collaborator
@@ -85,6 +95,18 @@ export interface MedFamilyContext {
         force?: boolean;
     }) => Promise<CleanupLocalWorktreeNodeResult>;
 
+    /**
+     * Bound `DaemonCommandRouter.precheckLocalWorktreeRemovable` — purely
+     * non-destructive validation of whether a local worktree node can be removed.
+     * Called BEFORE session cleanup so a refusal does not orphan the session.
+     */
+    precheckLocalWorktreeRemovable: (args: {
+        mesh: any;
+        node: any;
+        nodeId: string;
+        force?: boolean;
+    }) => Promise<WorktreeRemovalPrecheckResult>;
+
     /** Bound `DaemonCommandRouter.startMeshRefineJob` (async execute path). */
     startMeshRefineJob: (meshId: string, nodeId: string, args: any) => Promise<CommandRouterResult>;
 

package/src/commands/router.ts

@@ -647,6 +647,7 @@ export class DaemonCommandRouter {
             normalizeMeshSessionCleanupMode: this.normalizeMeshSessionCleanupMode.bind(this),
             cleanupMeshSessions: this.cleanupMeshSessions.bind(this),
             cleanupLocalWorktreeNode: this.cleanupLocalWorktreeNode.bind(this),
+            precheckLocalWorktreeRemovable: this.precheckLocalWorktreeRemovable.bind(this),
             startMeshRefineJob: this.startMeshRefineJob.bind(this),
             batchRefineMeshNodes: this.batchRefineMeshNodes.bind(this),
             startMeshRefineBatchJob: this.startMeshRefineBatchJob.bind(this),
@@ -916,6 +917,133 @@ export class DaemonCommandRouter {
             : { removed: true, residue: false };
     }
 
+    /**
+     * Non-destructive precheck mirroring every REFUSAL condition in
+     * {@link cleanupLocalWorktreeNode} — missing workspace / source-repo / branch
+     * metadata, unexpected (non-managed) path, branch mismatch — PLUS the
+     * dirty-worktree guard that `removeWorktree(requireClean)` enforces
+     * (`git status --porcelain`). It performs ZERO destructive actions: no
+     * `git worktree remove`, no `git worktree prune`, no directory deletion.
+     *
+     * remove_mesh_node calls this BEFORE any session cleanup so that a refusal
+     * (the common one being a dirty worktree) does not first stop/delete the
+     * delegated session and orphan it — the original ordering bug. Success/skip
+     * cases that the real cleanup handles idempotently (worktree path already
+     * gone, git-de-registered residue) are NOT refusals and return `{ ok: true }`.
+     *
+     * `force:true` skips the dirty guard, preserving `removeWorktree`'s
+     * `requireClean: !force` semantics. This is a read-only superset check; the
+     * authoritative `requireClean` guard inside `removeWorktree` is intentionally
+     * kept as a second line of defense against a precheck→execute race.
+     */
+    private async precheckLocalWorktreeRemovable(args: {
+        mesh: any;
+        node: any;
+        nodeId: string;
+        force?: boolean;
+    }): Promise<{ ok: true } | { ok: false; code: string; error: string; recoveryHint: string }> {
+        const sessionPreservedNote = ' The delegated session was left running (not stopped) — resolve the issue and retry mesh_remove_node.';
+        const workspace = typeof args.node?.workspace === 'string' ? args.node.workspace.trim() : '';
+        if (!workspace) {
+            return {
+                ok: 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.' + sessionPreservedNote,
+            };
+        }
+
+        // Worktree path already gone → not a refusal; the real cleanup returns a
+        // skipped:true success and the node is dropped from the registry.
+        if (!fs.existsSync(workspace)) return { ok: true };
+
+        const sourceNode = args.node?.clonedFromNodeId
+            ? args.mesh?.nodes?.find((n: any) => meshNodeIdMatches(n, 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 (!repoRoot || !fs.existsSync(repoRoot)) {
+            return {
+                ok: 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.' + sessionPreservedNote,
+            };
+        }
+        if (typeof args.node?.worktreeBranch !== 'string' || !args.node.worktreeBranch.trim()) {
+            return {
+                ok: 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.' + sessionPreservedNote,
+            };
+        }
+
+        const { resolveWorktreePath, listWorktrees } = 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 {
+                ok: 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.' + sessionPreservedNote,
+            };
+        }
+
+        const entries = await listWorktrees(repoRoot);
+        const managedEntry = entries.find(entry => normalizePath(entry.path) === actualPath);
+        // De-registered residue (git no longer lists it as a worktree) is an
+        // idempotent recovery path in the real cleanup, NOT a refusal — neither the
+        // branch-mismatch nor the dirty check applies, so let the removal proceed.
+        if (!managedEntry) return { ok: true };
+
+        if (managedEntry.branch && managedEntry.branch !== args.node.worktreeBranch) {
+            return {
+                ok: 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.' + sessionPreservedNote,
+            };
+        }
+
+        // Dirty-worktree guard — a read-only mirror of removeWorktree(requireClean)
+        // (`git status --porcelain` run inside the worktree). `force:true` skips it,
+        // preserving the requireClean:!force semantics.
+        if (args.force !== true) {
+            const { execFile } = await import('node:child_process');
+            const { promisify } = await import('node:util');
+            const execFileAsync = promisify(execFile);
+            try {
+                const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
+                    cwd: workspace, encoding: 'utf8', timeout: 30_000, maxBuffer: 4 * 1024 * 1024, windowsHide: true,
+                });
+                if (stdout.trim()) {
+                    return {
+                        ok: false,
+                        code: 'mesh_worktree_cleanup_dirty',
+                        error: `Refusing to remove dirty worktree: ${workspace}`,
+                        recoveryHint: 'Commit, stash, or intentionally discard the worktree changes before retrying mesh_remove_node. The mesh registry entry is preserved until cleanup is safe.' + sessionPreservedNote,
+                    };
+                }
+            } catch {
+                // A status probe failure is not itself proof of dirtiness; defer to
+                // the authoritative removeWorktree(requireClean) guard rather than
+                // refusing here (which would block an otherwise-clean removal).
+                return { ok: true };
+            }
+        }
+
+        return { ok: true };
+    }
+
     private async cleanupLocalWorktreeNode(args: {
         mesh: any;
         node: any;

package/src/mesh/mesh-clone-grace.ts

@@ -0,0 +1,68 @@
+import { normalizeMeshNodeId, type MeshNodeIdentified } from '@adhdev/mesh-shared';
+
+// ---------------------------------------------------------------------------
+// Recently-cloned worktree node grace window
+// ---------------------------------------------------------------------------
+// FALSE-BLOCKER-CLONE-QUEUE: right after mesh_clone_node registers a worktree node, a
+// queue task pinned to that node id (target_node pin) can transiently find NO matching
+// node in the coordinator-owning daemon's mesh view, because:
+//   - the clone wrote the node ONLY into the inline mesh cache (med-family clone branch),
+//     and that inline entry has not yet PROPAGATED to the coordinator daemon (the clone
+//     may have run on the source node's machine and forwarded), and/or
+//   - the node's worktree bootstrap (npm install / native-addon repair) is still running,
+//     so the claim gate defers anyway.
+// In BOTH cases the unmatch SELF-RESOLVES within ~seconds (observed bootstrap ~2m8s) — it
+// is NOT the permanent `target_node_id_unmatched` routing miss (a removed/dead node) that
+// the actionable-blocker coordinator notification exists for. This registry lets the skip
+// classifier tell the transient case apart from the permanent one: a node id recorded here
+// (within the grace TTL) is a freshly cloned worktree whose unmatch should be reported as a
+// transient, NON-actionable skip rather than paging the coordinator with a false
+// "will NOT clear on its own" blocker.
+//
+// The window is floored well above the observed clone + bootstrap + inline-cache
+// propagation latency so a slow-but-live clone is never misclassified as a permanent
+// unmatch. A genuinely dead/removed node is never recorded here (or its entry has long
+// expired), so its `target_node_id_unmatched` stays correctly actionable.
+export const CLONE_BOOTSTRAP_GRACE_MS = 10 * 60 * 1000;
+
+const recentlyClonedNodeExpiry = new Map<string, number>(); // normalized nodeId -> expiry epoch ms
+const MAX_TRACKED_CLONED_NODES = 512;
+
+function normalizeNodeIdKey(nodeId: string | undefined | null): string {
+    return normalizeMeshNodeId({ id: nodeId ?? undefined } as MeshNodeIdentified) ?? '';
+}
+
+/** Record that a worktree node id was just cloned, opening its transient grace window. */
+export function noteRecentlyClonedNode(nodeId: string | undefined | null, nowMs: number = Date.now()): void {
+    const key = normalizeNodeIdKey(nodeId);
+    if (!key) return;
+    recentlyClonedNodeExpiry.set(key, nowMs + CLONE_BOOTSTRAP_GRACE_MS);
+    if (recentlyClonedNodeExpiry.size > MAX_TRACKED_CLONED_NODES) {
+        // Map iteration is insertion-ordered; the first key is the oldest-inserted entry.
+        const oldest = recentlyClonedNodeExpiry.keys().next().value;
+        if (oldest !== undefined) recentlyClonedNodeExpiry.delete(oldest);
+    }
+}
+
+/** True when nodeId was cloned within the grace window (and the entry has not expired). */
+export function isWithinCloneBootstrapGrace(nodeId: string | undefined | null, nowMs: number = Date.now()): boolean {
+    const key = normalizeNodeIdKey(nodeId);
+    if (!key) return false;
+    const expiry = recentlyClonedNodeExpiry.get(key);
+    if (expiry === undefined) return false;
+    if (nowMs >= expiry) {
+        recentlyClonedNodeExpiry.delete(key);
+        return false;
+    }
+    return true;
+}
+
+/** Drop a node's grace entry (e.g. once it has fully resolved into the mesh view). */
+export function clearCloneBootstrapGrace(nodeId: string | undefined | null): void {
+    const key = normalizeNodeIdKey(nodeId);
+    if (key) recentlyClonedNodeExpiry.delete(key);
+}
+
+export function __resetCloneBootstrapGraceForTests(): void {
+    recentlyClonedNodeExpiry.clear();
+}

package/src/mesh/mesh-events-pending.ts

@@ -541,6 +541,57 @@ export function drainPendingMeshCoordinatorEvents(
     return reconcilePendingMeshCoordinatorEvents(meshId, merged);
 }
 
+/**
+ * FALSE-BLOCKER-CLONE-QUEUE: retract any still-UNDELIVERED `mesh:dispatch_blocked`
+ * actionable-skip event for a task whose blocker has since resolved (the task was
+ * claimed, or its skip transitioned to a self-resolving transient reason). Without
+ * this, a `target_node_id_unmatched` blocker paged during the brief clone/bootstrap
+ * propagation window would linger in the coordinator's pending queue and surface as a
+ * false "actionable blocker — will NOT clear on its own" even after the task dispatched.
+ *
+ * Only removes events that have NOT yet been drained/delivered to the coordinator — an
+ * already-delivered message cannot be unsent, but de-dup re-arm (caller side) plus this
+ * retraction guarantee no NEW stale blocker accumulates. Best-effort across both the
+ * SQLite inbox and the JSONL legacy files (scoped + shared). Returns rows removed.
+ */
+export function retractPendingDispatchBlockedEvent(
+    meshId: string | undefined,
+    taskId: string | undefined,
+    coordinatorDaemonId?: string,
+): number {
+    if (!meshId || !taskId) return 0;
+    let removed = 0;
+    const matchesTask = (event: PendingMeshCoordinatorEvent | undefined): boolean => {
+        if (!event || event.event !== 'mesh:dispatch_blocked') return false;
+        const rowTaskId = readNonEmptyString((event.metadataEvent as Record<string, unknown> | undefined)?.taskId);
+        return rowTaskId === taskId;
+    };
+
+    // SQLite inbox: peek undrained rows for the mesh, hard-delete the matching ones by id.
+    try {
+        const store = MeshRuntimeStore.getInstance();
+        const ids: string[] = [];
+        for (const row of store.peekPendingEvents(meshId)) {
+            if (row.event !== 'mesh:dispatch_blocked') continue;
+            if (matchesTask(row.payload as PendingMeshCoordinatorEvent)) ids.push(row.id);
+        }
+        if (ids.length) removed += store.deletePendingEventsById(ids);
+    } catch { /* best-effort — JSONL retraction below still runs */ }
+
+    // JSONL legacy files: selectively drop matching lines (rewrites the rest back).
+    const daemonIds = normalizeCoordinatorDaemonIds(coordinatorDaemonId);
+    const primaryDaemonId = daemonIds[0];
+    const paths = primaryDaemonId
+        ? [getPendingEventsPath(meshId, primaryDaemonId), getPendingEventsPath(meshId)]
+        : [getPendingEventsPath(meshId)];
+    for (const path of paths) {
+        try {
+            removed += selectiveDrainFile(path, matchesTask).length;
+        } catch { /* best-effort */ }
+    }
+    return removed;
+}
+
 /** Peek at pending coordinator events without draining (non-destructive). */
 export function getPendingMeshCoordinatorEvents(meshId?: string, coordinatorDaemonId?: string | ReadonlyArray<string>): readonly PendingMeshCoordinatorEvent[] {
     if (!meshId) return [];

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

@@ -18,8 +18,9 @@ import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
 import { normalizeMeshNodeId, meshNodeIdMatches, daemonIdsEquivalent, canonicalDaemonId, normalizeMeshWorkspaceForCompare, meshWorkspacesEquivalent, type MeshNodeIdentified } from '@adhdev/mesh-shared';
 import { findTerminalLedgerEvidenceForTask, hasUnterminalDirectDispatchLedgerEntry } from './mesh-events-stale.js';
 import { readNonEmptyString } from './mesh-events-utils.js';
-import { queuePendingMeshCoordinatorEvent } from './mesh-events-pending.js';
+import { queuePendingMeshCoordinatorEvent, retractPendingDispatchBlockedEvent } from './mesh-events-pending.js';
 import { isWorktreeBootstrapStaleRunning } from './worktree-bootstrap-config.js';
+import { isWithinCloneBootstrapGrace } from './mesh-clone-grace.js';
 import { beginTaskDispatchInFlight, endTaskDispatchInFlight } from './mesh-task-inflight.js';
 
 /**
@@ -434,6 +435,13 @@ export function tryAssignQueueTask(
 
     LOG.info('MeshQueue', `Node ${nodeId} (${sessionId}) pulled task ${task.id}`);
 
+    // FALSE-BLOCKER-CLONE-QUEUE (stale-event clear): the task just claimed and will dispatch,
+    // so any actionable blocker previously paged for it (e.g. a 'target_node_id_unmatched'
+    // emitted during the clone/bootstrap propagation window before the node became
+    // claimable) is now stale — re-arm the de-dup ledger and retract any undelivered
+    // dispatch_blocked event so the coordinator does not keep seeing a resolved blocker.
+    retractActionableSkipIfPreviouslyNotified(meshId, task.id);
+
     // CANON-IDENTITY single-flight: mark the just-claimed task in-flight the moment it
     // is handed to a transport. The atomic claim already prevents a concurrent claim,
     // but this lets requeueTask distinguish a genuinely-generating task (refuse the
@@ -606,6 +614,16 @@ const ACTIONABLE_SKIP_REASON_PREFIXES = [
     'dirty_workspace',
 ];
 
+// FALSE-BLOCKER-CLONE-QUEUE: the TRANSIENT counterpart of 'target_node_id_unmatched'. A
+// queue task pinned to a freshly cloned worktree node can transiently find no matching node
+// (its inline-cache entry has not propagated to this coordinator daemon yet, and/or its
+// worktree bootstrap is still running). That unmatch SELF-RESOLVES — it is not the permanent
+// routing miss the actionable blocker exists for — so it is deliberately NOT listed in
+// ACTIONABLE_SKIP_REASON_PREFIXES: isActionableSkipReason() returns false for it, so no
+// "actionable blocker — will NOT clear on its own" coordinator page is emitted. The skip is
+// still recorded to task.autoLaunch + the ledger for diagnosability.
+const TRANSIENT_TARGET_NODE_BOOTSTRAP_PENDING_REASON = 'target_node_bootstrap_pending';
+
 // De-dup actionable-skip coordinator notifications: emit once per (mesh, task) until the
 // reason CHANGES, so the 4s reconcile loop re-marking the same skip does not re-notify. A
 // non-skip transition (or a genuine reason change) re-arms it. In-memory only — a daemon
@@ -617,6 +635,54 @@ function isActionableSkipReason(reason?: string): boolean {
     return ACTIONABLE_SKIP_REASON_PREFIXES.some(prefix => reason === prefix || reason.startsWith(prefix));
 }
 
+/**
+ * FALSE-BLOCKER-CLONE-QUEUE: a target pin is TRANSIENTLY (not permanently) unresolved when
+ * the pinned node is a freshly cloned worktree that will auto-claim once its bootstrap
+ * completes / its inline-cache entry propagates — as opposed to a removed/dead node whose
+ * unmatch is a permanent, actionable routing miss. Two signals, either suffices:
+ *   (a) the node IS visible in the (cache-merged) mesh view but its worktree bootstrap is
+ *       still 'running' (and not stuck past the stale backstop), or
+ *   (b) the node is NOT visible here yet, but a clone for its id was issued within the grace
+ *       window (propagation/bootstrap latency) — see mesh-clone-grace.
+ * Conservative: a node neither bootstrap-running nor recently cloned → returns false, so a
+ * genuinely dead node keeps its permanent, actionable 'target_node_id_unmatched'.
+ */
+function isTargetNodeTransientlyUnresolved(mesh: any, task: MeshWorkQueueEntry): boolean {
+    const targetNodeId = readNonEmptyString(task.targetNodeId);
+    if (!targetNodeId) return false;
+    const node = Array.isArray(mesh?.nodes)
+        ? mesh.nodes.find((n: any) => meshNodeIdMatches(n, targetNodeId))
+        : undefined;
+    if (node
+        && (node as { worktreeBootstrap?: { status?: string } }).worktreeBootstrap?.status === 'running'
+        && !isWorktreeBootstrapStaleRunning(node)) {
+        return true;
+    }
+    return isWithinCloneBootstrapGrace(targetNodeId);
+}
+
+/**
+ * FALSE-BLOCKER-CLONE-QUEUE (stale-event clear): once a task whose actionable blocker we
+ * previously paged either gets claimed or transitions to a self-resolving state, re-arm the
+ * de-dup ledger (so a later genuine blocker re-notifies) AND retract any still-undelivered
+ * dispatch_blocked pending event, so the coordinator's pending queue no longer carries the
+ * stale "will NOT clear on its own" warning. Cheap: only touches the pending store when this
+ * (mesh, task) actually had a prior actionable notification recorded.
+ */
+function retractActionableSkipIfPreviouslyNotified(meshId: string, taskId: string): void {
+    const dedupKey = `${meshId}:${taskId}`;
+    if (!lastActionableSkipNotified.delete(dedupKey)) return; // nothing was paged → nothing to retract
+    try {
+        const coordinatorDaemonId = readNonEmptyString(loadConfig().machineId) || undefined;
+        const removed = retractPendingDispatchBlockedEvent(meshId, taskId, coordinatorDaemonId);
+        if (removed > 0) {
+            LOG.info('MeshQueue', `Retracted ${removed} stale dispatch-blocked event(s) for task ${taskId} (mesh ${meshId}) — its blocker resolved`);
+        }
+    } catch (e: any) {
+        LOG.warn('MeshQueue', `Failed to retract stale dispatch-blocked event for task ${taskId} (mesh ${meshId}): ${e?.message || e}`);
+    }
+}
+
 function actionableSkipGuidance(reason: string): { summary: string; nextAction: string } {
     if (reason === 'target_node_id_unmatched') return {
         summary: 'it is pinned to a target node id that matches no node in the mesh (the node may have been removed, or its id form does not resolve)',
@@ -652,6 +718,12 @@ function actionableSkipGuidance(reason: string): { summary: string; nextAction:
  *  event (so it is delivered actively, not only on poll). De-duped per (mesh, task, reason). */
 function notifyCoordinatorOfActionableSkip(meshId: string, taskId: string, reason: string | undefined, nodeId?: string): void {
     if (!isActionableSkipReason(reason)) return;
+    // FALSE-BLOCKER-CLONE-QUEUE chokepoint defense: a 'target_node_id_unmatched' skip whose
+    // node was cloned within the grace window is a TRANSIENT propagation/bootstrap gap that
+    // auto-clears, not a permanent routing miss — never page the coordinator for it (the
+    // reason classifier upstream already routes the common case to the transient reason; this
+    // is the single-funnel backstop for any path that still labels it as the permanent reason).
+    if (reason === 'target_node_id_unmatched' && isWithinCloneBootstrapGrace(readNonEmptyString(nodeId))) return;
     const dedupKey = `${meshId}:${taskId}`;
     if (lastActionableSkipNotified.get(dedupKey) === reason) return;
     lastActionableSkipNotified.set(dedupKey, reason!);
@@ -1095,9 +1167,19 @@ function markAutoLaunch(meshId: string, taskId: string, args: {
     // notification on any non-skip transition (started/completed) so a later genuine skip
     // re-notifies.
     if (args.status === 'skipped') {
-        notifyCoordinatorOfActionableSkip(meshId, taskId, args.reason, args.nodeId);
+        if (isActionableSkipReason(args.reason)) {
+            notifyCoordinatorOfActionableSkip(meshId, taskId, args.reason, args.nodeId);
+        } else if (args.reason === TRANSIENT_TARGET_NODE_BOOTSTRAP_PENDING_REASON) {
+            // FALSE-BLOCKER-CLONE-QUEUE (stale-event clear): the unmatch is now known to be a
+            // self-resolving clone/bootstrap window — retract any earlier actionable blocker we
+            // paged for this same task. Other transient/back-pressure reasons (cooldown, caps)
+            // intentionally do NOT retract: they can mask a still-standing real blocker.
+            retractActionableSkipIfPreviouslyNotified(meshId, taskId);
+        }
     } else {
-        lastActionableSkipNotified.delete(`${meshId}:${taskId}`);
+        // started/completed: the task is progressing — re-arm the de-dup ledger and retract
+        // any still-undelivered stale blocker for it.
+        retractActionableSkipIfPreviouslyNotified(meshId, taskId);
     }
 }
 
@@ -1264,11 +1346,22 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                         !task.targetNodeId || meshNodeIdMatches(n, task.targetNodeId));
                     return matched.length > 0 && matched.every((n: any) => n?.isLocalWorktree === true);
                 })();
+            // FALSE-BLOCKER-CLONE-QUEUE: an unmatched target pin is only a PERMANENT routing
+            // miss when the node is genuinely absent — a freshly cloned worktree whose
+            // inline-cache entry has not propagated here yet (or whose bootstrap is still
+            // running) is TRANSIENTLY unresolved and auto-claims shortly. Report that as the
+            // transient (non-actionable) reason so the coordinator is not paged with a false
+            // "actionable blocker — will NOT clear on its own". A genuinely dead node is neither
+            // bootstrap-running nor inside the clone grace window → stays 'target_node_id_unmatched'.
+            const targetTransientlyUnresolved = targetPinUnmatched
+                && isTargetNodeTransientlyUnresolved(mesh, task);
             markAutoLaunch(meshId, task.id, {
                 status: 'skipped',
                 reason: convergenceOntoWorktree
                     ? 'mesh_convergence_target_is_worktree'
-                    : (targetPinUnmatched ? 'target_node_id_unmatched' : 'no_node_satisfies_required_tags'),
+                    : targetTransientlyUnresolved
+                        ? TRANSIENT_TARGET_NODE_BOOTSTRAP_PENDING_REASON
+                        : (targetPinUnmatched ? 'target_node_id_unmatched' : 'no_node_satisfies_required_tags'),
                 nodeId: task.targetNodeId,
             });
             continue;