feat(bindings): host env and mounts applied after construction survive reset

[chaliy]

What changed

A host can now apply environment to a running interpreter, and host setup applied after construction survives a rebuild.

• Core: Bash::set_env(key, value) — the environment counterpart to live mount(). Preserves shell state; no rebuild.
• NAPI / Python: setEnv / set_env, plus a recorded replay of host set_env and runtime mount calls. reset() now keeps them the way it already kept custom builtins and constructor files. unmount() retracts its record, so a rebuild cannot resurrect a removed mount. Env a script exported stays transient — reset() still discards it.

The practical effect: a reusable mount + env + builtin bundle installs onto an existing instance in one step, instead of splitting into a config-fragment the host merges by hand plus a post-construction apply function where only half the setup survives a reset.

Bash::set_env writes both the exported entry and the shell variable, matching BashBuilder::env. The exported entry alone is shadowed by a same-named shell variable during expansion, so a host value applied later would silently lose to a builder-configured one. This was caught by a failing binding test, not by inspection.

Why

Issue #2291 asks for a publishable extension object with mount/env/command hooks. Investigating it surfaced a smaller, more concrete gap underneath: mount was runtime-callable but env was construction-only, so no single-phase install was expressible; and of the three parts of such a bundle, only builtins survived reset().

Fixing that makes the extension shape ordinary userland code, and fixes a lifecycle inconsistency that stood on its own regardless of the issue.

Scope: this is the prerequisite, not the whole issue. Still open from #2291: the declarative extension object itself (extensions: [...] / installExtension), schema-backed ctx.command() on Bash (today addBuiltin gives raw argv; help/discover/--dry-run live only in ScriptedTool), and onBeforeExecute.

Before / After

The issue's example, run against the shipped API (node, NAPI binding):

Before — two phases, and the mount is gone after a reset:

$ node skill-today.mjs
# my-skill (args: hello)
SKILL.md

after reset: exit 1 — cat: /skills/my-skill/SKILL.md: io error: file not found
re-mounted: # my-skill        # only after calling mountSkill() again by hand

After — one phase, intact across reset():

const installSkill = (bash) => {
  bash.mount(SKILL_PATH, skillFs);
  bash.setEnv("SKILL_PATH", SKILL_PATH);
  bash.addBuiltin("my-skill", (ctx) => ctx.fs.readFile(`${SKILL_PATH}/SKILL.md`));
};

$ node smoke.mjs
fresh:               "# my-skill\n/skills/my-skill\n"
after reset:         "# my-skill\n# my-skill\n"
after unmount+reset: 1

Python is byte-identical on the same script:

fresh:               '# my-skill\n/skills/my-skill\n'
after reset:         '# my-skill\n# my-skill\n'
after unmount+reset: 1

Risk

• Low
• New API surface only; no existing call path changes behavior. The one semantic shift is that a binding reset() now keeps host setEnv/runtime mounts where it previously dropped them — the direction TM-ISO-025 already requires for constructor config, and the reason unmount() had to become retracting rather than live-only.
• Nothing lands on the exec hot path: the replay logs are touched only by setEnv/mount/unmount and read once per rebuild.
• The env log holds one entry per key, so a host calling setEnv per request does not accumulate entries.

Checklist

• Tests added or updated — 7 core (runtime_env_tests.rs), 15 NAPI (runtime-extension.spec.ts), 14 Python (test_runtime_extension.py), covering live application, export visibility, precedence against builder/constructor env, reset replay, unmount retraction, and the full bundle end to end
• Backward compatibility considered — additive; internal project, no external API contract

Knowledge updated: runtime_env row in the capability parity contract (with recorded reasons for the five surfaces that intentionally lack it), TM-ISO-025 evidence, the live-mount guide, the Python package doc, and the knowledge log.

Part of #2291

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	bashkit	9e37c43	Commit Preview URL Branch Preview URL	Aug 13 2026, 01:09 AM