pi-oxidized 0.1.1

package/crates/pi/src/cli/bootstrap.rs

@@ -0,0 +1,2134 @@
+//! CLI bootstrap: argv → resolved mode + runtime handle, or short-circuit exit.
+//!
+//! Ports the ordered pipeline of `.references/pi/packages/coding-agent/src/
+//! main.ts` into a testable orchestrator. Everything that touches the process
+//! (env vars, TTY status, stdin, stdout/stderr) flows through an injected
+//! [`BootstrapIo`] trait; everything that builds the agent-session runtime
+//! flows through an injected [`RuntimeFactory`] trait. Pure helpers
+//! ([`resolve_app_mode`], validators) are public so the integrator and tests
+//! can drive them directly.
+//!
+//! # Pipeline order (matches `main.ts:472-858`)
+//!
+//! 1. Reset timings (no-op here; the timings module is a sibling concern).
+//! 2. Offline mode: `args.contains("--offline") || PI_OFFLINE` → set
+//!    `PI_OFFLINE=1`, `PI_SKIP_VERSION_CHECK=1`.
+//! 3. Package/config short-circuit (`pi install …`, `pi config …`).
+//! 4. `parse_args` + report diagnostics (errors exit 1, warnings continue).
+//! 5. `--version` → print version, exit 0.
+//! 6. `--export` → export session file, exit 0/1.
+//! 7. `resolve_app_mode` + `take_over_stdout` (unless interactive or plain
+//!    runtime metadata command).
+//! 8. RPC + `@file` guard.
+//! 9. Fork / session-id flag validation.
+//! 10. `run_migrations` (records `migrated_providers` + `deprecation_warnings`).
+//! 11. Startup settings + first-time setup (interactive only — gated, the UI
+//!     surface itself is a sibling slice).
+//! 12. Session-dir resolution + `create_session_manager`.
+//! 13. `--name` append + validation.
+//! 14. Trust store + resource paths.
+//! 15. Build runtime via factory.
+//! 16. `--help` (with extension flags) → exit 0.
+//! 17. `--list-models` → exit 0.
+//! 18. Read piped stdin (skip RPC); demote interactive→print when stdin present.
+//! 19. Prepare initial message.
+//! 20. Report runtime diagnostics (errors exit 1, with extension hint when
+//!     relevant).
+//! 21. Non-interactive requires `session.model`, else no-models message + exit 1.
+//! 22. `PI_STARTUP_BENCHMARK` guard.
+//! 23. Return [`BootstrapOutcome::Dispatch`] with the resolved mode + handle.
+
+use std::io;
+use std::path::{Path, PathBuf};
+use std::pin::Pin;
+
+use futures::future::BoxFuture;
+
+use crate::cli::args::{Args, DiagnosticLevel, ListModels, Mode};
+use crate::cli::package_manager_cli::{self, DispatchPlatform, PackageHandler, PackageOutput};
+use crate::core::agent_session_runtime::AgentSessionRuntime;
+use crate::core::config::{ENV_SESSION_DIR, VERSION, expand_tilde_path};
+use crate::core::migrations::{self, MigrationResult};
+use crate::core::output_guard::{self, ProductOutput};
+use crate::core::sessions::SessionManager;
+
+/// Resolved application mode.
+///
+/// Mirrors TypeScript `AppMode = interactive | print | json | rpc`.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum AppMode {
+    /// Interactive TUI session.
+    Interactive,
+    /// Single-shot text print.
+    Print,
+    /// JSONL event print.
+    Json,
+    /// Headless JSONL RPC server.
+    Rpc,
+}
+
+impl AppMode {
+    /// Returns `true` for the JSON output mode.
+    #[must_use]
+    pub const fn is_json(self) -> bool {
+        matches!(self, Self::Json)
+    }
+
+    /// Returns `true` for the RPC server mode.
+    #[must_use]
+    pub const fn is_rpc(self) -> bool {
+        matches!(self, Self::Rpc)
+    }
+
+    /// Returns `true` for the interactive TUI mode.
+    #[must_use]
+    pub const fn is_interactive(self) -> bool {
+        matches!(self, Self::Interactive)
+    }
+}
+
+/// Resolve the application mode from parsed args and TTY status.
+///
+/// Mirrors `resolveAppMode` (`main.ts:99-110`):
+/// - `--mode rpc` → RPC (highest precedence, forces non-interactive).
+/// - `--mode json` → JSON.
+/// - `--print` or non-TTY stdin/stdout → Print.
+/// - Otherwise → Interactive.
+#[must_use]
+pub fn resolve_app_mode(parsed: &Args, stdin_is_tty: bool, stdout_is_tty: bool) -> AppMode {
+    match parsed.mode {
+        Some(Mode::Rpc) => AppMode::Rpc,
+        Some(Mode::Json) => AppMode::Json,
+        Some(Mode::Text) | None => {
+            if parsed.print || !stdin_is_tty || !stdout_is_tty {
+                AppMode::Print
+            } else {
+                AppMode::Interactive
+            }
+        }
+    }
+}
+
+/// Whether `--help`/`--list-models` should run without taking over stdout.
+///
+/// Mirrors `isPlainRuntimeMetadataCommand` (`main.ts:116-118`): true when the
+/// user did not pass `--print` or an explicit `--mode` and is asking for
+/// `--help` or `--list-models`. These commands print to stdout directly
+/// without the protocol takeover so the output reaches the user even when the
+/// runtime is built (e.g. to discover extension flags).
+#[must_use]
+pub fn is_plain_runtime_metadata_command(parsed: &Args) -> bool {
+    !parsed.print
+        && parsed.mode.is_none()
+        && (parsed.help || !matches!(parsed.list_models, ListModels::None))
+}
+
+/// Error returned by [`validate_fork_flags`] / [`validate_session_id_flags`].
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct FlagValidationError {
+    /// Verbatim message to surface on stderr (prefixed with `Error: `).
+    pub message: String,
+}
+
+/// `--fork` cannot combine with `--session`/`--continue`/`--resume`/`--no-session`.
+///
+/// Mirrors `validateForkFlags` (`main.ts:204-218`).
+///
+/// # Errors
+/// Returns an error when `--fork` is combined with any incompatible session flag.
+pub fn validate_fork_flags(parsed: &Args) -> Result<(), FlagValidationError> {
+    let Some(_fork) = parsed.fork.as_ref() else {
+        return Ok(());
+    };
+    let mut conflicts = Vec::new();
+    if parsed.session.is_some() {
+        conflicts.push("--session");
+    }
+    if parsed.r#continue {
+        conflicts.push("--continue");
+    }
+    if parsed.resume {
+        conflicts.push("--resume");
+    }
+    if parsed.no_session {
+        conflicts.push("--no-session");
+    }
+    if conflicts.is_empty() {
+        Ok(())
+    } else {
+        Err(FlagValidationError {
+            message: format!("--fork cannot be combined with {}", conflicts.join(", ")),
+        })
+    }
+}
+
+/// `--session-id` cannot combine with `--session`/`--continue`/`--resume`.
+///
+/// Mirrors `validateSessionIdFlags` (`main.ts:220-241`). The ID syntax check
+/// itself is delegated to `SessionManager`/`assert_valid_session_id` at
+/// session-construction time; this validator only covers the CLI-level
+/// conflicts.
+///
+/// # Errors
+/// Returns an error when `--session-id` is combined with `--session`,
+/// `--continue`, or `--resume`.
+pub fn validate_session_id_flags(parsed: &Args) -> Result<(), FlagValidationError> {
+    let Some(_id) = parsed.session_id.as_ref() else {
+        return Ok(());
+    };
+    let mut conflicts = Vec::new();
+    if parsed.session.is_some() {
+        conflicts.push("--session");
+    }
+    if parsed.r#continue {
+        conflicts.push("--continue");
+    }
+    if parsed.resume {
+        conflicts.push("--resume");
+    }
+    if conflicts.is_empty() {
+        Ok(())
+    } else {
+        Err(FlagValidationError {
+            message: format!(
+                "--session-id cannot be combined with {}",
+                conflicts.join(", ")
+            ),
+        })
+    }
+}
+
+/// Validate `--name`/`-n` post-parse.
+///
+/// The parser records an empty value verbatim (`--name ""` → `name = Some("")`).
+/// `main.ts:590-597` rejects empty/whitespace-only names with exit 1 before
+/// appending to session info.
+///
+/// # Errors
+/// Returns an error when `--name` is present but empty or whitespace-only.
+pub fn validate_name(parsed: &Args) -> Result<(), FlagValidationError> {
+    if let Some(name) = parsed.name.as_ref()
+        && name.trim().is_empty()
+    {
+        return Err(FlagValidationError {
+            message: "--name requires a non-empty value".to_owned(),
+        });
+    }
+    Ok(())
+}
+
+/// Truthy env-flag test matching `isTruthyEnvFlag` (`main.ts:94-97`).
+#[must_use]
+pub fn is_truthy_env_flag(value: Option<&str>) -> bool {
+    match value {
+        Some(v) => {
+            let lower = v.to_ascii_lowercase();
+            v == "1" || lower == "true" || lower == "yes"
+        }
+        None => false,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// I/O injection
+// ---------------------------------------------------------------------------
+
+/// Process-level I/O surface the bootstrap needs.
+///
+/// All methods are sync except [`Self::read_piped_stdin`]. Implementations are
+/// expected to be cheap to clone (`Arc`-backed) so the bootstrap can hold them
+/// across `.await` points.
+pub trait BootstrapIo: Send + Sync {
+    /// Read an environment variable.
+    fn env(&self, key: &str) -> Option<String>;
+    /// Set an environment variable for this process.
+    fn set_env(&self, key: &str, value: &str);
+    /// Process working directory.
+    fn cwd(&self) -> PathBuf;
+    /// Whether stdin is attached to a TTY.
+    fn stdin_is_tty(&self) -> bool;
+    /// Whether stdout is attached to a TTY.
+    fn stdout_is_tty(&self) -> bool;
+    /// Read piped stdin to EOF, returning `None` when empty/whitespace-only.
+    fn read_piped_stdin<'a>(
+        &'a self,
+    ) -> Pin<Box<dyn Future<Output = io::Result<Option<String>>> + Send + 'a>>;
+    /// Write a line to product stdout (newline appended).
+    fn write_stdout(&self, line: &str);
+    /// Write a line to product stderr (newline appended).
+    fn write_stderr(&self, line: &str);
+}
+
+// ---------------------------------------------------------------------------
+// Runtime factory injection
+// ---------------------------------------------------------------------------
+
+/// Inputs to [`RuntimeFactory::create`].
+pub struct RuntimeFactoryOptions {
+    /// Effective working directory.
+    pub cwd: String,
+    /// Agent config directory.
+    pub agent_dir: String,
+    /// Session manager bound to the chosen session.
+    pub session_manager: SessionManager,
+    /// Parsed CLI args (for extension flags, model overrides, tool gates).
+    pub parsed: Args,
+}
+
+/// Result of a successful runtime construction.
+pub struct RuntimeHandle {
+    /// The runtime owning the current session.
+    pub runtime: std::sync::Arc<AgentSessionRuntime>,
+}
+
+impl std::fmt::Debug for RuntimeHandle {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RuntimeHandle")
+            .field("runtime", &"<AgentSessionRuntime>")
+            .finish()
+    }
+}
+
+/// Injected factory that turns a session manager + CLI args into a live
+/// [`AgentSessionRuntime`].
+///
+/// Implementations wrap `create_agent_session_services` +
+/// `create_agent_session_from_services` + `AgentSessionRuntime::new`. A fake
+/// implementation in tests returns a lightweight runtime without network or
+/// filesystem access.
+pub trait RuntimeFactory: Send + Sync {
+    /// Build the runtime.
+    ///
+    /// # Errors
+    /// Implementation-defined; the error string is surfaced verbatim prefixed
+    /// with `Error: `.
+    fn create(
+        &self,
+        options: RuntimeFactoryOptions,
+    ) -> BoxFuture<'_, Result<RuntimeHandle, String>>;
+
+    /// Whether the factory has a usable interactive TUI runtime. The default
+    /// is `true`; a minimal/fake factory returns `false` so the bootstrap
+    /// short-circuits interactive runs with an actionable error instead of
+    /// launching an empty TUI.
+    fn supports_interactive(&self) -> bool {
+        true
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Outcome
+// ---------------------------------------------------------------------------
+
+/// Result of running the bootstrap pipeline.
+#[derive(Debug)]
+pub enum BootstrapOutcome {
+    /// Short-circuit: process should exit with this code and no further work.
+    Exit {
+        /// Process exit code.
+        code: u8,
+        /// Win32 `pi update` success must drain naturally.
+        drain_quirk: bool,
+    },
+    /// Continue to mode dispatch.
+    Dispatch(Dispatched),
+}
+
+/// A bootstrap that reached the dispatch stage.
+#[derive(Debug)]
+pub struct Dispatched {
+    /// Resolved application mode.
+    pub mode: AppMode,
+    /// Live runtime handle.
+    pub handle: RuntimeHandle,
+    /// Initial message assembled from stdin + `@file` + first CLI message.
+    pub initial_message: Option<String>,
+    /// Images attached to the initial message.
+    pub initial_images: Vec<pi_ai::ImageContent>,
+    /// Remaining CLI messages for follow-up prompts.
+    pub remaining_messages: Vec<String>,
+    /// Migration result (carried into interactive mode for changelog display).
+    pub migrations: MigrationResult,
+}
+
+// ---------------------------------------------------------------------------
+// Bootstrap driver
+// ---------------------------------------------------------------------------
+
+/// Inputs to [`run_bootstrap`].
+pub struct BootstrapInputs<'a> {
+    /// argv after the program name.
+    pub args: Vec<String>,
+    /// Process I/O surface.
+    pub io: &'a dyn BootstrapIo,
+    /// Runtime factory.
+    pub factory: &'a dyn RuntimeFactory,
+    /// Package-command handler (real or fake).
+    pub package_handler: &'a dyn PackageHandler,
+    /// Package-command output sink.
+    pub package_output: &'a dyn PackageOutput,
+}
+
+/// Run the bootstrap pipeline.
+///
+/// This is the pure-logic orchestration layer; all process interaction is
+/// routed through `inputs.io` and side-effecting package operations through
+/// `inputs.package_handler`.
+pub async fn run_bootstrap(inputs: BootstrapInputs<'_>) -> BootstrapOutcome {
+    let parsed = match initialize_bootstrap(&inputs) {
+        Ok(parsed) => parsed,
+        Err(exit) => return exit.into_outcome(),
+    };
+    let prepared = match prepare_session(&inputs, parsed).await {
+        Ok(prepared) => prepared,
+        Err(exit) => return exit.into_outcome(),
+    };
+    let (state, handle) = match create_runtime(&inputs, prepared).await {
+        Ok(runtime) => runtime,
+        Err(exit) => return exit.into_outcome(),
+    };
+    if let Some(outcome) = handle_runtime_metadata(inputs.io, &state, &handle).await {
+        return outcome;
+    }
+    finish_bootstrap(inputs.io, state, handle).await
+}
+
+type BootstrapStep<T> = Result<T, BootstrapExit>;
+
+struct PreparedSession {
+    parsed: Args,
+    app_mode: AppMode,
+    should_take_over_stdout: bool,
+    cwd: String,
+    migrations: MigrationResult,
+    agent_dir: String,
+    session_manager: SessionManager,
+}
+
+struct BootstrapState {
+    parsed: Args,
+    app_mode: AppMode,
+    should_take_over_stdout: bool,
+    cwd: String,
+    migrations: MigrationResult,
+}
+
+#[derive(Clone, Copy)]
+struct BootstrapExit {
+    code: u8,
+    drain_quirk: bool,
+}
+
+impl BootstrapExit {
+    fn into_outcome(self) -> BootstrapOutcome {
+        exit(self.code, self.drain_quirk)
+    }
+}
+
+fn exit(code: u8, drain_quirk: bool) -> BootstrapOutcome {
+    BootstrapOutcome::Exit { code, drain_quirk }
+}
+
+fn stop(code: u8, drain_quirk: bool) -> BootstrapExit {
+    BootstrapExit { code, drain_quirk }
+}
+
+fn fail(io: &dyn BootstrapIo, restore_stdout: bool, message: &str) -> BootstrapExit {
+    io.write_stderr(message);
+    if restore_stdout {
+        output_guard::restore_stdout();
+    }
+    stop(1, false)
+}
+
+fn initialize_bootstrap(inputs: &BootstrapInputs<'_>) -> BootstrapStep<Args> {
+    let mut parsed = crate::cli::args::parse_args(&inputs.args);
+    let offline_mode = parsed.offline || is_truthy_env_flag(inputs.io.env("PI_OFFLINE").as_deref());
+    parsed.offline = offline_mode;
+    if offline_mode {
+        inputs.io.set_env("PI_OFFLINE", "1");
+        inputs.io.set_env("PI_SKIP_VERSION_CHECK", "1");
+    }
+
+    if let Some(outcome) = package_manager_cli::handle_package_command(
+        &inputs.args,
+        inputs.package_handler,
+        inputs.package_output,
+        current_platform(),
+    ) {
+        return Err(stop(outcome.exit_code, outcome.drain_quirk));
+    }
+    if let Some(outcome) = package_manager_cli::handle_config_command(
+        &inputs.args,
+        inputs.package_output,
+        inputs.io.stdin_is_tty(),
+        inputs.io.stdout_is_tty(),
+    ) {
+        return Err(stop(outcome.exit_code, outcome.drain_quirk));
+    }
+
+    let mut parsed = crate::cli::args::parse_args(&inputs.args);
+    parsed.offline = offline_mode;
+    report_diagnostics(&parsed, inputs.io);
+    if parsed
+        .diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.level == DiagnosticLevel::Error)
+    {
+        return Err(stop(1, false));
+    }
+    if parsed.version {
+        inputs.io.write_stdout(VERSION);
+        return Err(stop(0, false));
+    }
+    if let Some(export_path) = parsed.export.as_ref()
+        && let Err(message) = run_export(export_path, parsed.messages.first())
+    {
+        inputs.io.write_stderr(&format!("Error: {message}"));
+        return Err(stop(1, false));
+    }
+    if parsed.export.is_some() {
+        return Err(stop(0, false));
+    }
+    Ok(parsed)
+}
+
+async fn prepare_session(
+    inputs: &BootstrapInputs<'_>,
+    parsed: Args,
+) -> BootstrapStep<PreparedSession> {
+    let app_mode = resolve_app_mode(&parsed, inputs.io.stdin_is_tty(), inputs.io.stdout_is_tty());
+    let plain_metadata = is_plain_runtime_metadata_command(&parsed);
+    let should_take_over_stdout = !app_mode.is_interactive() && !plain_metadata && !parsed.help;
+    if should_take_over_stdout && let Err(err) = output_guard::take_over_stdout() {
+        return Err(fail(inputs.io, false, &format!("Error: {err}")));
+    }
+    if app_mode.is_rpc() && !parsed.file_args.is_empty() {
+        return Err(fail(
+            inputs.io,
+            should_take_over_stdout,
+            "Error: @file arguments are not supported in RPC mode",
+        ));
+    }
+    let flag_error = validate_fork_flags(&parsed)
+        .err()
+        .or_else(|| validate_session_id_flags(&parsed).err());
+    if let Some(err) = flag_error {
+        return Err(fail(
+            inputs.io,
+            should_take_over_stdout,
+            &format!("Error: {}", err.message),
+        ));
+    }
+
+    let cwd = inputs.io.cwd().to_string_lossy().into_owned();
+    let migrations = migrations::run_migrations(Path::new(&cwd));
+    let agent_dir = resolve_agent_dir(inputs.io);
+    let session_dir = resolve_session_dir(&parsed, inputs.io);
+    let mut session_manager =
+        build_session_manager(&parsed, &cwd, session_dir.as_deref(), app_mode)
+            .await
+            .map_err(|message| {
+                fail(
+                    inputs.io,
+                    should_take_over_stdout,
+                    &format!("Error: {message}"),
+                )
+            })?;
+
+    if let Some(name) = parsed.name.as_ref() {
+        let trimmed = name.trim();
+        if trimmed.is_empty() {
+            return Err(fail(
+                inputs.io,
+                should_take_over_stdout,
+                "Error: --name requires a non-empty value",
+            ));
+        }
+        session_manager
+            .append_session_info(trimmed)
+            .map_err(|err| fail(inputs.io, should_take_over_stdout, &format!("Error: {err}")))?;
+    }
+
+    Ok(PreparedSession {
+        parsed,
+        app_mode,
+        should_take_over_stdout,
+        cwd,
+        migrations,
+        agent_dir,
+        session_manager,
+    })
+}
+
+async fn create_runtime(
+    inputs: &BootstrapInputs<'_>,
+    prepared: PreparedSession,
+) -> BootstrapStep<(BootstrapState, RuntimeHandle)> {
+    let PreparedSession {
+        parsed,
+        app_mode,
+        should_take_over_stdout,
+        cwd,
+        migrations,
+        agent_dir,
+        session_manager,
+    } = prepared;
+    let handle = inputs
+        .factory
+        .create(RuntimeFactoryOptions {
+            cwd: session_manager.get_cwd().to_owned(),
+            agent_dir,
+            session_manager,
+            parsed: parsed.clone(),
+        })
+        .await
+        .map_err(|message| {
+            fail(
+                inputs.io,
+                should_take_over_stdout,
+                &format!("Error: {message}"),
+            )
+        })?;
+
+    let diagnostics = handle.runtime.diagnostics();
+    let has_error = diagnostics.iter().any(|diagnostic| {
+        diagnostic.kind
+            == crate::core::agent_session_services::AgentSessionRuntimeDiagnosticKind::Error
+    });
+    let has_extension_load_error = diagnostics.iter().any(|diagnostic| {
+        diagnostic.kind
+            == crate::core::agent_session_services::AgentSessionRuntimeDiagnosticKind::Error
+            && diagnostic.message.contains("Failed to load extension")
+    });
+    for diagnostic in &diagnostics {
+        let label = match diagnostic.kind {
+            crate::core::agent_session_services::AgentSessionRuntimeDiagnosticKind::Info => "Info",
+            crate::core::agent_session_services::AgentSessionRuntimeDiagnosticKind::Warning => {
+                "Warning"
+            }
+            crate::core::agent_session_services::AgentSessionRuntimeDiagnosticKind::Error => {
+                "Error"
+            }
+        };
+        inputs
+            .io
+            .write_stderr(&format!("{label}: {}", diagnostic.message));
+    }
+    if has_error {
+        if has_extension_load_error {
+            inputs
+                .io
+                .write_stderr("Hint: Start without extensions using \"pi -ne\".");
+        }
+        if should_take_over_stdout {
+            output_guard::restore_stdout();
+        }
+        return Err(stop(1, false));
+    }
+
+    Ok((
+        BootstrapState {
+            parsed,
+            app_mode,
+            should_take_over_stdout,
+            cwd,
+            migrations,
+        },
+        handle,
+    ))
+}
+
+async fn handle_runtime_metadata(
+    io: &dyn BootstrapIo,
+    state: &BootstrapState,
+    handle: &RuntimeHandle,
+) -> Option<BootstrapOutcome> {
+    if state.parsed.help {
+        let extension_flags: Vec<crate::cli::help::ExtensionFlagHelp> =
+            collect_extension_flags(&handle.runtime);
+        let text = crate::cli::help::format_help(
+            Some(&extension_flags),
+            crate::cli::help::HelpStyle { styled: false },
+        );
+        io.write_stdout(&text);
+        if state.should_take_over_stdout {
+            output_guard::restore_stdout();
+        }
+        return Some(exit(0, false));
+    }
+    if matches!(state.parsed.list_models, ListModels::None) {
+        return None;
+    }
+    if state.should_take_over_stdout {
+        output_guard::restore_stdout();
+    }
+    let pattern = match &state.parsed.list_models {
+        ListModels::Search(search) => Some(search.to_lowercase()),
+        ListModels::All | ListModels::None => None,
+    };
+    let model_runtime = handle.runtime.session().model_runtime_handle();
+    if let Some(model_runtime) = model_runtime
+        && let Ok(models) = model_runtime.get_available(None).await
+    {
+        let mut rows: Vec<(String, String, String)> = Vec::new();
+        for model in &models {
+            if let Some(search) = &pattern
+                && !model.provider.to_lowercase().contains(search)
+                && !model.id.to_lowercase().contains(search)
+            {
+                continue;
+            }
+            rows.push((model.provider.clone(), model.id.clone(), model.name.clone()));
+        }
+        rows.sort_by(|left, right| left.0.cmp(&right.0).then(left.1.cmp(&right.1)));
+        for (provider, id, name) in &rows {
+            io.write_stdout(&format!("{provider}/{id} {name}"));
+        }
+        if let Some(message) = model_runtime.get_error() {
+            io.write_stderr(&format!("Warning: {message}"));
+        }
+    }
+    Some(exit(0, false))
+}
+
+async fn finish_bootstrap(
+    io: &dyn BootstrapIo,
+    mut state: BootstrapState,
+    handle: RuntimeHandle,
+) -> BootstrapOutcome {
+    let stdin_content = if state.app_mode.is_rpc() {
+        None
+    } else {
+        match io.read_piped_stdin().await {
+            Ok(content) => content,
+            Err(err) => {
+                return fail(
+                    io,
+                    state.should_take_over_stdout,
+                    &format!("Error: failed to read stdin: {err}"),
+                )
+                .into_outcome();
+            }
+        }
+    };
+    if stdin_content.is_some() && state.app_mode.is_interactive() {
+        state.app_mode = AppMode::Print;
+    }
+    let (initial_message, initial_images, remaining_messages) = match prepare_initial_message(
+        &mut state.parsed,
+        stdin_content.as_deref(),
+        &handle.runtime,
+        &state.cwd,
+    )
+    .await
+    {
+        Ok(prepared) => prepared,
+        Err(err) => {
+            return fail(io, state.should_take_over_stdout, &format!("Error: {err}"))
+                .into_outcome();
+        }
+    };
+
+    if !state.app_mode.is_interactive() {
+        let session = handle.runtime.session();
+        if session.model().provider == "unknown" {
+            return fail(
+                io,
+                state.should_take_over_stdout,
+                &crate::core::agent_session_services::format_no_models_available_message(),
+            )
+            .into_outcome();
+        }
+    }
+    if is_truthy_env_flag(io.env("PI_STARTUP_BENCHMARK").as_deref())
+        && !state.app_mode.is_interactive()
+    {
+        return fail(
+            io,
+            state.should_take_over_stdout,
+            "Error: PI_STARTUP_BENCHMARK only supports interactive mode",
+        )
+        .into_outcome();
+    }
+
+    BootstrapOutcome::Dispatch(Dispatched {
+        mode: state.app_mode,
+        handle,
+        initial_message,
+        initial_images,
+        remaining_messages,
+        migrations: state.migrations,
+    })
+}
+
+/// Report parse diagnostics to stderr (no exit decision here).
+fn report_diagnostics(parsed: &Args, io: &dyn BootstrapIo) {
+    for d in &parsed.diagnostics {
+        let label = match d.level {
+            DiagnosticLevel::Error => "Error",
+            DiagnosticLevel::Warning => "Warning",
+        };
+        io.write_stderr(&format!("{label}: {}", d.message));
+    }
+}
+
+/// Resolve the agent dir from process env (`PI_CODING_AGENT_DIR`) or home.
+///
+/// Reads the real process environment via [`crate::core::config::get_agent_dir`]
+/// so the path matches what the settings/session managers resolve
+/// independently. Tests that need a specific agent dir set the env var
+/// before invoking the bootstrap.
+fn resolve_agent_dir(_io: &dyn BootstrapIo) -> String {
+    crate::core::config::get_agent_dir()
+        .to_string_lossy()
+        .into_owned()
+}
+
+/// Resolve the session directory from `--session-dir`, env, or settings.
+fn resolve_session_dir(parsed: &Args, io: &dyn BootstrapIo) -> Option<String> {
+    if let Some(dir) = parsed.session_dir.as_ref() {
+        let normalized =
+            crate::core::config::normalize_path(dir, crate::core::config::PathInputOptions::new());
+        return Some(normalized.to_string_lossy().into_owned());
+    }
+    if let Some(env_dir) = io.env(ENV_SESSION_DIR) {
+        return Some(expand_tilde_path(&env_dir).to_string_lossy().into_owned());
+    }
+    None
+}
+
+/// Build the [`SessionManager`] using the same branching as
+/// `createSessionManager` (`main.ts:263-354`).
+///
+/// The interactive `--resume`/global-search paths require UI selectors owned
+/// by a sibling slice; for now those paths fall back to an in-memory manager
+/// with the requested id so the runtime still builds. The integrator wires the
+/// real selector when the TUI lands.
+async fn build_session_manager(
+    parsed: &Args,
+    cwd: &str,
+    session_dir: Option<&str>,
+    app_mode: AppMode,
+) -> Result<SessionManager, String> {
+    let id_opt = parsed.session_id.as_deref();
+
+    if parsed.no_session || parsed.help || !matches!(parsed.list_models, ListModels::None) {
+        return SessionManager::in_memory(Some(cwd), id_opt.map(sessions_id_opt))
+            .map_err(|e| e.to_string());
+    }
+
+    if let Some(fork_arg) = parsed.fork.as_deref() {
+        if let Some(id) = id_opt
+            && find_local_session_by_exact_id(id, cwd, session_dir)
+                .await
+                .is_some()
+        {
+            return Err(format!("Session already exists with id '{id}'"));
+        }
+        let resolved = resolve_session_path(fork_arg, cwd, session_dir).await;
+        let path = match resolved {
+            ResolvedSession::Path(path) => path,
+            ResolvedSession::NotFound(arg) => {
+                return Err(format!("No session found matching '{arg}'"));
+            }
+        };
+        return SessionManager::fork_from(&path, cwd, session_dir, id_opt.map(sessions_id_opt))
+            .map_err(|e| e.to_string());
+    }
+
+    if let Some(session_arg) = parsed.session.as_deref() {
+        let resolved = resolve_session_path(session_arg, cwd, session_dir).await;
+        let path = match resolved {
+            ResolvedSession::Path(path) => path,
+            ResolvedSession::NotFound(arg) => {
+                return Err(format!("No session found matching '{arg}'"));
+            }
+        };
+        return SessionManager::open(&path, session_dir, None).map_err(|e| e.to_string());
+    }
+
+    if parsed.resume {
+        let _ = app_mode;
+        return SessionManager::continue_recent(cwd, session_dir).map_err(|e| e.to_string());
+    }
+
+    if parsed.r#continue {
+        return SessionManager::continue_recent(cwd, session_dir).map_err(|e| e.to_string());
+    }
+
+    if let Some(id) = id_opt
+        && let Some(path) = find_local_session_by_exact_id(id, cwd, session_dir).await
+    {
+        return SessionManager::open(&path, session_dir, None).map_err(|e| e.to_string());
+    }
+
+    SessionManager::create(cwd, session_dir, id_opt.map(sessions_id_opt)).map_err(|e| e.to_string())
+}
+
+fn sessions_id_opt(id: &str) -> crate::core::sessions::NewSessionOptions {
+    crate::core::sessions::NewSessionOptions {
+        id: Some(id.to_owned()),
+        parent_session: None,
+    }
+}
+
+/// Result of resolving a session argument to a file path.
+#[derive(Clone, Debug)]
+enum ResolvedSession {
+    Path(String),
+    NotFound(String),
+}
+
+/// Resolve a session argument to a file path.
+///
+/// Path-like arguments retain explicit filesystem semantics. Bare arguments
+/// must identify an existing session in the current project.
+async fn resolve_session_path(arg: &str, cwd: &str, session_dir: Option<&str>) -> ResolvedSession {
+    if arg.contains('/') || arg.contains('\\') || has_jsonl_extension(arg) {
+        let resolved = crate::core::config::resolve_path_with(
+            arg,
+            Path::new(cwd),
+            crate::core::config::PathInputOptions::new(),
+        );
+        return ResolvedSession::Path(resolved.to_string_lossy().into_owned());
+    }
+    match find_local_session_by_exact_id(arg, cwd, session_dir).await {
+        Some(path) => ResolvedSession::Path(path),
+        None => ResolvedSession::NotFound(arg.to_owned()),
+    }
+}
+
+fn has_jsonl_extension(path: &str) -> bool {
+    path.as_bytes()
+        .get(path.len().saturating_sub(6)..)
+        .is_some_and(|extension| extension.eq_ignore_ascii_case(b".jsonl"))
+}
+
+/// Match a session ID exactly in the current project.
+///
+/// `list_sessions_for_cwd` is async, so this helper is async too.
+async fn find_local_session_by_exact_id(
+    session_id: &str,
+    cwd: &str,
+    session_dir: Option<&str>,
+) -> Option<String> {
+    find_local_session_by_exact_id_in_agent_dir(
+        session_id,
+        cwd,
+        session_dir,
+        &crate::core::config::get_agent_dir(),
+    )
+    .await
+}
+
+async fn find_local_session_by_exact_id_in_agent_dir(
+    session_id: &str,
+    cwd: &str,
+    session_dir: Option<&str>,
+    agent_dir: &Path,
+) -> Option<String> {
+    let default_dir = crate::core::sessions::default_session_dir_path(cwd, agent_dir);
+    let session_dir = session_dir.map_or_else(
+        || PathBuf::from(&default_dir),
+        |dir| {
+            crate::core::config::normalize_path(dir, crate::core::config::PathInputOptions::new())
+        },
+    );
+    let filter_cwd = session_dir != Path::new(&default_dir);
+    let sessions =
+        crate::core::sessions::list_sessions_for_cwd(cwd, &session_dir, filter_cwd, None).await;
+    sessions
+        .into_iter()
+        .find(|session| session.id.as_deref() == Some(session_id))
+        .map(|session| session.path)
+}
+
+/// Run `--export` via the shared export engine.
+fn run_export(input_path: &str, output_path: Option<&String>) -> Result<(), String> {
+    let result = crate::core::export_html::export_from_file(
+        input_path,
+        crate::core::export_html::ExportOptions {
+            output_path: output_path.map(PathBuf::from),
+            ..Default::default()
+        },
+    )
+    .map_err(|e| e.to_string())?;
+    ProductOutput::writeln(&format!("Exported to: {result}"));
+    Ok(())
+}
+
+/// Collect extension CLI flag metadata from the runtime's resource loader.
+///
+/// Returns an empty list until the resource loader exposes its flag map; the
+/// `--help` block still renders the canonical options.
+fn collect_extension_flags(
+    runtime: &std::sync::Arc<AgentSessionRuntime>,
+) -> Vec<crate::cli::help::ExtensionFlagHelp> {
+    let session = runtime.session();
+    let Some(host_runner) = session.host_extension_runner() else {
+        return Vec::new();
+    };
+    let registry = host_runner.registry();
+    registry
+        .flags()
+        .iter()
+        .map(|flag| {
+            let extension_path = match flag.extension_path.as_deref() {
+                Some(path) if !path.is_empty() => path.to_owned(),
+                _ => "<extension>".to_owned(),
+            };
+            crate::cli::help::ExtensionFlagHelp {
+                name: flag.name.clone(),
+                description: flag.description.clone(),
+                takes_value: matches!(flag.kind, pi_ext::adapters::FlagKind::String),
+                extension_path,
+            }
+        })
+        .collect()
+}
+
+/// Prepare the initial message and split remaining CLI messages.
+///
+/// Expands `@file` arguments through the shared image pipeline using the
+/// runtime's `images.autoResize` setting, then merges with stdin and the
+/// first CLI message in the same join order as the TypeScript reference.
+async fn prepare_initial_message(
+    parsed: &mut Args,
+    stdin_content: Option<&str>,
+    runtime: &std::sync::Arc<AgentSessionRuntime>,
+    cwd: &str,
+) -> Result<(Option<String>, Vec<pi_ai::ImageContent>, Vec<String>), String> {
+    if parsed.file_args.is_empty() {
+        let prompt = crate::modes::print::build_initial_message(
+            &mut parsed.messages,
+            stdin_content,
+            None,
+            Vec::new(),
+        );
+        return Ok((
+            prompt.initial_message,
+            prompt.initial_images,
+            parsed.messages.clone(),
+        ));
+    }
+    let session = runtime.session();
+    let auto_resize = session.lock_settings().get_image_auto_resize();
+    let files = crate::modes::print::process_file_arguments(
+        &parsed.file_args,
+        cwd,
+        crate::modes::print::ProcessFileOptions {
+            auto_resize_images: auto_resize,
+        },
+    )
+    .await
+    .map_err(|err| err.to_string())?;
+    let prompt = crate::modes::print::build_initial_message(
+        &mut parsed.messages,
+        stdin_content,
+        Some(&files.text),
+        files.images,
+    );
+    Ok((
+        prompt.initial_message,
+        prompt.initial_images,
+        parsed.messages.clone(),
+    ))
+}
+
+/// Detect the current dispatch platform.
+fn current_platform() -> DispatchPlatform {
+    if cfg!(target_os = "windows") {
+        DispatchPlatform::Windows
+    } else {
+        DispatchPlatform::Unix
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+    use std::sync::{Mutex, MutexGuard};
+
+    fn lock_recover<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
+        match mutex.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        }
+    }
+
+    fn validation_error(
+        result: Result<(), FlagValidationError>,
+        context: &str,
+    ) -> Result<FlagValidationError, String> {
+        match result {
+            Ok(()) => Err(format!("{context}: validation unexpectedly succeeded")),
+            Err(error) => Ok(error),
+        }
+    }
+
+    fn assert_exit_code(outcome: BootstrapOutcome, expected: u8) -> Result<(), String> {
+        match outcome {
+            BootstrapOutcome::Exit { code, .. } => {
+                assert_eq!(code, expected);
+                Ok(())
+            }
+            BootstrapOutcome::Dispatch(dispatched) => Err(format!(
+                "expected Exit with code {expected}, got Dispatch({:?})",
+                dispatched.mode
+            )),
+        }
+    }
+
+    fn args_vec(tokens: &[&str]) -> Vec<String> {
+        tokens.iter().map(|s| (*s).to_owned()).collect()
+    }
+
+    fn write_session_header(
+        path: &Path,
+        id: &str,
+        cwd: &str,
+    ) -> Result<(), Box<dyn std::error::Error>> {
+        let header = crate::core::sessions::SessionHeader::new(
+            id.to_owned(),
+            "2026-01-01T00:00:00.000Z".to_owned(),
+            cwd.to_owned(),
+            None,
+        );
+        std::fs::write(path, format!("{}\n", serde_json::to_string(&header)?))?;
+        Ok(())
+    }
+
+    /// In-memory I/O surface for tests.
+    #[derive(Default)]
+    struct FakeIo {
+        env: Mutex<std::collections::HashMap<String, String>>,
+        stdout: Mutex<Vec<String>>,
+        stderr: Mutex<Vec<String>>,
+        stdin_payload: Option<String>,
+        stdin_is_tty: bool,
+        stdout_is_tty: bool,
+        cwd: PathBuf,
+    }
+
+    impl BootstrapIo for Arc<FakeIo> {
+        fn env(&self, key: &str) -> Option<String> {
+            lock_recover(&self.env).get(key).cloned()
+        }
+        fn set_env(&self, key: &str, value: &str) {
+            lock_recover(&self.env).insert(key.to_owned(), value.to_owned());
+        }
+        fn cwd(&self) -> PathBuf {
+            self.cwd.clone()
+        }
+        fn stdin_is_tty(&self) -> bool {
+            self.stdin_is_tty
+        }
+        fn stdout_is_tty(&self) -> bool {
+            self.stdout_is_tty
+        }
+        fn read_piped_stdin<'a>(
+            &'a self,
+        ) -> Pin<Box<dyn Future<Output = io::Result<Option<String>>> + Send + 'a>> {
+            Box::pin(async move { Ok(self.stdin_payload.clone()) })
+        }
+        fn write_stdout(&self, line: &str) {
+            lock_recover(&self.stdout).push(line.to_owned());
+        }
+        fn write_stderr(&self, line: &str) {
+            lock_recover(&self.stderr).push(line.to_owned());
+        }
+    }
+
+    impl FakeIo {
+        fn new() -> Self {
+            let mut env = std::collections::HashMap::new();
+            env.insert(
+                "PI_CODING_AGENT_DIR".to_owned(),
+                std::env::temp_dir()
+                    .join("pi-bootstrap-test")
+                    .to_string_lossy()
+                    .into_owned(),
+            );
+            Self {
+                env: Mutex::new(env),
+                stdout: Mutex::new(Vec::new()),
+                stderr: Mutex::new(Vec::new()),
+                stdin_payload: None,
+                stdin_is_tty: true,
+                stdout_is_tty: true,
+                cwd: std::env::temp_dir(),
+            }
+        }
+
+        fn stdout_lines(&self) -> Vec<String> {
+            lock_recover(&self.stdout).clone()
+        }
+
+        fn stderr_lines(&self) -> Vec<String> {
+            lock_recover(&self.stderr).clone()
+        }
+    }
+
+    /// Fake runtime factory. Defaults to returning a fixed error so short-circuit
+    /// tests can assert factory failures; set `succeed = true` when a real
+    /// runtime handle is required (e.g. `PI_STARTUP_BENCHMARK` guard).
+    #[derive(Default)]
+    struct FakeFactory {
+        calls: Mutex<Vec<String>>,
+        supports_interactive: bool,
+        /// When true, build a lightweight runtime with a non-`unknown` model.
+        succeed: bool,
+    }
+
+    #[derive(Clone)]
+    struct StubProvider;
+
+    impl pi_ai::Provider for StubProvider {
+        fn stream(
+            &self,
+            _model: &pi_ai::Model,
+            _context: pi_ai::Context,
+            _options: pi_ai::StreamOptions,
+        ) -> futures::stream::BoxStream<
+            'static,
+            Result<pi_ai::AssistantMessageEvent, pi_ai::ProviderError>,
+        > {
+            Box::pin(futures::stream::empty())
+        }
+    }
+
+    fn fake_runtime_model() -> pi_ai::Model {
+        pi_ai::Model {
+            id: "m".to_owned(),
+            name: "m".to_owned(),
+            api: "test-api".to_owned(),
+            provider: "test-provider".to_owned(),
+            base_url: String::new(),
+            reasoning: false,
+            thinking_level_map: None,
+            input: vec![pi_ai::ModelInput::Text],
+            cost: pi_ai::ModelCost::default(),
+            context_window: 8_192,
+            max_tokens: 1_024,
+            headers: None,
+            compat: None,
+            extra: std::collections::BTreeMap::new(),
+        }
+    }
+
+    #[derive(Default)]
+    struct StubRuntimeFactory;
+
+    impl crate::core::agent_session_runtime::CreateAgentSessionRuntimeFactory for StubRuntimeFactory {
+        fn create(
+            &self,
+            _options: crate::core::agent_session_runtime::CreateAgentSessionRuntimeOptions,
+        ) -> BoxFuture<
+            '_,
+            Result<
+                crate::core::agent_session_runtime::CreateAgentSessionRuntimeResult,
+                crate::core::agent_session_runtime::AgentSessionRuntimeError,
+            >,
+        > {
+            Box::pin(async {
+                Err(
+                    crate::core::agent_session_runtime::AgentSessionRuntimeError::Factory(
+                        "stub runtime factory is not expected to create replacements".to_owned(),
+                    ),
+                )
+            })
+        }
+    }
+
+    impl RuntimeFactory for Arc<FakeFactory> {
+        fn create(
+            &self,
+            options: RuntimeFactoryOptions,
+        ) -> BoxFuture<'_, Result<RuntimeHandle, String>> {
+            lock_recover(&self.calls).push(format!(
+                "create:{}:{}",
+                options.cwd,
+                options.session_manager.get_session_id()
+            ));
+            let succeed = self.succeed;
+            Box::pin(async move {
+                if !succeed {
+                    return Err("__fake_factory_unavailable__".to_owned());
+                }
+                let config = crate::core::agent_session::AgentSessionConfig::test_config(
+                    Arc::new(StubProvider),
+                    fake_runtime_model(),
+                )
+                .map_err(|e| e.to_string())?;
+                let session = crate::core::agent_session::AgentSession::new(config)
+                    .map_err(|e| e.to_string())?;
+                let runtime = AgentSessionRuntime::new(
+                    session,
+                    crate::core::agent_session_runtime::AgentSessionRuntimeServices {
+                        cwd: PathBuf::from(options.cwd),
+                        agent_dir: PathBuf::from(options.agent_dir),
+                    },
+                    Arc::new(StubRuntimeFactory),
+                    Vec::new(),
+                    None,
+                );
+                Ok(RuntimeHandle {
+                    runtime: Arc::new(runtime),
+                })
+            })
+        }
+        fn supports_interactive(&self) -> bool {
+            self.supports_interactive
+        }
+    }
+
+    #[derive(Default, Clone)]
+    struct CapturedOutput {
+        inner: Arc<Mutex<CapturedInner>>,
+    }
+
+    #[derive(Default)]
+    struct CapturedInner {
+        status: Vec<String>,
+        status_dim: Vec<String>,
+        success: Vec<String>,
+        error: Vec<String>,
+    }
+
+    impl PackageOutput for CapturedOutput {
+        fn status(&self, line: &str) {
+            lock_recover(&self.inner).status.push(line.to_owned());
+        }
+        fn status_dim(&self, line: &str) {
+            lock_recover(&self.inner).status_dim.push(line.to_owned());
+        }
+        fn success(&self, line: &str) {
+            lock_recover(&self.inner).success.push(line.to_owned());
+        }
+        fn error(&self, line: &str) {
+            lock_recover(&self.inner).error.push(line.to_owned());
+        }
+    }
+
+    #[derive(Default, Clone)]
+    struct FakePackageHandler {
+        trusted: bool,
+        calls: Arc<Mutex<Vec<String>>>,
+    }
+
+    impl PackageHandler for FakePackageHandler {
+        fn install(&self, source: &str, local: bool) -> Result<(), String> {
+            lock_recover(&self.calls).push(format!("install:{source}:{local}"));
+            Ok(())
+        }
+        fn remove(&self, source: &str, local: bool) -> Result<bool, String> {
+            lock_recover(&self.calls).push(format!("remove:{source}:{local}"));
+            Ok(true)
+        }
+        fn list(&self) -> Result<Vec<package_manager_cli::ListedPackage>, String> {
+            lock_recover(&self.calls).push("list".to_owned());
+            Ok(Vec::new())
+        }
+        fn is_project_trusted(&self) -> bool {
+            self.trusted
+        }
+        fn refresh_models(&self) -> Result<(), String> {
+            Ok(())
+        }
+        fn update_extensions(&self, source: Option<&str>) -> Result<(), String> {
+            lock_recover(&self.calls).push(format!("ext:{source:?}"));
+            Ok(())
+        }
+        fn update_self(&self, force: bool) -> Result<bool, String> {
+            lock_recover(&self.calls).push(format!("self:{force}"));
+            Ok(false)
+        }
+    }
+
+    // ----- resolve_app_mode tests -----------------------------------------
+
+    #[test]
+    fn resolve_app_mode_rpc_forces_non_interactive() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--mode", "rpc"]));
+        assert_eq!(resolve_app_mode(&parsed, true, true), AppMode::Rpc);
+    }
+
+    #[test]
+    fn resolve_app_mode_json_forces_non_interactive() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--mode", "json"]));
+        assert_eq!(resolve_app_mode(&parsed, true, true), AppMode::Json);
+    }
+
+    #[test]
+    fn resolve_app_mode_text_with_dual_tty_is_interactive() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--mode", "text"]));
+        assert_eq!(resolve_app_mode(&parsed, true, true), AppMode::Interactive);
+    }
+
+    #[test]
+    fn resolve_app_mode_print_flag_demotes() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--print"]));
+        assert_eq!(resolve_app_mode(&parsed, true, true), AppMode::Print);
+    }
+
+    #[test]
+    fn resolve_app_mode_non_tty_stdin_demotes() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&[]));
+        assert_eq!(resolve_app_mode(&parsed, false, true), AppMode::Print);
+    }
+
+    #[test]
+    fn resolve_app_mode_non_tty_stdout_demotes() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&[]));
+        assert_eq!(resolve_app_mode(&parsed, true, false), AppMode::Print);
+    }
+
+    // ----- is_plain_runtime_metadata_command tests -----------------------
+
+    #[test]
+    fn plain_metadata_for_help_without_mode() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--help"]));
+        assert!(is_plain_runtime_metadata_command(&parsed));
+    }
+
+    #[test]
+    fn plain_metadata_for_list_models_without_mode() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--list-models"]));
+        assert!(is_plain_runtime_metadata_command(&parsed));
+    }
+
+    #[test]
+    fn plain_metadata_false_when_print_set() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--print", "--help"]));
+        assert!(!is_plain_runtime_metadata_command(&parsed));
+    }
+
+    #[test]
+    fn plain_metadata_false_when_mode_set() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--mode", "json", "--help"]));
+        assert!(!is_plain_runtime_metadata_command(&parsed));
+    }
+
+    // ----- validators ------------------------------------------------------
+
+    #[test]
+    fn fork_conflicts_with_session() -> Result<(), String> {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--fork", "abc", "--session", "x"]));
+        let err = validation_error(validate_fork_flags(&parsed), "fork with session")?;
+        assert!(
+            err.message
+                .contains("--fork cannot be combined with --session")
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn fork_conflicts_with_continue_and_resume() -> Result<(), String> {
+        let parsed =
+            crate::cli::args::parse_args(&args_vec(&["--fork", "abc", "--continue", "--resume"]));
+        let err = validation_error(
+            validate_fork_flags(&parsed),
+            "fork with continue and resume",
+        )?;
+        assert!(err.message.contains("--continue, --resume"));
+        Ok(())
+    }
+
+    #[test]
+    fn fork_alone_is_ok() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--fork", "abc"]));
+        assert!(validate_fork_flags(&parsed).is_ok());
+    }
+
+    #[test]
+    fn session_id_conflicts_with_continue() -> Result<(), String> {
+        let parsed =
+            crate::cli::args::parse_args(&args_vec(&["--session-id", "xyz", "--continue"]));
+        let err = validation_error(
+            validate_session_id_flags(&parsed),
+            "session id with continue",
+        )?;
+        assert!(
+            err.message
+                .contains("--session-id cannot be combined with --continue")
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn session_id_alone_is_ok() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--session-id", "xyz"]));
+        assert!(validate_session_id_flags(&parsed).is_ok());
+    }
+
+    #[test]
+    fn name_rejects_empty_value() -> Result<(), String> {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--name", ""]));
+        let err = validation_error(validate_name(&parsed), "empty name")?;
+        assert_eq!(err.message, "--name requires a non-empty value");
+        Ok(())
+    }
+
+    #[test]
+    fn name_rejects_whitespace_only_value() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--name", "   "]));
+        assert!(validate_name(&parsed).is_err());
+    }
+
+    #[test]
+    fn name_accepts_non_empty_value() {
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--name", "my session"]));
+        assert!(validate_name(&parsed).is_ok());
+    }
+
+    // ----- is_truthy_env_flag ---------------------------------------------
+
+    #[test]
+    fn truthy_env_flag_values() {
+        assert!(!is_truthy_env_flag(None));
+        assert!(is_truthy_env_flag(Some("1")));
+        assert!(is_truthy_env_flag(Some("true")));
+        assert!(is_truthy_env_flag(Some("TRUE")));
+        assert!(is_truthy_env_flag(Some("yes")));
+        assert!(!is_truthy_env_flag(Some("0")));
+        assert!(!is_truthy_env_flag(Some("false")));
+        assert!(!is_truthy_env_flag(Some("")));
+    }
+
+    // ----- bootstrap pipeline tests ---------------------------------------
+
+    #[tokio::test]
+    async fn default_session_lookup_uses_agent_project_directory()
+    -> Result<(), Box<dyn std::error::Error>> {
+        let root = tempfile::tempdir()?;
+        let cwd = root.path().join("project");
+        let agent_dir = root.path().join("agent");
+        std::fs::create_dir_all(&cwd)?;
+        let session_dir = crate::core::sessions::default_session_dir_path(
+            cwd.to_str().ok_or("cwd utf8")?,
+            &agent_dir,
+        );
+        std::fs::create_dir_all(&session_dir)?;
+        let session_file = Path::new(&session_dir).join("known.jsonl");
+        write_session_header(
+            &session_file,
+            "known-session",
+            cwd.to_str().ok_or("cwd utf8")?,
+        )?;
+
+        let found = find_local_session_by_exact_id_in_agent_dir(
+            "known-session",
+            cwd.to_str().ok_or("cwd utf8")?,
+            None,
+            &agent_dir,
+        )
+        .await;
+
+        assert_eq!(found.as_deref(), session_file.to_str());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn unknown_bare_session_id_is_rejected() -> Result<(), Box<dyn std::error::Error>> {
+        let root = tempfile::tempdir()?;
+        let cwd = root.path().join("project");
+        let sessions = root.path().join("sessions");
+        std::fs::create_dir_all(&cwd)?;
+        std::fs::create_dir_all(&sessions)?;
+        let parsed = crate::cli::args::parse_args(&args_vec(&["--session", "missing-session"]));
+
+        let Err(error) = build_session_manager(
+            &parsed,
+            cwd.to_str().ok_or("cwd utf8")?,
+            Some(sessions.to_str().ok_or("sessions utf8")?),
+            AppMode::Print,
+        )
+        .await
+        else {
+            return Err("unknown bare ID unexpectedly succeeded".into());
+        };
+
+        assert_eq!(error, "No session found matching 'missing-session'");
+        assert!(!cwd.join("missing-session").exists());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn explicit_missing_session_path_is_preserved() -> Result<(), Box<dyn std::error::Error>>
+    {
+        let root = tempfile::tempdir()?;
+        let cwd = root.path().join("project");
+        let sessions = root.path().join("sessions");
+        std::fs::create_dir_all(&cwd)?;
+        std::fs::create_dir_all(&sessions)?;
+        let explicit = cwd.join("new-session.jsonl");
+        let parsed = crate::cli::args::parse_args(&args_vec(&[
+            "--session",
+            explicit.to_str().ok_or("explicit utf8")?,
+        ]));
+
+        let manager = build_session_manager(
+            &parsed,
+            cwd.to_str().ok_or("cwd utf8")?,
+            Some(sessions.to_str().ok_or("sessions utf8")?),
+            AppMode::Print,
+        )
+        .await?;
+
+        assert_eq!(manager.get_session_file(), explicit.to_str());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn fork_rejects_existing_session_id() -> Result<(), Box<dyn std::error::Error>> {
+        let root = tempfile::tempdir()?;
+        let cwd = root.path().join("project");
+        let sessions = root.path().join("sessions");
+        std::fs::create_dir_all(&cwd)?;
+        std::fs::create_dir_all(&sessions)?;
+        let cwd_str = cwd.to_str().ok_or("cwd utf8")?;
+        let existing = sessions.join("existing.jsonl");
+        let source = sessions.join("source.jsonl");
+        write_session_header(&existing, "duplicate-id", cwd_str)?;
+        write_session_header(&source, "source-id", cwd_str)?;
+        let parsed = crate::cli::args::parse_args(&args_vec(&[
+            "--fork",
+            source.to_str().ok_or("source utf8")?,
+            "--session-id",
+            "duplicate-id",
+        ]));
+
+        let Err(error) = build_session_manager(
+            &parsed,
+            cwd_str,
+            Some(sessions.to_str().ok_or("sessions utf8")?),
+            AppMode::Print,
+        )
+        .await
+        else {
+            return Err("fork target collision unexpectedly succeeded".into());
+        };
+
+        assert_eq!(error, "Session already exists with id 'duplicate-id'");
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_version_short_circuit() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--version"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 0)?;
+        let stdout = io.stdout_lines();
+        assert!(!stdout.is_empty());
+        assert!(stdout[0].chars().any(|c| c.is_ascii_digit()));
+        assert!(lock_recover(&factory.calls).is_empty());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_help_short_circuit_before_factory() -> Result<(), String> {
+        // --help should NOT reach the factory (parsed but no runtime needed
+        // when help is the plain-metadata short-circuit at exit-time). Note:
+        // the bootstrap currently builds the runtime THEN renders help with
+        // extension flags, matching main.ts. So the factory IS called. This
+        // test documents the behavior.
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--help"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        // The fake factory returns an error, so the bootstrap exits 1 with
+        // the error message. The point of this test is to document that the
+        // factory is reached when help is requested (so extension flags can
+        // be discovered).
+        assert_exit_code(outcome, 1)?;
+        assert!(!lock_recover(&factory.calls).is_empty());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_parse_error_exits_one() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--name"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 1)?;
+        let stderr = io.stderr_lines();
+        assert!(stderr.iter().any(|s| s.contains("--name requires a value")));
+        assert!(lock_recover(&factory.calls).is_empty());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_thinking_warning_does_not_exit() -> Result<(), String> {
+        // A warning diagnostic should not short-circuit; the bootstrap should
+        // continue past the parse-diagnostics step. The fake factory then
+        // returns an error, so we still exit 1 — but the warning must appear
+        // on stderr first.
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--thinking", "bogus"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 1)?;
+        let stderr = io.stderr_lines();
+        assert!(stderr.iter().any(|s| s.contains("Invalid thinking level")));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_rpc_with_file_arg_exits_one() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--mode", "rpc", "@file.txt"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 1)?;
+        let stderr = io.stderr_lines();
+        assert!(
+            stderr
+                .iter()
+                .any(|s| s.contains("@file arguments are not supported in RPC mode"))
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_missing_file_arg_exits_one() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory {
+            succeed: true,
+            ..FakeFactory::default()
+        });
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--print", "--no-session", "@missing-file-arg.txt"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+
+        assert_exit_code(outcome, 1)?;
+        assert!(
+            io.stderr_lines()
+                .iter()
+                .any(|line| line.contains("missing-file-arg.txt"))
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_fork_conflict_exits_one() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--fork", "abc", "--continue"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 1)?;
+        let stderr = io.stderr_lines();
+        assert!(
+            stderr
+                .iter()
+                .any(|s| s.contains("--fork cannot be combined"))
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_package_command_short_circuits() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["list"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 0)?;
+        assert!(lock_recover(&factory.calls).is_empty());
+        assert!(!lock_recover(&pkg.calls).is_empty());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_sets_offline_env() {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let _ = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--version", "--offline"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        let env = lock_recover(&io.env);
+        assert_eq!(env.get("PI_OFFLINE").map(String::as_str), Some("1"));
+        assert_eq!(
+            env.get("PI_SKIP_VERSION_CHECK").map(String::as_str),
+            Some("1")
+        );
+    }
+
+    #[tokio::test]
+    async fn bootstrap_export_missing_file_exits_one() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--export", "/nonexistent/path/missing.jsonl"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 1)?;
+        let stderr = io.stderr_lines();
+        assert!(stderr.iter().any(|s| s.contains("Error: File not found")));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_unknown_short_flag_is_parse_error() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["-Z"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 1)?;
+        let stderr = io.stderr_lines();
+        assert!(stderr.iter().any(|s| s.contains("Unknown option: -Z")));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_factory_error_surfaces_verbatim() -> Result<(), String> {
+        let io = Arc::new(FakeIo::new());
+        let factory = Arc::new(FakeFactory::default());
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--no-session", "hello"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 1)?;
+        let stderr = io.stderr_lines();
+        assert!(
+            stderr
+                .iter()
+                .any(|s| s.contains("__fake_factory_unavailable__"))
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn bootstrap_pi_startup_benchmark_guard() -> Result<(), String> {
+        // PI_STARTUP_BENCHMARK is set, mode is print (because stdin not TTY
+        // would also demote). Use --print to force print mode cleanly.
+        let io_state = FakeIo::new();
+        lock_recover(&io_state.env).insert("PI_STARTUP_BENCHMARK".to_owned(), "1".to_owned());
+        let io = Arc::new(io_state);
+        let factory = Arc::new(FakeFactory {
+            succeed: true,
+            ..FakeFactory::default()
+        });
+        let pkg_out = CapturedOutput::default();
+        let pkg = FakePackageHandler::default();
+        let outcome = run_bootstrap(BootstrapInputs {
+            args: args_vec(&["--print", "hello"]),
+            io: &io,
+            factory: &factory,
+            package_handler: &pkg,
+            package_output: &pkg_out,
+        })
+        .await;
+        assert_exit_code(outcome, 1)?;
+        let stderr = io.stderr_lines();
+        assert!(
+            stderr
+                .iter()
+                .any(|s| s.contains("PI_STARTUP_BENCHMARK only supports interactive mode"))
+        );
+        Ok(())
+    }
+
+    /// Flag snapshot the fake host serves for `extensions.load`.
+    fn fake_flag_snapshot() -> serde_json::Value {
+        serde_json::json!({
+            "flags": [
+                {
+                    "name": "verbose-log",
+                    "type": "boolean",
+                    "description": "Enable verbose logging",
+                    "extensionPath": "/plugins/logger"
+                },
+                {
+                    "name": "api-url",
+                    "type": "string",
+                    "description": "Custom API URL",
+                    "extensionPath": "/plugins/api"
+                },
+                {
+                    "name": "fallback-flag",
+                    "type": "boolean",
+                    "extensionPath": "/plugins/fallback"
+                },
+                {
+                    "name": "legacy-flag",
+                    "type": "string"
+                }
+            ]
+        })
+    }
+
+    /// Build a test runtime, optionally binding a host extension runner.
+    /// Propagates typed construction errors instead of panicking.
+    fn build_test_runtime(
+        runner: Option<Arc<crate::core::extension_host::HostExtensionRunner>>,
+    ) -> Result<Arc<AgentSessionRuntime>, String> {
+        let cwd = std::env::current_dir().map_err(|e| format!("current_dir: {e}"))?;
+        let mut config = crate::core::agent_session::AgentSessionConfig::test_config(
+            Arc::new(StubProvider),
+            fake_runtime_model(),
+        )
+        .map_err(|e| format!("test_config: {e}"))?;
+        config.host_extension_runner = runner;
+        let session = crate::core::agent_session::AgentSession::new(config)
+            .map_err(|e| format!("AgentSession::new: {e}"))?;
+        Ok(Arc::new(AgentSessionRuntime::new(
+            session,
+            crate::core::agent_session_runtime::AgentSessionRuntimeServices {
+                cwd: cwd.clone(),
+                agent_dir: cwd,
+            },
+            Arc::new(StubRuntimeFactory),
+            Vec::new(),
+            None,
+        )))
+    }
+
+    /// Answer one fake-host request line, propagating encode/serialization
+    /// errors instead of unwrapping.
+    async fn serve_fake_host_line(
+        line: &str,
+        snapshot: &serde_json::Value,
+        writer: &mut tokio::io::DuplexStream,
+    ) -> Result<(), String> {
+        use tokio::io::AsyncWriteExt;
+        let req =
+            pi_ext::protocol::decode_frame_str(line).map_err(|e| format!("decode request: {e}"))?;
+        let payload = if req.method == "hello" {
+            serde_json::to_value(pi_ext::protocol::HelloAck::local())
+                .map_err(|e| format!("encode hello: {e}"))?
+        } else if req.method == "extensions.load" {
+            snapshot.clone()
+        } else {
+            serde_json::Value::Object(serde_json::Map::new())
+        };
+        let resp = pi_ext::protocol::Frame {
+            id: req.id,
+            kind: pi_ext::protocol::FrameKind::Res,
+            method: req.method,
+            payload,
+        };
+        let bytes =
+            pi_ext::protocol::encode_frame(&resp).map_err(|e| format!("encode frame: {e}"))?;
+        writer
+            .write_all(&bytes)
+            .await
+            .map_err(|e| format!("write frame: {e}"))?;
+        writer
+            .flush()
+            .await
+            .map_err(|e| format!("flush frame: {e}"))?;
+        Ok(())
+    }
+
+    /// Spawn a fake extension host over a duplex pair. Encode/serialization
+    /// failures are recorded into `errors` (never silently swallowed) and the
+    /// task exits so the client observes EOF.
+    fn spawn_fake_extension_host(
+        host_from_client: tokio::io::DuplexStream,
+        host_to_client: tokio::io::DuplexStream,
+        snapshot: serde_json::Value,
+        errors: Arc<Mutex<Vec<String>>>,
+    ) -> tokio::task::JoinHandle<()> {
+        use tokio::io::AsyncBufReadExt;
+        tokio::spawn(async move {
+            let mut reader = tokio::io::BufReader::new(host_from_client);
+            let mut writer = host_to_client;
+            let mut line = String::new();
+            loop {
+                line.clear();
+                match reader.read_line(&mut line).await {
+                    Ok(0) | Err(_) => break,
+                    Ok(_) => {}
+                }
+                if let Err(message) = serve_fake_host_line(&line, &snapshot, &mut writer).await {
+                    lock_recover(&errors).push(message);
+                    break;
+                }
+            }
+        })
+    }
+
+    fn assert_extension_flag(
+        flag: &crate::cli::help::ExtensionFlagHelp,
+        name: &str,
+        takes_value: bool,
+        description: Option<&str>,
+        extension_path: &str,
+    ) {
+        assert_eq!(flag.name, name);
+        assert_eq!(flag.takes_value, takes_value);
+        assert_eq!(flag.description.as_deref(), description);
+        assert_eq!(flag.extension_path, extension_path);
+    }
+
+    #[tokio::test]
+    async fn test_collect_extension_flags() -> Result<(), String> {
+        // 1. No runner → empty flag list.
+        let runtime = build_test_runtime(None)?;
+        assert!(
+            collect_extension_flags(&runtime).is_empty(),
+            "expected empty flags when no runner is present"
+        );
+
+        // 2. Wire a fake host serving boolean/string flags with varied metadata.
+        let (client_to_host, host_from_client) = tokio::io::duplex(64 * 1024);
+        let (host_to_client, client_from_host) = tokio::io::duplex(64 * 1024);
+        let (client_err, _host_err) = tokio::io::duplex(4096);
+        let client = Arc::new(pi_ext::client::HostClient::connect_boxed(
+            Box::new(client_to_host),
+            Box::new(client_from_host),
+            Box::new(client_err),
+            None,
+        ));
+        let host_errors: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
+        let _host = spawn_fake_extension_host(
+            host_from_client,
+            host_to_client,
+            fake_flag_snapshot(),
+            Arc::clone(&host_errors),
+        );
+
+        let runner = crate::core::extension_host::HostExtensionRunner::connect(client, vec![])
+            .await
+            .map_err(|e| format!("HostExtensionRunner::connect: {e}"))?;
+
+        let runtime_with_runner = build_test_runtime(Some(runner))?;
+        let flags = collect_extension_flags(&runtime_with_runner);
+        assert_eq!(flags.len(), 4, "expected four registered flags");
+
+        // Order, description, takes_value, and extension_path mapping.
+        assert_extension_flag(
+            &flags[0],
+            "verbose-log",
+            false,
+            Some("Enable verbose logging"),
+            "/plugins/logger",
+        );
+        assert_extension_flag(
+            &flags[1],
+            "api-url",
+            true,
+            Some("Custom API URL"),
+            "/plugins/api",
+        );
+        // No description → falls back to extension_path in help rendering.
+        assert_extension_flag(&flags[2], "fallback-flag", false, None, "/plugins/fallback");
+        // No description and no extensionPath → maps to "<extension>".
+        assert_extension_flag(&flags[3], "legacy-flag", true, None, "<extension>");
+
+        // Help rendering surfaces the description-fallback source.
+        let help_text = crate::cli::help::format_help(
+            Some(&flags),
+            crate::cli::help::HelpStyle { styled: false },
+        );
+        assert!(
+            help_text.contains("Registered by /plugins/fallback"),
+            "help missing fallback-path registration line"
+        );
+        assert!(
+            help_text.contains("Registered by <extension>"),
+            "help missing generic-extension registration line"
+        );
+        // The fake host must not have silently hidden any encode/serialization failure.
+        assert!(
+            lock_recover(&host_errors).is_empty(),
+            "fake host reported errors: {:?}",
+            lock_recover(&host_errors).clone()
+        );
+        Ok(())
+    }
+}