@dreamlake/dreamlake-cli 0.95.0 → 0.96.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -43,6 +43,8 @@ export const helpExamples = {
43
43
  "hosts ssh": "dreamlake hosts ssh geyang/dev/worker --duration 1800",
44
44
  "exec": "dreamlake exec geyang/dev/worker -- uname -a\ndreamlake exec geyang/dev/worker --timeout 30 -- sh -c 'printf \"%s\\n\" \"$HOME\"'",
45
45
  "hosts exec": "dreamlake hosts exec geyang/dev/worker -- python3 -c 'print(\"hello\")'",
46
+ "hosts upgrade": "dreamlake hosts upgrade geyang/dev/worker --nymph-version 0.1.32 --dry-run\ndreamlake hosts upgrade geyang/dev/worker --nymph-version 0.1.32\ndreamlake hosts upgrade 'geyang/lab/*' --nymph-version 0.1.32 --concurrency 4 --max-failures 2\ndreamlake hosts upgrade --all --namespace geyang --nymph-version 0.1.32 --json",
47
+ "hosts rollback": "dreamlake hosts rollback geyang/dev/worker\ndreamlake hosts rollback geyang/dev/worker --upgrade-id 20261029-001 --json",
46
48
  "infra list": "dreamlake infra list --namespace fortyfive --project dreamlake-infra --json",
47
49
  "infra status": "dreamlake infra status da8e49cf-1b37-446f-9494-9620faf3192d --json",
48
50
  "infra connect": "dreamlake infra connect da8e49cf-1b37-446f-9494-9620faf3192d",
@@ -81,11 +83,11 @@ export const helpExamples = {
81
83
  "notes insert": "dreamlake notes insert --note \"$NOTE_ID\" --ind 0 --text 'Review: ' \\\n --base-revision \"$BASE\" --json\n# ACK is the revision returned by the insertion receipt.\ndreamlake notes read \"$NOTE_ID\" --at \"$ACK\"",
82
84
  "notes delete": "dreamlake notes delete 'obsolete paragraph' --note \"$NOTE_ID\" \\\n --base-revision \"$BASE\" --json\n# Pin verification to the receipt's acknowledged revision.\ndreamlake notes read \"$NOTE_ID\" --at \"$ACK\"",
83
85
  "notes write": "dreamlake notes read \"$NOTE_ID\" --json > baseline.json\nBASE=$(jq -er .revision baseline.json)\njq -jr .content baseline.json > draft.md\n# Edit draft.md without changing the saved original baseline.\ndreamlake notes write \"$NOTE_ID\" --file draft.md --base-revision \"$BASE\" --json\n# ACK is the successful write receipt's revision.\ndreamlake notes read \"$NOTE_ID\" --at \"$ACK\"",
84
- "notes": "# Find a note and read it directly.\ndreamlake notes search \"release plan\"\ndreamlake notes read release-plan\n\n# Preview a unique wording change, apply it, then read back.\ndreamlake notes replace \"Draft checklist\" --text \"Ready for review\" --note release-plan --dry-run\ndreamlake notes replace \"Draft checklist\" --text \"Ready for review\" --note release-plan\ndreamlake notes read release-plan\n\n# Create a private note from a Markdown file.\ndreamlake notes create \"Release plan\" --file release-plan.md",
86
+ "notes": "# Find a note and read it directly.\ndreamlake notes search \"release plan\"\ndreamlake notes read release-plan\n\n# Preview a unique wording change, apply it, then read back.\ndreamlake notes replace \"Draft checklist\" --text \"Ready for review\" --note release-plan --dry-run\ndreamlake notes replace \"Draft checklist\" --text \"Ready for review\" --note release-plan\ndreamlake notes read release-plan\n\n# Create a private note from a Markdown file.\ndreamlake notes create \"Release plan\" --file release-plan.md\n\n# Cross-interface design (unreleased target APIs; verify installed --help):\n# https://docs.dreamlake.ai/notes/api/",
85
87
  "notes list": "dreamlake notes list --limit 10\ndreamlake notes list --shared\ndreamlake notes list --namespace acme",
86
88
  "notes search": "dreamlake notes search \"release plan\"\ndreamlake notes search deploy --namespace acme --json",
87
89
  "notes create": "dreamlake notes create \"Release plan\" --text \"Draft checklist\"\nprintf '# Release plan\\n' | dreamlake notes create \"Release plan\" --file - --json",
88
- "notes read": "dreamlake notes read release-plan\ndreamlake notes read release-plan --since \"10 minutes ago\" --format diff\n# Reuse a stable agent identity for this task.\nexport DREAMLAKE_AGENT_ID=release-reviewer-a\nexport DREAMLAKE_AGENT_NAME=\"Release reviewer A\"\ndreamlake notes read release-plan --linger\n# Ctrl-C stops following.\n\nExample notifications:\n+ @alice joined\n+ Reviewer (agent) joined\n* Reviewer (agent) read the note\n* Reviewer (agent) edited the note\n* @alice selected \"## The center\"\n- @alice left",
90
+ "notes read": "dreamlake notes read release-plan\n# Inspect source with generated address hints; do not write the hints back.\ndreamlake notes read release-plan --view markdown\n# Preserve exact source plus revision/hash for a programmatic edit baseline.\ndreamlake notes read release-plan --json > baseline.json\ndreamlake notes read release-plan --since \"10 minutes ago\" --format diff\n# Detailed read design (unreleased target syntax):\n# https://docs.dreamlake.ai/notes/api/reading/\n# Reuse a stable agent identity for this task.\nexport DREAMLAKE_AGENT_ID=release-reviewer-a\nexport DREAMLAKE_AGENT_NAME=\"Release reviewer A\"\ndreamlake notes read release-plan --linger\n# Ctrl-C stops following.\n\nExample notifications:\n+ @alice joined\n+ Reviewer (agent) joined\n* Reviewer (agent) read the note\n* Reviewer (agent) edited the note\n* @alice selected \"## The center\"\n- @alice left",
89
91
  "notes projects": "dreamlake notes projects 000000000000000000000001 --namespace acme",
90
92
  "notes move": "# Standalone cross-namespace Note transfer is unavailable (exit 3).\ndreamlake notes move NOTE_ID --to-namespace my-org --project shared-research --dry-run\n# Add a project association within the note's CURRENT workspace.\ndreamlake notes move NOTE_ID --to-namespace current-workspace --project research --dry-run\n# Apply only an executable same-workspace preview.\ndreamlake notes move NOTE_ID --to-namespace current-workspace --project research\n# Relocate the note to an existing folder of one project (CLI 0.87.0+).\ndreamlake notes move NOTE_ID --namespace acme --project research --folder reports/2026 --dry-run",
91
93
  "notes diff": "NOTE_ID=release-plan\ndreamlake notes read \"$NOTE_ID\" --json > baseline.json\nHASH=$(jq -er .hash baseline.json)\ndreamlake notes diff \"$NOTE_ID\" --since \"$HASH\" --format diff",
@@ -1 +1 @@
1
- export declare const BOOTSTRAP_PYTHON = "import base64, fcntl, pwd, hashlib, json, os, pathlib, shutil, subprocess, sys, tempfile, re, urllib.request, plistlib\n\ndef run(args, **kwargs):\n return subprocess.run(args, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)\ndef prerequisite_error(code):\n print(json.dumps({'code': code}))\n sys.exit(1)\ndef openssl_binary():\n # Apple's bundled LibreSSL does not reliably support Ed25519 DER keys.\n candidates = ([str(pathlib.Path.home() / '.local/bin/openssl'),\n '/opt/homebrew/opt/openssl@3/bin/openssl',\n '/usr/local/opt/openssl@3/bin/openssl'] if sys.platform == 'darwin' else [])\n candidates.append(shutil.which('openssl'))\n for binary in candidates:\n if not binary or not os.access(binary, os.X_OK):\n continue\n try:\n result = run([binary, 'pkey', '-inform', 'DER', '-pubout', '-outform', 'DER'],\n input=bytes.fromhex('302e020100300506032b657004220420') + bytes(32)).stdout\n if len(result) == 44 and result[:12] == bytes.fromhex('302a300506032b6570032100'):\n return binary\n except Exception:\n pass\n prerequisite_error('openssl_ed25519_required')\n\ndef check_prerequisites():\n openssl = openssl_binary()\n if sys.platform == 'darwin':\n if os.getuid() == 0:\n prerequisite_error('macos_user_required')\n try:\n run(['launchctl', 'print', 'gui/' + str(os.getuid())])\n except Exception:\n prerequisite_error('launchd_gui_unavailable')\n return openssl\n if sys.platform != 'linux':\n prerequisite_error('platform_unsupported')\n try:\n run(['systemctl', '--user', 'show-environment'])\n except Exception:\n prerequisite_error('systemd_user_unavailable')\n try:\n linger = run(['loginctl', 'show-user', pwd.getpwuid(os.getuid()).pw_name, '-p', 'Linger', '--value']).stdout.strip()\n except Exception:\n prerequisite_error('linger_unavailable')\n if linger != b'yes':\n prerequisite_error('linger_required')\n return openssl\ndef write(path, value):\n fd, tmp = tempfile.mkstemp(dir=str(path.parent))\n try:\n os.fchmod(fd, 0o600)\n with os.fdopen(fd, 'w') as f: f.write(value)\n os.replace(tmp, path)\n finally:\n if os.path.exists(tmp): os.unlink(tmp)\ndef nymph_binary(p, home):\n binary = shutil.which('nymph')\n if not binary:\n bindir = home / '.local/bin'\n bindir.mkdir(parents=True, exist_ok=True)\n binary = str(bindir / 'nymph')\n if not pathlib.Path(binary).exists():\n with urllib.request.urlopen('https://dreamlake.ai/dreamlake/nymph/install.sh', timeout=30) as response:\n installer = response.read()\n # Published immutable release directories use v-prefixed tags.\n version = p.get('version', 'latest')\n if re.fullmatch(r'\\d+\\.\\d+\\.\\d+(?:-[A-Za-z0-9.-]+)?', version):\n version = 'v' + version\n run(['bash','-s','--','--dest',str(bindir),'--version',version], input=installer)\n return binary\n\ndef main():\n p = json.load(sys.stdin)\n # Check before identity creation or requesting an enrollment grant.\n openssl = check_prerequisites()\n home = pathlib.Path.home()\n root = home / '.local/state/dreamlake/hosts' / hashlib.sha256(p['name'].encode()).hexdigest()\n root.mkdir(parents=True, exist_ok=True, mode=0o700)\n os.chmod(root, 0o700)\n with open(root / 'lock', 'a') as lock:\n fcntl.flock(lock, fcntl.LOCK_EX)\n if p.get('managedAccess'):\n binary = nymph_binary(p, home)\n try: run([binary, 'access', '--help'])\n except Exception: prerequisite_error('nymph_access_version_required')\n if (root / 'nymph.toml').exists() and not (root / 'access.json').exists():\n prerequisite_error('nymph_access_migration_required')\n key = root / 'identity.key'\n if not key.exists(): write(key, base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))\n os.chmod(key, 0o600)\n raw = base64.urlsafe_b64decode(key.read_text().strip() + '==')\n if len(raw) != 32: raise RuntimeError('identity format')\n public = run([openssl,'pkey','-inform','DER','-pubout','-outform','DER'], input=bytes.fromhex('302e020100300506032b657004220420') + raw).stdout\n if len(public) != 44 or public[:12] != bytes.fromhex('302a300506032b6570032100'): raise RuntimeError('public format')\n public_key = base64.urlsafe_b64encode(public[12:]).decode().rstrip('=')\n if p['action'] == 'probe':\n print(json.dumps({'unixUser':pwd.getpwuid(os.getuid()).pw_name,'publicKey':public_key}))\n return\n if public_key != p['publicKey']: raise RuntimeError('identity changed')\n # Never fall back to a privileged system unit or an unsupervised daemon.\n binary = nymph_binary(p, home)\n web_terminal = p.get('webTerminal', True)\n if not isinstance(web_terminal, bool): raise RuntimeError('invalid web terminal option')\n sshd = '/usr/sbin/sshd'\n if web_terminal:\n if not os.access(sshd, os.X_OK): prerequisite_error('sshd_required')\n try: run([sshd, '-V'])\n except Exception: prerequisite_error('sshd_required')\n version = run([binary, '--version']).stdout.decode('utf8', errors='replace')\n match = re.search(r'\\b(\\d+)\\.(\\d+)\\.(\\d+)\\b', version)\n if not match or tuple(map(int, match.groups())) < (0, 1, 11):\n prerequisite_error('nymph_ssh_version_required')\n if sys.platform == 'linux':\n privilege_dir = pathlib.Path('/run/sshd')\n if not privilege_dir.is_dir() or privilege_dir.stat().st_uid != 0 or privilege_dir.stat().st_mode & 0o022:\n prerequisite_error('sshd_privilege_directory_required')\n (root / 'ssh').mkdir(exist_ok=True, mode=0o700)\n os.chmod(root / 'ssh', 0o700)\n grant = root / 'enroll-token'\n if p.get('token'): write(grant, p['token'])\n q = json.dumps\n config = '\\n'.join([\n '[server]', 'url = ' + q(p['controlPlaneUrl']), 'namespace = ' + q(p['namespace']),\n '[daemon]', 'machine_id = ' + q(p['machineId']), 'label = ' + q(p['name']),\n '[runtime]', 'keep_alive_s = -1', 'workdir = ' + q(str(root / 'work')), 'runners = [\"process\"]', 'default_runner = \"process\"',\n '[identity]', 'enabled = true', 'key_file = ' + q(str(key)), 'enroll_token_file = ' + q(str(grant)),\n ]) + '\\n'\n if p.get('managedAccess'):\n access = root / 'access.json'\n if not access.exists():\n write(access, json.dumps({'version': 1, 'scope': {'server': p['controlPlaneUrl'], 'namespace': p['namespace'], 'machine_id': p['machineId']}, 'permissions': {'upload': False, 'command_execution': False}}))\n config = 'access_file = ' + q(str(access)) + '\\n' + config\n if web_terminal:\n config += '\\n'.join(['[ssh]', 'enabled = true', 'state_dir = ' + q(str(root / 'ssh')),\n 'sshd = ' + q(sshd), 'max_duration_s = 3600']) + '\\n'\n (root / 'work').mkdir(exist_ok=True)\n config_file = root / 'nymph.toml'\n changed = not config_file.exists() or config_file.read_text() != config\n reload_marker = root / 'launchd-reload-required'\n if sys.platform == 'darwin' and changed:\n write(reload_marker, 'pending')\n write(config_file, config)\n service_path = str(home / '.local/bin') + (':/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin' if sys.platform == 'darwin' else ':/usr/local/bin:/usr/bin:/bin')\n if sys.platform == 'darwin':\n label = 'ai.dreamlake.host.' + hashlib.sha256(p['name'].encode()).hexdigest()[:24]\n domain = 'gui/' + str(os.getuid())\n target = domain + '/' + label\n agents = home / 'Library/LaunchAgents'\n agents.mkdir(parents=True, exist_ok=True)\n agent_file = agents / (label + '.plist')\n agent = plistlib.dumps({\n 'Label': label,\n 'ProgramArguments': [binary, '--config', str(config_file)],\n 'EnvironmentVariables': {'PATH': service_path, 'HOME': str(home)},\n 'WorkingDirectory': str(root / 'work'),\n 'RunAtLoad': True,\n 'KeepAlive': True,\n 'ThrottleInterval': 3,\n # Daemon output can contain sensitive workloads: do not persist it.\n 'StandardOutPath': '/dev/null',\n 'StandardErrorPath': '/dev/null',\n }, sort_keys=True).decode('utf8')\n changed = changed or not agent_file.exists() or agent_file.read_text() != agent or reload_marker.exists()\n if changed:\n write(reload_marker, 'pending')\n # Unload before replacing a loaded definition. Never ignore bootout failure.\n loaded = subprocess.run(['launchctl', 'print', target], stdout=subprocess.DEVNULL,\n stderr=subprocess.DEVNULL).returncode == 0\n if loaded and changed:\n run(['launchctl', 'bootout', target])\n loaded = False\n write(agent_file, agent)\n run(['launchctl', 'enable', target])\n if not loaded:\n run(['launchctl', 'bootstrap', domain, str(agent_file)])\n # No -k: replay must not kill a healthy daemon or its active workloads.\n run(['launchctl', 'kickstart', target])\n run(['launchctl', 'print', target])\n if reload_marker.exists():\n reload_marker.unlink()\n else:\n # JSON string escaping covers quoted systemd arguments; percent must be escaped separately.\n unit_quote = lambda s: q(s.replace('%','%%'))\n unit_name = 'dreamlake-host-' + hashlib.sha256(p['name'].encode()).hexdigest()[:24] + '.service'\n unit_dir = home / '.config/systemd/user'\n unit_dir.mkdir(parents=True, exist_ok=True)\n unit = '[Unit]\\nDescription=DreamLake nymph host\\n[Service]\\nEnvironment=' + unit_quote('PATH=' + service_path) + '\\nExecStart=' + unit_quote(binary) + ' --config ' + unit_quote(str(config_file)) + '\\nRestart=on-failure\\nRestartSec=3\\n[Install]\\nWantedBy=default.target\\n'\n unit_file = unit_dir / unit_name\n changed = changed or not unit_file.exists() or unit_file.read_text() != unit\n write(unit_file, unit)\n run(['systemctl','--user','daemon-reload'])\n run(['systemctl','--user','enable',unit_name])\n run(['systemctl','--user','restart' if changed else 'start',unit_name])\n print(json.dumps({'started':True}))\ntry:\n main()\nexcept Exception:\n # Never forward child stdout/stderr or payloads: these can contain grants.\n print(json.dumps({'error':'Remote bootstrap failed. Verify Python 3, OpenSSL, the platform user-service manager, OpenSSL Ed25519 support, and nymph installation access.'}))\n sys.exit(1)\n";
1
+ export declare const BOOTSTRAP_PYTHON = "import base64, fcntl, pwd, hashlib, json, os, pathlib, shutil, stat, subprocess, sys, tempfile, time, re, urllib.request, plistlib\n\ndef run(args, **kwargs):\n return subprocess.run(args, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)\ndef prerequisite_error(code):\n print(json.dumps({'code': code}))\n sys.exit(1)\ndef openssl_binary():\n # Apple's bundled LibreSSL does not reliably support Ed25519 DER keys.\n candidates = ([str(pathlib.Path.home() / '.local/bin/openssl'),\n '/opt/homebrew/opt/openssl@3/bin/openssl',\n '/usr/local/opt/openssl@3/bin/openssl'] if sys.platform == 'darwin' else [])\n candidates.append(shutil.which('openssl'))\n for binary in candidates:\n if not binary or not os.access(binary, os.X_OK):\n continue\n try:\n result = run([binary, 'pkey', '-inform', 'DER', '-pubout', '-outform', 'DER'],\n input=bytes.fromhex('302e020100300506032b657004220420') + bytes(32)).stdout\n if len(result) == 44 and result[:12] == bytes.fromhex('302a300506032b6570032100'):\n return binary\n except Exception:\n pass\n prerequisite_error('openssl_ed25519_required')\n\ndef check_prerequisites():\n openssl = openssl_binary()\n if sys.platform == 'darwin':\n if os.getuid() == 0:\n prerequisite_error('macos_user_required')\n try:\n run(['launchctl', 'print', 'gui/' + str(os.getuid())])\n except Exception:\n prerequisite_error('launchd_gui_unavailable')\n return openssl\n if sys.platform != 'linux':\n prerequisite_error('platform_unsupported')\n try:\n run(['systemctl', '--user', 'show-environment'])\n except Exception:\n prerequisite_error('systemd_user_unavailable')\n try:\n linger = run(['loginctl', 'show-user', pwd.getpwuid(os.getuid()).pw_name, '-p', 'Linger', '--value']).stdout.strip()\n except Exception:\n prerequisite_error('linger_unavailable')\n if linger != b'yes':\n prerequisite_error('linger_required')\n return openssl\ndef write(path, value):\n fd, tmp = tempfile.mkstemp(dir=str(path.parent))\n try:\n os.fchmod(fd, 0o600)\n with os.fdopen(fd, 'w') as f: f.write(value)\n os.replace(tmp, path)\n finally:\n if os.path.exists(tmp): os.unlink(tmp)\ndef nymph_binary(p, home):\n binary = shutil.which('nymph')\n if not binary:\n bindir = home / '.local/bin'\n bindir.mkdir(parents=True, exist_ok=True)\n binary = str(bindir / 'nymph')\n if not pathlib.Path(binary).exists():\n with urllib.request.urlopen('https://dreamlake.ai/dreamlake/nymph/install.sh', timeout=30) as response:\n installer = response.read()\n # Published immutable release directories use v-prefixed tags.\n version = p.get('version', 'latest')\n if re.fullmatch(r'\\d+\\.\\d+\\.\\d+(?:-[A-Za-z0-9.-]+)?', version):\n version = 'v' + version\n run(['bash','-s','--','--dest',str(bindir),'--version',version], input=installer)\n return binary\n\ndef service_names(name):\n digest = hashlib.sha256(name.encode()).hexdigest()[:24]\n return 'ai.dreamlake.host.' + digest, 'dreamlake-host-' + digest + '.service'\n\n# ---- Nymph upgrade, verification and rollback (`dreamlake hosts upgrade`) ----\n# Every action records itself in ~/.local/share/dreamlake/fleet-upgrades/<YYYYMMDD-NNN>/.\n# The restart that activates a new binary runs once, later, outside the session\n# that requested it: `dreamlake exec` sessions are relayed by nymph itself.\nUPGRADE_TOOL = 'dreamlake-hosts-upgrade'\nUPGRADE_ACTIONS = ('upgrade', 'rollback', 'verify', 'inspect')\nRESTART_GRACE = 90\nVERSION = r'\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?'\n\ndef fail(code, **extra):\n extra['code'] = code\n print(json.dumps(extra))\n sys.exit(1)\ndef sha256_file(path):\n digest = hashlib.sha256()\n with open(str(path), 'rb') as f:\n for chunk in iter(lambda: f.read(1 << 20), b''): digest.update(chunk)\n return digest.hexdigest()\ndef binary_version(binary):\n try: out = run([str(binary), '--version']).stdout.decode('utf8', errors='replace')\n except Exception: return None\n match = re.search(r'(?<![0-9.])(' + VERSION + ')', out)\n return match.group(1) if match else None\ndef bounded(value, default, low, high, code):\n value = default if value is None else value\n if not isinstance(value, int) or isinstance(value, bool) or not low <= value <= high: fail(code)\n return value\n\ndef leftover_restart_jobs(home, remove=True):\n \"\"\"Same rule as src/cli/hosts/leftover-jobs.ts (dreamlake-cli#407): only a submitted\n ai.dreamlake.refresh.* job running this user's fleet-upgrades/<id>/restart.py, which\n the 2026-10 fleet upgrade left behind and launchd re-ran forever. Nothing else.\"\"\"\n if sys.platform != 'darwin': return []\n script = re.compile(r'^\\s*' + re.escape(str(home)) + r'/\\.local/share/dreamlake/fleet-upgrades/[A-Za-z0-9._-]+/restart\\.py$', re.M)\n found = []\n try: listing = run(['launchctl', 'list']).stdout.decode('utf8', errors='replace')\n except Exception: return found\n for line in listing.split('\\n'):\n fields = line.split()\n label = fields[2] if len(fields) > 2 else ''\n if not re.fullmatch(r'ai\\.dreamlake\\.refresh\\.[A-Za-z0-9]+', label): continue\n try:\n detail = run(['launchctl', 'print', 'gui/%d/%s' % (os.getuid(), label)]).stdout.decode('utf8', errors='replace')\n if not re.search(r'^\\s*type = Submitted$', detail, re.M) or not script.search(detail): continue\n if remove: run(['launchctl', 'remove', label])\n found.append(label)\n except Exception:\n pass\n return found\n\ndef service_prerequisites():\n if sys.platform == 'darwin':\n if os.getuid() == 0: prerequisite_error('macos_user_required')\n try: run(['launchctl', 'print', 'gui/' + str(os.getuid())])\n except Exception: prerequisite_error('launchd_gui_unavailable')\n elif sys.platform == 'linux':\n try: run(['systemctl', '--user', 'show-environment'])\n except Exception: prerequisite_error('systemd_user_unavailable')\n if not shutil.which('systemd-run'): prerequisite_error('systemd_run_required')\n else:\n prerequisite_error('platform_unsupported')\n\ndef installed_service(name, home):\n \"\"\"The service and binary that enrollment installed; never a guess from PATH.\"\"\"\n label, unit = service_names(name)\n if sys.platform == 'darwin':\n agent = home / 'Library/LaunchAgents' / (label + '.plist')\n if not agent.is_file(): fail('service_not_installed')\n with open(str(agent), 'rb') as f: binary = plistlib.load(f)['ProgramArguments'][0]\n service = {'kind': 'launchd', 'target': 'gui/%d/%s' % (os.getuid(), label)}\n else:\n unit_file = home / '.config/systemd/user' / unit\n if not unit_file.is_file(): fail('service_not_installed')\n lines = [l for l in unit_file.read_text().splitlines() if l.startswith('ExecStart=')]\n if len(lines) != 1: fail('service_not_installed')\n binary = json.JSONDecoder().raw_decode(lines[0][len('ExecStart='):])[0].replace('%%', '%')\n service = {'kind': 'systemd', 'unit': unit}\n service['binary'] = binary\n return service\n\ndef check_binary(binary):\n # Swap only a regular file this user owns in a directory it can write; never a\n # package-managed symlink or a root-owned install that would need sudo.\n try: st = os.lstat(str(binary))\n except OSError: fail('nymph_binary_missing', binary=str(binary))\n if not binary.is_absolute() or not stat.S_ISREG(st.st_mode) or st.st_uid != os.getuid() or not os.access(str(binary.parent), os.W_OK):\n fail('nymph_binary_unmanaged', binary=str(binary))\n\ndef service_state(service):\n if service['kind'] == 'launchd':\n result = subprocess.run(['launchctl', 'print', service['target']], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)\n if result.returncode != 0: return {'loaded': False, 'pid': None, 'runs': None}\n text = result.stdout.decode('utf8', errors='replace')\n pid, runs = re.search(r'^\\tpid = (\\d+)$', text, re.M), re.search(r'^\\truns = (\\d+)$', text, re.M)\n return {'loaded': True, 'pid': int(pid.group(1)) if pid else None, 'runs': int(runs.group(1)) if runs else None}\n result = subprocess.run(['systemctl', '--user', 'show', service['unit'], '-p', 'MainPID', '-p', 'InvocationID', '-p', 'NRestarts', '-p', 'ActiveState'],\n stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)\n props = dict(l.split('=', 1) for l in result.stdout.decode('utf8', errors='replace').splitlines() if '=' in l)\n pid = int(props.get('MainPID') or 0) or None\n return {'loaded': props.get('ActiveState') == 'active', 'pid': pid, 'invocation': props.get('InvocationID') or None,\n 'autoRestarts': int(props.get('NRestarts') or 0)}\n\ndef process_started_at(pid):\n try: out = run(['ps', '-o', 'etime=', '-p', str(pid)]).stdout.decode().strip()\n except Exception: return None\n match = re.fullmatch(r'(?:(\\d+)-)?(?:(\\d+):)?(\\d+):(\\d+)', out)\n if not match: return None\n days, hours, minutes, seconds = (int(x or 0) for x in match.groups())\n return time.time() - (((days * 24 + hours) * 60 + minutes) * 60 + seconds)\n\ndef running_current(state, binary):\n \"\"\"Whether the service process was started from the binary now on disk.\"\"\"\n pid = state.get('pid')\n if not pid: return False\n if sys.platform == 'linux':\n try:\n if os.readlink('/proc/%d/exe' % pid).endswith(' (deleted)'): return False\n except OSError: pass\n started = process_started_at(pid)\n # etime is whole (possibly rounded) seconds: demand a 2 s margin. An ambiguous\n # answer only costs one extra, verified restart.\n return started is not None and started - 2 >= os.stat(str(binary)).st_mtime\ndef verified_current(fleet, service, sha, pid):\n \"\"\"A recorded verification proves this PID came from the restart onto this binary.\"\"\"\n for d, data in reversed(receipts(fleet)):\n if data.get('binary') != service['binary'] or data.get('status') != 'restart_scheduled': continue\n try: result = json.loads((d / 'verification.json').read_text())\n except Exception: return False\n return data.get('sha256') == sha and result.get('status') == 'verified' and bool(pid) and (result.get('pid') or {}).get('after') == pid\n return False\n\ndef fleet_root(home):\n root = home / '.local/share/dreamlake/fleet-upgrades'\n root.mkdir(parents=True, exist_ok=True, mode=0o700)\n return root\ndef receipts(fleet):\n \"\"\"Receipts written by this tool, oldest first. Ad-hoc 2026-10 receipts are ignored.\"\"\"\n found = []\n for d in sorted(fleet.iterdir()):\n if not re.fullmatch(r'\\d{8}-\\d{3}', d.name) or not (d / 'receipt.json').is_file(): continue\n try: data = json.loads((d / 'receipt.json').read_text())\n except Exception: continue\n if isinstance(data, dict) and data.get('tool') == UPGRADE_TOOL: found.append((d, data))\n return found\ndef select_receipt(fleet, service, upgrade_id=None, rollback=False):\n for d, data in reversed(receipts(fleet)):\n if upgrade_id is not None and d.name != upgrade_id: continue\n if data.get('binary') != service['binary'] or data.get('status') != 'restart_scheduled': continue\n if rollback and not (d / 'previous-nymph').is_file(): continue\n return d, data\n fail('receipt_not_found')\ndef pending_restart(fleet):\n now = time.time()\n for d, data in receipts(fleet):\n at = (data.get('restart') or {}).get('at')\n if at and not (d / 'restart.started').exists() and now < at + RESTART_GRACE: return d.name\ndef new_action_dir(fleet):\n day = time.strftime('%Y%m%d')\n taken = [int(d.name[9:]) for d in fleet.iterdir() if re.fullmatch(day + r'-\\d{3}', d.name)]\n for n in range(max(taken + [0]) + 1, 1000):\n d = fleet / ('%s-%03d' % (day, n))\n try:\n d.mkdir(mode=0o700)\n return d\n except FileExistsError:\n continue\n raise RuntimeError('upgrade ids exhausted')\n\ndef swap_binary(source, binary, expected):\n \"\"\"Atomic replace in the binary's own directory; the old path never disappears.\"\"\"\n mode = stat.S_IMODE(os.stat(str(binary)).st_mode) | 0o500\n tmp = binary.parent / ('.nymph-upgrade-' + os.urandom(6).hex())\n try:\n shutil.copyfile(str(source), str(tmp))\n os.chmod(str(tmp), mode)\n with open(str(tmp), 'rb') as f: os.fsync(f.fileno())\n if sha256_file(tmp) != expected: raise RuntimeError('staged binary changed')\n os.replace(str(tmp), str(binary))\n finally:\n if tmp.exists(): tmp.unlink()\n\ndef shell_quote(value):\n return \"'\" + str(value).replace(\"'\", \"'\\\\''\") + \"'\"\ndef schedule_restart(service, d, delay):\n \"\"\"One delayed restart that outlives this session and can run at most once.\n restart.sh creates restart.started with noclobber before restarting; any second\n execution, for any reason, finds the marker and exits without restarting.\"\"\"\n launchctl, systemctl = shutil.which('launchctl'), shutil.which('systemctl')\n if service['kind'] == 'launchd':\n if not launchctl: raise RuntimeError('launchctl missing')\n command = [launchctl, 'kickstart', '-k', service['target']]\n read_pid = \"%s print %s | awk '/^\\\\tpid = / {print $3; exit}'\" % (shell_quote(launchctl), shell_quote(service['target']))\n else:\n if not systemctl: raise RuntimeError('systemctl missing')\n command = [systemctl, '--user', 'restart', service['unit']]\n read_pid = \"%s --user show %s -p MainPID | awk -F= '$1 == \\\"MainPID\\\" {print $2; exit}'\" % (shell_quote(systemctl), shell_quote(service['unit']))\n script = d / 'restart.sh'\n # restart.pid is the service PID right after this restart; verification requires the\n # final PID to equal it, which proves no later restart happened.\n write(script, '\\n'.join([\n '# One-shot nymph restart for %s; written by dreamlake hosts upgrade.' % d.name,\n 'if ! (set -C; : > %s) 2>/dev/null; then exit 0; fi' % shell_quote(d / 'restart.started'),\n 'date +%%s >> %s' % shell_quote(d / 'restart.log'),\n ' '.join(shell_quote(a) for a in command),\n 'status=$?',\n 'for attempt in 1 2 3 4 5 6 7 8 9 10; do pid=$(%s); [ -n \"$pid\" ] && [ \"$pid\" != 0 ] && break; sleep 1; done' % read_pid,\n 'echo \"$pid\" > %s' % shell_quote(d / 'restart.pid'),\n 'echo \"$status\" > %s' % shell_quote(d / 'restart.exit'), '']))\n at = time.time() + delay\n if service['kind'] == 'launchd':\n # A plain process in its own session (setsid): launchd never registers it, so\n # nothing can respawn it (no `launchctl submit`, no KeepAlive), and outside\n # nymph's process group neither the SSH session ending nor nymph's teardown\n # signals it before it runs.\n child = subprocess.Popen(['/bin/sh', '-c', 'sleep %d; exec /bin/sh %s' % (delay, shell_quote(script))],\n stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,\n close_fds=True, start_new_session=True, cwd='/')\n return {'mechanism': 'detached-process', 'pid': child.pid, 'at': at, 'delaySeconds': delay}\n # A transient timer in the user manager, outside nymph's cgroup (a child of nymph\n # would be killed by its own restart). No Restart= and an OnActiveSec timer that\n # unloads after elapsing: systemd starts the service once and then forgets both.\n unit = 'dreamlake-nymph-restart-%s-%s' % (d.name, os.urandom(3).hex())\n run([shutil.which('systemd-run'), '--user', '--quiet', '--collect', '--unit=' + unit, '--on-active=%ds' % delay,\n '--timer-property=AccuracySec=1s', '--timer-property=RemainAfterElapse=no', '/bin/sh', str(script)])\n return {'mechanism': 'systemd-run-timer', 'unit': unit, 'at': at, 'delaySeconds': delay}\n\ndef helper_finished(restart):\n if restart.get('mechanism') == 'detached-process':\n try: os.kill(restart['pid'], 0)\n except ProcessLookupError: return True\n except OSError: return False\n try: command = run(['ps', '-o', 'command=', '-p', str(restart['pid'])]).stdout.decode('utf8', errors='replace')\n except Exception: return True\n return 'restart.sh' not in command\n for suffix in ('.timer', '.service'):\n result = subprocess.run(['systemctl', '--user', 'show', restart['unit'] + suffix, '-p', 'ActiveState'],\n stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)\n if result.stdout.decode().strip() in ('ActiveState=active', 'ActiveState=activating'): return False\n return True\n\ndef apply_binary(fleet, service, binary, source, sha, receipt, delay):\n \"\"\"Keep the previous binary, swap atomically, record, then schedule the one restart.\"\"\"\n d = receipt['dir']\n shutil.copyfile(str(source), str(d / 'nymph'))\n shutil.copyfile(str(binary), str(d / 'previous-nymph'))\n for kept in ('nymph', 'previous-nymph'): os.chmod(str(d / kept), 0o700)\n if sha256_file(d / 'nymph') != sha or sha256_file(d / 'previous-nymph') != receipt['previousSha256']:\n raise RuntimeError('copied binary changed')\n del receipt['dir']\n receipt['status'] = 'swapping'\n write(d / 'receipt.json', json.dumps(receipt, sort_keys=True))\n swap_binary(d / 'nymph', binary, sha)\n try:\n receipt['restart'] = schedule_restart(service, d, delay)\n except Exception:\n swap_binary(d / 'previous-nymph', binary, receipt['previousSha256'])\n receipt['status'] = 'reverted'\n write(d / 'receipt.json', json.dumps(receipt, sort_keys=True))\n fail('restart_schedule_failed', upgradeId=d.name)\n receipt['status'] = 'restart_scheduled'\n write(d / 'receipt.json', json.dumps(receipt, sort_keys=True))\n return d\n\ndef restart_only(fleet, service, binary, receipt, delay):\n d = receipt.pop('dir')\n receipt['status'] = 'restart_scheduled'\n receipt['restart'] = schedule_restart(service, d, delay)\n write(d / 'receipt.json', json.dumps(receipt, sort_keys=True))\n return d\n\ndef scheduled(d, receipt, removed):\n return {'status': 'restart_scheduled', 'action': receipt['action'], 'upgradeId': d.name, 'version': receipt['version'],\n 'previousVersion': receipt.get('previousVersion'), 'sha256': receipt['sha256'], 'previousSha256': receipt.get('previousSha256'),\n 'restart': {k: receipt['restart'][k] for k in ('mechanism', 'at', 'delaySeconds')}, 'before': receipt['before'],\n 'leftoverJobsRemoved': removed}\n\ndef verify(fleet, service, binary, p):\n d, receipt = select_receipt(fleet, service, p.get('upgradeId'))\n stable = bounded(p.get('stableSeconds'), 15, 1, 300, 'invalid_stable_seconds')\n restart, before = receipt.get('restart') or {}, receipt.get('before') or {}\n deadline = (restart.get('at') or 0) + RESTART_GRACE\n while time.time() < deadline and not (d / 'restart.exit').exists(): time.sleep(0.5)\n state = service_state(service)\n while time.time() < deadline and (not state.get('pid') or state.get('pid') == before.get('pid')):\n time.sleep(1)\n state = service_state(service)\n samples, end = [state], time.time() + stable\n while time.time() < end:\n time.sleep(1)\n samples.append(service_state(service))\n after = samples[-1]\n log = d / 'restart.log'\n helper_runs = len(log.read_text().split()) if log.exists() else 0\n exit_status = (d / 'restart.exit').read_text().strip() if (d / 'restart.exit').exists() else None\n restart_pid = (d / 'restart.pid').read_text().strip() if (d / 'restart.pid').exists() else ''\n checks = {\n 'restartRan': (d / 'restart.started').exists(),\n 'restartRuns': helper_runs,\n 'restartExit': int(exit_status) if exit_status and exit_status.isdigit() else None,\n 'pidChanged': bool(after.get('pid')) and after.get('pid') != before.get('pid'),\n 'pidStable': len({s.get('pid') for s in samples}) == 1 and bool(after.get('pid')),\n 'restartPid': int(restart_pid) if restart_pid.isdigit() else None,\n 'helperFinished': helper_finished(restart) if restart else False,\n 'binarySha256': sha256_file(binary) == receipt['sha256'],\n 'version': binary_version(binary),\n # Informational: the PID chain (pidFromRestart) is the proof; ps start times are coarse.\n 'processCurrent': running_current(after, binary),\n 'leftoverJobsRemoved': leftover_restart_jobs(pathlib.Path.home()),\n }\n if service['kind'] == 'launchd' and before.get('runs') is not None and after.get('runs') is not None:\n checks['serviceStarts'] = after['runs'] - before['runs']\n if service['kind'] == 'systemd':\n checks['invocationChanged'] = bool(after.get('invocation')) and after.get('invocation') != before.get('invocation')\n # An explicit systemctl restart resets NRestarts. Only the new\n # activation's count applies; subtracting the previous activation can\n # reject a healthy restart or hide new crashes behind an old count.\n checks['autoRestarts'] = after.get('autoRestarts', 0)\n failures = [k for k, ok in [\n ('restartRan', checks['restartRan']), ('restartRuns', helper_runs == 1), ('restartExit', checks['restartExit'] == 0),\n ('pidChanged', checks['pidChanged']), ('pidStable', checks['pidStable']),\n ('pidFromRestart', checks['restartPid'] is not None and checks['restartPid'] == after.get('pid')),\n ('helperFinished', checks['helperFinished']),\n ('binarySha256', checks['binarySha256']), ('version', checks['version'] == receipt['version']),\n ('serviceStarts', checks.get('serviceStarts', 1) == 1),\n ('invocationChanged', checks.get('invocationChanged', True)), ('autoRestarts', checks.get('autoRestarts', 0) == 0)] if not ok]\n result = {'status': 'failed' if failures else 'verified', 'action': receipt['action'], 'upgradeId': d.name,\n 'version': checks['version'], 'expectedVersion': receipt['version'],\n 'pid': {'before': before.get('pid'), 'after': after.get('pid')}, 'restarts': helper_runs,\n 'stableSeconds': stable, 'checks': checks, 'failures': failures}\n write(d / 'verification.json', json.dumps(result, sort_keys=True))\n print(json.dumps(result))\n if failures: sys.exit(1)\n\ndef inspect(fleet, service, binary, p):\n state = service_state(service)\n version = binary_version(binary)\n wanted = p.get('version')\n sha = sha256_file(binary)\n current = verified_current(fleet, service, sha, state.get('pid')) or running_current(state, binary)\n pending = pending_restart(fleet)\n rollback = next((d.name for d, data in reversed(receipts(fleet)) if data.get('binary') == service['binary']\n and data.get('status') == 'restart_scheduled' and (d / 'previous-nymph').is_file()), None)\n plan = None\n if isinstance(wanted, str):\n wanted = wanted[1:] if wanted.startswith('v') else wanted\n plan = 'blocked:restart_pending' if pending else 'current' if version == wanted and current else 'restart' if version == wanted else 'upgrade'\n print(json.dumps({'status': 'inspected', 'service': {k: v for k, v in service.items() if k != 'binary'}, 'binary': service['binary'],\n 'version': version, 'sha256': sha, 'pid': state.get('pid'), 'processCurrent': current,\n 'pendingRestart': pending, 'rollbackAvailable': rollback, 'plan': plan,\n 'leftoverJobs': leftover_restart_jobs(pathlib.Path.home(), remove=False)}))\n\ndef upgrade_main(p):\n action = p['action']\n if not isinstance(p.get('name'), str) or not p['name']: fail('invalid_request')\n service_prerequisites()\n home = pathlib.Path.home()\n fleet = fleet_root(home)\n service = installed_service(p['name'], home)\n binary = pathlib.Path(service['binary'])\n check_binary(binary)\n if action == 'inspect': return inspect(fleet, service, binary, p)\n with open(str(fleet / '.lock'), 'a') as lock:\n try: fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)\n except OSError: fail('upgrade_in_progress')\n if action == 'verify': return verify(fleet, service, binary, p)\n delay = bounded(p.get('restartDelaySeconds'), 15, 1, 600, 'invalid_restart_delay')\n removed = leftover_restart_jobs(home)\n pending = pending_restart(fleet)\n if pending: fail('restart_pending', upgradeId=pending)\n current_sha, current_version = sha256_file(binary), binary_version(binary)\n state = service_state(service)\n base = {'tool': UPGRADE_TOOL, 'schema': 1, 'name': p['name'], 'binary': service['binary'],\n 'service': {k: v for k, v in service.items() if k != 'binary'}, 'previousVersion': current_version,\n 'previousSha256': current_sha, 'before': state, 'leftoverJobsRemoved': removed, 'at': time.time()}\n if action == 'rollback':\n source_dir, source = select_receipt(fleet, service, p.get('upgradeId'), rollback=True)\n if current_sha != source.get('sha256'): fail('rollback_receipt_mismatch', upgradeId=source_dir.name)\n previous = source_dir / 'previous-nymph'\n if sha256_file(previous) != source.get('previousSha256'): fail('rollback_binary_corrupt', upgradeId=source_dir.name)\n receipt = dict(base, action='rollback', rollbackOf=source_dir.name, version=source.get('previousVersion') or binary_version(previous),\n sha256=source['previousSha256'], dir=new_action_dir(fleet))\n d = apply_binary(fleet, service, binary, previous, receipt['sha256'], receipt, delay)\n print(json.dumps(scheduled(d, receipt, removed)))\n return\n version = p.get('version')\n if not isinstance(version, str) or not re.fullmatch('v?' + VERSION, version): fail('invalid_version')\n version = version[1:] if version.startswith('v') else version\n if current_version == version:\n if verified_current(fleet, service, current_sha, state.get('pid')) or running_current(state, binary):\n print(json.dumps({'status': 'current', 'version': version, 'sha256': current_sha, 'pid': state.get('pid'),\n 'leftoverJobsRemoved': removed}))\n return\n # Already swapped but the service still runs an older process: restart only.\n receipt = dict(base, action='restart', version=version, sha256=current_sha, dir=new_action_dir(fleet))\n d = restart_only(fleet, service, binary, receipt, delay)\n print(json.dumps(scheduled(d, receipt, removed)))\n return\n d = new_action_dir(fleet)\n try:\n stage = d / 'stage'\n stage.mkdir(mode=0o700)\n with urllib.request.urlopen('https://dreamlake.ai/dreamlake/nymph/install.sh', timeout=30) as response:\n installer = response.read()\n # The official installer downloads the archive and verifies its published SHA-256.\n run(['bash', '-s', '--', '--dest', str(stage), '--version', 'v' + version], input=installer)\n staged = stage / 'nymph'\n if not staged.is_file(): fail('installer_failed')\n found = binary_version(staged)\n if found != version: fail('installer_version_mismatch', expected=version, found=found)\n sha = sha256_file(staged)\n receipt = dict(base, action='upgrade', version=version, sha256=sha, dir=d)\n apply_binary(fleet, service, binary, staged, sha, receipt, delay)\n shutil.rmtree(str(stage), ignore_errors=True)\n except BaseException:\n if not (d / 'receipt.json').exists(): shutil.rmtree(str(d), ignore_errors=True)\n raise\n print(json.dumps(scheduled(d, receipt, removed)))\n\ndef main():\n p = json.load(sys.stdin)\n if p.get('action') in UPGRADE_ACTIONS:\n try:\n return upgrade_main(p)\n except SystemExit:\n raise\n except Exception:\n fail('upgrade_failed')\n # Check before identity creation or requesting an enrollment grant.\n openssl = check_prerequisites()\n home = pathlib.Path.home()\n root = home / '.local/state/dreamlake/hosts' / hashlib.sha256(p['name'].encode()).hexdigest()\n root.mkdir(parents=True, exist_ok=True, mode=0o700)\n os.chmod(root, 0o700)\n with open(root / 'lock', 'a') as lock:\n fcntl.flock(lock, fcntl.LOCK_EX)\n if p.get('managedAccess'):\n binary = nymph_binary(p, home)\n try: run([binary, 'access', '--help'])\n except Exception: prerequisite_error('nymph_access_version_required')\n if (root / 'nymph.toml').exists() and not (root / 'access.json').exists():\n prerequisite_error('nymph_access_migration_required')\n key = root / 'identity.key'\n if not key.exists(): write(key, base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))\n os.chmod(key, 0o600)\n raw = base64.urlsafe_b64decode(key.read_text().strip() + '==')\n if len(raw) != 32: raise RuntimeError('identity format')\n public = run([openssl,'pkey','-inform','DER','-pubout','-outform','DER'], input=bytes.fromhex('302e020100300506032b657004220420') + raw).stdout\n if len(public) != 44 or public[:12] != bytes.fromhex('302a300506032b6570032100'): raise RuntimeError('public format')\n public_key = base64.urlsafe_b64encode(public[12:]).decode().rstrip('=')\n if p['action'] == 'probe':\n print(json.dumps({'unixUser':pwd.getpwuid(os.getuid()).pw_name,'publicKey':public_key}))\n return\n if public_key != p['publicKey']: raise RuntimeError('identity changed')\n # Never fall back to a privileged system unit or an unsupervised daemon.\n binary = nymph_binary(p, home)\n web_terminal = p.get('webTerminal', True)\n if not isinstance(web_terminal, bool): raise RuntimeError('invalid web terminal option')\n sshd = '/usr/sbin/sshd'\n if web_terminal:\n if not os.access(sshd, os.X_OK): prerequisite_error('sshd_required')\n try: run([sshd, '-V'])\n except Exception: prerequisite_error('sshd_required')\n version = run([binary, '--version']).stdout.decode('utf8', errors='replace')\n match = re.search(r'\\b(\\d+)\\.(\\d+)\\.(\\d+)\\b', version)\n if not match or tuple(map(int, match.groups())) < (0, 1, 11):\n prerequisite_error('nymph_ssh_version_required')\n if sys.platform == 'linux':\n privilege_dir = pathlib.Path('/run/sshd')\n if not privilege_dir.is_dir() or privilege_dir.stat().st_uid != 0 or privilege_dir.stat().st_mode & 0o022:\n prerequisite_error('sshd_privilege_directory_required')\n (root / 'ssh').mkdir(exist_ok=True, mode=0o700)\n os.chmod(root / 'ssh', 0o700)\n grant = root / 'enroll-token'\n if p.get('token'): write(grant, p['token'])\n q = json.dumps\n config = '\\n'.join([\n '[server]', 'url = ' + q(p['controlPlaneUrl']), 'namespace = ' + q(p['namespace']),\n '[daemon]', 'machine_id = ' + q(p['machineId']), 'label = ' + q(p['name']),\n '[runtime]', 'keep_alive_s = -1', 'workdir = ' + q(str(root / 'work')), 'runners = [\"process\"]', 'default_runner = \"process\"',\n '[identity]', 'enabled = true', 'key_file = ' + q(str(key)), 'enroll_token_file = ' + q(str(grant)),\n ]) + '\\n'\n if p.get('managedAccess'):\n access = root / 'access.json'\n if not access.exists():\n write(access, json.dumps({'version': 1, 'scope': {'server': p['controlPlaneUrl'], 'namespace': p['namespace'], 'machine_id': p['machineId']}, 'permissions': {'upload': False, 'command_execution': False}}))\n config = 'access_file = ' + q(str(access)) + '\\n' + config\n if web_terminal:\n config += '\\n'.join(['[ssh]', 'enabled = true', 'state_dir = ' + q(str(root / 'ssh')),\n 'sshd = ' + q(sshd), 'max_duration_s = 3600']) + '\\n'\n (root / 'work').mkdir(exist_ok=True)\n config_file = root / 'nymph.toml'\n changed = not config_file.exists() or config_file.read_text() != config\n reload_marker = root / 'launchd-reload-required'\n if sys.platform == 'darwin' and changed:\n write(reload_marker, 'pending')\n write(config_file, config)\n service_path = str(home / '.local/bin') + (':/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin' if sys.platform == 'darwin' else ':/usr/local/bin:/usr/bin:/bin')\n if sys.platform == 'darwin':\n label = service_names(p['name'])[0]\n domain = 'gui/' + str(os.getuid())\n target = domain + '/' + label\n agents = home / 'Library/LaunchAgents'\n agents.mkdir(parents=True, exist_ok=True)\n agent_file = agents / (label + '.plist')\n agent = plistlib.dumps({\n 'Label': label,\n 'ProgramArguments': [binary, '--config', str(config_file)],\n 'EnvironmentVariables': {'PATH': service_path, 'HOME': str(home)},\n 'WorkingDirectory': str(root / 'work'),\n 'RunAtLoad': True,\n 'KeepAlive': True,\n 'ThrottleInterval': 3,\n # Daemon output can contain sensitive workloads: do not persist it.\n 'StandardOutPath': '/dev/null',\n 'StandardErrorPath': '/dev/null',\n }, sort_keys=True).decode('utf8')\n changed = changed or not agent_file.exists() or agent_file.read_text() != agent or reload_marker.exists()\n if changed:\n write(reload_marker, 'pending')\n # Unload before replacing a loaded definition. Never ignore bootout failure.\n loaded = subprocess.run(['launchctl', 'print', target], stdout=subprocess.DEVNULL,\n stderr=subprocess.DEVNULL).returncode == 0\n if loaded and changed:\n run(['launchctl', 'bootout', target])\n loaded = False\n write(agent_file, agent)\n run(['launchctl', 'enable', target])\n if not loaded:\n run(['launchctl', 'bootstrap', domain, str(agent_file)])\n # No -k: replay must not kill a healthy daemon or its active workloads.\n run(['launchctl', 'kickstart', target])\n run(['launchctl', 'print', target])\n if reload_marker.exists():\n reload_marker.unlink()\n else:\n # JSON string escaping covers quoted systemd arguments; percent must be escaped separately.\n unit_quote = lambda s: q(s.replace('%','%%'))\n unit_name = service_names(p['name'])[1]\n unit_dir = home / '.config/systemd/user'\n unit_dir.mkdir(parents=True, exist_ok=True)\n unit = '[Unit]\\nDescription=DreamLake nymph host\\n[Service]\\nEnvironment=' + unit_quote('PATH=' + service_path) + '\\nExecStart=' + unit_quote(binary) + ' --config ' + unit_quote(str(config_file)) + '\\nRestart=on-failure\\nRestartSec=3\\n[Install]\\nWantedBy=default.target\\n'\n unit_file = unit_dir / unit_name\n changed = changed or not unit_file.exists() or unit_file.read_text() != unit\n write(unit_file, unit)\n run(['systemctl','--user','daemon-reload'])\n run(['systemctl','--user','enable',unit_name])\n run(['systemctl','--user','restart' if changed else 'start',unit_name])\n print(json.dumps({'started':True}))\ntry:\n main()\nexcept Exception:\n # Never forward child stdout/stderr or payloads: these can contain grants.\n print(json.dumps({'error':'Remote bootstrap failed. Verify Python 3, OpenSSL, the platform user-service manager, OpenSSL Ed25519 support, and nymph installation access.'}))\n sys.exit(1)\n";
@@ -1,2 +1,2 @@
1
1
  // Generated by scripts/gen-host-bootstrap.mjs from bootstrap.py.
2
- export const BOOTSTRAP_PYTHON = "import base64, fcntl, pwd, hashlib, json, os, pathlib, shutil, subprocess, sys, tempfile, re, urllib.request, plistlib\n\ndef run(args, **kwargs):\n return subprocess.run(args, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)\ndef prerequisite_error(code):\n print(json.dumps({'code': code}))\n sys.exit(1)\ndef openssl_binary():\n # Apple's bundled LibreSSL does not reliably support Ed25519 DER keys.\n candidates = ([str(pathlib.Path.home() / '.local/bin/openssl'),\n '/opt/homebrew/opt/openssl@3/bin/openssl',\n '/usr/local/opt/openssl@3/bin/openssl'] if sys.platform == 'darwin' else [])\n candidates.append(shutil.which('openssl'))\n for binary in candidates:\n if not binary or not os.access(binary, os.X_OK):\n continue\n try:\n result = run([binary, 'pkey', '-inform', 'DER', '-pubout', '-outform', 'DER'],\n input=bytes.fromhex('302e020100300506032b657004220420') + bytes(32)).stdout\n if len(result) == 44 and result[:12] == bytes.fromhex('302a300506032b6570032100'):\n return binary\n except Exception:\n pass\n prerequisite_error('openssl_ed25519_required')\n\ndef check_prerequisites():\n openssl = openssl_binary()\n if sys.platform == 'darwin':\n if os.getuid() == 0:\n prerequisite_error('macos_user_required')\n try:\n run(['launchctl', 'print', 'gui/' + str(os.getuid())])\n except Exception:\n prerequisite_error('launchd_gui_unavailable')\n return openssl\n if sys.platform != 'linux':\n prerequisite_error('platform_unsupported')\n try:\n run(['systemctl', '--user', 'show-environment'])\n except Exception:\n prerequisite_error('systemd_user_unavailable')\n try:\n linger = run(['loginctl', 'show-user', pwd.getpwuid(os.getuid()).pw_name, '-p', 'Linger', '--value']).stdout.strip()\n except Exception:\n prerequisite_error('linger_unavailable')\n if linger != b'yes':\n prerequisite_error('linger_required')\n return openssl\ndef write(path, value):\n fd, tmp = tempfile.mkstemp(dir=str(path.parent))\n try:\n os.fchmod(fd, 0o600)\n with os.fdopen(fd, 'w') as f: f.write(value)\n os.replace(tmp, path)\n finally:\n if os.path.exists(tmp): os.unlink(tmp)\ndef nymph_binary(p, home):\n binary = shutil.which('nymph')\n if not binary:\n bindir = home / '.local/bin'\n bindir.mkdir(parents=True, exist_ok=True)\n binary = str(bindir / 'nymph')\n if not pathlib.Path(binary).exists():\n with urllib.request.urlopen('https://dreamlake.ai/dreamlake/nymph/install.sh', timeout=30) as response:\n installer = response.read()\n # Published immutable release directories use v-prefixed tags.\n version = p.get('version', 'latest')\n if re.fullmatch(r'\\d+\\.\\d+\\.\\d+(?:-[A-Za-z0-9.-]+)?', version):\n version = 'v' + version\n run(['bash','-s','--','--dest',str(bindir),'--version',version], input=installer)\n return binary\n\ndef main():\n p = json.load(sys.stdin)\n # Check before identity creation or requesting an enrollment grant.\n openssl = check_prerequisites()\n home = pathlib.Path.home()\n root = home / '.local/state/dreamlake/hosts' / hashlib.sha256(p['name'].encode()).hexdigest()\n root.mkdir(parents=True, exist_ok=True, mode=0o700)\n os.chmod(root, 0o700)\n with open(root / 'lock', 'a') as lock:\n fcntl.flock(lock, fcntl.LOCK_EX)\n if p.get('managedAccess'):\n binary = nymph_binary(p, home)\n try: run([binary, 'access', '--help'])\n except Exception: prerequisite_error('nymph_access_version_required')\n if (root / 'nymph.toml').exists() and not (root / 'access.json').exists():\n prerequisite_error('nymph_access_migration_required')\n key = root / 'identity.key'\n if not key.exists(): write(key, base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))\n os.chmod(key, 0o600)\n raw = base64.urlsafe_b64decode(key.read_text().strip() + '==')\n if len(raw) != 32: raise RuntimeError('identity format')\n public = run([openssl,'pkey','-inform','DER','-pubout','-outform','DER'], input=bytes.fromhex('302e020100300506032b657004220420') + raw).stdout\n if len(public) != 44 or public[:12] != bytes.fromhex('302a300506032b6570032100'): raise RuntimeError('public format')\n public_key = base64.urlsafe_b64encode(public[12:]).decode().rstrip('=')\n if p['action'] == 'probe':\n print(json.dumps({'unixUser':pwd.getpwuid(os.getuid()).pw_name,'publicKey':public_key}))\n return\n if public_key != p['publicKey']: raise RuntimeError('identity changed')\n # Never fall back to a privileged system unit or an unsupervised daemon.\n binary = nymph_binary(p, home)\n web_terminal = p.get('webTerminal', True)\n if not isinstance(web_terminal, bool): raise RuntimeError('invalid web terminal option')\n sshd = '/usr/sbin/sshd'\n if web_terminal:\n if not os.access(sshd, os.X_OK): prerequisite_error('sshd_required')\n try: run([sshd, '-V'])\n except Exception: prerequisite_error('sshd_required')\n version = run([binary, '--version']).stdout.decode('utf8', errors='replace')\n match = re.search(r'\\b(\\d+)\\.(\\d+)\\.(\\d+)\\b', version)\n if not match or tuple(map(int, match.groups())) < (0, 1, 11):\n prerequisite_error('nymph_ssh_version_required')\n if sys.platform == 'linux':\n privilege_dir = pathlib.Path('/run/sshd')\n if not privilege_dir.is_dir() or privilege_dir.stat().st_uid != 0 or privilege_dir.stat().st_mode & 0o022:\n prerequisite_error('sshd_privilege_directory_required')\n (root / 'ssh').mkdir(exist_ok=True, mode=0o700)\n os.chmod(root / 'ssh', 0o700)\n grant = root / 'enroll-token'\n if p.get('token'): write(grant, p['token'])\n q = json.dumps\n config = '\\n'.join([\n '[server]', 'url = ' + q(p['controlPlaneUrl']), 'namespace = ' + q(p['namespace']),\n '[daemon]', 'machine_id = ' + q(p['machineId']), 'label = ' + q(p['name']),\n '[runtime]', 'keep_alive_s = -1', 'workdir = ' + q(str(root / 'work')), 'runners = [\"process\"]', 'default_runner = \"process\"',\n '[identity]', 'enabled = true', 'key_file = ' + q(str(key)), 'enroll_token_file = ' + q(str(grant)),\n ]) + '\\n'\n if p.get('managedAccess'):\n access = root / 'access.json'\n if not access.exists():\n write(access, json.dumps({'version': 1, 'scope': {'server': p['controlPlaneUrl'], 'namespace': p['namespace'], 'machine_id': p['machineId']}, 'permissions': {'upload': False, 'command_execution': False}}))\n config = 'access_file = ' + q(str(access)) + '\\n' + config\n if web_terminal:\n config += '\\n'.join(['[ssh]', 'enabled = true', 'state_dir = ' + q(str(root / 'ssh')),\n 'sshd = ' + q(sshd), 'max_duration_s = 3600']) + '\\n'\n (root / 'work').mkdir(exist_ok=True)\n config_file = root / 'nymph.toml'\n changed = not config_file.exists() or config_file.read_text() != config\n reload_marker = root / 'launchd-reload-required'\n if sys.platform == 'darwin' and changed:\n write(reload_marker, 'pending')\n write(config_file, config)\n service_path = str(home / '.local/bin') + (':/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin' if sys.platform == 'darwin' else ':/usr/local/bin:/usr/bin:/bin')\n if sys.platform == 'darwin':\n label = 'ai.dreamlake.host.' + hashlib.sha256(p['name'].encode()).hexdigest()[:24]\n domain = 'gui/' + str(os.getuid())\n target = domain + '/' + label\n agents = home / 'Library/LaunchAgents'\n agents.mkdir(parents=True, exist_ok=True)\n agent_file = agents / (label + '.plist')\n agent = plistlib.dumps({\n 'Label': label,\n 'ProgramArguments': [binary, '--config', str(config_file)],\n 'EnvironmentVariables': {'PATH': service_path, 'HOME': str(home)},\n 'WorkingDirectory': str(root / 'work'),\n 'RunAtLoad': True,\n 'KeepAlive': True,\n 'ThrottleInterval': 3,\n # Daemon output can contain sensitive workloads: do not persist it.\n 'StandardOutPath': '/dev/null',\n 'StandardErrorPath': '/dev/null',\n }, sort_keys=True).decode('utf8')\n changed = changed or not agent_file.exists() or agent_file.read_text() != agent or reload_marker.exists()\n if changed:\n write(reload_marker, 'pending')\n # Unload before replacing a loaded definition. Never ignore bootout failure.\n loaded = subprocess.run(['launchctl', 'print', target], stdout=subprocess.DEVNULL,\n stderr=subprocess.DEVNULL).returncode == 0\n if loaded and changed:\n run(['launchctl', 'bootout', target])\n loaded = False\n write(agent_file, agent)\n run(['launchctl', 'enable', target])\n if not loaded:\n run(['launchctl', 'bootstrap', domain, str(agent_file)])\n # No -k: replay must not kill a healthy daemon or its active workloads.\n run(['launchctl', 'kickstart', target])\n run(['launchctl', 'print', target])\n if reload_marker.exists():\n reload_marker.unlink()\n else:\n # JSON string escaping covers quoted systemd arguments; percent must be escaped separately.\n unit_quote = lambda s: q(s.replace('%','%%'))\n unit_name = 'dreamlake-host-' + hashlib.sha256(p['name'].encode()).hexdigest()[:24] + '.service'\n unit_dir = home / '.config/systemd/user'\n unit_dir.mkdir(parents=True, exist_ok=True)\n unit = '[Unit]\\nDescription=DreamLake nymph host\\n[Service]\\nEnvironment=' + unit_quote('PATH=' + service_path) + '\\nExecStart=' + unit_quote(binary) + ' --config ' + unit_quote(str(config_file)) + '\\nRestart=on-failure\\nRestartSec=3\\n[Install]\\nWantedBy=default.target\\n'\n unit_file = unit_dir / unit_name\n changed = changed or not unit_file.exists() or unit_file.read_text() != unit\n write(unit_file, unit)\n run(['systemctl','--user','daemon-reload'])\n run(['systemctl','--user','enable',unit_name])\n run(['systemctl','--user','restart' if changed else 'start',unit_name])\n print(json.dumps({'started':True}))\ntry:\n main()\nexcept Exception:\n # Never forward child stdout/stderr or payloads: these can contain grants.\n print(json.dumps({'error':'Remote bootstrap failed. Verify Python 3, OpenSSL, the platform user-service manager, OpenSSL Ed25519 support, and nymph installation access.'}))\n sys.exit(1)\n";
2
+ export const BOOTSTRAP_PYTHON = "import base64, fcntl, pwd, hashlib, json, os, pathlib, shutil, stat, subprocess, sys, tempfile, time, re, urllib.request, plistlib\n\ndef run(args, **kwargs):\n return subprocess.run(args, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)\ndef prerequisite_error(code):\n print(json.dumps({'code': code}))\n sys.exit(1)\ndef openssl_binary():\n # Apple's bundled LibreSSL does not reliably support Ed25519 DER keys.\n candidates = ([str(pathlib.Path.home() / '.local/bin/openssl'),\n '/opt/homebrew/opt/openssl@3/bin/openssl',\n '/usr/local/opt/openssl@3/bin/openssl'] if sys.platform == 'darwin' else [])\n candidates.append(shutil.which('openssl'))\n for binary in candidates:\n if not binary or not os.access(binary, os.X_OK):\n continue\n try:\n result = run([binary, 'pkey', '-inform', 'DER', '-pubout', '-outform', 'DER'],\n input=bytes.fromhex('302e020100300506032b657004220420') + bytes(32)).stdout\n if len(result) == 44 and result[:12] == bytes.fromhex('302a300506032b6570032100'):\n return binary\n except Exception:\n pass\n prerequisite_error('openssl_ed25519_required')\n\ndef check_prerequisites():\n openssl = openssl_binary()\n if sys.platform == 'darwin':\n if os.getuid() == 0:\n prerequisite_error('macos_user_required')\n try:\n run(['launchctl', 'print', 'gui/' + str(os.getuid())])\n except Exception:\n prerequisite_error('launchd_gui_unavailable')\n return openssl\n if sys.platform != 'linux':\n prerequisite_error('platform_unsupported')\n try:\n run(['systemctl', '--user', 'show-environment'])\n except Exception:\n prerequisite_error('systemd_user_unavailable')\n try:\n linger = run(['loginctl', 'show-user', pwd.getpwuid(os.getuid()).pw_name, '-p', 'Linger', '--value']).stdout.strip()\n except Exception:\n prerequisite_error('linger_unavailable')\n if linger != b'yes':\n prerequisite_error('linger_required')\n return openssl\ndef write(path, value):\n fd, tmp = tempfile.mkstemp(dir=str(path.parent))\n try:\n os.fchmod(fd, 0o600)\n with os.fdopen(fd, 'w') as f: f.write(value)\n os.replace(tmp, path)\n finally:\n if os.path.exists(tmp): os.unlink(tmp)\ndef nymph_binary(p, home):\n binary = shutil.which('nymph')\n if not binary:\n bindir = home / '.local/bin'\n bindir.mkdir(parents=True, exist_ok=True)\n binary = str(bindir / 'nymph')\n if not pathlib.Path(binary).exists():\n with urllib.request.urlopen('https://dreamlake.ai/dreamlake/nymph/install.sh', timeout=30) as response:\n installer = response.read()\n # Published immutable release directories use v-prefixed tags.\n version = p.get('version', 'latest')\n if re.fullmatch(r'\\d+\\.\\d+\\.\\d+(?:-[A-Za-z0-9.-]+)?', version):\n version = 'v' + version\n run(['bash','-s','--','--dest',str(bindir),'--version',version], input=installer)\n return binary\n\ndef service_names(name):\n digest = hashlib.sha256(name.encode()).hexdigest()[:24]\n return 'ai.dreamlake.host.' + digest, 'dreamlake-host-' + digest + '.service'\n\n# ---- Nymph upgrade, verification and rollback (`dreamlake hosts upgrade`) ----\n# Every action records itself in ~/.local/share/dreamlake/fleet-upgrades/<YYYYMMDD-NNN>/.\n# The restart that activates a new binary runs once, later, outside the session\n# that requested it: `dreamlake exec` sessions are relayed by nymph itself.\nUPGRADE_TOOL = 'dreamlake-hosts-upgrade'\nUPGRADE_ACTIONS = ('upgrade', 'rollback', 'verify', 'inspect')\nRESTART_GRACE = 90\nVERSION = r'\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?'\n\ndef fail(code, **extra):\n extra['code'] = code\n print(json.dumps(extra))\n sys.exit(1)\ndef sha256_file(path):\n digest = hashlib.sha256()\n with open(str(path), 'rb') as f:\n for chunk in iter(lambda: f.read(1 << 20), b''): digest.update(chunk)\n return digest.hexdigest()\ndef binary_version(binary):\n try: out = run([str(binary), '--version']).stdout.decode('utf8', errors='replace')\n except Exception: return None\n match = re.search(r'(?<![0-9.])(' + VERSION + ')', out)\n return match.group(1) if match else None\ndef bounded(value, default, low, high, code):\n value = default if value is None else value\n if not isinstance(value, int) or isinstance(value, bool) or not low <= value <= high: fail(code)\n return value\n\ndef leftover_restart_jobs(home, remove=True):\n \"\"\"Same rule as src/cli/hosts/leftover-jobs.ts (dreamlake-cli#407): only a submitted\n ai.dreamlake.refresh.* job running this user's fleet-upgrades/<id>/restart.py, which\n the 2026-10 fleet upgrade left behind and launchd re-ran forever. Nothing else.\"\"\"\n if sys.platform != 'darwin': return []\n script = re.compile(r'^\\s*' + re.escape(str(home)) + r'/\\.local/share/dreamlake/fleet-upgrades/[A-Za-z0-9._-]+/restart\\.py$', re.M)\n found = []\n try: listing = run(['launchctl', 'list']).stdout.decode('utf8', errors='replace')\n except Exception: return found\n for line in listing.split('\\n'):\n fields = line.split()\n label = fields[2] if len(fields) > 2 else ''\n if not re.fullmatch(r'ai\\.dreamlake\\.refresh\\.[A-Za-z0-9]+', label): continue\n try:\n detail = run(['launchctl', 'print', 'gui/%d/%s' % (os.getuid(), label)]).stdout.decode('utf8', errors='replace')\n if not re.search(r'^\\s*type = Submitted$', detail, re.M) or not script.search(detail): continue\n if remove: run(['launchctl', 'remove', label])\n found.append(label)\n except Exception:\n pass\n return found\n\ndef service_prerequisites():\n if sys.platform == 'darwin':\n if os.getuid() == 0: prerequisite_error('macos_user_required')\n try: run(['launchctl', 'print', 'gui/' + str(os.getuid())])\n except Exception: prerequisite_error('launchd_gui_unavailable')\n elif sys.platform == 'linux':\n try: run(['systemctl', '--user', 'show-environment'])\n except Exception: prerequisite_error('systemd_user_unavailable')\n if not shutil.which('systemd-run'): prerequisite_error('systemd_run_required')\n else:\n prerequisite_error('platform_unsupported')\n\ndef installed_service(name, home):\n \"\"\"The service and binary that enrollment installed; never a guess from PATH.\"\"\"\n label, unit = service_names(name)\n if sys.platform == 'darwin':\n agent = home / 'Library/LaunchAgents' / (label + '.plist')\n if not agent.is_file(): fail('service_not_installed')\n with open(str(agent), 'rb') as f: binary = plistlib.load(f)['ProgramArguments'][0]\n service = {'kind': 'launchd', 'target': 'gui/%d/%s' % (os.getuid(), label)}\n else:\n unit_file = home / '.config/systemd/user' / unit\n if not unit_file.is_file(): fail('service_not_installed')\n lines = [l for l in unit_file.read_text().splitlines() if l.startswith('ExecStart=')]\n if len(lines) != 1: fail('service_not_installed')\n binary = json.JSONDecoder().raw_decode(lines[0][len('ExecStart='):])[0].replace('%%', '%')\n service = {'kind': 'systemd', 'unit': unit}\n service['binary'] = binary\n return service\n\ndef check_binary(binary):\n # Swap only a regular file this user owns in a directory it can write; never a\n # package-managed symlink or a root-owned install that would need sudo.\n try: st = os.lstat(str(binary))\n except OSError: fail('nymph_binary_missing', binary=str(binary))\n if not binary.is_absolute() or not stat.S_ISREG(st.st_mode) or st.st_uid != os.getuid() or not os.access(str(binary.parent), os.W_OK):\n fail('nymph_binary_unmanaged', binary=str(binary))\n\ndef service_state(service):\n if service['kind'] == 'launchd':\n result = subprocess.run(['launchctl', 'print', service['target']], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)\n if result.returncode != 0: return {'loaded': False, 'pid': None, 'runs': None}\n text = result.stdout.decode('utf8', errors='replace')\n pid, runs = re.search(r'^\\tpid = (\\d+)$', text, re.M), re.search(r'^\\truns = (\\d+)$', text, re.M)\n return {'loaded': True, 'pid': int(pid.group(1)) if pid else None, 'runs': int(runs.group(1)) if runs else None}\n result = subprocess.run(['systemctl', '--user', 'show', service['unit'], '-p', 'MainPID', '-p', 'InvocationID', '-p', 'NRestarts', '-p', 'ActiveState'],\n stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)\n props = dict(l.split('=', 1) for l in result.stdout.decode('utf8', errors='replace').splitlines() if '=' in l)\n pid = int(props.get('MainPID') or 0) or None\n return {'loaded': props.get('ActiveState') == 'active', 'pid': pid, 'invocation': props.get('InvocationID') or None,\n 'autoRestarts': int(props.get('NRestarts') or 0)}\n\ndef process_started_at(pid):\n try: out = run(['ps', '-o', 'etime=', '-p', str(pid)]).stdout.decode().strip()\n except Exception: return None\n match = re.fullmatch(r'(?:(\\d+)-)?(?:(\\d+):)?(\\d+):(\\d+)', out)\n if not match: return None\n days, hours, minutes, seconds = (int(x or 0) for x in match.groups())\n return time.time() - (((days * 24 + hours) * 60 + minutes) * 60 + seconds)\n\ndef running_current(state, binary):\n \"\"\"Whether the service process was started from the binary now on disk.\"\"\"\n pid = state.get('pid')\n if not pid: return False\n if sys.platform == 'linux':\n try:\n if os.readlink('/proc/%d/exe' % pid).endswith(' (deleted)'): return False\n except OSError: pass\n started = process_started_at(pid)\n # etime is whole (possibly rounded) seconds: demand a 2 s margin. An ambiguous\n # answer only costs one extra, verified restart.\n return started is not None and started - 2 >= os.stat(str(binary)).st_mtime\ndef verified_current(fleet, service, sha, pid):\n \"\"\"A recorded verification proves this PID came from the restart onto this binary.\"\"\"\n for d, data in reversed(receipts(fleet)):\n if data.get('binary') != service['binary'] or data.get('status') != 'restart_scheduled': continue\n try: result = json.loads((d / 'verification.json').read_text())\n except Exception: return False\n return data.get('sha256') == sha and result.get('status') == 'verified' and bool(pid) and (result.get('pid') or {}).get('after') == pid\n return False\n\ndef fleet_root(home):\n root = home / '.local/share/dreamlake/fleet-upgrades'\n root.mkdir(parents=True, exist_ok=True, mode=0o700)\n return root\ndef receipts(fleet):\n \"\"\"Receipts written by this tool, oldest first. Ad-hoc 2026-10 receipts are ignored.\"\"\"\n found = []\n for d in sorted(fleet.iterdir()):\n if not re.fullmatch(r'\\d{8}-\\d{3}', d.name) or not (d / 'receipt.json').is_file(): continue\n try: data = json.loads((d / 'receipt.json').read_text())\n except Exception: continue\n if isinstance(data, dict) and data.get('tool') == UPGRADE_TOOL: found.append((d, data))\n return found\ndef select_receipt(fleet, service, upgrade_id=None, rollback=False):\n for d, data in reversed(receipts(fleet)):\n if upgrade_id is not None and d.name != upgrade_id: continue\n if data.get('binary') != service['binary'] or data.get('status') != 'restart_scheduled': continue\n if rollback and not (d / 'previous-nymph').is_file(): continue\n return d, data\n fail('receipt_not_found')\ndef pending_restart(fleet):\n now = time.time()\n for d, data in receipts(fleet):\n at = (data.get('restart') or {}).get('at')\n if at and not (d / 'restart.started').exists() and now < at + RESTART_GRACE: return d.name\ndef new_action_dir(fleet):\n day = time.strftime('%Y%m%d')\n taken = [int(d.name[9:]) for d in fleet.iterdir() if re.fullmatch(day + r'-\\d{3}', d.name)]\n for n in range(max(taken + [0]) + 1, 1000):\n d = fleet / ('%s-%03d' % (day, n))\n try:\n d.mkdir(mode=0o700)\n return d\n except FileExistsError:\n continue\n raise RuntimeError('upgrade ids exhausted')\n\ndef swap_binary(source, binary, expected):\n \"\"\"Atomic replace in the binary's own directory; the old path never disappears.\"\"\"\n mode = stat.S_IMODE(os.stat(str(binary)).st_mode) | 0o500\n tmp = binary.parent / ('.nymph-upgrade-' + os.urandom(6).hex())\n try:\n shutil.copyfile(str(source), str(tmp))\n os.chmod(str(tmp), mode)\n with open(str(tmp), 'rb') as f: os.fsync(f.fileno())\n if sha256_file(tmp) != expected: raise RuntimeError('staged binary changed')\n os.replace(str(tmp), str(binary))\n finally:\n if tmp.exists(): tmp.unlink()\n\ndef shell_quote(value):\n return \"'\" + str(value).replace(\"'\", \"'\\\\''\") + \"'\"\ndef schedule_restart(service, d, delay):\n \"\"\"One delayed restart that outlives this session and can run at most once.\n restart.sh creates restart.started with noclobber before restarting; any second\n execution, for any reason, finds the marker and exits without restarting.\"\"\"\n launchctl, systemctl = shutil.which('launchctl'), shutil.which('systemctl')\n if service['kind'] == 'launchd':\n if not launchctl: raise RuntimeError('launchctl missing')\n command = [launchctl, 'kickstart', '-k', service['target']]\n read_pid = \"%s print %s | awk '/^\\\\tpid = / {print $3; exit}'\" % (shell_quote(launchctl), shell_quote(service['target']))\n else:\n if not systemctl: raise RuntimeError('systemctl missing')\n command = [systemctl, '--user', 'restart', service['unit']]\n read_pid = \"%s --user show %s -p MainPID | awk -F= '$1 == \\\"MainPID\\\" {print $2; exit}'\" % (shell_quote(systemctl), shell_quote(service['unit']))\n script = d / 'restart.sh'\n # restart.pid is the service PID right after this restart; verification requires the\n # final PID to equal it, which proves no later restart happened.\n write(script, '\\n'.join([\n '# One-shot nymph restart for %s; written by dreamlake hosts upgrade.' % d.name,\n 'if ! (set -C; : > %s) 2>/dev/null; then exit 0; fi' % shell_quote(d / 'restart.started'),\n 'date +%%s >> %s' % shell_quote(d / 'restart.log'),\n ' '.join(shell_quote(a) for a in command),\n 'status=$?',\n 'for attempt in 1 2 3 4 5 6 7 8 9 10; do pid=$(%s); [ -n \"$pid\" ] && [ \"$pid\" != 0 ] && break; sleep 1; done' % read_pid,\n 'echo \"$pid\" > %s' % shell_quote(d / 'restart.pid'),\n 'echo \"$status\" > %s' % shell_quote(d / 'restart.exit'), '']))\n at = time.time() + delay\n if service['kind'] == 'launchd':\n # A plain process in its own session (setsid): launchd never registers it, so\n # nothing can respawn it (no `launchctl submit`, no KeepAlive), and outside\n # nymph's process group neither the SSH session ending nor nymph's teardown\n # signals it before it runs.\n child = subprocess.Popen(['/bin/sh', '-c', 'sleep %d; exec /bin/sh %s' % (delay, shell_quote(script))],\n stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,\n close_fds=True, start_new_session=True, cwd='/')\n return {'mechanism': 'detached-process', 'pid': child.pid, 'at': at, 'delaySeconds': delay}\n # A transient timer in the user manager, outside nymph's cgroup (a child of nymph\n # would be killed by its own restart). No Restart= and an OnActiveSec timer that\n # unloads after elapsing: systemd starts the service once and then forgets both.\n unit = 'dreamlake-nymph-restart-%s-%s' % (d.name, os.urandom(3).hex())\n run([shutil.which('systemd-run'), '--user', '--quiet', '--collect', '--unit=' + unit, '--on-active=%ds' % delay,\n '--timer-property=AccuracySec=1s', '--timer-property=RemainAfterElapse=no', '/bin/sh', str(script)])\n return {'mechanism': 'systemd-run-timer', 'unit': unit, 'at': at, 'delaySeconds': delay}\n\ndef helper_finished(restart):\n if restart.get('mechanism') == 'detached-process':\n try: os.kill(restart['pid'], 0)\n except ProcessLookupError: return True\n except OSError: return False\n try: command = run(['ps', '-o', 'command=', '-p', str(restart['pid'])]).stdout.decode('utf8', errors='replace')\n except Exception: return True\n return 'restart.sh' not in command\n for suffix in ('.timer', '.service'):\n result = subprocess.run(['systemctl', '--user', 'show', restart['unit'] + suffix, '-p', 'ActiveState'],\n stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)\n if result.stdout.decode().strip() in ('ActiveState=active', 'ActiveState=activating'): return False\n return True\n\ndef apply_binary(fleet, service, binary, source, sha, receipt, delay):\n \"\"\"Keep the previous binary, swap atomically, record, then schedule the one restart.\"\"\"\n d = receipt['dir']\n shutil.copyfile(str(source), str(d / 'nymph'))\n shutil.copyfile(str(binary), str(d / 'previous-nymph'))\n for kept in ('nymph', 'previous-nymph'): os.chmod(str(d / kept), 0o700)\n if sha256_file(d / 'nymph') != sha or sha256_file(d / 'previous-nymph') != receipt['previousSha256']:\n raise RuntimeError('copied binary changed')\n del receipt['dir']\n receipt['status'] = 'swapping'\n write(d / 'receipt.json', json.dumps(receipt, sort_keys=True))\n swap_binary(d / 'nymph', binary, sha)\n try:\n receipt['restart'] = schedule_restart(service, d, delay)\n except Exception:\n swap_binary(d / 'previous-nymph', binary, receipt['previousSha256'])\n receipt['status'] = 'reverted'\n write(d / 'receipt.json', json.dumps(receipt, sort_keys=True))\n fail('restart_schedule_failed', upgradeId=d.name)\n receipt['status'] = 'restart_scheduled'\n write(d / 'receipt.json', json.dumps(receipt, sort_keys=True))\n return d\n\ndef restart_only(fleet, service, binary, receipt, delay):\n d = receipt.pop('dir')\n receipt['status'] = 'restart_scheduled'\n receipt['restart'] = schedule_restart(service, d, delay)\n write(d / 'receipt.json', json.dumps(receipt, sort_keys=True))\n return d\n\ndef scheduled(d, receipt, removed):\n return {'status': 'restart_scheduled', 'action': receipt['action'], 'upgradeId': d.name, 'version': receipt['version'],\n 'previousVersion': receipt.get('previousVersion'), 'sha256': receipt['sha256'], 'previousSha256': receipt.get('previousSha256'),\n 'restart': {k: receipt['restart'][k] for k in ('mechanism', 'at', 'delaySeconds')}, 'before': receipt['before'],\n 'leftoverJobsRemoved': removed}\n\ndef verify(fleet, service, binary, p):\n d, receipt = select_receipt(fleet, service, p.get('upgradeId'))\n stable = bounded(p.get('stableSeconds'), 15, 1, 300, 'invalid_stable_seconds')\n restart, before = receipt.get('restart') or {}, receipt.get('before') or {}\n deadline = (restart.get('at') or 0) + RESTART_GRACE\n while time.time() < deadline and not (d / 'restart.exit').exists(): time.sleep(0.5)\n state = service_state(service)\n while time.time() < deadline and (not state.get('pid') or state.get('pid') == before.get('pid')):\n time.sleep(1)\n state = service_state(service)\n samples, end = [state], time.time() + stable\n while time.time() < end:\n time.sleep(1)\n samples.append(service_state(service))\n after = samples[-1]\n log = d / 'restart.log'\n helper_runs = len(log.read_text().split()) if log.exists() else 0\n exit_status = (d / 'restart.exit').read_text().strip() if (d / 'restart.exit').exists() else None\n restart_pid = (d / 'restart.pid').read_text().strip() if (d / 'restart.pid').exists() else ''\n checks = {\n 'restartRan': (d / 'restart.started').exists(),\n 'restartRuns': helper_runs,\n 'restartExit': int(exit_status) if exit_status and exit_status.isdigit() else None,\n 'pidChanged': bool(after.get('pid')) and after.get('pid') != before.get('pid'),\n 'pidStable': len({s.get('pid') for s in samples}) == 1 and bool(after.get('pid')),\n 'restartPid': int(restart_pid) if restart_pid.isdigit() else None,\n 'helperFinished': helper_finished(restart) if restart else False,\n 'binarySha256': sha256_file(binary) == receipt['sha256'],\n 'version': binary_version(binary),\n # Informational: the PID chain (pidFromRestart) is the proof; ps start times are coarse.\n 'processCurrent': running_current(after, binary),\n 'leftoverJobsRemoved': leftover_restart_jobs(pathlib.Path.home()),\n }\n if service['kind'] == 'launchd' and before.get('runs') is not None and after.get('runs') is not None:\n checks['serviceStarts'] = after['runs'] - before['runs']\n if service['kind'] == 'systemd':\n checks['invocationChanged'] = bool(after.get('invocation')) and after.get('invocation') != before.get('invocation')\n # An explicit systemctl restart resets NRestarts. Only the new\n # activation's count applies; subtracting the previous activation can\n # reject a healthy restart or hide new crashes behind an old count.\n checks['autoRestarts'] = after.get('autoRestarts', 0)\n failures = [k for k, ok in [\n ('restartRan', checks['restartRan']), ('restartRuns', helper_runs == 1), ('restartExit', checks['restartExit'] == 0),\n ('pidChanged', checks['pidChanged']), ('pidStable', checks['pidStable']),\n ('pidFromRestart', checks['restartPid'] is not None and checks['restartPid'] == after.get('pid')),\n ('helperFinished', checks['helperFinished']),\n ('binarySha256', checks['binarySha256']), ('version', checks['version'] == receipt['version']),\n ('serviceStarts', checks.get('serviceStarts', 1) == 1),\n ('invocationChanged', checks.get('invocationChanged', True)), ('autoRestarts', checks.get('autoRestarts', 0) == 0)] if not ok]\n result = {'status': 'failed' if failures else 'verified', 'action': receipt['action'], 'upgradeId': d.name,\n 'version': checks['version'], 'expectedVersion': receipt['version'],\n 'pid': {'before': before.get('pid'), 'after': after.get('pid')}, 'restarts': helper_runs,\n 'stableSeconds': stable, 'checks': checks, 'failures': failures}\n write(d / 'verification.json', json.dumps(result, sort_keys=True))\n print(json.dumps(result))\n if failures: sys.exit(1)\n\ndef inspect(fleet, service, binary, p):\n state = service_state(service)\n version = binary_version(binary)\n wanted = p.get('version')\n sha = sha256_file(binary)\n current = verified_current(fleet, service, sha, state.get('pid')) or running_current(state, binary)\n pending = pending_restart(fleet)\n rollback = next((d.name for d, data in reversed(receipts(fleet)) if data.get('binary') == service['binary']\n and data.get('status') == 'restart_scheduled' and (d / 'previous-nymph').is_file()), None)\n plan = None\n if isinstance(wanted, str):\n wanted = wanted[1:] if wanted.startswith('v') else wanted\n plan = 'blocked:restart_pending' if pending else 'current' if version == wanted and current else 'restart' if version == wanted else 'upgrade'\n print(json.dumps({'status': 'inspected', 'service': {k: v for k, v in service.items() if k != 'binary'}, 'binary': service['binary'],\n 'version': version, 'sha256': sha, 'pid': state.get('pid'), 'processCurrent': current,\n 'pendingRestart': pending, 'rollbackAvailable': rollback, 'plan': plan,\n 'leftoverJobs': leftover_restart_jobs(pathlib.Path.home(), remove=False)}))\n\ndef upgrade_main(p):\n action = p['action']\n if not isinstance(p.get('name'), str) or not p['name']: fail('invalid_request')\n service_prerequisites()\n home = pathlib.Path.home()\n fleet = fleet_root(home)\n service = installed_service(p['name'], home)\n binary = pathlib.Path(service['binary'])\n check_binary(binary)\n if action == 'inspect': return inspect(fleet, service, binary, p)\n with open(str(fleet / '.lock'), 'a') as lock:\n try: fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)\n except OSError: fail('upgrade_in_progress')\n if action == 'verify': return verify(fleet, service, binary, p)\n delay = bounded(p.get('restartDelaySeconds'), 15, 1, 600, 'invalid_restart_delay')\n removed = leftover_restart_jobs(home)\n pending = pending_restart(fleet)\n if pending: fail('restart_pending', upgradeId=pending)\n current_sha, current_version = sha256_file(binary), binary_version(binary)\n state = service_state(service)\n base = {'tool': UPGRADE_TOOL, 'schema': 1, 'name': p['name'], 'binary': service['binary'],\n 'service': {k: v for k, v in service.items() if k != 'binary'}, 'previousVersion': current_version,\n 'previousSha256': current_sha, 'before': state, 'leftoverJobsRemoved': removed, 'at': time.time()}\n if action == 'rollback':\n source_dir, source = select_receipt(fleet, service, p.get('upgradeId'), rollback=True)\n if current_sha != source.get('sha256'): fail('rollback_receipt_mismatch', upgradeId=source_dir.name)\n previous = source_dir / 'previous-nymph'\n if sha256_file(previous) != source.get('previousSha256'): fail('rollback_binary_corrupt', upgradeId=source_dir.name)\n receipt = dict(base, action='rollback', rollbackOf=source_dir.name, version=source.get('previousVersion') or binary_version(previous),\n sha256=source['previousSha256'], dir=new_action_dir(fleet))\n d = apply_binary(fleet, service, binary, previous, receipt['sha256'], receipt, delay)\n print(json.dumps(scheduled(d, receipt, removed)))\n return\n version = p.get('version')\n if not isinstance(version, str) or not re.fullmatch('v?' + VERSION, version): fail('invalid_version')\n version = version[1:] if version.startswith('v') else version\n if current_version == version:\n if verified_current(fleet, service, current_sha, state.get('pid')) or running_current(state, binary):\n print(json.dumps({'status': 'current', 'version': version, 'sha256': current_sha, 'pid': state.get('pid'),\n 'leftoverJobsRemoved': removed}))\n return\n # Already swapped but the service still runs an older process: restart only.\n receipt = dict(base, action='restart', version=version, sha256=current_sha, dir=new_action_dir(fleet))\n d = restart_only(fleet, service, binary, receipt, delay)\n print(json.dumps(scheduled(d, receipt, removed)))\n return\n d = new_action_dir(fleet)\n try:\n stage = d / 'stage'\n stage.mkdir(mode=0o700)\n with urllib.request.urlopen('https://dreamlake.ai/dreamlake/nymph/install.sh', timeout=30) as response:\n installer = response.read()\n # The official installer downloads the archive and verifies its published SHA-256.\n run(['bash', '-s', '--', '--dest', str(stage), '--version', 'v' + version], input=installer)\n staged = stage / 'nymph'\n if not staged.is_file(): fail('installer_failed')\n found = binary_version(staged)\n if found != version: fail('installer_version_mismatch', expected=version, found=found)\n sha = sha256_file(staged)\n receipt = dict(base, action='upgrade', version=version, sha256=sha, dir=d)\n apply_binary(fleet, service, binary, staged, sha, receipt, delay)\n shutil.rmtree(str(stage), ignore_errors=True)\n except BaseException:\n if not (d / 'receipt.json').exists(): shutil.rmtree(str(d), ignore_errors=True)\n raise\n print(json.dumps(scheduled(d, receipt, removed)))\n\ndef main():\n p = json.load(sys.stdin)\n if p.get('action') in UPGRADE_ACTIONS:\n try:\n return upgrade_main(p)\n except SystemExit:\n raise\n except Exception:\n fail('upgrade_failed')\n # Check before identity creation or requesting an enrollment grant.\n openssl = check_prerequisites()\n home = pathlib.Path.home()\n root = home / '.local/state/dreamlake/hosts' / hashlib.sha256(p['name'].encode()).hexdigest()\n root.mkdir(parents=True, exist_ok=True, mode=0o700)\n os.chmod(root, 0o700)\n with open(root / 'lock', 'a') as lock:\n fcntl.flock(lock, fcntl.LOCK_EX)\n if p.get('managedAccess'):\n binary = nymph_binary(p, home)\n try: run([binary, 'access', '--help'])\n except Exception: prerequisite_error('nymph_access_version_required')\n if (root / 'nymph.toml').exists() and not (root / 'access.json').exists():\n prerequisite_error('nymph_access_migration_required')\n key = root / 'identity.key'\n if not key.exists(): write(key, base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))\n os.chmod(key, 0o600)\n raw = base64.urlsafe_b64decode(key.read_text().strip() + '==')\n if len(raw) != 32: raise RuntimeError('identity format')\n public = run([openssl,'pkey','-inform','DER','-pubout','-outform','DER'], input=bytes.fromhex('302e020100300506032b657004220420') + raw).stdout\n if len(public) != 44 or public[:12] != bytes.fromhex('302a300506032b6570032100'): raise RuntimeError('public format')\n public_key = base64.urlsafe_b64encode(public[12:]).decode().rstrip('=')\n if p['action'] == 'probe':\n print(json.dumps({'unixUser':pwd.getpwuid(os.getuid()).pw_name,'publicKey':public_key}))\n return\n if public_key != p['publicKey']: raise RuntimeError('identity changed')\n # Never fall back to a privileged system unit or an unsupervised daemon.\n binary = nymph_binary(p, home)\n web_terminal = p.get('webTerminal', True)\n if not isinstance(web_terminal, bool): raise RuntimeError('invalid web terminal option')\n sshd = '/usr/sbin/sshd'\n if web_terminal:\n if not os.access(sshd, os.X_OK): prerequisite_error('sshd_required')\n try: run([sshd, '-V'])\n except Exception: prerequisite_error('sshd_required')\n version = run([binary, '--version']).stdout.decode('utf8', errors='replace')\n match = re.search(r'\\b(\\d+)\\.(\\d+)\\.(\\d+)\\b', version)\n if not match or tuple(map(int, match.groups())) < (0, 1, 11):\n prerequisite_error('nymph_ssh_version_required')\n if sys.platform == 'linux':\n privilege_dir = pathlib.Path('/run/sshd')\n if not privilege_dir.is_dir() or privilege_dir.stat().st_uid != 0 or privilege_dir.stat().st_mode & 0o022:\n prerequisite_error('sshd_privilege_directory_required')\n (root / 'ssh').mkdir(exist_ok=True, mode=0o700)\n os.chmod(root / 'ssh', 0o700)\n grant = root / 'enroll-token'\n if p.get('token'): write(grant, p['token'])\n q = json.dumps\n config = '\\n'.join([\n '[server]', 'url = ' + q(p['controlPlaneUrl']), 'namespace = ' + q(p['namespace']),\n '[daemon]', 'machine_id = ' + q(p['machineId']), 'label = ' + q(p['name']),\n '[runtime]', 'keep_alive_s = -1', 'workdir = ' + q(str(root / 'work')), 'runners = [\"process\"]', 'default_runner = \"process\"',\n '[identity]', 'enabled = true', 'key_file = ' + q(str(key)), 'enroll_token_file = ' + q(str(grant)),\n ]) + '\\n'\n if p.get('managedAccess'):\n access = root / 'access.json'\n if not access.exists():\n write(access, json.dumps({'version': 1, 'scope': {'server': p['controlPlaneUrl'], 'namespace': p['namespace'], 'machine_id': p['machineId']}, 'permissions': {'upload': False, 'command_execution': False}}))\n config = 'access_file = ' + q(str(access)) + '\\n' + config\n if web_terminal:\n config += '\\n'.join(['[ssh]', 'enabled = true', 'state_dir = ' + q(str(root / 'ssh')),\n 'sshd = ' + q(sshd), 'max_duration_s = 3600']) + '\\n'\n (root / 'work').mkdir(exist_ok=True)\n config_file = root / 'nymph.toml'\n changed = not config_file.exists() or config_file.read_text() != config\n reload_marker = root / 'launchd-reload-required'\n if sys.platform == 'darwin' and changed:\n write(reload_marker, 'pending')\n write(config_file, config)\n service_path = str(home / '.local/bin') + (':/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin' if sys.platform == 'darwin' else ':/usr/local/bin:/usr/bin:/bin')\n if sys.platform == 'darwin':\n label = service_names(p['name'])[0]\n domain = 'gui/' + str(os.getuid())\n target = domain + '/' + label\n agents = home / 'Library/LaunchAgents'\n agents.mkdir(parents=True, exist_ok=True)\n agent_file = agents / (label + '.plist')\n agent = plistlib.dumps({\n 'Label': label,\n 'ProgramArguments': [binary, '--config', str(config_file)],\n 'EnvironmentVariables': {'PATH': service_path, 'HOME': str(home)},\n 'WorkingDirectory': str(root / 'work'),\n 'RunAtLoad': True,\n 'KeepAlive': True,\n 'ThrottleInterval': 3,\n # Daemon output can contain sensitive workloads: do not persist it.\n 'StandardOutPath': '/dev/null',\n 'StandardErrorPath': '/dev/null',\n }, sort_keys=True).decode('utf8')\n changed = changed or not agent_file.exists() or agent_file.read_text() != agent or reload_marker.exists()\n if changed:\n write(reload_marker, 'pending')\n # Unload before replacing a loaded definition. Never ignore bootout failure.\n loaded = subprocess.run(['launchctl', 'print', target], stdout=subprocess.DEVNULL,\n stderr=subprocess.DEVNULL).returncode == 0\n if loaded and changed:\n run(['launchctl', 'bootout', target])\n loaded = False\n write(agent_file, agent)\n run(['launchctl', 'enable', target])\n if not loaded:\n run(['launchctl', 'bootstrap', domain, str(agent_file)])\n # No -k: replay must not kill a healthy daemon or its active workloads.\n run(['launchctl', 'kickstart', target])\n run(['launchctl', 'print', target])\n if reload_marker.exists():\n reload_marker.unlink()\n else:\n # JSON string escaping covers quoted systemd arguments; percent must be escaped separately.\n unit_quote = lambda s: q(s.replace('%','%%'))\n unit_name = service_names(p['name'])[1]\n unit_dir = home / '.config/systemd/user'\n unit_dir.mkdir(parents=True, exist_ok=True)\n unit = '[Unit]\\nDescription=DreamLake nymph host\\n[Service]\\nEnvironment=' + unit_quote('PATH=' + service_path) + '\\nExecStart=' + unit_quote(binary) + ' --config ' + unit_quote(str(config_file)) + '\\nRestart=on-failure\\nRestartSec=3\\n[Install]\\nWantedBy=default.target\\n'\n unit_file = unit_dir / unit_name\n changed = changed or not unit_file.exists() or unit_file.read_text() != unit\n write(unit_file, unit)\n run(['systemctl','--user','daemon-reload'])\n run(['systemctl','--user','enable',unit_name])\n run(['systemctl','--user','restart' if changed else 'start',unit_name])\n print(json.dumps({'started':True}))\ntry:\n main()\nexcept Exception:\n # Never forward child stdout/stderr or payloads: these can contain grants.\n print(json.dumps({'error':'Remote bootstrap failed. Verify Python 3, OpenSSL, the platform user-service manager, OpenSSL Ed25519 support, and nymph installation access.'}))\n sys.exit(1)\n";
@@ -2,6 +2,7 @@ import { collectionList } from "../collection-list.js";
2
2
  import { inspectHostCatalog, changeHostCatalog, formatHostCatalog } from "./catalog.js";
3
3
  import { registerHostLifecycleCommands } from "./lifecycle.js";
4
4
  import { registerHostSshCommands } from "./ssh.js";
5
+ import { registerHostUpgradeCommands } from "./upgrade.js";
5
6
  import { resolveRemote, resolveToken } from '../config.js';
6
7
  import { saveCredentials } from './credentials.js';
7
8
  import { enrollHost, hostStatus } from "./enroll.js";
@@ -276,4 +277,5 @@ export function registerHostsCommand(program) {
276
277
  });
277
278
  registerHostSshCommands(group, program);
278
279
  registerHostLifecycleCommands(group);
280
+ registerHostUpgradeCommands(group);
279
281
  }
@@ -45,7 +45,10 @@ export interface SshIO {
45
45
  fetch: typeof fetch;
46
46
  socket: (url: string, ticket: string) => WebSocket;
47
47
  spawn: (args: string[]) => ChildProcess;
48
+ chooseTarget?: (targets: SshTarget[]) => Promise<string>;
48
49
  }
50
+ export declare const defaultSshIO: SshIO;
51
+ export declare function chooseSshTarget(targets: SshTarget[], selector: string, opts: SshOptions, argv: string[] | undefined, choose?: SshIO['chooseTarget']): Promise<SshTarget>;
49
52
  export declare function sshPublicKey(value: string): string;
50
53
  export declare function validateSshTarget(t: SshTarget, hostId: string, namespace: string): void;
51
54
  export declare function validateSshSession(s: SshSession, t: SshTarget, previous?: string): string;
@@ -8,6 +8,7 @@ import { Duplex } from 'node:stream';
8
8
  import { promisify } from 'node:util';
9
9
  import { setTimeout as delay } from 'node:timers/promises';
10
10
  import WebSocket from 'ws';
11
+ import { select } from '@inquirer/prompts';
11
12
  import { HostApiError, hostApiPath, hostRequest } from './api.js';
12
13
  import { hostStatus } from './enroll.js';
13
14
  import { resolveHostNamespace } from './inventory.js';
@@ -19,12 +20,38 @@ export function busyRetryDelay(attempt, retryAt, now = Date.now()) {
19
20
  const hinted = retryAt ? Math.min(Math.max(Date.parse(retryAt) - now, 0), 5000) : 0;
20
21
  return Math.max(Number.isFinite(hinted) ? hinted : 0, 1000 * 2 ** (attempt - 1));
21
22
  }
22
- const defaults = {
23
+ export const defaultSshIO = {
23
24
  request: hostRequest, fetch: (...args) => fetch(...args),
24
25
  socket: (url, ticket) => new WebSocket(url, 'nymph-ssh.v1', { headers: { Authorization: `Bearer ${ticket}` },
25
26
  perMessageDeflate: false, maxPayload: 65537, handshakeTimeout: 10000, followRedirects: false }),
26
27
  spawn: args => spawn('ssh', args, { stdio: 'inherit' }),
27
28
  };
29
+ export async function chooseSshTarget(targets, selector, opts, argv, choose) {
30
+ if (targets.length === 0)
31
+ throw new Error('No ready SSH enrollment for this host');
32
+ if (targets.length === 1)
33
+ return targets[0];
34
+ const label = (t) => `${t.username} (UID ${t.unixUid}) — ready — enrollment ${t.enrollmentId}`;
35
+ if (!choose && process.stdin.isTTY && process.stderr.isTTY) {
36
+ choose = choices => select({ message: `Choose an SSH user on ${selector}`, choices: choices.map(t => ({ name: label(t), value: t.enrollmentId })) }, { output: process.stderr });
37
+ }
38
+ if (!choose) {
39
+ const quote = (value) => /^[A-Za-z0-9_./:@=-]+$/.test(value) ? value : "'" + value.replace(/'/g, "'\\''") + "'";
40
+ const options = [opts.namespace ? ['--namespace', opts.namespace] : [],
41
+ opts.duration ? ['--duration', opts.duration] : [], opts.timeout ? ['--timeout', opts.timeout] : []].flat();
42
+ const rows = targets.map(t => {
43
+ const command = ['dreamlake', argv === undefined ? 'ssh' : 'exec', selector, ...options,
44
+ '--enrollment', t.enrollmentId, ...(argv === undefined ? [] : ['--', ...argv])];
45
+ return ` ${label(t)}\n ${command.map(quote).join(' ')}`;
46
+ });
47
+ throw new Error(`Multiple SSH enrollments; choose one with --enrollment:\n${rows.join('\n')}`);
48
+ }
49
+ const enrollment = await choose(targets);
50
+ const selected = targets.filter(t => t.enrollmentId === enrollment);
51
+ if (selected.length !== 1)
52
+ throw new Error('No unique SSH enrollment selected');
53
+ return selected[0];
54
+ }
28
55
  export function sshPublicKey(value) {
29
56
  if (typeof value !== 'string')
30
57
  throw new Error('Invalid SSH host key');
@@ -105,7 +132,7 @@ export class SshRelay extends Duplex {
105
132
  _final(done) { this.ws.send(Buffer.from([1]), { binary: true }, error => done(error ? new Error('SSH relay FIN failed') : undefined)); }
106
133
  _destroy(error, done) { this.ws.terminate(); done(error); }
107
134
  }
108
- export async function runHostSsh(selector, opts, argv, io = defaults) {
135
+ export async function runHostSsh(selector, opts, argv, io = defaultSshIO) {
109
136
  if (process.platform === 'win32')
110
137
  throw new Error('Host SSH currently requires Linux or macOS and OpenSSH');
111
138
  if (selector.includes('*'))
@@ -129,12 +156,14 @@ export async function runHostSsh(selector, opts, argv, io = defaults) {
129
156
  if (!Array.isArray(catalog?.targets))
130
157
  throw new Error('Invalid SSH target catalog');
131
158
  const matches = catalog.targets.filter((t) => t.hostId === detail.host.id && (!opts.enrollment || t.enrollmentId === opts.enrollment));
132
- if (matches.length !== 1)
133
- throw new Error(matches.length ? 'Multiple SSH enrollments; select --enrollment' : 'No ready SSH enrollment for this host');
134
- const target = matches[0];
135
- validateSshTarget(target, detail.host.id, namespace);
136
- if (!detail.enrollments.some((e) => e.id === target.enrollmentId && e.machineId === target.machineId && e.unixUser === target.username))
137
- throw new Error('SSH enrollment identity changed');
159
+ // Validate every displayed identity before prompting, and preserve the same
160
+ // host/enrollment binding and host-key checks after the selection.
161
+ for (const target of matches) {
162
+ validateSshTarget(target, detail.host.id, namespace);
163
+ if (!detail.enrollments.some((e) => e.id === target.enrollmentId && e.machineId === target.machineId && e.unixUser === target.username))
164
+ throw new Error('SSH enrollment identity changed');
165
+ }
166
+ const target = await chooseSshTarget(matches, selector, opts, argv, io.chooseTarget);
138
167
  const dir = await mkdtemp(join(tmpdir(), 'dreamlake-ssh-'));
139
168
  let sessionId, credential;
140
169
  let child, relay, socket, ws;
@@ -0,0 +1,122 @@
1
+ import type { Command } from "commander";
2
+ import { hostStatus } from "./enroll.js";
3
+ import { listHosts, resolveHostNamespace } from "./inventory.js";
4
+ /**
5
+ * Host-side upgrade, verification and rollback run the enrollment bootstrap
6
+ * (bootstrap.py) over `dreamlake exec`. The program and its JSON payload travel
7
+ * on stdin, so the remote command stays a short fixed loader.
8
+ */
9
+ export declare const BOOTSTRAP_LOADER: string;
10
+ export declare function bootstrapInput(payload: Record<string, unknown>): Buffer;
11
+ /** The bootstrap prints exactly one JSON object; tolerate shell noise before it. */
12
+ export declare function parseBootstrapOutput(text: string): Record<string, any> | undefined;
13
+ export interface ExecTarget {
14
+ selector: string;
15
+ namespace?: string;
16
+ enrollment?: string;
17
+ }
18
+ export interface ExecReply {
19
+ exitCode: number;
20
+ result?: Record<string, any>;
21
+ }
22
+ export type HostExec = (target: ExecTarget, payload: Record<string, unknown>, timeoutSeconds: number) => Promise<ExecReply>;
23
+ /** Runs one bootstrap action through the nymph SSH relay (the `dreamlake exec` path). */
24
+ export declare const execOverNymph: HostExec;
25
+ export type FleetAction = "upgrade" | "rollback";
26
+ export interface FleetOptions {
27
+ action: FleetAction;
28
+ nymphVersion?: string;
29
+ upgradeId?: string;
30
+ namespace?: string;
31
+ enrollment?: string;
32
+ all?: boolean;
33
+ dryRun?: boolean;
34
+ concurrency?: string | number;
35
+ maxFailures?: string | number;
36
+ restartDelay?: string | number;
37
+ stableSeconds?: string | number;
38
+ verifyTimeout?: string | number;
39
+ record?: string;
40
+ json?: boolean;
41
+ }
42
+ export interface FleetPlan {
43
+ action: FleetAction;
44
+ version?: string;
45
+ upgradeId?: string;
46
+ dryRun: boolean;
47
+ namespace?: string;
48
+ enrollment?: string;
49
+ concurrency: number;
50
+ maxFailures: number;
51
+ restartDelay: number;
52
+ stableSeconds: number;
53
+ verifyTimeout: number;
54
+ }
55
+ export interface FleetHost {
56
+ id: string;
57
+ name: string;
58
+ namespace: string;
59
+ online: boolean;
60
+ }
61
+ export type HostOutcomeStatus = "upgraded" | "rolled_back" | "current" | "planned" | "failed" | "skipped" | "not_started";
62
+ export interface HostOutcome {
63
+ host: string;
64
+ hostId: string;
65
+ status: HostOutcomeStatus;
66
+ upgradeId?: string;
67
+ version?: string | null;
68
+ previousVersion?: string | null;
69
+ pid?: {
70
+ before?: number | null;
71
+ after?: number | null;
72
+ };
73
+ restarts?: number;
74
+ restart?: Record<string, unknown>;
75
+ leftoverJobsRemoved?: string[];
76
+ failures?: string[];
77
+ code?: string;
78
+ error?: string;
79
+ plan?: Record<string, unknown>;
80
+ startedAt?: string;
81
+ finishedAt?: string;
82
+ earlierRestart?: {
83
+ upgradeId: string;
84
+ status: "verified";
85
+ };
86
+ }
87
+ export interface FleetDeps {
88
+ exec: HostExec;
89
+ sleep: (ms: number) => Promise<void>;
90
+ now: () => number;
91
+ record: (entry: Record<string, unknown>) => void;
92
+ }
93
+ export declare function resolveFleetPlan(opts: FleetOptions): FleetPlan;
94
+ export interface ResolveDeps {
95
+ status: typeof hostStatus;
96
+ list: typeof listHosts;
97
+ namespace: typeof resolveHostNamespace;
98
+ }
99
+ /** Expands selectors into distinct hosts, in order. A host appears at most once. */
100
+ export declare function resolveFleetHosts(selectors: string[], opts: {
101
+ all?: boolean;
102
+ namespace?: string;
103
+ }, deps?: ResolveDeps): Promise<FleetHost[]>;
104
+ /** One host: apply, wait out the delayed restart, then verify it happened exactly once. */
105
+ export declare function processFleetHost(host: FleetHost, plan: FleetPlan, deps: FleetDeps): Promise<HostOutcome>;
106
+ export interface FleetReport {
107
+ action: FleetAction;
108
+ version?: string;
109
+ dryRun: boolean;
110
+ stoppedEarly: boolean;
111
+ counts: Partial<Record<HostOutcomeStatus, number>>;
112
+ hosts: HostOutcome[];
113
+ record?: string;
114
+ }
115
+ /** Bounded concurrency; stops starting hosts after maxFailures; one worker per host at a time. */
116
+ export declare function runFleet(hosts: FleetHost[], plan: FleetPlan, deps: FleetDeps): Promise<FleetReport>;
117
+ export declare function fleetSucceeded(report: FleetReport): boolean;
118
+ export declare function formatFleetReport(report: FleetReport): string;
119
+ export declare function runHostsUpgrade(selectors: string[], opts: FleetOptions, overrides?: Partial<FleetDeps> & {
120
+ resolve?: ResolveDeps;
121
+ }): Promise<number>;
122
+ export declare function registerHostUpgradeCommands(group: Command): void;
@@ -0,0 +1,366 @@
1
+ import { spawn } from "node:child_process";
2
+ import { appendFileSync, mkdirSync } from "node:fs";
3
+ import { randomBytes } from "node:crypto";
4
+ import { homedir } from "node:os";
5
+ import path from "node:path";
6
+ import { BOOTSTRAP_PYTHON } from "./bootstrap-source.js";
7
+ import { hostStatus } from "./enroll.js";
8
+ import { hostConnection, listHosts, resolveHostNamespace } from "./inventory.js";
9
+ import { defaultSshIO, runHostSsh } from "./ssh.js";
10
+ /**
11
+ * Host-side upgrade, verification and rollback run the enrollment bootstrap
12
+ * (bootstrap.py) over `dreamlake exec`. The program and its JSON payload travel
13
+ * on stdin, so the remote command stays a short fixed loader.
14
+ */
15
+ export const BOOTSTRAP_LOADER = [
16
+ "import io,sys",
17
+ "d=sys.stdin.buffer.read()",
18
+ "n,_,r=d.partition(b'\\n')",
19
+ "n=int(n)",
20
+ "sys.stdin=io.TextIOWrapper(io.BytesIO(r[n:]),encoding='utf-8')",
21
+ "exec(compile(r[:n].decode('utf-8'),'dreamlake-host-bootstrap','exec'),{'__name__':'__main__'})",
22
+ ].join("\n");
23
+ export function bootstrapInput(payload) {
24
+ const source = Buffer.from(BOOTSTRAP_PYTHON, "utf8");
25
+ return Buffer.concat([Buffer.from(`${source.length}\n`), source, Buffer.from(JSON.stringify(payload))]);
26
+ }
27
+ /** The bootstrap prints exactly one JSON object; tolerate shell noise before it. */
28
+ export function parseBootstrapOutput(text) {
29
+ for (const line of text.trim().split("\n").reverse()) {
30
+ try {
31
+ const value = JSON.parse(line);
32
+ if (value && typeof value === "object" && !Array.isArray(value))
33
+ return value;
34
+ }
35
+ catch { }
36
+ }
37
+ return undefined;
38
+ }
39
+ /** Runs one bootstrap action through the nymph SSH relay (the `dreamlake exec` path). */
40
+ export const execOverNymph = async (target, payload, timeoutSeconds) => {
41
+ const chunks = [];
42
+ let bytes = 0;
43
+ const io = { ...defaultSshIO, spawn: args => {
44
+ const child = spawn("ssh", args, { stdio: ["pipe", "pipe", "ignore"] });
45
+ child.stdout.on("data", (b) => { bytes += b.length; if (bytes <= 64_000)
46
+ chunks.push(b); });
47
+ child.stdin.on("error", () => { });
48
+ child.stdin.end(bootstrapInput(payload));
49
+ return child;
50
+ } };
51
+ const exitCode = await runHostSsh(target.selector, { namespace: target.namespace, enrollment: target.enrollment,
52
+ duration: "1800", timeout: String(timeoutSeconds) }, ["python3", "-c", BOOTSTRAP_LOADER], io);
53
+ return { exitCode, result: parseBootstrapOutput(Buffer.concat(chunks).toString("utf8")) };
54
+ };
55
+ const VERSION = /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
56
+ const UPGRADE_ID = /^\d{8}-\d{3}$/;
57
+ const ENROLLMENT = /^[a-f0-9]{24}$/;
58
+ // Host-side verification waits up to this long after the scheduled restart.
59
+ const RESTART_GRACE = 90;
60
+ function integer(value, fallback, low, high, flag) {
61
+ const n = value === undefined ? fallback : Number(value);
62
+ if (!Number.isInteger(n) || n < low || n > high)
63
+ throw new Error(`${flag} must be an integer from ${low} to ${high}`);
64
+ return n;
65
+ }
66
+ export function resolveFleetPlan(opts) {
67
+ let version;
68
+ if (opts.action === "upgrade") {
69
+ if (typeof opts.nymphVersion !== "string" || !VERSION.test(opts.nymphVersion)) {
70
+ throw new Error("--nymph-version must be an exact release such as 0.1.32; fleet upgrades never use latest");
71
+ }
72
+ version = opts.nymphVersion.replace(/^v/, "");
73
+ }
74
+ else if (opts.nymphVersion !== undefined)
75
+ throw new Error("rollback restores the kept previous binary; omit --nymph-version");
76
+ if (opts.upgradeId !== undefined && (opts.action !== "rollback" || !UPGRADE_ID.test(opts.upgradeId))) {
77
+ throw new Error("--upgrade-id applies to rollback and must look like YYYYMMDD-NNN");
78
+ }
79
+ if (opts.enrollment !== undefined && !ENROLLMENT.test(opts.enrollment))
80
+ throw new Error("--enrollment must be an exact enrollment ID");
81
+ const restartDelay = integer(opts.restartDelay, 15, 5, 300, "--restart-delay");
82
+ const stableSeconds = integer(opts.stableSeconds, 15, 5, 300, "--stable-seconds");
83
+ return {
84
+ action: opts.action, version, upgradeId: opts.upgradeId, dryRun: opts.dryRun === true, namespace: opts.namespace, enrollment: opts.enrollment,
85
+ concurrency: integer(opts.concurrency, 1, 1, 16, "--concurrency"),
86
+ maxFailures: integer(opts.maxFailures, 1, 1, 10_000, "--max-failures"),
87
+ restartDelay, stableSeconds,
88
+ verifyTimeout: integer(opts.verifyTimeout, 300, restartDelay + stableSeconds + 30, 3600, "--verify-timeout"),
89
+ };
90
+ }
91
+ const resolveDefaults = { status: hostStatus, list: listHosts, namespace: resolveHostNamespace };
92
+ /** Expands selectors into distinct hosts, in order. A host appears at most once. */
93
+ export async function resolveFleetHosts(selectors, opts, deps = resolveDefaults) {
94
+ if (opts.all ? selectors.length > 0 : selectors.length === 0)
95
+ throw new Error("Select hosts by ID, namespace/group/host or namespace/group/*, or use --all (not both)");
96
+ const hosts = [];
97
+ const seen = new Set();
98
+ const add = (host, namespace, enrollments = host.enrollments) => {
99
+ if (!host || typeof host.id !== "string" || !/^[a-f0-9]{24}$/i.test(host.id) || typeof host.name !== "string")
100
+ throw new Error("Host API returned an invalid host");
101
+ const id = host.id.toLowerCase();
102
+ if (seen.has(id))
103
+ return;
104
+ seen.add(id);
105
+ hosts.push({ id, name: host.name, namespace, online: hostConnection(enrollments) === "online" });
106
+ };
107
+ if (opts.all) {
108
+ const namespace = await deps.namespace(opts.namespace);
109
+ for (const host of (await deps.list({ namespace, all: true })).hosts)
110
+ add(host, namespace);
111
+ return hosts;
112
+ }
113
+ for (const selector of selectors) {
114
+ const parts = selector.split("/");
115
+ if (parts.length === 3 && parts[2] === "*") {
116
+ if (opts.namespace !== undefined && opts.namespace !== parts[0])
117
+ throw new Error("--namespace conflicts with the host selector");
118
+ for (const host of (await deps.list({ namespace: parts[0], group: parts[1], all: true })).hosts)
119
+ add(host, parts[0]);
120
+ continue;
121
+ }
122
+ if (selector.includes("*"))
123
+ throw new Error("Wildcards select a whole group: namespace/group/*");
124
+ if (parts.length === 3 && opts.namespace !== undefined && opts.namespace !== parts[0])
125
+ throw new Error("--namespace conflicts with the host selector");
126
+ const namespace = parts.length === 3 ? parts[0] : await deps.namespace(opts.namespace);
127
+ const detail = await deps.status(selector, { namespace: parts.length === 3 ? undefined : namespace });
128
+ add(detail?.host, namespace, detail?.enrollments);
129
+ }
130
+ return hosts;
131
+ }
132
+ const nowIso = (deps) => new Date(deps.now()).toISOString();
133
+ function failure(base, code, error, extra = {}) {
134
+ return { ...base, ...extra, status: "failed", code, error };
135
+ }
136
+ const HOST_ERRORS = {
137
+ service_not_installed: "no nymph service from `dreamlake hosts enroll` was found for this host name",
138
+ nymph_binary_unmanaged: "the service binary is not a user-owned regular file in a writable directory (package-managed or root-owned); upgrade it with its installer",
139
+ nymph_binary_missing: "the service binary is missing",
140
+ upgrade_in_progress: "another upgrade, verification or rollback holds this host's lock",
141
+ restart_pending: "another restart became due on the host during this run; rerun to apply",
142
+ restart_schedule_failed: "the delayed restart could not be scheduled; the previous binary was restored",
143
+ installer_failed: "the nymph installer did not produce a binary",
144
+ installer_version_mismatch: "the installed binary reports a different version than requested",
145
+ rollback_receipt_mismatch: "the installed binary is not the one the selected upgrade installed; nothing was changed",
146
+ rollback_binary_corrupt: "the kept previous binary no longer matches its recorded checksum; nothing was changed",
147
+ receipt_not_found: "no upgrade receipt from this tool matches the installed binary",
148
+ systemd_run_required: "Linux upgrade needs systemd-run for the one-shot restart timer",
149
+ invalid_version: "invalid nymph version",
150
+ upgrade_failed: "host-side upgrade failed",
151
+ };
152
+ function hostError(reply) {
153
+ const code = typeof reply.result?.code === "string" ? reply.result.code : "no_result";
154
+ return { code, error: HOST_ERRORS[code] ?? (code === "no_result" ? `the host returned no result (exit ${reply.exitCode})` : `host-side check failed: ${code}`) };
155
+ }
156
+ /** One host: apply, wait out the delayed restart, then verify it happened exactly once. */
157
+ export async function processFleetHost(host, plan, deps) {
158
+ const base = { host: host.name, hostId: host.id, status: "failed", startedAt: nowIso(deps) };
159
+ const done = (outcome) => ({ ...outcome, finishedAt: nowIso(deps) });
160
+ if (!host.online)
161
+ return done({ ...base, status: "skipped", code: "offline", error: "no verified online enrollment; not contacted" });
162
+ const target = { selector: host.id, namespace: host.namespace, enrollment: plan.enrollment };
163
+ if (plan.dryRun) {
164
+ let reply;
165
+ try {
166
+ reply = await deps.exec(target, { action: "inspect", name: host.name, ...(plan.version ? { version: plan.version } : {}) }, 120);
167
+ }
168
+ catch (error) {
169
+ return done(failure(base, "transport", error instanceof Error ? error.message : "exec failed"));
170
+ }
171
+ if (reply.result?.status !== "inspected")
172
+ return done(failure(base, hostError(reply).code, hostError(reply).error));
173
+ const { status: _status, ...inspected } = reply.result;
174
+ return done({ ...base, status: "planned", version: inspected.version, plan: inspected });
175
+ }
176
+ const payload = { action: plan.action, name: host.name, restartDelaySeconds: plan.restartDelay,
177
+ ...(plan.version ? { version: plan.version } : {}), ...(plan.upgradeId ? { upgradeId: plan.upgradeId } : {}) };
178
+ let earlier;
179
+ // At most two rounds: a restart still due from an earlier run is verified first (never
180
+ // stacked), then the requested action is applied once.
181
+ for (let round = 0; round < 2; round++) {
182
+ let reply;
183
+ try {
184
+ reply = await deps.exec(target, payload, 600);
185
+ }
186
+ catch (error) {
187
+ return done(failure(base, "transport", error instanceof Error ? error.message : "exec failed"));
188
+ }
189
+ const applied = reply.result;
190
+ const extra = earlier ? { earlierRestart: earlier } : {};
191
+ if (applied?.status === "current") {
192
+ return done({ ...base, ...extra, status: "current", version: applied.version, pid: { before: applied.pid, after: applied.pid }, restarts: 0, leftoverJobsRemoved: applied.leftoverJobsRemoved });
193
+ }
194
+ if (applied?.code === "restart_pending" && UPGRADE_ID.test(applied.upgradeId) && round === 0) {
195
+ const previous = await verifyRestart(host, target, applied.upgradeId, plan, deps, { ...base, upgradeId: applied.upgradeId });
196
+ if (previous.status !== "verified") {
197
+ return done(failure(previous.outcome, "earlier_restart_unverified", `an earlier restart (${applied.upgradeId}) was still due and did not verify: ${previous.outcome.error}`));
198
+ }
199
+ earlier = { upgradeId: applied.upgradeId, status: "verified" };
200
+ continue;
201
+ }
202
+ if (applied?.status !== "restart_scheduled" || !UPGRADE_ID.test(applied.upgradeId)) {
203
+ const { code, error } = hostError(reply);
204
+ return done(failure({ ...base, ...extra }, code, error));
205
+ }
206
+ const pending = { ...base, ...extra, upgradeId: applied.upgradeId, version: applied.version, previousVersion: applied.previousVersion,
207
+ restart: applied.restart, leftoverJobsRemoved: applied.leftoverJobsRemoved };
208
+ deps.record({ type: "scheduled", ...pending });
209
+ const result = await verifyRestart(host, target, applied.upgradeId, plan, deps, pending);
210
+ return done(result.status === "verified" ? { ...result.outcome, status: plan.action === "rollback" ? "rolled_back" : "upgraded" } : result.outcome);
211
+ }
212
+ return done(failure(base, "restart_pending", "a restart is still pending on the host"));
213
+ }
214
+ /** Waits out the delayed restart, then verifies it, retrying while the relay reconnects. */
215
+ async function verifyRestart(host, target, upgradeId, plan, deps, pending) {
216
+ // The restart ends the session that scheduled it; reconnect only after it is due.
217
+ await deps.sleep((plan.restartDelay + 3) * 1000);
218
+ const deadline = deps.now() + plan.verifyTimeout * 1000;
219
+ let last = "verification did not run";
220
+ while (true) {
221
+ try {
222
+ const check = await deps.exec(target, { action: "verify", name: host.name, upgradeId, stableSeconds: plan.stableSeconds }, plan.stableSeconds + RESTART_GRACE + 60);
223
+ const result = check.result;
224
+ const observed = result?.status === "verified" || result?.status === "failed" ? {
225
+ version: result.version, pid: result.pid, restarts: result.restarts, failures: result.failures,
226
+ } : undefined;
227
+ if (result?.status === "verified")
228
+ return { status: "verified", outcome: { ...pending, ...observed } };
229
+ if (result?.status === "failed") {
230
+ return { status: "failed", outcome: failure(pending, "verification_failed", `restart verification failed: ${(result.failures ?? []).join(", ")}`, observed) };
231
+ }
232
+ // A missing result means the relay dropped (often nymph restarting); a busy lock clears.
233
+ if (result?.code && result.code !== "upgrade_in_progress") {
234
+ const e = hostError(check);
235
+ return { status: "failed", outcome: failure(pending, e.code, e.error) };
236
+ }
237
+ last = result?.code ? HOST_ERRORS[result.code] : `verification session ended without a result (exit ${check.exitCode})`;
238
+ }
239
+ catch (error) {
240
+ last = error instanceof Error ? error.message : "exec failed";
241
+ }
242
+ if (deps.now() >= deadline)
243
+ return { status: "failed", outcome: failure(pending, "verification_timeout", `${last}; rerun upgrade or inspect with --dry-run`) };
244
+ await deps.sleep(5000);
245
+ }
246
+ }
247
+ /** Bounded concurrency; stops starting hosts after maxFailures; one worker per host at a time. */
248
+ export async function runFleet(hosts, plan, deps) {
249
+ const ids = new Set(hosts.map(h => h.id));
250
+ if (ids.size !== hosts.length)
251
+ throw new Error("A host was selected twice");
252
+ const outcomes = new Array(hosts.length);
253
+ const active = new Set();
254
+ let next = 0, failures = 0;
255
+ const worker = async () => {
256
+ while (next < hosts.length && failures < plan.maxFailures) {
257
+ const index = next++;
258
+ const host = hosts[index];
259
+ if (active.has(host.id))
260
+ throw new Error("A host was scheduled twice concurrently");
261
+ active.add(host.id);
262
+ let outcome;
263
+ try {
264
+ outcome = await processFleetHost(host, plan, deps);
265
+ }
266
+ catch (error) {
267
+ outcome = { host: host.name, hostId: host.id, status: "failed", code: "internal", error: error instanceof Error ? error.message : String(error) };
268
+ }
269
+ finally {
270
+ active.delete(host.id);
271
+ }
272
+ if (outcome.status === "failed")
273
+ failures++;
274
+ outcomes[index] = outcome;
275
+ deps.record({ type: "host", ...outcome });
276
+ }
277
+ };
278
+ await Promise.all(Array.from({ length: Math.min(plan.concurrency, hosts.length) }, worker));
279
+ // Array.from, not map: map skips the holes left by hosts that were never started.
280
+ const final = Array.from(hosts, (h, i) => outcomes[i] ?? { host: h.name, hostId: h.id, status: "not_started" });
281
+ const counts = {};
282
+ for (const outcome of final)
283
+ counts[outcome.status] = (counts[outcome.status] ?? 0) + 1;
284
+ return { action: plan.action, ...(plan.version ? { version: plan.version } : {}), dryRun: plan.dryRun,
285
+ stoppedEarly: final.some(o => o.status === "not_started"), counts, hosts: final };
286
+ }
287
+ export function fleetSucceeded(report) {
288
+ return report.hosts.every(h => ["upgraded", "rolled_back", "current", "planned"].includes(h.status));
289
+ }
290
+ function cell(value) {
291
+ return value === undefined || value === null || value === "" ? "-" : String(value).replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
292
+ }
293
+ export function formatFleetReport(report) {
294
+ const rows = [["HOST", "STATUS", "VERSION", "PID", "RESTARTS", "NOTE"], ...report.hosts.map(h => [
295
+ cell(h.host), h.status, h.plan ? `${cell(h.version)} (plan: ${cell(h.plan.plan)})` : h.previousVersion && h.version ? `${h.previousVersion} -> ${h.version}` : cell(h.version),
296
+ h.pid ? `${cell(h.pid.before)} -> ${cell(h.pid.after)}` : "-", cell(h.restarts),
297
+ cell([h.error, h.leftoverJobsRemoved?.length ? `removed leftover job ${h.leftoverJobsRemoved.join(", ")}` : "",
298
+ h.plan && Array.isArray(h.plan.leftoverJobs) && h.plan.leftoverJobs.length ? `would remove leftover job ${h.plan.leftoverJobs.join(", ")}` : ""].filter(Boolean).join("; ")),
299
+ ])];
300
+ const widths = rows[0].map((_, i) => Math.max(...rows.map(r => r[i].length)));
301
+ const lines = rows.map(r => r.map((v, i) => i === r.length - 1 ? v : v.padEnd(widths[i])).join(" "));
302
+ lines.push(Object.entries(report.counts).map(([k, v]) => `${v} ${k}`).join(", ") + ".");
303
+ if (report.stoppedEarly)
304
+ lines.push("Stopped after reaching --max-failures; not_started hosts were not contacted.");
305
+ if (report.dryRun)
306
+ lines.push("Dry run: hosts were inspected read-only; nothing was changed.");
307
+ if (report.record)
308
+ lines.push(`Outcome record: ${report.record}`);
309
+ return lines.join("\n");
310
+ }
311
+ function recordFile(file) {
312
+ const target = file ?? path.join(homedir(), ".dreamlake/hosts-upgrades", `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}.jsonl`);
313
+ mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
314
+ return { path: target, write: entry => appendFileSync(target, JSON.stringify({ at: new Date().toISOString(), ...entry }) + "\n", { mode: 0o600 }) };
315
+ }
316
+ export async function runHostsUpgrade(selectors, opts, overrides = {}) {
317
+ let record;
318
+ try {
319
+ const plan = resolveFleetPlan(opts);
320
+ const hosts = await resolveFleetHosts(selectors, { all: opts.all, namespace: opts.namespace }, overrides.resolve);
321
+ if (plan.enrollment && hosts.length !== 1)
322
+ throw new Error("--enrollment applies to exactly one host");
323
+ if (plan.upgradeId && hosts.length !== 1)
324
+ throw new Error("--upgrade-id applies to exactly one host; upgrade IDs are per host");
325
+ record = recordFile(opts.record);
326
+ const deps = { exec: overrides.exec ?? execOverNymph, sleep: overrides.sleep ?? (ms => new Promise(r => setTimeout(r, ms))),
327
+ now: overrides.now ?? Date.now, record: overrides.record ?? record.write };
328
+ deps.record({ type: "run", action: plan.action, version: plan.version, dryRun: plan.dryRun, concurrency: plan.concurrency,
329
+ maxFailures: plan.maxFailures, hosts: hosts.map(h => ({ host: h.name, hostId: h.id, online: h.online })) });
330
+ const report = { ...await runFleet(hosts, plan, deps), record: record.path };
331
+ deps.record({ type: "summary", counts: report.counts, stoppedEarly: report.stoppedEarly });
332
+ console.log(opts.json ? JSON.stringify(report, null, 2) : formatFleetReport(report));
333
+ return fleetSucceeded(report) ? 0 : 1;
334
+ }
335
+ catch (error) {
336
+ const message = error instanceof Error ? error.message : String(error);
337
+ if (opts.json)
338
+ console.log(JSON.stringify({ status: "error", error: message, ...(record ? { record: record.path } : {}) }));
339
+ else
340
+ console.error(`Host ${opts.action}: ${message}`);
341
+ return 1;
342
+ }
343
+ }
344
+ export function registerHostUpgradeCommands(group) {
345
+ const common = (command) => command
346
+ .argument("[selectors...]", "host IDs, namespace/group/host, or quoted namespace/group/*")
347
+ .option("--all", "every host in --namespace (offline hosts are reported as skipped)")
348
+ .option("--namespace <namespace>", "namespace for --all and host IDs (default: signed-in personal namespace)")
349
+ .option("--enrollment <id>", "exact SSH enrollment when one host has several")
350
+ .option("--dry-run", "inspect each host read-only (version, pending restart, leftover jobs); change nothing")
351
+ .option("--concurrency <n>", "hosts processed at once, 1–16 (default 1)")
352
+ .option("--max-failures <n>", "stop starting new hosts after this many failures (default 1)")
353
+ .option("--restart-delay <seconds>", "delay before the one-shot nymph restart, 5–300 (default 15)")
354
+ .option("--stable-seconds <seconds>", "new nymph PID must stay unchanged this long, 5–300 (default 15)")
355
+ .option("--verify-timeout <seconds>", "time allowed to reconnect and verify after the restart (default 300)")
356
+ .option("--record <path>", "JSON Lines outcome record (default ~/.dreamlake/hosts-upgrades/<run>.jsonl)")
357
+ .option("--json", "emit the fleet report as JSON");
358
+ common(group.command("upgrade")
359
+ .description("upgrade nymph on enrolled hosts over the nymph relay with one verified delayed restart"))
360
+ .option("--nymph-version <version>", "exact nymph release to install, such as 0.1.32 (required)")
361
+ .action(async (selectors, opts) => { process.exitCode = await runHostsUpgrade(selectors, { ...opts, action: "upgrade" }); });
362
+ common(group.command("rollback")
363
+ .description("restore the nymph binary kept by the last upgrade and verify one delayed restart"))
364
+ .option("--upgrade-id <id>", "roll back this YYYYMMDD-NNN host receipt instead of the latest (one host only)")
365
+ .action(async (selectors, opts) => { process.exitCode = await runHostsUpgrade(selectors, { ...opts, action: "rollback" }); });
366
+ }
@@ -1 +1 @@
1
- export declare const VERSION = "0.95.0";
1
+ export declare const VERSION = "0.96.0";
@@ -6,4 +6,4 @@
6
6
  // value means a binary that re-installs the same version forever.
7
7
  //
8
8
  // Editing this by hand does nothing for a release; bump package.json.
9
- export const VERSION = "0.95.0";
9
+ export const VERSION = "0.96.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dreamlake/dreamlake-cli",
3
- "version": "0.95.0",
3
+ "version": "0.96.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/dreamlake-ai/dreamlake-cli.git"
@@ -35,13 +35,13 @@
35
35
  "node": ">=18"
36
36
  },
37
37
  "optionalDependencies": {
38
- "@dreamlake/dreamlake-cli-darwin-arm64": "0.95.0",
39
- "@dreamlake/dreamlake-cli-darwin-x64": "0.95.0",
40
- "@dreamlake/dreamlake-cli-linux-x64": "0.95.0",
41
- "@dreamlake/dreamlake-cli-linux-arm64": "0.95.0",
42
- "@dreamlake/dreamlake-cli-linux-x64-musl": "0.95.0",
43
- "@dreamlake/dreamlake-cli-linux-arm64-musl": "0.95.0",
44
- "@dreamlake/dreamlake-cli-win32-x64": "0.95.0",
45
- "@dreamlake/dreamlake-cli-win32-arm64": "0.95.0"
38
+ "@dreamlake/dreamlake-cli-darwin-arm64": "0.96.0",
39
+ "@dreamlake/dreamlake-cli-darwin-x64": "0.96.0",
40
+ "@dreamlake/dreamlake-cli-linux-x64": "0.96.0",
41
+ "@dreamlake/dreamlake-cli-linux-arm64": "0.96.0",
42
+ "@dreamlake/dreamlake-cli-linux-x64-musl": "0.96.0",
43
+ "@dreamlake/dreamlake-cli-linux-arm64-musl": "0.96.0",
44
+ "@dreamlake/dreamlake-cli-win32-x64": "0.96.0",
45
+ "@dreamlake/dreamlake-cli-win32-arm64": "0.96.0"
46
46
  }
47
47
  }