galaxy/specs/APP-3736/TECH.md

APP-3736: Allow specifying tab-close behavior in tab configs — Tech Spec

Product spec: specs/APP-3736/PRODUCT.md

Problem

Tab configs can declare how to open a tab, including pane layout, startup commands, and templated params, but there was no declarative way to run cleanup when a tab created from a config is later closed. This was especially painful for worktree configs, which can create a worktree on open but previously left users to manually remove the worktree directory and branch.

Relevant Code

• app/src/tab_configs/tab_config.rs — TabConfigOnClose, ResolvedTabCloseBehavior, TabConfig::on_close, render_tab_close_behavior, build_template_contexts
• app/src/tab_configs/mod.rs — exports render_tab_close_behavior and ResolvedTabCloseBehavior
• app/src/tab.rs — stores resolved_tab_close_behavior on TabData
• app/src/workspace/view.rs — resolves close behavior when opening a tab config, runs cleanup during tab close, and executes close commands with LocalCommandExecutor
• app/src/tab_configs/session_config.rs — initializes on_close: None for generated configs that do not define close behavior
• app/src/tab_configs/tab_config_tests.rs — parser and template-rendering coverage for [on_close]

Current State

TabConfig already supports templated titles, pane directory, pane startup commands, and params. Rendering uses two template contexts: unquoted values for paths/titles and shell-quoted values for commands. TabData is the in-memory state container for each tab. Before this change, it tracked pane group state, colors, mouse state, and telemetry flags, but not any tab-config-specific close behavior. Tab close flows already funnel through Workspace::close_tabs, which optionally shows an unsaved-state confirmation dialog, cancels tab renaming, removes tabs in reverse index order, and emits telemetry once tabs are actually closed.

Changes

1. Tab-config schema and resolved close behavior

TabConfig now has an optional top-level on_close: Option<TabConfigOnClose>. TabConfigOnClose mirrors the close-time command contract:

• directory: Option<String> — optional working directory for cleanup commands
• commands: Vec<String> — ordered commands to run on tab close ResolvedTabCloseBehavior stores the fully rendered cleanup plan for one opened tab instance:
• directory: Option<PathBuf>
• commands: Vec<String> The resolved form is intentionally separate from TabConfigOnClose so close-time execution can use the exact values chosen when that tab was opened, without re-reading config files or re-prompting for params.

2. Shared template-context builder

build_template_contexts now centralizes construction of both template contexts used by tab config rendering:

• unquoted_context: raw param values, plus autogenerated_branch_name when provided
• quoted_context: shell-quoted param values, plus a shell-quoted autogenerated_branch_name when provided render_tab_config and render_tab_close_behavior both use this helper so open-time and close-time template substitution follow the same quoting rules:
• titles and pane directory use unquoted values
• commands use shell-quoted values This avoids duplicating context setup and preserves existing shell-quoting behavior for command templates with spaces.

3. Render and attach close behavior when opening tab configs

Workspace::open_tab_config_with_params now resolves both:

• the tab title + pane layout via render_tab_config
• the optional close behavior via render_tab_close_behavior After calling add_tab_with_pane_layout, the method writes the resolved close behavior into self.tabs[self.active_tab_index].resolved_tab_close_behavior. It also applies the tab color from the config as before. This means each tab instance carries its own rendered cleanup commands, including manual param values and the generated branch name from maybe_generate_worktree_name.

4. Store close behavior on tab state

TabData has a new field:

• resolved_tab_close_behavior: Option<ResolvedTabCloseBehavior> TabData::new initializes it to None, so ordinary tabs and tabs not opened from configs have no close hook and keep the existing close behavior. The field is stored only in memory on the live TabData; it is not serialized into workspace snapshots.

5. Run cleanup from the existing tab-close flow

Workspace::close_tabs now collects each closing tab's resolved_tab_close_behavior before removing any tabs:

1. Build tab_indices_vec
2. Show the existing unsaved-state confirmation dialog if needed
3. Cancel any in-progress tab rename
4. Take (consume) each selected tab's resolved close behavior and mark cleanup_was_run = true on the tab
5. Call run_tab_close_cleanup for each collected behavior
6. Remove tabs in reverse index order as before Collecting the close behaviors first avoids depending on tab indices after tabs have been removed.

6. Async best-effort cleanup execution on native local-tty builds

On native builds with local_tty, run_tab_close_cleanup reads the current LocalShellState and spawns execute_tab_close_behavior with:

• shell type
• shell path
• PATH from the active local shell environment If LocalShellState is unavailable, cleanup is skipped and a warning is logged. execute_tab_close_behavior constructs a LocalCommandExecutor and executes the resolved cleanup commands sequentially. For each command, it passes:
• the resolved directory, if present
• environment variables containing HOME and PATH when available
• ExecuteCommandOptions { run_command_in_same_shell_as_session: true } If a command exits successfully, execution continues to the next command. If a command returns a non-zero status, execution stops and returns an error containing the failed command and command output. The spawned callback logs that error with log::warn!. The workspace does not await this task before removing the tab, so cleanup is intentionally best-effort and non-blocking from the user's perspective. If cleanup fails, or if LocalShellState is unavailable, run_tab_close_cleanup also adds a persistent DismissibleToast::error(...) to the workspace toast stack so the failure is visible without blocking tab close. On builds without native local-tty support, run_tab_close_cleanup is a no-op stub.

7. Default on_close value for generated configs

build_tab_config and tab_config_from_pane_snapshot now initialize on_close: None so generated startup/session configs and saved-from-live-tab configs preserve current behavior unless a user explicitly edits the TOML to add [on_close].

8. Tests

tab_config_tests.rs adds coverage for:

• parsing [on_close] in a worktree config
• render_tab_close_behavior substituting manual params
• render_tab_close_behavior substituting autogenerated_branch_name
• shell-quoting command params with spaces while leaving pane directory unquoted Existing render tests continue to cover open-time title/layout rendering and fallback behavior for invalid pane trees.

End-to-End Flow

1. User selects a tab config from the new-session menu.
2. If the config has params, the params modal collects values; otherwise defaults are used. If any pane sets worktree_name_autogenerated = true, maybe_generate_worktree_name creates a unique branch name.
3. open_tab_config_with_params renders the pane template, title, and optional close behavior, opens the tab, and stores the resolved close behavior on the new TabData.
4. User later closes that tab.
5. close_tabs gathers each tab's resolved close behavior and calls run_tab_close_cleanup before removing the tabs.
6. On native local-tty builds, cleanup commands run asynchronously through LocalCommandExecutor. Tabs disappear immediately; failures are logged and stop any remaining cleanup commands for that tab.

Risks and Limitations

• Single-fire cleanup: resolved_tab_close_behavior is consumed (.take()n) before the tab is removed, so re-closing an undo-restored tab does not fire cleanup again. Tabs restored from workspace snapshots also do not recover a prior close hook because the field is not serialized.
• Undo-close CWD fallback: when a tab with cleanup_was_run = true is restored via undo-close, restore_closed_tab iterates its terminal panes and calls cd_home_if_dir_missing on each. If the CWD no longer exists (e.g., the worktree was removed by cleanup), the shell falls back to the home directory.
• Race between cleanup and undo-close: cleanup runs asynchronously via ctx.spawn, so it may not have finished by the time the user triggers undo-close. In that case, the CWD still exists at restoration time and the fallback is a no-op. If the user then runs commands, the directory may disappear mid-session once cleanup finishes.
• Best-effort async cleanup: Because tab removal does not wait for cleanup completion, users can immediately create another worktree or branch with the same name and race against the cleanup task.
• Non-blocking failure toast only: Cleanup failures show a persistent toast and log a warning, but there is still no blocking retry/undo flow in the close path.
• Depends on local shell availability: If LocalShellState is unavailable, cleanup is skipped.
• Command environment is intentionally minimal: Cleanup gets HOME and PATH, but not a full clone of the pane's process environment.

Testing and Validation

• Run targeted tab-config tests covering parser and rendering behavior, especially [on_close] and shell-quoting cases.
• Run targeted workspace tests for the close-cleanup failure path to verify persistent error toasts are shown.
• Manually verify a config that removes only a worktree on close.
• Manually verify a config that removes a worktree and then deletes the branch on close.
• Manually verify that a failing cleanup command does not block tab close, shows a persistent error toast, and prevents later cleanup commands from running.
• Manually verify that tabs opened from configs without [on_close] keep existing close behavior.
• Run cargo fmt and a Rust test/lint pass appropriate for the touched modules before sending the branch for review.

Follow-ups

• Persist close behavior in tab/workspace snapshots if restored tabs should continue running [on_close].
• Consider generating [on_close] automatically in build_worktree_config_toml if default worktree configs should clean themselves up without manual edits.