@adhdev/daemon-core 0.9.82-rc.317 → 0.9.82-rc.319

package/dist/providers/spec/adapter.d.ts

@@ -5,6 +5,16 @@ export interface TerminalAdapterOpts {
     args?: string[];
     cwd?: string;
     env?: Record<string, string>;
+    /**
+     * When true, `env` is already a COMPLETE, sanitized environment (the spawn
+     * planner merged + stripped process.env already) and must be passed to the
+     * PTY verbatim — NOT overlaid on top of process.env. Overlaying would
+     * re-introduce the npm_/PNPM_/parent-session keys the planner explicitly
+     * stripped, so the spec path's spawn env would diverge from the legacy
+     * path's. Defaults to false (legacy overlay behaviour) for any caller that
+     * still passes a partial env.
+     */
+    envIsComplete?: boolean;
     cols?: number;
     rows?: number;
     /** Coalesce screen snapshots: emit on_screen_changed at most this often. */

package/dist/providers/working-dir.d.ts

@@ -0,0 +1,17 @@
+/**
+ * working-dir — shared helpers for deriving display names from a session's
+ * working directory. Used by CLI/ACP provider instances to build session/tab
+ * titles.
+ */
+/**
+ * OS-aware basename of a working directory path.
+ *
+ * Splits on BOTH POSIX (`/`) and Windows (`\`) separators so a win32 path like
+ * `D:\gh\adhdev-cloud` resolves to `adhdev-cloud` even when the daemon's own
+ * `path.basename` is POSIX-only — and a path that mixes separators still works.
+ * Trailing separators and root-only paths fall back to `'session'`, matching
+ * the historical `.split('/').filter(Boolean).pop() || 'session'` behavior.
+ *
+ * Mirrors the web dashboard's `getWorkspaceName` (`ws.split(/[/\\]/)`).
+ */
+export declare function workingDirBasename(p: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.317",
+  "version": "0.9.82-rc.319",
   "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.317",
+    "@adhdev/mesh-shared": "0.9.82-rc.319",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

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

@@ -34,22 +34,69 @@ export function resolveCliSpawnPlan(options: {
     const configuredCommand = typeof runtimeSettings.executablePath === 'string' && runtimeSettings.executablePath.trim()
         ? runtimeSettings.executablePath.trim()
         : spawnConfig.command;
-    const binaryPath = findBinary(configuredCommand);
+    return resolveCliSpawnPlanFromParts({
+        command: configuredCommand,
+        baseArgs: spawnConfig.args,
+        shell: spawnConfig.shell,
+        baseEnv: spawnConfig.env,
+        workingDir,
+        extraArgs,
+        extraEnv,
+    });
+}
+
+/**
+ * Cols/rows for a PTY spawn. Defaults to the session-host terminal size; the
+ * spec driver may override per-instance.
+ */
+export interface CliSpawnGeometry {
+    cols?: number;
+    rows?: number;
+}
+
+/**
+ * Core spawn-plan resolution from already-flattened spawn parts — the single
+ * source of truth for binary resolution (findBinary: PATH + npm-global / Node
+ * dir fallback), `{{workingDir}}` token substitution, shell wrapping
+ * (script-shims / non-absolute / non-native binaries), and env sanitization +
+ * TERMINAL_CWD. Both the legacy provider-module path (resolveCliSpawnPlan) and
+ * the spec/FSM path (FsmDriver.buildAdapterOpts) feed into this so the two
+ * spawn paths can never diverge.
+ */
+export function resolveCliSpawnPlanFromParts(options: {
+    /** Raw command from the spec/provider (`binary` / `spawn.command`), or an
+     *  operator-configured executable path override. */
+    command: string;
+    /** Base launch args declared by the spec/provider (`spawn_args` /
+     *  `spawn.args`). */
+    baseArgs?: string[];
+    /** When true, always wrap the launch in a login shell. */
+    shell?: boolean;
+    /** Base env declared by the spec/provider (`env` / `spawn.env`). */
+    baseEnv?: Record<string, string>;
+    workingDir: string;
+    /** Per-launch extra args (e.g. resume session id) appended after baseArgs. */
+    extraArgs?: string[];
+    extraEnv?: Record<string, string>;
+    geometry?: CliSpawnGeometry;
+}): CliSpawnPlan {
+    const { command, baseArgs, shell, baseEnv, workingDir, extraArgs, extraEnv, geometry } = options;
+    const binaryPath = findBinary(command);
     const isWin = os.platform() === 'win32';
-    const allArgs = [...spawnConfig.args, ...extraArgs].map((arg) =>
+    const allArgs = [...(baseArgs ?? []), ...(extraArgs ?? [])].map((arg) =>
         typeof arg === 'string' ? arg.replace(/\{\{workingDir\}\}/g, workingDir) : arg,
     );
 
     let shellCmd: string;
     let shellArgs: string[];
     const useShellUnix = !isWin && (
-        !!spawnConfig.shell
+        !!shell
         || !path.isAbsolute(binaryPath)
         || isScriptBinary(binaryPath)
         || !looksLikeMachOOrElf(binaryPath)
     );
     const isCmdShim = isWin && /\.(cmd|bat)$/i.test(binaryPath);
-    const useShellWin = !!spawnConfig.shell
+    const useShellWin = !!shell
         || isCmdShim
         || !path.isAbsolute(binaryPath)
         || isScriptBinary(binaryPath);
@@ -68,7 +115,7 @@ export function resolveCliSpawnPlan(options: {
         shellArgs = allArgs;
     }
 
-    const env = buildCliSpawnEnv(process.env, { ...(spawnConfig.env || {}), ...(extraEnv || {}) });
+    const env = buildCliSpawnEnv(process.env, { ...(baseEnv || {}), ...(extraEnv || {}) });
     // Some CLI agents, notably Hermes, route their tools through TERMINAL_CWD
     // rather than process.cwd(). Keep the generic ADHDev launch workspace as
     // the single source of truth so PTY cwd and tool cwd cannot diverge.
@@ -82,8 +129,8 @@ export function resolveCliSpawnPlan(options: {
         isWin,
         useShell,
         ptyOptions: {
-            cols: DEFAULT_SESSION_HOST_COLS,
-            rows: DEFAULT_SESSION_HOST_ROWS,
+            cols: geometry?.cols ?? DEFAULT_SESSION_HOST_COLS,
+            rows: geometry?.rows ?? DEFAULT_SESSION_HOST_ROWS,
             cwd: workingDir,
             env,
         },

package/src/cli-adapters/resolve-executable.ts

@@ -6,6 +6,42 @@ import * as path from 'path';
 // need a cmd.exe wrapper).
 const DIRECT_EXEC_EXT = new Set(['.exe', '.com']);
 
+// Executable extensions to probe when scanning a directory ourselves, ordered
+// most-directly-launchable first. node-pty's ConPTY backend launches an
+// absolute `.cmd`/`.bat` shim fine (verified) — it only fails to *resolve* a
+// bare command against an incomplete PATH — so once we hand it an absolute
+// path, a `.cmd` shim works just as well as a real `.exe`.
+const WIN_EXEC_EXT = ['.exe', '.com', '.cmd', '.bat'];
+
+/**
+ * Resolve a bare command against well-known global-bin directories that are
+ * frequently NOT on the daemon's inherited PATH, so `where` (which only
+ * searches PATH) misses them. A daemon running under one Node install (e.g.
+ * nvm) never sees another npm prefix's bin dir — notably npm's Windows default
+ * prefix at %APPDATA%\npm, where `npm i -g @openai/codex` lands. Returns an
+ * absolute path on the first hit, or null. Mirrors findBinary()'s extraDirs in
+ * provider-cli-shared.ts; kept inline here so this lightweight module (loaded
+ * by pty-transport) need not pull in the heavier shared module.
+ */
+function resolveWin32GlobalBin(trimmed: string): string | null {
+  // Only resolve a bare command name — anything with a path separator is the
+  // caller's explicit location and must not be re-pointed at a global bin dir.
+  if (path.isAbsolute(trimmed) || trimmed.includes('/') || trimmed.includes('\\')) {
+    return null;
+  }
+  const extraDirs: string[] = [];
+  if (process.env.APPDATA) extraDirs.push(path.join(process.env.APPDATA, 'npm'));
+  try { extraDirs.push(path.dirname(process.execPath)); } catch { /* best-effort */ }
+  for (const dir of extraDirs) {
+    if (!dir) continue;
+    for (const ext of WIN_EXEC_EXT) {
+      const full = path.join(dir, trimmed + ext);
+      if (existsSync(full)) return full;
+    }
+  }
+  return null;
+}
+
 /**
  * Resolve a launch command to an absolute executable path on Windows.
  *
@@ -39,7 +75,16 @@ export function resolveWin32Executable(command: string): string {
       return direct || matches[0] || command;
     }
   } catch {
-    // `where` not found / non-zero exit — fall through to original command.
+    // `where` not found / non-zero exit — fall through to the global-bin scan.
   }
+
+  // `where` found nothing on PATH. Before giving up (and letting node-pty crash
+  // with "File not found:" on the bare command), search npm's off-PATH global
+  // bin dir(s). This is the codex case: `npm i -g @openai/codex` installs to
+  // %APPDATA%\npm, which is absent from a nvm-launched daemon's PATH, so a spec
+  // binary of "codex" never resolved and the spawn ENOENT'd.
+  const globalBin = resolveWin32GlobalBin(trimmed);
+  if (globalBin) return globalBin;
+
   return command;
 }

package/src/detection/cli-detector.ts

@@ -12,6 +12,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { existsSync } from 'fs';
 import type { ProviderLoader } from '../providers/provider-loader.js';
+import { findBinary } from '../cli-adapters/provider-cli-shared.js';
 
 export interface CLIInfo {
     id: string;
@@ -57,6 +58,29 @@ function resolveCommandPath(command: string): string | null {
     return null;
 }
 
+/**
+ * Resolve a CLI command to an absolute path for install detection.
+ * Order: explicit path → PATH (`where`/`which`) → well-known global-bin dirs
+ * (e.g. %APPDATA%\npm) via the shared spawn-layer findBinary.
+ *
+ * The final step keeps detection consistent with the spawn layer: findBinary
+ * already searches npm's default Windows prefix at %APPDATA%\npm (where
+ * `npm i -g @openai/codex` lands), so a CLI installed under an npm prefix that
+ * is NOT on the daemon's inherited PATH is detected as installed instead of
+ * being blocked at the launch gate. findBinary returns a bare "<name>.cmd"
+ * (non-absolute) when nothing is found, so we only accept an absolute path
+ * that actually exists.
+ */
+async function resolveDetectionPath(command: string, whichCmd: string): Promise<string | null> {
+    const explicitPath = resolveCommandPath(command);
+    if (explicitPath) return explicitPath;
+    const whichResult = await execAsync(`${whichCmd} ${shellQuote(command)}`);
+    if (whichResult) return whichResult.split('\n')[0];
+    const resolved = findBinary(command);
+    if (path.isAbsolute(resolved) && existsSync(resolved)) return resolved;
+    return null;
+}
+
 /** Run a shell command with timeout, returning stdout or null on failure */
 function execAsync(cmd: string, timeoutMs = 5000): Promise<string | null> {
     return new Promise((resolve) => {
@@ -97,11 +121,8 @@ export async function detectCLIs(
     const results = await Promise.all(
         cliList.map(async (cli): Promise<CLIInfo> => {
             try {
-                const explicitPath = resolveCommandPath(cli.command);
-                const pathResult = explicitPath || await execAsync(`${whichCmd} ${shellQuote(cli.command)}`);
-                if (!pathResult) return { ...cli, installed: false };
-
-                const firstPath = explicitPath || pathResult.split('\n')[0];
+                const firstPath = await resolveDetectionPath(cli.command, whichCmd);
+                if (!firstPath) return { ...cli, installed: false };
 
                 // Get version (parallel with other checks)
                 let version: string | undefined;
@@ -148,10 +169,8 @@ export async function detectCLI(
             const platform = os.platform();
             const whichCmd = platform === 'win32' ? 'where' : 'which';
             try {
-                const explicitPath = resolveCommandPath(target.command);
-                const pathResult = explicitPath || await execAsync(`${whichCmd} ${shellQuote(target.command)}`);
-                if (!pathResult) return null;
-                const firstPath = explicitPath || pathResult.split('\n')[0];
+                const firstPath = await resolveDetectionPath(target.command, whichCmd);
+                if (!firstPath) return null;
                 let version: string | undefined;
                 if (options?.includeVersion !== false) {
                     const versionCommands = [

package/src/detection/ide-detector.ts

@@ -14,6 +14,7 @@ import { existsSync, statSync } from 'fs';
 import { platform, homedir } from 'os';
 import * as path from 'path';
 import type { ProviderLoader } from '../providers/provider-loader.js';
+import { isKnownWin32GuiExe, readWin32IdeVersionFromDisk } from './win32-ide-version.js';
 
 // ─── Types ──────────────────────────────────────
 
@@ -95,7 +96,28 @@ function findCliCommand(command: string): string | null {
     return null;
 }
 
-async function getIdeVersion(cliCommand: string): Promise<string | null> {
+/**
+ * Resolve an IDE version on demand (NOT at boot).
+ *
+ * Order of preference, all spawn-free where possible:
+ *  1. win32: read the bundled product.json/package.json next to the exe.
+ *  2. Otherwise spawn `<cli> --version` — but ONLY when the binary is not a
+ *     known GUI executable (the #4 guard), so we never boot an IDE window.
+ *
+ * `win32ProcessNames` is provider.json `processNames.win32` (type → exe names),
+ * used to recognise GUI executables. Callers that have a ProviderLoader can
+ * pass `providerLoader.getWinProcessNames()`.
+ */
+export async function getIdeVersion(
+    cliCommand: string,
+    win32ProcessNames: Record<string, string[]> = {},
+): Promise<string | null> {
+    if (platform() === 'win32') {
+        const fromDisk = readWin32IdeVersionFromDisk(cliCommand);
+        if (fromDisk) return fromDisk;
+        // Refuse to spawn a known GUI exe — it would launch the IDE window.
+        if (isKnownWin32GuiExe(cliCommand, win32ProcessNames)) return null;
+    }
     try {
         const { stdout } = await execAsync(`"${cliCommand}" --version`, {
             encoding: 'utf-8',
@@ -162,7 +184,14 @@ export async function detectIDEs(providerLoader?: ProviderLoader): Promise<IDEIn
         const installed = os === 'darwin'
             ? !!(resolvedCli || appPath)
             : !!resolvedCli;
-        const version = resolvedCli ? await getIdeVersion(resolvedCli) : null;
+        // Boot-time IDE detection must NOT spawn `<cli> --version`. On Windows
+        // the resolved "CLI" is frequently the GUI Electron exe (case-insensitive
+        // FS matches `...\cursor\cursor.exe` against `Cursor.exe`), and running it
+        // with `--version` boots the IDE window. `installed` is decided purely by
+        // existsSync above, and the dashboard drops `version` anyway — the only
+        // real version consumer is provider-loader.resolve() at CDP attach time,
+        // which fetches the version lazily. So leave it null here.
+        const version: string | null = null;
 
         results.push({
             id: def.id,

package/src/detection/win32-ide-version.ts

@@ -0,0 +1,106 @@
+/**
+ * ADHDev — Windows IDE version detection (execution-free)
+ *
+ * On Windows the resolved "CLI" for a VS Code fork (Cursor, Antigravity, …)
+ * frequently resolves to the GUI Electron executable itself, because the
+ * case-insensitive filesystem matches `...\cursor\cursor.exe` against the
+ * real `Cursor.exe`. Running `<that exe> --version` boots the GUI instead of
+ * printing a version (Electron ignores the unknown flag and opens a window).
+ *
+ * To learn the version WITHOUT spawning anything, we read the bundled
+ * `product.json` / `package.json` that ship next to the executable. VS Code
+ * forks embed their version there. This is a pure filesystem read.
+ *
+ * It also exposes a guard so any remaining `--version` exec path can refuse to
+ * spawn a binary that is a known GUI executable for an IDE provider.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Candidate locations for the version manifest relative to the GUI exe dir.
+ * VS Code forks place `resources/app/{product,package}.json` next to the exe.
+ */
+function manifestCandidates(exeDir: string): string[] {
+  return [
+    path.join(exeDir, 'resources', 'app', 'product.json'),
+    path.join(exeDir, 'resources', 'app', 'package.json'),
+    // Some packagings keep product.json one level up.
+    path.join(exeDir, 'product.json'),
+  ];
+}
+
+function parseVersionFromManifest(raw: string): string | null {
+  try {
+    const json = JSON.parse(raw) as Record<string, unknown>;
+    // product.json forks expose the IDE's own version here; package.json
+    // exposes the upstream VS Code engine version. Prefer the former.
+    const candidate = json.version;
+    if (typeof candidate === 'string' && candidate.trim()) {
+      return candidate.trim();
+    }
+  } catch {
+    /* not valid JSON — ignore */
+  }
+  return null;
+}
+
+/**
+ * Read an IDE version from disk (no process spawn).
+ *
+ * @param exePath Absolute path to the GUI executable (or any path inside the
+ *   IDE install dir — we read the manifest relative to its directory).
+ * @returns The version string, or null if it could not be determined.
+ */
+export function readWin32IdeVersionFromDisk(exePath: string): string | null {
+  if (!exePath) return null;
+  let exeDir: string;
+  try {
+    exeDir = fs.statSync(exePath).isDirectory() ? exePath : path.dirname(exePath);
+  } catch {
+    exeDir = path.dirname(exePath);
+  }
+  for (const candidate of manifestCandidates(exeDir)) {
+    try {
+      if (!fs.existsSync(candidate)) continue;
+      const version = parseVersionFromManifest(fs.readFileSync(candidate, 'utf-8'));
+      if (version) return version;
+    } catch {
+      /* ignore unreadable manifest */
+    }
+  }
+  return null;
+}
+
+/**
+ * True when `binPath` resolves to a known GUI executable for some IDE.
+ *
+ * Used as a safety net: any code path about to run `<bin> --version` must skip
+ * the spawn when the binary is actually the GUI Electron exe, since that would
+ * launch the IDE window. Comparison is case-insensitive on the basename
+ * (Windows filesystem semantics) against every provider's `processNames.win32`.
+ *
+ * @param binPath Resolved binary path that would be exec'd.
+ * @param win32ProcessNames Map of provider type → list of GUI exe names
+ *   (from provider.json `processNames.win32`, e.g. `["Cursor.exe"]`).
+ */
+export function isKnownWin32GuiExe(
+  binPath: string | null | undefined,
+  win32ProcessNames: Record<string, string[]>,
+): boolean {
+  if (!binPath) return false;
+  // Use win32 basename semantics regardless of host OS: this matches Windows
+  // paths even when the daemon-core test/CI host is POSIX (where `/` is the
+  // only separator). On the real win32 target this is identical to basename().
+  const base = path.win32.basename(binPath).toLowerCase();
+  if (!base.endsWith('.exe')) return false;
+  for (const names of Object.values(win32ProcessNames)) {
+    for (const name of names) {
+      if (typeof name === 'string' && name.toLowerCase() === base) {
+        return true;
+      }
+    }
+  }
+  return false;
+}

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

@@ -380,6 +380,16 @@ const autoLaunchInProgress = new Set<string>();
 const autoLaunchCooldownUntil = new Map<string, number>();
 const AUTO_LAUNCH_COOLDOWN_MS = 5_000;
 
+// De-dup for repeated `skipped` ledger noise: the reconcile loop re-runs the queue
+// trigger every 4s, so a task that can't be claimed (e.g. a remote node with no
+// transport, or a node under cooldown) would otherwise append an identical
+// session_auto_launch{phase:'skipped'} entry on every tick — flooding the ledger.
+// We suppress a `skipped` ledger append when the immediately-prior recorded event
+// for that task was the SAME (phase, reason). Any non-skip phase (started/failed/
+// completed) or a changed reason resets the de-dup so real transitions still record.
+const lastAutoLaunchLedgerKey = new Map<string, string>();
+const AUTO_LAUNCH_LEDGER_DEDUP_MAX = 2000;
+
 function sweepExpiredCooldowns(): void {
     const now = Date.now();
     for (const [key, until] of autoLaunchCooldownUntil) {
@@ -457,7 +467,9 @@ function isLaunchableNode(node: any): boolean {
     return health === 'online' || health === 'unknown';
 }
 
-function localAutoLaunchSkipReason(node: any): string | null {
+/** Whether a mesh node's daemon/machine identity resolves to THIS coordinator daemon
+ *  (i.e. the queue session can be spawned by a direct local `launch_cli`). */
+function isLocalAutoLaunchNode(node: any): boolean {
     const daemonId = readNonEmptyString(node?.daemonId);
     const machineId = readNonEmptyString(node?.machineId);
     const appConfig = loadConfig();
@@ -466,17 +478,44 @@ function localAutoLaunchSkipReason(node: any): string | null {
     const standaloneDaemonId = localMachineId ? `standalone_${localMachineId}` : '';
 
     const daemonMatchesLocal = !daemonId || daemonId === cloudDaemonId || daemonId === standaloneDaemonId;
-    const machineMatchesLocal = !machineId || (localMachineId && machineId === localMachineId);
+    const machineMatchesLocal = !machineId || (!!localMachineId && machineId === localMachineId);
 
     if (node?.isLocalWorktree === true) {
-        return daemonMatchesLocal && machineMatchesLocal ? null : 'remote_auto_launch_unsupported';
+        return daemonMatchesLocal && machineMatchesLocal;
     }
-
     if (daemonId || machineId) {
-        return daemonMatchesLocal && machineMatchesLocal ? null : 'remote_auto_launch_unsupported';
+        return daemonMatchesLocal && machineMatchesLocal;
     }
+    return true;
+}
 
-    return null;
+/**
+ * Resolve how a pending queue task should be auto-launched onto a node.
+ *
+ * - `local`: spawn directly on this daemon via cliManager.handleCliCommand('launch_cli').
+ * - `remote`: forward `launch_cli` to the node's daemon via dispatchMeshCommand
+ *   (mirrors what mesh_launch_session does). Requires dispatchMeshCommand AND a
+ *   resolvable coordinator daemonId for relay-safe completion routing.
+ * - `skip`: not launchable from here — carries the reason (e.g. a remote node with
+ *   no dispatch transport, or no coordinator daemonId to stamp).
+ */
+function resolveAutoLaunchTarget(components: DaemonComponents, node: any): {
+    mode: 'local' | 'remote' | 'skip';
+    reason?: string;
+    daemonId?: string;
+    coordinatorDaemonId?: string;
+} {
+    if (isLocalAutoLaunchNode(node)) return { mode: 'local' };
+
+    // Remote node. Forwarding the launch is possible only with a dispatch transport
+    // (cloud mode) plus a coordinator daemonId to stamp into the worker so completion
+    // events route back here. Without either, fall back to a graceful skip.
+    const daemonId = readNonEmptyString(node?.daemonId);
+    if (!daemonId) return { mode: 'skip', reason: 'remote_auto_launch_unsupported' };
+    if (!components.dispatchMeshCommand) return { mode: 'skip', reason: 'remote_auto_launch_unsupported' };
+    const coordinatorDaemonId = readNonEmptyString(loadConfig().machineId);
+    if (!coordinatorDaemonId) return { mode: 'skip', reason: 'remote_auto_launch_no_coordinator_daemon_id' };
+    return { mode: 'remote', daemonId, coordinatorDaemonId };
 }
 
 function activeAssignedCount(meshId: string): number {
@@ -632,6 +671,20 @@ function recordAutoLaunchEvent(meshId: string, args: {
     reason?: string;
     error?: string;
 }) {
+    // Suppress consecutive identical `skipped` entries for the same task (4s reconcile
+    // re-trigger noise). Non-skip phases and changed reasons always record and reset
+    // the de-dup so genuine state transitions remain visible in the ledger.
+    const dedupKey = `${meshId}:${args.taskId}`;
+    const currentSig = `${args.phase}|${args.reason || ''}`;
+    if (args.phase === 'skipped' && lastAutoLaunchLedgerKey.get(dedupKey) === currentSig) {
+        return;
+    }
+    lastAutoLaunchLedgerKey.set(dedupKey, currentSig);
+    if (lastAutoLaunchLedgerKey.size > AUTO_LAUNCH_LEDGER_DEDUP_MAX) {
+        // Bound memory: drop the oldest insertion (Map preserves insertion order).
+        const oldest = lastAutoLaunchLedgerKey.keys().next().value;
+        if (oldest !== undefined) lastAutoLaunchLedgerKey.delete(oldest);
+    }
     try {
         appendLedgerEntry(meshId, {
             kind: 'session_auto_launch',
@@ -827,9 +880,13 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                 markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_not_launch_ready', nodeId });
                 continue;
             }
-            const localSkipReason = localAutoLaunchSkipReason(node);
-            if (localSkipReason) {
-                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: localSkipReason, nodeId });
+            const launchTarget = resolveAutoLaunchTarget(components, node);
+            if (launchTarget.mode === 'skip') {
+                // Remote node we can't reach (no transport / no coordinator daemonId).
+                // Set a cooldown so the 4s reconcile loop doesn't re-attempt this node
+                // every tick; the de-dup'd skip ledger keeps it diagnosable without flood.
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: launchTarget.reason || 'auto_launch_unavailable', nodeId });
+                autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS); sweepExpiredCooldowns();
                 continue;
             }
             // Write tasks keep the one-active-per-node invariant (worktree isolation);
@@ -865,23 +922,68 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                     continue;
                 }
 
+                // Shared worker-launch envelope. For a local node it spawns directly on this
+                // daemon; for a remote node the identical command is forwarded to the node's
+                // daemon (mirrors mesh_launch_session), with the coordinator daemonId stamped
+                // so the worker's completion events route back to this coordinator.
+                const launchSettings: Record<string, unknown> = {
+                    // Worker launch envelope: role + mesh context so worker can route completion events.
+                    role: 'worker',
+                    meshNodeFor: meshId,
+                    meshNodeId: nodeId,
+                    spawnedSessionVisibility: mesh?.policy?.spawnedSessionVisibility || 'hidden',
+                    // Coordinator-dispatched worker: auto-approve unless mesh/node policy
+                    // opts out (default true). Lands in settingsOverride and beats the
+                    // global per-provider-type autoApprove config (see shouldAutoApprove).
+                    autoApprove: resolveDelegatedWorkerAutoApprove(mesh?.policy, node?.policy),
+                    launchedByCoordinator: true,
+                    autoLaunchedForQueueTaskId: task.id,
+                };
+
+                if (launchTarget.mode === 'remote') {
+                    // Relay-safe completion routing: stamp the coordinator anchor the same way
+                    // mesh_launch_session does so the worker forwards events back to this daemon.
+                    const remoteSettings: Record<string, unknown> = {
+                        ...launchSettings,
+                        meshCoordinatorDaemonId: launchTarget.coordinatorDaemonId,
+                        meshCoordinatorNodeId: nodeId,
+                    };
+                    markAutoLaunch(meshId, task.id, { status: 'started', nodeId, providerType: resolved.providerType });
+                    let launchResult: any;
+                    try {
+                        launchResult = await components.dispatchMeshCommand!(launchTarget.daemonId!, 'launch_cli', {
+                            cliType: resolved.providerType,
+                            dir: node.workspace,
+                            settings: remoteSettings,
+                        });
+                    } catch (e: any) {
+                        markAutoLaunch(meshId, task.id, { status: 'failed', reason: `remote_launch_dispatch_failed: ${e?.message || String(e)}`, nodeId, providerType: resolved.providerType });
+                        autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS); sweepExpiredCooldowns();
+                        return false;
+                    }
+                    const payload = (launchResult && typeof launchResult === 'object' && 'payload' in launchResult && launchResult.payload && typeof launchResult.payload === 'object')
+                        ? launchResult.payload
+                        : launchResult;
+                    if (!payload?.success) {
+                        const reason = readNonEmptyString(payload?.error) || 'remote_launch_cli_failed';
+                        markAutoLaunch(meshId, task.id, { status: 'failed', reason, nodeId, providerType: resolved.providerType });
+                        autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS); sweepExpiredCooldowns();
+                        return false;
+                    }
+                    // Remote launch is async: the worker session will register and emit agent:ready,
+                    // which (forwarded back here) drives the claim via the normal event path / PHASE 1
+                    // reconcile. Set a cooldown so the 4s loop doesn't re-launch before that lands.
+                    const remoteSessionId = readNonEmptyString(payload.sessionId) || readNonEmptyString(payload.id) || readNonEmptyString(payload.runtimeSessionId);
+                    markAutoLaunch(meshId, task.id, { status: 'completed', nodeId, providerType: resolved.providerType, sessionId: remoteSessionId || undefined });
+                    autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS); sweepExpiredCooldowns();
+                    return true;
+                }
+
                 markAutoLaunch(meshId, task.id, { status: 'started', nodeId, providerType: resolved.providerType });
                 const launchResult: any = await components.cliManager.handleCliCommand('launch_cli', {
                     cliType: resolved.providerType,
                     dir: node.workspace,
-                    settings: {
-                        // Worker launch envelope: role + mesh context so worker can route completion events.
-                        role: 'worker',
-                        meshNodeFor: meshId,
-                        meshNodeId: nodeId,
-                        spawnedSessionVisibility: mesh?.policy?.spawnedSessionVisibility || 'hidden',
-                        // Coordinator-dispatched worker: auto-approve unless mesh/node policy
-                        // opts out (default true). Lands in settingsOverride and beats the
-                        // global per-provider-type autoApprove config (see shouldAutoApprove).
-                        autoApprove: resolveDelegatedWorkerAutoApprove(mesh?.policy, node?.policy),
-                        launchedByCoordinator: true,
-                        autoLaunchedForQueueTaskId: task.id,
-                    },
+                    settings: launchSettings,
                 });
                 if (!launchResult?.success) {
                     const reason = launchResult?.error || 'launch_cli_failed';