From 3300e0dead173abb31cc82eb5f7c418620664d69 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Mon, 12 Oct 2026 18:09:57 +0100
Subject: [PATCH 1/9] perf: the setup pass runs its stages in subshells, not a
 bash each

Every new non-interactive bash reads $BASH_ENV, and kinisi_ros's image
points it at its whole ROS bashrc: about 1.1s a read inside a devpod ssh
session. A cold launch's setup trip started one bash per stage on top of
its own, so the trip took about 11s for 6.7s of work.

The stages now run as `( eval '<script>' )`. eval keeps what the nested
bash gave each stage: the script parses when the stage runs, so a parse
error fails its own stage only, and exit, set -u and set -C end at the
closing parenthesis. The stage inherits the environment the pass already
loaded, which is the one it was reading anyway.

Measured over six cold kinisi_ros launches on fresh branches, alternating
builds: the setup trip went from 10.90s-11.14s to 6.66s-6.90s.
---
 CHANGELOG.md                               |  10 ++
 docs/performance.md                        |  18 ++
 rust/devlaunch-core/src/flows/provision.rs | 182 +++++++++++++------
 rust/dl/tests/setup_pass_shells.rs         | 194 +++++++++++++++++++++
 4 files changed, 351 insertions(+), 53 deletions(-)
 create mode 100644 rust/dl/tests/setup_pass_shells.rs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc10dc61..8e21ac66 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **A cold launch's setup pass starts one shell, not one per stage.** Each stage (session
+  name, zellij, codex, title, onboarding, trust) ran in a nested `bash -c`, and every new
+  bash reads the image's `$BASH_ENV`. kinisi_ros points that at its whole ROS bashrc, about
+  1.1s a read inside `devpod ssh`, so the trip took about 11s. The stages now run in
+  subshells of the pass (`( eval '<script>' )`), which keep each stage's `exit`, `set -u`
+  and parse errors to itself as the nested bash did. Measured over six cold kinisi_ros
+  launches, the setup trip went from 10.9s to 11.1s down to 6.7s to 6.9s.
+
 ## [0.59.4] - 2026-10-05
 
 ### Fixed
diff --git a/docs/performance.md b/docs/performance.md
index a19bcf73..542207c0 100644
--- a/docs/performance.md
+++ b/docs/performance.md
@@ -120,6 +120,24 @@ failing. A master that has gone away leaves a socket the next client unlinks, an
 resident `devpod ssh --stdio` process and a `docker exec` per key, and `dl` must
 not be the reason a container never goes idle.
 
+## One shell for the setup pass
+
+A cold launch sends one `devpod ssh --command` trip that runs dl's setup stages
+and then the tools probe. Each stage runs in a subshell of that trip's shell, not
+in a `bash` of its own. The reason is `$BASH_ENV`: every new non-interactive bash
+reads it, and an image may point it at a whole ROS bashrc. kinisi_ros's image
+does, and inside a `devpod ssh` session one read costs about 1.1s.
+
+Measured on 2026-10-12, on one host with the local docker provider and devpod
+0.26.3, over six cold launches of `kinisi-robotics/kinisi_ros` on six fresh
+branches. With a `bash -c` per stage the trip took 10.90s to 11.14s. With
+subshells it took 6.66s to 6.90s, so about 4.2s comes off every cold launch of
+that repo. An image with no `$BASH_ENV` saves a few milliseconds, because there
+was nothing to read. A warm launch makes no setup trip, so it is not affected.
+
+`the_pass_reads_the_images_bash_env_once_however_many_stages_it_runs` and
+`dl/tests/setup_pass_shells.rs` pin the count at one read per pass.
+
 ## Measuring launch time
 
 Set `DEVLAUNCH_TIMING=1` and a `dl` command ends with one summary on stderr,
diff --git a/rust/devlaunch-core/src/flows/provision.rs b/rust/devlaunch-core/src/flows/provision.rs
index 7cf1fe69..aadd129c 100644
--- a/rust/devlaunch-core/src/flows/provision.rs
+++ b/rust/devlaunch-core/src/flows/provision.rs
@@ -1882,6 +1882,25 @@ impl Stage {
     }
 }
 
+/// A multi-line stage script as one command, run in a subshell of the pass.
+///
+/// A subshell and not a nested `bash -c`, because a new bash reads `$BASH_ENV`
+/// when it starts and the subshell does not. An image may point that variable at
+/// a whole ROS bashrc: kinisi_ros's does, and inside a `devpod ssh` session one
+/// read costs about 1.1s, so five stages that each started a bash cost a cold
+/// launch about 4.4s for nothing. The subshell inherits the environment the pass
+/// already loaded, which is the environment the stages were reading anyway.
+///
+/// `eval` of one quoted word, rather than the script pasted between parentheses,
+/// keeps what the nested bash gave each stage: the script is parsed when the stage
+/// runs, so a script that will not parse fails its own stage and not the whole
+/// pass, and an `exit`, a `set -u` or a `set -C` in it ends at the closing
+/// parenthesis. `the_pass_reads_the_images_bash_env_once_however_many_stages_it_runs`
+/// pins the count.
+fn in_subshell(script: &str) -> String {
+    format!("( eval {} )", quote(script))
+}
+
 /// The stages one setup pass runs in `workspace`, in order.
 ///
 /// Built per pass rather than declared as a constant because a stage's command
@@ -1951,19 +1970,16 @@ pub(crate) fn setup_stages(
         // and the stage above usually cannot set one. Gated on nothing, like the
         // hostname and unlike the title: `DEVLAUNCH_NO_TITLE` turns off what dl
         // puts on the terminal, and did not ask for a session other agents cannot
-        // find. A nested `bash -c` for the title stage's reason, a stage being one
-        // line and this being several.
+        // find. In a subshell for the title stage's reason, a stage being one line
+        // and this being several.
         Stage::new(
             SESSION_NAME_STAGE,
-            format!(
-                "bash -c {}",
-                quote(
-                    &[
-                        profile_resolution("$HOME"),
-                        profile_prepend(&remote_control_prefix_line(workspace), None),
-                    ]
-                    .join("\n")
-                )
+            in_subshell(
+                &[
+                    profile_resolution("$HOME"),
+                    profile_prepend(&remote_control_prefix_line(workspace), None),
+                ]
+                .join("\n"),
             ),
         )
         // Quieter for the title stage's reason: a profile that cannot be written
@@ -1973,9 +1989,10 @@ pub(crate) fn setup_stages(
     if let (ToolsSwitch::Install, ZellijSwitch::Install) = (tools, zellij) {
         stages.push(Stage::new(
             ZELLIJ_STAGE,
-            // A nested `bash -c` because a stage is interpolated into
-            // `if <command>; then`, which is one line, and this script is not. It
-            // inherits the pass's exported PATH rather than sourcing the profile
+            // In a subshell because a stage is interpolated into
+            // `if <command>; then`, which is one line, and this script is not
+            // ([`in_subshell`] says why not a nested bash). It inherits the pass's
+            // exported PATH rather than sourcing the profile
             // again: the pass is already a login shell, so an installed zellij is
             // on PATH here, and a second `-l` would re-run a chatty image's
             // profile on every launch.
@@ -1987,11 +2004,11 @@ pub(crate) fn setup_stages(
             // /dev/null because the setup pass captures stdout: an install
             // redirected into that buffer is a cold launch that looks hung with
             // nothing to show for it.
-            format!("bash -c {} >&2", quote(&zellij_script())),
+            format!("{} >&2", in_subshell(&zellij_script())),
         ));
     }
     if let (ToolsSwitch::Install, CodexSwitch::Install) = (tools, codex) {
-        // Nested `bash -c`, redirected whole to stderr, for the zellij stage's two
+        // In a subshell, redirected whole to stderr, for the zellij stage's two
         // reasons: a stage is interpolated into `if <command>; then` and this script
         // is more than one line, and pixi is loud enough that its progress on the
         // probe's stdout is one unlucky line from being read as protocol.
@@ -2001,14 +2018,14 @@ pub(crate) fn setup_stages(
         // override a machine that has turned provisioning off.
         stages.push(Stage::new(
             CODEX_STAGE,
-            format!("bash -c {} >&2", quote(&codex_script())),
+            format!("{} >&2", in_subshell(&codex_script())),
         ));
     }
     if let Some(title) = title {
         stages.push(
             Stage::new(
                 TITLE_STAGE,
-                // Several statements, so a nested `bash -c` for the reason the
+                // Several statements, so a subshell for the reason the
                 // zellij stage has one: a stage is interpolated into
                 // `if <command>; then`, which is one line. The profile is resolved
                 // and appended to exactly as the PATH writers do it, so every edit
@@ -2020,16 +2037,13 @@ pub(crate) fn setup_stages(
                 // `DEVLAUNCH_NO_TITLE` is the honest owner of all three. Somebody
                 // who turned dl's naming off did not ask for claude's to go with
                 // it, and nothing in a container would tell them why it had.
-                format!(
-                    "bash -c {}",
-                    quote(
-                        &[
-                            profile_resolution("$HOME"),
-                            profile_prepend(&profile_title_line(title), None),
-                            profile_prepend(CLAUDE_TITLE_EXPORT, None),
-                        ]
-                        .join("\n")
-                    )
+                in_subshell(
+                    &[
+                        profile_resolution("$HOME"),
+                        profile_prepend(&profile_title_line(title), None),
+                        profile_prepend(CLAUDE_TITLE_EXPORT, None),
+                    ]
+                    .join("\n"),
                 ),
             )
             // Quieter for the hostname stage's reason: an image that will not let
@@ -2047,7 +2061,7 @@ pub(crate) fn setup_stages(
     // reaches its login screen because there is no credential rather than because
     // a flag was missing.
     //
-    // A nested `bash -c` for the zellij stage's reason: a stage is interpolated into
+    // In a subshell for the zellij stage's reason: a stage is interpolated into
     // `if <command>; then`, which is one line, and this script is not. Not
     // redirected, unlike that one, because nothing in this script writes to
     // *stdout*, which is the stream the outcome protocol shares. `mkdir` and the
@@ -2055,21 +2069,18 @@ pub(crate) fn setup_stages(
     // complaint belongs.
     stages.push(Stage::new(
         ONBOARDING_STAGE,
-        format!("bash -c {}", quote(&onboarding_script())),
+        in_subshell(&onboarding_script()),
     ));
     // Behind the seed and gated on nothing either, for the seed's reasons and one of
     // its own: the two write the same file, and this one is the half that reaches a
     // file already there. Behind, so that a file the seed just created is found here
     // with the entry already in it and this exits without a second write.
     //
-    // A nested `bash -c` for the zellij stage's reason, and unredirected for the
+    // In a subshell for the zellij stage's reason, and unredirected for the
     // seed's: nothing in this script writes to stdout, which is the stream the
     // outcome protocol shares, and python3's complaint about a file it could not
     // write belongs on stderr where a stage's complaints go.
-    stages.push(Stage::new(
-        TRUST_STAGE,
-        format!("bash -c {}", quote(&trust_script())),
-    ));
+    stages.push(Stage::new(TRUST_STAGE, in_subshell(&trust_script())));
     stages
 }
 
@@ -3413,6 +3424,10 @@ grep -qxF '# devlaunch: 63c662ba0560' "$PROFILE" 2>/dev/null || printf '%s\n' '#
     /// The hostname stage's snippet, and the zellij stage's — the second carrying a
     /// whole quoted script, which is where Python's `shlex.quote` and the `shlex`
     /// crate's disagree about bytes and this module's [`quote`] does not.
+    ///
+    /// The zellij stage's bytes are Python's quoting of its script, inside the
+    /// `( eval … )` that replaced Python's `bash -c` (see [`in_subshell`]). The
+    /// quoted word is the part these goldens exist for, and it has not moved.
     const PYTHON_HOSTNAME_STAGE: &str = r#"if sudo hostname myws; then
   echo "devlaunch-probe stage hostname ok"
 else
@@ -3421,11 +3436,11 @@ fi"#;
 
     /// The session-name stage's snippet for `myws`, spelled out. Not a `PYTHON_`
     /// golden: the stage is newer than the Python tree.
-    const SESSION_NAME_STAGE_SNIPPET: &str = r#"if bash -c 'if [ -f "$HOME/.bash_profile" ]; then PROFILE="$HOME/.bash_profile"
+    const SESSION_NAME_STAGE_SNIPPET: &str = r#"if ( eval 'if [ -f "$HOME/.bash_profile" ]; then PROFILE="$HOME/.bash_profile"
 elif [ -f "$HOME/.bash_login" ]; then PROFILE="$HOME/.bash_login"
 else PROFILE="$HOME/.profile"
 fi
-grep -qxF '"'"'# devlaunch: 52224b6588f3'"'"' "$PROFILE" 2>/dev/null || printf '"'"'%s\n'"'"' '"'"'# devlaunch: 52224b6588f3'"'"' '"'"'export CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX=myws'"'"' >> "$PROFILE"'; then
+grep -qxF '"'"'# devlaunch: 52224b6588f3'"'"' "$PROFILE" 2>/dev/null || printf '"'"'%s\n'"'"' '"'"'# devlaunch: 52224b6588f3'"'"' '"'"'export CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX=myws'"'"' >> "$PROFILE"' ); then
   echo "devlaunch-probe stage session-name ok"
 else
   echo "devlaunch-probe stage session-name failed $?"
@@ -3436,7 +3451,7 @@ fi"#;
     /// and the reason it is a literal anyway is the reason those are — it carries a
     /// whole quoted script, so a quoting layer that merely *worked* would change
     /// these bytes without failing anything else.
-    const ONBOARDING_STAGE_SNIPPET: &str = r#"if bash -c 'set -u
+    const ONBOARDING_STAGE_SNIPPET: &str = r#"if ( eval 'set -u
 dir="${CLAUDE_CONFIG_DIR:-}"
 if [ -z "$dir" ]; then
   dir="${HOME:-}"
@@ -3456,7 +3471,7 @@ if [ -n "$ws" ]; then
   printf '"'"'{"hasCompletedOnboarding":true,"projects":{"%s":{"hasTrustDialogAccepted":true}}}\n'"'"' "$ws" > "$dir/.claude.json"
 else
   printf '"'"'%s\n'"'"' '"'"'{"hasCompletedOnboarding":true}'"'"' > "$dir/.claude.json"
-fi'; then
+fi' ); then
   echo "devlaunch-probe stage onboarding ok"
 else
   echo "devlaunch-probe stage onboarding failed $?"
@@ -3466,7 +3481,7 @@ fi"#;
     /// and with more riding on it: this one carries a Python program through two
     /// quoting layers, so it is the place in this module where a quoting change is
     /// likeliest to be silently survivable and least likely to be harmless.
-    const TRUST_STAGE_SNIPPET: &str = r#"if bash -c 'set -u
+    const TRUST_STAGE_SNIPPET: &str = r#"if ( eval 'set -u
 dir="${CLAUDE_CONFIG_DIR:-}"
 if [ -z "$dir" ]; then
   dir="${HOME:-}"
@@ -3528,13 +3543,13 @@ except OSError:
             pass
     sys.exit(0)
 '"'"'
-python3 -c "$prog" "$file" "$ws"'; then
+python3 -c "$prog" "$file" "$ws"' ); then
   echo "devlaunch-probe stage trust ok"
 else
   echo "devlaunch-probe stage trust failed $?"
 fi"#;
 
-    const PYTHON_ZELLIJ_STAGE: &str = r#"if bash -c 'set -u
+    const PYTHON_ZELLIJ_STAGE: &str = r#"if ( eval 'set -u
 failed=0
 if command -v zellij >/dev/null 2>&1; then exit 0; fi
 export PIXI_HOME="$HOME/.devlaunch/pixi"
@@ -3552,7 +3567,7 @@ elif [ -f "$HOME/.bash_login" ]; then PROFILE="$HOME/.bash_login"
 else PROFILE="$HOME/.profile"
 fi
 grep -qxF '"'"'# devlaunch: 87ccd356540b'"'"' "$PROFILE" 2>/dev/null || printf '"'"'%s\n'"'"' '"'"'# devlaunch: 87ccd356540b'"'"' '"'"'export PATH="$HOME/.devlaunch/pixi/bin:$PATH"'"'"' >> "$PROFILE" || failed=1
-exit "$failed"' >&2; then
+exit "$failed"' ) >&2; then
   echo "devlaunch-probe stage zellij ok"
 else
   echo "devlaunch-probe stage zellij failed $?"
@@ -4430,7 +4445,7 @@ fi
     }
 
     #[test]
-    fn the_codex_stage_is_one_word_the_pass_shell_hands_to_a_nested_bash() {
+    fn the_codex_stage_is_one_word_the_pass_shell_evals_in_a_subshell() {
         let stages = setup_stages(
             "myws",
             ToolsSwitch::Install,
@@ -4447,9 +4462,10 @@ fi
         assert_eq!(
             words,
             vec![
-                "bash".to_owned(),
-                "-c".to_owned(),
+                "(".to_owned(),
+                "eval".to_owned(),
                 codex_script(),
+                ")".to_owned(),
                 // The stage redirects itself, because it cannot be redirected from
                 // outside: `stage_snippet` interpolates it into `if <command>; then`.
                 ">&2".to_owned(),
@@ -4458,9 +4474,9 @@ fi
     }
 
     #[test]
-    fn the_zellij_stage_is_one_word_the_pass_shell_hands_to_a_nested_bash() {
+    fn the_zellij_stage_is_one_word_the_pass_shell_evals_in_a_subshell() {
         // The stage is interpolated into `if <command>; then`, so the quoting has to
-        // survive being read by the *pass's* shell before the nested bash sees it.
+        // survive being read by the *pass's* shell before `eval` reads it again.
         let stages = setup_stages(
             "myws",
             ToolsSwitch::Install,
@@ -4477,9 +4493,10 @@ fi
         assert_eq!(
             words,
             vec![
-                "bash".to_owned(),
-                "-c".to_owned(),
+                "(".to_owned(),
+                "eval".to_owned(),
                 zellij_script(),
+                ")".to_owned(),
                 ">&2".to_owned(),
             ]
         );
@@ -5499,9 +5516,9 @@ fi
     }
 
     #[test]
-    fn the_claude_config_stages_are_one_word_the_pass_shell_hands_to_a_nested_bash() {
+    fn the_claude_config_stages_are_one_word_the_pass_shell_evals_in_a_subshell() {
         // The zellij stage's property, for the zellij stage's reason: the quoting has
-        // to survive being read by the *pass's* shell before the nested bash sees a
+        // to survive being read by the *pass's* shell before `eval` reads a
         // script with quotes and braces of its own in it. The trust stage asks more of
         // it than any other — its script carries a Python program, itself
         // single-quoted, inside the single-quoted script.
@@ -5523,7 +5540,7 @@ fi
                 .command;
             assert_eq!(
                 shlex::split(command).expect("a stage a shell can read"),
-                vec!["bash".to_owned(), "-c".to_owned(), script],
+                vec!["(".to_owned(), "eval".to_owned(), script, ")".to_owned()],
                 "{}",
                 name.as_str()
             );
@@ -6765,6 +6782,65 @@ fi
         .find(|outcome| outcome.stage == stage)
     }
 
+    #[test]
+    fn the_pass_reads_the_images_bash_env_once_however_many_stages_it_runs() {
+        // A non-interactive bash sources `$BASH_ENV` on startup, and an image may
+        // point it at a whole ROS bashrc: kinisi_ros's does, at about a second a
+        // read inside a `devpod ssh` session. A stage that started its own bash
+        // paid that again, four or five times a cold launch. The stages run in
+        // subshells of the pass, so the one read is the pass's own.
+        let scratch = scratch();
+        let home = a_home(scratch.path());
+        let sysbin = sysbin(scratch.path(), &["readlink", "bash", "mkdir", "pwd"]);
+        let reads = scratch.path().join("bash-env-reads");
+        let bash_env = scratch.path().join("bash-env");
+        fs::write(
+            &bash_env,
+            format!("echo read >> \"{}\"\n", reads.to_string_lossy()),
+        )
+        .expect("a BASH_ENV");
+        let stages = setup_stages(
+            "myws",
+            ToolsSwitch::Install,
+            ZellijSwitch::Skip,
+            CodexSwitch::Skip,
+            Some("my-title"),
+        );
+        let ran = bash_with(
+            &setup_script(&stages),
+            &[
+                ("HOME", &home.to_string_lossy()),
+                ("PATH", &sysbin.to_string_lossy()),
+                ("BASH_ENV", &bash_env.to_string_lossy()),
+            ],
+        );
+        assert!(
+            ran.status.success(),
+            "{}",
+            String::from_utf8_lossy(&ran.stderr)
+        );
+        let report = String::from_utf8_lossy(&ran.stdout);
+        // Every stage still reports, so the count below is not one because the
+        // stages stopped running.
+        for stage in &stages {
+            assert!(
+                report.contains(&format!(
+                    "{PROBE_MARK} {STAGE_KEY} {} ",
+                    stage.name.as_str()
+                )),
+                "{} did not report:\n{report}",
+                stage.name.as_str()
+            );
+        }
+        let read = fs::read_to_string(&reads).expect("the pass read BASH_ENV");
+        assert_eq!(
+            read.lines().count(),
+            1,
+            "BASH_ENV was read {} times",
+            read.lines().count()
+        );
+    }
+
     #[test]
     fn a_real_bash_over_the_pass_calls_hostname_with_the_whole_id() {
         // The derivation through a real shell, reading what `hostname` was actually
diff --git a/rust/dl/tests/setup_pass_shells.rs b/rust/dl/tests/setup_pass_shells.rs
new file mode 100644
index 00000000..4cf2076e
--- /dev/null
+++ b/rust/dl/tests/setup_pass_shells.rs
@@ -0,0 +1,194 @@
+//! How many shells a cold launch's setup pass starts inside the container.
+//!
+//! The pass is one `devpod ssh --command` trip carrying dl's stages and then the
+//! probe. Every new bash in it reads the image's `$BASH_ENV`, and an image may point
+//! that at a whole ROS bashrc: kinisi_ros's does, at about 1.1s a read inside a
+//! `devpod ssh` session. When each stage was a nested `bash -c`, a cold launch paid
+//! that read once for the pass and once more per stage, 11s for the trip where 6.7s
+//! does the same work. The stages now run in subshells of the pass.
+//!
+//! The core suite pins the script (`flows::provision`'s
+//! `the_pass_reads_the_images_bash_env_once_however_many_stages_it_runs`). This
+//! one pins the launch: the real `dl` binary, a cold `up`, and a `devpod` whose
+//! `ssh --command` runs the command it was handed under a `BASH_ENV` that counts
+//! its reads, the way the container's shell would.
+//!
+//! Linux-only, like `dl/tests/resumed_setup.rs`, whose cold world this borrows.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use devlaunch_test_support::KeepingCoverage;
+
+fn repo_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("..")
+        .join("..")
+        .canonicalize()
+        .expect("the repository root")
+}
+
+struct World {
+    root: PathBuf,
+    _scratch: tempfile::TempDir,
+}
+
+impl World {
+    /// The cold world `dl/tests/launch.rs` builds, with a `devpod` that runs the
+    /// setup pass's command for real.
+    ///
+    /// The scenario's fake devpod answers `ssh` by exiting 0 and runs nothing, so a
+    /// count over it would be zero whatever the pass sent. This wrapper runs the
+    /// `--command` through `sh -c`, as devpod's ssh server hands it to the user's
+    /// shell, and then lets the fake keep its own books.
+    fn cold() -> Self {
+        let scratch = tempfile::Builder::new()
+            .prefix("dlshells")
+            .tempdir_in("/tmp")
+            .expect("a scratch directory under /tmp");
+        let root = scratch.path().to_path_buf();
+        let built = Command::new("python3")
+            .arg(Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/launch_scenario.py"))
+            .arg(&root)
+            .arg(repo_root().join("test/fixtures/devpod_shim.py"))
+            .output()
+            .expect("python3 is installed");
+        assert!(
+            built.status.success(),
+            "launch_scenario.py failed: {}",
+            String::from_utf8_lossy(&built.stderr)
+        );
+
+        let devpod = root.join("bin/devpod");
+        let original = std::fs::read_to_string(&devpod).expect("the scenario's devpod");
+        let delegate = original
+            .lines()
+            .find(|line| line.starts_with("exec "))
+            .expect("the delegate exec line");
+        let run = delegate.strip_prefix("exec ").expect("an exec line");
+        // The `up` half is `resumed_setup.rs`'s: devpod's create records, which the
+        // launch reads on the way to the pass.
+        let script = format!(
+            "#!/bin/sh\n\
+             if [ \"$1\" = \"up\" ]; then\n\
+             \x20 {run} \"$@\" || exit $?\n\
+             \x20 ws=$2; prev=\n\
+             \x20 for a in \"$@\"; do\n\
+             \x20   if [ \"$prev\" = \"--id\" ]; then ws=$a; fi\n\
+             \x20   prev=$a\n\
+             \x20 done\n\
+             \x20 d=\"$DEVPOD_HOME/contexts/default/workspaces/$ws\"\n\
+             \x20 mkdir -p \"$d\"\n\
+             \x20 printf '{{}}' > \"$d/workspace.json\"\n\
+             \x20 printf '{{}}' > \"$d/workspace_result.json\"\n\
+             \x20 exit 0\n\
+             fi\n\
+             if [ \"$1\" = \"ssh\" ]; then\n\
+             \x20 cmd=; prev=\n\
+             \x20 for a in \"$@\"; do\n\
+             \x20   if [ \"$prev\" = \"--command\" ]; then cmd=$a; fi\n\
+             \x20   prev=$a\n\
+             \x20 done\n\
+             \x20 if [ -n \"$cmd\" ]; then\n\
+             \x20   {run} \"$@\" >/dev/null || exit $?\n\
+             \x20   BASH_ENV=\"$DL_BASH_ENV\" exec sh -c \"$cmd\"\n\
+             \x20 fi\n\
+             fi\n\
+             {delegate}\n"
+        );
+        std::fs::write(&devpod, script).expect("rewrite devpod");
+        // The hostname stage runs `sudo hostname <id>`, and the test host's sudo
+        // must neither prompt nor rename the machine running the suite.
+        let sudo = root.join("bin/sudo");
+        std::fs::write(&sudo, "#!/bin/sh\nexit 0\n").expect("a fake sudo");
+        let reads = root.join("bash-env-reads");
+        std::fs::write(
+            root.join("bash-env"),
+            format!("echo read >> \"{}\"\n", reads.display()),
+        )
+        .expect("a counting BASH_ENV");
+        use std::os::unix::fs::PermissionsExt as _;
+        for program in [&devpod, &sudo] {
+            std::fs::set_permissions(program, std::fs::Permissions::from_mode(0o755))
+                .expect("keep it executable");
+        }
+
+        World {
+            root,
+            _scratch: scratch,
+        }
+    }
+
+    fn path(&self, relative: &str) -> PathBuf {
+        self.root.join(relative)
+    }
+
+    /// A cold `dl blooop/devlaunch@cold`, run to completion.
+    ///
+    /// `DEVLAUNCH_NO_TOOLS` so the pass carries its stages and the probe and stops
+    /// there: the stages are not tools work, so they all still run, and the lend
+    /// and the network install that would follow do not.
+    fn launched(&self) -> String {
+        let root = self.root.display().to_string();
+        let done = Command::new(env!("CARGO_BIN_EXE_dl"))
+            .arg("blooop/devlaunch@cold")
+            .env_clear()
+            .keeping_coverage()
+            .env("PATH", format!("{root}/bin:/usr/bin:/bin"))
+            .env("HOME", format!("{root}/home"))
+            .env("XDG_CACHE_HOME", format!("{root}/cache"))
+            .env("XDG_CONFIG_HOME", format!("{root}/config"))
+            .env("DEVPOD_HOME", format!("{root}/devpod"))
+            .env("DEVPOD_SHIM_STATE", format!("{root}/shim-state.json"))
+            .env("DEVPOD_SHIM_LOG", format!("{root}/shim-log.jsonl"))
+            .env("DEVPOD_SHIM_CONFIG", format!("{root}/shim-config.json"))
+            .env("DEVLAUNCH_NO_GH_TOKEN", "1")
+            .env("DEVLAUNCH_NO_TOOLS", "1")
+            .env("DL_BASH_ENV", self.path("bash-env").display().to_string())
+            .env("GIT_SSH_COMMAND", "false")
+            .env("GIT_CONFIG_GLOBAL", "/dev/null")
+            .env("GIT_CONFIG_SYSTEM", "/dev/null")
+            .output()
+            .expect("the dl binary runs");
+        assert!(
+            done.status.success(),
+            "dl failed ({:?}): {}",
+            done.status.code(),
+            String::from_utf8_lossy(&done.stderr)
+        );
+        String::from_utf8_lossy(&done.stderr).into_owned()
+    }
+
+    fn bash_env_reads(&self) -> usize {
+        std::fs::read_to_string(self.path("bash-env-reads"))
+            .unwrap_or_default()
+            .lines()
+            .count()
+    }
+}
+
+#[test]
+fn a_cold_launch_reads_the_images_bash_env_once_for_the_whole_setup_pass() {
+    let world = World::cold();
+    let said = world.launched();
+
+    // The pass reached the container and every stage reported back: a stage that
+    // never ran reads nothing, so a count of one is only worth something beside a
+    // pass with nothing missing from it.
+    assert!(
+        !said.contains("not reached") && !said.contains("did not finish"),
+        "the setup pass did not run whole: {said}"
+    );
+    assert!(
+        world.path("home/.claude.json").exists(),
+        "the onboarding stage did not run, so the count proves nothing: {said}"
+    );
+    // One read: the pass's own `bash -lc`. Each stage that started a bash of its
+    // own read it again.
+    assert_eq!(
+        world.bash_env_reads(),
+        1,
+        "the setup pass read BASH_ENV {} times: {said}",
+        world.bash_env_reads()
+    );
+}

From 17b7340d4b4d26a5104a62c9627c036509a3445a Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Mon, 12 Oct 2026 18:15:50 +0100
Subject: [PATCH 2/9] docs: the setup pass comments and docs say four stages
 and 4.2s, as measured

---
 docs/performance.md                        |  4 ++--
 rust/devlaunch-core/src/flows/provision.rs | 21 +++++++++++++++------
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/docs/performance.md b/docs/performance.md
index 542207c0..a53b394e 100644
--- a/docs/performance.md
+++ b/docs/performance.md
@@ -132,8 +132,8 @@ Measured on 2026-10-12, on one host with the local docker provider and devpod
 0.26.3, over six cold launches of `kinisi-robotics/kinisi_ros` on six fresh
 branches. With a `bash -c` per stage the trip took 10.90s to 11.14s. With
 subshells it took 6.66s to 6.90s, so about 4.2s comes off every cold launch of
-that repo. An image with no `$BASH_ENV` saves a few milliseconds, because there
-was nothing to read. A warm launch makes no setup trip, so it is not affected.
+that repo. The saving on an image with no `$BASH_ENV` is not measured. It should
+be the cost of starting a bash per stage, which is small. A warm launch makes no setup trip, so it is not affected.
 
 `the_pass_reads_the_images_bash_env_once_however_many_stages_it_runs` and
 `dl/tests/setup_pass_shells.rs` pin the count at one read per pass.
diff --git a/rust/devlaunch-core/src/flows/provision.rs b/rust/devlaunch-core/src/flows/provision.rs
index aadd129c..349a7bbc 100644
--- a/rust/devlaunch-core/src/flows/provision.rs
+++ b/rust/devlaunch-core/src/flows/provision.rs
@@ -27,7 +27,8 @@
 //!    ticket of its own.
 //! 2. **A quoting layer.** The scripts are interpolated into `devpod ssh
 //!    --command`, and one of them is interpolated into another (the zellij stage
-//!    is a `bash -c <script>` inside the setup pass). [`quote`] is CPython's
+//!    runs as `( eval <script> )` in a subshell of the setup pass, see
+//!    [`in_subshell`]). [`quote`] is CPython's
 //!    `shlex.quote`, reproduced rather than delegated — see its own note.
 //! 3. **A three-trip flow.** [`provision_tools`] probes, lends and installs, and
 //!    each trip earns the next: a provisioned workspace pays one, a lendable or
@@ -1887,9 +1888,17 @@ impl Stage {
 /// A subshell and not a nested `bash -c`, because a new bash reads `$BASH_ENV`
 /// when it starts and the subshell does not. An image may point that variable at
 /// a whole ROS bashrc: kinisi_ros's does, and inside a `devpod ssh` session one
-/// read costs about 1.1s, so five stages that each started a bash cost a cold
-/// launch about 4.4s for nothing. The subshell inherits the environment the pass
-/// already loaded, which is the environment the stages were reading anyway.
+/// read costs about 1.1s. A default cold launch there runs four stages (session
+/// name, title, onboarding and trust; zellij and codex are off by default), and
+/// a bash for each made the setup trip about 4.2s slower, measured over six cold
+/// launches. The subshell inherits the environment the pass already loaded,
+/// which is the environment the stages were reading anyway.
+///
+/// The trade: a function or alias that the login profile defines now reaches the
+/// stages, where a nested bash did not get profile functions. A profile `zellij()`
+/// wrapper, for example, makes `command -v zellij` succeed, so the stage skips
+/// its install. That is accepted as unlikely, because a profile wrapper with no
+/// binary behind it is rare.
 ///
 /// `eval` of one quoted word, rather than the script pasted between parentheses,
 /// keeps what the nested bash gave each stage: the script is parsed when the stage
@@ -6785,9 +6794,9 @@ fi
     #[test]
     fn the_pass_reads_the_images_bash_env_once_however_many_stages_it_runs() {
         // A non-interactive bash sources `$BASH_ENV` on startup, and an image may
-        // point it at a whole ROS bashrc: kinisi_ros's does, at about a second a
+        // point it at a whole ROS bashrc: kinisi_ros's does, at about 1.1s a
         // read inside a `devpod ssh` session. A stage that started its own bash
-        // paid that again, four or five times a cold launch. The stages run in
+        // paid that again, four times on a default cold launch. The stages run in
         // subshells of the pass, so the one read is the pass's own.
         let scratch = scratch();
         let home = a_home(scratch.path());

From 08dc0a21732e066fc1171d61af3f8e13bba343af Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Mon, 12 Oct 2026 18:16:08 +0100
Subject: [PATCH 3/9] test: a stage that will not parse, or sets -u and -C,
 keeps it to itself

---
 rust/devlaunch-core/src/flows/provision.rs | 87 ++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/rust/devlaunch-core/src/flows/provision.rs b/rust/devlaunch-core/src/flows/provision.rs
index 349a7bbc..2c7de36f 100644
--- a/rust/devlaunch-core/src/flows/provision.rs
+++ b/rust/devlaunch-core/src/flows/provision.rs
@@ -6850,6 +6850,93 @@ fi
         );
     }
 
+    /// Two stages that exist only to be run here.
+    const FIRST_STAGE: StageName = StageName::new("first");
+    const SECOND_STAGE: StageName = StageName::new("second");
+
+    /// Run `stages` as a whole pass on a stripped PATH, and return its report.
+    fn run_stages(scratch: &Path, stages: &[Stage]) -> String {
+        let home = a_home(scratch);
+        let sysbin = sysbin(scratch, &["readlink"]);
+        let ran = bash_with(
+            &setup_script(stages),
+            &[
+                ("HOME", &home.to_string_lossy()),
+                ("PATH", &sysbin.to_string_lossy()),
+            ],
+        );
+        assert!(
+            ran.status.success(),
+            "{}",
+            String::from_utf8_lossy(&ran.stderr)
+        );
+        String::from_utf8_lossy(&ran.stdout).into_owned()
+    }
+
+    #[test]
+    fn a_stage_that_will_not_parse_fails_alone_and_the_pass_goes_on() {
+        let scratch = scratch();
+        let stages = [
+            Stage::new(FIRST_STAGE, in_subshell("if then")),
+            Stage::new(SECOND_STAGE, in_subshell("true")),
+        ];
+        let report = run_stages(scratch.path(), &stages);
+        assert_eq!(
+            stage_outcomes(&report, &stages),
+            vec![
+                StageOutcome {
+                    stage: FIRST_STAGE,
+                    result: StageResult::Failed { status: 2 },
+                },
+                StageOutcome {
+                    stage: SECOND_STAGE,
+                    result: StageResult::Ok,
+                },
+            ],
+            "{report}"
+        );
+        assert!(
+            report.contains(&format!("{PROBE_MARK} tools ")),
+            "the probe did not answer:\n{report}"
+        );
+    }
+
+    #[test]
+    fn a_stage_that_sets_u_and_c_keeps_them_to_itself() {
+        let scratch = scratch();
+        let existing = scratch.path().join("existing");
+        fs::write(&existing, "old\n").expect("a file to overwrite");
+        let stages = [
+            Stage::new(FIRST_STAGE, in_subshell("set -uC; true")),
+            Stage::new(
+                SECOND_STAGE,
+                in_subshell(&format!(
+                    "echo \"$unset_var\" >/dev/null\necho new > {}",
+                    quote(&existing.to_string_lossy())
+                )),
+            ),
+        ];
+        let report = run_stages(scratch.path(), &stages);
+        assert_eq!(
+            stage_outcomes(&report, &stages),
+            vec![
+                StageOutcome {
+                    stage: FIRST_STAGE,
+                    result: StageResult::Ok,
+                },
+                StageOutcome {
+                    stage: SECOND_STAGE,
+                    result: StageResult::Ok,
+                },
+            ],
+            "{report}"
+        );
+        assert_eq!(
+            fs::read_to_string(&existing).expect("the file is still there"),
+            "new\n"
+        );
+    }
+
     #[test]
     fn a_real_bash_over_the_pass_calls_hostname_with_the_whole_id() {
         // The derivation through a real shell, reading what `hostname` was actually

From 38831611ae38e994f884805c6f5ca4e2ecf21642 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Thu, 15 Oct 2026 15:02:15 +0100
Subject: [PATCH 4/9] docs: Describe the BASH_ENV case without naming one repo

---
 CHANGELOG.md                               | 11 ++++++-----
 docs/performance.md                        | 13 +++++++------
 rust/devlaunch-core/src/flows/provision.rs | 15 ++++++++-------
 rust/dl/tests/setup_pass_shells.rs         |  4 ++--
 4 files changed, 23 insertions(+), 20 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8e21ac66..3ee9ee48 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,11 +11,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **A cold launch's setup pass starts one shell, not one per stage.** Each stage (session
   name, zellij, codex, title, onboarding, trust) ran in a nested `bash -c`, and every new
-  bash reads the image's `$BASH_ENV`. kinisi_ros points that at its whole ROS bashrc, about
-  1.1s a read inside `devpod ssh`, so the trip took about 11s. The stages now run in
-  subshells of the pass (`( eval '<script>' )`), which keep each stage's `exit`, `set -u`
-  and parse errors to itself as the nested bash did. Measured over six cold kinisi_ros
-  launches, the setup trip went from 10.9s to 11.1s down to 6.7s to 6.9s.
+  bash reads the image's `$BASH_ENV`. An image that points it at a heavy shell profile
+  (for example a ROS environment) can pay about 1.1s a read inside `devpod ssh`, so the
+  trip took about 11s. The stages now run in subshells of the pass
+  (`( eval '<script>' )`), which keep each stage's `exit`, `set -u` and parse errors to
+  itself as the nested bash did. Measured over six cold launches of such an image, the
+  setup trip went from 10.9s to 11.1s down to 6.7s to 6.9s.
 
 ## [0.59.4] - 2026-10-05
 
diff --git a/docs/performance.md b/docs/performance.md
index a53b394e..d90cec3b 100644
--- a/docs/performance.md
+++ b/docs/performance.md
@@ -125,14 +125,15 @@ not be the reason a container never goes idle.
 A cold launch sends one `devpod ssh --command` trip that runs dl's setup stages
 and then the tools probe. Each stage runs in a subshell of that trip's shell, not
 in a `bash` of its own. The reason is `$BASH_ENV`: every new non-interactive bash
-reads it, and an image may point it at a whole ROS bashrc. kinisi_ros's image
-does, and inside a `devpod ssh` session one read costs about 1.1s.
+reads it, and an image may point it at a heavy shell profile (for example a ROS
+environment). On the image measured below, one read inside a `devpod ssh`
+session costs about 1.1s.
 
 Measured on 2026-10-12, on one host with the local docker provider and devpod
-0.26.3, over six cold launches of `kinisi-robotics/kinisi_ros` on six fresh
-branches. With a `bash -c` per stage the trip took 10.90s to 11.14s. With
-subshells it took 6.66s to 6.90s, so about 4.2s comes off every cold launch of
-that repo. The saving on an image with no `$BASH_ENV` is not measured. It should
+0.26.3, over six cold launches of a large ROS repository whose image sets
+`$BASH_ENV`, on six fresh branches. With a `bash -c` per stage the trip took
+10.90s to 11.14s. With subshells it took 6.66s to 6.90s, so about 4.2s comes
+off every cold launch of that repo. The saving on an image with no `$BASH_ENV` is not measured. It should
 be the cost of starting a bash per stage, which is small. A warm launch makes no setup trip, so it is not affected.
 
 `the_pass_reads_the_images_bash_env_once_however_many_stages_it_runs` and
diff --git a/rust/devlaunch-core/src/flows/provision.rs b/rust/devlaunch-core/src/flows/provision.rs
index 2c7de36f..b9d0f171 100644
--- a/rust/devlaunch-core/src/flows/provision.rs
+++ b/rust/devlaunch-core/src/flows/provision.rs
@@ -1887,11 +1887,11 @@ impl Stage {
 ///
 /// A subshell and not a nested `bash -c`, because a new bash reads `$BASH_ENV`
 /// when it starts and the subshell does not. An image may point that variable at
-/// a whole ROS bashrc: kinisi_ros's does, and inside a `devpod ssh` session one
-/// read costs about 1.1s. A default cold launch there runs four stages (session
-/// name, title, onboarding and trust; zellij and codex are off by default), and
-/// a bash for each made the setup trip about 4.2s slower, measured over six cold
-/// launches. The subshell inherits the environment the pass already loaded,
+/// a heavy shell profile (for example a ROS environment). On one such image a
+/// read inside a `devpod ssh` session costs about 1.1s. A default cold launch
+/// runs four stages (session name, title, onboarding and trust; zellij and codex
+/// are off by default), and a bash for each made the setup trip about 4.2s
+/// slower, measured over six cold launches of that image. The subshell inherits the environment the pass already loaded,
 /// which is the environment the stages were reading anyway.
 ///
 /// The trade: a function or alias that the login profile defines now reaches the
@@ -6794,8 +6794,9 @@ fi
     #[test]
     fn the_pass_reads_the_images_bash_env_once_however_many_stages_it_runs() {
         // A non-interactive bash sources `$BASH_ENV` on startup, and an image may
-        // point it at a whole ROS bashrc: kinisi_ros's does, at about 1.1s a
-        // read inside a `devpod ssh` session. A stage that started its own bash
+        // point it at a heavy shell profile (for example a ROS environment).
+        // One such image costs about 1.1s a read inside a `devpod ssh`
+        // session. A stage that started its own bash
         // paid that again, four times on a default cold launch. The stages run in
         // subshells of the pass, so the one read is the pass's own.
         let scratch = scratch();
diff --git a/rust/dl/tests/setup_pass_shells.rs b/rust/dl/tests/setup_pass_shells.rs
index 4cf2076e..af06f224 100644
--- a/rust/dl/tests/setup_pass_shells.rs
+++ b/rust/dl/tests/setup_pass_shells.rs
@@ -2,8 +2,8 @@
 //!
 //! The pass is one `devpod ssh --command` trip carrying dl's stages and then the
 //! probe. Every new bash in it reads the image's `$BASH_ENV`, and an image may point
-//! that at a whole ROS bashrc: kinisi_ros's does, at about 1.1s a read inside a
-//! `devpod ssh` session. When each stage was a nested `bash -c`, a cold launch paid
+//! that at a heavy shell profile (for example a ROS environment). One such image
+//! costs about 1.1s a read inside a `devpod ssh` session. When each stage was a nested `bash -c`, a cold launch paid
 //! that read once for the pass and once more per stage, 11s for the trip where 6.7s
 //! does the same work. The stages now run in subshells of the pass.
 //!

From 66846effe396ed5efb0f447c3eb8e0bb9333be1b Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Thu, 15 Oct 2026 15:05:44 +0100
Subject: [PATCH 5/9] test: the trust stage runs its merge through the setup
 pass

---
 rust/devlaunch-core/src/flows/provision.rs | 50 ++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/rust/devlaunch-core/src/flows/provision.rs b/rust/devlaunch-core/src/flows/provision.rs
index b9d0f171..0ebe8da5 100644
--- a/rust/devlaunch-core/src/flows/provision.rs
+++ b/rust/devlaunch-core/src/flows/provision.rs
@@ -6199,6 +6199,56 @@ fi
         assert_eq!(world.read(), r#"{"hasCompletedOnboarding":true}"#);
     }
 
+    #[test]
+    fn the_setup_pass_records_trust_for_the_workspace_it_stands_in() {
+        let world = TrustWorld::new(Some(r#"{"hasCompletedOnboarding":true}"#));
+        let stages: Vec<Stage> = setup_stages(
+            "devlaunch-nb99-hicj",
+            ToolsSwitch::Skip,
+            ZellijSwitch::Skip,
+            CodexSwitch::Skip,
+            None,
+        )
+        .into_iter()
+        .filter(|stage| stage.name == ONBOARDING_STAGE || stage.name == TRUST_STAGE)
+        .collect();
+        assert_eq!(stages.len(), 2, "both stages are in the pass");
+        let ran = std::process::Command::new("bash")
+            .arg("-c")
+            .arg(setup_script(&stages))
+            .current_dir(&world.workspace)
+            .env("HOME", &world.home)
+            .env_remove("CLAUDE_CONFIG_DIR")
+            .output()
+            .expect("bash ran");
+        assert!(
+            ran.status.success(),
+            "{}",
+            String::from_utf8_lossy(&ran.stderr)
+        );
+        let report = String::from_utf8_lossy(&ran.stdout);
+        assert_eq!(
+            stage_outcomes(&report, &stages),
+            vec![
+                StageOutcome {
+                    stage: ONBOARDING_STAGE,
+                    result: StageResult::Ok,
+                },
+                StageOutcome {
+                    stage: TRUST_STAGE,
+                    result: StageResult::Ok,
+                },
+            ],
+            "{report}\n{}",
+            String::from_utf8_lossy(&ran.stderr)
+        );
+        assert_eq!(world.trusts(&world.keyed), Some(true.into()));
+        assert_eq!(
+            world.parsed().get("hasCompletedOnboarding"),
+            Some(&true.into())
+        );
+    }
+
     #[test]
     fn onboarding_seeds_nothing_when_there_is_no_home_to_seed() {
         // No `CLAUDE_CONFIG_DIR` and no `$HOME` is a container that can say where

From a52b3e9ee4607cabfa9079298837c2e98842ca6a Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Thu, 15 Oct 2026 15:04:23 +0100
Subject: [PATCH 6/9] test: a stage that calls exit ends only itself

---
 rust/devlaunch-core/src/flows/provision.rs | 28 ++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/rust/devlaunch-core/src/flows/provision.rs b/rust/devlaunch-core/src/flows/provision.rs
index 0ebe8da5..622404ad 100644
--- a/rust/devlaunch-core/src/flows/provision.rs
+++ b/rust/devlaunch-core/src/flows/provision.rs
@@ -6952,6 +6952,34 @@ fi
         );
     }
 
+    #[test]
+    fn a_stage_that_calls_exit_ends_only_itself() {
+        let scratch = scratch();
+        let stages = [
+            Stage::new(FIRST_STAGE, in_subshell("exit 3")),
+            Stage::new(SECOND_STAGE, in_subshell("true")),
+        ];
+        let report = run_stages(scratch.path(), &stages);
+        assert_eq!(
+            stage_outcomes(&report, &stages),
+            vec![
+                StageOutcome {
+                    stage: FIRST_STAGE,
+                    result: StageResult::Failed { status: 3 },
+                },
+                StageOutcome {
+                    stage: SECOND_STAGE,
+                    result: StageResult::Ok,
+                },
+            ],
+            "{report}"
+        );
+        assert!(
+            report.contains(&format!("{PROBE_MARK} tools ")),
+            "the probe did not answer:\n{report}"
+        );
+    }
+
     #[test]
     fn a_stage_that_sets_u_and_c_keeps_them_to_itself() {
         let scratch = scratch();

From cf70976df67eb033287b31968cf827ceb3006d26 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Thu, 15 Oct 2026 15:03:54 +0100
Subject: [PATCH 7/9] docs: in_subshell says a stage inherits the pass's
 options and variables

---
 rust/devlaunch-core/src/flows/provision.rs | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/rust/devlaunch-core/src/flows/provision.rs b/rust/devlaunch-core/src/flows/provision.rs
index 622404ad..9c58fc50 100644
--- a/rust/devlaunch-core/src/flows/provision.rs
+++ b/rust/devlaunch-core/src/flows/provision.rs
@@ -1894,11 +1894,14 @@ impl Stage {
 /// slower, measured over six cold launches of that image. The subshell inherits the environment the pass already loaded,
 /// which is the environment the stages were reading anyway.
 ///
-/// The trade: a function or alias that the login profile defines now reaches the
-/// stages, where a nested bash did not get profile functions. A profile `zellij()`
-/// wrapper, for example, makes `command -v zellij` succeed, so the stage skips
-/// its install. That is accepted as unlikely, because a profile wrapper with no
-/// binary behind it is rare.
+/// The trade: a stage does not start in a clean shell. It inherits everything the
+/// login profile left in the pass: shell options (`set -u`, `set -C`,
+/// `pipefail`), unexported and readonly variables, functions and aliases. So a
+/// stage must assign a variable before it reads it (or read it as `${X:-}`), must
+/// not assign a name a profile may make readonly, and must not trust
+/// `command -v` alone: a profile `zellij()` wrapper makes it succeed, so the
+/// stage skips its install. That last case is accepted as unlikely, because a
+/// profile wrapper with no binary behind it is rare.
 ///
 /// `eval` of one quoted word, rather than the script pasted between parentheses,
 /// keeps what the nested bash gave each stage: the script is parsed when the stage

From 745e1aae895aa4381cbd5705139c9a5a02e45f5a Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Thu, 15 Oct 2026 15:04:04 +0100
Subject: [PATCH 8/9] docs: comments no longer describe a nested bash per stage

---
 rust/devlaunch-core/src/flows/provision.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/devlaunch-core/src/flows/provision.rs b/rust/devlaunch-core/src/flows/provision.rs
index 9c58fc50..fe7854c6 100644
--- a/rust/devlaunch-core/src/flows/provision.rs
+++ b/rust/devlaunch-core/src/flows/provision.rs
@@ -1190,7 +1190,7 @@ pub(crate) fn onboarding_script() -> String {
         //
         // `printf` with the JSON as an *argument* in the second, so the stage stays
         // one line's worth of quoting (see [`Stage`]) and no heredoc has to survive
-        // being read by the pass's shell before the nested one sees it. The first
+        // being read by the pass's shell before `eval` reads it again. The first
         // puts the JSON in the *format* and the path in the argument, which is what
         // keeps a path out of the position where it could be read as a format.
         "if [ -n \"$ws\" ]; then".to_owned(),
@@ -1368,7 +1368,7 @@ pub(crate) fn trust_script() -> String {
     lines.extend([
         "if [ -z \"$ws\" ]; then exit 0; fi".to_owned(),
         // The program through a variable rather than inline, so the `-c` argument is
-        // one word to the nested shell whatever the program contains, and the two
+        // one word to `python3` whatever the program contains, and the two
         // paths stay `argv` rather than becoming text in it.
         format!("prog={}", quote(TRUST_MERGE_PY)),
         "python3 -c \"$prog\" \"$file\" \"$ws\"".to_owned(),

From 4981e02e7ffb7b635f417f6fc78c10cd2a3c1b59 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Fri, 16 Oct 2026 13:32:45 +0100
Subject: [PATCH 9/9] docs: the setup-pass entry is unreleased, not part of
 0.60.0

---
 CHANGELOG.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f0a67263..a7698b7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,16 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.60.0] - 2026-10-16
-
-### Added
-
-- **`dla` is a second name for `aid`** (#679). It is easier to type: `dl` and one letter. It is the
-  same program, built from the same source, so it takes the same flags, prints the same
-  messages and answers `dla --version` as `aid <version>`. The wheel, the conda package and
-  `./dev.sh` (as `dla-next`) ship it, and bash completion treats it as `aid`. An existing
-  install gets `dla` completion after it runs `dl --install` again.
-
 ### Changed
 
 - **A cold launch's setup pass starts one shell, not one per stage.** Each stage (session
@@ -28,6 +18,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   itself as the nested bash did. Measured over six cold launches of such an image, the
   setup trip went from 10.9s to 11.1s down to 6.7s to 6.9s.
 
+## [0.60.0] - 2026-10-16
+
+### Added
+
+- **`dla` is a second name for `aid`** (#679). It is easier to type: `dl` and one letter. It is the
+  same program, built from the same source, so it takes the same flags, prints the same
+  messages and answers `dla --version` as `aid <version>`. The wheel, the conda package and
+  `./dev.sh` (as `dla-next`) ship it, and bash completion treats it as `aid`. An existing
+  install gets `dla` completion after it runs `dl --install` again.
+
 ## [0.59.4] - 2026-10-05
 
 ### Fixed