project-sandbox-tui 0.1.0__tar.gz

project_sandbox_tui-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.project-sandbox/
+.release-status/
+# project-sandbox — do not commit agent secrets
+.devcontainer/

project_sandbox_tui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Krusche
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

project_sandbox_tui-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: project-sandbox-tui
+Version: 0.1.0
+Summary: Minimal vim/ranger-style TUI for running project-sandbox sessions per branch
+Project-URL: Homepage, https://github.com/pkrusche/project-sandbox-tui
+Project-URL: Documentation, https://github.com/pkrusche/project-sandbox-tui/tree/main/docs
+Project-URL: Issues, https://github.com/pkrusche/project-sandbox-tui/issues
+Project-URL: Source, https://github.com/pkrusche/project-sandbox-tui
+Author: Peter Krusche
+License-Expression: MIT
+License-File: LICENSE
+Keywords: coding-agent,jj,jujutsu,sandbox,textual,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.12
+Requires-Dist: textual<9,>=6.0
+Requires-Dist: tomlkit<0.16,>=0.13
+Description-Content-Type: text/markdown
+
+# project-sandbox-tui
+
+A [vim](https://www.vim.org/)/[ranger](https://ranger.fm/)-style terminal UI for
+running coding agents in [project-sandbox](https://github.com/pkrusche/project-sandbox)
+containers, with one sandbox per [jj bookmark](https://docs.jj-vcs.dev/latest/bookmarks/).
+
+> 🤖 Written largely by AI, reviewed by a human. Use at your own risk.
+
+- Run agents interactively or in the background with completion notifications.
+- Merge or rebase tasks from separate jj workspaces with agent assistance.
+- Follow each bookmark's prompts and merges in a history graph (`L` for every run); delete and undo with `dd` / `u`.
+- Run shell or configured commands in the foreground (`:!make`, `:test`), once in the repository background (`:&test`), or in each selected workspace (`:*test`); see the [command comparison](docs/usage.md#choosing-how-to-run-a-shell-command). Map any form to leader keys.
+- Let project-sandbox handle isolation, credentials and workspace teardown.
+
+```text
+ sbx-tui   ~/workspace/myproject   5 bookmarks · 1 running
+         bookmark          vs main    reviewed  head      subject                       status
+         @ working copy ●  ↑1                   qzmvtlno  (no description set)
+ ▶─╮     merge/parser-tui  ↑6 Δ9      0/9       wnrtlxqz  Merge feature/parser, spike…  merging
+ ✓ │     feature/parser    ↑3 Δ5      5/5       sutnpmvo  Add streaming parser          completed
+ │ ✗     spike/tui         ↑2 ↓1 Δ4   1/4       zsuskuln  Try a ranger-style layout     failed (1)
+ │ │ ○   fix/flaky-tests   ↑1 Δ2      0/2       rlvkpnrz  Stabilise integration tests
+ ○─┴─╯   main ●            =                    kxyrwpsn  Initial import
+```
+
+## Requirements
+
+- Linux or macOS (WSL on Windows)
+- Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/)
+- [jj](https://github.com/jj-vcs/jj) ≥ 0.46 on `PATH`; for an existing Git repository, run `jj git init --colocate`
+- [project-sandbox](https://github.com/pkrusche/project-sandbox) ≥ 0.2.2 and Apple Containers, Docker or Podman
+
+## Getting started
+
+```sh
+uv tool install project-sandbox
+uv tool install git+https://github.com/pkrusche/project-sandbox-tui
+# From a checkout: uv tool install . (or uv sync && uv run sbx-tui)
+
+cd ~/workspace/myproject
+sbx-tui --init      # detect the project type, write config and install a local setup skill
+sbx-tui doctor      # check dependencies, runtime and configuration
+sbx-tui --dry-run   # preview project-sandbox calls
+sbx-tui             # launch
+```
+
+Press `?` for full help.
+
+`--init` detects a root `Dockerfile`, Python/uv, Rust/Cargo or Node/npm project
+(in that order). It installs a gitignored `sbx-tui-config` agent skill to help
+tailor the configuration. Existing config and skill files are preserved; see
+[initialization](docs/configuration.md#initialization) for detection and skill paths.
+
+## Documentation
+
+- [Usage and keys](docs/usage.md)
+- [Worked example: foreground and background commands](docs/command-workflow.md)
+- [Sessions, terminals and notifications](docs/sessions.md)
+- [Merging and rebasing](docs/merging.md)
+- [Workspace cleanup](docs/cleanup.md)
+- [Configuration](docs/configuration.md)
+- [Model suggestions](docs/models.md)
+- [Architecture](docs/architecture.md)
+- [Development](docs/development.md)
+
+## License
+
+[MIT](LICENSE)

project_sandbox_tui-0.1.0/README.md

@@ -0,0 +1,68 @@
+# project-sandbox-tui
+
+A [vim](https://www.vim.org/)/[ranger](https://ranger.fm/)-style terminal UI for
+running coding agents in [project-sandbox](https://github.com/pkrusche/project-sandbox)
+containers, with one sandbox per [jj bookmark](https://docs.jj-vcs.dev/latest/bookmarks/).
+
+> 🤖 Written largely by AI, reviewed by a human. Use at your own risk.
+
+- Run agents interactively or in the background with completion notifications.
+- Merge or rebase tasks from separate jj workspaces with agent assistance.
+- Follow each bookmark's prompts and merges in a history graph (`L` for every run); delete and undo with `dd` / `u`.
+- Run shell or configured commands in the foreground (`:!make`, `:test`), once in the repository background (`:&test`), or in each selected workspace (`:*test`); see the [command comparison](docs/usage.md#choosing-how-to-run-a-shell-command). Map any form to leader keys.
+- Let project-sandbox handle isolation, credentials and workspace teardown.
+
+```text
+ sbx-tui   ~/workspace/myproject   5 bookmarks · 1 running
+         bookmark          vs main    reviewed  head      subject                       status
+         @ working copy ●  ↑1                   qzmvtlno  (no description set)
+ ▶─╮     merge/parser-tui  ↑6 Δ9      0/9       wnrtlxqz  Merge feature/parser, spike…  merging
+ ✓ │     feature/parser    ↑3 Δ5      5/5       sutnpmvo  Add streaming parser          completed
+ │ ✗     spike/tui         ↑2 ↓1 Δ4   1/4       zsuskuln  Try a ranger-style layout     failed (1)
+ │ │ ○   fix/flaky-tests   ↑1 Δ2      0/2       rlvkpnrz  Stabilise integration tests
+ ○─┴─╯   main ●            =                    kxyrwpsn  Initial import
+```
+
+## Requirements
+
+- Linux or macOS (WSL on Windows)
+- Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/)
+- [jj](https://github.com/jj-vcs/jj) ≥ 0.46 on `PATH`; for an existing Git repository, run `jj git init --colocate`
+- [project-sandbox](https://github.com/pkrusche/project-sandbox) ≥ 0.2.2 and Apple Containers, Docker or Podman
+
+## Getting started
+
+```sh
+uv tool install project-sandbox
+uv tool install git+https://github.com/pkrusche/project-sandbox-tui
+# From a checkout: uv tool install . (or uv sync && uv run sbx-tui)
+
+cd ~/workspace/myproject
+sbx-tui --init      # detect the project type, write config and install a local setup skill
+sbx-tui doctor      # check dependencies, runtime and configuration
+sbx-tui --dry-run   # preview project-sandbox calls
+sbx-tui             # launch
+```
+
+Press `?` for full help.
+
+`--init` detects a root `Dockerfile`, Python/uv, Rust/Cargo or Node/npm project
+(in that order). It installs a gitignored `sbx-tui-config` agent skill to help
+tailor the configuration. Existing config and skill files are preserved; see
+[initialization](docs/configuration.md#initialization) for detection and skill paths.
+
+## Documentation
+
+- [Usage and keys](docs/usage.md)
+- [Worked example: foreground and background commands](docs/command-workflow.md)
+- [Sessions, terminals and notifications](docs/sessions.md)
+- [Merging and rebasing](docs/merging.md)
+- [Workspace cleanup](docs/cleanup.md)
+- [Configuration](docs/configuration.md)
+- [Model suggestions](docs/models.md)
+- [Architecture](docs/architecture.md)
+- [Development](docs/development.md)
+
+## License
+
+[MIT](LICENSE)

project_sandbox_tui-0.1.0/docs/architecture.md

@@ -0,0 +1,124 @@
+# Architecture
+
+The Textual app calls `jj` and `project-sandbox` and reads session records from
+disk. Project-sandbox manages containers, credentials and runtimes. Repositories
+require a `.jj/` directory.
+
+## Modules (`src/project_sandbox_tui/`)
+
+| Module | Role |
+|---|---|
+| `cli.py`, `settings.py`, `doctor.py` | Entry point, config commands, dependency checks |
+| `config.py` | Typed TOML loading, validation, trust, state paths and launch defaults |
+| `vcs.py` | Bookmark discovery, creation, changed files, working-copy moves and fast-forwarding |
+| `sandbox.py` | `LaunchSpec`, argv construction and session matching |
+| `jobs.py` | Detached jobs, persistence, polling, adoption and stopping |
+| `tasks.py` | `:&` / `:*` host commands: detached, output and exit status captured |
+| `launchers.py`, `terminal.py` | External terminals and terminal restoration |
+| `octopus.py`, `cleanup.py` | Host-side integration and workspace cleanup |
+| `models.py`, `history.py`, `notify.py` | Suggestions, prompt and command history, notifications |
+| `commands.py` | `:` command parsing (`:!`, `:&`, `:*`, `[actions]`), completion and leader-key mappings |
+| `review.py` | Diff review: files marked seen per bookmark |
+| `opgraph.py` | Bookmark history graph, op log, undo stack and jj-style graph layout |
+| `app.py`, `widgets.py`, `screens/` | Bookmark list, forms, dialogs, logs, op history and prompt search |
+
+## Launches and job lifecycle
+
+`sandbox.py` maps [configuration](configuration.md) to `--flag=value` arguments,
+preventing leading `-` characters from becoming options. Bookmark launches add
+`--branch`; background launches add `--prompt-text`, `--log`, `--json-summary`
+and optional `--timeout`.
+
+1. **Guard:** reject busy workspaces. Project-sandbox records in
+   `$XDG_STATE_HOME/project-sandbox/sessions/` lack branch names; match
+   `workspace_path` using its slug rule
+   (`/` → `-`, plus sha256[:6]).
+2. **Spawn:** detach with `start_new_session=True`, capture output and write a
+   job record under a repository lock.
+3. **Poll:** every `refresh_seconds`, finalise dead processes using the summary's
+   exit code, then the child's, else `orphaned`. A summary never closes
+   a live process.
+4. **Notify:** claim `notified` atomically so only one instance announces completion.
+5. **Restart:** adopt live processes; finalise dead ones.
+
+Detached helpers (notifications, editors, terminal launchers and container stop
+commands) are reaped by daemon waiters. Forgotten or replaced job handles are
+handed to the same waiters so their children are collected even without another
+refresh. Waiters do not stop live processes or delay quitting the TUI.
+
+Inline sessions use temporary job records to mark workspaces busy across
+instances. Job records keep only each bookmark's latest run; `opgraph.json`
+keeps every run as a node of the [bookmark history](usage.md#bookmark-history),
+finalised with the bookmark's commit on the first refresh that lists bookmarks
+after the run ended. See [sessions](sessions.md) for terminal behavior and
+[state storage](configuration.md#state-directory) for paths and permissions.
+
+## Concurrency and locking
+
+Several TUI instances may run on one repository, and each does its jj, file and
+process work in worker threads. These locks order what they do:
+
+```text
+  this TUI only       _history_lock (asyncio)    held for a whole action that
+                              │                  changes the repository: n dd u
+                              │                  ctrl+r f @ e, merge or rebase
+                              │                  preparation, W removal
+                              ▼
+  every TUI on the    opgraph.json.lock          bookmark history and undo stack
+  repository                  │
+  (flock on files             ▼
+  in the state        jobs.lock                  job records, and the launch
+  directory)                  │                  guard: busy checks and spawns
+                              │                  happen under it
+                              ▼
+                      tasks.lock                 background task records
+```
+
+A lock is only taken while holding the ones above it, never the reverse, so
+actions cannot deadlock. The diff review, prompt history and command history
+each have their own `<file>.lock`, taken alone.
+
+Which actions take which locks. *history* is `_history_lock`, *graph*
+`opgraph.json.lock`; `A → B` takes B while holding A, `A, B` one after the other:
+
+| Action | Locks | Done under them |
+|---|---|---|
+| Refresh (every `ui.refresh_seconds`) | graph, jobs, tasks | Adopt new bookmarks and record finished runs; poll jobs and claim their notifications; the same for tasks |
+| `r` / `i`, `:NAME` actions | jobs, graph | Recheck busy, spawn and write the job record; add the run node. A new bookmark typed into the form is recorded first, under graph |
+| `r` / `i` with bookmarks selected | history → (jobs, graph); then as `r` / `i` | Check the result bookmark is free, merge or rebase with jj, record the result bookmark |
+| `n` | history → graph | Create with jj, then record the creation and its undo entry |
+| `dd` | history → graph → jobs | Busy check, delete, undo entry |
+| `u` / `ctrl+r` | history → graph → jobs | Busy check, delete or restore, move the undo position |
+| `f` | history → graph | Fast-forward main, undo entry |
+| `@` | history → jobs | Busy check of the working copy (and of the target's workspace before starting a change there), move it |
+| `e` | history | Describe, only if the target is still the commit that was edited |
+| `:*` | jobs, tasks | Create a missing workspace unless a session is starting; start the task |
+| `:&` | jobs, tasks | Start one task in the repository under `@`; warn if a session is running there |
+| `o` | jobs | Create a missing workspace unless a session is starting |
+| `x` | tasks, jobs, graph | Signal tasks; signal or forget the run; record a forgotten run's outcome |
+| `W` | tasks; removal: history → graph → jobs → tasks | List without the launch guard; recheck each chosen workspace right before deleting it |
+| `D` in the cleanup list | jobs → tasks | Recheck, then force-delete |
+| `sbx-tui --cleanup-workspaces` | tasks; jobs → tasks | As `W`, without the bookmark history |
+
+- Checks that guard an action are repeated under its lock with records and
+  session files read again. The UI's cached state only decides what to offer.
+- Inline sessions hold `jobs.lock` only while starting and finishing, not
+  while the agent runs.
+- Readers take no lock. Files are replaced atomically, and a reload swaps the
+  in-memory records in one assignment, so readers see the old state or the new.
+- Locks are `flock`s on separately opened files, so they also order the threads
+  of one TUI. They are not re-entrant: code holding one uses unlocked helpers
+  such as `JobManager._busy_reason`.
+- Workers that change the repository are not `exclusive`. A second action waits
+  for `_history_lock` instead of cancelling the first after jj has already run.
+- `last_used.json` and the trusted project config are replaced atomically
+  without a lock; the last write wins.
+
+## Limitations
+
+- Inline sessions, diffs and shell commands suspend the event loop;
+  notifications arrive on return.
+- External launches, stale records and PID reuse after crashes may need
+  [manual recovery](sessions.md#interactive-sessions).
+- Working-copy dirty markers, prompt files, remote bookmarks and switching
+  repositories are not implemented.

project_sandbox_tui-0.1.0/docs/cleanup.md

@@ -0,0 +1,43 @@
+# Workspace cleanup
+
+```sh
+sbx-tui --cleanup-workspaces --dry-run   # preview
+sbx-tui --cleanup-workspaces             # remove eligible workspaces and merged bookmarks
+```
+
+Press `W` to review candidates: eligible rows are preselected; others show why
+they are kept. `j` `k` move, `space` toggles a row, `a` selects all/none,
+`enter` lists what goes and asks for `y`, and `esc` or `q` cancels. The CLI removes all eligible candidates, reporting removals and
+reasons for keeping others.
+
+Candidates come from `jj workspace list`, regardless of name or location. The
+current workspace is excluded. Normal cleanup keeps `default` and workspaces
+with running sessions or [`:*` tasks](usage.md#running-in-each-workspace),
+uncommitted changes or files too large to snapshot; workspaces in use cannot
+be force-removed either.
+Directories containing another registered workspace are protected from both
+normal and force removal; remove the nested workspace first and scan again.
+Running sessions also protect enclosing and nested workspace directories.
+
+## Merged work
+
+The [main bookmark](configuration.md#settings-reference) defines merged work:
+
+- Workspaces with only empty revisions outside `::main` can be removed, deleting
+  ignored files or unregistering missing directories. Their bookmarks are also
+  deleted if the bookmarks themselves are fully merged, except main. A
+  workspace and its namesake bookmark can point at different revisions.
+- Fully merged bookmarks without workspaces appear as separate rows.
+
+Unmerged workspaces with ignored files or missing directories are kept. Removal
+checks each workspace again just before deleting it, then runs
+`jj workspace forget` and deletes eligible bookmarks;
+tracked remote bookmarks are deleted on the next `jj git push`. Job history and the
+[bookmark history](usage.md#bookmark-history) stay. In the TUI, `u` restores the
+deleted bookmarks; removed workspaces cannot be undone.
+
+## Force delete
+
+Highlight a kept workspace, press `D` and confirm to unregister it and delete
+its directory, including uncommitted, untracked and ignored files. Bookmarks
+stay. Running sessions and `default` cannot be force-deleted.

project_sandbox_tui-0.1.0/docs/command-workflow.md

@@ -0,0 +1,133 @@
+# Workflow: run tests while keeping sbx-tui open
+
+This example follows a Python project from a quick foreground check to a
+repository background task, then tests two bookmarks in parallel. It uses
+`feature/parser` and `fix/cache` as example bookmarks; substitute your own.
+The illustrations use the actual TUI renderer with staged project data and
+test results. They show the workflow, not results from this repository's tests.
+
+## 1. Define one test command
+
+From your project directory, configure a reusable command:
+
+```sh
+sbx-tui config set --project commands.test 'uv run pytest -q'
+sbx-tui
+```
+
+This adds `test = "uv run pytest -q"` under `[commands]` in the project
+configuration. The project must already have pytest available through uv.
+These commands run on the host; they do not launch a sandbox or an agent.
+
+You can run the same configured command three ways:
+
+| Enter in sbx-tui | Where the tests start | What you can do meanwhile |
+|---|---|---|
+| `:test` | Once in the repository root | Use the command's terminal; return when it exits |
+| `:&test` | Once in the repository root, ignoring marks | Keep navigating sbx-tui |
+| `:*test` | Once in each marked workspace, or the highlighted workspace if none are marked | Keep navigating sbx-tui |
+
+The literal equivalents are `:!uv run pytest -q`, `:&!uv run pytest -q`,
+and `:*!uv run pytest -q`. The prefix changes execution; the configured script
+stays the same. See the [full comparison](usage.md#choosing-how-to-run-a-shell-command)
+for environment variables and task persistence.
+
+## 2. Do a quick foreground check
+
+Press `:`, type `test`, and press `Enter`. The command takes over the terminal:
+
+```text
+── sbx-tui: :test → uv run pytest -q ──
+
+..........................................                         [100%]
+42 passed in 3.12s
+
+── exited with 0; press Enter to return to sbx-tui ──
+```
+
+Press `Enter` to return. If the tests take longer than expected, `Ctrl+C`
+interrupts them; press `Enter` at the exit prompt to return to the TUI.
+An exit status of `-2` or `130` means the command was interrupted. This form
+does not create a background task or a captured log in the task list.
+
+## 3. Run once in the repository background
+
+Use `j` / `k` to move to `feature/parser` and press `Space` to mark it.
+Move to `fix/cache` and mark it too. `Space` marks a row and moves down;
+move back to `feature/parser` to leave it highlighted.
+
+The marks are deliberately left in place for the next command:
+
+![Bookmark list with feature/parser highlighted and both feature/parser and fix/cache marked.](images/command-workflow/01-repository-command.svg)
+
+*Two rows are marked, but `:&test` will ignore them.*
+
+Enter `:&test` to launch **one task in the repository root**, then press `T`
+to open the task list:
+
+![Task list showing one running :&test task under the working copy @.](images/command-workflow/02-repository-task.svg)
+
+*The task belongs to `@`, even though `feature/parser` was highlighted.*
+
+The TUI remains usable. In the task list, select the task and press `Enter`
+or `l` to follow its captured output; `q` returns to the task list, and another
+`q` returns to the bookmark list. Let this run finish before the next step.
+Its result remains available in `T`.
+
+`:&test` does not create or enter the highlighted bookmark's workspace.
+Use the `&` prefix as shown: a trailing shell `&` (`:!uv run pytest -q &`)
+does not create a tracked sbx-tui task.
+
+## 4. Run in both marked workspaces
+
+Back on the bookmark list, keep `feature/parser` and `fix/cache` marked and
+enter `:*test`. This starts two background tasks, each in its own workspace.
+sbx-tui creates a missing workspace before launching its task. For Python
+projects, uv prepares that workspace's environment as needed.
+
+Press `T` again. In this example, the parser tests pass and the cache tests fail:
+
+![Task list with :*test completed for feature/parser, failed with exit 1 for fix/cache, and the earlier completed :&test under @.](images/command-workflow/03-workspace-tasks.svg)
+
+*Three records: the earlier repository run, plus one run for each marked bookmark.*
+
+The separate results matter: a passing repository run says nothing about
+changes that exist only in another bookmark's workspace. With no rows marked,
+`:*test` runs only in the highlighted workspace. `Esc` on the bookmark list
+clears marks when you want that single-workspace behavior.
+
+## 5. Inspect the failure
+
+In `T`, use `j` / `k` to select the failed `fix/cache` task, then press `Enter`:
+
+![Captured test output for fix/cache showing an expired cache entry assertion failure and 1 failed, 41 passed.](images/command-workflow/04-failure-output.svg)
+
+*The log belongs to the selected task; the title identifies the bookmark and exit code.*
+
+Use `j` / `k` to scroll, `gg` / `G` for the top or bottom, and `q` to go back.
+For a running task, the log follows new output automatically.
+
+To rerun just the cache tests after making a fix, return to the bookmark list,
+press `Esc` to clear marks, highlight `fix/cache`, and enter `:*test` again.
+Each invocation creates a new task record, so you can compare it with the
+earlier failure in `T`.
+
+## 6. Cancel or leave a task running
+
+To stop a background task, open `T`, select its running row, and press `x`.
+That targets just that task. If it does not stop, further presses escalate
+from SIGINT to SIGTERM and SIGKILL. On a finished row, `x` forgets the task
+and removes its captured output instead.
+
+On the bookmark list, `x` acts on the target bookmarks and can affect several
+running tasks or sandbox runs. Use the task list when you want to cancel only
+one command.
+
+Both `:&` and `:*` tasks keep running if you quit sbx-tui. Confirm the quit
+prompt when tasks are still running; reopening sbx-tui in the same repository
+lets you inspect their status and logs. Background commands capture output
+and have no interactive input, so use the foreground form for commands that
+need terminal interaction.
+
+For the complete controls, see [Tasks](usage.md#tasks) and the
+[log viewer](usage.md#log-viewer).