agent-bios 0.9.0 → 0.9.2

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/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/package.json

@@ -1,6 +1,7 @@
 {
   "name": "agent-bios",
-  "version": "0.9.0",
+  "version": "0.9.2",
+  "releaseDate": "2026-07-23",
   "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"
@@ -607,6 +609,9 @@ def _build_app_class():
     def setup_panel(plan):
         panel = Static("\n".join(setup_summary_lines(plan)), id="al-setup")
         panel.border_title = "Current setup"
+        release = version_label()
+        if release:
+            panel.border_subtitle = release
         return panel
 
     class MenuScreen(ModalScreen):
@@ -1458,6 +1463,13 @@ CORPUS_STATUS_PATH = pathlib.Path(
     )
 )
 
+VERSION_INFO_PATH = pathlib.Path(
+    os.environ.get(
+        "AGENT_LAUNCH_VERSION_FILE",
+        str(pathlib.Path.home() / ".local/share/agent-bios/version.json"),
+    )
+)
+
 
 def load_corpus_status() -> dict[str, Any] | None:
     try:
@@ -1466,6 +1478,22 @@ def load_corpus_status() -> dict[str, Any] | None:
         return None
 
 
+def version_label() -> str | None:
+    """The deployed agent-bios version + release date for the TUI, or None when
+    the marker is absent (uninstalled / dev checkout). `agent-bios install`
+    writes it from package.json (version + releaseDate). This is the deploy /
+    system version — distinct from the corpus content version in the distill hub."""
+    try:
+        info = json.loads(VERSION_INFO_PATH.read_text())
+    except (OSError, ValueError):
+        return None
+    version = info.get("version") if isinstance(info, dict) else None
+    if not version:
+        return None
+    released = info.get("releaseDate")
+    return f"agent-bios v{version} · {released}" if released else f"agent-bios v{version}"
+
+
 def corpus_summary_lines(status: dict[str, Any] | None) -> list[str]:
     """Panel body for the Session Distill area: which corpus content is
     live, through which mechanisms, and whether the corpus is rolled back."""
@@ -1683,8 +1711,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 +1727,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 +1782,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 +1791,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 +1811,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 +1839,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 +2072,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,113 @@ 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)"
+            )
+
+        # Version line: version_label reads the deployed version marker
+        # ($STATE_DIR/version.json) that install writes from package.json. A
+        # present marker yields "agent-bios v<version> · <releaseDate>"; an absent
+        # one yields None (uninstalled / dev checkout, so the panel shows no line).
+        saved_version_path = launcher_module.VERSION_INFO_PATH
+        try:
+            version_marker = pathlib.Path(tempfile.mkdtemp()) / "version.json"
+            version_marker.write_text('{"version": "9.9.9", "releaseDate": "2026-01-02"}')
+            launcher_module.VERSION_INFO_PATH = version_marker
+            if launcher_module.version_label() != "agent-bios v9.9.9 · 2026-01-02":
+                mark_fail(
+                    "agent-launch version_label wrong with a marker present: "
+                    f"{launcher_module.version_label()!r}"
+                )
+            launcher_module.VERSION_INFO_PATH = version_marker.parent / "absent.json"
+            if launcher_module.version_label() is not None:
+                mark_fail("agent-launch version_label must be None when the marker is absent")
+        finally:
+            launcher_module.VERSION_INFO_PATH = saved_version_path
+
     with tempfile.TemporaryDirectory() as raw_tmp:
         tmp = pathlib.Path(raw_tmp)
         backend = tmp / "backend"
@@ -719,10 +826,13 @@ if launcher.is_file() and launch_profile:
             mark_fail(f"fake launch profile did not replace every backend: {fake_commands!r}")
             fake_profile = pathlib.Path("/nonexistent/unsafe-fixture")
         env = os.environ.copy()
+        version_fixture = tmp / "version.json"
+        version_fixture.write_text('{"version": "9.9.9", "releaseDate": "2026-01-02"}')
         env.update(
             FAKE_LAUNCH_ARGV=str(argv_log),
             AGENT_LAUNCH_CONFIG=str(fake_profile),
             XDG_CACHE_HOME=str(tmp / "cache"),
+            AGENT_LAUNCH_VERSION_FILE=str(version_fixture),
         )
 
         pty_env = env.copy()
@@ -841,7 +951,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).
@@ -887,6 +997,8 @@ if launcher.is_file() and launch_profile:
             < positions[b"Options ("]
         ):
             mark_fail("agent-launch layout is not setup then description then options")
+        if b"agent-bios v9.9.9" not in transcript:
+            mark_fail("agent-launch does not show the deployed version line in the setup panel")
 
         _, picker_status = run_picker_scenario(
             "root escape cancellation",
@@ -1217,7 +1329,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 +1702,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",

package/scripts/install.sh

@@ -476,6 +476,24 @@ cmd_install() {
   else
     log "note: corpus-status projection unavailable (versions.json/ledger missing?)"
   fi
+  # Deploy/system version marker for the launcher's TUI version line, read from
+  # package.json (version + releaseDate) — distinct from the corpus content
+  # version. Best-effort: a failure here never fails the install.
+  if [ "$DRY_RUN" != 1 ]; then
+    if python3 - "$REPO/package.json" "$STATE_DIR/version.json" <<'PY' 2>/dev/null
+import json, sys
+pkg = json.load(open(sys.argv[1]))
+with open(sys.argv[2], "w") as f:
+    json.dump({"version": pkg.get("version"), "releaseDate": pkg.get("releaseDate")}, f)
+    f.write("\n")
+PY
+    then
+      printf '%s\n' "$STATE_DIR/version.json" >> "$MANIFEST"
+      info "version marker written ($STATE_DIR/version.json)"
+    else
+      log "note: version marker not written (package.json unreadable)"
+    fi
+  fi
   log ""
   log "Verifying deployment..."
   if cmd_verify; then