@bastani/atomic 0.9.41 → 0.9.42-alpha.1

package/dist/utils/shell.js

@@ -292,6 +292,20 @@ export function killProcessTree(pid) {
         }
     }
     else {
+        if (process.platform === "darwin") {
+            // macOS signals group members individually after releasing the group lock. A killed
+            // child can wake its waiting shell before that shell is signalled, letting `a; b`
+            // start b during cancellation (pi #11252). Stop the group first to reduce this race;
+            // this is best-effort, not an atomic freeze. SIGKILL also kills stopped processes.
+            // Linux holds tasklist_lock across group signalling; child exit notification needs
+            // its write lock, so the shell is signalled before observing the killed child's exit.
+            try {
+                process.kill(-pid, "SIGSTOP");
+            }
+            catch {
+                // A failed stop must not prevent the kill attempt or its single-process fallback.
+            }
+        }
         // Use SIGKILL on Unix/Linux/Mac
         try {
             process.kill(-pid, "SIGKILL");

package/dist/utils/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/utils/shell.ts"],"names":[],"mappings":"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","sourcesContent":["import { accessSync, constants } from \"node:fs\";\nimport { delimiter, join, win32 } from \"node:path\";\nimport { Worker } from \"node:worker_threads\";\nimport { spawn, spawnSync } from \"child_process\";\nimport { getBinDir } from \"../config.js\";\nimport { createChildProcessEnvironment } from \"./child-process.ts\";\n\nexport interface ShellConfig {\n\tshell: string;\n\targs: string[];\n\tcommandTransport?: \"argv\" | \"stdin\";\n}\n\nfunction isLegacyWslBashPath(path: string): boolean {\n\tconst normalized = win32.normalize(path).toLowerCase();\n\tconst systemRoot = process.env.SystemRoot;\n\tif (systemRoot) {\n\t\tif (!/^[a-z]:[\\\\/]/i.test(systemRoot)) return false;\n\t\treturn [\"System32\", \"Sysnative\"].some(\n\t\t\t(directory) => normalized === win32.join(systemRoot, directory, \"bash.exe\").toLowerCase(),\n\t\t);\n\t}\n\t// Fall back to conventional launcher paths only when the Windows directory is unknown.\n\treturn /^[a-z]:\\\\windows\\\\(?:system32|sysnative)\\\\bash\\.exe$/.test(normalized);\n}\n\nfunction getBashShellConfig(shell: string): ShellConfig {\n\treturn isLegacyWslBashPath(shell) ? { shell, args: [\"-s\"], commandTransport: \"stdin\" } : { shell, args: [\"-c\"] };\n}\n\n// On Unix this is identical to existsSync() (both are access(F_OK)), just\n// spelled with try/catch. On Windows we explicitly avoid existsSync(): its\n// extra stat check rejects runnable Store aliases (nodejs/node#36790).\nfunction shellPathExists(path: string): boolean {\n\ttry {\n\t\taccessSync(path, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nconst MISSING_EXECUTABLE_RECHECK_MS = 30_000;\n\ninterface ExecutableLookup {\n\tpath: string | null;\n\tcheckedAt: number;\n}\n\nconst executablePathLookups = new Map<string, ExecutableLookup>();\n\nfunction isReusableLookup(lookup: ExecutableLookup): boolean {\n\treturn lookup.path === null\n\t\t? Date.now() - lookup.checkedAt < MISSING_EXECUTABLE_RECHECK_MS\n\t\t: shellPathExists(lookup.path);\n}\n\n/**\n * Find an executable on PATH (cross-platform), memoized per PATH value.\n * A missing executable is looked up again once its result is 30 seconds old.\n */\nfunction findExecutableOnPath(executable: string): string | null {\n\tconst key = `${executable}\\0${process.env.PATH ?? \"\"}`;\n\tconst cached = executablePathLookups.get(key);\n\tif (cached && isReusableLookup(cached)) return cached.path;\n\tconst path = lookupExecutableOnPath(executable);\n\texecutablePathLookups.set(key, { path, checkedAt: Date.now() });\n\treturn path;\n}\n\nfunction lookupExecutableOnPath(executable: string): string | null {\n\tif (process.platform === \"win32\") {\n\t\t// Windows: use 'where' and check the returned path.\n\t\ttry {\n\t\t\tconst result = spawnSync(\"where\", [executable], {\n\t\t\t\tencoding: \"utf-8\",\n\t\t\t\ttimeout: 5000,\n\t\t\t\tenv: createChildProcessEnvironment(),\n\t\t\t});\n\t\t\tif (result.status === 0 && result.stdout) {\n\t\t\t\tconst firstMatch = result.stdout.trim().split(/\\r?\\n/)[0];\n\t\t\t\tif (firstMatch && shellPathExists(firstMatch)) {\n\t\t\t\t\treturn firstMatch;\n\t\t\t\t}\n\t\t\t}\n\t\t} catch {\n\t\t\t// Ignore errors\n\t\t}\n\t\treturn null;\n\t}\n\n\t// Unix: Use 'which' and trust its output (handles Termux and special filesystems)\n\ttry {\n\t\tconst result = spawnSync(\"which\", [executable], {\n\t\t\tencoding: \"utf-8\",\n\t\t\ttimeout: 5000,\n\t\t\tenv: createChildProcessEnvironment(),\n\t\t});\n\t\tif (result.status === 0 && result.stdout) {\n\t\t\tconst firstMatch = result.stdout.trim().split(/\\r?\\n/)[0];\n\t\t\tif (firstMatch) {\n\t\t\t\treturn firstMatch;\n\t\t\t}\n\t\t}\n\t} catch {\n\t\t// Ignore errors\n\t}\n\treturn null;\n}\n\n/**\n * Resolve shell configuration based on platform and an optional explicit shell path.\n * Resolution order:\n * 1. User-specified shellPath\n * 2. On Windows: Git Bash in known locations, then bash on PATH\n * 3. On Unix: /bin/bash, then bash on PATH, then fallback to sh\n */\nexport function getShellConfig(customShellPath?: string): ShellConfig {\n\t// 1. Check user-specified shell path\n\tif (customShellPath) {\n\t\tif (shellPathExists(customShellPath)) {\n\t\t\treturn getBashShellConfig(customShellPath);\n\t\t}\n\t\tthrow new Error(`Custom shell path not found: ${customShellPath}`);\n\t}\n\n\tif (process.platform === \"win32\") {\n\t\t// 2. Try Git Bash in known locations\n\t\tconst paths: string[] = [];\n\t\tconst programFiles = process.env.ProgramFiles;\n\t\tif (programFiles) {\n\t\t\tpaths.push(`${programFiles}\\\\Git\\\\bin\\\\bash.exe`);\n\t\t}\n\t\tconst programFilesX86 = process.env[\"ProgramFiles(x86)\"];\n\t\tif (programFilesX86) {\n\t\t\tpaths.push(`${programFilesX86}\\\\Git\\\\bin\\\\bash.exe`);\n\t\t}\n\n\t\tfor (const path of paths) {\n\t\t\tif (shellPathExists(path)) {\n\t\t\t\treturn getBashShellConfig(path);\n\t\t\t}\n\t\t}\n\n\t\t// 3. Fallback: search bash.exe on PATH (Cygwin, MSYS2, WSL, etc.)\n\t\tconst bashOnPath = findExecutableOnPath(\"bash.exe\");\n\t\tif (bashOnPath) {\n\t\t\treturn getBashShellConfig(bashOnPath);\n\t\t}\n\n\t\tthrow new Error(\n\t\t\t`No bash shell found. Options:\\n` +\n\t\t\t\t`  1. Install Git for Windows: https://git-scm.com/download/win\\n` +\n\t\t\t\t`  2. Add your bash to PATH (Cygwin, MSYS2, etc.)\\n` +\n\t\t\t\t\"  3. Set shellPath in settings.json\\n\\n\" +\n\t\t\t\t`Searched Git Bash in:\\n${paths.map((p) => `  ${p}`).join(\"\\n\")}`,\n\t\t);\n\t}\n\n\t// Unix: try /bin/bash, then bash on PATH, then fallback to sh\n\tif (shellPathExists(\"/bin/bash\")) {\n\t\treturn getBashShellConfig(\"/bin/bash\");\n\t}\n\n\tconst bashOnPath = findExecutableOnPath(\"bash\");\n\tif (bashOnPath) {\n\t\treturn getBashShellConfig(bashOnPath);\n\t}\n\n\treturn { shell: \"sh\", args: [\"-c\"] };\n}\n\nexport const POWERSHELL_ARGS = [\"-NoProfile\", \"-NonInteractive\", \"-ExecutionPolicy\", \"Bypass\", \"-Command\"] as const;\n\nexport function getPowerShellConfig(): ShellConfig {\n\tif (process.platform !== \"win32\") throw new Error(\"The powershell tool is only available on Windows.\");\n\tlet shell = findExecutableOnPath(\"pwsh.exe\");\n\t// Installation directories may be on any drive and need not be on PATH.\n\tconst programFiles = process.env.ProgramFiles;\n\tif (!shell && programFiles) {\n\t\tconst pwsh7 = win32.join(programFiles, \"PowerShell\", \"7\", \"pwsh.exe\");\n\t\tif (shellPathExists(pwsh7)) shell = pwsh7;\n\t}\n\n\tshell ??= findExecutableOnPath(\"powershell.exe\");\n\tconst systemRoot = process.env.SystemRoot;\n\tif (!shell && systemRoot) {\n\t\tconst windowsPowerShell = win32.join(systemRoot, \"System32\", \"WindowsPowerShell\", \"v1.0\", \"powershell.exe\");\n\t\tif (shellPathExists(windowsPowerShell)) shell = windowsPowerShell;\n\t}\n\n\tif (!shell) throw new Error(\"No PowerShell executable found. Install PowerShell or add it to PATH.\");\n\treturn { shell, args: [...POWERSHELL_ARGS] };\n}\n\nexport function isPowerShellAvailable(): boolean {\n\ttry {\n\t\tgetPowerShellConfig();\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport function getShellEnv(): NodeJS.ProcessEnv {\n\tconst binDir = getBinDir();\n\tconst pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === \"path\") ?? \"PATH\";\n\tconst currentPath = process.env[pathKey] ?? \"\";\n\tconst pathEntries = currentPath.split(delimiter).filter(Boolean);\n\tconst hasBinDir = pathEntries.includes(binDir);\n\tconst updatedPath = hasBinDir ? currentPath : [binDir, currentPath].filter(Boolean).join(delimiter);\n\n\treturn {\n\t\t...process.env,\n\t\t[pathKey]: updatedPath,\n\t};\n}\n\n/**\n * Sanitize binary output for display/storage.\n * Removes characters that crash string-width or cause display issues:\n * - Control characters (except tab, newline, carriage return)\n * - Unicode interlinear annotation characters U+FFF9..U+FFFB\n */\nexport function sanitizeBinaryOutput(str: string): string {\n\t// Removed characters are single UTF-16 code units; surrogate pairs remain intact.\n\treturn str.replace(/[\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\uFFF9-\\uFFFB]/g, \"\");\n}\n\ninterface DetachedChildGuardian {\n\tpostMessage(message: { action: \"track\" | \"untrack\"; pid: number }): void;\n\tterminate(): Promise<number>;\n\tunref(): void;\n}\n\nlet detachedChildGuardian: DetachedChildGuardian | undefined;\n\nconst PARENT_GUARDIAN_SOURCE = `\nconst { parentPort, workerData } = require(\"node:worker_threads\");\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { join } = require(\"node:path\");\nconst tracked = new Set();\nparentPort.on(\"message\", ({ action, pid }) => {\n  if (action === \"track\") tracked.add(pid);\n  else tracked.delete(pid);\n});\nfunction killTree(pid) {\n  if (process.platform === \"win32\") {\n    // Same System32 hardening as killProcessTree: PATH is not trusted here, and an\n    // unconsumed async \"error\" from a failed spawn would take the guardian thread\n    // down and leak every detached child it exists to reap.\n    try {\n      const child = spawn(join(process.env.SystemRoot || \"C:\\\\\\\\Windows\", \"System32\", \"taskkill.exe\"), [\"/F\", \"/T\", \"/PID\", String(pid)], { stdio: \"ignore\", detached: true, windowsHide: true, env: { ...process.env, AI_AGENT: workerData.aiAgent } });\n      child.once(\"error\", () => {});\n    } catch {}\n    return;\n  }\n  try { process.kill(-pid, \"SIGKILL\"); }\n  catch { try { process.kill(pid, \"SIGKILL\"); } catch {} }\n}\nconst timer = setInterval(() => {\n  let parentAlive = true;\n  try { process.kill(workerData.parentPid, 0); } catch { parentAlive = false; }\n  if (parentAlive && (!workerData.stopFile || !existsSync(workerData.stopFile))) return;\n  for (const pid of tracked) killTree(pid);\n  killTree(process.pid);\n}, 50);\ntimer.unref?.();\n`;\n\nexport function startParentProcessGuardian(parentPid: number, stopFile?: string): () => Promise<void> {\n\tif (detachedChildGuardian) return async () => {};\n\tconst guardian = new Worker(PARENT_GUARDIAN_SOURCE, {\n\t\teval: true,\n\t\tworkerData: { parentPid, stopFile, aiAgent: createChildProcessEnvironment().AI_AGENT },\n\t});\n\tdetachedChildGuardian = guardian;\n\tfor (const pid of trackedDetachedChildPids) guardian.postMessage({ action: \"track\", pid });\n\tguardian.unref();\n\treturn async () => {\n\t\tif (detachedChildGuardian !== guardian) return;\n\t\tdetachedChildGuardian = undefined;\n\t\tawait guardian.terminate();\n\t};\n}\n\n/**\n * Detached child processes must be tracked so they can be killed on parent\n * shutdown signals (SIGHUP/SIGTERM).\n */\nconst trackedDetachedChildPids = new Set<number>();\n\nexport function trackDetachedChildPid(pid: number): void {\n\ttrackedDetachedChildPids.add(pid);\n\tdetachedChildGuardian?.postMessage({ action: \"track\", pid });\n}\n\nexport function untrackDetachedChildPid(pid: number): void {\n\ttrackedDetachedChildPids.delete(pid);\n\tdetachedChildGuardian?.postMessage({ action: \"untrack\", pid });\n}\n\nexport function killTrackedDetachedChildren(): void {\n\tfor (const pid of trackedDetachedChildPids) {\n\t\tkillProcessTree(pid);\n\t\tdetachedChildGuardian?.postMessage({ action: \"untrack\", pid });\n\t}\n\ttrackedDetachedChildPids.clear();\n}\n\n/**\n * Kill a process and all its children (cross-platform)\n */\nexport function killProcessTree(pid: number): void {\n\tif (process.platform === \"win32\") {\n\t\t// Use the trusted System32 executable so cleanup does not depend on PATH.\n\t\ttry {\n\t\t\tconst child = spawn(\n\t\t\t\tjoin(process.env.SystemRoot || \"C:\\\\Windows\", \"System32\", \"taskkill.exe\"),\n\t\t\t\t[\"/F\", \"/T\", \"/PID\", String(pid)],\n\t\t\t\t{\n\t\t\t\t\tstdio: \"ignore\",\n\t\t\t\t\tdetached: true,\n\t\t\t\t\t// `detached` gives the child its own console on Windows unless this is\n\t\t\t\t\t// set, so omitting it both flashes a window and pays for a console\n\t\t\t\t\t// allocation on every tree kill. Every other spawn in the fork sets it.\n\t\t\t\t\twindowsHide: true,\n\t\t\t\t\tenv: createChildProcessEnvironment(),\n\t\t\t\t},\n\t\t\t);\n\t\t\t// A failed spawn emits \"error\" asynchronously; consume it to avoid crashing Node.\n\t\t\tchild.once(\"error\", () => {});\n\t\t} catch {\n\t\t\t// Ignore errors if taskkill fails.\n\t\t}\n\t} else {\n\t\t// Use SIGKILL on Unix/Linux/Mac\n\t\ttry {\n\t\t\tprocess.kill(-pid, \"SIGKILL\");\n\t\t} catch {\n\t\t\t// Fallback to killing just the child if process group kill fails\n\t\t\ttry {\n\t\t\t\tprocess.kill(pid, \"SIGKILL\");\n\t\t\t} catch {\n\t\t\t\t// Process already dead\n\t\t\t}\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/utils/shell.ts"],"names":[],"mappings":"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","sourcesContent":["import { accessSync, constants } from \"node:fs\";\nimport { delimiter, join, win32 } from \"node:path\";\nimport { Worker } from \"node:worker_threads\";\nimport { spawn, spawnSync } from \"child_process\";\nimport { getBinDir } from \"../config.js\";\nimport { createChildProcessEnvironment } from \"./child-process.ts\";\n\nexport interface ShellConfig {\n\tshell: string;\n\targs: string[];\n\tcommandTransport?: \"argv\" | \"stdin\";\n}\n\nfunction isLegacyWslBashPath(path: string): boolean {\n\tconst normalized = win32.normalize(path).toLowerCase();\n\tconst systemRoot = process.env.SystemRoot;\n\tif (systemRoot) {\n\t\tif (!/^[a-z]:[\\\\/]/i.test(systemRoot)) return false;\n\t\treturn [\"System32\", \"Sysnative\"].some(\n\t\t\t(directory) => normalized === win32.join(systemRoot, directory, \"bash.exe\").toLowerCase(),\n\t\t);\n\t}\n\t// Fall back to conventional launcher paths only when the Windows directory is unknown.\n\treturn /^[a-z]:\\\\windows\\\\(?:system32|sysnative)\\\\bash\\.exe$/.test(normalized);\n}\n\nfunction getBashShellConfig(shell: string): ShellConfig {\n\treturn isLegacyWslBashPath(shell) ? { shell, args: [\"-s\"], commandTransport: \"stdin\" } : { shell, args: [\"-c\"] };\n}\n\n// On Unix this is identical to existsSync() (both are access(F_OK)), just\n// spelled with try/catch. On Windows we explicitly avoid existsSync(): its\n// extra stat check rejects runnable Store aliases (nodejs/node#36790).\nfunction shellPathExists(path: string): boolean {\n\ttry {\n\t\taccessSync(path, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nconst MISSING_EXECUTABLE_RECHECK_MS = 30_000;\n\ninterface ExecutableLookup {\n\tpath: string | null;\n\tcheckedAt: number;\n}\n\nconst executablePathLookups = new Map<string, ExecutableLookup>();\n\nfunction isReusableLookup(lookup: ExecutableLookup): boolean {\n\treturn lookup.path === null\n\t\t? Date.now() - lookup.checkedAt < MISSING_EXECUTABLE_RECHECK_MS\n\t\t: shellPathExists(lookup.path);\n}\n\n/**\n * Find an executable on PATH (cross-platform), memoized per PATH value.\n * A missing executable is looked up again once its result is 30 seconds old.\n */\nfunction findExecutableOnPath(executable: string): string | null {\n\tconst key = `${executable}\\0${process.env.PATH ?? \"\"}`;\n\tconst cached = executablePathLookups.get(key);\n\tif (cached && isReusableLookup(cached)) return cached.path;\n\tconst path = lookupExecutableOnPath(executable);\n\texecutablePathLookups.set(key, { path, checkedAt: Date.now() });\n\treturn path;\n}\n\nfunction lookupExecutableOnPath(executable: string): string | null {\n\tif (process.platform === \"win32\") {\n\t\t// Windows: use 'where' and check the returned path.\n\t\ttry {\n\t\t\tconst result = spawnSync(\"where\", [executable], {\n\t\t\t\tencoding: \"utf-8\",\n\t\t\t\ttimeout: 5000,\n\t\t\t\tenv: createChildProcessEnvironment(),\n\t\t\t});\n\t\t\tif (result.status === 0 && result.stdout) {\n\t\t\t\tconst firstMatch = result.stdout.trim().split(/\\r?\\n/)[0];\n\t\t\t\tif (firstMatch && shellPathExists(firstMatch)) {\n\t\t\t\t\treturn firstMatch;\n\t\t\t\t}\n\t\t\t}\n\t\t} catch {\n\t\t\t// Ignore errors\n\t\t}\n\t\treturn null;\n\t}\n\n\t// Unix: Use 'which' and trust its output (handles Termux and special filesystems)\n\ttry {\n\t\tconst result = spawnSync(\"which\", [executable], {\n\t\t\tencoding: \"utf-8\",\n\t\t\ttimeout: 5000,\n\t\t\tenv: createChildProcessEnvironment(),\n\t\t});\n\t\tif (result.status === 0 && result.stdout) {\n\t\t\tconst firstMatch = result.stdout.trim().split(/\\r?\\n/)[0];\n\t\t\tif (firstMatch) {\n\t\t\t\treturn firstMatch;\n\t\t\t}\n\t\t}\n\t} catch {\n\t\t// Ignore errors\n\t}\n\treturn null;\n}\n\n/**\n * Resolve shell configuration based on platform and an optional explicit shell path.\n * Resolution order:\n * 1. User-specified shellPath\n * 2. On Windows: Git Bash in known locations, then bash on PATH\n * 3. On Unix: /bin/bash, then bash on PATH, then fallback to sh\n */\nexport function getShellConfig(customShellPath?: string): ShellConfig {\n\t// 1. Check user-specified shell path\n\tif (customShellPath) {\n\t\tif (shellPathExists(customShellPath)) {\n\t\t\treturn getBashShellConfig(customShellPath);\n\t\t}\n\t\tthrow new Error(`Custom shell path not found: ${customShellPath}`);\n\t}\n\n\tif (process.platform === \"win32\") {\n\t\t// 2. Try Git Bash in known locations\n\t\tconst paths: string[] = [];\n\t\tconst programFiles = process.env.ProgramFiles;\n\t\tif (programFiles) {\n\t\t\tpaths.push(`${programFiles}\\\\Git\\\\bin\\\\bash.exe`);\n\t\t}\n\t\tconst programFilesX86 = process.env[\"ProgramFiles(x86)\"];\n\t\tif (programFilesX86) {\n\t\t\tpaths.push(`${programFilesX86}\\\\Git\\\\bin\\\\bash.exe`);\n\t\t}\n\n\t\tfor (const path of paths) {\n\t\t\tif (shellPathExists(path)) {\n\t\t\t\treturn getBashShellConfig(path);\n\t\t\t}\n\t\t}\n\n\t\t// 3. Fallback: search bash.exe on PATH (Cygwin, MSYS2, WSL, etc.)\n\t\tconst bashOnPath = findExecutableOnPath(\"bash.exe\");\n\t\tif (bashOnPath) {\n\t\t\treturn getBashShellConfig(bashOnPath);\n\t\t}\n\n\t\tthrow new Error(\n\t\t\t`No bash shell found. Options:\\n` +\n\t\t\t\t`  1. Install Git for Windows: https://git-scm.com/download/win\\n` +\n\t\t\t\t`  2. Add your bash to PATH (Cygwin, MSYS2, etc.)\\n` +\n\t\t\t\t\"  3. Set shellPath in settings.json\\n\\n\" +\n\t\t\t\t`Searched Git Bash in:\\n${paths.map((p) => `  ${p}`).join(\"\\n\")}`,\n\t\t);\n\t}\n\n\t// Unix: try /bin/bash, then bash on PATH, then fallback to sh\n\tif (shellPathExists(\"/bin/bash\")) {\n\t\treturn getBashShellConfig(\"/bin/bash\");\n\t}\n\n\tconst bashOnPath = findExecutableOnPath(\"bash\");\n\tif (bashOnPath) {\n\t\treturn getBashShellConfig(bashOnPath);\n\t}\n\n\treturn { shell: \"sh\", args: [\"-c\"] };\n}\n\nexport const POWERSHELL_ARGS = [\"-NoProfile\", \"-NonInteractive\", \"-ExecutionPolicy\", \"Bypass\", \"-Command\"] as const;\n\nexport function getPowerShellConfig(): ShellConfig {\n\tif (process.platform !== \"win32\") throw new Error(\"The powershell tool is only available on Windows.\");\n\tlet shell = findExecutableOnPath(\"pwsh.exe\");\n\t// Installation directories may be on any drive and need not be on PATH.\n\tconst programFiles = process.env.ProgramFiles;\n\tif (!shell && programFiles) {\n\t\tconst pwsh7 = win32.join(programFiles, \"PowerShell\", \"7\", \"pwsh.exe\");\n\t\tif (shellPathExists(pwsh7)) shell = pwsh7;\n\t}\n\n\tshell ??= findExecutableOnPath(\"powershell.exe\");\n\tconst systemRoot = process.env.SystemRoot;\n\tif (!shell && systemRoot) {\n\t\tconst windowsPowerShell = win32.join(systemRoot, \"System32\", \"WindowsPowerShell\", \"v1.0\", \"powershell.exe\");\n\t\tif (shellPathExists(windowsPowerShell)) shell = windowsPowerShell;\n\t}\n\n\tif (!shell) throw new Error(\"No PowerShell executable found. Install PowerShell or add it to PATH.\");\n\treturn { shell, args: [...POWERSHELL_ARGS] };\n}\n\nexport function isPowerShellAvailable(): boolean {\n\ttry {\n\t\tgetPowerShellConfig();\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport function getShellEnv(): NodeJS.ProcessEnv {\n\tconst binDir = getBinDir();\n\tconst pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === \"path\") ?? \"PATH\";\n\tconst currentPath = process.env[pathKey] ?? \"\";\n\tconst pathEntries = currentPath.split(delimiter).filter(Boolean);\n\tconst hasBinDir = pathEntries.includes(binDir);\n\tconst updatedPath = hasBinDir ? currentPath : [binDir, currentPath].filter(Boolean).join(delimiter);\n\n\treturn {\n\t\t...process.env,\n\t\t[pathKey]: updatedPath,\n\t};\n}\n\n/**\n * Sanitize binary output for display/storage.\n * Removes characters that crash string-width or cause display issues:\n * - Control characters (except tab, newline, carriage return)\n * - Unicode interlinear annotation characters U+FFF9..U+FFFB\n */\nexport function sanitizeBinaryOutput(str: string): string {\n\t// Removed characters are single UTF-16 code units; surrogate pairs remain intact.\n\treturn str.replace(/[\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\uFFF9-\\uFFFB]/g, \"\");\n}\n\ninterface DetachedChildGuardian {\n\tpostMessage(message: { action: \"track\" | \"untrack\"; pid: number }): void;\n\tterminate(): Promise<number>;\n\tunref(): void;\n}\n\nlet detachedChildGuardian: DetachedChildGuardian | undefined;\n\nconst PARENT_GUARDIAN_SOURCE = `\nconst { parentPort, workerData } = require(\"node:worker_threads\");\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { join } = require(\"node:path\");\nconst tracked = new Set();\nparentPort.on(\"message\", ({ action, pid }) => {\n  if (action === \"track\") tracked.add(pid);\n  else tracked.delete(pid);\n});\nfunction killTree(pid) {\n  if (process.platform === \"win32\") {\n    // Same System32 hardening as killProcessTree: PATH is not trusted here, and an\n    // unconsumed async \"error\" from a failed spawn would take the guardian thread\n    // down and leak every detached child it exists to reap.\n    try {\n      const child = spawn(join(process.env.SystemRoot || \"C:\\\\\\\\Windows\", \"System32\", \"taskkill.exe\"), [\"/F\", \"/T\", \"/PID\", String(pid)], { stdio: \"ignore\", detached: true, windowsHide: true, env: { ...process.env, AI_AGENT: workerData.aiAgent } });\n      child.once(\"error\", () => {});\n    } catch {}\n    return;\n  }\n  try { process.kill(-pid, \"SIGKILL\"); }\n  catch { try { process.kill(pid, \"SIGKILL\"); } catch {} }\n}\nconst timer = setInterval(() => {\n  let parentAlive = true;\n  try { process.kill(workerData.parentPid, 0); } catch { parentAlive = false; }\n  if (parentAlive && (!workerData.stopFile || !existsSync(workerData.stopFile))) return;\n  for (const pid of tracked) killTree(pid);\n  killTree(process.pid);\n}, 50);\ntimer.unref?.();\n`;\n\nexport function startParentProcessGuardian(parentPid: number, stopFile?: string): () => Promise<void> {\n\tif (detachedChildGuardian) return async () => {};\n\tconst guardian = new Worker(PARENT_GUARDIAN_SOURCE, {\n\t\teval: true,\n\t\tworkerData: { parentPid, stopFile, aiAgent: createChildProcessEnvironment().AI_AGENT },\n\t});\n\tdetachedChildGuardian = guardian;\n\tfor (const pid of trackedDetachedChildPids) guardian.postMessage({ action: \"track\", pid });\n\tguardian.unref();\n\treturn async () => {\n\t\tif (detachedChildGuardian !== guardian) return;\n\t\tdetachedChildGuardian = undefined;\n\t\tawait guardian.terminate();\n\t};\n}\n\n/**\n * Detached child processes must be tracked so they can be killed on parent\n * shutdown signals (SIGHUP/SIGTERM).\n */\nconst trackedDetachedChildPids = new Set<number>();\n\nexport function trackDetachedChildPid(pid: number): void {\n\ttrackedDetachedChildPids.add(pid);\n\tdetachedChildGuardian?.postMessage({ action: \"track\", pid });\n}\n\nexport function untrackDetachedChildPid(pid: number): void {\n\ttrackedDetachedChildPids.delete(pid);\n\tdetachedChildGuardian?.postMessage({ action: \"untrack\", pid });\n}\n\nexport function killTrackedDetachedChildren(): void {\n\tfor (const pid of trackedDetachedChildPids) {\n\t\tkillProcessTree(pid);\n\t\tdetachedChildGuardian?.postMessage({ action: \"untrack\", pid });\n\t}\n\ttrackedDetachedChildPids.clear();\n}\n\n/**\n * Kill a process and all its children (cross-platform)\n */\nexport function killProcessTree(pid: number): void {\n\tif (process.platform === \"win32\") {\n\t\t// Use the trusted System32 executable so cleanup does not depend on PATH.\n\t\ttry {\n\t\t\tconst child = spawn(\n\t\t\t\tjoin(process.env.SystemRoot || \"C:\\\\Windows\", \"System32\", \"taskkill.exe\"),\n\t\t\t\t[\"/F\", \"/T\", \"/PID\", String(pid)],\n\t\t\t\t{\n\t\t\t\t\tstdio: \"ignore\",\n\t\t\t\t\tdetached: true,\n\t\t\t\t\t// `detached` gives the child its own console on Windows unless this is\n\t\t\t\t\t// set, so omitting it both flashes a window and pays for a console\n\t\t\t\t\t// allocation on every tree kill. Every other spawn in the fork sets it.\n\t\t\t\t\twindowsHide: true,\n\t\t\t\t\tenv: createChildProcessEnvironment(),\n\t\t\t\t},\n\t\t\t);\n\t\t\t// A failed spawn emits \"error\" asynchronously; consume it to avoid crashing Node.\n\t\t\tchild.once(\"error\", () => {});\n\t\t} catch {\n\t\t\t// Ignore errors if taskkill fails.\n\t\t}\n\t} else {\n\t\tif (process.platform === \"darwin\") {\n\t\t\t// macOS signals group members individually after releasing the group lock. A killed\n\t\t\t// child can wake its waiting shell before that shell is signalled, letting `a; b`\n\t\t\t// start b during cancellation (pi #11252). Stop the group first to reduce this race;\n\t\t\t// this is best-effort, not an atomic freeze. SIGKILL also kills stopped processes.\n\t\t\t// Linux holds tasklist_lock across group signalling; child exit notification needs\n\t\t\t// its write lock, so the shell is signalled before observing the killed child's exit.\n\t\t\ttry {\n\t\t\t\tprocess.kill(-pid, \"SIGSTOP\");\n\t\t\t} catch {\n\t\t\t\t// A failed stop must not prevent the kill attempt or its single-process fallback.\n\t\t\t}\n\t\t}\n\t\t// Use SIGKILL on Unix/Linux/Mac\n\t\ttry {\n\t\t\tprocess.kill(-pid, \"SIGKILL\");\n\t\t} catch {\n\t\t\t// Fallback to killing just the child if process group kill fails\n\t\t\ttry {\n\t\t\t\tprocess.kill(pid, \"SIGKILL\");\n\t\t\t} catch {\n\t\t\t\t// Process already dead\n\t\t\t}\n\t\t}\n\t}\n}\n"]}

package/docs/custom-provider/oauth.md

@@ -156,13 +156,20 @@ interface OAuthLoginCallbacks {
   onAuth(params: { url: string }): void;
 
   // Show device code (for device authorization flow)
-  onDeviceCode(params: { userCode: string; verificationUri: string }): void;
+  onDeviceCode(params: {
+    userCode: string;
+    verificationUri: string;
+    openBrowserOnConfirm?: boolean; // default true
+    copyCodeOnConfirm?: boolean; // default true
+  }): void;
 
   // Prompt user for input (for manual token entry)
   onPrompt(params: { message: string }): Promise<string>;
 }
 ```
 
+In `/login`, press Enter (`tui.select.confirm`) to open the device-login URL and copy the code, or log in manually. Providers can disable either action with `openBrowserOnConfirm: false` or `copyCodeOnConfirm: false` in `onDeviceCode` or native `AuthEvent` notifications.
+
 ### OAuthCredentials
 
 Credentials are persisted in `~/.atomic/agent/auth.json` (legacy `~/.pi/agent/auth.json` may be read for compatibility):

package/docs/extensions/api-reference.md

@@ -800,6 +800,8 @@ The transformer receives the Markdown string and a context with:
 - `messageType` — `"user"`, `"assistant"`, or `"assistant-thinking"`
 - `isStreaming` — `true` for partial assistant updates; `false` for user, finalized assistant, and restored messages
 - `availableWidth` — exact terminal columns available for the transformed Markdown content
+- `messageId` — the session entry id when the message is rendered from the saved session (resume, `/tree`, rebuilds); `undefined` for live messages
+- `timestamp` — the session entry's ISO timestamp under the same conditions; `undefined` for live messages
 
 Return the transformed Markdown:
 

package/docs/intercom/operations.md

@@ -18,6 +18,7 @@ Start with the state you can observe. The existing sections below explain the co
 | Terminal stage delivery failure | The stage fails without spending a model retry or fallback. | Fix the delivery failure rather than changing models. The typed failure applies to every model candidate. See [How it works](#how-it-works). |
 | Destination-side admission failure | A blocking non-parent asker receives a correlated error instead of waiting for the reply timeout. | Act on the returned destination error, then send again when the destination can admit the message. See [Workflow and subagent notifications](#workflow-and-subagent-notifications). |
 | Broker restart or concurrent startup | Sessions disappear briefly, or several sessions invoke Intercom at the same time. | Usually no action is needed. Clients reconnect, and the spawn lock prevents duplicate brokers. See [How it works](#how-it-works). |
+| Broker accepts connections but stops answering | List, send, or workflow route requests time out. | Allow about a minute for automatic broker replacement, then reconnect backoff. A request timeout can add up to five seconds for a health check. Check the logs below if it repeats. See [How it works](#how-it-works). |
 | Broker does not start | The startup or readiness error quotes the broker log path and includes a bounded tail. | Read `~/.atomic/agent/intercom/broker.log`, or the equivalent path below `ATOMIC_CODING_AGENT_DIR`. See [How it works](#how-it-works). |
 | Half-closed peer or undeliverable send | The send returns `Session not found`; its message id remains retryable. | Refresh the session list and retry after the target reconnects. See [How it works](#how-it-works). |
 | Subagent being restored after a restart | A send or ask to a background subagent that its owner will restore, or is restoring, waits instead of returning `Session not found`. For a plain session's subagent this holds from the moment its reopened session starts. For a subagent of an interrupted workflow stage it holds from the moment the session that launched the run is back and the run is addressable, until the stage, once running again, restores it. It holds for the owner and for any session in the subagent's group, whether the message uses the subagent's name, its Atomic session ID, or the Intercom session ID it had before the restart. The name and Atomic session ID are held from the first moment; the pre-restart ID is held once the owner has read it from the subagent's own session, usually within a fraction of a second. Each waiting message is delivered once, in the order it was sent, when the subagent reconnects. If the subagent has not reconnected within 20 seconds, the sender gets a "still being restored" error. If the subagent did not survive the restart, the sender gets an explicit "did not survive the restart and is gone" error. If another Atomic session takes over the interrupted run, the senders waiting for its subagents get an error saying so. None of these returns `Session not found`. | Retry later if the subagent has not reconnected yet, launch a new subagent if the old one is gone, or send again to the session that took over the run. See [How it works](#how-it-works). |
@@ -59,6 +60,8 @@ A stage name reused by a later occurrence in the same run (for example `reviewer
 
 The local broker starts on first use and exits after five seconds without registered sessions. Clients reconnect automatically using delays of 1, 2, 5, 10, then 30 seconds. Explicit connection failures remain visible while background recovery continues.
 
+If the broker stops answering health requests for about a minute, it terminates itself so clients can start a replacement. A single slow request does not restart a responsive broker. This protection starts with a newly launched broker; a broker still running from an older Atomic version must restart before it gains it. A process suspended by the operating system cannot run its own recovery. If it remains stuck, verify which process owns the broker before stopping it manually. Do not delete the Intercom database or key files.
+
 If workflow-stage warm-up exhausts its retries, a stage with queued messages fails without consuming them or spending a model retry. Restore broker availability before retrying the work. Protocol, authentication, configuration, and terminal delivery failures require attention rather than a model change.
 
 For `send`, `ask`, and `reply`, the tool owns reconnect recovery. One invocation makes the initial attempt and up to three retries, waiting 1, 2, then 5 seconds between attempts. Retries preserve the original message ID, caller arguments, attachment order and presence, and reply thread. The model neither supplies nor receives a retry token. Every new invocation is a fresh intentional operation, even with identical text. Existing integrations must stop passing `retryToken`; caller-supplied tokens are refused without sending.
@@ -77,7 +80,7 @@ Custom hosts may declare an optional `recipientPurpose` on session registration
 
 Configuration and diagnostics live in `~/.atomic/agent/intercom/`, or under `ATOMIC_CODING_AGENT_DIR`. The legacy `PI_CODING_AGENT_DIR` applies when the Atomic variable is unset. Edit `config.json` for [Intercom settings](/intercom/reference#configuration).
 
-When startup fails, read the `broker.log` path printed in the error. The log is replaced on each broker spawn and ordinary broker diagnostics are capped at 8 KiB, so capture relevant output before retrying.
+When startup fails, read the `broker.log` path printed in the error. Ordinary diagnostics are capped at 8 KiB per broker. The next spawn keeps a bounded copy in `broker.log.previous`; `broker-watchdog.log` separately retains the latest automatic termination's time, PID, and reason. Preserve these files when reporting repeated stalls or restarts. They live under the Intercom directory above.
 
 ## Workflow and Subagent Notifications
 
@@ -128,9 +131,9 @@ By default, each machine's broker serves only the sessions on that machine. With
 
 ### Turning it on
 
-Give every machine the same shared top-level `storage` selection, including the same `prefix`. To reach other machines, the selection must be an [adapter](/storage#selecting-an-adapter) whose module implements `openDatabase` and connects to a database that every machine can reach, as described in [Sharing storage across hosts](/storage#sharing-storage-across-hosts). Install the adapter module on every machine.
+Give every machine the same shared top-level `storage` selection, including the same `prefix`. To reach other machines, the selection must be an [adapter](/storage#selecting-an-adapter) whose module implements `openDatabase` and connects to a database that every machine can reach, as described in [Sharing storage across hosts](/storage#sharing-storage-across-hosts). Install the adapter on every machine, for example as an [Atomic package](/storage#adapters-from-atomic-packages) so that `atomic install` also brings its driver.
 
-Multi-node routing needs Atomic installed from npm (`npm install -g @bastani/atomic`). The standalone binary's broker cannot load storage adapters, so routing stays off there even with a shared `storage` selection, and sessions on other machines cannot be reached. Use an npm installation on every machine that should take part.
+Both the npm installation and the standalone binary run multi-node routing and load storage adapters.
 
 The broker takes its selection from one of two places:
 
@@ -148,14 +151,20 @@ The broker takes its selection from one of two places:
 }
 ```
 
-One broker serves every session in an agent directory and keeps the selection it started with until it exits. After changing the selection, close the Atomic sessions on that machine. The broker exits five seconds after its last session disconnects, and the next session that uses Intercom starts one with the new selection.
+One broker serves every session in an agent directory and keeps the selection it started with until it exits. After changing the selection, run `atomic intercom restart`. It asks the broker to shut down; the sessions connected to it reconnect within a few seconds, and the first one starts a broker with the new selection. The command waits for that broker and prints its multi-node routing state. When no session is connected, the next session that uses Intercom starts the new broker. A broker started by an older Atomic version, which does not answer the request, is stopped with SIGTERM.
+
+`atomic intercom status` shows whether the broker is running, how many sessions it serves, whether it uses the current selection, and its multi-node routing state with the number of other brokers live in the shared database. `atomic storage status` shows the same together with the selection for sessions and workflow runs; see [Checking the selected storage](/storage#checking-the-selected-storage). In a session, `intercom({ action: "status" })` adds a `Multi-node routing:` line, for example `Multi-node routing: on (adapter @bastani/atomic-storage-libsql, prefix none), 1 peer broker live (build-host)`.
+
+Each broker writes its multi-node state to `broker.log` when it starts: `Intercom multi-node routing is on (adapter <adapter>, prefix <prefix>)` once it has opened the shared database, or `Intercom multi-node routing is off: <reason>`. `<adapter>` is `sqlite` for a `path` selection.
 
 Multi-node routing stays off, and Intercom behaves exactly as on a single machine, when the selection is:
 
 - absent, including when only project settings (`.atomic/settings.json`), `sessions.storage`, `workflows.journal`, `ATOMIC_SESSIONS_STORAGE`, or `ATOMIC_WORKFLOWS_JOURNAL` select storage;
 - in memory: `{ "memory": true }` or `{ "path": ":memory:" }`;
 - an adapter that implements only `openSessionStore` or `openRunJournal` and has no `openDatabase`;
-- invalid, for example an `env` secret that is not set in the broker's environment, or an adapter module that cannot be loaded. The broker then writes `Intercom multi-node routing is off: <reason>` to `broker.log`.
+- invalid, for example an `env` secret that is not set in the broker's environment, or an adapter module that cannot be loaded. Sessions warn at startup when the Atomic they run cannot load the adapter.
+
+In each case the broker writes `Intercom multi-node routing is off: <reason>` to `broker.log`.
 
 A `path` selection, including the default storage file, is a local SQLite file. Only brokers on the same machine that open the same file share it. Do not put it on a network filesystem.
 
@@ -204,15 +213,15 @@ When a whole machine or its broker stops, its sessions still look connected for
 
 **A session on another machine does not appear in `intercom list`.**
 
-- Check that both machines use the same storage selection and the same `prefix`, from settings or from the process that started each broker. A broker started before you changed the selection keeps the old one until it exits.
-- Check `broker.log` on both machines for `Intercom multi-node routing is off: <reason>` or `Intercom multi-node routing is unavailable: <reason>`. An absent, in-memory, or domain-only selection stays off without a message, and a `path` selection reaches only brokers on the same machine.
+- Run `atomic storage status` on both machines. Both must use the same storage selection and the same `prefix`, from settings or from the process that started each broker, and the broker must report `storage: matches the selection above`. A broker started before you changed the selection keeps the old one until `atomic intercom restart` replaces it.
+- Check that each broker reports multi-node routing `on` with the other broker live, in `atomic intercom status` or in `broker.log`. `Intercom multi-node routing is off: <reason>` or `Intercom multi-node routing is unavailable: <reason>` there gives the cause. A `path` selection reaches only brokers on the same machine, and a machine whose broker is not running is not live.
 - A session appears only after it connects to Intercom, which happens lazily. Ask it to use Intercom once, for example `intercom({ action: "status" })`.
 - Both sessions must share a group.
 - When the database is slow to answer, `intercom list` shows only local sessions. Try again.
 
 **A send stays queued.** The recipient is offline. It receives the message when the same Atomic session connects to Intercom again with the same home group, on a machine that uses the same storage and prefix. A session reopened on a machine with a different selection never sees it.
 
-**The database is unavailable.** Messages between sessions on the same machine keep working. A send to a session on another machine fails with `Session not found on this node, and Intercom could not reach the shared storage database to look for it on other nodes. Try again once the database is available.` If the database cannot be opened when the broker starts, the broker logs `Intercom multi-node routing is unavailable: <reason>` and retries after 1 second, doubling up to every 30 seconds. Intercom never falls back to in-memory storage. If sends keep failing after the database is back, close the sessions on that machine so that a new broker starts.
+**The database is unavailable.** Messages between sessions on the same machine keep working. A send to a session on another machine fails with `Session not found on this node, and Intercom could not reach the shared storage database to look for it on other nodes. Try again once the database is available.` If the database cannot be opened when the broker starts, the broker logs `Intercom multi-node routing is unavailable: <reason>` and retries after 1 second, doubling up to every 30 seconds. Intercom never falls back to in-memory storage. If sends keep failing after the database is back, run `atomic intercom restart` so that a new broker starts.
 
 **An ask to a session on another machine never gets an answer.** If that session disconnects before it answers, the asker is not told, and waits until the ask times out after 10 minutes.
 

package/docs/intercom/reference.md

@@ -28,7 +28,7 @@ description: The intercom tool contract and every intercom setting.
 | `ask` | Sends a message and blocks until a live recipient replies (10-minute timeout). An ask to a known workflow stage whose session has not initialized is refused with `pending_stage_ask_unsupported` and recommends ordinary `send`; holding a waiter until a stage eventually starts would be unbounded. A live recipient disconnect fails promptly. Parallel children continue in the same execution after a correlated reply; single-child parent handoffs remain unchanged. |
 | `reply` | Replies to the intercom-triggered message of the current turn; otherwise falls back to the single unresolved inbound ask. With multiple pending asks, pass `to` or inspect with `pending` first. |
 | `pending` | Lists unresolved inbound asks with sender, message ID, elapsed time, and a short preview. |
-| `status` | Shows connection status, session ID, every group this session belongs to, and the count of active sessions visible through those memberships. A `group` filter remains a read-only peek. |
+| `status` | Shows connection status, session ID, every group this session belongs to, the count of active sessions visible through those memberships, and the broker's multi-node routing state with the number of other brokers live in the shared database. A `group` filter remains a read-only peek. |
 
 To give two plain chat sessions a private shared membership, have both call:
 

package/docs/keybindings.md

@@ -179,7 +179,7 @@ Both keys are recognized by their physical identity, not by the configured `app.
 
 Ctrl+C is the host's escape hatch whenever an engine-owned `ctx.ui.custom()` component or overlay holds input: those forward every key to the engine, so a component that never resolves would swallow Ctrl+C. Which component gets the press is decided per mount, in this order:
 
-1. If the engine is provably not answering, the first press terminates and replaces it — a wedged child cannot run the component's own handler either. "Not answering" means the watchdog has declared it unresponsive, a cooperative abort has gone unanswered past the same one-second threshold, a replacement has been waiting for readiness past it, or a replacement failed. A failed replacement keeps Ctrl+C armed so another press can try again; Atomic never retries on its own.
+1. If the engine stops answering, the first press terminates and replaces it. This includes a queue clear or cancellation of chat, a shell command, compaction, or a retry unanswered for over one second, a failed clear or cancellation, a replacement waiting over one second for readiness, or a failed replacement. Engine heartbeats do not disarm recovery for a stalled control request. A failed replacement keeps Ctrl+C available for another attempt; a control failure never triggers an automatic restart.
 2. Otherwise, if the component declared `handlesCtrlC` when it was mounted, it receives the press and keeps its own Skip, Close, or cancel behavior. The bundled workflow surfaces declare it. If the same component is still holding input on the next press, that press closes it.
 3. Otherwise the first press closes that one component, exactly as if it had been cancelled: its `ctx.ui.custom()` promise resolves with `undefined`, the editor comes back, and the engine — along with everything else it has mounted or is running — is left alone.
 

package/docs/packages/authoring.md

@@ -52,6 +52,21 @@ Entries use the same schema as `mcp.json`, including URL environment-variable in
 
 Contributed servers have the lowest precedence: users can replace or disable one by name in their own MCP configuration, and filter them with `mcpServers` patterns in settings. Project packages contribute servers only in trusted projects. For a server whose configuration is computed at runtime, call [`pi.registerMcpServer()`](/extensions/api-reference#pi-registermcpserver-name-config) from an extension.
 
+### Storage Adapters
+
+A package can provide [storage adapters](/storage#selecting-an-adapter) with `storageAdapters`, a list of adapter module paths relative to the package root. Put the database driver in `dependencies` so `atomic install` installs it with the package, and list `@bastani/atomic` in `peerDependencies`:
+
+```json
+{
+  "name": "@example/atomic-libsql",
+  "dependencies": { "@libsql/client": "0.18.0" },
+  "peerDependencies": { "@bastani/atomic": "*" },
+  "atomic": { "storageAdapters": ["./libsql-adapter.ts"] }
+}
+```
+
+Users select the adapter with the package name, for example `"storage": { "adapter": "@example/atomic-libsql" }`, or with `<package>/<name>` when the package lists several adapters, where `<name>` is the adapter file's name without its extension. Storage adapters are only read from the manifest, never from a convention directory, and only from packages in user settings. See [Adapters from Atomic packages](/storage#adapters-from-atomic-packages).
+
 ### Gallery Metadata
 
 The package gallery currently recognizes legacy `pi-package` metadata, while new Atomic packages should also include `atomic-package`. Add `video` or `image` fields to show a preview:

package/docs/packages.md

@@ -1,13 +1,13 @@
 ---
 title: "Atomic packages"
-description: "Install, manage, and share Atomic packages that bundle extensions, skills, prompt templates, themes, workflows, and MCP servers."
+description: "Install, manage, and share Atomic packages that bundle extensions, skills, prompt templates, themes, workflows, MCP servers, and storage adapters."
 ---
 
 > Atomic can help you create packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
 
 # Atomic Packages
 
-Atomic packages bundle extensions, skills, prompt templates, themes, workflow definitions, and MCP servers so you can share them through npm or git. Declare resources in `package.json` under the `atomic` key, or use conventional directories.
+Atomic packages bundle extensions, skills, prompt templates, themes, workflow definitions, MCP servers, and [storage adapters](/storage#adapters-from-atomic-packages) so you can share them through npm or git. Declare resources in `package.json` under the `atomic` key, or use conventional directories.
 
 ## Where to go next
 
@@ -28,6 +28,7 @@ Read this page to install and manage packages, then continue:
   - [Creating an Atomic Package](/packages/authoring#creating-an-atomic-package)
     - [Gallery Metadata](/packages/authoring#gallery-metadata)
     - [MCP Servers](/packages/authoring#mcp-servers)
+    - [Storage Adapters](/packages/authoring#storage-adapters)
   - [Package Structure](/packages/authoring#package-structure)
     - [Convention Directories](/packages/authoring#convention-directories)
   - [Dependencies](/packages/authoring#dependencies)

package/docs/providers.md

@@ -39,6 +39,8 @@ OpenRouter opens its browser PKCE flow and asks whether to mint a new API key. C
 
 Kimi Code displays its device URL/code and polls until approval, then refreshes expired tokens automatically.
 
+Device-code logins (Kimi Code, GitHub Copilot, Meta, and extension providers) show the URL and code without opening a browser. Press Enter to open the URL and copy the code, or open it yourself and type the code.
+
 Built-in and extension-provided OAuth work in both direct and isolated sessions. Login completes once credentials are saved; model-catalog refresh runs separately.
 
 Escape or Ctrl+C quietly cancels the matching login, including immediate/pre-device native aborts, and leaves the previously committed credential and catalog unchanged. Provider denial, device expiry, timeout, browser/network/protocol failure, malformed responses, token exchange, and persistence failures remain visible. Atomic claims success when the provider flow and credential persistence complete; it does not wait for model-catalog or ambient-availability refresh work.

package/docs/reference/cli.md

@@ -90,6 +90,23 @@ Once the complete credential reaches stdout, the command has succeeded. If the s
 
 `auth check --credentials --json` may instead write a credential-free JSON status object on a non-zero check result. See [Security](/security#credential-export) before wiring this into a script.
 
+## Storage and Intercom Commands
+
+```bash
+atomic storage status [--json]                                       # Selection, source, adapter and connection per domain
+atomic storage join <url> [--token-file <path>] [--prefix <prefix>]  # Use a shared libSQL / Turso database
+atomic intercom status                                               # This machine's Intercom broker and multi-node state
+atomic intercom restart                                              # Replace the broker so it reads the current selection
+```
+
+`atomic storage status` reports, for sessions, workflow runs, and Intercom, the selected storage, where the selection comes from (an environment variable, project or global settings, or the default) and the outranked selections, whether the adapter loads, and whether the database answers a `SELECT 1`. It also shows the running Intercom broker: whether it uses the current selection, its multi-node routing state, and the other brokers live in the shared database. It creates and changes nothing, and exits `1` when a selection is invalid, an adapter cannot load, or a database does not answer.
+
+`atomic storage join` checks the token and the connection with `@bastani/atomic-storage-libsql`, stores the trimmed token in a new `storage-token.<id>` file in the agent directory with mode 600, writes only the global `storage` setting, and lists the environment variables and settings that override it. Previous token files are never overwritten; a settings-write failure removes only the new token. It creates no tables. `--token-file` is required except for absolute `file:` URLs; relative file URLs and URLs that contain the token itself (a user name, a password, or an `authToken` parameter) are refused. When the package is not installed, it prints the install command. See [Storage](/storage#joining-a-machine-to-a-shared-database).
+
+`atomic intercom restart` asks the broker to shut down (an older broker gets SIGTERM), waits for it to exit, and then for a reconnecting session to start a new broker, whose state it prints. Without connected sessions, the next session that uses Intercom starts one.
+
+See [Joining a machine to a shared database](/storage#joining-a-machine-to-a-shared-database) and [Running Intercom across machines](/intercom/operations#running-intercom-across-machines).
+
 ## Modes
 
 | Flag | Description |

package/docs/sdk.md

@@ -162,6 +162,39 @@ const { session } = await createAgentSession({
 });
 ```
 
+### Shared resource admission
+
+SDK hosts can pass `resourceAdmission` to `createAgentSession()` to share their own capacity policy across sessions and managed shell commands:
+
+```typescript
+import type { ResourceAdmission } from "@bastani/atomic";
+
+const resourceAdmission: ResourceAdmission = {
+  async acquire(kind, signal, request) {
+    if (request?.delegated) {
+      const permit = capacity.tryAcquire(kind);
+      if (!permit) throw new Error("No capacity left for a delegated child session");
+      return async () => permit.release();
+    }
+    const permit = await capacity.acquire(kind, { signal });
+    return async () => permit.release();
+  },
+};
+const { session } = await createAgentSession({ resourceAdmission });
+```
+
+`capacity` is your host's admission service. `kind` is `"session"` or `"process"`. Make acquisition cancellation-aware and the returned release function idempotent. `resourceAdmissionSignal` cancels a wait for session capacity; children inherit the admission service, not that signal. Pass the same service whenever your runtime factory creates a replacement session.
+
+A session holds its permit until clean disposal. A managed command holds its permit through background execution and confirmed process cleanup, even after an observation wait returns. Failed launches release their permits after rollback. Cleanup failures keep capacity reserved; inspect and resolve them instead of recycling a slot on a timer. Arbitrary processes created outside Atomic's managed command APIs are not counted.
+
+Your admission service must reconcile abandoned holders after a host crash. Atomic does not treat lease expiry as cleanup proof or clear a service's retained permits automatically.
+
+On Unix, Atomic calls `permit.bindProcess({ kind: "unix-process-group", id })` on a process permit once the command's process group exists and before the launch returns, if the permit provides it. Persist the identity with the permit so a replacement host can check whether the group is still alive before it frees the capacity. The identity only names the group and gives no right to signal it. Windows commands report no identity, so keep those permits reserved until normal cleanup confirms them. If `bindProcess` rejects, Atomic cancels the command, fails the launch, and releases the permit only after cleanup is confirmed.
+
+A parent session keeps its permit while it waits for a child, so a child that queued for a permit could wait on its own parent. Atomic marks child sessions (subagents and other sessions built from `getChildSessionOptions()`) with `request.delegated`. For those requests, grant a permit immediately or throw. Never queue them or exceed the cap. A cap of one, or a cap filled by parents, therefore rejects delegation with your error instead of stalling. Set the cap above the number of parents that can be live at once if you need children to run.
+
+Use `withResourceAdmission(resourceAdmission, async () => { ... })` to apply a service to SDK sessions and managed commands launched within an asynchronous operation, including commands using an existing task owner. An explicit session service wins for that session; commands in the operation use its scoped service.
+
 ### Session storage
 
 `createAgentSession()` persists sessions in `~/.atomic/workflows/journal.sqlite` by default, sharing the file with workflow runs under separate `session_` and `wf_` table prefixes. Pass `sessionStore` to choose storage explicitly:
@@ -297,6 +330,10 @@ Without a `journal` option, the session's own `workflows.journal` setting applie
 
 Without a per-run or per-session option, `ATOMIC_WORKFLOWS_JOURNAL` or a non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH` wins, then `ATOMIC_STORAGE`, then `workflows.journal`, then shared top-level `storage`. Setting both journal variables is a conflict. Nearer-scope settings replace whole selections. Relative settings paths resolve against Atomic home. The default journal is `~/.atomic/workflows/journal.sqlite`; an empty shared selection uses `~/.atomic/storage.sqlite`. Keep the original journal and working directory to resume saved runs. Invalid configuration and storage failures reject rather than switching to memory. See [Workflow storage settings](/settings#workflow-storage) and [Selecting storage per process](/storage#selecting-storage-per-process).
 
+### Intercom in standalone workflows
+
+Workflow stages run by the standalone `run()` API can use Intercom when the stage has access to the `intercom` tool, including with `executionMode: "non_interactive"`. Atomic opens Intercom when an eligible stage starts and closes the workflow route when the run settles. Intercom remains unavailable when a stage excludes the tool or disables its builtin package. A local session that needs to steer a standalone run can join `workflow:<rootRunId>` and send to a stage or `workflow:<rootRunId>/**`. See [Programmatic usage](/workflows/api-reference#programmatic-usage) for details.
+
 ### Workflow run control
 
 `session.workflows` controls this session's runs without slash commands or the model-facing `workflow` tool. A fresh session can inspect a durable root by its full UUID within the same working directory and journal. Inspection stays read-only and does not add the run to `listRuns()`.

package/docs/settings.md

@@ -577,13 +577,44 @@ Workflow runs use a SQLite journal, by default the local file `~/.atomic/workflo
 }
 ```
 
+#### Local worker pools
+
+Local worker pools are disabled unless `workflows.localWorkers` is set. With the option omitted, Atomic creates no worker tables, processes, or polling loops. A worker definition must be importable from its module path and export name. Only first-level `ctx.workflow(...)` child subtrees run in the pool; a root closure stays in the main process, and nested children stay on their assigned worker.
+
+```json
+{
+  "workflows": {
+    "localWorkers": {
+      "count": 4,
+      "definitions": [
+        { "path": "./workflows/research.ts", "exportName": "research" }
+      ]
+    },
+    "admission": {
+      "limits": { "session": 4, "process": 8 },
+      "userLimits": { "session": 8, "process": 16 },
+      "userDatabase": "/Users/alex/.atomic/workflows/journal.sqlite",
+      "host": { "maxLoadPerCpu": 2, "minFreeMemoryBytes": 2147483648 }
+    }
+  }
+}
+```
+
+`count` is a positive integer. Paths in the settings object resolve against the invocation working directory. Worker settings and entry-module digests are saved with the root; resume refuses changed settings or definitions. The entry-module digest does not include imported dependencies.
+
+`limits` caps agent sessions and managed tool processes for one root. Session permits cover creation through disposal, including fallback and delegated sessions. Process permits last until confirmed cleanup; yielding an observation wait does not free one. Processes outside Atomic's managed tools are not counted. `host` load and memory thresholds gate launches but do not impose hard OS limits.
+
+`userLimits` counts across runs only when all participating runs use the same canonical local SQLite journal. Set `userDatabase` to that exact path, and pass the admission options to participating non-pooled SDK runs. This coordinates processes for one local user; it is not a tenant isolation boundary.
+
+Workers require native process and boot identity and are currently supported only on Linux and macOS. Windows and hosts without those identities refuse activation, even if no process cap is configured. Remote workers are not supported. SDK callers cannot combine the pool with process-bound adapters, UI, persistence, or similar overrides. An unregistered or non-importable child fails; Atomic does not execute it locally as a fallback. Recovery may repeat external effects that occurred after a checkpoint, so use stable idempotency keys for operations that must not be repeated.
+
 Relative settings paths resolve against the Atomic home directory, normally `~/.atomic`, not the project directory. Precedence is SDK `RunOpts.journal` (or `createAgentSession({ journal })` for a session's `workflow` tool), `--storage` or `--storage-file`, `ATOMIC_WORKFLOWS_JOURNAL` or non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH`, `ATOMIC_STORAGE`, `workflows.journal`, shared top-level `storage`, then the default journal file. An empty environment variable is ignored. SDK sessions read `workflows.journal` from the settings they were given, so `SettingsManager.inMemory(...)` selects a journal per session. A present empty journal block selects the journal default rather than inheriting shared storage. See [Selecting storage per process](/storage#selecting-storage-per-process).
 
 To keep workflow records only in memory, set `"journal": { "memory": true }`. Do not combine `memory: true` with a non-empty `path`. Memory must be selected explicitly and cannot recover runs after the process exits; an environment path still takes precedence over this setting.
 
 Project `workflows.journal` and `storage` each replace their global selection as a whole, including options, secrets, and prefix. For example, a project can select `{ "memory": true }` over a global path. Invalid selected settings raise `StorageConfigError` instead of trying a lower-precedence selection. Combining `memory: true` with a non-empty `path` is an error.
 
-To use your own database driver, install an adapter module and select it by module specifier:
+To use your own database driver, install an adapter module, for example as an [Atomic package](/storage#adapters-from-atomic-packages), and select it by package name or module path:
 
 ```json
 {
@@ -596,7 +627,7 @@ To use your own database driver, install an adapter module and select it by modu
 }
 ```
 
-The shared `storage` setting supplies defaults for both sessions and the journal. Use `sessions.storage` or `workflows.journal` for a domain-only override. A shared empty selection uses `~/.atomic/storage.sqlite`. Atomic bundles no remote driver. Adapter modules execute code, so review them before trusting project settings. Secret references accept `{ "env": "VARIABLE" }` or `{ "file": "token.txt" }`; relative secret files resolve against Atomic home and their contents are passed verbatim. See [Storage adapters](/storage#selecting-an-adapter).
+The shared `storage` setting supplies defaults for both sessions and the journal. Use `sessions.storage` or `workflows.journal` for a domain-only override. A shared empty selection uses `~/.atomic/storage.sqlite`. Atomic bundles no remote driver. Adapter modules execute code, so review them before trusting project settings. Secret references accept `{ "env": "VARIABLE" }` or `{ "file": "token.txt" }`; relative secret files resolve against Atomic home, and their contents are passed as written except for one trailing line ending (`\n` or `\r\n`), which is removed. See [Storage adapters](/storage#selecting-an-adapter).
 
 Changing the journal selects a different run history. Preserve the original file to inspect or resume its runs. The default local file needs no separate server; a remote database requires an adapter, and every host that shares runs must select the same database and prefix. See [Sharing storage across hosts](/storage#sharing-storage-across-hosts). If the selected journal cannot be opened or written, the action fails with a typed storage error rather than selecting memory. Restore access to the store and inspect the retained run before retrying. See [Durable workflows](/workflows/operations#durable-workflows-and-cross-session-resume).