Cloud Sandboxes

A cloud agent sandbox opens a repository with the sandbox image’s default Node runtime, not necessarily the Node line the repository pins. Running any LumenFlow lifecycle command under the wrong Node ABI corrupts the shared CLI dist for every later session that reuses it, because the CLI dist hashes the Node ABI it was built with. Installing this project’s own private packages as a consumer also needs a registry npmrc carrying a licence-scoped credential, and a cloud sandbox has no interactive step to supply one.

The fix is a committed, cross-platform Node script run from a SessionStart hook registered once in .claude/settings.json (matcher startup|resume — deliberately not clear/compact, which already carry the repo’s own recovery hook and are not a genuinely new session environment), alongside its other session-start hooks.

What it does, inside a cloud session only

1. Detects the cloud/remote session. Only LUMENFLOW_CLOUD=1 (an explicit, repo-owned override) or the harness’s own remote-session environment signal activate the rest of the script. Neither present means a strict no-op: no PATH change, no build, no npmrc write.

2. Selects the pinned Node version through nvm, when nvm is present. Resolves the nvm-managed bin directory for the version in .nvmrc and, when the harness exposes a session-environment file to append export lines to, persists the selection for the rest of the session. A SessionStart hook cannot change its caller’s shell PATH just by exiting.

3. Runs pnpm bootstrap (turbo build --filter=@hellmai/lumenflow-cli) under the selected Node, so the first lifecycle command in the session finds a dist already built for the right ABI. This script runs before any workspace dist exists, so it cannot take a workspace package dependency to resolve pnpm’s Windows shim safely; instead it resolves the spawn form itself: on win32 it launches the command processor (ComSpec, or cmd.exe) with /d /s /c and the constant command line pnpm bootstrap (never user input) — pnpm ships as a .cmd shim there, and Node refuses to launch one directly since CVE-2024-27980. Elsewhere it resolves pnpm normally through PATH.

4. Writes the consumer registry credential, when supplied, without clobbering the rest of the file. When LUMENFLOW_CONSUMER_NPMRC is set, writes it into a managed block (bounded by begin/end marker comments) inside the user-level npmrc (~/.npmrc), with restricted permissions (POSIX mode 0600 on Linux/macOS; Windows has no equivalent POSIX bit, so the script reports that instead of failing). Any pre-existing content in that file — including a line a developer added by hand outside the managed block — survives untouched; a later run (for example after the secret rotates) replaces only its own block. The value is never printed or logged.

Every step reports its own failure and the script always exits 0: a SessionStart hook cannot block session start for this event, so a broken bootstrap must never prevent the session itself from starting.

Caution

On a developer’s own box, none of this runs. No cloud/remote signal is present, so the script returns immediately, before touching the filesystem or the environment. Rebuilding the shared CLI dist on every local session start would cost every other session on that box.

See Cloud sandbox session-start bootstrap for the full deployment contract.

Adding an equivalent bootstrap to your own repository

A repository that consumes LumenFlow and also runs in cloud sandboxes can follow the same shape:

1. Write a small, cross-platform Node script (for example a script under a scripts/ directory) that:

   • returns immediately unless a cloud/remote signal is present in the environment;
   • otherwise, selects your project’s pinned Node version (through nvm, Volta, or whatever version manager your sandbox image provides) and runs your project’s own build/bootstrap command;
   • when a registry credential is supplied through an environment variable, writes it to the user-level npmrc with restricted file permissions and never logs it.

2. Register that script once as a SessionStart hook in your project’s own .claude/settings.json (or the equivalent hook configuration for your agent harness), alongside any hooks already registered for that event — never replacing them.

3. Prove the no-op branch and each active branch with an injected environment, a fake version-manager directory layout, and a temporary home directory, never against a real version-manager install or a real build.