Repository navigation
Start investigations through the launcher hub.toml names - #435
Merged
Merged
Conversation
#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.
Contributor
There was a problem hiding this comment.
🟡 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] launcherconfiguration, retainingclaudeas 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); |
Owner
Author
|
Proof of this change on the work laptop: #434 (comment) |
This was referenced Nov 19, 2026
Open
Open
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

✅ What
launchersetting under[investigation]inhub.tomlnames, by absolute path, a program hub runs in place ofclaudefor every investigation and review; without it, hub runsclaudeexactly as beforeclaude, its--permission-mode auto,--strict-mcp-configand system prompt included, so a launcher only has to set things up and pass them onhub.toml, a launcher path that isn't absolute still stops it. Thee2a5d91commit message says less than that, so this is the accurate versioniis 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 ithub.tomlschema acceptslauncher, and decision 034 records the choice and the options it beatlauncherin its ownhub.toml; on my work laptop that means adding it tohub-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 ahub.tomlwith keys they don't know, and the installed daemon would stop at its next startcc#434 for detailed explanations of this solution's overall approach and design🤔 Why
claudeand skipped the dotfiles launcher that sets up the Vertex AI project and the work logins/bin/shwith 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👩🔬 How to verify
🛠️ 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:
Keep a copy of the device config so it can be restored, in a folder of its own:
✨ What's new
📄 With
launcherset tocc.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
cc.bashwith the Vertex AI variables setauth's output; the dotfiles tests cover that path, and the launch passed no--unattended-cwithpwd: .: No such file or directory, so hub never started in it. On a freshtmux -Lserver, bothmainand this branch opened the review's window, so it isn't something this PR doesmainand 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.tomlStart hub in a background Rex tab, widen it so the status bar isn't cut off, then press
ion a PR row:Expect a new tab labelled
PR <number> (<author>): investigateRead the new session's flags, which Vertex AI variables its environment has (keys only), and the launcher it ran through:
👀 What I saw
The tab hub opened:
Its flags:
Its environment's keys, then the launcher it ran through:
Its mode, with no
--append-system-prompt-file, since this worktree has no related-repo hints:📄 While sessions use Vertex AI, that review runs instead of failing with "No projectId"
🧾 Proven by
ANTHROPIC_VERTEX_PROJECT_ID, which the run in the row above shows is now set; sessions started withccrun on Vertex AI with the same two variables🔍 Verification steps
cc-switch vertex, pression a PR row, and expect the new session to answer instead of showing "No projectId was given"cc-switch subscriptionto move sessions back👀 What I saw
📄 A
launcherthat can't run stops hub at start with a message naming the setting🧾 Proven by
a_launcher_that_cant_run_is_refused_naming_the_setting_and_path(a missing file, a folder, a file with no execute bit) anda_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] launcherand the path👀 What I saw
📄 A
launcherremoved while hub runs shows its error in the status bar wheniis pressed, and opens no window or worktree, in tmux and in Rex🧾 Proven by
ionce with the launcher present and once after deleting ita_launch_whose_launcher_no_longer_runs_is_refused_naming_the_setting_and_path, plusloading_refuses_a_launcher_that_cant_run_naming_the_setting_and_pathand the tworeading_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:
Start hub in a fresh tmux server and press
ion a PR row:Expect a second window named after the PR, and the launcher's first arguments to be
--permission-mode,auto,--strict-mcp-configOnce that window has closed, delete the launcher, press
iagain, and read the windows, the status bar and the investigation worktrees:Expect only the
tuiwindow, the error in the status bar, and no new worktreeRepeat both presses in a Rex tab sized 320×50, following the Rex loop in
AGENTS.md, and expectOpened in Workers (<repo>)then the same error with no new tabRun
tmux -L hubqa435 kill-server👀 What I saw
In tmux, with the launcher present, a window opened through it:
After deleting it, no window opened in 6 seconds of polling, no worktree was added, and the status bar read:
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 worktreeAt
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🟰 What stays the same
🧪 Without
launcher, hub runsclaudeexactly as before🧾 Proven by
composesnapshot tests, whose only change isHUB_LAUNCHER=claudein the environment and"$HUB_LAUNCHER"where the command saidclaudeno_launcher_means_claude🧪 Every session is in auto mode with
--strict-mcp-configand hub's guidance🧾 Proven by
investigations_run_in_auto_mode_and_never_bypass_permissions,investigations_ignore_every_mcp_config_hub_did_not_passandthe_launcher_starts_the_command_with_hubs_argumentsa_launcher_path_with_spaces_and_quotes_runs_with_hubs_arguments_unchanged, which runs the command under/bin/shand checks the launcher receives every argument a plain path would, the system prompt whole🧹 Clean up
Close the tabs the runs opened, then restore the device config link:
🚀 After merge
main, then setlauncherunder[investigation]in this device'shub.tomland restart hub, so its investigations start through the launcherclaudeto haveHUB_LAUNCHERnaming the launcher in its environment, as in the first row above🔖 Related links
cc#434, which stays open until the Vertex AI behaviour is proven after merge