Skip to content

Start investigations through the launcher hub.toml names - #435

Merged
ooloth merged 6 commits into
mainfrom
investigation-launcher
Nov 19, 2026
Merged

ooloth merged 6 commits into
mainfrom
investigation-launcher

Conversation

@ooloth

@ooloth ooloth commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

✅ What

  • A new launcher setting under [investigation] in hub.toml names, by absolute path, a program hub runs in place of claude for every investigation and review; without it, hub runs claude exactly as before
  • hub hands the launcher the same arguments it gave claude, its --permission-mode auto, --strict-mcp-config and system prompt included, so a launcher only has to set things up and pass them on
  • The TUI refuses to start when the launcher can't run, and says which setting and path are wrong, instead of opening tabs that fail. The daemon never launches anything, so it skips that check, but like any malformed hub.toml, a launcher path that isn't absolute still stops it. The e2a5d91 commit message says less than that, so this is the accurate version
  • The TUI checks the launcher again each time i is pressed, so one removed while hub runs shows its error in the status bar instead of opening a tmux window that closes before anyone sees it
  • The hub.toml schema accepts launcher, and decision 034 records the choice and the options it beat
  • To turn it on, a device sets launcher in its own hub.toml; on my work laptop that means adding it to hub-private/devices/work-laptop.toml, which this PR doesn't touch. That waits until a build with this PR is installed, because older builds refuse a hub.toml with keys they don't know, and the installed daemon would stop at its next start
  • See Claude sessions hub starts get the same launch behaviour as cc #434 for detailed explanations of this solution's overall approach and design

🤔 Why

  • On the work laptop, sessions hub started failed with "No projectId was given" whenever Claude Code sessions moved to Vertex AI at the usage limit, because hub ran bare claude and skipped the dotfiles launcher that sets up the Vertex AI project and the work logins
  • Why not just export the project somewhere? hub runs its command through /bin/sh with an explicit environment, so no shell startup file reaches it, and the launcher also runs the logins and keeps one place for all of it
  • Why does hub keep passing its own mode? The dotfiles launcher picks bypass mode on personal Macs, and investigations read text other people wrote, so the mode stays hub's to choose
  • The dotfiles side, which makes the launcher respect a caller's mode and system prompt, shipped in ooloth/dotfiles@2ef2c508 and ooloth/dotfiles@5b445cfe

👩‍🔬 How to verify

  1. 🛠️ Setup

    💻 A build of this branch with a linked device config (every run row)

    • From a checkout of this branch with hub-private set up, build hub:

      just setup-private work-laptop
      just build
    • Keep a copy of the device config so it can be restored, in a folder of its own:

      export HUB_QA="$(mktemp -d)"
      cp -L hub.toml "$HUB_QA/hub.toml.original"
  2. ✨ What's new

    1. 📄 With launcher set to cc.bash, a PR review opened from hub on the work laptop starts with the Vertex AI project in its environment and runs the work logins first

      🧾 Proven by

      • The run below, which shows the session started through cc.bash with the Vertex AI variables set
      • That the logins ran is not visible in the tab, because Claude Code's full screen covers auth's output; the dotfiles tests cover that path, and the launch passed no --unattended
      • The run below used a Rex tab, because my running tmux server started every pane given -c with pwd: .: No such file or directory, so hub never started in it. On a fresh tmux -L server, both main and this branch opened the review's window, so it isn't something this PR does
      • The environment check tells main and this branch apart only in Rex. Before this PR, the same Rex steps printed no Vertex AI keys; a tmux pane can already have them, inherited from the tmux server's environment

      🔍 Verification steps

      • Point the launcher at the dotfiles launcher:

        rm hub.toml
        { cat "$HUB_QA/hub.toml.original"; printf '\n[investigation]\nlauncher = "%s/Repos/ooloth/dotfiles/tools/claude/cc.bash"\n' "$HOME"; } > hub.toml
      • Start hub in a background Rex tab, widen it so the status bar isn't cut off, then press i on a PR row:

        B=$(rex window new "hub 434: proof" --focus=false --keep-open -c "$PWD" --json -- /bin/zsh -c "HUB_PROFILE=dev ./target/debug/hub-tui" | jq -er '.block_ids[0]')
        rex block call -b "$B" resize '{"columns":200,"rows":50}'
        rex send-key -b "$B" i
      • Expect a new tab labelled PR <number> (<author>): investigate

      • Read the new session's flags, which Vertex AI variables its environment has (keys only), and the launcher it ran through:

        N=$(pgrep -n -f "claude .*--strict-mcp-config")
        ps -p $N -ww -o command= | tr ' ' '\n' | grep -E '^(claude|--[a-z-]+)$' | head -12 | tr '\n' ' '
        ps -p $N -wwE -o command= | tr ' ' '\n' | grep -oE '^(ANTHROPIC_VERTEX_PROJECT_ID|CLOUD_ML_REGION|PRIVATE_VERTEX_PROJECT|HUB_LAUNCHER|CLAUDE_CODE_USE_VERTEX)=' | sort -u
        ps -p $N -wwE -o command= | tr ' ' '\n' | grep '^HUB_LAUNCHER='
        ps -p $N -ww -o command= | grep -oE -- '--permission-mode [a-zA-Z]+|--append-system-prompt-file'

      👀 What I saw

      • The tab hub opened:

        PR 1862 (dependabot): investigate
        
      • Its flags:

        claude --permission-mode --strict-mcp-config --mcp-config --model --append-system-prompt
        
      • Its environment's keys, then the launcher it ran through:

        ANTHROPIC_VERTEX_PROJECT_ID=
        CLOUD_ML_REGION=
        HUB_LAUNCHER=
        PRIVATE_VERTEX_PROJECT=
        HUB_LAUNCHER=/Users/michael.uloth/Repos/ooloth/dotfiles/tools/claude/cc.bash
        
      • Its mode, with no --append-system-prompt-file, since this worktree has no related-repo hints:

        --permission-mode auto
        
    2. 📄 While sessions use Vertex AI, that review runs instead of failing with "No projectId"

      🧾 Proven by

      • Not run end to end: moving sessions to Vertex AI moves every Claude Code session open on the machine
      • The failure this fixes was the missing ANTHROPIC_VERTEX_PROJECT_ID, which the run in the row above shows is now set; sessions started with cc run on Vertex AI with the same two variables

      🔍 Verification steps

      • With the setup from the row above, run cc-switch vertex, press i on a PR row, and expect the new session to answer instead of showing "No projectId was given"
      • Run cc-switch subscription to move sessions back

      👀 What I saw

      • Not run, for the reason under Proven by
    3. 📄 A launcher that can't run stops hub at start with a message naming the setting

      🧾 Proven by

      • The run below
      • In CI, a_launcher_that_cant_run_is_refused_naming_the_setting_and_path (a missing file, a folder, a file with no execute bit) and a_launcher_that_is_not_absolute_is_rejected_naming_the_setting

      🔍 Verification steps

      • Point the launcher at a path that doesn't exist and start hub:

        rm hub.toml
        { cat "$HUB_QA/hub.toml.original"; printf '\n[investigation]\nlauncher = "/nonexistent/cc.bash"\n'; } > hub.toml
        HUB_PROFILE=dev ./target/debug/hub-tui; echo EXIT=$?
      • Expect hub to exit before drawing anything, naming [investigation] launcher and the path

      👀 What I saw

      • Error: [investigation] launcher "/nonexistent/cc.bash" in hub.toml can't run
        
        Caused by:
            No such file or directory (os error 2)
        EXIT=1
        
    4. 📄 A launcher removed while hub runs shows its error in the status bar when i is pressed, and opens no window or worktree, in tmux and in Rex

      🧾 Proven by

      • The runs below, in a fresh tmux server and in a Rex tab, each pressing i once with the launcher present and once after deleting it
      • In CI, a_launch_whose_launcher_no_longer_runs_is_refused_naming_the_setting_and_path, plus loading_refuses_a_launcher_that_cant_run_naming_the_setting_and_path and the two reading_ tests for the startup and daemon paths

      🔍 Verification steps

      • Make a launcher that records its arguments and stays open for 25 seconds, and a config that names it:

        mkdir -p "$HUB_QA/run" "$HUB_QA/launchers"
        printf '#!/bin/sh\nprintf "%%s\\n" "$@" > %s/argv.txt\nsleep 25\n' "$HUB_QA" > "$HUB_QA/launchers/rec.sh"
        chmod 755 "$HUB_QA/launchers/rec.sh"
        { cat "$HUB_QA/hub.toml.original"; printf '\n[investigation]\nlauncher = "%s/launchers/rec.sh"\n' "$HUB_QA"; } > "$HUB_QA/run/hub.toml"
      • Start hub in a fresh tmux server and press i on a PR row:

        tmux -L hubqa435 -f /dev/null new-session -d -s qa -n tui -x 320 -y 50 -c "$HUB_QA/run" "HUB_PROFILE=dev $PWD/target/debug/hub-tui"
        tmux -L hubqa435 -f /dev/null send-keys -t qa:tui i
        tmux -L hubqa435 -f /dev/null list-panes -s -t qa -F '#{window_name} :: #{pane_start_command}'
        head -3 "$HUB_QA/argv.txt"
      • Expect a second window named after the PR, and the launcher's first arguments to be --permission-mode, auto, --strict-mcp-config

      • Once that window has closed, delete the launcher, press i again, and read the windows, the status bar and the investigation worktrees:

        rm "$HUB_QA/launchers/rec.sh"
        tmux -L hubqa435 -f /dev/null send-keys -t qa:tui i
        tmux -L hubqa435 -f /dev/null list-windows -t qa -F '#{window_name}'
        tmux -L hubqa435 -f /dev/null capture-pane -t qa:tui -p | tail -1
        find ~/.hub/repos -mindepth 2 -maxdepth 2 -name 'investigation-*'
      • Expect only the tui window, the error in the status bar, and no new worktree

      • Repeat both presses in a Rex tab sized 320×50, following the Rex loop in AGENTS.md, and expect Opened in Workers (<repo>) then the same error with no new tab

      • Run tmux -L hubqa435 kill-server

      👀 What I saw

      • In tmux, with the launcher present, a window opened through it:

        <repo>:pr:1862 :: "\"\$HUB_LAUNCHER\" --permission-mode auto --strict-mcp-config --mcp-config \"\$HUB_MCP_CONFIG\" --model opus --allowedTools 'Bash,R
        
        --permission-mode
        auto
        --strict-mcp-config
        
      • After deleting it, no window opened in 6 seconds of polling, no worktree was added, and the status bar read:

         [investigation] launcher "/var/folders/nx/09sdrj2s39zdwx5zh93ss1n00000gr/T/tmp.STsfmeOTBS/launchers/rec.sh" in hub.toml can't run: No such file or directory (os error 2)
        
      • In Rex, the first press said Opened in Workers (<repo>) and opened one tab, PR 1862 (dependabot): investigate. The second showed the same error, opened no tab and added no worktree

      • At f4aba75, before the check at each launch was added, the same deletion in tmux opened no window and changed nothing in the status bar, so the failure went unseen

  3. 🟰 What stays the same

    1. 🧪 Without launcher, hub runs claude exactly as before

      🧾 Proven by

      • In CI, the compose snapshot tests, whose only change is HUB_LAUNCHER=claude in the environment and "$HUB_LAUNCHER" where the command said claude
      • In CI, no_launcher_means_claude
      • Not visible from outside beyond the command itself, so there are no steps of its own
    2. 🧪 Every session is in auto mode with --strict-mcp-config and hub's guidance

      🧾 Proven by

      • In CI, investigations_run_in_auto_mode_and_never_bypass_permissions, investigations_ignore_every_mcp_config_hub_did_not_pass and the_launcher_starts_the_command_with_hubs_arguments
      • In CI, a_launcher_path_with_spaces_and_quotes_runs_with_hubs_arguments_unchanged, which runs the command under /bin/sh and checks the launcher receives every argument a plain path would, the system prompt whole
      • What a configured launcher then does with those arguments is up to it; decision 034's Risk section and the MCP invariant say so
  4. 🧹 Clean up
    • Close the tabs the runs opened, then restore the device config link:

      rm hub.toml
      ln -s "$(cd .. && pwd)/hub-private/devices/work-laptop.toml" hub.toml
      rm -rf "$HUB_QA"
  5. 🚀 After merge
    • Install hub from main, then set launcher under [investigation] in this device's hub.toml and restart hub, so its investigations start through the launcher
    • Expect a new investigation's claude to have HUB_LAUNCHER naming the launcher in its environment, as in the first row above

🔖 Related links

#434

hub started every investigation with bare `claude`, so on the work
laptop its sessions got neither the Vertex AI project nor the work
logins the dotfiles launcher sets up, and failed whenever sessions
moved to Vertex AI. Decision 034 records how hub reaches that launcher
without naming it: `launcher` under `[investigation]` in hub.toml names
an executable by absolute path, absent means `claude`, hub keeps
passing its own permission mode and system prompt, and hub refuses to
start when the path can't run. It also records the options rejected
and why.
#434

Every investigation ran bare `claude`, so on the work laptop its session
got neither the Vertex AI project nor the work logins the dotfiles
launcher sets up, and failed with "No projectId was given" whenever
sessions moved to Vertex AI.

`launcher` under `[investigation]` in hub.toml now names, by absolute
path, an executable hub runs in place of `claude`; absent, hub runs
`claude` as before. The new InvestigationLauncher type only admits an
absolute path, and the TUI checks at start that the path is an
executable file, before credentials resolve, so a bad path refuses at
once and names the setting. The daemon reads the same file but never
launches anything, so it parses the setting without that check.
compose() passes the launcher in HUB_LAUNCHER and starts the command
with "$HUB_LAUNCHER", the way it already passes the prompts, so a path
with spaces or quotes never becomes shell syntax. The rest of the
command is unchanged: hub keeps its auto mode, its system prompt and
--strict-mcp-config, as decision 034 records.

Two choices were made during the work. The check that the launcher can
run sits in Config::load, the TUI's path, rather than in
ConfigFile::read, so a launcher problem can't stop the daemon's
refreshes. The domain type wraps the path in LauncherPath, whose only
constructor validates it, so no caller can build an executable launcher
from a relative path. Neither would fail silently, gets costlier to
change, or closes an option.
#434

The schema taplo validates hub.toml against listed only `mcp_servers`
under `[investigation]` and refused other keys, so a device that set
`launcher` as decision 034 says got "'launcher' was unexpected" from
taplo and its editor. The schema now accepts it as an absolute path.

The test that a launcher path with spaces and quotes survives /bin/sh
now compares every argument the launcher receives with what a plain
path receives, and checks the system prompt arrives whole, instead of
checking only the first three and the last. The full device config
test now sets `launcher`, and the docs for ConfigFile::read, the domain
type and the open question about skipping permissions say what is
checked where.
#434

Decision 034 said hub passes its arguments "through the window's
environment", when only the launcher's path and the prompts travel
there; it said hub refuses to start on a bad path, when only the TUI
does; and it said decision 015 rules out other runners, when 015 only
names that as its trigger for revisiting. Its Risk section now also
says the dotfiles launcher runs the work logins first, so a background
tab can wait on a login. Decision 023 no longer calls the launcher's
arguments "the same", since a launcher may add its own.

The MCP invariant lists a configured launcher among what its checks
miss, since a launcher could drop --strict-mcp-config. AGENTS.md finds
an investigation's claude by --strict-mcp-config rather than by its
first flags, which a launcher may precede with its own, and says the
window's command names the launcher only through HUB_LAUNCHER.
#434

A launcher removed or made non-executable after the TUI started
reached a tmux window whose command failed at once, and the window
closed with the error in it, so nothing showed. launch() now runs the
same check the TUI runs at startup before it claims a window or makes
a worktree, so the status bar names the setting and the path, and it
passes that same launcher on to compose().

ConfigFile::read and Config::load gain path-taking forms, so tests
load a real hub.toml from a scratch folder. New tests fail when the
check in Config::load, the parse in ConfigFile::read or the check in
launch() is removed; before, all three could be deleted with every
test passing.

Decision 034 now says the TUI checks at each launch, that a build
from before it refuses a hub.toml setting launcher (so install first),
that a launcher must not drop --strict-mcp-config, and that hub's
sessions still get no related-repo hints. AGENTS.md shows the escaped
form tmux prints for the command, how to read HUB_LAUNCHER, and that a
launcher can wait at a login before claude starts. Smaller wording
fixes in the example config, the MCP invariant, the TUI README, the
secrets doc, the questions doc and doc comments.
#434

Decision 034's Forced by described the missing related-repo hints as
a separate change to cc.bash, which understated it: cc.bash would also
look for related repos under ~/.hub, because hub's worktrees come from
bare clones there. It now says the hints don't reach hub's sessions yet
and links ooloth/dotfiles#300. Its Also update items are ticked, as
other decision records tick theirs, and an AGENTS.md gotcha now points
at the pgrep commands in Rex pitfalls, where they are.
@ooloth
ooloth marked this pull request as ready for review November 19, 2026 01:50
Copilot AI balanced review requested due to automatic review settings November 19, 2026 01:50
@ooloth
ooloth merged commit 8295ab3 into main Nov 19, 2026
5 checks passed
@ooloth
ooloth deleted the investigation-launcher branch November 19, 2026 01:50

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Launcher validation accepts execute permissions granted only to another permission class, allowing startup checks to pass even when the current user cannot execute the launcher and tmux windows disappear without a status-bar error.

1 open issue
What changed in this PR

Adds a per-device investigation launcher so Hub can reuse machine-specific authentication and environment setup instead of invoking claude directly, addressing the launch-configuration gap in #434.

Changes:

  • Adds optional [investigation] launcher configuration, retaining claude as the default.
  • Passes Hub’s existing arguments through the launcher and adds startup and per-launch validation; the daemon checks only path syntax.
  • Adds regression tests, updates command snapshots, and documents configuration, trust boundaries, and verification.
File Description
ui/​tui/​src/​investigations/​snapshots/​hub_tui__investigations__command__tests__pr_review_investigation_command.snap Updates PR review command expectations.
ui/​tui/​src/​investigations/​snapshots/​hub_tui__investigations__command__tests__pr_review_investigation_command_with_an_mcp_server.snap Updates review command expectations with MCP configuration.
ui/​tui/​src/​investigations/​snapshots/​hub_tui__investigations__command__tests__pr_ask_investigation_command.snap Updates interactive PR command expectations.
ui/​tui/​src/​investigations/​snapshots/​hub_tui__investigations__command__tests__loki_investigation_command.snap Updates Loki launcher expectations.
ui/​tui/​src/​investigations/​snapshots/​hub_tui__investigations__command__tests__loki_investigation_command_with_a_hostile_message.snap Updates hostile-message command expectations.
ui/​tui/​src/​investigations/​snapshots/​hub_tui__investigations__command__tests__issue_investigation_command.snap Updates issue launcher expectations.
ui/​tui/​src/​investigations/​snapshots/​hub_tui__investigations__command__tests__gcp_investigation_command.snap Updates GCP launcher expectations.
ui/​tui/​src/​investigations/​snapshots/​hub_tui__investigations__command__tests__ci_investigation_command.snap Updates CI launcher expectations.
ui/​tui/​src/​investigations/​launch.rs Checks the launcher before creating windows or worktrees.
ui/​tui/​src/​investigations/​command.rs Invokes the configured launcher through a quoted environment variable.
ui/​tui/​README.md Clarifies terminology for the shared launch function.
hub.example.toml Documents the optional launcher setting.
domain/​src/​lib.rs Exports launcher domain types.
domain/​src/​investigation_launcher.rs Models the default command and validated absolute paths.
docs/​questions/​should-investigations-run-with-permissions-skipped.md Describes launcher forwarding of permission arguments.
docs/​invariants/​an-investigation-never-loads-mcp-servers-from-the-repository-it-investigates.md Documents the launcher’s MCP trust boundary.
docs/​decisions/​034-investigations-start-through-the-launcher-hub-toml-names.md Records the launcher design, risks, and rollout requirements.
docs/​decisions/​023-investigation-prompts-fence-foreign-text.md Adds launcher context to permission-mode documentation.
docs/​architecture/​secrets.md Documents validation before credential resolution.
config/​src/​toml.rs Adds launcher configuration to the full parsing fixture.
config/​src/​snapshots/​config__toml__tests__a_full_device_config_parses_every_section.snap Records the parsed launcher setting.
config/​src/​resolved.rs Carries the launcher and validates it during TUI configuration loading.
config/​src/​investigation.rs Parses launcher settings and checks file executability.
config/​src/​config_file.rs Preserves launcher configuration without requiring daemon-side executability.
config/​schemas/​hub.toml.schema.json Adds the absolute-path launcher setting to the schema.
AGENTS.md Updates live-verification guidance for launcher-based sessions.

Review effort: Balanced

Comment on lines +89 to +90
if metadata.permissions().mode() & 0o111 == 0 {
return Err(anyhow!("it has no execute bit")).with_context(context);
@ooloth

ooloth commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Proof of this change on the work laptop: #434 (comment)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants