better-dsh 0.3.0 → 0.3.1-a

package/README.md

@@ -1,196 +1,71 @@
-> Part of [Super D](../README.md). This is the independently installable `better-dsh` package. Super Dash embeds the same local build and registers it as a separate native Plugin Manager row, with its own enable/disable switch; both versions advance together toward 0.3.0. Active source is this directory, with shared specifications and references under root `docs/`.
-
-# Better Dsh — Dashr
-
-DASHR is a persistent-kernel REPL for the DeepSeek Harness (dsh): a
-**stateful `ctx.replRuntime` provider** (one persistent IPython kernel
-subprocess **per session**, the run's `principal`, held in a map inside the
-one service instance per mount). Each `run()` is one cell on the calling
-session's kernel; variables, imports, and definitions assigned in run N
-survive into run N+1 — *state codification* (blueprint §1.1 channel ②),
-deliberately NOT the per-run isolation a one-shot execution backend
-provides — and two sessions sharing one service instance never see each
-other's variables.
-
-Naming (v0.1.5 layer model): the runtime class is **`DashrRuntime`** — the
-standing-mount-layer component (one instance per mount holding the
-cross-session kernel map), and therefore the de facto daemon while the
-profile-level `DashrDaemon` concept stays an empty shell; the session layer
-is the ipykernel subprocess itself, a pure interpreter with no harness
-awareness.
-
-The presentation half — the `eval` transport tool, the Python SDK renderer,
-and the tool→binding bridge — lives in the SAME package (merged in v0.1.8;
-the pre-merge `dsh-rlm-mode`/`dashr-presentation` sibling split is gone).
-The runtime registers the service key `replRuntime` through its own vendored
-Service Definition (see `src/vendored/repl-runtime.ts`), so it carries **zero
-dsh runtime package dependencies**: only `@deepseek-ai/cordis` (peer),
-`schemastery`, and `zeromq`.
-
-## Package positioning
-
-- npm name: `better-dsh` (unscoped; formerly `@pgmi-builds/better-dsh`, which
-  now stays published only as a deprecated pointer to this name).
-- A standard Cordis plugin (`Context` + schemastery `Config`, every tunable
-  configurable from `cordis.yml`, no hardcoded tunables).
-- "Registrations are effects": the kernel lifecycle (lazy spawn on a key's
-  first `run()`, teardown on that session's `agent/disposed`, optional
-  snapshot at either teardown) is effect-owned, so plugin disposal tears
-  every subprocess down.
-- Published surface: `lib/` only (`files: ["lib"]`, `main`/`types`/`exports`
-  pointing at `lib/index.js` / `lib/index.d.ts`) — the build emits beside the
-  manifest (`outDir: 'lib'`; the tsdown default `dist/` left the exports map
-  dangling, fixed in M2B). The root also re-exports the vendored Service
-  Definition's public contract (`ReplRuntime` plus the `CodeRun*` /
-  `CodeBinding*` / `CodeJsonValue` types) so consumers depend on the
-  published shape instead of reaching into sources. The declaration keeps
-  dependency imports external (`dts: { resolve: false }`): bundled copies
-  would create duplicate type identities in a consumer's program.
-
-## Native Web defaults
-
-The bundle owns native DSH Web policies as independently toggleable components.
-`dashr-web-trust` accepts authenticated serving Host/Origin values while retaining
-native cookie authentication. `dashr-webserver` inherits the native server and
-waits for welcome confirmation before listening; its default address is
-`0.0.0.0`, with the native port and CLI override behavior preserved.
-Automatic credential onboarding is disabled; users can still configure models.
-
-`dashr-welcome-notice` reads the current `WELCOME_NOTICE_VERSION` from the Models
-client belonging to the actual DSH installation and acknowledges it through the
-original General settings namespace before the first HTTP read. No version is
-pinned in the plugin. Ordinary version bumps adapt at startup; changed private
-symbols or build layouts fail explicitly. Restore native welcome behavior with:
-
-```yaml
-- id: dashr-welcome-notice
-  disabled: true
-```
+> Part of [Super D](../README.md). `better-dsh` is an independently installable native DSH bundle. Super Dash installs it through the native Plugin Manager; both packages use synchronized versions and independent enable/disable controls. Canonical shared specifications are in root `docs/`.
 
-The sibling Super Dash pack builds this repository locally and embeds its actual
-tarball. Better Dash remains independently installable. `../dev-webmcp` is an
-unshipped development-only bundle owned by this repository.
+# Better Dash — Dashr
 
-## Install
+Better provides a stateful `ctx.replRuntime` and the model-facing `eval` tool. Each DSH session has its own persistent Python child: variables, imports and definitions survive across cells, while sessions remain isolated. `DashrRuntime` owns the children and their lifecycle; the presentation layer exposes the Python SDK and bridges calls to the current session's host tools.
+
+The execution path is Node → JSON lines → an unchanged, pinned OMP Python runner → Python. Better adapts the host interfaces and packages the runner resources with compiled JavaScript. No OMP package, Bun, IPython, Jupyter or ZeroMQ is required by this path. Host modules remain optional peers and keep their runtime identity; Better's own JavaScript dependencies are bundled at build time.
+
+## Native Web policies
+
+The bundle owns independently toggleable WebTrust, mobile behavior, password-page and onboarding contributions through native DSH interfaces. Native WebServer/HMR and CLI listener policy remain in place. `dashr-welcome-notice` shadows the native welcome entry and calls its public completion callback; disabling that component restores the native welcome item.
+
+Super Dash installs Better as a separate native bundle. `../dev-webmcp` is a development-only test bundle and is not shipped in either product tarball.
+
+## Install and interpreter
 
 ```sh
 npm install better-dsh
 ```
 
-The runtime OWNS its kernel environment. With `python` left at the
-`python3` sentinel (or absent), it provisions a managed venv under the
-package (`.venv-kernel`) on first use, installing `ipykernel` + `dill`
-(CPython 3.11) — no `/tmp` symlink, no blind trust in a host `python3`.
-An explicit `python` (or `DASHR_KERNEL_PYTHON`) is verified instead. For
-development and tests, pre-create the venv:
+Better uses an existing Python interpreter. An explicit `python` setting (or `DASHR_KERNEL_PYTHON`) takes precedence; otherwise discovery checks the active virtual/Conda environment, an existing workspace `.venv` or `venv`, then PATH `python3` and `python`. Candidates are actually probed, and a broken automatically discovered candidate does not hide a working fallback. Relative explicit paths resolve against the session workspace. No CPython implementation or Python3.11 version is selected. The packaged dill0.4.1 checkpoint helper requires Python >=3.9.
 
-```sh
-npm run kernel:venv        # uv venv .venv-kernel --python 3.11 + ipykernel + dill
-```
+Better does not install Python, invoke uv/pip, or create a virtual environment. When none of the existing candidates works, the error lists the attempts and asks for an existing interpreter or a Python installation. `npm run kernel:check` checks availability without changing the environment. The runner and dill sources ship in the package; runtime checkpoints belong under the native profile home, and package upgrades do not require rebuilding a package-local Python environment.
 
-Tests pick the kernel interpreter from `DASHR_TEST_PYTHON`, falling back to
-`./.venv-kernel/bin/python`, then `python3` — see `test/helpers.ts`.
+The old `kernelEnvDir`, `kernelPythonVersion` and `kernelAutoInstall` provisioning fields and `kernel:venv` command are removed. Existing package-local `.venv-kernel` / `.uv-cache` directories are no longer selected automatically or modified; an existing interpreter can still be selected explicitly. A checkpoint made with another interpreter/environment may be incompatible and produces the usual explicit recovery notice; it is never replayed into a new environment.
+
+The original OMP runner's source commit/hash and MIT license, and dill's source hashes/version and BSD-3-Clause license, accompany the packaged resources. Better's integration code is separate from these original files. OMP-specific Agent helpers are not exposed as DSH features.
 
 ## Configuration
 
-Every field of the plugin `Config` (schemastery defaults shown):
+Runtime fields remain configurable through the ordinary Cordis row. The implementation's schema is authoritative; the principal controls are:
 
 | Field | Default | Meaning |
 | --- | --- | --- |
-| `python` | `python3` | Explicit interpreter with `ipykernel`; the bare `python3` sentinel (or absent) selects a managed venv under `kernelEnvDir`. |
-| `startupTimeoutMs` | `30000` | Budget for kernel spawn → ready, in milliseconds. |
-| `runTimeoutMs` | `120000` | Wall budget per run; expiry interrupts the kernel then force-settles. |
-| `interruptGraceMs` | `2000` | Grace between a timeout/abort interrupt and the force-settle. |
-| `interruptConfirmMs` | `250` | Confirm window between the control-channel interrupt and the SIGALRM escalation (must be `< interruptGraceMs`); see "Interrupts" below. |
-| `disposeTimeoutMs` | `5000` | Budget for graceful kernel teardown (shutdown_request → SIGKILL). |
-| `snapshotTimeoutMs` | `30000` | Budget for internal snapshot/restore cells (dill dump/load). |
-| `maxOutputBytes` | `67108864` | Hard cap for serialized log-array, completion-value, and failure-message payloads. |
-| `snapshotDir` | *(unset)* | Base directory for per-session namespace snapshots (`<dir>/<principal>/state.dill` + `manifest.json`); none when absent. |
-| `snapshotSizeCapBytes` | `268435456` | Serialized-size cap for a turn-end snapshot; over-cap snapshots are skipped (one-time model warning). |
-| `username` | `dashr` | Jupyter username stamped on wire messages. |
-| `kernelEnvDir` | *(unset)* | Managed venv directory (defaults to `<package>/.venv-kernel`). |
-| `kernelPythonVersion` | *(unset)* | Preferred CPython version for a managed venv (default `3.11`). |
-| `kernelAutoInstall` | `true` | Provision the managed venv (`ipykernel` + `dill`) on first use. |
-
-## Persistent-state semantics
-
-- **Cell semantics**: each `run({ program })` is one cell on the calling
-  session's kernel namespace (`user_ns`) — a pure IPython REPL. Top-level
-  `await` works; a top-level `return` is a SyntaxError, exactly as in a
-  native IPython cell. The completion value is the LAST expression's value
-  (REPL displayhook-style): a statement-ending cell or a `None` final
-  expression yields no `value` field, and a non-JSON value comes back as its
-  repr text.
-- **Session keying** (M3-A): one kernel per distinct `request.principal`
-  (the presentation bridge passes the calling agent's session id); runs
-  without a principal share one default key, preserving M1 semantics. The
-  service instance count is unchanged — one per mount — the keying is a
-  `Map<principal, kernel>` inside the provider.
-- **Kernel lifetime**: lazy start on a key's first `run()`; teardown when
-  that session's agent is disposed (the dsh `agent/disposed` event, payload
-  `{ agent: { id } }`, listened through the untyped cordis event service to
-  keep this package's zero-dsh-dependency rule) and on plugin disposal
-  (`shutdown_request`, then SIGKILL after `disposeTimeoutMs`). A kernel that
-  dies unexpectedly is never reused in-process: it respawns onto its nearest
-  replayable snapshot (or a fresh empty kernel when none exists) and the run
-  that observed the death gets an explicit `worker-exit` naming what was lost.
-- **Turn-end snapshots** (M3-B): with `snapshotDir` configured, every
-  successful run is followed by a size-capped snapshot cell that dumps the
-  user namespace to `<snapshotDir>/<principal>/state.dill` + `manifest.json`
-  (`turn`, `pythonVersion`, `venvPath` = the kernel's own `sys.executable`,
-  `skills`, `names`, `sizeBytes`). A namespace whose serialized size exceeds
-  `snapshotSizeCapBytes` is skipped — estimated BEFORE any dill IO by a
-  bounded walk that reads numpy/pandas in-memory footprints, then confirmed
-  against the actual `.part` dump — and the model is warned once through the
-  run's own logs. Skipped snapshots never replace the previous good one.
-- **Restore-on-first-boot** (M3-B): a key's first kernel boot restores its
-  on-disk snapshot before running user code. The kernel validates the
-  manifest itself (python version, interpreter identity, skills); a
-  non-replayable snapshot degrades to an EMPTY namespace and the first run
-  tells the model so. Variable state and the append-only transcript are NOT
-  transactionally consistent (blueprint §8.3): the snapshot is a point-in-time
-  namespace capture that can lag the transcript, and a degraded restore never
-  fabricates variables the transcript once saw.
-- **Interrupts** (M3-A hardened): aborts/timeouts escalate in two phases —
-  the zmq control `interrupt_request` first, then SIGALRM only after
-  `interruptConfirmMs` if the cell has still not settled. The kernel-side
-  bootstrap installs a busy guard that only raises `KeyboardInterrupt` while
-  a dashr cell is actually executing, so a signal landing on an idle or
-  booting kernel is swallowed instead of terminating the process (the M1
-  same-tick dual send killed idle kernels deterministically — 10/10
-  same-tick, 8/10 at +1-2ms, 40/40 during cold boot; see
-  `test/interrupt-race.spec.ts`). The hard-abort contract is intact: a busy
-  `while True: pass` still breaks inside the grace (blueprint §10.4).
-- **Concurrency**: the bridge serializes cells per kernel (`executeCell`
-  awaits the previous cell), so concurrent `run()` calls on one session
-  queue rather than interleave; see `test/parallel.spec.ts`. Runs on
-  DIFFERENT principals execute on their own kernels concurrently.
-- **What snapshots do NOT carry**: nothing outside the kernel namespace is
-  ever in scope — the v0.1.8b removal deleted the Continual Harness
-  (`refine()`, `harnessDir`) entirely, so the snapshot/restore cycle's only
-  persistence channel is the kernel namespace itself (blueprint §8.4).
-  Anything a cell stores in ordinary variables follows the snapshot rules
-  above as before.
+| `python` | automatic discovery | Existing executable name/path; explicit selection bypasses discovery. |
+| `startupTimeoutMs` | `30000` | Budget for child startup and initialization. |
+| `runTimeoutMs` | `120000` | Wall budget per user cell. |
+| `interruptGraceMs` | `2000` | Grace after an interrupt before terminating an unresponsive child. |
+| `interruptConfirmMs` | `250` | Delay before confirming an interrupt that has not finished the cell. |
+| `disposeTimeoutMs` | `5000` | Bound on graceful child teardown before forced cleanup. |
+| `snapshotTimeoutMs` | `30000` | Budget for internal save/restore operations. |
+| `maxOutputBytes` | `67108864` | Cap for serialized logs, completion and error output; overflow is reported. |
+| `snapshotDir` | native profile checkpoint directory | Explicit directory overrides the native profile default; `""` disables persistence and retains only live process state. Standalone runtimes must explicitly configure persistence. |
+| `snapshotSizeCapBytes` | `268435456` | Checkpoint payload cap; failed or over-cap saves preserve the previous committed generation. |
+| `username` | `dashr` | Retained compatibility field. |
 
-## Testing
+## Cells and recovery
 
-```sh
-npm install
-npm run kernel:venv     # once; or export DASHR_TEST_PYTHON=/path/to/python
-npm run typecheck       # tsc --noEmit
-npm test                # vitest --run (fileParallelism: false)
-```
+One `eval` call runs one Python cell. Top-level `await` works and top-level `return` is invalid. The final expression supplies the completion value; a final `None` or statement produces no value. Non-JSON completions return repr text. Printed stdout/stderr become logs. Tools use `await tool.<name>({...})` and failures raise `ToolCallError`.
+
+Operations for one session serialize, including initialization, user cells, checkpointing, variable access and reset. Different sessions can execute concurrently; one cell can fan out independent asynchronous host tool calls.
+
+Completed cells attempt a checkpoint, including cells that raise after changing state. The helper saves an admitted user object graph, preserving shared references among retained values. Serialization failures, resource exclusions and partial coverage are reported to the model. A complete generation is committed atomically; a failed attempt before commit retains the previous valid checkpoint. If interruption prevents confirmation of the commit, Better reports that uncertainty.
 
-Teardown discipline: every test context is disposed through
-`onTestFinished`, and CI must assert no orphan kernels remain:
+On a fresh child, Better validates and attempts restoration once before admitting user code. The notice identifies the saved cell and any omissions. A damaged or incompatible checkpoint starts empty and reports why. Runner plumbing, tool bindings and OS resources are excluded. Current tools are recreated from the host; files, sockets, subprocesses, threads, locks, connections, environment mutations and external side effects are not restored as a Python process.
+
+A dying or interrupted cell may already have performed side effects. Better never automatically retries it or blindly replays historical cells. Read the recovery notice and inspect real state before deciding which work to repeat. `reset: true` clears the session's memory and disk checkpoints.
+
+For the full boundary and source provenance contract, see [the runtime guide](docs/specs/omp-python-repl-port/runtime-guide.md) and [spec](docs/specs/omp-python-repl-port/spec.md).
+
+## Testing
 
 ```sh
-pgrep -cf -- '-[m] ipykernel_launcher' || echo no-orphans
+npm run typecheck
+DASHR_TEST_PYTHON=python3 npm test
 ```
 
-(The `-[m]` trick prevents `pgrep` from matching itself; 208 orphaned
-kernels once exhausted machine memory while every unit test stayed green —
-blueprint §10.8/§10.9.)
+Tests create real Python children and dispose their contexts. Stdlib-only interpreter coverage verifies that external kernel packages are unnecessary. Consumer acceptance additionally requires the root dual-tarball launcher and dev3 installed behavior; source tests and process liveness alone are insufficient.
 
 ---
 
@@ -198,7 +73,7 @@ blueprint §10.8/§10.9.)
 
 The DASHR agent-plane presentation (blueprint §7.4): the plugin half that
 presents the persistent-kernel runtime to the model as **cells on one
-persistent IPython kernel**. It contributes:
+persistent Python runner**. It contributes:
 
 - **`eval`** — the cell transport tool: one call = one cell on the calling
   session's kernel (the `ctx.replRuntime` service). Variables, imports, and
@@ -303,15 +178,12 @@ unknown id, or an infrastructure rejection all map to an `error` string.
 
 ```sh
 npm install
-npm run kernel:venv     # once; or export DASHR_TEST_PYTHON=/path/to/python
+export DASHR_TEST_PYTHON=python3  # or an explicit supported interpreter
 npm run typecheck
 npm test                # vitest --run
 ```
 
-The suite needs a Python interpreter with `ipykernel` (+ `dill` for the
-snapshot tiers) for the real-kernel specs; it resolves one from
-`DASHR_TEST_PYTHON`, then `./.venv-kernel/bin/python`, then `python3` —
-see `test/helpers.ts`.
+The suite needs a supported Python interpreter; the runner and checkpoint serializer are supplied by Better. `DASHR_TEST_PYTHON` selects the test interpreter.
 
 ## Relationship to upstream
 

package/cordis.patch.yml

@@ -14,17 +14,14 @@
 # a PTC session resolves to UNKNOWN_TOOL). DASHR ships no PTC mode, so that
 # rule never bites here.
 #
-# `python` is only a hint: the runtime OWNS the kernel environment. An
-# explicit interpreter (DASHR_KERNEL_PYTHON) is verified; the bare
+# An explicit DASHR_KERNEL_PYTHON interpreter is verified. The default
+# python3 compatibility path may prepare a managed Python environment;
+# the packaged OMP runner needs no Jupyter or kernel package installation.
 - insert:
-    # No-op standalone; keeps a containing pack's local companion delivery current.
-    - id: dashr-bundle-delivery
-      name: 'better-dsh/bundle-delivery'
-
     - id: dashr-repl
       name: 'better-dsh'
       config:
-        python: !!js process.env.DASHR_KERNEL_PYTHON ?? 'python3'
+        python: !!js process.env.DASHR_KERNEL_PYTHON
 
     # URL-aware I/O + hashline + devices. Gates ride THIS row's config
     # (schema defaults: both ON — opt-out), no longer the core row's.
@@ -72,7 +69,7 @@
     - id: dashr-web-password
       name: 'better-dsh/web-password'
 
-    # Automatically acknowledge the installed Host's current welcome version.
+    # Skip native welcome selections through the client's public onboarding slot.
     # Single-row opt-out: dashr-welcome-notice: disabled.
     - id: dashr-welcome-notice
       name: 'better-dsh/welcome-notice'
@@ -105,35 +102,7 @@
   config:
     trustedHosts: !!js (process.env.DSH_TRUSTED_HOSTS ?? '').split(/\s+/).filter(Boolean).concat(ctx.webRuntime.trustedHosts)
 
-# Replacement uses the public patch mechanism: disable the native provider,
-# then insert a distinct row providing the same native webServer service.
-- id: webserver
-  name: '@deepseek-ai/dsh-host-webserver'
-  disabled: true
-- insert:
-    - id: dashr-webserver
-      name: 'better-dsh/webserver'
-      inject: [webStartup]
-      config:
-        host: !!js ctx.webStartup.host ?? '0.0.0.0'
-        port: !!js ctx.webStartup.port ?? 3080
-        compression: gzip
-        compressionLevel: 1
-        compressionThresholdBytes: 1024
-
 - id: ui-settings-models
   name: '@deepseek-ai/dsh-client-ui-settings-models'
   config:
     credentialOnboarding: false
-
-# Native watcher/queue with scoped transaction context across listener replacement.
-# Distinct row preserves whole-bundle disablement in the native manager.
-- id: hmr
-  name: '@deepseek-ai/dsh-hmr'
-  disabled: true
-- insert:
-    - id: dashr-hmr
-      name: 'better-dsh/hmr'
-      disabled: !!js "!ctx.get('profileContext')"
-      config:
-        root: []

package/docs/20_specs/kernel-provisioning/spec.md

@@ -1,5 +1,7 @@
 # kernel-provisioning Specification
 
+> Historical iKernel contract, superseded on2026-10-12. Do not apply the provisioning requirements below to current Better. The active [existing-interpreter discovery contract](../../specs/kernel-provisioning/spec.md) removes uv/pip provisioning,3.11 selection and package-local venv creation.
+
 ## Purpose
 better-dsh 的 REPL kernel（IPython）供给契约：独占 managed venv（插件包目录内，`kernelEnvDir` 可显式覆盖）、版本锁定（ipykernel 7.3.0 / dill 0.4.1，uv 与 pip 双路径）、三级触发供给（postinstall 加速器 / daemon spin-up 主路径 / 首用 lazy 兜底）全 fail-open 且幂等、供给状态可观测；npm 包不内嵌预建 venv（供给能力随包，供给结果不随包）。
 

package/docs/adr/0015-independent-bundles-agent-remote.md

@@ -0,0 +1,40 @@
+# ADR 0015 — Independent bundles and Agent-owned remote tools
+
+Status: accepted design (2026-10-10); consumer acceptance tracked separately.
+
+## Context
+
+The October 9 user decision supersedes ADR 0014's npm dependency architecture. Better Dash and Super Dash are independent native DSH bundles at synchronized versions. Their independent disable/uninstall choices must remain meaningful.
+
+## Decision
+
+- Super has no Better npm dependency, optional dependency or peer edge. The native Plugin Manager companion operation requests `better-dsh@<installed Super version>`, then `latest`, then the bare name. Existing installation and user choices are preserved; Super upgrade does not reinstall a removed companion. The same native operation serves Settings explicit installation.
+- `better-dsh/src/remote/` is the sole editable enhanced-remote source. The build generates Super's self-contained `remote/` ESM/declarations and source SHA-256 provenance, exposed by `super-dsh/remote`. This narrow exception carries neither the Better bundle, client, other tools nor a runtime dependency on Better. Host modules remain external optional peers and single-instance.
+- Both remote rows default on. Official Agent creation events allow the first enabled row to own registration for that Agent instance. A loser does not retry. Winner unload cleans its Agent resources; it does not trigger automatic hot takeover. New Agent creation and cold resume can compete again.
+- Hub is optional and independent of native remote registration. Hub-body authenticated executors do not depend on the model-facing remote row. No machine availability poller or second background job registry is introduced.
+
+## Consequences and verification
+
+Pack validation covers exports, generated closure/provenance, host externalization, and absence of Better payload/dependency edges. Consumer acceptance must additionally exercise Super's worker while Better is absent, independent Plugin Manager transitions, actual tools and model-visible recovery guidance. Source tests or mounted plugin rows are not substitutes.
+
+See [the feature specification](../specs/remote-tool-enhancement/spec.md), [delivery guide §8](../07-cordis-dsh-dev-test-guides.md#8-better-dash-双构建与原生-companion-交付2026-10-09-再修订), and the dated acceptance report. ADR 0014 and its historical reports are preserved as evidence of the former design.
+
+
+### 2026-10-10 consumer worker delivery correction
+
+The generated Super `remote/` contains exactly `plugin.js`, `plugin.d.ts`, private `file-worker.js`, and `provenance.json`. The worker leaf is built solely from canonical `better-dsh/src/remote/file-worker.ts`, has Node-builtins-only imports, and is hashed/checked with the closure. It has no public package export, host peer imports, duplicated host modules, source loader or Better dependency. The public plugin contract remains unchanged. The existing owned child-process/group cleanup remains the receiver boundary; no worker-thread lifecycle replacement. This narrow extra generated leaf fixes actual installed receiver resolution, not a general guarantee that host plugins import outside their host resolver.
+
+### Receiving ownership and two-remote byte route (Rulings22–25)
+
+SSH and canonical Docker/Incus oneshots share the portable receiving gate/control/work owner, preserving official jobs and Agent/plugin ownership. Container helpers additionally self-enable unprivileged child-subreaping before work to reap only their own/adopted descendants. Actual receiving helper/group cleanup precedes settlement; unavailable final transport drain is diagnosed honestly. Prerequisites and three-startup cost are explicit in the tool Surface.
+
+Ruling25 supersedes the original two-remote source -R/private-master/sshd-FD/pidfd design after actual default dev3 source failed its permission requirement. A task-owned portable Python loopback proxy, inside the existing receiving helper/group/lease, carries bounded binary frames over authenticated SSH work stdio to an origin TCP bridge into the destination -L tunnel. A real full-route @RSYNCD greeting precedes business admission. No source Linux /proc, pidfd, privileged sshd access or source forwarding permission is required; native find, native rsync and the existing portable Bash/Python/fcntl/shared-monotonic prerequisites remain. No origin Python, credentials on peers, copy fallback, lease increase or second registry. Five-byte type/length frames cap data at64KiB and Python queues at256KiB; one active connection, real backpressure and half-close, prior reader/socket close before next OPEN. Ordinary two-remote transfer measures12 SSH startups: source preflight+inspection clock/work3, relay source/destination preflight2, destination clock/daemon+tunnel2, source proxy clock/owner/work3, native source rsync clock/work2. Fault recovery adds only task-owned authenticated cleanup reconnects, never transfer retries. Same real helper/listener/group/metadata/tunnel/socket cleanup barrier; receiving progress remains an explicit assumption. Historical M permission failure remains in the acceptance report; current default-dev3-source source test passes, installed next-artifact proof is separate.
+
+
+### CLI binary receiving ownership (consumer correction, Ruling26)
+
+Actual N native SSH copy cancellation settled while the remote import process and its unnamed staging file remained live under a finite work-channel EOF hold. CLI export/import/digest now reuse the canonical portable receiving owner, with raw binary work streams and the same counted lease, admission gate and authenticated recovery. Cancellation/failure waits for receiving helper/group/temp cleanup before local transport teardown/settlement. Normal success must completely drain the binary stream; the oneshot text lane's 2500ms incomplete-output rule does not apply. Archive validation, selected manifest digests, merge/no-delete behavior and canonical SSH identity/ProxyJump are unchanged. Local and Hub file lanes are unchanged.
+
+This intentionally replaces the former Python-only minimum for CLI peers: Bash4.1+, Python3.7+ (macOS3.10+), Unix fcntl.flock/shared non-adjustable cross-process monotonic clock, mktemp/mv/rm/sleep; Linux containers also need stdlib ctypes and permitted unprivileged PR_SET_CHILD_SUBREAPER. No rsync or origin Python requirement, auto-install, second registry, fallback, peer polling or increased lease. Minimal Python-only peers no longer support this CLI lane; use a supported peer or authenticated Hub.
+
+Each remote export/import/digest costs three native transport starts: clock, independent owner/control, literal binary work. Thus verified local→CLI or CLI→local costs six; CLI→CLI twelve. verify:false skips digest operations, reducing counts to three/three/six. Local/Hub operations do not contribute CLI starts. Fault recovery may add same-identity authenticated cleanup starts and may remain pending until genuine cleanup observation is possible. Artifact O must re-prove installed cancellation and complete binary integrity; N failures remain historical evidence.

package/docs/remote-tools.md

@@ -0,0 +1,56 @@
+# Remote tools
+
+Better Dash and Super Dash each provide the native `remote` tool and REPL route. The first enabled provider owns each Agent; unloading it does not hot-transfer ownership. Start a new Agent or cold-resume after changing providers. Super works without Better; Hub transport is optional. See [ADR 0015](adr/0015-independent-bundles-agent-remote.md).
+
+## Choose a call
+
+| Goal | Input |
+| --- | --- |
+| List locally known targets without dialing | `{}` |
+| Probe one target | `{target:"ssh:alias"}` |
+| Register an Agent-local SSH identity | `{target:"byossh:build",ssh:{host:"host",user:"user",key:"/origin/key"}}` |
+| Stateless command and stdin | `{target:"byossh:build",cmd:"cat",stdin:"hello"}` |
+| Stream a local script to fixed `bash -s` | `{target:"ssh:alias",script:"/absolute/script.sh"}` |
+| Persistent shell | `{target:"ssh:alias",mode:"pty",cmd:"cd /tmp; export CHECK=ready"}` |
+| Official background job | `{target:"ssh:alias",cmd:"long-command",run_in_background:true}` |
+| Native CLI copy | `{action:"copy",src:"/absolute/source",dst:"ssh:alias:/absolute/destination",argv:["-p"]}` |
+| Native rsync | `{action:"rsync",src:"/absolute/source/",dst:"ssh:alias:/existing/destination/",argv:["-a","--partial","--dry-run"]}` |
+
+`script` cannot combine with cmd/stdin/spawn/PTY. Direct local command execution is not provided; use native local shell tools. Background jobs are oneshot-only, require the official jobs service/controller, and are read/killed with `job_output`/`job_kill`; they have no default foreground timeout. An explicit timeout still applies. SSH keys/config stay on the origin; BYO identities are not persisted across new/cold Agents. PTY backlog recovery and live probes are not part of this release.
+
+Native/PTY output retains at most 4,000,000 UTF-16 units per stream; Hub oneshot retains 4 MiB bytes. Normal returned tails are smaller. Read `outputStats` units and dropped/returned counters rather than treating character counts as bytes. Discarded output is not recoverable after restart.
+
+## File operations: native CLI semantics
+
+`remote` addresses targets once (`ssh:<name>`, `byossh:<label>`, `docker:<name>`, `incus:<name>`, `hub:<machine>`, local paths) and hands the actual transfer to the native CLI. `argv` is an ordered array of native option tokens — one element = one argv token, appended verbatim before the parsed `src`/`dst`. There is no option whitelist, no shell parsing, and no forced defaults: no hidden `--dry-run`, no forced archive/timeout, no automatic verification. A dry run means passing `--dry-run` yourself; unknown or incompatible options fail in the native CLI and its exit code and stderr come back as-is. Success of a native command is never reported as independently verified — `verified:false` on native copy receipts means exactly that.
+
+### copy routes
+
+| Route | Command | Notes |
+| --- | --- | --- |
+| local↔SSH | `scp` | default SFTP; caller may pass `-O` explicitly |
+| SSH↔SSH | `scp -3` (data through the origin) | both identities stay on the origin; differing BYO identities are separated by a temporary origin-only SSH config, removed afterwards. `scp -R` is refused before start: it would authenticate from the source host |
+| local↔Docker | `docker cp` | |
+| local↔Incus | `incus file push/pull` | |
+| other cross-endpoint pairs (SSH↔Docker, Docker↔Incus, …) | two native commands with origin staging | each half takes its own options via `pullArgv`/`pushArgv` (mutually exclusive with `argv`); the receipt states both commands |
+| Hub↔local↔local | existing staged archive lane | the only lane where `verify`/`mkdir` apply; it keeps SHA-256 verification and destination-parent creation. CLI-option fields are rejected on this lane |
+
+The native CLIs do not create destination parents or verify results on their own; receipts report each command's exit, stdout/stderr and the sanitized argv. Two-segment routes stage in an origin scratch directory that is removed on normal exit (`cleanup:"released"`); an interrupted channel is reported as `cleanup:"unknown"`.
+
+### rsync routes
+
+rsync supports SSH/byossh endpoints with at most one local endpoint. Local↔SSH runs `rsync` on the origin with the endpoint's SSH identity wired through `RSYNC_RSH`; an explicit `-e`/`--rsh` in `argv` replaces that wiring per rsync's own rules (the command must then carry its own port/key/config). Nothing else is injected — no archive, no timeout, no dry-run, no remote owner, no `--rsync-path`.
+
+SSH↔SSH prefers the native forwarding route: the destination runs a temporary loopback-only rsync daemon, `ssh -L` brings it to an origin port, `ssh -R` carries it onto the source's loopback, and the source's own native rsync client performs one protocol conversation through the chain. The origin only forwards rsync protocol bytes; the destination's existing file data feeds real delta matching (`--stats` shows Matched data dominating for a small change on a large file). If an endpoint refuses TCP forwarding (`AllowTcpForwarding no`), a standard-stream route would be attempted; on the current OpenSSH/rsync combination (10.2 / 3.4.1) that route reports itself unavailable — the error says so and nothing is copied. rsync never falls back to a full copy or to Python.
+
+Tool-owned daemons/forwards/SSH sessions are torn down on normal exit and observable cancellation; a lost channel is reported with `cleanup:"unknown"` rather than a false success claim.
+
+### Prerequisites
+
+File operations require the corresponding CLI on the origin (`scp`, `rsync`, `docker`, `incus`) and on the SSH/container endpoints that execute it (`rsync` for rsync routes; none beyond the container's own CLI for docker/incus copy). No remote Python, Node or worker is deployed for file transfers. The dual-SSH forwarding route requires `AllowTcpForwarding` on both endpoints. BYO-PTY is not a file endpoint.
+
+## One-shot command requirements
+
+One-shot SSH/byossh commands (foreground, background, script and literal stdin) run through ONE native SSH exec: the command executes under bash with a small POSIX wrapper whose TERM/HUP trap kills the command's whole process group, so backgrounded children do not outlive the session teardown. Remote prerequisites: bash (POSIX) — **no Python, no owner/lease protocol, no flock/monotonic clock, no extra sessions**. On normal completion the wrapper's EXIT trap reaps the command's whole process group (backgrounded children included — they neither outlive the call nor hold the channel open), and the exit code passes through verbatim. On timeout/cancellation the local transport dies at once and a dedicated cleanup session reads the pidfile the wrapper left and kills the group (TERM→KILL); sshd delivers no signal to a no-PTY session, so this explicit cleanup is the remote kill path.
+
+Docker/Incus one-shots use the same pure-CLI lane (`docker exec` / `incus exec` with the same wrapper); container prerequisites are the container's own bash. PTY paths are unchanged (`ssh -tt bash`, docker via script(1), incus interactive) and never required Python.

package/docs/specs/kernel-provisioning/spec.md

@@ -1,53 +1,25 @@
-# kernel-provisioning Specification
+# Existing Python interpreter discovery
 
-## Purpose
-better-dsh 的 REPL kernel（IPython）供给契约：独占 managed venv（插件包目录内，`kernelEnvDir` 可显式覆盖）、版本锁定（ipykernel 7.3.0 / dill 0.4.1，uv 与 pip 双路径）、三级触发供给（postinstall 加速器 / daemon spin-up 主路径 / 首用 lazy 兜底）全 fail-open 且幂等、供给状态可观测；npm 包不内嵌预建 venv（供给能力随包，供给结果不随包）。
+Updated 2026-10-12 by explicit user correction. This replaces the former iKernel managed-provisioning contract. Execution and recovery are specified in [OMP Python REPL](../omp-python-repl-port/spec.md); consumer behavior is in its [runtime guide](../omp-python-repl-port/runtime-guide.md).
 
 ## Requirements
 
-### Requirement: Exclusive managed kernel venv
+### Existing interpreters only
 
-The plugin SHALL provision its REPL kernel interpreter exclusively inside a managed venv rooted in the plugin's own package directory (web-profile scope in production deployments, `kernelEnvDir` as the explicit override), and SHALL NOT install into, mutate, or depend on the user's global Python environment; kernel probes MUST NOT import user-site modules, and the distributed npm package MUST NOT embed a prebuilt venv (provisioning capability ships, not provisioning results).
+Better SHALL run an existing Python interpreter. It SHALL NOT invoke uv/pip, download Python, create or repair a virtual environment, or place Python environment/cache state in the installed npm package. No CPython implementation or Python3.11 preference is applied. The packaged dill0.4.1 checkpoint helper requires Python >=3.9.
 
-#### Scenario: Venv lives inside the plugin territory
+### Explicit selection
 
-- **WHEN** the plugin is installed into a web profile and the kernel is provisioned
-- **THEN** the venv root is inside the plugin's package directory (or the explicitly configured `kernelEnvDir`), and no file outside that territory is required for kernel operation
+An explicit `python` executable name/path SHALL bypass automatic discovery. Bare `python3` is an explicit executable name, not a provisioning sentinel. Relative paths SHALL resolve against the session workspace and `~/` against the user's home. An unusable explicit selection SHALL report the actual failure without silently substituting another interpreter. Existing explicit virtual environments SHALL receive their activation environment.
 
-#### Scenario: User global environment untouched
+### Automatic discovery
 
-- **WHEN** provisioning runs on a host with an existing global Python installation
-- **THEN** no package is installed into, and no configuration of, the user's global environment is modified
+Without explicit selection, Better SHALL probe an existing active virtual/Conda environment or workspace `.venv`/`venv`, then PATH `python3` and `python`. A broken automatically discovered candidate SHALL permit a working fallback without repair. Resolved executable identity and activation environment SHALL reach the spawned child. One session's project interpreter SHALL NOT be cached as the choice for another workspace.
 
-### Requirement: Robust provisioning with pinned versions
+### Readiness and failure
 
-Provisioning SHALL redirect its tool caches (uv) to a plugin-territory location so read-only home directories cannot block it, SHALL fall back to `python3 -m venv` + ensurepip when `uv` is unavailable, and SHALL install pinned, tested versions of `ipykernel` and `dill` alongside the pinned CPython version; provisioning MUST be idempotent (a complete venv is reused; a partial one is repaired).
+Availability is checked when the session needs its Python child. Plugin mounting SHALL NOT provision an environment. With no working candidate, the error SHALL identify attempted interpreters and explain how to install Python or configure an existing executable. `npm run kernel:check` SHALL perform discovery only, with no installation side effects.
 
-#### Scenario: Read-only home cache does not block
+### Runtime state and migration
 
-- **WHEN** the kernel is provisioned on a host whose `~/.cache` is read-only
-- **THEN** provisioning succeeds using the redirected cache location
-
-#### Scenario: Pinned versions installed
-
-- **WHEN** provisioning creates or repairs the venv
-- **THEN** the installed `ipykernel` and `dill` match the pinned tested versions, verifiable by the kernel probe
-
-### Requirement: Provisioning ladder — install-time, daemon spin-up, first-use
-
-The plugin SHALL provision the kernel through a three-trigger ladder converging on the same managed venv, every trigger fail-open (a failure or suppression at any level degrades to a logged status message and NEVER blocks package installation, daemon startup, or plugin mounting, and never asks the user for approval): (1) an install-time postinstall best-effort step that runs only when the package manager executes build scripts; (2) a daemon spin-up check as the PRIMARY path — when the plugin is brought up on the host plane by the host daemon, it asynchronously verifies the kernel environment and provisions it immediately when absent (uv → `python3 -m venv` → explicit configuration), so an agent session never discovers a missing kernel at first use; (3) first-use lazy provisioning as the final fallback. Provisioning status (provisioning/ready/degraded/failed) SHALL be logged, and failure messages MUST name the available remedies (`npm run kernel:venv`, `kernelAutoInstall`, explicit `python`).
-
-#### Scenario: Daemon spin-up provisions before any agent session
-
-- **WHEN** the host daemon starts and brings the plugin up on the host plane, and the managed venv is absent
-- **THEN** the plugin asynchronously provisions the kernel within the spin-up window without blocking daemon startup or plugin mounting, and a new agent session's first REPL cell finds the kernel already in place
-
-#### Scenario: Suppressed postinstall still reaches a working kernel
-
-- **WHEN** the package manager skips the plugin's postinstall script and the daemon later starts
-- **THEN** the spin-up check provisions the kernel and REPL cells execute, with the install itself never having failed and no approval ever having been requested
-
-#### Scenario: Failure is non-blocking and visible
-
-- **WHEN** provisioning fails on a constrained host at any trigger
-- **THEN** the installation, daemon startup, and plugin mounting all succeed; the surfaced error names the concrete remedy commands/configuration paths
+Checkpoints SHALL remain under the native profile home (or explicitly configured snapshot directory), isolated by profile/session. Old `kernelEnvDir`, `kernelPythonVersion`, `kernelAutoInstall` fields and `kernel:venv` command are removed. Existing package-local `.venv-kernel`/`.uv-cache` files SHALL be left untouched and SHALL NOT be selected automatically. An interpreter/environment change SHALL pass the existing checkpoint compatibility checks and report incompatible recovery explicitly; no user cell is replayed.

package/docs/specs/omp-python-repl-port/runtime-guide.md

@@ -0,0 +1,35 @@
+# Better Dash Python REPL execution and recovery
+
+Implementation and acceptance are tracked in the [plan](../../superpowers/plans/2026-10-12-omp-python-repl-port.md). The [spec](spec.md) defines the recovery boundary; this guide explains the consumer contract being implemented.
+
+Better runs a persistent Python child for each DSH session. Node communicates with an unchanged, pinned OMP runner over JSON lines. Better owns tool bindings, cancellation, output mapping and checkpoint management. Interpreter discovery reuses an explicitly configured interpreter, otherwise an active/project environment then PATH `python3` or `python`. It probes candidates and falls back from broken automatically discovered environments; it never invokes uv/pip, installs Python or creates a venv. Explicit relative paths and project environments resolve against the session workspace. Python >=3.9 is required by the packaged dill0.4.1 checkpoint helper; no3.11 or CPython implementation is selected. Better ships the Python runner and dill 0.4.1 source. It does not install Jupyter, IPython, ZeroMQ or dill into the consumer's interpreter. OMP's Agent-specific prelude is not exposed as a DSH feature.
+
+Variables, functions, classes and imports remain available across cells while the child lives. Top-level await works; a top-level return is invalid. The final expression supplies the completion value and print supplies logs. Host tools remain callable with `await tool.<name>({...})`. Internal initialization and checkpoint cells do not appear as user results or user scratchpad variables.
+
+`tool.read` forwards to the current DSH native read tool with its usual permissions, scheduling and results. Better supplies the call-site helper required by OMP's compiler without enabling OMP speculative reads. Interactive `input()` is unsupported and returns an actionable error. Output uses the existing text/log/result contract; a nontext-only display produces an explicit MIME notice.
+
+`npm run kernel:check` checks existing interpreter availability without provisioning. Legacy provisioning fields `kernelEnvDir`, `kernelPythonVersion`, `kernelAutoInstall` and the `kernel:venv` command are removed. Old package-local environments/caches are left untouched and are not auto-selected. An interpreter change may make existing checkpoints incompatible; recovery reports that condition explicitly.
+
+## Checkpoint boundary
+
+In a native DSH profile, checkpoints belong under that profile's resolved DSH home and are isolated by profile and session. An explicitly configured checkpoint directory takes precedence; `snapshotDir: ""` disables persistence and leaves process-local state only. A standalone runtime without a native profile must explicitly choose a checkpoint directory.
+
+A completed cell attempts a new checkpoint, including a cell that raises after changing variables. Saving a checkpoint can fail or skip values. Better reports the coverage and latest committed cell instead of claiming complete process recovery. Aliases and dependencies among retained values must survive as one object graph; values whose dependencies cannot safely be preserved are omitted or the checkpoint is rejected.
+
+The serializer does not preserve runner state, host tool bindings, open files, sockets, subprocesses, threads, locks or database connections. Tool bindings are recreated from the current host. Current directory, environment changes, module caches and library global state are not generally restored. File modifications and network/tool side effects have their own real sources and are never replayed or rolled back by a variable checkpoint.
+
+The checkpoint manifest records format, completed-cell sequence, interpreter/environment identity, payload size/integrity, saved names and omissions. Only a complete committed generation is eligible for restoration. A failed attempt before commit preserves the previous valid generation. If interruption prevents commit confirmation, the result reports that uncertainty; the manifest remains the authority on the latest complete generation. Restore validates the owned session checkpoint before loading it and runs once before admitting a new user cell. Damage or incompatibility produces an explicit empty-state notice. A partial restore lists the missing coverage.
+
+`reset: true` discards the session child and its persisted checkpoints. Do not use it when you intend to retain state.
+
+## After a crash or interruption
+
+Read the recovery notice, check the latest successful checkpoint and inspect real external state. A cell that died after starting may already have performed side effects. Better does not automatically retry it and does not instruct blind replay. Recreate omitted resources and rerun only the operations you determine are still needed.
+
+Snapshots are private executable serialization, not an interchange format. Do not copy arbitrary external dill files into the checkpoint directory or treat them as data imports. The owned directory, session isolation and permissions are part of the recovery contract.
+
+## Delivery verification
+
+The original OMP runner, its MIT license and source/hash provenance travel inside the npm package. Vendored dill carries its version, original source hashes and BSD-3-Clause license. The build verifies these resources and copies them beside compiled JavaScript; consumers never execute TypeScript or load OMP/Bun packages.
+
+Acceptance uses the normal dual tarball launcher and a dev3 test installation. Source tests, successful build or a live Python process alone are insufficient. The final test report records exact artifacts and the observed model-visible recovery behavior.