agent-bios 0.8.0 → 0.9.1

package/README.md

@@ -68,7 +68,7 @@ agent-bios uninstall   # remove deployed files and the zsh hook
 
 From a git clone, run `./scripts/install.sh install` directly (the same CLI). `install` respects `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `AGENT_LAUNCH_VENV`, and `ZDOTDIR`; `--dry-run` prints actions without changing anything. Deploy to **every active environment in one sitting** — a partial deploy leaves a shared global pointing at a guide some environment lacks; globals are English only. Replaced files are backed up under `~/.local/share/agent-bios/backups/<timestamp>/`, and the installed set is recorded in a manifest that `uninstall` consumes. The published npm package ships only the deploy set (never `settings.json`, `config.toml`, `ko/`, or `benchmarks/`).
 
-In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **General user** (Vanilla: the bare CLI with no launch contract, no tier bindings, standard permissions; domain presets arrive with the non-technical rollout), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off), **Session distill** — then a preset within it. In Builder, select **Custom** to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`scripts/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native, onto, and ultracode — 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`, onto via an `llmOverride` to the configured openai seat, ultracode via the `$ultracode-for-codex` Codex skill); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, onto via an `llmOverride` to the anthropic seat, ultracode via `claude --effort ultracode -p` — Claude Code's headless `/workflows` ultracode mode, verified accepted on claude 2.1.210). The concrete reviewer command, resolved absolute path, `llmOverride`, 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. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
+In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **Software Engineer** (repo-scoped work that defers to the project's own AGENTS.md/CLAUDE.md: **Vanilla**, the bare CLI with no launch contract, tier bindings, or applied permissions, plus **Custom**; SE-specific review defaults arrive later), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off, plus Custom), **Session distill** — then a preset within it. Select **Custom** (in Software Engineer or Builder) to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`scripts/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native, onto, and ultracode — 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`, onto via an `llmOverride` to the configured openai seat, ultracode via the `$ultracode-for-codex` Codex skill); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, onto via an `llmOverride` to the anthropic seat, ultracode via `claude --effort ultracode -p` — Claude Code's headless `/workflows` ultracode mode, verified accepted on claude 2.1.210). The concrete reviewer command, resolved absolute path, `llmOverride`, 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. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
 
 At the shell-wrapper boundary, every argument-bearing command (`codex exec ...`, `claude -p ...`) and every non-TTY invocation skips launch-profile projection and preserves caller arguments. The Claude direct path intentionally retains its wrapper default, `--dangerously-skip-permissions`. `codex --no-tui ...` / `claude --no-tui ...` explicitly take that direct path, and `AGENT_LAUNCH_TUI=0` disables zero-argument TUI interception for a process tree.
 

package/claude/guides/tooling-gotchas.md

@@ -125,6 +125,13 @@ depends on it, pin it explicitly instead of trusting the environment.
   leaving stale, unreferenced definitions live. After updating, re-read the
   resource, check definitions and active references separately, and remove
   the orphans explicitly.
+- **A new revision is not live traffic**: on a runtime that pins traffic to a
+  named revision (e.g. Cloud Run with a fixed split), `gcloud run deploy` (or
+  the equivalent) creates the new revision but shifts no traffic to it — the
+  previous revision keeps serving until an explicit `gcloud run services
+  update-traffic`. Read the "deploy succeeded" message as "a revision exists",
+  not "the new code is serving"; verify the live traffic split before
+  concluding the deploy took effect.
 - **Perimeter controls need the enforcement point's own logs**: an agent-side
   fetch is not an independent external observer — its egress IP and caching
   path are opaque, and it may share the protected network or serve a stale

package/codex/guides/tooling-gotchas.md

@@ -125,6 +125,13 @@ depends on it, pin it explicitly instead of trusting the environment.
   leaving stale, unreferenced definitions live. After updating, re-read the
   resource, check definitions and active references separately, and remove
   the orphans explicitly.
+- **A new revision is not live traffic**: on a runtime that pins traffic to a
+  named revision (e.g. Cloud Run with a fixed split), `gcloud run deploy` (or
+  the equivalent) creates the new revision but shifts no traffic to it — the
+  previous revision keeps serving until an explicit `gcloud run services
+  update-traffic`. Read the "deploy succeeded" message as "a revision exists",
+  not "the new code is serving"; verify the live traffic split before
+  concluding the deploy took effect.
 - **Perimeter controls need the enforcement point's own logs**: an agent-side
   fetch is not an independent external observer — its egress IP and caching
   path are opaque, and it may share the protected network or serve a stale

package/config/agent-launch.toml

@@ -116,7 +116,7 @@ claude_permission_mode = "bypassPermissions"
 [presets.vanilla]
 label = "Vanilla"
 description = "Plain CLI session: no launch contract, no tier bindings, standard permissions — exactly what the bare backend gives you."
-mode = "general"
+mode = "software-engineer"
 main_tier = "helm"
 frontier_effort = "max"
 review_setup = "none"

package/config/promotions.json

@@ -1,4 +1,12 @@
 {
   "version": 1,
-  "promotions": []
+  "promotions": [
+    {
+      "learning_id": "a6feee41-2aeb-4fb6-acc6-4584c5c1336c",
+      "tier": "domain",
+      "domains": [
+        "builder-base"
+      ]
+    }
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bios",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
   "bin": {
     "agent-bios": "scripts/install.sh"

package/scripts/agent-launch.py

@@ -44,17 +44,19 @@ EFFORT_DESCRIPTIONS = {
 }
 CUSTOM_PRESET = "__custom__"
 OTHER_MODEL = "__other_model__"
-# Root-menu grouping for presets: "builder" (tunable, includes Custom), "general"
-# (plain CLI presets like Vanilla), "distill" (opens the Session Distill hub).
-# A preset with a missing/unknown mode defaults to "builder" so presets written
-# before this field existed (including saved/local user presets) keep working.
-GENERAL_MODE = "general"
+# Root-menu grouping for presets: "builder" (tunable tier presets, includes
+# Custom), "software-engineer" (repo-scoped work under the project's own
+# AGENTS.md/CLAUDE.md — the bare Vanilla session plus Custom), "distill" (opens
+# the Session Distill hub). A preset with a missing/unknown mode defaults to
+# "builder" so presets written before this field existed (including saved/local
+# user presets, and any that still carry the former "general" value) keep working.
+SWE_MODE = "software-engineer"
 DEFAULT_PRESET_MODE = "builder"
 # The mode value that opens the Session Distill hub instead of a preset
 # submenu; doubles as the option value on the root Mode menu so selecting it
 # needs no translation.
 DISTILL_MODE = "distill"
-PRESET_MODES = (GENERAL_MODE, DEFAULT_PRESET_MODE, DISTILL_MODE)
+PRESET_MODES = (SWE_MODE, DEFAULT_PRESET_MODE, DISTILL_MODE)
 # User-saved presets live beside the deployed config, in a file the installer
 # neither deploys nor verifies, so they survive `agent-bios install`.
 USER_PRESETS_NAME = "presets.local.toml"
@@ -1683,8 +1685,9 @@ def pick_mode_and_preset(
     ui: TextualUI | None,
     resume_mode: str | None,
 ) -> tuple[str, bool, str]:
-    """Root menu: a 3-way mode picker (General user / Builder / Session
-    distill), then that mode's preset submenu (Builder also lists Custom).
+    """Root menu: a 3-way mode picker (Software Engineer / Builder / Session
+    distill), then that mode's preset submenu (Software Engineer and Builder
+    both list Custom).
 
     Esc in the submenu returns to the mode picker; Esc at the mode picker
     cancels the launcher, matching the picker's prior root Esc/q semantics.
@@ -1698,10 +1701,11 @@ def pick_mode_and_preset(
         if mode is None:
             mode_options = [
                 MenuOption(
-                    GENERAL_MODE,
-                    "General user",
-                    "Plain presets with nothing launch-specific applied, like "
-                    "Vanilla: no tier bindings or launch contract.",
+                    SWE_MODE,
+                    "Software Engineer",
+                    "Repo-scoped work that defers to the project's own "
+                    "AGENTS.md/CLAUDE.md: a bare Vanilla session, or Custom to "
+                    "configure one.",
                 ),
                 MenuOption(
                     DEFAULT_PRESET_MODE,
@@ -1752,7 +1756,7 @@ def pick_mode_and_preset(
             for name, data in presets.items()
             if preset_mode(data) == mode
         ]
-        if mode == DEFAULT_PRESET_MODE:
+        if mode in (DEFAULT_PRESET_MODE, SWE_MODE):
             options.append(
                 MenuOption(
                     CUSTOM_PRESET,
@@ -1761,11 +1765,16 @@ def pick_mode_and_preset(
                 )
             )
         default = mode_default_preset(presets, mode) or CUSTOM_PRESET
+        # Custom always starts from the builder default (an applied baseline), so a
+        # Custom entered from Software Engineer mode applies its settings instead of
+        # inheriting Vanilla's bare short-circuit. (SE-specific review defaults are
+        # deferred; today Custom shares the builder baseline.)
+        custom_base = mode_default_preset(presets, DEFAULT_PRESET_MODE) or default
         if ui is not None and default != CUSTOM_PRESET:
             ui.set_plan(build_plan(config, host, default))
 
         def preview_preset(value: str) -> dict[str, Any]:
-            target = default if value == CUSTOM_PRESET else value
+            target = custom_base if value == CUSTOM_PRESET else value
             return build_plan(config, host, target)
 
         try:
@@ -1776,7 +1785,7 @@ def pick_mode_and_preset(
             mode = None
             continue
         if selected == CUSTOM_PRESET:
-            return default, True, mode
+            return custom_base, True, mode
         return selected, False, mode
 
 
@@ -1804,6 +1813,13 @@ def select_plan(
         plan = build_plan(config, host, selected_name)
         if selected_custom:
             plan["label"] = f"Custom ({plan['label']})"
+            # A customized plan is always an applied setup, never the bare Vanilla
+            # short-circuit — even if custom_base fell back to an SE-mode preset
+            # under a stripped config with no builder presets. project_args
+            # projects the bare backend iff mode == SWE_MODE, so force a Custom
+            # launch out of that mode.
+            if plan.get("mode") == SWE_MODE:
+                plan["mode"] = DEFAULT_PRESET_MODE
         if ui is not None:
             ui.set_plan(plan)
         if selected_custom:
@@ -2030,11 +2046,13 @@ def claude_agents(plan: dict[str, Any]) -> str:
 
 def project_args(plan: dict[str, Any], materialize_agents: bool = True) -> list[str]:
     host = plan["host"]
-    if plan.get("mode") == GENERAL_MODE:
-        # General mode is defined as the plain backend with nothing applied: no
-        # launch contract, no tier pinning, no agents, no permission/sandbox
-        # flag. Short-circuit here so that invariant holds structurally instead
-        # of depending on every general-mode preset being configured just so.
+    if plan.get("mode") == SWE_MODE:
+        # Software Engineer's Vanilla preset is the plain backend with nothing
+        # applied: no launch contract, no tier pinning, no agents, no
+        # permission/sandbox flag — it defers entirely to the repo's own
+        # AGENTS.md/CLAUDE.md. Short-circuit so that invariant holds
+        # structurally. Custom entered from this mode re-bases to the builder
+        # default, so its plan mode is "builder" and its settings DO apply.
         return []
     main = plan["tiers"][plan["main_tier"]]
     main_effort = tier_effort(plan, plan["main_tier"])

package/scripts/check-parity.sh

@@ -677,6 +677,93 @@ if launcher.is_file() and launch_profile:
         if not scripted_ui.checked or not scripted_plan.get("_launch_confirmed"):
             mark_fail("agent-launch scripted Custom hub did not reach final confirmation")
 
+        # Software Engineer mode: its submenu is exactly Vanilla + Custom; Vanilla
+        # stays the bare backend (no launch contract), while Custom re-bases to the
+        # applied builder baseline rather than inheriting Vanilla's bare
+        # short-circuit. Driven directly through pick_mode_and_preset — the root
+        # mode picker is TTY-only, so a piped/non-TTY run defaults past it.
+        class SEModeUI:
+            def __init__(self, pick):
+                self._pick = pick
+                self.submenu_labels = None
+
+            def set_plan(self, plan):
+                pass
+
+            def choose(self, title, options, default, allow_back, preview=None, corpus_lines=None):
+                if title == "Mode":
+                    if launcher_module.SWE_MODE not in {option.value for option in options}:
+                        mark_fail("agent-launch root menu is missing the Software Engineer mode")
+                    return launcher_module.SWE_MODE
+                if title == "Preset":
+                    self.submenu_labels = [option.label for option in options]
+                    return self._pick
+                raise AssertionError(f"unexpected scripted menu: {title}")
+
+        se_vanilla_ui = SEModeUI("vanilla")
+        se_v_name, se_v_custom, _ = launcher_module.pick_mode_and_preset(
+            launch_profile, "codex", se_vanilla_ui, None
+        )
+        if se_vanilla_ui.submenu_labels != ["Vanilla", "Custom"]:
+            mark_fail(
+                "agent-launch Software Engineer submenu must be exactly Vanilla + "
+                f"Custom, got {se_vanilla_ui.submenu_labels}"
+            )
+        if se_v_custom or se_v_name != "vanilla":
+            mark_fail("agent-launch SE -> Vanilla must select the vanilla preset directly")
+        elif launcher_module.project_args(
+            launcher_module.build_plan(launch_profile, "codex", se_v_name),
+            materialize_agents=False,
+        ):
+            mark_fail("agent-launch SE -> Vanilla must project the bare backend (no launch contract)")
+
+        se_custom_ui = SEModeUI(launcher_module.CUSTOM_PRESET)
+        se_c_name, se_c_custom, _ = launcher_module.pick_mode_and_preset(
+            launch_profile, "codex", se_custom_ui, None
+        )
+        if not se_c_custom:
+            mark_fail("agent-launch SE -> Custom must request the settings hub")
+        elif not launcher_module.project_args(
+            launcher_module.build_plan(launch_profile, "codex", se_c_name),
+            materialize_agents=False,
+        ):
+            mark_fail("agent-launch SE -> Custom must project an applied setup, not the bare backend")
+
+        # Under a config with no builder presets, custom_base falls back to the SE
+        # default (vanilla), so SE -> Custom builds a plan in SWE_MODE; select_plan
+        # must force a customized plan out of that bare short-circuit so the user's
+        # settings are not silently discarded. Driven through the real select_plan.
+        class SECustomHubUI:
+            def set_plan(self, plan):
+                pass
+
+            def choose(self, title, options, default, allow_back, preview=None, corpus_lines=None):
+                if title == "Mode":
+                    return launcher_module.SWE_MODE
+                if title == "Preset":
+                    return launcher_module.CUSTOM_PRESET
+                if title == "Custom settings":
+                    return "start"
+                raise AssertionError(f"unexpected scripted menu: {title}")
+
+            def prompt_text(self, label, default):
+                return default
+
+        stripped_profile = dict(launch_profile)
+        stripped_profile["presets"] = {
+            name: data
+            for name, data in launch_profile["presets"].items()
+            if name in ("vanilla", "session-distill")
+        }
+        stripped_custom_plan = launcher_module.select_plan(
+            stripped_profile, "codex", None, False, SECustomHubUI()
+        )
+        if not launcher_module.project_args(stripped_custom_plan, materialize_agents=False):
+            mark_fail(
+                "agent-launch SE -> Custom under a no-builder-preset config must still "
+                "project an applied setup (customization must not be silently discarded)"
+            )
+
     with tempfile.TemporaryDirectory() as raw_tmp:
         tmp = pathlib.Path(raw_tmp)
         backend = tmp / "backend"
@@ -841,7 +928,7 @@ if launcher.is_file() and launch_profile:
                 os.close(master)
             return bytes(transcript), picker_status
 
-        # Root menu is now a Mode picker (General user / Builder / Session
+        # Root menu is now a Mode picker (Software Engineer / Builder / Session
         # distill); Builder is the default highlight and lists Custom. Reaching
         # Custom means: Enter the root to open Builder's preset submenu, then
         # step down through its fixed presets (Balanced default-highlighted).
@@ -1217,7 +1304,7 @@ if launcher.is_file() and launch_profile:
         # TERM=dumb routes to numbered prompts (textual renders on any usable
         # terminal, so the numbered fallback is gated on TERM/non-TTY/textual
         # availability, not a terminfo probe). 'b' is the numbered back command.
-        # The root Mode menu is fixed (General=1, Builder=2, Session distill=3)
+        # The root Mode menu is fixed (Software Engineer=1, Builder=2, Session distill=3)
         # regardless of preset count; only Custom's position within Builder's
         # own preset submenu depends on how many builder-mode presets exist.
         builder_preset_count = sum(
@@ -1590,7 +1677,7 @@ if launcher.is_file() and launch_profile:
                         "agent-launch Claude expert overrides were not appended last"
                     )
 
-        # Vanilla (mode=general): the raw backend with nothing applied — no
+        # Vanilla (mode=software-engineer): the raw backend with nothing applied — no
         # launch contract, no agents, no permission-bypass flag.
         vanilla_configured = invoke([
             sys.executable, str(launcher), "--preset", "vanilla", "--yes", "--dry-run",