@adhdev/daemon-core 1.0.18-rc.2 → 1.0.18-rc.20

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

@@ -2,11 +2,68 @@ import { execFileSync, spawn, spawnSync, type ChildProcess } from 'child_process
 import * as fs from 'fs';
 import * as http from 'http';
 import * as path from 'path';
+import { stopOwnedProcessesForPrefixes } from './process-lifecycle.js';
 
 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.
+export const ADHDEV_OWNED_MARKERS = [
+    'session-host-daemon',
+    'node_modules/adhdev',
+    'node_modules/@adhdev/daemon-standalone',
+] as const;
+
 export interface WindowsInstallerLayout {
   homeDir: string;
   installRoot: string;
@@ -22,7 +79,7 @@ export interface WindowsAtomicUpgradeHooks {
   restartOld: (portableNode: string) => void;
   waitForHealth: (pid: number, targetVersion: string) => Promise<boolean>;
   stopProcess: (pid: number) => void;
-  cleanup: (layout: WindowsInstallerLayout, activePrefix: string) => void;
+  cleanup: (layout: WindowsInstallerLayout, activePrefix: string) => void | Promise<void>;
   log: (message: string) => void;
 }
 
@@ -32,6 +89,8 @@ export interface WindowsAtomicUpgradeOptions {
   targetVersion: string;
   portableNode: string;
   hooks: WindowsAtomicUpgradeHooks;
+  /** PIDs that must never be terminated during prefix sweeps (helper + parent daemon). */
+  excludePids?: number[];
 }
 
 export interface WindowsAtomicUpgradeResult {
@@ -102,6 +161,28 @@ function packageRootForPrefix(prefix: string, packageName: string): string {
   return path.join(prefix, 'node_modules', ...packageName.split('/'));
 }
 
+// node-pty ships a Windows x64 prebuild. If npm rebuilds from source (because a
+// .npmrc sets build-from-source=true), the install script deletes the prebuild
+// and may leave no conpty.node on machines without build tools. Verify it
+// survived before we ever activate the staged prefix.
+const CONPTY_PREBUILD_RELATIVE_PATH = path.join(
+  'node_modules', 'adhdev', 'node_modules', 'node-pty', 'prebuilds', 'win32-x64', 'conpty.node'
+);
+
+function resolveStagedConptyPrebuildPath(stagedPrefix: string): string {
+  return path.join(stagedPrefix, CONPTY_PREBUILD_RELATIVE_PATH);
+}
+
+function verifyStagedConptyPrebuild(stagedPrefix: string): void {
+  const conptyPath = resolveStagedConptyPrebuildPath(stagedPrefix);
+  if (!fs.existsSync(conptyPath)) {
+    throw new Error(
+      `Staged install is missing required native addon: ${conptyPath}. ` +
+      'Aborting activation to prevent a daemon boot crash.'
+    );
+  }
+}
+
 function readPackageCliEntry(prefix: string, packageName: string, targetVersion: string): string {
   const packageRoot = packageRootForPrefix(prefix, packageName);
   const packageJsonPath = path.join(packageRoot, 'package.json');
@@ -128,13 +209,31 @@ function quotePowerShellLiteral(value: string): string {
 function pinStagedShims(prefix: string, portableNode: string, cliEntry: string): void {
   const cmdPath = path.join(prefix, 'adhdev.cmd');
   const ps1Path = path.join(prefix, 'adhdev.ps1');
+  // The no-extension `adhdev` shim is what `where.exe adhdev` can resolve first
+  // and what git-bash / MSYS / WSL and `spawnSync('adhdev')` invoke. npm generates
+  // it as a POSIX `sh` shim whose ELSE branch falls back to the FIRST `node` on
+  // PATH (`else exec node ...`). On a box where system PATH node is v24, that
+  // fallback trips adhdev's own Node-24 guard and `adhdev doctor` reports the
+  // runtime surface broken. Rewrite it too so it hard-codes the portable Node 22
+  // absolute path with NO system-node fallback — mirroring the .cmd/.ps1 pins.
+  const noExtPath = path.join(prefix, 'adhdev');
   const cmd = `@echo off\r\n"${portableNode}" "${cliEntry}" %*\r\n`;
   const ps1 = `#!/usr/bin/env pwsh\r\n& ${quotePowerShellLiteral(portableNode)} ${quotePowerShellLiteral(cliEntry)} @args\r\nexit $LASTEXITCODE\r\n`;
+  // sh shim: single unconditional exec of the pinned node — no `if -x node` /
+  // `else exec node` branch, so PATH ordering can never shadow the runtime.
+  const noExt = `#!/bin/sh\nexec "${portableNode}" "${cliEntry}" "$@"\n`;
   fs.writeFileSync(cmdPath, cmd, 'ascii');
   fs.writeFileSync(ps1Path, ps1, 'utf8');
+  fs.writeFileSync(noExtPath, noExt, 'ascii');
   const cmdReadback = fs.readFileSync(cmdPath, 'utf8');
   const ps1Readback = fs.readFileSync(ps1Path, 'utf8');
-  if (!cmdReadback.includes(portableNode) || !ps1Readback.includes(portableNode)) {
+  const noExtReadback = fs.readFileSync(noExtPath, 'utf8');
+  if (
+    !cmdReadback.includes(portableNode)
+    || !ps1Readback.includes(portableNode)
+    || !noExtReadback.includes(portableNode)
+    || /(^|\s)exec\s+node(\s|$)/m.test(noExtReadback)
+  ) {
     throw new Error('portable Node 22 pin validation failed');
   }
 }
@@ -220,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 */ }
+    }
   }
 }
 
@@ -247,11 +375,31 @@ export async function performWindowsAtomicUpgrade(options: WindowsAtomicUpgradeO
   try {
     hooks.log(`Installing ${packageName}@${targetVersion} into inactive prefix ${stagedPrefix}`);
     await hooks.install(stagedPrefix, portableNode);
+    verifyStagedConptyPrebuild(stagedPrefix);
     const stagedCliEntry = readPackageCliEntry(stagedPrefix, packageName, targetVersion);
     pinStagedShims(stagedPrefix, portableNode, stagedCliEntry);
     validateStagedCli(portableNode, stagedCliEntry, targetVersion);
     hooks.log(`Validated staged CLI and portable Node 22 shims in ${stagedPrefix}`);
 
+    // Stop every ADHDev-owned process still executing from the current active
+    // prefix or the legacy stable shim tree before moving the pointer. A stale
+    // session-host left running here keeps node-pty's native addon mapped from
+    // the old tree and resolves lazy requires against a deleted prefix after
+    // activation. Survivors block activation so the pointer is never corrupted.
+    const excludedPids = new Set([process.pid, ...(options.excludePids ?? [])].filter((n) => Number.isFinite(n) && n > 0));
+    const preStop = await stopOwnedProcessesForPrefixes({
+      prefixes: [layout.activePrefix, layout.stablePrefix],
+      excludePids: Array.from(excludedPids),
+      markers: Array.from(ADHDEV_OWNED_MARKERS),
+      waitMs: 15_000,
+      log: hooks.log,
+    });
+    if (preStop.survivors.length > 0) {
+      throw new Error(
+        `Cannot activate ${versionName}: ${preStop.survivors.length} owned process(es) still running under the current prefix`
+      );
+    }
+
     activated = true;
     publishStableShimsAndPointer(layout, versionName);
     hooks.log(`Atomically activated ${versionName}`);
@@ -261,20 +409,20 @@ export async function performWindowsAtomicUpgrade(options: WindowsAtomicUpgradeO
       throw new Error('replacement daemon did not pass the health/version gate');
     }
     hooks.log(`Replacement daemon pid ${daemonPid} passed health for ${targetVersion}`);
-    hooks.cleanup(layout, stagedPrefix);
+    await hooks.cleanup(layout, stagedPrefix);
     return { stagedPrefix, stagedCliEntry, daemonPid };
   } catch (error) {
     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)}`);
       }
     }
     try { hooks.restartOld(portableNode); } catch { hooks.log('Failed to restart the previous daemon during rollback'); }
-    try { hooks.cleanup(layout, layout.activePrefix); } catch { /* failure path must preserve original error */ }
+    try { await hooks.cleanup(layout, layout.activePrefix); } catch { /* failure path must preserve original error */ }
     throw error;
   }
 }
@@ -287,13 +435,24 @@ 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 = { ...options.env, ADHDEV_BOOTSTRAP: '1' };
+      const env: NodeJS.ProcessEnv = {
+        ...options.env,
+        ADHDEV_BOOTSTRAP: '1',
+        npm_config_build_from_source: 'false',
+        'npm_config_build-from-source': 'false',
+      };
       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,
       ], {
@@ -302,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);
@@ -329,31 +492,55 @@ 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) => {
       try { execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }); } catch { /* noop */ }
     },
-    cleanup: (layout, activePrefix) => boundedCleanupInactivePrefixes(layout, activePrefix, options.log),
+    cleanup: async (layout, activePrefix) => cleanupInactivePrefixesWithGuard({
+      layout,
+      activePrefix,
+      excludePids: [process.pid],
+      markers: Array.from(ADHDEV_OWNED_MARKERS),
+      waitMs: 15_000,
+      log: options.log,
+    }),
     log: options.log,
   };
 }
@@ -375,11 +562,70 @@ 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: {
+  layout: WindowsInstallerLayout;
+  activePrefix: string;
+  excludePids?: number[];
+  markers?: readonly string[];
+  waitMs?: number;
+  log?: (message: string) => void;
+}): Promise<void> {
+  const { layout, activePrefix, log } = options;
+  let candidates: string[] = [];
+  try {
+    candidates = fs.readdirSync(layout.installRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith('version-'))
+      .map((entry) => path.join(layout.installRoot, entry.name))
+      .filter((entry) => normalizeForCompare(entry) !== normalizeForCompare(activePrefix))
+      .sort()
+      .slice(0, 8);
+  } catch {
+    return;
+  }
+  if (candidates.length === 0) return;
+
+  for (const candidate of candidates) {
+    const stopResult = await stopOwnedProcessesForPrefixes({
+      prefixes: [candidate],
+      excludePids: options.excludePids,
+      markers: options.markers,
+      waitMs: options.waitMs ?? 15_000,
+      log,
+    });
+    if (stopResult.survivors.length > 0) {
+      log?.(`Skipping cleanup of ${candidate}: ${stopResult.survivors.length} owned process(es) could not be stopped`);
+      continue;
+    }
+    removeInactivePrefix(candidate, log);
+  }
+}
+
+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 {
+    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;
 
@@ -160,6 +201,14 @@ function normalizeOperatingNote(value: unknown): CoordinatorOperatingNote | null
         ...(category ? { category } : {}),
         ...(typeof value.createdAt === 'string' ? { createdAt: value.createdAt } : {}),
         ...(typeof value.sourceCoordinator === 'string' ? { sourceCoordinator: value.sourceCoordinator } : {}),
+        // Operating-notes lifecycle: a repo-declared note may pin itself or set an
+        // explicit expiry, same as a runtime-recorded one. Phase 2 (b)/(c): it may
+        // also declare supersedes/subjectKey to retire an earlier note or group
+        // same-subject notes for folding.
+        ...(value.pinned === true ? { pinned: true } : {}),
+        ...(typeof value.expiresAt === 'string' ? { expiresAt: value.expiresAt } : {}),
+        ...(typeof value.supersedes === 'string' ? { supersedes: value.supersedes } : {}),
+        ...(typeof value.subjectKey === 'string' ? { subjectKey: value.subjectKey } : {}),
     };
 }
 
@@ -218,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 };
 }
 
@@ -356,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'>,
@@ -370,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';