harn_cli/commands/

demo.rs

//! `harn demo` — bundled, fully-offline scenarios that demonstrate the
//! Harn moat (persona supervision, replay determinism, provider
//! routing) without any API keys. See issue #1650.
//!
//! Each scenario ships with:
//!   - a `.harn` script (`assets/demo/<id>/scenario.harn`)
//!   - a JSONL `--llm-mock` tape (`assets/demo/<id>/tape.jsonl`)
//!   - optionally, sibling files (`.harn.prompt` templates, imported modules,
//!     fixtures) anywhere under `assets/demo/<id>/`
//!
//! The script and tape are `include_str!`'d here; sibling files are embedded by
//! `build.rs` (see `DEMO_SIBLING_FILES`). At run time `stage_scenario`
//! materializes the whole set into a tempdir and `run_scenario` executes there
//! hermetically, so `harn demo <id>` works from a static-linked install with no
//! repo checkout — and a multi-file scenario behaves exactly like a real
//! on-disk Harn project.

use std::collections::HashSet;
use std::fs;
use std::io::IsTerminal;
use std::path::{Path, PathBuf};
use std::time::{Instant, SystemTime, UNIX_EPOCH};

use unicode_width::UnicodeWidthStr;

use crate::cli::DemoArgs;
use crate::commands::run::{
    execute_run_with_sandbox_options, CliLlmMockMode, RunOutcome, RunProfileOptions,
    RunSandboxOptions,
};

// Generated by build.rs: `(<id>/<relative path>, contents)` for every demo
// sibling file (`.harn.prompt` templates, imported modules, fixtures) beyond
// the primary scenario.harn + tape.jsonl. Materialized into the run tempdir by
// `stage_scenario` so multi-file scenarios run fully offline.
include!(concat!(env!("OUT_DIR"), "/demo_assets_table.rs"));

/// Bundled scenarios shipped with the binary. Keep ordered by the
/// "first-touch impact" we want stranger users to see — the menu and
/// `--list` print in this order, and the interactive menu offers the first
/// entry as its default choice.
const SCENARIOS: &[Scenario] = &[
    Scenario {
        id: "merge-captain",
        title: "Merge Captain triages 3 PRs",
        description: "A merge_captain persona triages three mocked PRs (trivial, risky, buggy), \
                      asks an LLM per PR, and emits a structured supervision receipt. \
                      Demonstrates persona supervision, approval gates, and trust receipts.",
        script: include_str!("../../assets/demo/merge-captain/scenario.harn"),
        tape: include_str!("../../assets/demo/merge-captain/tape.jsonl"),
    },
    Scenario {
        id: "review-captain",
        title: "Review Captain inspects a 5-file diff",
        description: "A review_captain reviews a 5-file diff, asks one clarifying question \
                      (HITL surfaced via the receipt), then renders a verdict with \
                      reasoning. Demonstrates clarifying-question loops and structured \
                      review receipts.",
        script: include_str!("../../assets/demo/review-captain/scenario.harn"),
        tape: include_str!("../../assets/demo/review-captain/tape.jsonl"),
    },
    Scenario {
        id: "provider-race",
        title: "Provider race with cost attribution",
        description: "Race three providers on one prompt with `parallel each`, pick the \
                      lowest-latency winner, and emit a cost-attribution receipt. \
                      Previews the routing_policy primitive (#1649).",
        script: include_str!("../../assets/demo/provider-race/scenario.harn"),
        tape: include_str!("../../assets/demo/provider-race/tape.jsonl"),
    },
    Scenario {
        id: "routing-policy",
        title: "routing_policy escalates a cheap chain to a frontier link",
        description: "Drive the v0.8.40 routing_policy primitive through three mocked tasks: a \
                      clean cheap-link success, a 429 that fails over to the frontier, and a \
                      TODO-poisoned cheap reply that the lint verifier escalates. Demonstrates \
                      per-attempt routing receipts, failover, and verifier-signal escalation \
                      (canary scenario for the demo gate, #2437).",
        script: include_str!("../../assets/demo/routing-policy/scenario.harn"),
        tape: include_str!("../../assets/demo/routing-policy/tape.jsonl"),
    },
    Scenario {
        id: "stdlib-toolkit",
        title: "stdlib toolkit assembles an XML system-prompt context",
        description: "Walk the new clone / deep_merge / unique / dict_from_pairs / to_xml / \
                      from_xml / word_wrap / indent / repeat built-ins through a realistic \
                      pre-flight render: layer per-task overrides onto a shared defaults dict, \
                      dedupe the operator's `previous_chats` list, emit an XML `<context>` \
                      block, round-trip it back through the parser, and frame the result in a \
                      60-column prompt margin. Fully offline.",
        script: include_str!("../../assets/demo/stdlib-toolkit/scenario.harn"),
        tape: include_str!("../../assets/demo/stdlib-toolkit/tape.jsonl"),
    },
    Scenario {
        id: "embed-similarity",
        title: "hostlib_embed_* ranks code-agent context offline",
        description: "Drive the cross-platform hostlib embedding surface fully offline: inspect \
                      the active backend, embed one symbol-like query, compare related vs \
                      unrelated text, and top-k rank a small context corpus. Demonstrates the \
                      shared similarity contract Burin can reuse for push-context retrieval and \
                      symbol relevance without macOS-only NaturalLanguage or live model calls.",
        script: include_str!("../../assets/demo/embed-similarity/scenario.harn"),
        tape: include_str!("../../assets/demo/embed-similarity/tape.jsonl"),
    },
    Scenario {
        id: "project-metadata",
        title: "project.metadata_* falls back to Harn metadata offline",
        description: "Drive standalone `host_call(\"project.metadata_*\", ...)` through Harn's \
                      built-in metadata store: set a namespace, read it with hierarchical \
                      inheritance, inspect the origin, refresh structure hashes, and save. \
                      Demonstrates the CLI/debug fallback path while product host bridges keep \
                      precedence when attached.",
        script: include_str!("../../assets/demo/project-metadata/scenario.harn"),
        tape: include_str!("../../assets/demo/project-metadata/tape.jsonl"),
    },
    Scenario {
        id: "runtime-prompt-content",
        title: "runtime.prompt_content reads typed multimodal session input",
        description: "Mock an ACP session prompt at the runtime host boundary, read its typed text \
                      and image blocks through `runtime_prompt_content()`, and emit a structured \
                      receipt. Fully offline.",
        script: include_str!("../../assets/demo/runtime-prompt-content/scenario.harn"),
        tape: include_str!("../../assets/demo/runtime-prompt-content/tape.jsonl"),
    },
    Scenario {
        id: "verification-snapshot",
        title: "verification_file_hash_snapshot binds checks to current file bytes",
        description: "Build a throw-away Rust workspace, seed the code index, then capture a \
                      seq-bound batch of file hashes through `std/verification`: fresh indexed \
                      files reuse index metadata, changed or newly-created files read current \
                      disk bytes, missing paths are explicit, and the resulting path->hash map \
                      feeds `verification_diagnostic_classify`. Fully offline.",
        script: include_str!("../../assets/demo/verification-snapshot/scenario.harn"),
        tape: include_str!("../../assets/demo/verification-snapshot/tape.jsonl"),
    },
    Scenario {
        id: "command-capture",
        title: "run_command preserves a slow command's full output past a `| tail` filter",
        description: "Walk the std/agent/command_capture recognizer: rewrite `producer | tail/wc/grep` \
                      pipelines to `producer | tee '<capture>' 2>/dev/null | filter` so the agent \
                      still sees the filtered output while the producer's COMPLETE output is \
                      preserved on disk, show the cases it deliberately leaves untouched (head, \
                      grep -q, command substitution, subshell grouping), then materialize a capture \
                      and demonstrate the post-run `output_capture` hint that lets an agent read the \
                      full output instead of re-running a slow command. Fully offline — no LLM, no \
                      subprocess.",
        script: include_str!("../../assets/demo/command-capture/scenario.harn"),
        tape: include_str!("../../assets/demo/command-capture/tape.jsonl"),
    },
    Scenario {
        id: "agent-edit-tools",
        title: "agent_edit_tools ships the canonical write/edit/mkdir/delete toolset",
        description: "Drive the default mutation tools (#PR-D) offline: `write_file`, `edit_file`, \
                      `create_directory`, and `delete_path` from `std/agent/host_tools`, root-scoped \
                      wrappers over the hostlib filesystem primitives. Walk the happy paths, the \
                      guardrails (edit_file refuses an ambiguous match; delete_path refuses a \
                      non-empty directory unless recursive), and the middleware seam — the same \
                      named tools wrapped with `with_consent` + `with_audit_log` so an embedder gets \
                      approval and receipts for free. Honestly annotated as mutating so the \
                      read-only stance hides them. Fully offline — no LLM, no subprocess.",
        script: include_str!("../../assets/demo/agent-edit-tools/scenario.harn"),
        tape: include_str!("../../assets/demo/agent-edit-tools/tape.jsonl"),
    },
    Scenario {
        id: "compaction-policy",
        title: "compaction.{policy,check,run} drives a session through the lifecycle",
        description: "Declare a per-session compaction policy with thresholds, call \
                      `compaction.check` to get a `compact_now` / `defer` decision, then drive \
                      the canonical #2323 lifecycle via `compaction.run`. Demonstrates the \
                      lifted-from-TUI policy primitive (#2505) entirely offline using a custom \
                      summarize closure.",
        script: include_str!("../../assets/demo/compaction-policy/scenario.harn"),
        tape: include_str!("../../assets/demo/compaction-policy/tape.jsonl"),
    },
    Scenario {
        id: "mcp-host",
        title: "harn.mcp.* host primitive lazy-spawn + status round-trip",
        description: "Drive the supervised MCP-host primitive (#2504): register two lazy MCP \
                      server specs, snapshot the supervision status (restart_count, circuit, \
                      cache_entries), stop one of them, and re-snapshot. Stays fully offline \
                      because lazy spawn doesn't try to connect. The receipt asserts every \
                      initial entry starts with the circuit closed and cache empty — the \
                      invariants downstream observability hooks lean on.",
        script: include_str!("../../assets/demo/mcp-host/scenario.harn"),
        tape: include_str!("../../assets/demo/mcp-host/tape.jsonl"),
    },
    Scenario {
        id: "http-transport",
        title: "http_etag / http_choose / http_not_modified / http_upgrade_ws / http_push_hints",
        description: "Drive the A.12 transport-completeness builtins (#2515) offline: pick a \
                      content type from a simulated `Accept` header via `http_choose`, derive a \
                      strong ETag from the JSON payload, build the matching `http_not_modified` \
                      envelope, assemble the `http_upgrade_ws` envelope with subprotocol \
                      negotiation, and decorate an `http_ok` envelope with `http_push_hints` so \
                      the codec emits one `Link: <path>; rel=preload; as=...` header per asset. \
                      The conformance test in `crates/harn-serve/tests/\
                      transport_conformance.rs` exercises the live HTTP / WS path; the demo \
                      keeps the offline smoke covered.",
        script: include_str!("../../assets/demo/http-transport/scenario.harn"),
        tape: include_str!("../../assets/demo/http-transport/tape.jsonl"),
    },
    Scenario {
        id: "harn-site",
        title: "harn serve site — a .harn file answers its own HTTP routes",
        description: "Drive the `harn serve site` handler contract (#2574) offline: a routed \
                      `pub fn` receives a request dict and returns an `http_*` envelope. The \
                      scenario calls a GET handler, a POST handler that echoes its body, and a \
                      conditional GET that returns 200 then 304 via `http_not_modified`, plus the \
                      `on_message` WebSocket frame callback — capturing each status in a receipt. \
                      The live socket path (routing, multipart, WS upgrade) is covered by \
                      `crates/harn-serve/tests/site_hosting.rs`; the demo keeps the offline \
                      handler-contract smoke covered.",
        script: include_str!("../../assets/demo/harn-site/scenario.harn"),
        tape: include_str!("../../assets/demo/harn-site/tape.jsonl"),
    },
    Scenario {
        id: "obs-primitive",
        title: "harness.obs.* spans + counter/histogram/gauge + audit roundtrip",
        description: "Drive the standardized observability primitive (#2513): open a span over a \
                      simulated `harn.session.put`, record one of each instrument variant \
                      (counter / histogram / gauge), emit a structured log inside the span, then \
                      drain the in-process buffer and surface a receipt of events-by-kind plus \
                      the bound request_id. Validates vocabulary at emit time and routes through \
                      the `test` backend so the scenario stays fully offline.",
        script: include_str!("../../assets/demo/obs-primitive/scenario.harn"),
        tape: include_str!("../../assets/demo/obs-primitive/tape.jsonl"),
    },
    Scenario {
        id: "edit-rename-symbol",
        title: "edit.rename_symbol rewrites a Rust struct across the workspace",
        description: "Stage a tiny Rust workspace, build the typed symbol graph (#2434), then \
                      drive `edit_rename_symbol` (#2508) through dry-run + applied + conflict \
                      paths: a workspace-scoped plan with per-edit byte/(row,col) spans, the \
                      same plan committed for real with identifier-context rewrites (skipping \
                      string literals and comments), and a follow-up rename whose new name \
                      already shadows another identifier — host short-circuits without \
                      touching disk. Fully offline.",
        script: include_str!("../../assets/demo/edit-rename-symbol/scenario.harn"),
        tape: include_str!("../../assets/demo/edit-rename-symbol/tape.jsonl"),
    },
    Scenario {
        id: "edit-language-coverage",
        title: "edit.capabilities + apply_node span the B.7 tier-1 languages",
        description: "Read the per-language AST-precise edit capability matrix (#2519), show \
                      graceful degradation for a language with no grammar (Dockerfile returns \
                      `unsupported_language` plus a text-edit fallback), then drive \
                      `edit_apply_node` (dry-run) against bundled JSON and CSS seeds to prove a \
                      format-preserving edit round-trips on the data/markup grammars added in \
                      B.7. Fully offline.",
        script: include_str!("../../assets/demo/edit-language-coverage/scenario.harn"),
        tape: include_str!("../../assets/demo/edit-language-coverage/tape.jsonl"),
    },
    Scenario {
        id: "edit-refactor",
        title: "edit.extract_function / add_parameter / change_return_type preview as diffs",
        description: "Drive the B.8 structured-refactoring primitives (#2520) offline against a \
                      bundled seed workspace, all in dry-run mode: extract two statements of a \
                      Python function into `compute_subtotal` (capturing `base`/`qty` but not the \
                      module-level `audit`), append a trailing parameter to a Rust function and \
                      fill the argument at all three call sites, and rewrite that function's \
                      return type — each previewed as a unified diff against a throw-away \
                      staged-fs overlay so no bytes hit disk. The conformance test in \
                      `crates/harn-vm`/`conformance` exercises the apply path; this demo keeps \
                      the offline preview smoke covered.",
        script: include_str!("../../assets/demo/edit-refactor/scenario.harn"),
        tape: include_str!("../../assets/demo/edit-refactor/tape.jsonl"),
    },
    Scenario {
        id: "prompt-guidance",
        title: "tool guidance rides with the tool, and the prompt is auditable",
        description: "Drive the unified prompt-fragment assembler: a tool carries a `guidance` \
                      string that the runtime injects as a capability-gated system-prompt fragment \
                      (`requires_tools: [<that tool>]`), so a 'always update the TODO tracker' \
                      instruction appears only when the todo tool is present and never otherwise — \
                      instruction and tool share one source of truth and cannot drift. Calls \
                      `prompt_explain(options)` with and without the tool, prints the assembled \
                      system string plus the per-fragment provenance (included/excluded + reason + \
                      bytes) an operator inspects, and proves the only difference between the two \
                      prompts is exactly the gated fragment. Fully offline — no LLM, no network.",
        script: include_str!("../../assets/demo/prompt-guidance/scenario.harn"),
        tape: include_str!("../../assets/demo/prompt-guidance/tape.jsonl"),
    },
    Scenario {
        id: "destructure-with-defaults",
        title: "destructuring-with-defaults collapses the `input?.x ?? default` idiom",
        description: "Collapse the most-repeated idiom in our Harn corpus — \
                      `const x = input?.field ?? default` (~5,700 sites across BurinCore alone) — \
                      into a single destructuring bind: `const { path = \"\", namespace = nil } = \
                      pipeline_input() ?? {}`. Present keys win, missing keys fall to their \
                      defaults, and the type checker now infers each binding's type from \
                      `field + default` exactly as the `?.`/`??` form did, so the migration is \
                      lossless under the checker. Fully offline — no LLM, no network.",
        script: include_str!("../../assets/demo/destructure-with-defaults/scenario.harn"),
        tape: include_str!("../../assets/demo/destructure-with-defaults/tape.jsonl"),
    },
    Scenario {
        id: "lexical-block",
        title: "`block` bounds cleanup and owned lifetimes",
        description: "Use an explicit `block { ... }` to create a lexical lifetime without a \
                      control-flow condition: keep inner bindings scoped, run deferred cleanup at \
                      the block boundary, then continue with outer state. This is \
                      the direct lifetime primitive for owned resources that previously required \
                      a helper function. Fully offline — no LLM, network, or subprocess.",
        script: include_str!("../../assets/demo/lexical-block/scenario.harn"),
        tape: include_str!("../../assets/demo/lexical-block/tape.jsonl"),
    },
    Scenario {
        id: "pub-type-exports",
        title: "`pub type` shares one alias across modules, annotations, and output",
        description: "Export a type alias from one module and consume it from another: the \
                      imported alias drives a plain annotation, an exhaustive `match` over its \
                      literal union, and schema-as-type on `llm_call` \
                      (`output: GradeReport`) — the compiler lowers the exported alias to \
                      JSON Schema and the validated result narrows back to it. Before `pub type`, \
                      every consumer re-declared shared wire shapes because aliases were \
                      module-private. Offline — the single LLM call replays from the bundled \
                      tape.",
        script: include_str!("../../assets/demo/pub-type-exports/scenario.harn"),
        tape: include_str!("../../assets/demo/pub-type-exports/tape.jsonl"),
    },
    Scenario {
        id: "catalog-patch-models",
        title: "[patch.models] tweaks one catalog field without copying the row",
        description: "A sibling harn.toml contributes a demo catalog row and a field-wise \
                      `[llm.patch.models]` patch for two of its fields (stream_timeout and \
                      pricing.output_per_mtok). The scenario reads the effective catalog back \
                      via `llm_model_info` and asserts the patched fields carry the patch \
                      values while every unpatched sibling field keeps its baseline — the \
                      alternative used to be copying the whole row verbatim and freezing it \
                      against catalog updates. Fully offline — no LLM calls.",
        script: include_str!("../../assets/demo/catalog-patch-models/scenario.harn"),
        tape: include_str!("../../assets/demo/catalog-patch-models/tape.jsonl"),
    },
];

#[derive(Clone, Copy)]
struct Scenario {
    id: &'static str,
    title: &'static str,
    description: &'static str,
    script: &'static str,
    tape: &'static str,
}

/// Public list of bundled scenario ids — used by tests and the smoke
/// loop that exercises every demo on every PR.
pub fn scenario_ids() -> Vec<&'static str> {
    SCENARIOS.iter().map(|s| s.id).collect()
}

/// What a bare `harn demo` (no scenario argument) should do.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum NoScenarioAction {
    /// Render the scenario list as JSON.
    ListJson,
    /// Prompt for a choice on an interactive terminal.
    Prompt,
    /// Print the scenario list as a table.
    ListTable,
}

/// Prompting needs a terminal at both ends: stdout to render the menu and stdin
/// to read the choice. Anywhere else — a pipe, a redirect, CI — print the menu
/// rather than running a scenario the caller never named.
fn no_scenario_action(json: bool, stdout_tty: bool, stdin_tty: bool) -> NoScenarioAction {
    if json {
        return NoScenarioAction::ListJson;
    }
    if stdout_tty && stdin_tty {
        return NoScenarioAction::Prompt;
    }
    NoScenarioAction::ListTable
}

pub(crate) async fn run(args: DemoArgs) -> i32 {
    if args.list {
        print_list_table(args.json);
        return 0;
    }

    let Some(scenario_id) = args.scenario.clone() else {
        return match no_scenario_action(
            args.json,
            std::io::stdout().is_terminal(),
            std::io::stdin().is_terminal(),
        ) {
            NoScenarioAction::ListJson => {
                print_list_table(true);
                0
            }
            NoScenarioAction::Prompt => interactive_pick(&args).await,
            NoScenarioAction::ListTable => {
                print_list_table(false);
                0
            }
        };
    };

    let Some(scenario) = lookup_scenario(&scenario_id) else {
        eprintln!("error: unknown scenario `{scenario_id}`");
        eprintln!();
        print_list_table(false);
        return 2;
    };
    run_scenario(&args, *scenario).await
}

fn lookup_scenario(id: &str) -> Option<&'static Scenario> {
    SCENARIOS.iter().find(|s| s.id == id)
}

fn print_list_table(as_json: bool) {
    if as_json {
        let entries: Vec<serde_json::Value> = SCENARIOS
            .iter()
            .map(|s| {
                serde_json::json!({
                    "id": s.id,
                    "title": s.title,
                    "description": s.description,
                })
            })
            .collect();
        println!(
            "{}",
            serde_json::to_string_pretty(&serde_json::json!({"scenarios": entries}))
                .unwrap_or_default()
        );
        return;
    }
    println!("Available demos (replayable offline, no API keys required):");
    println!();
    for s in SCENARIOS {
        println!("  {:<16}  {}", s.id, s.title);
        for line in wrap_text(s.description, 70) {
            println!("    {line}");
        }
        println!();
    }
    println!("Run a scenario:    harn demo <id>");
    println!("Use real provider: harn demo <id> --live");
}

/// Greedy word-wrap for terminal output. `width` is a column budget, so the
/// fit test measures display columns — byte length wraps non-ASCII text far
/// too early, and a `char` count misses double-width CJK and emoji.
fn wrap_text(text: &str, width: usize) -> Vec<String> {
    let mut lines = Vec::new();
    let mut current = String::new();
    for word in text.split_whitespace() {
        if current.is_empty() {
            current.push_str(word);
            continue;
        }
        if UnicodeWidthStr::width(current.as_str()) + 1 + UnicodeWidthStr::width(word) > width {
            lines.push(std::mem::take(&mut current));
            current.push_str(word);
        } else {
            current.push(' ');
            current.push_str(word);
        }
    }
    if !current.is_empty() {
        lines.push(current);
    }
    lines
}

async fn interactive_pick(args: &DemoArgs) -> i32 {
    use std::io::Write;
    println!("Pick a Harn demo (offline replay, no API keys required):");
    println!();
    for (idx, s) in SCENARIOS.iter().enumerate() {
        println!("  {}) {:<16}  {}", idx + 1, s.id, s.title);
    }
    println!();
    print!("Choice [1-{}, default 1]: ", SCENARIOS.len());
    let _ = std::io::stdout().flush();
    let mut buf = String::new();
    let n = std::io::stdin().read_line(&mut buf).unwrap_or(0);
    let trimmed = buf.trim();
    let pick: usize = if n == 0 || trimmed.is_empty() {
        1
    } else {
        match trimmed.parse::<usize>() {
            Ok(n) if (1..=SCENARIOS.len()).contains(&n) => n,
            _ => {
                eprintln!("error: invalid selection `{trimmed}`");
                return 2;
            }
        }
    };
    run_scenario(args, SCENARIOS[pick - 1]).await
}

async fn run_scenario(args: &DemoArgs, scenario: Scenario) -> i32 {
    let staged = match stage_scenario(scenario) {
        Ok(s) => s,
        Err(error) => {
            eprintln!("error: {error}");
            return 1;
        }
    };

    if !args.json {
        println!("=== harn demo · {} ===", scenario.id);
        println!("{}", scenario.title);
        println!();
        if !args.live {
            println!("(offline replay — no API keys required)");
            println!();
        }
    }

    let llm_mock_mode = if args.live {
        if !args.json {
            println!("(--live: routing through the configured provider — set HARN_LLM_PROVIDER if none is wired)");
            println!();
        }
        CliLlmMockMode::Off
    } else {
        CliLlmMockMode::Replay {
            fixture_path: staged.tape_path.clone(),
        }
    };

    // Run the demo hermetically: root both the sandbox workspace and the
    // process working directory at the staged tempdir. This way file-backed
    // prompts and imports resolve relative to the script, and anything the
    // scenario writes (e.g. command-capture's output file, addressed via
    // `execution_root()`) lands in the tempdir instead of polluting the
    // caller's cwd. The cwd guard is scoped to the run and restored before the
    // run record is written, so records still land under the user's cwd.
    let sandbox = RunSandboxOptions {
        workspace_root: Some(staged.root.clone()),
        ..RunSandboxOptions::default()
    };

    let started = Instant::now();
    let outcome = {
        let _cwd = ScopedCwd::enter(&staged.root);
        execute_run_with_sandbox_options(
            staged.script_path.to_string_lossy().as_ref(),
            false,
            HashSet::new(),
            Vec::new(),
            Vec::new(),
            llm_mock_mode,
            None,
            RunProfileOptions::default(),
            sandbox,
        )
        .await
    };
    let elapsed = started.elapsed();

    if !args.json && !outcome.stdout.is_empty() {
        print!("{}", outcome.stdout);
    }
    if !outcome.stderr.is_empty() {
        eprint!("{}", outcome.stderr);
    }

    if outcome.exit_code != 0 {
        if !args.json {
            eprintln!(
                "error: demo `{}` failed (exit {})",
                scenario.id, outcome.exit_code
            );
            if args.live && live_failure_looks_like_provider_misconfig(&outcome) {
                eprintln!();
                eprintln!("hint: --live needs a configured LLM provider. Re-run without --live");
                eprintln!("      to use the bundled offline tape, or run `harn quickstart`");
                eprintln!("      to wire a provider.");
            }
        } else {
            print_json_summary(scenario, &outcome, elapsed.as_millis(), None);
        }
        return outcome.exit_code;
    }

    let receipt_dir = if args.no_record {
        None
    } else {
        match write_run_record(scenario, &outcome) {
            Ok(path) => Some(path),
            Err(error) => {
                eprintln!("warning: failed to write demo run record: {error}");
                None
            }
        }
    };

    if args.json {
        print_json_summary(
            scenario,
            &outcome,
            elapsed.as_millis(),
            receipt_dir.as_deref(),
        );
    } else {
        println!();
        println!("--- demo complete in {} ms ---", elapsed.as_millis());
        if let Some(dir) = &receipt_dir {
            println!("  run record: {}", dir.join("run.json").display());
        }
        println!();
        println!("Next steps:");
        println!("  harn demo --list           list every bundled scenario");
        if !args.live {
            println!(
                "  harn demo {} --live      run again against the configured provider",
                scenario.id
            );
        }
        println!("  harn portal                browse run records in the UI");
    }
    0
}

struct StagedScenario {
    _temp_root: tempfile::TempDir,
    script_path: PathBuf,
    tape_path: PathBuf,
    /// The staged tempdir holding the script, tape, and any sibling files.
    /// The run is rooted here (cwd + sandbox workspace) so the scenario
    /// executes hermetically: file-backed prompts and imports resolve, and any
    /// artifacts it writes land in the tempdir instead of the caller's cwd.
    root: PathBuf,
}

/// RAII guard that sets the process working directory for the duration of a
/// single demo run and restores the previous one on drop (including on early
/// return or panic). `harn demo` runs one scenario at a time, so this brief,
/// scoped change to process-global cwd is safe and lets scenarios execute as if
/// the staged tempdir were the working directory.
struct ScopedCwd {
    previous: Option<PathBuf>,
}

impl ScopedCwd {
    fn enter(dir: &Path) -> Self {
        let previous = std::env::current_dir().ok();
        if let Err(error) = std::env::set_current_dir(dir) {
            eprintln!(
                "warning: failed to enter demo working dir {}: {error}",
                dir.display()
            );
        }
        Self { previous }
    }
}

impl Drop for ScopedCwd {
    fn drop(&mut self) {
        if let Some(previous) = self.previous.take() {
            let _ = std::env::set_current_dir(previous);
        }
    }
}

fn stage_scenario(scenario: Scenario) -> Result<StagedScenario, String> {
    let dir = tempfile::Builder::new()
        .prefix(&format!("harn-demo-{}-", scenario.id))
        .tempdir()
        .map_err(|e| format!("failed to create demo tempdir: {e}"))?;
    let script_path = dir.path().join(format!("{}.harn", scenario.id));
    let tape_path = dir.path().join(format!("{}.tape.jsonl", scenario.id));
    fs::write(&script_path, scenario.script)
        .map_err(|e| format!("failed to stage demo script: {e}"))?;
    fs::write(&tape_path, scenario.tape).map_err(|e| format!("failed to stage demo tape: {e}"))?;

    // Materialize any sibling files (`.harn.prompt` templates, imported
    // modules, fixtures) next to the script so file-backed prompts and imports
    // resolve relative to the script, the same way a real Harn project is laid
    // out on disk.
    let prefix = format!("{}/", scenario.id);
    for (rel, bytes) in DEMO_SIBLING_FILES {
        let Some(sub) = rel.strip_prefix(&prefix) else {
            continue;
        };
        let dest = dir.path().join(sub);
        if let Some(parent) = dest.parent() {
            fs::create_dir_all(parent).map_err(|e| {
                format!("failed to create demo asset dir {}: {e}", parent.display())
            })?;
        }
        fs::write(&dest, bytes).map_err(|e| format!("failed to stage demo asset {sub}: {e}"))?;
    }

    let root = dir.path().to_path_buf();
    Ok(StagedScenario {
        _temp_root: dir,
        script_path,
        tape_path,
        root,
    })
}

fn write_run_record(scenario: Scenario, outcome: &RunOutcome) -> Result<PathBuf, String> {
    let cwd = std::env::current_dir().map_err(|e| format!("cwd: {e}"))?;
    let runs_root = cwd.join(".harn-runs");
    let ts = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    let started_iso = time::OffsetDateTime::from_unix_timestamp(ts as i64)
        .ok()
        .and_then(|t| {
            t.format(&time::format_description::well_known::Rfc3339)
                .ok()
        })
        .unwrap_or_else(|| format!("1970-01-01T00:00:{ts:02}Z"));
    let dir = runs_root.join(format!("demo-{}-{ts}", scenario.id));
    fs::create_dir_all(&dir).map_err(|e| format!("create {}: {e}", dir.display()))?;
    // Conform to the `run_record` envelope the portal scans for so the
    // demo shows up in `harn portal` alongside real workflow runs. The
    // demo-specific payload (script, tape ref, stdout/stderr) lives
    // under `metadata.demo` so portal listings can group on it.
    let record = serde_json::json!({
        "_type": "run_record",
        "id": format!("demo-{}-{ts}", scenario.id),
        "workflow_id": format!("harn-demo:{}", scenario.id),
        "workflow_name": scenario.title,
        "task": scenario.id,
        "status": if outcome.exit_code == 0 { "complete" } else { "failed" },
        "started_at": started_iso,
        "finished_at": started_iso,
        "stages": [],
        "transitions": [],
        "checkpoints": [],
        "pending_nodes": [],
        "completed_nodes": [],
        "child_runs": [],
        "artifacts": [],
        "policy": {},
        "metadata": {
            "demo": {
                "scenario": scenario.id,
                "title": scenario.title,
                "description": scenario.description,
                "exit_code": outcome.exit_code,
                "stdout": outcome.stdout,
                "stderr": outcome.stderr,
                "recorded_at_unix_seconds": ts,
            }
        },
    });
    let path = dir.join("run.json");
    fs::write(
        &path,
        serde_json::to_string_pretty(&record).unwrap_or_default(),
    )
    .map_err(|e| format!("write {}: {e}", path.display()))?;
    Ok(dir)
}

fn live_failure_looks_like_provider_misconfig(outcome: &RunOutcome) -> bool {
    // Heuristic on the rendered diagnostic — every error path Harn
    // surfaces for "no key / wrong key / no provider" is one of these
    // category strings or substrings. Avoids over-firing on script
    // bugs that happen to fail under `--live`.
    let blob = format!("{}{}", outcome.stderr, outcome.stdout);
    blob.contains("category: auth")
        || blob.contains("auth_failure")
        || blob.contains("HTTP 401")
        || blob.contains("HTTP 403")
        || blob.contains("api_key")
        || blob.contains("HARN_LLM_PROVIDER")
        || blob.contains("no provider configured")
}

fn print_json_summary(
    scenario: Scenario,
    outcome: &RunOutcome,
    elapsed_ms: u128,
    record_dir: Option<&Path>,
) {
    let record = serde_json::json!({
        "scenario": scenario.id,
        "title": scenario.title,
        "exit_code": outcome.exit_code,
        "elapsed_ms": elapsed_ms,
        "stdout": outcome.stdout,
        "stderr": outcome.stderr,
        "run_record_dir": record_dir.map(|p| p.display().to_string()),
    });
    println!(
        "{}",
        serde_json::to_string_pretty(&record).unwrap_or_default()
    );
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn wrap_text_budgets_columns_not_bytes_or_chars() {
        // Each word is 2 chars / 6 bytes / 4 columns, which separates all three
        // readings under a budget of 9: by columns exactly two words fit
        // (4 + 1 + 4 = 9); by bytes not even two would (6 + 1 + 6 = 13); by
        // chars all three would have been packed onto one line (8).
        let wrapped = wrap_text("日本 語で すね", 9);
        assert_eq!(wrapped, vec!["日本 語で".to_string(), "すね".to_string()]);
    }

    #[test]
    fn wrap_text_treats_emoji_as_double_width() {
        // "🚀🚀" is 2 chars but 4 columns, so it cannot join "ab" under a
        // budget of 6 (2 + 1 + 4 = 7). A char count would have packed them.
        assert_eq!(
            wrap_text("ab 🚀🚀", 6),
            vec!["ab".to_string(), "🚀🚀".to_string()]
        );
    }

    #[test]
    fn wrap_text_is_unchanged_for_ascii() {
        assert_eq!(
            wrap_text("the quick brown fox", 9),
            vec!["the quick".to_string(), "brown fox".to_string()]
        );
    }

    #[test]
    fn bare_demo_action_covers_every_stdio_shape() {
        let cases = [
            (false, true, true, NoScenarioAction::Prompt),
            (false, true, false, NoScenarioAction::ListTable),
            (false, false, true, NoScenarioAction::ListTable),
            (false, false, false, NoScenarioAction::ListTable),
            (true, true, true, NoScenarioAction::ListJson),
            (true, true, false, NoScenarioAction::ListJson),
            (true, false, true, NoScenarioAction::ListJson),
            (true, false, false, NoScenarioAction::ListJson),
        ];
        for (json, stdout_tty, stdin_tty, expected) in cases {
            assert_eq!(
                no_scenario_action(json, stdout_tty, stdin_tty),
                expected,
                "json={json} stdout_tty={stdout_tty} stdin_tty={stdin_tty}"
            );
        }
    }

    #[test]
    fn scenarios_have_unique_nonempty_ids() {
        let mut seen = HashSet::new();
        for s in SCENARIOS {
            assert!(!s.id.is_empty(), "scenario id is empty");
            assert!(!s.title.is_empty(), "scenario {} has empty title", s.id);
            assert!(
                !s.description.is_empty(),
                "scenario {} has empty description",
                s.id
            );
            assert!(!s.script.is_empty(), "scenario {} script is empty", s.id);
            assert!(!s.tape.is_empty(), "scenario {} tape is empty", s.id);
            assert!(seen.insert(s.id), "duplicate scenario id: {}", s.id);
        }
    }

    #[test]
    fn review_captain_prompt_templates_are_embedded() {
        // Drift guard for the build.rs sibling-asset embedding + the
        // review-captain migration to file-backed prompts. If the build script
        // stops embedding sibling files (or the prompt files are renamed away),
        // the demo's `render_prompt` calls would fail at runtime; catch it here.
        for name in [
            "review-captain/review.harn.prompt",
            "review-captain/clarification.harn.prompt",
        ] {
            let found = DEMO_SIBLING_FILES
                .iter()
                .find(|(rel, _)| *rel == name)
                .unwrap_or_else(|| panic!("demo sibling asset `{name}` was not embedded"));
            assert!(!found.1.is_empty(), "embedded demo asset `{name}` is empty");
        }
    }

    #[test]
    fn embedded_sibling_files_exclude_primary_and_runrecord_files() {
        // The primary script + tape are embedded separately via include_str!;
        // the gitignored `.harn/` run-record dir must never be embedded.
        for (rel, _) in DEMO_SIBLING_FILES {
            assert!(
                !rel.ends_with("/scenario.harn") && !rel.ends_with("/tape.jsonl"),
                "primary file `{rel}` should not be in the sibling table"
            );
            assert!(
                !rel.contains("/.harn/"),
                "run-record file `{rel}` should not be embedded"
            );
        }
    }

    #[test]
    fn scenario_tape_lines_parse_as_json() {
        for s in SCENARIOS {
            for (i, line) in s.tape.lines().enumerate() {
                if line.trim().is_empty() {
                    continue;
                }
                serde_json::from_str::<serde_json::Value>(line).unwrap_or_else(|e| {
                    panic!("scenario {} tape line {} is invalid JSON: {e}", s.id, i + 1)
                });
            }
        }
    }

    #[test]
    fn scenario_ids_match_assets_dir_names() {
        // Sanity: the const SCENARIOS array's ids should mirror the
        // checked-in asset directories. If a developer adds a new
        // scenario but forgets to wire it into SCENARIOS, this test
        // does nothing — but if they rename an asset dir without
        // updating the const, the include_str! at top will fail to
        // compile, which is the better failure mode.
        let manifest_dir = env!("CARGO_MANIFEST_DIR");
        let assets = std::path::Path::new(manifest_dir).join("assets/demo");
        for s in SCENARIOS {
            let dir = assets.join(s.id);
            assert!(dir.is_dir(), "missing demo asset dir for {}", s.id);
            assert!(
                dir.join("scenario.harn").is_file(),
                "missing scenario.harn for {}",
                s.id
            );
            assert!(
                dir.join("tape.jsonl").is_file(),
                "missing tape.jsonl for {}",
                s.id
            );
        }
    }
}