@adhdev/daemon-core 1.0.18-rc.8 → 1.0.18

package/src/commands/upgrade-helper.ts

@@ -144,19 +144,68 @@ function resolveInstallPrefixFromPackageRoot(packageRoot: string, packageName: s
   return maybeLibDir;
 }
 
+// True when `prefix` is the bin dir of a portable Node 22 the installer manages
+// under ~/.adhdev/tools/node22/<node-vX>/. A `npm i -g adhdev` run while that
+// portable node is the active `node` installs adhdev into node's own default
+// global prefix (= that dir) — a "legacy node22-prefix" install that lives at
+// the FRONT of PATH (Enable-NodePath prepends node22) and shadows the canonical
+// dispatcher shims in ~/.adhdev/npm-global. Because self-upgrade reuses the
+// running prefix, that install then re-installs into the same node22 dir forever
+// and never converts to the dispatcher. Detecting it lets us force convergence.
+function isPortableNode22Prefix(prefix: string | null, homeDir: string): boolean {
+  if (!prefix) return false;
+  const portableRoot = path.join(homeDir, '.adhdev', 'tools', 'node22');
+  const normalizedPrefix = path.resolve(prefix).replace(/[\\/]+$/, '').toLowerCase();
+  const normalizedRoot = path.resolve(portableRoot).replace(/[\\/]+$/, '').toLowerCase();
+  return normalizedPrefix === normalizedRoot || normalizedPrefix.startsWith(`${normalizedRoot}${path.sep.toLowerCase()}`);
+}
+
+// Redirect a legacy node22-prefix install to the canonical dispatcher install
+// root so resolveWindowsInstallerLayout accepts it and the atomic-upgrade
+// publishes the ~/.adhdev/npm-global pointer + shims. Prefer the version the
+// dispatcher pointer already names (so we sit on the real active dispatcher
+// prefix); otherwise synthesize a stable migration sentinel under npm-installs.
+// resolveWindowsInstallerLayout only requires a `npm-installs/version-*` path —
+// performWindowsAtomicUpgrade stages a fresh version- prefix of its own and uses
+// this only as the "old prefix" to stop/clean, so a non-existent path is a no-op.
+function canonicalDispatcherInstallPrefix(homeDir: string): string {
+  const installRoot = path.join(homeDir, '.adhdev', 'npm-installs');
+  const pointerPath = path.join(homeDir, '.adhdev', 'npm-global', '.adhdev-current');
+  try {
+    const activeVersion = fs.readFileSync(pointerPath, 'utf8').trim();
+    if (activeVersion.startsWith('version-')) return path.join(installRoot, activeVersion);
+  } catch {
+    // No dispatcher pointer yet (first migration off the legacy layout).
+  }
+  return path.join(installRoot, 'version-legacy-migrate');
+}
+
 export function resolveCurrentGlobalInstallSurface(options: {
   packageName: string;
   currentCliPath?: string;
   nodeExecutable?: string;
   platform?: NodeJS.Platform;
+  homeDir?: string;
 }): CurrentGlobalInstallSurface {
   const packageRoot = findCurrentPackageRoot(options.currentCliPath || process.argv[1], options.packageName);
   const npmInvocation = resolveSiblingNpmInvocation(options.nodeExecutable || process.execPath, options.platform);
+  const platform = options.platform || process.platform;
+  const homeDir = options.homeDir || os.homedir();
+  let installPrefix = packageRoot ? resolveInstallPrefixFromPackageRoot(packageRoot, options.packageName) : null;
+  // FIX C: on Windows, never let a self-upgrade perpetuate the legacy
+  // node22-prefix install. If the running adhdev lives under ~/.adhdev/tools/
+  // node22, force the install onto the canonical dispatcher prefix so the update
+  // converges to the ~/.adhdev/npm-global pointer + shims. Scoped to win32 AND a
+  // tools/node22 prefix so npm-linked dev / standalone / real dispatcher installs
+  // are untouched.
+  if (platform === 'win32' && isPortableNode22Prefix(installPrefix, homeDir)) {
+    installPrefix = canonicalDispatcherInstallPrefix(homeDir);
+  }
   return {
     npmExecutable: npmInvocation.executable,
     npmArgsPrefix: npmInvocation.argsPrefix,
     packageRoot,
-    installPrefix: packageRoot ? resolveInstallPrefixFromPackageRoot(packageRoot, options.packageName) : null,
+    installPrefix,
     execOptions: npmInvocation.execOptions,
   };
 }
@@ -560,22 +609,36 @@ async function runDaemonUpgradeHelper(payload: DaemonUpgradeHelperPayload): Prom
       );
     }
 
-    await performWindowsAtomicUpgrade({
-      layout: windowsInstallerLayout,
-      packageName: payload.packageName,
-      targetVersion: payload.targetVersion,
-      portableNode,
-      excludePids: upgradePids,
-      hooks: createDefaultWindowsAtomicHooks({
+    try {
+      await performWindowsAtomicUpgrade({
+        layout: windowsInstallerLayout,
         packageName: payload.packageName,
         targetVersion: payload.targetVersion,
-        npmCliPath,
-        restartArgv,
-        cwd: payload.cwd || process.cwd(),
-        env: Object.fromEntries(Object.entries(process.env).filter(([key]) => key !== UPGRADE_HELPER_ENV)),
-        log: appendUpgradeLog,
-      }),
-    });
+        portableNode,
+        excludePids: upgradePids,
+        hooks: createDefaultWindowsAtomicHooks({
+          packageName: payload.packageName,
+          targetVersion: payload.targetVersion,
+          npmCliPath,
+          restartArgv,
+          cwd: payload.cwd || process.cwd(),
+          env: Object.fromEntries(Object.entries(process.env).filter(([key]) => key !== UPGRADE_HELPER_ENV)),
+          log: appendUpgradeLog,
+        }),
+      });
+    } catch (error: any) {
+      // performWindowsAtomicUpgrade already rolled the pointer/shims back to the
+      // prior version before rethrowing. Without a durable notice that rollback
+      // was silent — the daemon simply kept running the old version (the rc.6
+      // stuck-upgrade defect). Leave an actionable last-error file naming the
+      // target that failed its health/version gate.
+      emitUpgradeFailureNotice([
+        `adhdev ${payload.packageName}@${payload.targetVersion} upgrade failed and was rolled back: ${error?.message || String(error)}`,
+        `Previous version preserved (active prefix: ${windowsInstallerLayout.activePrefix}).`,
+        'See daemon-upgrade.log for the full install/health trace. The next daemon start will retry.',
+      ]);
+      throw error;
+    }
     try { fs.unlinkSync(getUpgradeFailureNoticePath()); } catch { /* no previous failure notice */ }
     appendUpgradeLog('Installer-managed Windows atomic upgrade completed');
     return;

package/src/commands/windows-atomic-upgrade.ts

@@ -8,6 +8,53 @@ const POINTER_NAME = '.adhdev-current';
 const STABLE_FILES = [POINTER_NAME, 'adhdev.cmd', 'adhdev.ps1', 'adhdev'] as const;
 const DEFAULT_HEALTH_PORT = 19222;
 
+// How long to wait for the replacement daemon to report the target version
+// before deterministically rolling back. status.version only appears AFTER the
+// daemon fully boots its components — a separate session-host process, node-pty/
+// conpty, CDP, and providers — which on a Windows cold self-upgrade routinely
+// exceeds the old 30s ceiling. Live Windows logs showed every rollback clustering
+// at 33–35s (30s timeout + poll overhead), so the gate was tripping on slow-boot,
+// not on genuine failure. 120s reflects real Windows self-upgrade cold-start time.
+export const DEFAULT_HEALTH_TIMEOUT_MS = 120_000;
+
+function fetchLocalJson(port: number, pathname: string): Promise<{ ok: boolean; body: string }> {
+  return new Promise((resolve) => {
+    const req = http.get(`http://127.0.0.1:${port}${pathname}`, { timeout: 1500 }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => resolve({ ok: res.statusCode === 200, body }));
+    });
+    req.on('timeout', () => req.destroy());
+    req.on('error', () => resolve({ ok: false, body: '' }));
+  });
+}
+
+// Liveness + pid identity: GET /health returns {ok, pid, wsPath, port}.
+async function fetchLocalHealth(port: number): Promise<{ ok: boolean; pid?: number }> {
+  const { ok, body } = await fetchLocalJson(port, '/health');
+  if (!ok) return { ok: false };
+  try {
+    const pid = Number(JSON.parse(body)?.pid);
+    return { ok: true, pid: Number.isFinite(pid) ? pid : undefined };
+  } catch {
+    return { ok: false };
+  }
+}
+
+// Running version: GET /api/v1/status exposes it at payload.status.version.
+// /health carries no version, so the upgrade version gate must read this.
+async function fetchLocalStatusVersion(port: number): Promise<string | undefined> {
+  const { ok, body } = await fetchLocalJson(port, '/api/v1/status');
+  if (!ok) return undefined;
+  try {
+    const version = (JSON.parse(body) as { status?: { version?: unknown } })?.status?.version;
+    return typeof version === 'string' ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 // Markers that identify a Node process as ADHDev-owned when its command line
 // also lives under a versioned install prefix. This deliberately excludes
 // arbitrary user scripts that happen to be located under ~/.adhdev.
@@ -272,10 +319,39 @@ function snapshotStableFiles(stablePrefix: string): Map<string, FileSnapshot> {
   return snapshots;
 }
 
-function restoreStableFiles(snapshots: Map<string, FileSnapshot>): void {
+// Rollback must never leave PATH `adhdev` broken. Two failure modes made the old
+// "restore-or-delete" logic dangerous:
+//   1. If a stable shim (adhdev.cmd/.ps1/no-ext) did not exist at snapshot time —
+//      a first/partial install, or a stable tree that never had the launcher —
+//      deleting it leaves `where.exe adhdev` / `spawnSync('adhdev')` resolving to
+//      nothing (ENOENT). `adhdev doctor` then reports the runtime surface broken.
+//   2. If the pointer (.adhdev-current) was absent at snapshot time, deleting it
+//      strands the re-published shims with no version to redirect to.
+// So rollback (re)guarantees a valid launcher surface: existing snapshots restore
+// their original bytes atomically; missing shims are re-issued from the canonical
+// pointer-redirect launcher contents; and the pointer, when it has no snapshot,
+// is re-written to the last-known-good active version instead of removed.
+function restoreStableFiles(snapshots: Map<string, FileSnapshot>, layout: WindowsInstallerLayout): void {
+  const shims = stableShimContents();
   for (const [target, snapshot] of snapshots) {
-    if (snapshot.exists && snapshot.data) atomicWrite(target, snapshot.data.toString('binary'), 'binary');
-    else try { fs.unlinkSync(target); } catch { /* noop */ }
+    if (snapshot.exists && snapshot.data) {
+      atomicWrite(target, snapshot.data.toString('binary'), 'binary');
+      continue;
+    }
+    const name = path.basename(target);
+    if (name === 'adhdev.cmd' || name === 'adhdev.ps1' || name === 'adhdev') {
+      // Re-issue a valid pointer-redirect launcher rather than deleting it, so
+      // PATH `adhdev` always resolves after a rollback.
+      atomicWrite(target, shims[name].content, shims[name].encoding);
+    } else if (name === POINTER_NAME) {
+      // Preserve the last-successful (currently active) version so the redirect
+      // launchers still reach a real prefix. Only fall back to deleting when we
+      // have no active version to point at.
+      if (layout.activeVersionName) atomicWrite(target, layout.activeVersionName, 'ascii');
+      else try { fs.unlinkSync(target); } catch { /* noop */ }
+    } else {
+      try { fs.unlinkSync(target); } catch { /* noop */ }
+    }
   }
 }
 
@@ -339,7 +415,7 @@ export async function performWindowsAtomicUpgrade(options: WindowsAtomicUpgradeO
     if (restarted?.pid) hooks.stopProcess(restarted.pid);
     if (activated) {
       try {
-        restoreStableFiles(snapshots);
+        restoreStableFiles(snapshots, layout);
         hooks.log(`Rolled back activation to ${layout.activeVersionName}`);
       } catch (rollbackError: any) {
         hooks.log(`Stable-file rollback failed: ${rollbackError?.message || String(rollbackError)}`);
@@ -359,7 +435,13 @@ export function createDefaultWindowsAtomicHooks(options: {
   cwd: string;
   env: NodeJS.ProcessEnv;
   log: (message: string) => void;
+  /** Loopback IPC port to probe for health/version. Defaults to the daemon's local IPC port. */
+  healthPort?: number;
+  /** How long to poll for the replacement daemon to report the target version. */
+  healthTimeoutMs?: number;
 }): WindowsAtomicUpgradeHooks {
+  const healthPort = options.healthPort ?? DEFAULT_HEALTH_PORT;
+  const healthTimeoutMs = options.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
   return {
     install: (stagedPrefix, portableNode) => {
       const env: NodeJS.ProcessEnv = {
@@ -370,7 +452,7 @@ export function createDefaultWindowsAtomicHooks(options: {
       };
       const pathKey = Object.keys(env).find((key) => key.toLowerCase() === 'path') || 'Path';
       env[pathKey] = `${path.dirname(portableNode)};${env[pathKey] || ''}`;
-      execFileSync(portableNode, [
+      const installOutput = String(execFileSync(portableNode, [
         options.npmCliPath,
         'install', '-g', `${options.packageName}@${options.targetVersion}`, '--force', '--prefer-online', '--prefix', stagedPrefix,
       ], {
@@ -379,7 +461,11 @@ export function createDefaultWindowsAtomicHooks(options: {
         maxBuffer: 20 * 1024 * 1024,
         windowsHide: true,
         env,
-      });
+      }));
+      // On failure execFileSync throws with stdout attached to the Error; on
+      // success it was previously discarded. Surface the npm output either way so
+      // a silently-succeeding-then-rolled-back upgrade leaves a diagnosable trail.
+      if (installOutput.trim()) options.log(installOutput.trim());
     },
     restart: (portableNode, stagedCliEntry) => {
       const restartArgv = options.restartArgv.map((arg, index) => index === 0 ? stagedCliEntry : arg);
@@ -406,25 +492,42 @@ export function createDefaultWindowsAtomicHooks(options: {
       child.unref();
     },
     waitForHealth: async (pid, targetVersion) => {
-      const deadline = Date.now() + 30000;
+      const startedAt = Date.now();
+      const deadline = startedAt + healthTimeoutMs;
+      let attempt = 0;
+      // Log the transition milestones exactly once so the daemon log shows how far
+      // the replacement got before the gate resolved: not-yet-alive → alive but
+      // version-not-yet-ready (components still booting) → version matched. This is
+      // what pins down which boot stage the full-boot budget is being spent in.
+      let loggedAlive = false;
+      let loggedVersionPending = false;
       while (Date.now() < deadline) {
-        const result = await new Promise<{ ok: boolean; pid?: number; body?: string }>((resolve) => {
-          const req = http.get(`http://127.0.0.1:${DEFAULT_HEALTH_PORT}/health`, { timeout: 1500 }, (res) => {
-            let body = '';
-            res.setEncoding('utf8');
-            res.on('data', (chunk) => { body += chunk; });
-            res.on('end', () => {
-              let responsePid: number | undefined;
-              try { responsePid = Number(JSON.parse(body)?.pid); } catch { /* noop */ }
-              resolve({ ok: res.statusCode === 200, pid: responsePid, body });
-            });
-          });
-          req.on('timeout', () => req.destroy());
-          req.on('error', () => resolve({ ok: false }));
-        });
-        if (result.ok && result.pid === pid && result.body?.includes(targetVersion)) return true;
+        attempt += 1;
+        // Liveness + pid identity come from GET /health, whose body is
+        // {ok, pid, wsPath, port} — it carries NO version. The running version
+        // lives only in GET /api/v1/status → payload.status.version, so the
+        // version gate must fetch that endpoint separately. Requiring the raw
+        // /health body to include targetVersion is unsatisfiable and silently
+        // rolls every upgrade back.
+        const liveness = await fetchLocalHealth(healthPort);
+        const alive = liveness.ok && liveness.pid === pid;
+        const version = alive ? await fetchLocalStatusVersion(healthPort) : undefined;
+        const elapsedMs = Date.now() - startedAt;
+        if (alive && version === targetVersion) {
+          options.log(`Health gate passed after ${elapsedMs}ms (${attempt} probe(s)): pid ${pid} reports ${targetVersion}`);
+          return true;
+        }
+        if (alive && !loggedAlive) {
+          loggedAlive = true;
+          options.log(`Health gate: replacement pid ${pid} is alive at ${elapsedMs}ms; awaiting status.version (components still booting)`);
+        }
+        if (alive && version && version !== targetVersion && !loggedVersionPending) {
+          loggedVersionPending = true;
+          options.log(`Health gate: replacement reports version ${version} (want ${targetVersion}) at ${elapsedMs}ms`);
+        }
         await new Promise((resolve) => setTimeout(resolve, 500));
       }
+      options.log(`Health gate timed out after ${Date.now() - startedAt}ms (${attempt} probe(s), budget ${healthTimeoutMs}ms) waiting for pid ${pid} to report ${targetVersion}`);
       return false;
     },
     stopProcess: (pid) => {
@@ -459,13 +562,19 @@ export function boundedCleanupInactivePrefixes(
     return;
   }
   if (candidates.length === 0) return;
-  const escaped = candidates.map((candidate) => quotePowerShellLiteral(candidate)).join(',');
-  const script = `$ErrorActionPreference='Stop'; @(${escaped}) | ForEach-Object { if (Test-Path -LiteralPath $_) { Remove-Item -LiteralPath $_ -Recurse -Force } }`;
-  const encoded = Buffer.from(script, 'utf16le').toString('base64');
-  const result = spawnSync('powershell.exe', [
-    '-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded,
-  ], { timeout: 5000, windowsHide: true, stdio: 'ignore' });
-  if (result.error || result.status !== 0) log('Bounded inactive-prefix cleanup was incomplete; future updates will retry');
+  // Delete in-process (see removeInactivePrefix) rather than via a powershell.exe
+  // Remove-Item batch under a 5000ms spawnSync timeout, which ETIMEDOUT'd on
+  // Windows and left orphan version-* prefixes behind. best-effort: a failure
+  // here never blocks the upgrade success/failure signal.
+  let incomplete = false;
+  for (const candidate of candidates) {
+    try {
+      fs.rmSync(candidate, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+    } catch {
+      incomplete = true;
+    }
+  }
+  if (incomplete) log('Bounded inactive-prefix cleanup was incomplete; future updates will retry');
 }
 
 export async function cleanupInactivePrefixesWithGuard(options: {
@@ -507,16 +616,15 @@ export async function cleanupInactivePrefixesWithGuard(options: {
 }
 
 function removeInactivePrefix(target: string, log?: (message: string) => void): void {
+  // Delete in-process with fs.rmSync instead of shelling out to powershell.exe.
+  // A version prefix holds thousands of small files (node_modules, node-pty
+  // prebuilds); Remove-Item -Recurse -Force over that, plus PowerShell 5.1's
+  // cold-start, routinely blew past the old 5000ms spawnSync timeout on Windows
+  // — every candidate then failed with ETIMEDOUT and orphan version-* dirs
+  // accumulated. fs.rmSync has no process spawn, no timeout, and retries the
+  // transient EBUSY/EPERM/ENOTEMPTY that a just-stopped process can leave behind.
   try {
-    const escaped = quotePowerShellLiteral(target);
-    const script = `if (Test-Path -LiteralPath ${escaped}) { Remove-Item -LiteralPath ${escaped} -Recurse -Force }`;
-    const encoded = Buffer.from(script, 'utf16le').toString('base64');
-    const result = spawnSync('powershell.exe', [
-      '-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded,
-    ], { timeout: 5000, windowsHide: true, stdio: 'ignore' });
-    if (result.error || result.status !== 0) {
-      log?.(`Failed to remove inactive prefix ${target}: ${result.error?.message || `exit ${result.status}`}`);
-    }
+    fs.rmSync(target, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
   } catch (error: any) {
     log?.(`Failed to remove inactive prefix ${target}: ${error?.message || String(error)}`);
   }

package/src/config/mesh-json-config.ts

@@ -19,6 +19,18 @@
  * machine-local policy directly. The repo file shapes the coordinator prompt and
  * operating notes, nothing else.
  *
+ * `providerDefaults` IS NOT POLICY EITHER. It is a repo-shared DECLARATIVE
+ * "requested auto-approve mode" per providerType — the answer to "WHEN a delegated
+ * worker of type X is auto-approved, WHICH mode should it use by default". It has
+ * NO say over WHETHER auto-approve is enabled: the ENABLE decision (and the
+ * dangerous-mode opt-in) remains 100% machine-local (meshes.json /
+ * RepoMeshPolicy). A repo can declare `providerDefaults` freely; a machine that
+ * has delegatedWorkerAutoApprove=false still gets no auto-approve, and a dangerous
+ * requested mode is still downgraded to PTY parsing unless the machine opts in.
+ * The requested mode ID is validated at runtime against the provider spec — an
+ * unknown mode ID is IGNORED (fall back to the provider's own default), never
+ * silently coerced into a dangerous mode.
+ *
  * The coordinator/operatingNotes merge is **in-memory only**: the on-disk
  * machine-local `meshes.json` is never mutated by this module.
  *
@@ -60,6 +72,19 @@ export interface RepoMeshDeclarativeLimits {
     maxNotes?: number;
 }
 
+/**
+ * Repo-shared declarative per-provider defaults. NOT policy — see the file header.
+ * `autoApproveModes` maps a providerType (e.g. "claude-cli") to the auto-approve
+ * mode ID that a delegated worker of that type should REQUEST when it is
+ * auto-approved. The map only influences WHICH mode is used, never WHETHER
+ * auto-approve is enabled (that stays machine-local). Mode IDs are validated
+ * against the live provider spec at resolve time; an unknown ID is ignored.
+ */
+export interface RepoMeshDeclarativeProviderDefaults {
+    /** providerType → requested auto-approve mode ID. */
+    autoApproveModes?: Record<string, string>;
+}
+
 /**
  * Parsed + normalized `.adhdev/mesh.json` shape. Every field is optional except
  * version so a repo can declare only the zone(s) it cares about. Policy is NOT a
@@ -70,6 +95,8 @@ export interface RepoMeshDeclarativeConfig {
     coordinator?: RepoMeshDeclarativeCoordinatorConfig;
     operatingNotes?: CoordinatorOperatingNote[];
     limits?: RepoMeshDeclarativeLimits;
+    /** Repo-shared per-provider defaults (requested auto-approve mode). NOT policy. */
+    providerDefaults?: RepoMeshDeclarativeProviderDefaults;
 }
 
 export interface RepoMeshJsonConfigLoadResult {
@@ -132,6 +159,20 @@ export const MESH_JSON_CONFIG_SCHEMA = {
                 maxNotes: { type: 'number', minimum: 1 },
             },
         },
+        providerDefaults: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                // providerType → requested auto-approve mode ID. Mode IDs are
+                // validated against the live provider spec at resolve time; an
+                // unknown ID is ignored (provider default is used), so the schema
+                // only constrains the shape (string→string), not the ID values.
+                autoApproveModes: {
+                    type: 'object',
+                    additionalProperties: { type: 'string' },
+                },
+            },
+        },
     },
 } as const;
 
@@ -226,6 +267,38 @@ export function normalizeRepoMeshDeclarativeConfig(parsed: unknown): {
         }
     }
 
+    // providerDefaults: shape-only normalization. We keep every string→string
+    // (providerType → requested mode ID) entry after trimming; we deliberately do
+    // NOT validate the mode IDs against any provider spec here — the normalizer has
+    // no provider registry, and (crucially) validity depends on the LIVE provider
+    // at resolve time. The runtime resolver (resolveDelegatedWorkerAutoApprove)
+    // checks the requested ID against provider.autoApproveModes.modes and falls
+    // back to the provider's own default when the ID is unknown. This keeps the
+    // config fail-closed: a stale/typo'd mode ID never coerces into a dangerous
+    // mode, it just means "no repo override → provider default".
+    if (parsed.providerDefaults !== undefined) {
+        if (isRecord(parsed.providerDefaults)) {
+            const pd: RepoMeshDeclarativeProviderDefaults = {};
+            const rawModes = (parsed.providerDefaults as Record<string, unknown>).autoApproveModes;
+            if (rawModes !== undefined) {
+                if (isRecord(rawModes)) {
+                    const modes: Record<string, string> = {};
+                    for (const [providerType, modeId] of Object.entries(rawModes)) {
+                        const type = typeof providerType === 'string' ? providerType.trim() : '';
+                        const id = typeof modeId === 'string' ? modeId.trim() : '';
+                        if (type && id) modes[type] = id;
+                    }
+                    if (Object.keys(modes).length) pd.autoApproveModes = modes;
+                } else {
+                    errors.push('providerDefaults.autoApproveModes must be an object when provided');
+                }
+            }
+            if (Object.keys(pd).length) config.providerDefaults = pd;
+        } else {
+            errors.push('providerDefaults must be an object when provided');
+        }
+    }
+
     return { valid: true, config, errors };
 }
 
@@ -364,6 +437,21 @@ export function applyRepoMeshConfig<T extends Pick<LocalMeshEntry, 'coordinator'
  * exported — it is machine-local only and has no place in mesh.json. Operating
  * notes are intentionally NOT exported either: those are runtime ledger lessons,
  * and a repo should declare baseline notes deliberately.
+ *
+ * `providerDefaults` is NOT auto-exported from the machine-local mesh (there is no
+ * machine-local source for it — it is a repo-authored declaration). To help an
+ * operator hand-author it, the scaffold carries a commented example shape:
+ *
+ *   "providerDefaults": {
+ *     "autoApproveModes": {
+ *       "claude-cli": "accept-edits",   // requested mode WHEN auto-approve is on
+ *       "codex-cli": "auto"             // (enable/dangerous opt-in stays machine-local)
+ *     }
+ *   }
+ *
+ * The example is surfaced via the scaffold's `_providerDefaultsExample` hint (JSON
+ * has no comments) rather than a live `providerDefaults` value, so serializing the
+ * scaffold never writes an unwanted requested-mode map into the repo file.
  */
 export function buildMeshJsonConfigScaffold(
     mesh: Pick<LocalMeshEntry, 'coordinator'>,
@@ -378,6 +466,21 @@ export function buildMeshJsonConfigScaffold(
     return scaffold;
 }
 
+/**
+ * A copy-paste example of the `providerDefaults` zone for operators hand-authoring
+ * a repo `.adhdev/mesh.json`. Returned by the export/write commands as a separate
+ * hint field (never merged into the serialized scaffold) so the repo file stays
+ * clean. The mode IDs shown are illustrative — a repo should use IDs that exist in
+ * its own providers' specs; an unknown ID is ignored at resolve time and the
+ * provider's own default is used.
+ */
+export const MESH_JSON_PROVIDER_DEFAULTS_EXAMPLE: RepoMeshDeclarativeProviderDefaults = {
+    autoApproveModes: {
+        'claude-cli': 'accept-edits',
+        'codex-cli': 'auto',
+    },
+};
+
 /** Serialize a scaffold to the canonical 2-space JSON draft text. */
 export function serializeMeshJsonConfigScaffold(config: RepoMeshDeclarativeConfig): string {
     return JSON.stringify(config, null, 2);

package/src/index.ts

@@ -143,6 +143,8 @@ export type {
 export {
   DEFAULT_MESH_POLICY,
   resolveDelegatedWorkerAutoApprove,
+  delegatedWorkerAutoApproveSettings,
+  resolveDelegatedWorkerDangerousModeAllow,
   resolveAllowSendKeysDestructive,
   resolveMagiSessionCleanupMode,
   magiAutoLaunchedSessionCleanupDecision,
@@ -161,6 +163,24 @@ export {
   resolveAutoConvergeCodeChange,
 } from './repo-mesh-types.js';
 
+// ── Repo-shared declarative mesh config (.adhdev/mesh.json) ──
+export {
+  loadRepoMeshJsonConfig,
+  normalizeRepoMeshDeclarativeConfig,
+  buildMeshJsonConfigScaffold,
+  serializeMeshJsonConfigScaffold,
+  MESH_JSON_CONFIG_LOCATIONS,
+  MESH_JSON_CONFIG_SCHEMA,
+  MESH_JSON_PROVIDER_DEFAULTS_EXAMPLE,
+} from './config/mesh-json-config.js';
+export type {
+  RepoMeshDeclarativeConfig,
+  RepoMeshDeclarativeCoordinatorConfig,
+  RepoMeshDeclarativeLimits,
+  RepoMeshDeclarativeProviderDefaults,
+  RepoMeshJsonConfigLoadResult,
+} from './config/mesh-json-config.js';
+
 // ── Git Surface ──
 export * from './git/index.js';
 
@@ -489,7 +509,7 @@ export { ProviderInstanceManager } from './providers/provider-instance-manager.j
 export { IdeProviderInstance } from './providers/ide-provider-instance.js';
 export { CliProviderInstance } from './providers/cli-provider-instance.js';
 export { AcpProviderInstance } from './providers/acp-provider-instance.js';
-export type { ProviderModule, CdpTargetFilter, ProviderResumeCapability, InputEnvelope, InputPart, MessagePart, ReadChatTurnStatus, ControlListResult, ControlSetResult, ControlInvokeResult } from './providers/contracts.js';
+export type { ProviderModule, AutoApproveMode, AutoApproveModesConfig, AutoApproveModeRisk, AutoApproveModeStrategy, CdpTargetFilter, ProviderResumeCapability, InputEnvelope, InputPart, MessagePart, ReadChatTurnStatus, ControlListResult, ControlSetResult, ControlInvokeResult } from './providers/contracts.js';
 export type { ProviderSourceConfigSnapshot, ProviderSourceConfigUpdate } from './config/provider-source-config.js';
 export { parseProviderSourceConfigUpdate } from './config/provider-source-config.js';
 export { normalizeInputEnvelope, normalizeMessageParts, flattenMessageParts } from './providers/io-contracts.js';

package/src/mesh/coordinator-prompt.ts

@@ -1007,7 +1007,8 @@ const TOOLS_SECTION = `## Available Tools
 | \`mesh_fast_forward_node\` | Safely dry-run or explicitly execute an obvious clean fast-forward without launching an agent session |
 | \`mesh_restart_daemon\` | Update a node's daemon to the latest published version on its channel and restart it (the dashboard "preview update" path, as a mesh command) |
 | \`mesh_checkpoint\` | Create a git checkpoint on a node |
-| \`mesh_approve\` | Approve/reject a pending agent action |
+| \`mesh_approve\` | Approve/reject a pending agent action (a yes/no tool-consent modal) |
+| \`mesh_answer_question\` | Answer a delegated session's multi-choice QUESTION (AskUserQuestion / status awaiting_choice). NOT an approval — it offers labelled options (possibly multi-select or freeform). Pass the promptId from the agent:waiting_choice event + one answer per question (select by option label or 1-based index). Use this, never mesh_approve, for a question |
 | \`mesh_list_pending_approvals\` | List every session across the mesh awaiting an approval decision (the approval inbox) — read-only; enumerate all blocked sessions at once, then drive a mesh_approve for each |
 | \`mesh_clone_node\` | Create a worktree node for isolated parallel branch work |
 | \`mesh_refine_node\` | Validate and merge a completed worktree node back into its base branch |

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

@@ -5,7 +5,7 @@ import { deleteDirectDispatchesByTaskId } from './mesh-work-queue.js';
 import { meshNodeIdMatches, daemonIdsEquivalent, sessionIdsEquivalent } from '@adhdev/mesh-shared';
 
 export type MeshActiveWorkSource = 'queue' | 'direct';
-export type MeshActiveWorkStatus = 'pending' | 'assigned' | 'generating' | 'idle' | 'failed' | 'awaiting_approval';
+export type MeshActiveWorkStatus = 'pending' | 'assigned' | 'generating' | 'idle' | 'failed' | 'awaiting_approval' | 'awaiting_choice';
 
 export interface MeshActiveWorkRecord {
     taskId: string;
@@ -135,6 +135,10 @@ export function sessionStatusFromNodes(nodes: any[] | undefined, nodeId?: string
     if (!session) return { staleReason: 'direct task session is not present in live session records' };
     if (typeof session === 'string') return {};
     const raw = `${readString(session.status) || ''} ${readString(session.lifecycle) || ''} ${readString(session.state) || ''} ${readString(session.activeChat?.status) || ''}`.toLowerCase();
+    // A question picker surfaces as waiting_choice — distinct from an approval modal.
+    // Check it first so a question worker is not mislabeled awaiting_approval and
+    // pulled into the approval inbox (mission f1d25e11).
+    if (raw.includes('waiting_choice') || raw.includes('choice')) return { status: 'awaiting_choice' };
     if (raw.includes('approval')) return { status: 'awaiting_approval' };
     if (raw.includes('generating') || raw.includes('running') || raw.includes('busy')) return { status: 'generating' };
     if (raw.includes('failed') || raw.includes('stopped') || raw.includes('terminated') || raw.includes('exited')) return { status: 'failed' };
@@ -166,6 +170,10 @@ function terminalMatchesDispatch(terminal: MeshLedgerEntry, dispatch: MeshLedger
 
 function statusFromTerminal(entry: MeshLedgerEntry): MeshActiveWorkStatus {
     if (entry.kind === 'task_approval_needed') return 'awaiting_approval';
+    // A question (waiting_choice) is a distinct blocked state — kept OUT of
+    // awaiting_approval so it is not surfaced in the approval inbox / mesh_approve
+    // flow (mission f1d25e11). Answered via mesh_answer_question.
+    if (entry.kind === 'task_question_pending') return 'awaiting_choice';
     if (entry.kind === 'task_completed') return 'idle';
     return 'failed';
 }
@@ -331,6 +339,7 @@ export function buildMeshActiveWorkSummary(activeWork: MeshActiveWorkRecord[]):
         idle: 0,
         failed: 0,
         awaiting_approval: 0,
+        awaiting_choice: 0,
     };
     const sourceCounts: Record<MeshActiveWorkSource, number> = { queue: 0, direct: 0 };
     for (const item of activeWork) {
@@ -380,6 +389,7 @@ export function buildMeshActiveWork(opts: BuildMeshActiveWorkOptions): { activeW
             ? sessionStatusFromNodes(opts.nodes, queueNodeId ?? undefined, queueSessionId ?? undefined)
             : {};
         const queueStatus: MeshActiveWorkStatus = queueLive.status === 'awaiting_approval'
+            || queueLive.status === 'awaiting_choice'
             || queueLive.status === 'generating'
             ? queueLive.status
             : task.status;