@code-yeongyu/senpi-codemode 2026.10.9 → 2026.10.10-3

package/CHANGELOG.md

@@ -12,6 +12,60 @@
 
 ### Removed
 
+## [2026.10.10-3] - 2026-10-06
+
+### Breaking Changes
+
+### Added
+
+- An opt-in process-isolated JavaScript kernel (`isolation.js: "process"` or `SENPI_CODEMODE_JS_ISOLATION=process`) runs each JavaScript kernel in its own subprocess instead of a worker thread, so a kernel crash (`SIGSEGV`, out-of-memory, `process.exit`, an uncaught error) can no longer take down the host session; the next cell runs on a replacement child with a restart notice naming the crash. It isolates crashes, not hostile code: a cell is trusted as in worker mode, and hostile code belongs in `isolate: true` sandbox cells ([#2752](https://github.com/code-yeongyu/senpi/issues/2752) tracks hostile-cell isolation). The child runs on the host's own runtime, exits as soon as its host is gone (including `SIGKILL`), carries large output and `BigInt`/`undefined` values as worker mode does, and its frames carry a per-process token so stray output is never taken for a frame. The default stays `"worker"` and worker-mode behaviour is unchanged ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+
+- The README now documents every eval surface (helpers, magic cells, settings, JavaScript isolation modes and sandbox cells), and CI checks it against the helper census, so a new helper cannot ship undocumented ([#2787](https://github.com/code-yeongyu/senpi/pull/2787)).
+
+### Fixed
+
+### Removed
+
+## [2026.10.10-2] - 2026-10-05
+
+### Breaking Changes
+
+### Added
+
+- `@code-yeongyu/senpi-codemode/executable-settings.json` lists the settings that name an executable run at session start (today `languages.pyInterpreter`). senpi's project-trust check reads it, so a project codemode file that sets one asks for trust, and a test fails if a new free-form string setting is neither on the list nor marked as not naming an executable ([#2772](https://github.com/code-yeongyu/senpi/pull/2772)).
+
+### Changed
+
+### Fixed
+
+- Settings that were accepted but did nothing now take effect ([#2763](https://github.com/code-yeongyu/senpi/issues/2763)): `kernelTools.enabled: false` makes JavaScript `tool(fn)` and Python `@tool` refuse with `tools_unavailable`; `languages.pyInterpreter` makes the Python kernel run exactly that executable (a path that does not answer makes Python unavailable, with a warning naming the setting; one named by a project's own settings file is honored only in a trusted project); `prompt.advertiseHelpers: true` adds one line pointing at `tool_schema('eval:helpers')` to the eval description. Settings-file warnings (an unknown key, a fallback to defaults) now reach the user as a notice, or on stderr without a UI.
+
+### Removed
+
+## [2026.10.10] - 2026-10-05
+
+### Breaking Changes
+
+### Added
+
+- Isolated eval cells: with `sandbox.enabled`, `isolate: true` runs a JavaScript cell in a fresh QuickJS VM with no persistence and no ambient host (only `tools.*`, `print`, `display`), streaming output under a credit window. Off by default; the eval schema is unchanged until the setting is on.
+- A JavaScript cell that is only `%bun add <package ...>` or `%npm add <package ...>` installs packages into a per-session managed environment without restarting the kernel; the next cell imports them by bare name, the project's `package.json` and `node_modules` are untouched, lifecycle scripts never run, and a failed or cancelled install leaves the previous packages active ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+
+### Fixed
+
+- An isolated (`isolate: true`) cell whose QuickJS runtime is missing now fails with `eval_isolate_unavailable` before any of its code runs, instead of a module-resolution error that named a host path ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+- `%bun add` over a package first installed from a local directory now works when the new archive's top directory is not `package/` (a GitHub-style `<repo>-<sha>.tgz`, or a plain `.tar`): its name is read from the archive's own top-level directory, so the old directory's links are removed before bun installs ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+- A nested tool call that is denied inside an `eval` cell (a permission denial or another hook's block) now reaches the cell as the plain denial, without the `Expected parameters:` schema hint that made it read like an argument error; argument failures still get the hint ([#2700](https://github.com/code-yeongyu/senpi/issues/2700)). Thanks to @MoerAI ([#2755](https://github.com/code-yeongyu/senpi/pull/2755)).
+- An `eval` run with an invalid `language` value (for example `"python"`, `""` or `null`) now gets its own error listing the enabled languages, instead of the "run requires language" message meant for an omitted one; `peek` and `stop` still need no language ([#1395](https://github.com/code-yeongyu/senpi/issues/1395)). Thanks to @MoerAI.
+
+### Removed
+
 ## [2026.10.9] - 2026-10-04
 
 ### Breaking Changes

package/README.md

@@ -59,6 +59,75 @@ task-tool names are known.
 A missing optional interpreter removes that language from the session's `eval`
 schema; it is not an installation failure.
 
+### JavaScript process isolation
+
+By default the JavaScript kernel runs as a worker thread on the host's own
+runtime (`isolation.js: "worker"`). Setting `isolation.js: "process"` (or
+`SENPI_CODEMODE_JS_ISOLATION=process`, which wins over the file) runs each
+JavaScript kernel in its own subprocess instead, so a kernel crash (a native
+`SIGSEGV`, an out-of-memory, `process.exit`, an uncaught error) cannot take down
+the host session. The next cell runs on a replacement child, and its result
+carries the restart notice and names the crash.
+
+**Trust model.** Process mode isolates crashes, not hostile code. A cell runs in
+the same process that talks to the host, so it can reach everything that process
+holds, exactly as a worker-mode cell can. The frame token described below guards
+only against accidental corruption of the channel. Hostile code belongs in
+`isolate: true` sandbox cells. Hostile-cell isolation for process mode is tracked
+in [#2752](https://github.com/code-yeongyu/senpi/issues/2752).
+
+**Core dumps (Linux).** The kernel child marks itself non-dumpable at start
+(`prctl(PR_SET_DUMPABLE, 0)`). A Linux system that pipes core dumps to
+`systemd-coredump` or apport otherwise holds a crashed child until its dump is
+read, which froze the cell for about 30 s; without the dump the crash is reported
+at once, still naming its signal. Two side effects: no core file is written for a
+crash of the kernel child itself, and a same-user debugger cannot attach to it
+(`ptrace` needs a dumpable process). A cell's own subprocesses are unaffected,
+because `exec` resets the flag. Set `SENPI_KERNEL_CORE_DUMPS=1` to keep dumps and
+debugger access while debugging the kernel.
+
+How it works:
+
+- **Runtime.** The child runs on the host's own runtime: bun when senpi runs on
+  Bun, node otherwise. A compiled binary whose executable is neither falls back to
+  `bun` or `node` on `PATH`, preferring the host's kind. The badge names the
+  runtime that actually runs the child, for example `js (bun 1.4.x, process)`.
+- **Frames.** The host writes a random token as the child's first line on fd 0,
+  and every frame the child sends carries it. The host parses only lines that
+  carry the token; any other line (a cell's raw fd write, a child process's
+  output) is delivered as text. Frames are written in full. Large text is split
+  below the 10 MiB frame limit, and a result too large to return fails its cell,
+  not the kernel. A `BigInt` or an `undefined` field reaches the host as it does
+  in worker mode.
+- **File descriptors.** Under Bun, the control channel moves to a private
+  duplicate of fd 0, fd 0 becomes `/dev/null`, and fd 1 is re-pointed at a
+  pipe that a reader thread turns into `text` frames as it is written. The pipe is kept
+  blocking (a child that switches it to non-blocking is undone before every cell and around
+  every child process a cell starts),
+  so output is never held in memory while a cell is busy. A cell's direct
+  `process.stdout.write` or fd 1 write (or a child process inheriting fd 1)
+  arrives before that cell's result. In a bun child, raw fd 1 bytes are not
+  interleaved with `console` output in the order they were written. A node
+  child cannot move its fds: cell output shares the channel, and fd 0 is the
+  channel. If libc cannot be loaded through `bun:ffi`, a bun child runs
+  the same way and still starts; the first cell's stderr says why.
+- **Lifetime.** The child exits as soon as its control channel closes. That
+  covers every way the host ends, including `SIGKILL`. A watchdog thread also
+  compares the parent pid with the one recorded at start, so a child whose cell
+  never yields (a busy loop, a blocking call) still ends with its host, including
+  under a Linux subreaper. A process-mode kernel never outlives its host.
+- **Failed start.** There is no inline fallback in process mode. A failed start
+  settles the waiting cell with a capability-gap result naming the missing
+  runtime (`Install bun or node, or use isolation.js: "worker"`). The result's
+  memory reading is the child's process footprint.
+
+The default stays `"worker"`, and worker-mode behaviour is unchanged.
+
+To run the `environments` suites with bun children (the runtime the product
+uses), run them under bun: `SENPI_CODEMODE_JS_ISOLATION=process bunx --bun vitest
+run test/environments`. Under plain `vitest` the children follow the test
+runner's runtime, which is node.
+
 Python startup waits for the interpreter's `ready` event. It reports progress
 through `stdlib-imports`, `runtime-init`, and `host-init`; advancing to the next
 stage resets an inactivity guard rather than consuming a total startup budget.
@@ -67,6 +136,12 @@ Windows fresh-cache bootstrap p99 (30 samples). A stalled or failed start names
 the last stage and retains the interpreter's diagnostic error. The low-level
 `PythonKernel.start({ startupTimeoutMs })` override applies per stage.
 
+Every `eval` run must explicitly select an enabled `language` (`js`, `py`, `rb`,
+or `jl`); there is no default kernel, even when only one language is enabled.
+Omitting `action` means `run`, so it also requires `language`. Control requests
+with `action: "peek"` or `action: "stop"` use `cell_id` and do not require a
+language.
+
 ### Session environment
 
 Every kernel starts with the active session's `PI_*` environment — `PI_SESSION_ID`,
@@ -117,6 +192,35 @@ cannot be read fails the cell with a message naming the path as written
 (`file not found: <path>`, `permission denied: <path>`); files over 8 MiB, and
 anything that is not a regular file, are refused.
 
+### JavaScript packages
+
+A JavaScript cell whose only line is `%bun add <package ...>` or `%npm add <package ...>`
+installs packages without restarting the kernel; the next cell imports them by bare name.
+`%bun add` uses bun and `%npm add` uses npm; `environments.js.installer` (`bun`, `npm` or
+`auto`: bun when it is on `PATH`, else npm) applies only where the magic names none, and the
+kernel's own runtime never changes to get one.
+
+In the default managed mode packages go into an environment revision under the session's
+artifacts directory, never into the project's `package.json` or `node_modules`. With
+`environments.managedRoot` set, every session using that root shares one revision chain: their
+installs are serialized and each revision carries the packages installed before it.
+A bare import resolves from the session directory's `node_modules` first and then from the
+active revision, using each package's `exports` for `import` (ESM-only packages load), so the
+project's own packages still win, and both win over Senpi's own dependencies (a package neither has may still load from Senpi's install). When a
+newly added package is also in the project's `node_modules`, the result says
+`environment_resolution_conflict` because the project copy resolves first.
+
+Each install builds a new revision that carries the previous one forward (its `package.json`,
+lockfile, and from `.npmrc` only `registry`, `@scope:registry`, `strict-ssl`, `ca` and `cafile`, rewritten as a regular file; credentials and every other key are dropped, and `bunfig.toml` is not carried)
+and is published only when the installer succeeds; a failed or cancelled install, or one still
+running when the session closes, leaves the previous revision active. Lifecycle scripts never run
+(`--ignore-scripts`), installer flags are refused because the host picks the destination, and a
+path-like package (`./pkg`, `file:../pkg`) is a path from the session directory. Package names
+are split on whitespace; quoting is not supported. Error and installer text names the session directory as
+`<cwd>`, the revision as `<root>`, the temp directory as `<tmp>`, the home directory as `~`, and an
+absolute package path by its file name only. `%environment project` installs
+into the session directory itself instead.
+
 ### Python packages
 
 A Python cell whose only line is `%pip install <requirements>` installs packages
@@ -145,6 +249,19 @@ that project, with concurrent installs serialised by a lock. Setting
 of `environment_install_failed`, `environment_install_cancelled`,
 `environment_installer_unavailable` or `environment_resolution_conflict`.
 
+### Isolated cells
+
+With `sandbox.enabled: true`, a JavaScript call may pass `isolate: true`. The cell then runs in a fresh QuickJS VM (the vendored pi codemode runtime) instead of the persistent kernel:
+
+- Nothing persists: globals from the kernel are not visible, and a global set in one isolated cell is gone in the next. `store()` throws `eval_isolate_no_state` and `load()` returns `undefined`.
+- No ambient host: there is no `process`, `require`, file system, network, child processes or timers. The cell's only reach is `tools.<name>` (also `tool.<name>`; every active tool except `eval`, run through the same permission hooks as a direct call) plus `print`, `display`, `text` and `image`.
+- `isolate: true` isolates the JavaScript, not the tools it calls: a tool keeps its normal reach. `tools.bash`, for example, runs a shell with the session's environment and files, under the same permission hooks as any other call.
+- Output streams from the VM in frames under a 256 KiB credit window, so the VM never holds a large item; the host joins an item's frames before adding it to the result, and memory stays bounded by `sandbox.memoryMb`.
+- It is a host entry in the JavaScript queue: it waits for earlier cells, Stop and the run budget end it, and the persistent kernel is never restarted for it.
+- Limits: `sandbox.memoryMb` (default 64) and `sandbox.timeoutSeconds` (default 300). Failures are named: `eval_isolate_memory_limit`, `eval_isolate_timeout`, `eval_isolate_unresolved_promise` (a top-level promise that can never settle) and `eval_isolate_unavailable` (the runtime could not start).
+
+While `sandbox.enabled` is `false` (the default) the `isolate` field is absent from the eval schema, and passing it is refused with `eval_isolate_invalid`, as are `isolate` with another language and `isolate` with `reset`.
+
 ## Settings
 
 Configuration is loaded in this order:
@@ -206,7 +323,7 @@ Configuration is loaded in this order:
 | `memory.retainedResultsMb` | `32` | In-memory byte budget (MiB) for the settled cells kept for `peek`/`list`, on top of the 32-cell count cap; the oldest go first and the newest is always kept. `0` keeps only the count cap. Env override: `SENPI_CODEMODE_RETAINED_RESULTS_MB` (a non-negative integer). |
 | `memory.retainedImagesMb` | `256` | Disk budget (MiB) for settled-cell images. Images of settled cells (foreground and detached) are written as base64 files under `<session artifacts>/settled-images/` instead of staying in memory, and `peek` reads them back, so it returns the full result. Beyond the budget the oldest files are deleted first; an evicted cell's files are deleted with it; the directory is removed when the session ends. A `peek` whose image file is gone returns the text plus a one-line note. `0` keeps only the count cap. Env override: `SENPI_CODEMODE_RETAINED_IMAGES_MB` (a non-negative integer). |
 | `memory.idleParkMinutes` | `0` | Off by default. When greater than 0, a kernel with no cell running or queued for this many minutes is closed to give its memory back, and the next cell for that language starts a fresh one; that cell's result says the kernel was restarted and every earlier global is lost. Applies to every language. |
-| `languages.pyInterpreter` | unset | Explicit Python interpreter path. Unset keeps today's `PATH` detection. |
+| `languages.pyInterpreter` | unset | Explicit Python interpreter path: the Python kernel runs exactly that executable (a path with spaces is fine). A path that does not answer `--version` makes Python unavailable for the session, with a warning naming the setting. Unset keeps `PATH` detection. |
 | `environments.managedRoot` | unset | Root directory for managed per-session environments; unset uses the session's default location. |
 | `environments.autoProvision` | `true` | Lets installs provision a managed environment. `false` makes installs refuse with `environment_installer_unavailable`. |
 | `environments.js.installer` | `auto` | Installer for the managed JavaScript environment: `auto`, `bun` or `npm`. |
@@ -216,16 +333,16 @@ Configuration is loaded in this order:
 | `sandbox.memoryMb` | `64` | Memory cap (MiB) for a sandbox cell. Env override: `SENPI_CODEMODE_SANDBOX_MEMORY_MB` (a positive integer wins). |
 | `sandbox.timeoutSeconds` | `300` | Time limit for a sandbox cell. |
 | `prompt.advertiseHelpers` | `false` | When `true`, one pointer line to `tool_schema('eval:helpers')` is appended to the eval description. |
-| `kernelTools.enabled` | `true` | Allows cells to define kernel tools (`tool(fn)`, `@tool`). `false` makes them refuse with `tools_unavailable`. |
+| `kernelTools.enabled` | `true` | Allows cells to define kernel tools. `false` makes JavaScript `tool(fn)` and Python `@tool` refuse with `tools_unavailable`, naming this setting. |
 
-The `languages.pyInterpreter`, `environments.*`, `isolation.*`, `sandbox.*`, `prompt.*` and `kernelTools.*` keys are accepted and validated now, with the defaults shown, which match today's behaviour. The effect each of those rows describes takes effect when its feature ships; until then, setting a key changes nothing.
+Every key in the table takes the effect its row describes.
 
 `SENPI_CODEMODE_PY`, `SENPI_CODEMODE_JS`, `SENPI_CODEMODE_RB`, and
 `SENPI_CODEMODE_JL` override the corresponding file setting. `1` or `true`
 enables; `0` or `false` disables. Any other value leaves the file setting in
 effect.
 
-A top-level key this version does not know is ignored with one warning naming it, and the rest of the file still applies, so a settings file written for a newer senpi keeps working. Malformed JSON, or an invalid value or an unknown key inside a known setting, falls back to all defaults with a warning.
+Settings problems reach the user as a notice in the interactive UI, or a `[senpi-codemode]` line on stderr without one. A top-level key this version does not know is ignored with one warning naming it, and the rest of the file still applies, so a settings file written for a newer senpi keeps working. Malformed JSON, or an invalid value or an unknown key inside a known setting, falls back to all defaults with a warning.
 The detached-cell environment override uses the run-budget parser: a positive
 base-10 integer wins over the file value; zero, negative, and malformed values
 leave the file value in effect.
@@ -240,6 +357,8 @@ options object and asynchronous helpers are `await`-able.
 | --- | --- |
 | `display(value)` | Emits text, structured JSON, markdown, or image display data. Images reach the model only through `display`: pass a figure, raw image bytes (PNG/JPEG/GIF/WebP/BMP sniffed), a `data:` URL, a `Blob`-like or `Bun.Image` value, a marshalled tool result, or one of its `images[i]` frames. |
 | `print(value, ...)` | Emits text output. |
+| `text(value)` (rb, jl) | Emits `value` as one text item without separators (`print` joins its arguments and calls it). |
+| `display_image(base64, mime_type)` (rb, jl) | Emits an image from base64 data; `mime_type` defaults to `image/png` (Ruby: `mime_type:` keyword). |
 | `read(path, offset?, limit?)` | Reads text with 1-indexed line slicing. `local://` paths resolve under the session artifact root. |
 | `write(path, content)` | Creates parent directories and writes text. `local://` paths persist in the session artifact root. |
 | `env(key?, value?)` | Reads all kernel environment values, one value, or sets one value. Includes the session's `PI_*` values (see [Session environment](#session-environment)). |
@@ -251,7 +370,7 @@ options object and asynchronous helpers are `await`-able.
 | `completion(prompt, model?, system?, schema?)` | Requests a one-shot host completion; `schema` asks the host to parse structured output. |
 | `agent(prompt, ...)` | Delegates to the configured active `taskTools.task` tool. Supports background handles and structured JSON results. |
 | `wait(handles, timeout?, mode?)` | Blocks the cell until the given handles settle (agent handle records, `handle()` views, completion handles, closed workpools, or saved `{kind, id, run_epoch}` references). `mode` is `all` (values in input order; the first failed, cancelled, or lost handle raises), `any` (`{index, ref, value}` of the first success), or `settled` (one outcome per input slot). `timeout` is wall-clock seconds from entry; on expiry `eval_wait_timeout` is raised and nothing is cancelled. Rides the bridge-call path, so the run budget pauses while parked. Agent and workpool handles need the host's `EvalHandleHost` capability (`eval_wait_unavailable` without it); completion handles always work. Julia extends `Base.wait` for handle views (`wait(handle(node))`). Details: `tool_schema("eval:wait")`. |
-| `handle(node \| ref \| {pool_id})` | Returns a rich view: the legacy record's fields plus a non-enumerable `control` (Python: attribute on a `dict` subclass; Ruby: singleton method) with `status()`, `output(format?, offset?, limit?)`, `send(message)` (agent handles only), `cancel()` (idempotent for that run epoch; never touches a successor run), and `wait(timeout?)`. Every control call is fenced by owner, id, and `run_epoch` inside the task owner (`eval_handle_stale`, `eval_handle_forbidden`). `completion(prompt, handle: true)` returns such a view for a host completion. The `agent(..., handle: true)` record itself is unchanged. Details: `tool_schema("eval:helpers")`. |
+| `handle(node \| ref \| {pool_id})` | Returns a rich view: the legacy record's fields plus a non-enumerable `control` (Python: attribute on a `dict` subclass; Ruby: singleton method) with `.status()`, `.output(format?, offset?, limit?)`, `.send(message)` (agent handles only), `.cancel()` (idempotent for that run epoch; never touches a successor run), and `.wait(timeout?)`. Every control call is fenced by owner, id, and `run_epoch` inside the task owner (`eval_handle_stale`, `eval_handle_forbidden`). `completion(prompt, handle: true)` returns such a view for a host completion. The `agent(..., handle: true)` record itself is unchanged. Details: `tool_schema("eval:helpers")`. |
 | `workpool(agent, name, mode?, tools?)` | Creates a thin adapter over the normal host `workpool` tool; exposes `pool_id`, `push(items)`, `close()`, `inspect()`, and `cancel()`. JS awaits creation and operations. `tools` is a list of kernel-tool names this cell defined; the pool's workers may call exactly those, the host refuses any name the caller doesn't hold, and a value that isn't a list of names raises `invalid_tools`. Ruby and Julia define no kernel tools, so they have nothing to grant. |
 | `output(ids, format?, offset?, limit?)` | Delegates transcript retrieval to the configured active `taskTools.output` tool. |
 | `parallel(thunks)` | Runs thunks through the configured bounded pool while preserving input order. |
@@ -443,6 +562,13 @@ original sizes, then a plain-path notice such as
   package.
 - Task transcript formats are limited to full (`raw`) and trailing (`tail`)
   output. Query, JSON, and stripped metadata formats are task-engine concerns.
+- There is no `pool.wait()`: a workpool's aggregate is delivered by the host after
+  `close()`, so a kernel never blocks on another engine's workers.
+- There is no `code_mode_only` mode and no speculative cell execution; both are
+  deferred to a separate design (omo#9232) rather than approximated here.
+- Kernels are never shared across owners: each session (and each in-process child
+  with its own eval tool) owns its kernels, and handles are fenced by owner, id and
+  run epoch.
 
 ## Security and lifecycle
 

package/package.json

@@ -1,13 +1,14 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.9",
+	"version": "2026.10.10-3",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
 	"exports": {
 		".": "./src/index.ts",
-		"./package.json": "./package.json"
+		"./package.json": "./package.json",
+		"./executable-settings.json": "./src/config/executable-settings.json"
 	},
 	"files": [
 		"src",
@@ -32,15 +33,15 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.9",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.10-3",
 		"quickjs-wasi": "3.6.2",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.9"
+		"@code-yeongyu/senpi": "2026.10.10-3"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.9"
+		"@code-yeongyu/senpi": "2026.10.10-3"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/protocol.ts

@@ -237,10 +237,15 @@ export function parseBridgeJsonLine(line: string, options: BridgeFrameOptions =
 export function decodeBridgeFrame(line: string, options: BridgeFrameOptions = {}): BridgeMessageDecodeResult {
 	const parsed = parseBridgeJsonLine(line, options);
 	if (!parsed.ok) return parsed;
-	if (Value.Check(bridgeMessageSchema, parsed.value)) {
-		return { ok: true, message: parsed.value };
+	return validateBridgeMessage(parsed.value);
+}
+
+/** Checks an already-parsed frame against the bridge schema (for transports that transform values before checking). */
+export function validateBridgeMessage(value: unknown): BridgeMessageDecodeResult {
+	if (Value.Check(bridgeMessageSchema, value)) {
+		return { ok: true, message: value };
 	}
-	const firstError = Value.Errors(bridgeMessageSchema, parsed.value)[0];
+	const firstError = Value.Errors(bridgeMessageSchema, value)[0];
 	const message = firstError ? `Invalid bridge message: ${firstError.message}` : "Invalid bridge message";
 	return { ok: false, error: { code: "invalid_message", message } };
 }

package/src/config/executable-settings.json

@@ -0,0 +1,5 @@
+{
+	"projectExecutableSettings": [
+		"languages.pyInterpreter"
+	]
+}

package/src/config/project-trust.ts

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+import executableSettings from "./executable-settings.json" with { type: "json" };
+import type { CodemodeSettings } from "./settings.ts";
+
+/**
+ * Settings that name an executable run at session start (an interpreter's `--version` probe, then the kernel). The
+ * one list of them lives in `executable-settings.json`, which senpi's project-trust check also reads: a project
+ * codemode file that sets any of them asks for trust. Without trust they are dropped with a warning and never run.
+ * Trust is asked only when the project's own file sets one, so a host that cannot answer still starts sessions;
+ * such a host counts as not trusting the project.
+ */
+export const PROJECT_EXECUTABLE_SETTINGS: readonly string[] = executableSettings.projectExecutableSettings;
+
+export function withoutUntrustedInterpreter<Settings extends CodemodeSettings>(
+	settings: Settings,
+	source: string | null,
+	cwd: string,
+	isProjectTrusted: (() => boolean) | undefined,
+): { readonly settings: Settings; readonly warning?: string } {
+	const projectFile = join(cwd, ".senpi", "codemode.json");
+	if (source !== projectFile) return { settings };
+	const named = PROJECT_EXECUTABLE_SETTINGS.filter((path) => valueAt(settings, path) !== undefined);
+	if (named.length === 0 || isProjectTrusted?.() === true) return { settings };
+	let trimmed: Settings = settings;
+	for (const path of named) trimmed = withoutPath(trimmed, path);
+	const list = named.map((path) => `${path} "${String(valueAt(settings, path))}"`).join(", ");
+	return {
+		settings: trimmed,
+		warning: `${list} in ${projectFile} is ignored because this project is not trusted; it was not run`,
+	};
+}
+
+function valueAt(value: unknown, path: string): unknown {
+	let current: unknown = value;
+	for (const key of path.split(".")) {
+		if (typeof current !== "object" || current === null) return undefined;
+		current = Reflect.get(current, key);
+	}
+	return current;
+}
+
+function withoutPath<T>(value: T, path: string): T {
+	const copy = structuredClone(value);
+	const keys = path.split(".");
+	const last = keys.pop();
+	let parent: unknown = copy;
+	for (const key of keys)
+		parent = typeof parent === "object" && parent !== null ? Reflect.get(parent, key) : undefined;
+	if (last !== undefined && typeof parent === "object" && parent !== null) Reflect.deleteProperty(parent, last);
+	return copy;
+}

package/src/config/settings-overrides.ts

@@ -20,6 +20,8 @@ export function resolveEnabledLanguages(
 	env: Environment = process.env,
 ): CodemodeSettings["languages"] {
 	return {
+		// Keep the non-flag keys (languages.pyInterpreter); only the four enable flags take env overrides.
+		...settings.languages,
 		py: resolveLanguage(settings.languages.py, env[languageEnvironmentFlags.py]),
 		js: resolveLanguage(settings.languages.js, env[languageEnvironmentFlags.js]),
 		rb: resolveLanguage(settings.languages.rb, env[languageEnvironmentFlags.rb]),

package/src/environments/js-environments.ts

@@ -0,0 +1,208 @@
+import { mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import { withRootLock } from "./install-lock.ts";
+import {
+	absoluteSpec,
+	type JsInstallerChoice,
+	parseJsPackages,
+	requestedPackageName,
+	resolveJsInstaller,
+	runJsInstall,
+	withoutHostPaths,
+} from "./js-installer.ts";
+import { carryNpmrcSettings, recordedFileSpecs, seedPackageJson } from "./js-revision-files.ts";
+import { assertBuiltRevisionLinks, assertNoLinksBelow, recordedInstallSources } from "./no-links.ts";
+import { projectResolves } from "./project-resolves.ts";
+import type { EnvironmentMode } from "./py-environment.ts";
+import { EnvironmentError } from "./py-installer.ts";
+import { mkdirPrivate, publishNextRevision, readActiveRevision } from "./revision-store.ts";
+
+/** The paths in a revision that the installer writes. */
+const INSTALLER_WRITES = [
+	"package.json",
+	"package-lock.json",
+	"bun.lock",
+	"bun.lockb",
+	"node_modules",
+	".npmrc",
+	"bunfig.toml",
+];
+
+export interface JsInstallReceipt {
+	readonly installer: "bun" | "npm";
+	readonly mode: EnvironmentMode;
+	readonly revision: number | undefined;
+	readonly added: readonly string[];
+	readonly shadowed: readonly string[];
+}
+
+export interface JsEnvironmentsOptions {
+	readonly artifactsDir: string;
+	readonly cwd: string;
+	readonly runtime: string;
+	readonly env: NodeJS.ProcessEnv;
+	readonly settings: Pick<ResolvedCodemodeSettings, "environments">;
+}
+
+export class JsEnvironments {
+	readonly #options: JsEnvironmentsOptions;
+	#mode: EnvironmentMode = "managed";
+	#packageRoot: string | undefined;
+
+	constructor(options: JsEnvironmentsOptions) {
+		this.#options = options;
+	}
+
+	get mode(): EnvironmentMode {
+		return this.#mode;
+	}
+
+	get packageRoot(): string | undefined {
+		return this.#mode === "managed" ? this.#packageRoot : undefined;
+	}
+
+	async setMode(mode: EnvironmentMode): Promise<string> {
+		this.#mode = mode;
+		if (mode === "project") return this.#options.cwd;
+		this.#packageRoot = (await readActiveRevision(this.#managedBase()))?.dir;
+		return this.#managedBase();
+	}
+
+	async install(
+		requested: string,
+		signal: AbortSignal,
+		onOutput?: (stream: "stdout" | "stderr", data: string) => void,
+		requestedInstaller?: "bun" | "npm",
+	): Promise<JsInstallReceipt> {
+		const environments = this.#options.settings.environments;
+		if (environments?.autoProvision === false) {
+			throw new EnvironmentError(
+				"environment_installer_unavailable",
+				"installs are turned off for this project (environments.autoProvision is false)",
+			);
+		}
+		const packages = parseJsPackages(requested).map((spec) => absoluteSpec(spec, this.#options.cwd));
+		// `%bun add` and `%npm add` name their installer; the setting applies only where the magic does not.
+		const choice: JsInstallerChoice = requestedInstaller ?? environments?.js?.installer ?? "auto";
+		const { installer, command } = resolveJsInstaller(choice, this.#options.env);
+		let recordedSpecs: readonly string[] = [];
+		const run = (root: string, remove?: string) =>
+			runJsInstall({
+				installer,
+				command,
+				root,
+				packages,
+				...(remove === undefined ? {} : { remove }),
+				recordedSpecs,
+				cwd: this.#options.cwd,
+				env: this.#options.env,
+				signal,
+				...(onOutput === undefined ? {} : { onOutput }),
+			});
+		// The lock and the revision store fail with raw file system errors; they reach the cell redacted.
+		const redacted =
+			(...roots: string[]) =>
+			(error: unknown) => {
+				const raw =
+					error instanceof EnvironmentError
+						? error.message.slice(error.code.length + 2)
+						: String(error instanceof Error ? error.message : error);
+				const text = roots.reduce(
+					(message, root) => withoutHostPaths(message, { root, cwd: this.#options.cwd, packages, recordedSpecs }),
+					raw,
+				);
+				if (error instanceof EnvironmentError) throw new EnvironmentError(error.code, text);
+				// An abort while waiting for the lock or before the publish is a cancel, not a failure.
+				if (signal.aborted)
+					throw new EnvironmentError("environment_install_cancelled", `the install was cancelled: ${text}`);
+				throw new EnvironmentError("environment_install_failed", text);
+			};
+		if (this.#mode === "project") {
+			const before = await dependencyNames(this.#options.cwd);
+			const lockRoot = join(this.#options.cwd, ".senpi", "js-packages");
+			await mkdir(lockRoot, { recursive: true });
+			await withRootLock(lockRoot, async () => await run(this.#options.cwd), signal).catch(redacted(lockRoot));
+			const added = (await dependencyNames(this.#options.cwd)).filter((name) => !before.includes(name));
+			return { installer, mode: "project", revision: undefined, added, shadowed: [] };
+		}
+		let added: string[] = [];
+		const requestedBase = this.#managedBase();
+		const base = await canonicalBase(this.#managedRoot(), requestedBase).catch(redacted(requestedBase));
+		const { revision } = await publishNextRevision(
+			base,
+			async (staging) => {
+				await carryNpmrcSettings(staging);
+				await rm(join(staging, "bunfig.toml"), { recursive: true, force: true });
+				await seedPackageJson(staging);
+				// Every path the installer writes must be the revision's own, never a link out of it.
+				for (const entry of INSTALLER_WRITES) await assertNoLinksBelow(base, join(staging, entry));
+				const before = await dependencyNames(staging);
+				recordedSpecs = await recordedFileSpecs(staging);
+				// A package whose source changes kind (a directory to a tarball or registry version, or back) is removed
+				// first: bun keeps its per-file links into the old directory otherwise (#2758).
+				for (const name of await sourceKindChanges(staging, packages)) await run(staging, name);
+				await run(staging);
+				await assertBuiltRevisionLinks(staging);
+				added = (await dependencyNames(staging)).filter((name) => !before.includes(name));
+			},
+			signal,
+		).catch(redacted(base, requestedBase));
+		this.#packageRoot = revision.dir;
+		const shadowed = added.filter((name) => projectResolves(this.#options.cwd, name));
+		return { installer, mode: "managed", revision: revision.number, added, shadowed };
+	}
+
+	#managedRoot(): string {
+		return this.#options.settings.environments?.managedRoot ?? this.#options.artifactsDir;
+	}
+
+	#managedBase(): string {
+		return join(this.#managedRoot(), "environments", "js", this.#options.runtime);
+	}
+}
+
+async function dependencyNames(root: string): Promise<string[]> {
+	try {
+		const manifest: unknown = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+		if (typeof manifest !== "object" || manifest === null || !("dependencies" in manifest)) return [];
+		const dependencies = manifest.dependencies;
+		return typeof dependencies === "object" && dependencies !== null ? Object.keys(dependencies) : [];
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/**
+ * Creates the managed base, checks that nothing below the managed root is a link, and returns its realpath: npm keys
+ * a linked package in its lockfile by a path relative to the prefix, and a prefix under a linked directory (macOS
+ * `/var` is a link to `/private/var`) gives keys that stop resolving once the staged revision is renamed.
+ */
+async function canonicalBase(managedRoot: string, base: string): Promise<string> {
+	await assertNoLinksBelow(managedRoot, base);
+	await mkdirPrivate(base);
+	await assertNoLinksBelow(managedRoot, base);
+	return await realpath(base);
+}
+
+/** Names among `packages` whose recorded source is a directory and is not the same directory now, or the reverse. */
+export async function sourceKindChanges(revision: string, packages: readonly string[]): Promise<string[]> {
+	const installed = new Set(await dependencyNames(revision));
+	const sources = await recordedInstallSources(revision);
+	const changed: string[] = [];
+	for (const spec of packages) {
+		const name = await requestedPackageName(spec);
+		if (name === undefined || !installed.has(name)) continue;
+		const directory = await localDirectory(spec);
+		if (directory !== sources.get(name)) changed.push(name);
+	}
+	return changed;
+}
+
+async function localDirectory(spec: string): Promise<string | undefined> {
+	const path = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+	if (!isAbsolute(path)) return undefined;
+	const resolved = await realpath(path).catch(() => undefined);
+	return resolved !== undefined && (await stat(resolved)).isDirectory() ? resolved : undefined;
+}