agent-bios 0.18.0 → 0.19.1

package/compose/setup/START.md

@@ -0,0 +1,158 @@
+# Set up agent-bios through conversation
+
+This guide uses the same installation controller as the terminal wizard. The
+conversation collects choices and presents effects; `setup` validates and executes
+them. It needs local command and file access on the intended machine, Bash, and
+Python 3.11 or newer. Codex CLI, an additional model login, and Textual are not
+requirements for this route.
+
+## Start without an installed skill
+
+The user can request installation using the public repository link. Follow the
+repository's root `INSTALL.md` to obtain and verify the source, select the language
+and run `setup start`. The agent resolves paths; the user does not need a checkout,
+an installed skill or a long installation prompt. An explicitly selected trusted
+local source remains valid. Preserve the acquisition's exact revision and location
+for the review and any resume. If the selected public revision lacks conversation
+setup, report that limitation instead of invoking an older installation route.
+
+## Choose the entrypoint and language
+
+For an already registered app bridge, run `python3 "$BRIDGE" setup start`, where
+`BRIDGE` is the absolute helper path beside the loaded skill. Read the returned
+`guide_path`. For an acquired source, use the verified `setup_argv` from its start
+response. Keep using that entrypoint and the reported private roots throughout
+the review. Shell variables from one app tool call do not persist to the next;
+pass absolute arguments or set the variable in the same call.
+
+`start` returns language choices, a suggested language and execution context without
+probing dependencies or creating private setup state. Confirm English, 한국어 or
+日本語, honoring an explicit language already chosen by the user, before `inspect`.
+Use the selected language for questions and explanations; retain identifiers,
+paths, versions, raw diagnostics and command arguments exactly. Use a native
+question control when the current host exposes one for this interaction, or ask
+ordinary concise questions. The conversation does not require custom widgets.
+
+The commands below use `agent-bios` as shorthand for that verified entrypoint. In
+an app bridge call, replace `agent-bios setup` with `python3 "$BRIDGE" setup`.
+
+```bash
+agent-bios setup inspect --language ko
+agent-bios setup discover --project-root /absolute/project
+```
+
+## Collect and review the choices
+
+Use `inspect`'s `default_plan`, inventory and choices. Present all dependency
+capabilities with readiness, purpose and installation destination. Ready dependencies
+are observations, not requested actions: include only chosen missing dependencies
+with returned recipes in `dependencies`. Do not create shell recipes from model
+memory. A dependency's presence does not authorize installing another one.
+
+`retained_corpus` reports local personal instructions and host learning records
+already stored on this device as `{target, label, item_count}`; localized labels are
+in `display.retained_corpus`. Present this separately as a read-only storage view,
+not as extra installation choices or evidence of active use. Counts cover stored,
+nonremoved items regardless of enable overrides or current host/project eligibility,
+and reveal no bodies. Do not copy these rows into `targets`; use the source `choices`
+and the user's activation-policy decision.
+
+Collect the six plan fields without asking the user to author JSON:
+
+- `selection_mode` and `targets`: keep saved policy, no active corpus, all available
+  corpus, or specific returned package/domain/item targets. Start from the returned
+  default. No active corpus retains private library assets but delivers no corpus.
+- `dependencies`: chosen installable inventory IDs; an empty list installs none.
+- `app_bridge`: the explicit **Connect to the Codex app** choice, adding `$agent-bios`
+  for setup and personal instruction management. Registration enables discovery only;
+  each task still requires its own explicit corpus use.
+- `project_roots` and `import_paths`: absolute project folders and explicitly
+  selected files from discovery. Capture is independent of corpus selection.
+
+Keep saved policy uses `selection_mode: null` and `targets: null`. No active corpus
+uses `"none"` and `[]`. Explicit choices use `"selected"` and their target list;
+all available corpus uses `"selected"` and `["all"]`.
+
+Discovery checks known global instruction locations and the specified project
+roots. Show detected sources before selecting them. Capture preserves originals
+and prepares private evidence for later model review; it is not an automatically
+optimized personal corpus. Read the import procedure only when the user requests
+that subsequent review.
+
+Save choices to a new caller-owned artifact. Run `plan` and save its complete
+stdout bytes to another new caller-owned artifact:
+
+```bash
+agent-bios setup plan --language ko --input /absolute/choices.json > /absolute/review.json
+```
+
+The returned review envelope contains `review_id`, `context`, `language`,
+`preview` and `summary`. Keep the entire envelope; do not reconstruct it from the
+summary, copy only `preview`, change its IDs, or accept truncated output. Show the
+concrete private paths, selected dependency commands/destinations, corpus policy,
+app discovery change and selected capture sources. Keep the exact artifact
+available for inspection. Preparing these caller-owned files is separate from
+applying installation effects.
+
+Apply the saved envelope only when its concrete choices are authorized. Existing
+authorization for those exact choices does not require another confirmation.
+
+```bash
+agent-bios setup apply --input /absolute/review.json --review-id REVIEW_ID --yes
+```
+
+The engine checks the reviewed context, source bytes, private state and package
+before its effects. If the review is stale, show a fresh plan and explain the
+changed effects; do not bypass checks. Report completed dependencies, private
+installation, bridge registration and pending import separately. A partial failure
+or cancellation does not roll back completed external package installations.
+
+## Continue or resume
+
+```bash
+agent-bios setup status --review-id REVIEW_ID
+agent-bios setup resume --review-id REVIEW_ID
+```
+
+These commands do not execute the remaining installation. `status` reports the
+recorded attempt in `receipt`, `result` and `state`; a past `complete` result does
+not establish the current runtime's health. Inspect `handoff` for current readiness
+and any `needs_action`. Package verification, full runtime verification and helper
+verification are independent observations; one does not prove the others.
+`replayed: true` means the existing attempt was returned without executing it again.
+If `handoff.verification` is `"deferred"`, its readiness fields are null: they are
+unverified, not false. Status can return recorded progress while setup holds the
+private-state lock. Follow `needs_action` and retry status when that operation has
+settled; require checked readiness before using a handoff to continue.
+
+`resume` adds `remaining_plan`, `review` and `needs_action`. When `review` is
+non-null, save that entire nested review object to a new caller-owned JSON artifact
+using deterministic JSON extraction. Do not pass the enclosing status response or
+`remaining_plan` to Apply. Preserve every review field, including `continuation`,
+and use the nested review's own `review_id`. Review its remaining effects before
+applying within the user's authorization. If `review` is null, inspect the stated
+reason; unknown prior effects are not permission to replay package installation.
+When `resumed_from` is present, the response has followed a receipt's `continued_by`
+link to an existing continuation. Report the returned child `review_id` rather than
+assuming the original ID is current.
+
+After an explicit app registration succeeds, use `handoff.helper_argv` only when
+`helper_usable` is true, appending `setup` and the desired operation.
+`helper_verified` confirms helper bytes, while `helper_usable` also requires a
+verified package and no pending work blocking it. Otherwise inspect `needs_action`
+and current readiness before continuing. A usable helper can continue in this task
+even if native skill discovery has not refreshed. Without a
+verified helper, a verified runtime's `setup_argv` already includes `setup`;
+`cli_argv` does not. Supply the returned `environment` with each call. These arrays
+are command arguments, not shell snippets. Finish applying an existing review
+through its reviewed entrypoint/context; changing entrypoints requires a fresh
+review. Status and subsequent setup can use the verified handoff.
+Do not create a duplicate personal skill or edit host discovery settings to force
+refresh. Once discovered, `$agent-bios` is the ordinary entrypoint. Registration
+on disk is not proof of discovery or corpus loading.
+
+If capture completed, report its actual capture ID and returned next action. Its
+semantic review, proposed consumption placement and revision-checked import are
+separate from installation. Setup enables no hooks, native agent registration,
+permissions or edits to global/project instruction files. Each app task requires
+its own explicit corpus use; neither setup nor opening the app performs it.

package/compose/ui_runtime/manifest.json

@@ -0,0 +1,238 @@
+{
+  "schema_version": 1,
+  "source": "pypi",
+  "python_requirement": ">=3.11",
+  "root_requirement": "textual==8.2.8",
+  "packages": [
+    {
+      "name": "linkify-it-py",
+      "version": "2.2.0",
+      "filename": "linkify_it_py-2.2.0-py3-none-any.whl",
+      "sha256": "3adc40eb5af300b2605fcfdb968c24e1d780a90f1f2221af7c15e5111e94d443",
+      "size_bytes": 21971,
+      "expanded_bytes": 66766,
+      "modules": [
+        "linkify_it"
+      ],
+      "license_files": [
+        "linkify_it_py-2.2.0.dist-info/licenses/LICENSE"
+      ],
+      "requires_python": ">=3.10",
+      "requires_dist": [
+        "pytest; extra == \"test\"",
+        "coverage; extra == \"test\"",
+        "pytest-cov; extra == \"test\"",
+        "pytest-timeout; extra == \"test\"",
+        "pre-commit; extra == \"dev\"",
+        "isort; extra == \"dev\"",
+        "flake8; extra == \"dev\"",
+        "black; extra == \"dev\"",
+        "pyproject-flake8; extra == \"dev\"",
+        "pytest; extra == \"benchmark\"",
+        "pytest-benchmark; extra == \"benchmark\"",
+        "sphinx; extra == \"doc\"",
+        "sphinx_book_theme; extra == \"doc\"",
+        "myst-parser; extra == \"doc\""
+      ]
+    },
+    {
+      "name": "markdown-it-py",
+      "version": "4.2.0",
+      "filename": "markdown_it_py-4.2.0-py3-none-any.whl",
+      "sha256": "9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a",
+      "size_bytes": 91687,
+      "expanded_bytes": 244684,
+      "modules": [
+        "markdown_it"
+      ],
+      "license_files": [
+        "markdown_it_py-4.2.0.dist-info/licenses/LICENSE",
+        "markdown_it_py-4.2.0.dist-info/licenses/LICENSE.markdown-it"
+      ],
+      "requires_python": ">=3.10",
+      "requires_dist": [
+        "mdurl~=0.1",
+        "psutil ; extra == \"benchmarking\"",
+        "pytest ; extra == \"benchmarking\"",
+        "pytest-benchmark ; extra == \"benchmarking\"",
+        "commonmark~=0.9 ; extra == \"compare\"",
+        "markdown~=3.4 ; extra == \"compare\"",
+        "mistletoe~=1.0 ; extra == \"compare\"",
+        "mistune~=3.0 ; extra == \"compare\"",
+        "panflute~=2.3 ; extra == \"compare\"",
+        "markdown-it-pyrs ; extra == \"compare\"",
+        "linkify-it-py>=1,<3 ; extra == \"linkify\"",
+        "mdit-py-plugins>=0.5.0 ; extra == \"plugins\"",
+        "gprof2dot ; extra == \"profiling\"",
+        "mdit-py-plugins>=0.5.0 ; extra == \"rtd\"",
+        "myst-parser ; extra == \"rtd\"",
+        "pyyaml ; extra == \"rtd\"",
+        "sphinx ; extra == \"rtd\"",
+        "sphinx-copybutton ; extra == \"rtd\"",
+        "sphinx-design ; extra == \"rtd\"",
+        "sphinx-book-theme~=1.0 ; extra == \"rtd\"",
+        "jupyter_sphinx ; extra == \"rtd\"",
+        "ipykernel ; extra == \"rtd\"",
+        "coverage ; extra == \"testing\"",
+        "pytest ; extra == \"testing\"",
+        "pytest-cov ; extra == \"testing\"",
+        "pytest-regressions ; extra == \"testing\"",
+        "pytest-timeout ; extra == \"testing\"",
+        "requests ; extra == \"testing\""
+      ]
+    },
+    {
+      "name": "mdit-py-plugins",
+      "version": "0.6.1",
+      "filename": "mdit_py_plugins-0.6.1-py3-none-any.whl",
+      "sha256": "214c82fb2ac524472ab6a5bcab1de80f73b50443e187f401bfd77efbc7c6481d",
+      "size_bytes": 66663,
+      "expanded_bytes": 172036,
+      "modules": [
+        "mdit_py_plugins"
+      ],
+      "license_files": [
+        "mdit_py_plugins-0.6.1.dist-info/licenses/LICENSE"
+      ],
+      "requires_python": ">=3.10",
+      "requires_dist": [
+        "markdown-it-py>=2.0.0,<5.0.0",
+        "pre-commit ; extra == \"code-style\"",
+        "myst-parser ; extra == \"rtd\"",
+        "sphinx-book-theme ; extra == \"rtd\"",
+        "coverage ; extra == \"testing\"",
+        "pytest ; extra == \"testing\"",
+        "pytest-cov ; extra == \"testing\"",
+        "pytest-regressions ; extra == \"testing\"",
+        "pytest-timeout ; extra == \"testing\""
+      ]
+    },
+    {
+      "name": "mdurl",
+      "version": "0.1.2",
+      "filename": "mdurl-0.1.2-py3-none-any.whl",
+      "sha256": "84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8",
+      "size_bytes": 9979,
+      "expanded_bytes": 23308,
+      "modules": [
+        "mdurl"
+      ],
+      "license_files": [
+        "mdurl-0.1.2.dist-info/LICENSE"
+      ],
+      "requires_python": ">=3.7",
+      "requires_dist": []
+    },
+    {
+      "name": "platformdirs",
+      "version": "4.11.8",
+      "filename": "platformdirs-4.11.8-py3-none-any.whl",
+      "sha256": "52f2f181bbfde907966932cc8312d967d02976422d66d537ea16092b8e291081",
+      "size_bytes": 24027,
+      "expanded_bytes": 129535,
+      "modules": [
+        "platformdirs"
+      ],
+      "license_files": [
+        "platformdirs-4.11.8.dist-info/licenses/LICENSE"
+      ],
+      "requires_python": ">=3.10",
+      "requires_dist": []
+    },
+    {
+      "name": "pygments",
+      "version": "2.21.0",
+      "filename": "pygments-2.21.0-py3-none-any.whl",
+      "sha256": "2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9",
+      "size_bytes": 1250147,
+      "expanded_bytes": 4621166,
+      "modules": [
+        "pygments"
+      ],
+      "license_files": [
+        "pygments-2.21.0.dist-info/licenses/AUTHORS",
+        "pygments-2.21.0.dist-info/licenses/LICENSE"
+      ],
+      "requires_python": ">=3.9",
+      "requires_dist": [
+        "colorama>=0.4.6; extra == 'windows-terminal'"
+      ]
+    },
+    {
+      "name": "rich",
+      "version": "15.0.0",
+      "filename": "rich-15.0.0-py3-none-any.whl",
+      "sha256": "33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb",
+      "size_bytes": 310654,
+      "expanded_bytes": 1245816,
+      "modules": [
+        "rich"
+      ],
+      "license_files": [
+        "rich-15.0.0.dist-info/licenses/LICENSE"
+      ],
+      "requires_python": ">=3.9.0",
+      "requires_dist": [
+        "ipywidgets (>=7.5.1,<9) ; extra == \"jupyter\"",
+        "markdown-it-py (>=2.2.0)",
+        "pygments (>=2.13.0,<3.0.0)"
+      ]
+    },
+    {
+      "name": "textual",
+      "version": "8.2.8",
+      "filename": "textual-8.2.8-py3-none-any.whl",
+      "sha256": "267375fd402dc8d981457212efa71f0e3365fd17bba144ba9bb3ed7563cb374a",
+      "size_bytes": 731418,
+      "expanded_bytes": 2827661,
+      "modules": [
+        "textual"
+      ],
+      "license_files": [
+        "textual-8.2.8.dist-info/licenses/LICENSE"
+      ],
+      "requires_python": ">=3.9,<4.0",
+      "requires_dist": [
+        "markdown-it-py[linkify] (>=2.1.0)",
+        "mdit-py-plugins",
+        "platformdirs (>=3.6.0,<5)",
+        "pygments (>=2.19.2,<3.0.0)",
+        "rich (>=14.2.0)",
+        "tree-sitter (>=0.25.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-bash (>=0.23.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-css (>=0.23.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-go (>=0.23.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-html (>=0.23.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-java (>=0.23.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-javascript (>=0.23.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-json (>=0.24.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-markdown (>=0.3.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-python (>=0.23.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-regex (>=0.24.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-rust (>=0.23.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-sql (>=0.3.11) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-toml (>=0.6.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-xml (>=0.7.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "tree-sitter-yaml (>=0.6.0) ; (python_version >= \"3.10\") and (extra == \"syntax\")",
+        "typing-extensions (>=4.4.0,<5.0.0)"
+      ]
+    },
+    {
+      "name": "typing-extensions",
+      "version": "4.16.0",
+      "filename": "typing_extensions-4.16.0-py3-none-any.whl",
+      "sha256": "481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8",
+      "size_bytes": 45571,
+      "expanded_bytes": 182767,
+      "modules": [
+        "typing_extensions"
+      ],
+      "license_files": [
+        "typing_extensions-4.16.0.dist-info/licenses/LICENSE"
+      ],
+      "requires_python": ">=3.9",
+      "requires_dist": []
+    }
+  ],
+  "bundle_id": "f86c64655f21c67f45a1b43cf5ea16da5f4b6957a5ce0b8b222e8e8f8d2c1194"
+}

package/docs/advanced-launch.md

@@ -0,0 +1,131 @@
+# Launch configuration
+
+[← Overview](../README.md) · [Setup](setup.md) · [Corpus](corpus.md) · [Sessions](session-model.md) · [Recovery](recovery.md) · [Launch](advanced-launch.md) · [Understand!](understand.md)
+
+Inspect settings before launching. Some Builder and internal-wrapper defaults use permission bypass. A configured review or registered hook is not evidence that it ran.
+
+## Preflight and settings
+
+The preflight keeps the current setup above each choice, supports the configured model
+catalog and **Other**, and offers Builder presets, Software Engineer / Vanilla,
+Session distill, Custom, Language, and **Corpus Studio**. Studio is the same backend as
+`agent-bios corpus`: it searches and renders the library, edits Markdown and
+consumption surface, and requires Preview then revision-bound Apply. Packaged
+entrypoints validate and temporarily extract their included UI bundle before loading
+Rich/Textual. A missing or corrupt bundle fails explicitly; no preinstalled Textual
+environment is required. Interface catalogs change only human UI text;
+model-consumed corpus remains English.
+
+Every arrow-key TUI selection screen keeps the complete current setup in a fixed top
+panel, followed by the highlighted option's description and the option list. Custom
+opens a persistent settings hub for the main tier, review setup, host policy, global instruction files, and tier
+bindings. Every edit returns to that hub; **Start with these settings** is the final
+launch confirmation, while **Exit without launching** cancels it. When the numbered
+launcher flow is selected with `--no-tui`, `b` is the back command. These controls configure an explicit
+agent-bios launch; they do not restore global instruction installation. Optional
+shell wiring is controlled separately from the root **Shell connection** menu.
+
+## Tiers and restricted seats
+
+Tier defaults come from the launch profile and the guides' Environment Binding
+tables. Claude Haiku 4.5 has no effort parameter: its tier entry, native agent
+definition and projected call omit it. SWEEP is one-rule-per-item read-only work.
+As a main seat it disables child delegation and requires review off (for example,
+Solo); a requested review needs a HELM or WORKHORSE main instead. Codex SWEEP mains
+use a read-only sandbox; Claude SWEEP mains use restricted Read/Glob/Grep tools
+and an empty, strict MCP configuration. Other main roles retain their selected
+policies, and explicit personal model/effort overrides remain available.
+
+## Global instruction files
+
+Activated sessions include the user's global instruction documents by default.
+**Custom → My global instruction files** can exclude them, or use
+`agent-launch --preset balanced --exclude-global-instructions claude`. The CLI flag
+sets Custom's initial choice; the final visible choice is what gets saved and run.
+The choice is retained by managed resume, which cannot change it through a new flag.
+
+Exclusion currently supports Claude Code 2.1.263 and newer: a per-call
+`claudeMdExcludes` setting omits the global `CLAUDE.md`, its imports, and user
+`rules/`. Project instructions and project memory remain, as do native settings,
+authentication, tool registrations, and permissions. No global file is rewritten.
+An existing CLI `--settings` argument, ambiguous relative/empty configuration home,
+symlinks, glob characters in the configuration path, or a project/global file alias
+is refused rather than replaced or silently included. Current Codex exclusion is
+unavailable; its native loader has no selective global-document switch. Vanilla
+and ordinary CLI launches retain their native loading behavior.
+This controls automatic instruction loading, not file access or memory erasure:
+tools can still open files, and project memory or prior conversation content can
+contain instructions independently of the excluded documents.
+
+## Native hooks and agents
+
+Native corpus consumption is default-off. `agent-bios corpus snapshot --host codex
+--native --json` (or `--host claude`) composes a preview; `agent-launch --corpus-native`
+opts one configured session into selected corpus hooks. Both hosts use the same
+installed Python carrier and typed `event`/`matcher` binding. Authoring accepts the
+combined event vocabulary; compilation reports an event unsupported by the selected
+host without changing its name or executing it through another event.
+
+Claude receives a namespaced plugin per CorpusRef through `--plugin-dir`. Codex
+receives inline `hooks.<Event>` config through per-session `-c` arguments. Existing
+user, project and session hooks remain present, and resume retains the pin's exact
+registrations. Neither adapter installs global hooks. Codex hook enablement and native
+trust still apply: new or changed definitions need review in `/hooks`. Discovery is
+checked before launch, but discovery alone does not establish execution. Hooks use the
+host's command permissions; opting in permits the selected carrier to run. Editing an
+event binding does not rewrite the Python carrier's input/output contract.
+
+Native corpus agents currently use Claude plugins and retain authored frontmatter and
+plugin-qualified names, distinct from launcher's bare tier agents. A Codex agent
+projection still needs to translate agent-specific model and tool restrictions; this
+does not limit shared hook delivery. Arbitrary prose promoted to `event` or `delegated`
+cannot become executable, and hidden discovery/config members are refused.
+
+## Optional shell connection
+
+**Shell connection** in the root TUI offers **Restore connection** and **Remove
+connection**, with confirmation before writing. The same owner is available as
+`agent-bios shell` (status), `agent-bios shell restore`, and `agent-bios shell remove`;
+`--dry-run` previews either action. Restore backs up existing files and adds one
+managed block to `${ZDOTDIR:-$HOME}/.zshrc`, plus a managed `shell.zsh`. Open a new
+terminal or source that `.zshrc` to load it. Interactive, argument-free `claude` and
+`codex` then open the TUI; argument-bearing and non-TTY calls go to the original CLI
+without added permission flags. Removal preserves other shell text and withdraws
+loaded managed wrappers on the next shell command. An edited managed file or block
+is preserved and reported for reconciliation, not overwritten. Backups remain private
+under `runtime/shell-backups/`; `ZDOTDIR` must match the connection's recorded path.
+Updates preserve an opted-in connection; reset and uninstall remove it. This setting
+never edits global `AGENTS.md`/`CLAUDE.md`, project files, or corpus content. Ordinary
+private installation also leaves those globals alone; explicit `migrate` can remove
+the old agent-bios-managed regions and imports while preserving user-authored text.
+First opt-in records ownership before publishing shell wiring, so interrupted restores
+remain recoverable. Reset and uninstall also detect receipt-less managed scripts from
+older interrupted restores. Install repairs a missing or non-executable owned launcher;
+an unavailable launcher falls back to the native CLI. Recovery rechecks path ancestors
+before writing and refuses redirected symlink targets.
+
+## Scripted launches and forwarded arguments
+
+Both the legacy shell adapter and the optional private shell connection preserve
+argument-bearing and non-TTY calls as direct backend invocations. The private
+connection adds no permission flags on that path. Without opting in, the private
+default installs no shell functions; an explicit `agent-launch` call projects a
+launch profile or corpus snapshot.
+
+Direct `agent-launch` calls still require a valid profile to resolve the backend command and its default arguments. `--preset`, `--custom`, or `--dry-run` select the configured-launch path even when non-TTY or combined with `--no-tui`; a non-TTY bare `--dry-run` deterministically uses Balanced, and a custom profile without that preset must pass `--preset NAME`. Forwarded backend arguments are appended verbatim after the projected defaults; one that would override a projected option (the seat, the contract, delegation, policy) is refused at launch so the contract keeps describing the run, and the summary discloses forwarded arguments when present. For scripted configured launches, call `$HOME/.local/bin/agent-launch --preset NAME --yes HOST -- ...` or add `$HOME/.local/bin` to `PATH`. The summary goes to stderr so backend stdout stays machine-consumable.
+
+## Review routing
+
+Review runs cross-family by default (`review_family`, default `cross`; `same` selects same-family projection): because the main's tiers are one model family, every dispatchable review route — native and the deep route — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, deep via plain `codex exec -m <frontier model> -c model_reasoning_effort="ultra"` with a self-contained packet on stdin — `-c service_tier="fast"` is the explicit faster, shallower opt-in); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, deep via the `claude` CLI headless with the keyword `ultracode` in the prompt, which is what opens Claude Code's dynamic workflow for that turn). The concrete reviewer command, resolved absolute path, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. A reviewer this launcher has never seen is yours to add: **Register another reviewer…** in the review editor asks for the descriptor a method needs, proves the candidate by running it through the real config reader before a byte is written, and appends it to `review-methods.local.toml` beside your config — a file the installer never deploys, verifies, or overwrites, whose entries face exactly the validation a shipped one does and whose name may not shadow a shipped method. A refusal shows the reader's own message and leaves that file byte-identical. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
+
+## Internal adapters and permission boundaries
+
+When the internal Codex wrappers are available to a configured route, `codex-helm` follows the local CLI default and launches the HELM main with `--dangerously-bypass-approvals-and-sandbox`; an explicit `--sandbox MODE` disables bypass for that run regardless of flag order. `AGENTS.md` gives root/main local Codex sessions standing ordinary-subagent authorization when the delegation gates fire. A non-Ultra HELM main sets native multi-agent off by default and instructs HELM to send tiered dispatch through the internal `codex-run` adapter, where the selected model, effort, and sandbox are pinned; native multi-agent defaults on only when the HELM main itself is explicitly Ultra. FRONTIER is instructed to run as a separate `gpt-6-astra` root that is always read-only, at max by default, Ultra for genuinely divisible complex work, or a lower supported effort when cost or latency dominates. Because the HELM main has bypass authority and arbitrary expert `-c` by design, this dispatch route is an instruction-backed, live-E2E-verified default rather than a security boundary. Keep `codex-run` as the low-level internal adapter, not as a user-facing policy boundary. Both wrappers accept `-c key=value` as an expert override, and that override may intentionally change wrapper defaults for a single run. The private installer keeps wrapper files in its immutable release rather than populating `$CODEX_HOME/bin`; a route that still names a native-home wrapper is unavailable until its adapter path is resolved.
+
+`claude-run` is the Claude-side review adapter carried by the release, and it takes `--model` and `--effort` to pin the seat. Omitting either warns and dispatches anyway, matching `codex-run`: refusing outright turned "the review ran unpinned" into "the review did not run", which is the worse of the two. The honest signal is downstream instead — an unpinned dispatch can name no seat, so it emits no receipt and the method adjudicates to UNKNOWN rather than to a clean pass. Its default denies the mutating tools, which is not the OS-level sandbox its Codex twin gets — do not read the two defaults as equivalent guarantees.
+
+## Review receipts
+
+**Review receipts.** A launch reports what it *projected*, because at launch no review has run — so a clean verdict without a receipt is PROPOSED, never ACHIEVED. Given `REVIEW_RECEIPT_DIR`, both adapters record what they observed of the dispatch they just performed: exit status, a hash of the packet fed in, a hash of the bytes returned, and the seat actually sent. Unset, they behave exactly as they would otherwise and write nothing. `agent-launch --fold-receipts DIR PACKET MAIN_DISPATCH_ID` folds a run into a `ReviewReceipts/v1` bundle — several passes of one method become the one record it is judged on — and `agent-launch --verify-receipts PLAN BUNDLE` adjudicates it, exiting non-zero unless every selected method verified. Adapting another tool needs no change here: call `agent-launch --emit-receipt` from your adapter and prove it conforms with `agent-launch --check-adapter SEAT -- CMD`, which is adjudicated by the same code that credits a real review. A receipt is still written by whoever ran the review, so this buys drift rather than honesty: what it stops is a reviewer that quietly never ran, returned nothing, or exited non-zero reading as a clean pass.
+
+See [verification and limits](session-model.md#verification-and-limits) for the evidence boundary, authenticated resume, and unsupported native named profiles.