better-dsh 0.3.0 → 0.3.1-b

package/lib/kernel-env-x_WkG6Fr.js

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+
+//#region src/kernel-env.ts
+const exec = promisify(execFile);
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+function venvPython(dir) {
+	return join(dir, process.platform === "win32" ? "Scripts/python.exe" : "bin/python");
+}
+function activate(dir) {
+	const bin = dirname(venvPython(dir));
+	return {
+		...process.env,
+		VIRTUAL_ENV: dir,
+		PATH: [bin, process.env.PATH].filter(Boolean).join(delimiter)
+	};
+}
+function explicitPath(python, cwd) {
+	const expanded = python === "~" ? homedir() : python.startsWith("~/") ? join(homedir(), python.slice(2)) : python;
+	return isAbsolute(expanded) || /[/\\]/.test(expanded) ? resolve(cwd, expanded) : expanded;
+}
+async function probe(python, env, cwd) {
+	const { stdout } = await exec(python, ["-c", "import ast, asyncio, json, sys; assert sys.version_info >= (3, 9), \"Packaged dill checkpoints require Python >=3.9\"; print(json.dumps({\"python\": sys.executable, \"version\": sys.version.split()[0]}))"], {
+		timeout: 15e3,
+		cwd,
+		env: {
+			...env,
+			PYTHONDONTWRITEBYTECODE: "1"
+		}
+	});
+	const result = JSON.parse(stdout.trim());
+	if (!isAbsolute(result.python) || !result.version) throw new Error("Interpreter did not report an absolute executable and version");
+	return {
+		...result,
+		env
+	};
+}
+async function resolveKernelEnv(options = {}) {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	if (options.python) {
+		const python = explicitPath(options.python, cwd);
+		const venv$1 = dirname(dirname(python));
+		const env = isAbsolute(python) && existsSync(join(venv$1, "pyvenv.cfg")) ? activate(venv$1) : { ...process.env };
+		try {
+			return await probe(python, env, cwd);
+		} catch (error) {
+			throw new Error(`Could not use configured Python ${JSON.stringify(options.python)}: ${error instanceof Error ? error.message : String(error)}. Configure python with a working Python >=3.9 interpreter.`);
+		}
+	}
+	const active = process.env.VIRTUAL_ENV || process.env.CONDA_PREFIX;
+	const project = [join(cwd, ".venv"), join(cwd, "venv")].find(existsSync);
+	const venv = active || project;
+	const candidates = [];
+	if (venv && existsSync(venvPython(venv))) candidates.push({
+		python: venvPython(venv),
+		env: activate(venv)
+	});
+	for (const python of ["python3", "python"]) candidates.push({
+		python,
+		env: { ...process.env }
+	});
+	const failures = [];
+	for (const candidate of candidates) try {
+		return await probe(candidate.python, candidate.env, cwd);
+	} catch (error) {
+		failures.push(`${candidate.python}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	throw new Error(`No working Python interpreter found. Tried: ${failures.join("; ")}. Install Python >=3.9 on PATH (python3 or python), or configure python with an existing interpreter. Better does not install Python automatically.`);
+}
+
+//#endregion
+export { resolveKernelEnv as n, PACKAGE_ROOT as t };

package/lib/kernel-env.d.ts

@@ -1,80 +1,16 @@
 //#region src/kernel-env.d.ts
-/**
- * Kernel environment resolution and provisioning.
- *
- * The runtime OWNS the interpreter it spawns: it never trusts a bare
- * `python3` on the PATH, because that interpreter may lack `ipykernel`
- * (hard failure — the kernel cannot start) or `dill` (snapshot capability —
- * silently degrading to no snapshots). Instead it resolves one of two
- * environments:
- *
- * - **Explicit** — `config.python` names a real interpreter (a path, or any
- *   name other than the bare-`python3` sentinel the default/patch produce).
- *   It is probed, and a missing `ipykernel` is a loud error while a missing
- *   `dill` is a loud warning (snapshots disabled).
- * - **Managed** — no explicit interpreter: the runtime provisions a venv
- *   UNDER THE PACKAGE (`<packageRoot>/.venv-kernel`, or `config.kernelEnvDir`)
- *   with `ipykernel` + `dill`, installing it on first use when
- *   `config.kernelAutoInstall` is on. The venv lives beside the package, NOT
- *   in `/tmp` (the pre-v0.1.9 dangling-symlink failure mode), so it survives
- *   the host's tmp reaper and the process restart.
- *
- * Provisioning uses `uv` when available (fast, can fetch the pinned CPython
- * version), falling back to `python3 -m venv` + `ensurepip`. It is idempotent:
- * a complete venv is reused untouched; a partial one is repaired.
- * @module dashr/kernel-env
- */
-/** The installed package root (where `lib/` and `src/` live): the default home of the managed venv. */
 declare const PACKAGE_ROOT: string;
-/** The config value meaning "no explicit interpreter — auto-manage a venv". */
-declare const AUTO_PYTHON_SENTINEL = "python3";
-/** Preferred CPython version for a managed venv. */
-declare const DEFAULT_KERNEL_PYTHON_VERSION = "3.11";
-/** Pinned, tested `ipykernel` version (2026-09-02 tested value; upgrade = explicit change + regression). */
-declare const IPYKERNEL_VERSION = "7.3.0";
-/** Pinned, tested `dill` version. */
-declare const DILL_VERSION = "0.4.1";
 interface KernelEnv {
-  /** Absolute path to the interpreter to spawn (`-m ipykernel_launcher`). */
   python: string;
-  /** True when this runtime provisioned a venv (vs an explicit interpreter). */
-  managed: boolean;
-  /** The managed venv root, when {@link managed}. */
-  venvDir: string | undefined;
-  /** True when `dill` is importable — snapshot capability is available. */
-  dill: boolean;
-  /** True when `ipykernel` is importable (a hard requirement). */
-  ipykernel: boolean;
-  /** The interpreter's reported version, e.g. `3.11.15`. */
+  env: NodeJS.ProcessEnv;
   version: string;
 }
 interface ResolveKernelEnvOptions {
-  /** `config.python`; the bare sentinel (or absent) selects a managed venv. */
+  /** An explicit path or executable name bypasses automatic discovery. */
   python?: string;
-  /** Managed venv directory; defaults to `<packageRoot>/.venv-kernel`. */
-  venvDir?: string;
-  /** Preferred CPython version for the managed venv. */
-  pythonVersion?: string;
-  /** Provision the managed venv when missing/incomplete (default true). */
-  autoInstall?: boolean;
-  /** Logger callback (info on provisioning, warn on degraded snapshot). */
-  log?: (level: 'info' | 'warn', message: string) => void;
+  /** Session workspace, used for existing project environments and relative paths. */
+  cwd?: string;
 }
-/** Tool-cache env for uv: caches live NEXT TO the venv (plugin territory), so a read-only home can never block provisioning. */
-declare function uvToolEnv(venvDir: string): NodeJS.ProcessEnv;
-/** uv venv arguments (pure; unit-tested). */
-declare function uvVenvArgs(venvDir: string, pythonVersion: string): string[];
-/** python3 -m venv fallback arguments (pure; cache-free by construction). */
-declare function venvFallbackArgs(venvDir: string): string[];
-/** uv pip install arguments with pinned versions (pure; unit-tested). */
-declare function uvInstallArgs(python: string): string[];
-/** pip install arguments with pinned versions for the venv interpreter (pure). */
-declare function pipInstallArgs(): string[];
-/**
- * Resolve the kernel interpreter, provisioning a managed venv when no
- * explicit interpreter is configured. Throws when the resolved interpreter
- * cannot run `ipykernel`; a missing `dill` only disables snapshots (warned).
- */
 declare function resolveKernelEnv(options?: ResolveKernelEnvOptions): Promise<KernelEnv>;
 //#endregion
-export { AUTO_PYTHON_SENTINEL, DEFAULT_KERNEL_PYTHON_VERSION, DILL_VERSION, IPYKERNEL_VERSION, KernelEnv, PACKAGE_ROOT, ResolveKernelEnvOptions, pipInstallArgs, resolveKernelEnv, uvInstallArgs, uvToolEnv, uvVenvArgs, venvFallbackArgs };
+export { KernelEnv, PACKAGE_ROOT, ResolveKernelEnvOptions, resolveKernelEnv };

package/lib/kernel-env.js

@@ -1,3 +1,3 @@
-import { a as PACKAGE_ROOT, c as uvInstallArgs, d as venvFallbackArgs, i as IPYKERNEL_VERSION, l as uvToolEnv, n as DEFAULT_KERNEL_PYTHON_VERSION, o as pipInstallArgs, r as DILL_VERSION, s as resolveKernelEnv, t as AUTO_PYTHON_SENTINEL, u as uvVenvArgs } from "./kernel-env-D8UOWeji.js";
+import { n as resolveKernelEnv, t as PACKAGE_ROOT } from "./kernel-env-x_WkG6Fr.js";
 
-export { AUTO_PYTHON_SENTINEL, DEFAULT_KERNEL_PYTHON_VERSION, DILL_VERSION, IPYKERNEL_VERSION, PACKAGE_ROOT, pipInstallArgs, resolveKernelEnv, uvInstallArgs, uvToolEnv, uvVenvArgs, venvFallbackArgs };
+export { PACKAGE_ROOT, resolveKernelEnv };

package/lib/{lsp-server-registry-BXvUTBY7.js → lsp-server-registry-BcdkHROD.js}

@@ -1,3 +1,3 @@
-import { a as primaryServerForFile, c as serversForFile, i as installServer, n as findWorkspaceRoot, o as resolveCommandPath, r as installHintFor, s as serverByName, t as clearCommandProbeCache } from "./lsp-server-registry-CH9WNFFt.js";
+import { a as primaryServerForFile, c as serversForFile, i as installServer, n as findWorkspaceRoot, o as resolveCommandPath, r as installHintFor, s as serverByName, t as clearCommandProbeCache } from "./lsp-server-registry-D4VLs1Sm.js";
 
 export { clearCommandProbeCache, findWorkspaceRoot, installHintFor, installServer, primaryServerForFile, resolveCommandPath, serverByName, serversForFile };

package/lib/{lsp-server-registry-CH9WNFFt.js → lsp-server-registry-D4VLs1Sm.js}

@@ -1,5 +1,5 @@
-import * as path$1 from "node:path";
 import { accessSync, constants, existsSync, readdirSync } from "node:fs";
+import * as path$1 from "node:path";
 
 //#region src/devices/lsp/defaults.json
 var defaults_default = {

package/lib/{main-BQeFrBM1.js → main-taSMz1KX.js}

@@ -1,3 +1,3 @@
-import { _ as Browser, a as TimeoutError, b as ChromeReleaseChannel, c as computeSystemExecutablePath, d as InstalledBrowser, f as detectBrowserPlatform, g as resolveDefaultUserDataDir, h as resolveBuildId, i as Process, l as launch, m as getVersionComparator, n as uninstall, o as WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX, p as createProfile, r as CDP_WEBSOCKET_ENDPOINT_REGEX, s as computeExecutablePath, t as getInstalledBrowsers, u as Cache, v as BrowserPlatform, y as BrowserTag } from "./main-CupOhMp5.js";
+import { _ as Browser, a as TimeoutError, b as ChromeReleaseChannel, c as computeSystemExecutablePath, d as InstalledBrowser, f as detectBrowserPlatform, g as resolveDefaultUserDataDir, h as resolveBuildId, i as Process, l as launch, m as getVersionComparator, n as uninstall, o as WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX, p as createProfile, r as CDP_WEBSOCKET_ENDPOINT_REGEX, s as computeExecutablePath, t as getInstalledBrowsers, u as Cache, v as BrowserPlatform, y as BrowserTag } from "./main-uqGqYYnA.js";
 
 export { Browser, BrowserPlatform, BrowserTag, CDP_WEBSOCKET_ENDPOINT_REGEX, Cache, ChromeReleaseChannel, InstalledBrowser, Process, TimeoutError, WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX, computeExecutablePath, computeSystemExecutablePath, createProfile, detectBrowserPlatform, getInstalledBrowsers, getVersionComparator, launch, resolveBuildId, resolveDefaultUserDataDir, uninstall };

package/lib/{main-CupOhMp5.js → main-uqGqYYnA.js}

@@ -1,14 +1,16 @@
 import { createHash } from "node:crypto";
-import childProcess, { execFile, execSync, spawn, spawnSync } from "node:child_process";
-import { mkdir, readdir, unlink } from "node:fs/promises";
+import fs, { accessSync, constants, createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+import childProcess, { execFile, execSync, spawn, spawnSync } from "node:child_process";
+import * as http from "node:http";
+import readline from "node:readline";
 import { URL as URL$1, urlToHttpOptions } from "node:url";
-import fs, { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import os from "node:os";
-import readline from "node:readline";
 import { debuglog, promisify } from "node:util";
+import { mkdir, readdir, symlink, unlink } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { Writable } from "node:stream";
 import { EventEmitter } from "node:events";
-import * as http from "node:http";
 import * as https from "node:https";
 
 //#region node_modules/@puppeteer/browsers/lib/browser-data/types.js

package/lib/omp-python/DILL-LICENSE

@@ -0,0 +1,35 @@
+Copyright (c) 2004-2016 California Institute of Technology.
+Copyright (c) 2016-2026 The Uncertainty Quantification Foundation.
+All rights reserved.
+
+This software is available subject to the conditions and terms laid
+out below. By downloading and using this software you are agreeing
+to the following conditions.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+    - Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    - Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+    - Neither the names of the copyright holders nor the names of any of
+      the contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

package/lib/omp-python/OMP-LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+Copyright (c) 2025-2026 Can Bölük
+Copyright (c) 2026 Stencil Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/omp-python/better_snapshot.py

@@ -0,0 +1,391 @@
+"""Best-effort checkpoints for the owned OMP namespace; dill 0.4.1 adapter.
+
+No cell history is stored/replayed. Pickling user objects is not a sandbox:
+reducers may execute arbitrary code. Host deadlines bound helper execution.
+"""
+import _thread
+import asyncio
+import dis
+import functools
+import hashlib
+import io
+import json
+import os
+import platform
+import re
+import socket
+import sqlite3
+import subprocess
+import sys
+import threading
+import time
+import types
+import uuid
+
+# Select the unchanged packaged implementation before ANY user cell can import dill.
+_VENDOR = os.path.join(os.path.dirname(__file__), 'vendor')
+sys.path.insert(0, _VENDOR)
+import dill
+if dill.__version__ != '0.4.1' or os.path.realpath(dill.__file__) != os.path.realpath(os.path.join(_VENDOR, 'dill', '__init__.py')):
+    raise RuntimeError('Better requires its packaged dill 0.4.1')
+
+_DIRECTORY = None
+_CAP = None
+_TIMEOUT = 30.0
+_FORMAT = 2
+_RESOURCES = (io.IOBase, _thread.LockType, type(threading.RLock()), socket.socket,
+    subprocess.Popen, threading.Thread, sqlite3.Connection, sqlite3.Cursor,
+    asyncio.Future, asyncio.AbstractEventLoop, types.GeneratorType,
+    types.CoroutineType, types.AsyncGeneratorType)
+_PRIMITIVES = (str, bytes, int, float, bool, type(None))
+
+
+class UnsupportedResource(Exception):
+    pass
+
+
+class SizeCap(Exception):
+    pass
+
+
+class NamespaceProxy:
+    pass
+
+
+def _proxy(ns):
+    proxy = NamespaceProxy()
+    proxy.__dict__ = ns
+    return proxy
+
+
+def configure(directory, cap, timeout_ms):
+    global _DIRECTORY, _CAP, _TIMEOUT
+    _DIRECTORY = os.path.abspath(directory) if directory else None
+    _CAP = cap
+    _TIMEOUT = timeout_ms / 1000.0 * 0.9
+
+
+def clear():
+    """Delete only our fixed manifest and generation files, including orphans."""
+    if _DIRECTORY and os.path.islink(_DIRECTORY):
+        raise ValueError('checkpoint directory cannot be a symlink')
+    if not _DIRECTORY or not os.path.isdir(_DIRECTORY):
+        return
+    for name in os.listdir(_DIRECTORY):
+        if name == 'manifest.json' or re.fullmatch(r'(state-[0-9a-f]{32}\.dill|\.checkpoint-[0-9a-f]{32}\.tmp)', name):
+            os.unlink(os.path.join(_DIRECTORY, name))
+
+
+def _paths(payload_path, manifest_path):
+    if not _DIRECTORY or os.path.abspath(manifest_path) != os.path.join(_DIRECTORY, 'manifest.json') or os.path.abspath(payload_path) != os.path.join(_DIRECTORY, 'state.dill'):
+        raise ValueError('checkpoint paths are not the configured session directory')
+    os.makedirs(_DIRECTORY, mode=0o700, exist_ok=True)
+    if os.path.islink(_DIRECTORY):
+        raise ValueError('checkpoint directory cannot be a symlink')
+    if os.path.islink(manifest_path):
+        raise ValueError('checkpoint manifest cannot be a symlink')
+    os.chmod(_DIRECTORY, 0o700)
+
+
+def _environment():
+    return dict(pythonVersion=platform.python_version(), implementation=platform.python_implementation(),
+        interpreter=os.path.realpath(sys.executable), venvPath=sys.prefix,
+        environmentHash=hashlib.sha256(json.dumps([sys.prefix, sys.base_prefix, sys.path], sort_keys=True).encode()).hexdigest(),
+        dillVersion=dill.__version__, protocol=4, skills=[])
+
+
+def _guard(ns):
+    import better_support
+    owned = [sys.modules['__main__'], sys.modules['better_support'], sys.modules[__name__]]
+    owned.extend(better_support.owned_objects())
+    denied = {id(value) for value in owned if not isinstance(value, _PRIMITIVES)}
+    def guard(value):
+        if id(value) in denied or (isinstance(value, (types.FunctionType, type)) and getattr(value, '__module__', None) in ('better_support', 'better_snapshot')) or type(value).__module__ == 'better_support':
+            raise UnsupportedResource('captured Better/runner binding')
+        if isinstance(value, _RESOURCES):
+            raise UnsupportedResource('unsupported live resource ' + type(value).__name__)
+        return None
+    return guard
+
+
+class CappedBuffer(io.BytesIO):
+    def __init__(self, cap):
+        super().__init__()
+        self.cap = cap
+    def write(self, value):
+        if self.tell() + len(value) > self.cap:
+            raise SizeCap('serialized graph exceeds snapshotSizeCapBytes')
+        return super().write(value)
+
+
+def _encode(ns, values, cap, guard):
+    output = CappedBuffer(cap)
+    # Exact Pickler: subclassing disables pinned dill's main-module logic.
+    pickler = dill.Pickler(output, protocol=4, recurse=False, byref=False)
+    pickler._main = _proxy(ns)
+    pickler._original_main = pickler._main
+    pickler._main_modified = True
+    pickler.persistent_id = guard
+    pickler.dump(values)
+    return output.getvalue()
+
+
+def _decode(ns, payload):
+    unpickler = dill.Unpickler(io.BytesIO(payload))
+    unpickler._main = _proxy(ns)
+    unpickler._ignore = True
+    return unpickler.load()
+
+
+def _dependencies(root, ns):
+    """Bounded static global scan; dynamic eval/globals lookups remain best effort."""
+    found, seen = set(), set()
+    def walk(value):
+        if id(value) in seen or isinstance(value, _PRIMITIVES):
+            return
+        seen.add(id(value))
+        if len(seen) > 10000:
+            raise UnsupportedResource('dependency graph exceeds inspection budget')
+        if isinstance(value, types.FunctionType):
+            if value.__globals__ is ns:
+                def code_names(code):
+                    for op in dis.get_instructions(code):
+                        if op.opname in ('LOAD_GLOBAL', 'LOAD_NAME'):
+                            found.add(op.argval)
+                    for item in code.co_consts:
+                        if isinstance(item, types.CodeType): code_names(item)
+                code_names(value.__code__)
+            walk(value.__defaults__)
+            walk(value.__kwdefaults__)
+            for cell in value.__closure__ or ():
+                try: walk(cell.cell_contents)
+                except ValueError: pass
+        elif isinstance(value, functools.partial):
+            walk(value.func); walk(value.args); walk(value.keywords); walk(vars(value))
+        elif isinstance(value, (staticmethod, classmethod)):
+            walk(value.__func__)
+        elif isinstance(value, property):
+            walk(value.fget); walk(value.fset); walk(value.fdel)
+        elif isinstance(value, types.MethodType):
+            walk(value.__func__); walk(value.__self__)
+        elif isinstance(value, dict):
+            for key, item in value.items(): walk(key); walk(item)
+        elif isinstance(value, (tuple, list, set, frozenset)):
+            for item in value: walk(item)
+        elif isinstance(value, type):
+            if value.__module__ == ns.get('__name__'):
+                for item in vars(value).values(): walk(item)
+                for base in value.__bases__: walk(base)
+        elif not isinstance(value, types.ModuleType) and type(value).__module__ == ns.get('__name__'):
+            walk(type(value))
+            if hasattr(value, '__dict__'): walk(vars(value))
+            # Scan descriptors across the MRO, including inherited/mangled slots.
+            for owner in type(value).__mro__:
+                for descriptor in vars(owner).values():
+                    if isinstance(descriptor, types.MemberDescriptorType):
+                        try: walk(descriptor.__get__(value, type(value)))
+                        except AttributeError: pass  # uninitialized slot
+    walk(root)
+    return found
+
+
+def _write_new(path, data):
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(fd, 'wb') as output:
+        output.write(data)
+        output.flush()
+        os.fsync(output.fileno())
+
+
+def _emit(sentinel, result):
+    print(sentinel + json.dumps(result, ensure_ascii=True))
+
+
+def _retained_payloads(manifest_path):
+    try:
+        with open(manifest_path, encoding='utf-8') as source:
+            manifest = json.load(source)
+    except (FileNotFoundError, ValueError):
+        return set(), None
+    if not isinstance(manifest, dict):
+        return set(), None
+    current = manifest.get('payload')
+    names = (current, manifest.get('previousPayload'))
+    retained = {name for name in names if isinstance(name, str) and re.fullmatch(r'state-[0-9a-f]{32}\.dill', name)}
+    return retained, current if isinstance(current, str) and current in retained else None
+
+
+def _scavenge(retained):
+    for name in os.listdir(_DIRECTORY):
+        if name not in retained and re.fullmatch(r'(state-[0-9a-f]{32}\.dill|\.checkpoint-[0-9a-f]{32}\.tmp)', name):
+            os.unlink(os.path.join(_DIRECTORY, name))
+
+
+def save(ns, payload_path, manifest_path, spec_json, sentinel):
+    attempt_paths, committed, result = [], False, None
+    payload_name, manifest, retained = None, None, set()
+    try:
+        _paths(payload_path, manifest_path)
+        retained, previous = _retained_payloads(manifest_path)
+        _scavenge(retained)  # collect killed-writer artifacts even if this attempt fails
+        deadline = time.monotonic() + _TIMEOUT
+        def check_deadline():
+            if time.monotonic() >= deadline:
+                raise TimeoutError('checkpoint deadline exceeded; previous generation retained')
+        spec = json.loads(spec_json)
+        cap = min(spec['sizeCapBytes'], _CAP)
+        import better_support
+        candidates = better_support.user_namespace(ns)
+        guard = _guard(ns)
+        kept, omitted, dependencies = {}, {}, {}
+        for name, value in candidates.items():
+            check_deadline()
+            try:
+                _encode(ns, {name: value}, cap, guard)
+                dependencies[name] = _dependencies(value, ns)
+                kept[name] = value
+            except SizeCap:
+                raise
+            except Exception as error:
+                omitted[name] = type(error).__name__ + ': ' + str(error)
+        changed = True
+        while changed:
+            changed = False
+            for name in list(kept):
+                missing = dependencies[name].intersection(omitted)
+                if missing:
+                    omitted[name] = 'depends on omitted globals: ' + ', '.join(sorted(missing))
+                    del kept[name]
+                    changed = True
+        check_deadline()
+        payload = _encode(ns, kept, cap, guard)
+        # Verify the FINAL shared graph, never independently reconstruct values.
+        trial_ns = dict(ns)
+        trial = _decode(trial_ns, payload)
+        if not isinstance(trial, dict) or set(trial) != set(kept):
+            raise ValueError('final graph round-trip changed admitted names')
+        trial_ns.update(trial)
+        groups = {}
+        for name, value in kept.items():
+            if id(value) in groups and trial[name] is not trial[groups[id(value)]]:
+                raise ValueError('final graph round-trip lost shared root identity')
+            groups[id(value)] = name
+        token = uuid.uuid4().hex
+        payload_name = 'state-' + token + '.dill'
+        manifest = dict(_environment(), snapshotFormat=_FORMAT, turn=spec['turn'],
+            payload=payload_name, previousPayload=previous, sizeBytes=len(payload), sha256=hashlib.sha256(payload).hexdigest(),
+            names=sorted(kept), dependencies={name: sorted(dependencies[name]) for name in kept},
+            bindingNames=sorted(better_support.injected_names()), omitted=omitted, coverage='partial' if omitted else 'best-effort',
+            skipped=False, limitations=['Dynamic globals/eval and arbitrary extension resources cannot be exhaustively inspected.'])
+        payload_file = os.path.join(_DIRECTORY, payload_name)
+        attempt_paths.append(payload_file)
+        _write_new(payload_file, payload)
+        temp = os.path.join(_DIRECTORY, '.checkpoint-' + token + '.tmp')
+        attempt_paths.append(temp)
+        _write_new(temp, json.dumps(manifest, sort_keys=True).encode())
+        # Sole commit point. Cleanup must never remove this payload afterwards.
+        check_deadline()
+        os.replace(temp, manifest_path)
+        committed = True
+        result = dict(kind='ok', sizeBytes=len(payload), names=manifest['names'], omitted=omitted, turn=spec['turn'])
+        warnings = []
+        if os.name == 'posix':
+            try:
+                fd = os.open(_DIRECTORY, os.O_RDONLY)
+                try: os.fsync(fd)
+                finally: os.close(fd)
+            except OSError as error:
+                warnings.append('directory fsync failed: ' + str(error))
+        try:
+            _scavenge({payload_name, previous})
+        except OSError as error:
+            warnings.append('stale artifact cleanup failed: ' + str(error))
+        if warnings:
+            result['warning'] = 'checkpoint committed; ' + '; '.join(warnings)
+    except SizeCap as error:
+        result = dict(kind='skipped', reason=str(error), capBytes=_CAP)
+    except Exception as error:
+        reason = type(error).__name__ + ': ' + str(error)
+        if payload_name is not None and not committed:
+            try:
+                _, pointed = _retained_payloads(manifest_path)
+                committed = pointed == payload_name
+            except OSError:
+                pass
+        if committed:
+            result = dict(kind='ok', sizeBytes=len(payload), names=manifest['names'], omitted=omitted, turn=spec['turn'])
+            result['warning'] = 'checkpoint committed; postcommit finalization failed: ' + reason
+        else:
+            result = dict(kind='failed', reason=reason)
+    finally:
+        if not committed and attempt_paths:
+            # A signal/error can arrive immediately after replace, before the
+            # local flag changes. The pointer is authoritative for deletion.
+            try:
+                latest, _ = _retained_payloads(manifest_path)
+                retained.update(latest)
+            except OSError:
+                # Cannot prove non-commit: leave recognized artifacts for the
+                # next save's pre-write scavenger rather than risk data loss.
+                retained.update(os.path.basename(path) for path in attempt_paths)
+            for path in attempt_paths:
+                if os.path.basename(path) in retained:
+                    continue
+                try: os.unlink(path)
+                except FileNotFoundError: pass
+                except OSError as error:
+                    if result is not None:
+                        result['reason'] += '; uncommitted artifact cleanup failed: ' + str(error)
+    if result is not None:
+        _emit(sentinel, result)
+
+
+def restore(ns, payload_path, manifest_path, sentinel, bindings_json):
+    try:
+        _paths(payload_path, manifest_path)
+        if os.path.getsize(manifest_path) > 1048576:
+            raise ValueError('manifest exceeds metadata cap')
+        with open(manifest_path, encoding='utf-8') as source:
+            manifest = json.load(source)
+        if not isinstance(manifest, dict) or manifest.get('snapshotFormat') != _FORMAT:
+            raise ValueError('unsupported snapshot format')
+        for key, value in _environment().items():
+            if manifest.get(key) != value: raise ValueError('checkpoint environment mismatch: ' + key)
+        name = manifest.get('payload', '')
+        if not isinstance(name, str) or not re.fullmatch(r'state-[0-9a-f]{32}\.dill', name):
+            raise ValueError('invalid owned payload name')
+        names = manifest.get('names')
+        import better_support
+        if not isinstance(names, list) or any(not isinstance(n, str) or n.startswith('__omp_') or n in ('__name__', '__builtins__', '__doc__') for n in names):
+            raise ValueError('invalid checkpoint namespace names')
+        turn = manifest.get('turn')
+        if not isinstance(turn, int) or isinstance(turn, bool) or turn < 0:
+            raise ValueError('invalid checkpoint turn')
+        path = os.path.join(_DIRECTORY, name)
+        size = os.path.getsize(path)
+        if os.path.islink(path) or size != manifest.get('sizeBytes') or size > _CAP:
+            raise ValueError('payload size/cap/path validation failed')
+        with open(path, 'rb') as source: payload = source.read(_CAP + 1)
+        if hashlib.sha256(payload).hexdigest() != manifest.get('sha256'):
+            raise ValueError('payload integrity hash mismatch')
+        values = _decode(ns, payload)
+        if not isinstance(values, dict) or sorted(values) != sorted(names):
+            raise ValueError('payload namespace differs from manifest')
+        omitted = dict(manifest.get('omitted', {}))
+        unavailable = set(manifest.get('bindingNames', [])) - set(json.loads(bindings_json))
+        dependencies = manifest.get('dependencies', {})
+        changed = True
+        while changed:
+            changed = False
+            for root in list(values):
+                missing_bindings = set(dependencies.get(root, [])).intersection(unavailable)
+                missing_state = set(dependencies.get(root, [])).intersection(omitted)
+                if missing_bindings or missing_state:
+                    omitted[root] = ('missing current host binding: ' + ', '.join(sorted(missing_bindings))) if missing_bindings else ('depends on omitted globals: ' + ', '.join(sorted(missing_state)))
+                    del values[root]
+                    changed = True
+        ns.update(values)
+        _emit(sentinel, dict(kind='restored', count=len(values), turn=turn, names=names,
+            omitted=omitted))
+    except Exception as error:
+        _emit(sentinel, dict(kind='degraded', reason=type(error).__name__ + ': ' + str(error)))