node-app-build 6.12.2

//! Live-stack probes: bring-up, status, mine, fund, channel, pay, logs, down.
//!
//! Each function corresponds to one `harness` subcommand.  They all operate
//! against the running stack and share the `HarnessState` index written by
//! `up()`.

use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};

use anyhow::{Context, Result};
#[cfg(unix)]
use libc;
use serde::Serialize;
use serde_json::json;

use crate::commands::dev;
use crate::commands::dev::agent::client::{AgentHttpClient, ProbeError};
use crate::commands::dev::agent::session::AgentSession;
use crate::commands::dev::host::{self, DaemonHost, InstanceProfile, Mode};
use crate::commands::harness::bitcoind::Bitcoind;
use crate::commands::harness::ports;
use crate::commands::harness::state::{
    resolve_state_path, state_path, BitcoindState, ChannelState, HarnessState, InstanceState,
};
use crate::commands::harness::BitcoindMode;

/// Bring up the full harness stack, write `harness-state.json`, and then
/// **block as a foreground supervisor** keeping alice + bob alive.
///
/// Sequence:
///   1. (optional clean) remove any prior state file + wipe partial DBs
///   2. bitcoind — LDK connects to it at daemon boot, so it MUST come first
///   3. build + spawn alice + bob directly via the host layer
///      (`host::for_mode(...).ensure_running()`), which blocks until each
///      daemon's IPC socket + HTTP port are ready
///   4. onboard + cross-seed via `agent::run_agent_setup`
///   5. load the agent sessions, build + save HarnessState (with supervisor pid)
///   6. print state JSON + a readiness line, then block until SIGTERM/SIGINT
///   7. on signal: shut each daemon down, stop bitcoind, return Ok
///
/// Unlike the old `dev::run(once: true)` path (which killed the daemons after
/// onboarding), the daemons stay alive because this process supervises them:
/// the `hosts` Vec (which owns each daemon `Child` + its stdio drain threads)
/// is kept in scope for the whole supervise loop.
///
/// When `--with-channel` is passed, `open_channel_flow` funds alice on-chain,
/// opens an alice→bob channel, and waits for it to become usable before the
/// READY line is printed.  Full `harness down` reuses the `supervisor_pid` written here.
pub fn up(
    monorepo_path: std::path::PathBuf,
    bitcoind_mode: BitcoindMode,
    with_channel: bool,
    clean: bool,
    // When `Some(name)`, both supervised instances boot in the client-node
    // PWA lane (port-offset HTTP/HTTPS/UI/OTA/P2P/cache/env); `name` selects
    // which instance gets auto-approval below.
    client_node: Option<String>,
    operation_mode: bool,
) -> Result<()> {
    // The client-node lane renames EVERY supervised instance (`alice` → `alice-pwa`), and that
    // label is what `monorepo_env_dir` hashes into the per-instance cache directory and what
    // `AgentSession::file_path` embeds in the session filename. So every filesystem path below —
    // the `--clean` wipe, the partial-state pre-flight, and the session load that builds
    // `HarnessState` — must resolve through the lane label, not the bare `alice`/`bob` the CLI
    // and the probe subcommands speak in. Getting this wrong is silent: onboarding writes
    // `alice-pwa`'s session under `alice-pwa`'s root while `--clean` wipes `alice`'s root and the
    // load looks for `alice`'s session, so a "clean" run leaves the real node's user in place,
    // its re-onboarding is refused with HTTP 409, and `up` dies at `load alice agent session`
    // having already brought both daemons up successfully.
    //
    // `InstanceState.name` deliberately keeps the BASE name: `harness pay alice bob`,
    // `state.instance("alice")` and `--client-node alice` are the user-facing vocabulary, and the
    // lane suffix is an implementation detail of where bytes live on disk.
    let serve_client_node = client_node.is_some();
    let lane_name = |base: &str| {
        crate::commands::dev::host::monorepo::lane_instance_name(base, serve_client_node)
    };

    // Claim the checkout BEFORE `--clean` touches anything. Harness state is per-checkout, so a
    // concurrent `up` would delete the running one's `harness-state.json` — orphaning its daemons
    // and leaving `down` with no `supervisor_pid` to signal, so it reports "no running harness"
    // while two node-servers keep their ports. Held for the whole supervise loop; released on
    // drop, including on every `?` below.
    let _lock = crate::commands::harness::state::HarnessLock::acquire(&monorepo_path)?;

    if clean {
        // Best-effort removal of a prior state file before re-upping.
        // Also wipe the per-instance node DBs and session files so
        // fresh onboarding succeeds (nodes with existing users reject
        // a new onboarding-challenge with HTTP 409).
        // Full teardown (stopping daemons + container) is added when
        // harness down is implemented.
        if let Ok(path) = state_path(&monorepo_path) {
            if path.exists() {
                let _ = std::fs::remove_file(&path);
            }
        }
        for base in ["alice", "bob"] {
            let instance = lane_name(base);
            let instance = instance.as_str();
            if let Ok(env_dir) = crate::commands::dev::host::monorepo::monorepo_dev_dir(
                &monorepo_path,
                instance,
                None,
            ).map(|dev_dir| dev_dir.parent().unwrap_or(&dev_dir).to_path_buf()) {
                // dev.db (and WAL/SHM) hold the node user account — wipe so
                // fresh onboarding is allowed by the server. lightning.db +
                // ldk_data hold LDK/BDK's persisted chain state (channel_manager
                // best block, header cache). Every `up` starts a fresh `--rm`
                // regtest bitcoind (ephemeral chain from genesis), so stale
                // ldk_data references block hashes that no longer exist on the
                // new chain → initial `synchronize_listeners` fails with
                // `RpcError -5 "Block not found"`, the node never leaves the
                // retry loop, and its chain tip freezes at the old height →
                // channel funding never confirms. Wipe them here so LDK starts
                // in lockstep with the fresh chain (mirrors `down --clean`).
                for name in ["dev.db", "dev.db-shm", "dev.db-wal", "lightning.db"] {
                    let _ = std::fs::remove_file(env_dir.join(name));
                }
                for name in ["ldk_data", "ldk_node_data", "ldk_node_data_backup"] {
                    let _ = std::fs::remove_dir_all(env_dir.join(name));
                }
                // Remove the stale session file so load_for_harness doesn't
                // return a session that references a now-deleted user.
                let dev_dir = env_dir.join("dev-apps");
                let _ = std::fs::remove_file(
                    crate::commands::dev::agent::session::AgentSession::file_path(&dev_dir, instance)
                );
            }
        }
    }

    // Pre-flight: if a node DB exists but the session file does not, we're in
    // a partial state from a prior interrupted run.  Wipe the DB so that
    // `node-server` boots clean and fresh onboarding succeeds.  This is
    // safe because the session file is the only persistent auth artifact
    // the harness relies on; without it the node is effectively unrecoverable
    // for our purposes anyway.
    for base in ["alice", "bob"] {
        let instance = lane_name(base);
        let instance = instance.as_str();
        if let Ok(dev_dir) = crate::commands::dev::host::monorepo::monorepo_dev_dir(
            &monorepo_path,
            instance,
            None,
        ) {
            let session_exists =
                crate::commands::dev::agent::session::AgentSession::file_path(&dev_dir, instance).exists();
            let env_dir = dev_dir.parent().unwrap_or(&dev_dir).to_path_buf();
            let db_exists = env_dir.join("dev.db").exists();
            if db_exists && !session_exists {
                eprintln!(
                    "harness: {instance} DB exists but session missing — \
                     wiping DB for clean re-onboard"
                );
                // Wipe LDK/BDK chain state too: even a non-`--clean` up gets a
                // fresh `--rm` genesis chain, so stale ldk_data reproduces the
                // frozen-tip stall documented in the `--clean` block above.
                for name in ["dev.db", "dev.db-shm", "dev.db-wal", "lightning.db"] {
                    let _ = std::fs::remove_file(env_dir.join(name));
                }
                for name in ["ldk_data", "ldk_node_data", "ldk_node_data_backup"] {
                    let _ = std::fs::remove_dir_all(env_dir.join(name));
                }
            }
        }
    }

    // Preflight the app tree before spending ~2 minutes on bitcoind + two
    // daemon boots. Without these apps the nodes come up but cannot onboard,
    // and that only surfaces after the full bring-up (see step 3).
    preflight_apps(&monorepo_path)?;

    // Install the shared SIGINT/SIGTERM handler now, so a signal arriving
    // mid-bring-up is observed rather than terminating the process abruptly
    // and orphaning the daemons.
    dev::install_shutdown_handler();

    // 1. bitcoind first — the daemons' LDK dials it at boot.
    let btc = Bitcoind::ensure(bitcoind_mode).context("bring up regtest bitcoind")?;

    // 2. Build one host per instance and bring each up. `ensure_running()`
    //    BLOCKS until the daemon's IPC socket + HTTP port are ready, and stores
    //    the daemon `Child` (plus its stdio drain threads) inside the host.
    //    node-server is built at most once (guarded by DAEMON_BUILD_ONCE).
    let mode = Mode::Monorepo { path: monorepo_path.clone() };
    let profiles = [InstanceProfile::alice(), InstanceProfile::bob()];

    // 1c. Allocate client-node lane ports BEFORE constructing hosts (spec D7
    // revision — real coexistence). The documented base (`ports::lane_offset`)
    // is only the FIRST candidate: `ports::allocate_lane_ports` probes it and,
    // only if a `Foreign` holder occupies it (e.g. a second concurrent
    // `harness up --client-node` for the same instance name from a different
    // checkout), shifts to the next slot. The common case — one harness on
    // this box — always gets the well-known literal (alice = 3301, etc.)
    // unchanged. `state_for_allocation` is this checkout's OWN prior
    // harness-state.json if one exists (best-effort — `None` just means that
    // signal contributes nothing, not that attribution silently succeeds).
    //
    // The result is recorded on each `InstanceState` below
    // (`client_node_ports`) rather than left for a later probe to
    // re-derive from `lane_offset` — once a shift happens, the base formula
    // alone is no longer the truth.
    let state_for_allocation = HarnessState::load_for(&monorepo_path).ok();
    let port_overrides: Vec<Option<ports::PortSet>> = profiles
        .iter()
        .map(|p| -> Result<Option<ports::PortSet>> {
            if !serve_client_node {
                return Ok(None);
            }
            let lane = lane_name(&p.name);
            let expected_env_path = crate::commands::dev::host::monorepo::monorepo_dev_dir(
                &monorepo_path,
                &lane,
                None,
            )?
            .parent()
            .map(|env_dir| env_dir.join("daemon.env"));
            let base =
                ports::PortSet::base_for(&p.name, p.http_port, p.https_port, p.p2p_port, p.ui_port);
            let allocated = ports::allocate_lane_ports(
                base,
                expected_env_path.as_deref(),
                state_for_allocation.as_ref(),
            )
            .with_context(|| format!("allocate client-node lane ports for {}", p.name))?;
            Ok(Some(allocated))
        })
        .collect::<Result<Vec<_>>>()?;

    // Both supervised instances boot in the client-node lane together when a
    // client-node instance is selected; `client_node` (the name) only picks
    // which one later gets auto-approval, not which one gets the offset.
    // (`serve_client_node` is bound at the top of `up` — see the lane-label comment there.)
    let hosts: Vec<Box<dyn DaemonHost>> = profiles
        .iter()
        .zip(&port_overrides)
        .map(|(p, port_override)| {
            host::for_mode(mode.clone(), p.clone(), None, None, None, serve_client_node, *port_override)
        })
        .collect();

    // Standalone manifests must be staged BEFORE the daemons boot. The daemon's boot-time
    // `standalone_discovery` scan is what binds each standalone app to its per-instance UDS;
    // staging afterwards leaves the app running and able to CALL capabilities (its control-socket
    // client works) while never being registered as a PROVIDER of its own — which is the
    // confusing half-alive state behind "onboarding.device.list never registered a provider".
    // `node-app dev` stages pre-boot for exactly this reason (see `dev::platform`).
    let standalone_sources = module_app_dirs(&monorepo_path);
    let pre_start_dirs: Vec<std::path::PathBuf> =
        hosts.iter().filter_map(|h| h.pre_start_dev_dir()).collect();
    if !pre_start_dirs.is_empty() {
        dev::platform::stage_standalone_manifests(&standalone_sources, &pre_start_dirs, None)
            .context("stage standalone manifests before daemon boot")?;
    }

    let mut handles = Vec::new();
    for h in &hosts {
        handles.push(h.ensure_running().context("start platform daemon")?);
    }

    // 2b. Spawn the standalone apps.
    //
    // An app whose manifest says `app_type: "standalone"` is NOT loaded by the daemon: it is an
    // independent process that registers itself back over the control socket
    // (`app.register_standalone`), which is why `app.reload` on one answers "standalone apps are
    // not managed by NodeAppManager". On a device systemd starts them; under `node-app dev`
    // `spawn_standalones` does. The harness did neither, so every capability a standalone app
    // provides stayed unregistered — including `onboarding.device.*`, which the client-device
    // pairing endpoint and the operation-mode approver both depend on. The approver's
    // "device surface did not become available within 90s; onboarding.device.list never
    // registered a provider" was that gap, not a slow start.
    //
    // Reuses the `dev` staging+spawn pair rather than reimplementing it: the staging step is
    // load-bearing, since it rewrites each app's `standalone.socket_path` to a per-instance UDS
    // under the instance's own dev dir (the manifest ships a hardcoded `/run/...` path that is
    // neither writable nor per-instance here).
    // Post-boot fallback staging, for any host that exposes no pre-start dev dir (mirrors
    // `dev::platform`'s own two-phase staging). A host covered pre-boot re-stages harmlessly.
    let dev_dirs: Vec<std::path::PathBuf> = handles.iter().map(|h| h.dev_dir.clone()).collect();
    dev::platform::stage_standalone_manifests(&standalone_sources, &dev_dirs, None)
        .context("stage standalone manifests")?;
    let mut spawned_standalones =
        dev::platform::spawn_standalones(&standalone_sources, &handles, &[], None);
    if !spawned_standalones.is_empty() {
        eprintln!(
            "✓ spawned {} standalone app process(es): {}",
            spawned_standalones.len(),
            spawned_standalones
                .iter()
                .map(|s| s.label.as_str())
                .collect::<Vec<_>>()
                .join(", "),
        );
    }

    // 3. Onboard (BIP39) + cross-seed peer IP pools.
    //
    // Advisory for the dev TUI, FATAL here: every probe authenticates with the
    // session file this step writes, so a harness that keeps going after a
    // failed onboarding can only die later — at `load_for_harness` below, with
    // "no agent session for 'alice' — did `harness up` onboarding run?", which
    // points at the wrong thing entirely. Abort with the actual HTTP error.
    let onboarding_failures = dev::agent::run_agent_setup(&handles, None, true);
    if !onboarding_failures.is_empty() {
        let detail = onboarding_failures
            .iter()
            .map(|(instance, error)| format!("  {instance}: {error}"))
            .collect::<Vec<_>>()
            .join("\n");
        anyhow::bail!(
            "onboarding failed — the harness cannot authenticate to the nodes it \
             just started:\n{detail}\n\n\
             A `No provider registered for capability '…'` message above means the \
             daemon came up without that capability's app. Two causes, in order of \
             likelihood:\n\
             1. `modules/` is missing the extracted node-app-* checkouts (the daemon \
             loads them from there via APT_APPS_DIR) — run `make bootstrap-apps`.\n\
             2. The app IS in `modules/` but its manifest.json was rejected, so the \
             host skipped it. Grep the daemon log for \
             `skipping malformed manifest` — the app name, whether it is critical, \
             and the parse error are all on that line. Note it logs under the \
             `node_app_host` target, so a directive-only RUST_LOG such as \
             `node_server=info` hides it; use `info,node_server=info` instead."
        );
    }

    // 4. Read the session files the agent step wrote, build state.
    // Derive the LDK peer address from the ACTUAL allocated ports
    // (`port_overrides`), not a recomputed `lane_offset` formula — once
    // `allocate_lane_ports` has shifted a lane past its documented base, the
    // formula alone is stale and would record the wrong peer address.
    let mut instances = Vec::new();
    for (i, profile) in profiles.iter().enumerate() {
        let name = profile.name.as_str();
        // `profiles` holds the BASE profiles; `host::for_mode` applied the lane rename to the
        // daemons it started, so the session the agent step just wrote is under the lane label.
        let lane = lane_name(name);
        let allocated = port_overrides[i];
        let p2p_port = allocated.map(|p| p.p2p).unwrap_or(profile.p2p_port);
        let ldk_addr = format!("127.0.0.1:{p2p_port}");
        let session = AgentSession::load_for_harness(&monorepo_path, &lane)
            .with_context(|| format!("load {lane} agent session"))?;
        let dev_dir = crate::commands::dev::host::monorepo::monorepo_dev_dir(
            &monorepo_path,
            &lane,
            None,
        )?;
        let session_path = AgentSession::file_path(&dev_dir, &lane);
        // The daemon's own PID, written by `MonorepoHost::ensure_running` to
        // `<instance-root>/daemon.pid` right after spawning. Read back here
        // so `InstanceState.pid` is a real, populated value instead of
        // always `None` — `ports::classify_holder`'s pid-recorded branch is
        // dead in practice otherwise, and a future `harness up` re-run for
        // this SAME checkout depends on it to recognize its own prior
        // daemon as `Ours` even if that daemon's `--env` argument were ever
        // to change shape.
        let pid = dev_dir
            .parent()
            .and_then(|env_dir| std::fs::read_to_string(env_dir.join("daemon.pid")).ok())
            .and_then(|s| s.trim().parse::<u32>().ok());
        instances.push(InstanceState {
            name: name.into(),
            session_path,
            base_url: session.base_url.clone(),
            ldk_addr,
            node_id: session.node_id.clone(),
            pid,
            client_node_ports: allocated,
        });
    }

    let mut state = HarnessState {
        created_at: now_iso8601(),
        monorepo_path: monorepo_path
            .canonicalize()
            .unwrap_or_else(|_| monorepo_path.clone()),
        bitcoind: BitcoindState {
            mode: format!("{bitcoind_mode:?}").to_lowercase(),
            rpc_url: btc.rpc_url.clone(),
            rpc_user: crate::commands::harness::bitcoind::RPC_USER.into(),
            container_id: btc.container_id.clone(),
        },
        instances,
        channel: None,
        supervisor_pid: Some(std::process::id()),
        client_node_instance: client_node.clone(),
        operation_mode,
        // `ensure_running()` (called via `h.ensure_running()` above, step 2)
        // already joined the PWA build handle before either daemon spawned —
        // if it had failed, `up` would have aborted with `?` back there and
        // never reached this point. This just surfaces WHICH outcome
        // (built vs skipped) for `harness status` to report (spec D6).
        pwa_dist_built: crate::commands::dev::host::monorepo::pwa_dist_build_outcome(),
    };

    // 4a. Open alice→bob channel if requested.
    if with_channel {
        let ch = open_channel_flow(&state, &btc, "alice", "bob", 100_000)?;
        state.channel = Some(ch);
    }

    // 4b. Start the shared operation-mode coordinator against the selected
    // instance. Its handle is held in scope until shutdown below — the
    // coordinator's polling loop observes the shared cancellation flag (via
    // `dev::shutdown_requested`), so teardown never blocks on the approval
    // timeout. `harness up` has no TUI, so `spawn(None)` — the coordinator
    // falls back to logging on stderr. Clone name+base_url out of `state` up
    // front (rather than re-resolving `selected_client_node` a second time
    // below) so the immutable borrow of `state` doesn't linger.
    let selected_instance = if operation_mode {
        let inst = selected_client_node(&state, client_node.as_deref())?
            .ok_or_else(|| anyhow::anyhow!("operation mode requires a client-node instance"))?;
        Some((inst.name.clone(), inst.base_url.clone()))
    } else {
        None
    };
    let _operation_mode_thread = if let Some((instance_name, _)) = &selected_instance {
        // `instance_name` came from `InstanceState`, which holds the base name — resolve it
        // back to the lane label the session was actually written under.
        let session = AgentSession::load_for_harness(&monorepo_path, &lane_name(instance_name))?;
        Some(dev::operation_mode::prepare(session)?.spawn(None))
    } else {
        None
    };

    // 5. Persist + announce readiness.
    let path = state.save()?;
    println!("{}", serde_json::to_string_pretty(&state)?);
    let client_node_line = match &selected_instance {
        Some((name, base_url)) => format!(" Client-node PWA ({name}): {base_url}."),
        None => String::new(),
    };
    eprintln!(
        "HARNESS READY — supervising alice+bob; state at {}.{client_node_line} \
         Send SIGTERM (or `node-app harness down`) to stop.",
        path.display()
    );

    // 6. Block as supervisor until SIGTERM/SIGINT. `hosts` stays alive in scope
    //    for the whole loop — dropping it would kill the daemons and abandon
    //    the drain threads that keep their piped stdio flowing.
    while !dev::shutdown_requested() {
        std::thread::sleep(Duration::from_millis(500));
    }

    // 7. Clean teardown (a preview of `harness down`): SIGTERM each daemon's
    //    process group, then stop the bitcoind container.
    eprintln!("harness: shutdown signal received — stopping alice+bob…");
    // Standalone apps are our child processes, not the daemons' — killing the hosts leaves them
    // orphaned, holding their per-instance UDS and their assigned port, which makes the NEXT
    // `harness up` fail in a way that looks nothing like a leaked process. Reap them first,
    // mirroring `dev::platform`'s own shutdown order.
    for s in spawned_standalones.iter_mut() {
        eprintln!("harness: killing standalone {}", s.label);
        let _ = s.child.kill();
        let _ = s.child.wait();
    }
    for h in &hosts {
        h.shutdown();
    }
    let _ = btc.stop();
    eprintln!("harness: teardown complete.");
    Ok(())
}

/// Fund alice on-chain, connect her to bob, open a channel, and wait until
/// the channel is usable.  Mirrors the `startWithChannel` sequence in
/// `tests/e2e/src/harness/test-harness.ts`.
///
/// Sequence:
///   1. Get a fresh on-chain address from `from` node.
///   2. Send 1 BTC to it via bitcoind → mine 6 blocks → sleep 3s (confirmations).
///   3. Connect `from` to `to` via `connect_peer`.
///   4. Open channel: capacity = `sats`, push = 10% (rounded down) of `sats`.
///   5. Mine 6 blocks → sleep 5s (funding tx confirmations + LDK chain monitor).
///   6. Poll `list_channels` every 2s (mine 1 block per tick) until
///      `is_usable || is_channel_ready`, or 120s deadline → bail.
pub fn open_channel_flow(
    state: &HarnessState,
    btc: &Bitcoind,
    from: &str,
    to: &str,
    sats: u64,
) -> Result<ChannelState> {
    let from_i = state.instance(from)?;
    let to_i = state.instance(to)?;

    let from_tok = AgentSession::read_token(&from_i.session_path)?;

    let client = AgentHttpClient::with_session(from_i.base_url.clone(), from_i.session_path.clone());

    // 1. Fund: get address, send 1 BTC, mine 6 confirmation blocks.
    eprintln!("harness: funding {from} on-chain (1 BTC)…");
    let addr = client.new_onchain_address(&from_tok)?;
    btc.send_to_address(&addr, 1.0)?;
    eprintln!("harness: mining 6 confirmation blocks…");
    btc.mine(6)?;
    std::thread::sleep(Duration::from_secs(3));

    // 2. Connect from → to.
    let peer_str = format!("{}@{}", to_i.node_id, to_i.ldk_addr);
    eprintln!("harness: connecting {from} → {to} ({peer_str})…");
    client.connect_peer(&from_tok, &peer_str)?;

    // 3. Open channel with 10% push to counterparty.
    let push_msat = (sats / 10) * 1_000;
    eprintln!(
        "harness: opening channel {from}→{to}: {sats} sats, pushing {} sats to {to}…",
        push_msat / 1_000
    );
    client.open_channel(&from_tok, &peer_str, sats, push_msat)?;

    // 4. Mine 6 blocks so the funding tx gets confirmed; give LDK time to react.
    eprintln!("harness: mining 6 channel confirmation blocks…");
    btc.mine(6)?;
    std::thread::sleep(Duration::from_secs(5));

    // 5. Poll until channel is usable (or timeout after 120s).
    eprintln!("harness: waiting for channel to become usable (120s deadline)…");
    let deadline = Instant::now() + Duration::from_secs(120);
    loop {
        let channels = client.list_channels(&from_tok)?;

        // channels is a JSON Value (array); check each element.
        let is_usable = if let Some(arr) = channels.as_array() {
            arr.iter().any(|ch| {
                ch.get("is_usable").and_then(|v| v.as_bool()).unwrap_or(false)
                    || ch.get("is_channel_ready").and_then(|v| v.as_bool()).unwrap_or(false)
            })
        } else {
            false
        };

        if is_usable {
            eprintln!("harness: channel {from}→{to} is usable");
            return Ok(ChannelState {
                from: from.into(),
                to: to.into(),
                capacity_sats: sats,
                status: "usable".into(),
            });
        }

        if Instant::now() >= deadline {
            anyhow::bail!(
                "channel {from}→{to} not usable within 120s; last: {channels}"
            );
        }

        // Mine 1 block per tick to keep LDK's chain monitor moving.
        let _ = btc.mine(1);
        std::thread::sleep(Duration::from_secs(2));
    }
}

/// Apps without which a freshly-booted node cannot complete onboarding, and so
/// cannot serve a single harness probe. Same pair `MonorepoHost` waits on after
/// the daemon's HTTP port opens. `ldk-node` is here (not just `builds` — its
/// staged `.dylib` next to a real `manifest.json`) because a missing/unbuilt
/// engine previously surfaced ~2 minutes into bring-up as an opaque `No
/// provider registered for capability 'core.lightning.node_id'` — gap 0b,
/// docs/superpowers/plans/2026-08-10-harness-browser-pairing.md.
const CRITICAL_APPS: [&str; 3] = ["device-registry", "core-storage", "ldk-node"];

/// Fail fast when the monorepo's `modules/` tree cannot serve the critical apps.
///
/// The monorepo daemon host points `APT_APPS_DIR` at `<monorepo>/modules`, and
/// the host registers an app's capabilities from its `manifest.json` — not from
/// the shared library next to it. A directory holding only a stale
/// `lib*.dylib`/`lib*.so` (what the retired `make builtin-apps` staged before
/// these apps were extracted into econ-v1/node-app-* repos) therefore registers
/// nothing, and onboarding dies on `No provider registered for capability
/// 'core.device.register'` two minutes into bring-up.
fn preflight_apps(monorepo_path: &std::path::Path) -> Result<()> {
    let modules_dir = monorepo_path.join("modules");
    let missing: Vec<&str> = CRITICAL_APPS
        .iter()
        .copied()
        .filter(|app| !modules_dir.join(app).join("manifest.json").is_file())
        .collect();

    if !missing.is_empty() {
        let ldk_note = if missing.contains(&"ldk-node") {
            "\nNote: modules/ldk-node is not built by `make bootstrap-apps` alone — after it \
             clones the repo, also run `make build-ldk-node` (features: swaps,cycles)."
        } else {
            ""
        };
        anyhow::bail!(
            "missing app manifest for: {} (looked under {}).\n\
             The daemon loads its apps from this directory, and without these it \
             cannot onboard — every harness probe would fail.\n\
             Run `make bootstrap-apps` to clone + build the extracted node-app-* \
             repos, then retry.{}\n\
             Note this preflight only checks that manifest.json EXISTS. A manifest \
             that is present but unparseable passes here and is dropped later by the \
             host, surfacing as `No provider registered for capability '…'` during \
             onboarding — see `skipping malformed manifest` in the daemon log.",
            missing.join(", "),
            modules_dir.display(),
            ldk_note,
        );
    }

    // Gap 0c/0e: materialize alice.env/bob.env from their .example templates
    // (with fresh per-worktree secrets) BEFORE bitcoind/daemons spend ~2
    // minutes booting, rather than discovering a missing/ungeneratable base
    // env deep inside MonorepoHost::ensure_running after that time is spent.
    for env_file_name in ["alice.env", "bob.env"] {
        let base_env_path = monorepo_path.join("system/server").join(env_file_name);
        if !base_env_path.exists() {
            crate::commands::dev::host::monorepo::materialize_base_env_from_example(
                &base_env_path,
            )
            .with_context(|| {
                format!(
                    "preflight: no base env file at {} and generating one from its \
                     .env.example template failed",
                    base_env_path.display()
                )
            })?;
        }
    }

    Ok(())
}

/// SIGTERM only the `node-server` processes this harness recorded.
///
/// Each instance runs with `--env <instance-root>/daemon.env`, and that path
/// carries the checkout+instance hash, so matching on it cannot reach another
/// checkout's daemons the way `pkill -f "node-server --env"` did.
#[cfg(unix)]
/// Delete this checkout's harness lock if the PID it names is gone.
///
/// Only ever removes a lock whose holder is dead: a LIVE holder means a real `harness up` owns
/// the checkout, and deleting its lock would let a second `up` in to delete its state — the very
/// failure the lock exists to prevent.
fn remove_stale_lock_for_cwd() {
    let Ok(cwd) = std::env::current_dir() else {
        return;
    };
    let Ok(path) = crate::commands::harness::state::lock_path(&cwd) else {
        return;
    };
    let holder = std::fs::read_to_string(&path)
        .ok()
        .and_then(|s| s.trim().parse::<u32>().ok());
    match holder {
        Some(pid) if crate::commands::harness::state::pid_is_alive(pid) => {}
        _ => {
            let _ = std::fs::remove_file(&path);
        }
    }
}

/// A node-server the harness started but has no state record for.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct OrphanedDaemon {
    pub(crate) pid: u32,
    pub(crate) env_path: std::path::PathBuf,
}

/// Harness-started `node-server` processes currently running ANYWHERE on
/// this box — every checkout, not just the caller's.
///
/// Identified by their `--env <cache>/node-app/monorepo-*/daemon.env` argument, which only the
/// dev/harness hosts generate. That specificity is the point: a bare match on `node-server` would
/// also sweep up a packaged install or a hand-run daemon, and `down` must never kill a process it
/// did not start.
///
/// Box-wide is deliberate here — this is raw discovery, not attribution. A DIFFERENT checkout's
/// daemon has an env path that ALSO contains `node-app/`, `/monorepo-`, and ends in `daemon.env`
/// (every harness/dev daemon's does), so this function alone cannot tell "ours" from "someone
/// else's". Callers MUST pass the result through `partition_orphaned_daemons` before touching any
/// of it — see that function's doc for why `down` used to get this wrong (#2221 sibling bug).
fn discover_orphaned_daemons() -> Vec<OrphanedDaemon> {
    let Ok(output) = std::process::Command::new("ps").args(["-eo", "pid=,command="]).output() else {
        return Vec::new();
    };
    let listing = String::from_utf8_lossy(&output.stdout);
    parse_orphaned_daemons(&listing)
}

/// Every `daemon.env` path THIS checkout could plausibly have produced —
/// every base instance name (`alice`/`bob`) crossed with plain/client-node
/// lane naming. An orphan's `--env` argument attributes to this checkout
/// only if it EXACTLY matches one of these, never by substring/prefix.
fn this_checkouts_daemon_env_paths(monorepo_path: &Path) -> Vec<PathBuf> {
    ["alice", "bob"]
        .iter()
        .flat_map(|base| {
            [false, true]
                .into_iter()
                .map(move |client_node| {
                    crate::commands::dev::host::monorepo::lane_instance_name(base, client_node)
                })
        })
        .filter_map(|instance| {
            crate::commands::dev::host::monorepo::monorepo_dev_dir(monorepo_path, &instance, None)
                .ok()
                .and_then(|dev_dir| dev_dir.parent().map(|env_dir| env_dir.join("daemon.env")))
        })
        .collect()
}

/// Split box-wide harness-shaped daemons (`discover_orphaned_daemons`) into
/// ones that belong to `monorepo_path` and ones that don't.
///
/// This is the fix for the sibling bug to #2221: `down`'s no-state-file
/// fallback (reached when a concurrent `up --clean` wipes THIS checkout's
/// state, or a SIGKILLed supervisor never wrote teardown) used to terminate
/// EVERY harness-shaped daemon on the box, because "looks harness-shaped"
/// (contains `node-app/`, `/monorepo-`, ends in `daemon.env`) is true for
/// every checkout's daemons, not just this one's.
///
/// SAFETY-CRITICAL ASYMMETRY (same rule as `ports::classify_port_holder`):
/// a daemon whose env path is not an EXACT match for one of THIS checkout's
/// own (instance × lane) env files goes to `foreign` — reported, never
/// touched. Attribution failing (e.g. `monorepo_dev_dir` erroring) means
/// `this_checkouts_daemon_env_paths` returns fewer entries, which can only
/// ever shrink `ours`, never grow it into a false positive.
fn partition_orphaned_daemons(
    all: Vec<OrphanedDaemon>,
    monorepo_path: &Path,
) -> (Vec<OrphanedDaemon>, Vec<OrphanedDaemon>) {
    let ours_paths = this_checkouts_daemon_env_paths(monorepo_path);
    all.into_iter().partition(|d| ours_paths.contains(&d.env_path))
}

/// Split out from the `ps` call so the matching rules are testable without spawning processes.
fn parse_orphaned_daemons(ps_listing: &str) -> Vec<OrphanedDaemon> {
    let mut found = Vec::new();
    for line in ps_listing.lines() {
        let line = line.trim_start();
        let Some((pid_str, command)) = line.split_once(char::is_whitespace) else {
            continue;
        };
        let Ok(pid) = pid_str.parse::<u32>() else {
            continue;
        };
        // The EXECUTABLE must be node-server — not merely a command line mentioning it. `down`
        // kills by PID, and a `ps` listing is full of processes that quote a daemon's command
        // without being one: the shell that launched the harness, a `grep` over the listing, an
        // editor with the path open. Matching on `contains` would send SIGKILL to those.
        let argv0 = command.split_whitespace().next().unwrap_or("");
        if !argv0.ends_with("node-server") {
            continue;
        }
        // The `--env` value, and only a harness/dev-generated one — a packaged install reads its
        // env from /etc and is not ours to stop.
        let Some(rest) = command.split("--env ").nth(1) else {
            continue;
        };
        let env_path = rest.split_whitespace().next().unwrap_or("");
        if !(env_path.contains("node-app/")
            && env_path.contains("/monorepo-")
            && env_path.ends_with("daemon.env"))
        {
            continue;
        }
        found.push(OrphanedDaemon { pid, env_path: std::path::PathBuf::from(env_path) });
    }
    found
}

fn kill_recorded_daemons(state: &HarnessState) {
    for inst in &state.instances {
        // session_path = <instance-root>/dev-apps/<name>-agent-session.json
        let Some(instance_root) = inst.session_path.parent().and_then(|p| p.parent()) else {
            continue;
        };
        let env_arg = instance_root.join("daemon.env");
        let _ = std::process::Command::new("pkill")
            .args(["-f", &format!("node-server --env {}", env_arg.display())])
            .status();
    }
}

fn now_iso8601() -> String {
    chrono::Utc::now().to_rfc3339()
}

// ─── Probe subcommands ────────────────────────────────────────────────────────

/// One check's outcome in a `harness status` report — never just an
/// `{"error": "..."}` blob standing in for "healthy" (spec D5 / AC-0: a
/// probe that finds one thing broken must not report success over the
/// top of it). `severity` is what makes an auth failure distinguishable
/// from an unreachable node without the caller having to string-match the
/// error text.
#[derive(Debug, Serialize)]
struct CheckResult {
    ok: bool,
    /// "ok" | "auth_failed" | "unreachable" | "http_error" | "protocol_error" | "error"
    severity: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    data: Option<serde_json::Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    error: Option<String>,
}

impl CheckResult {
    fn from_result(result: Result<serde_json::Value>) -> Self {
        match result {
            Ok(data) => Self { ok: true, severity: "ok", data: Some(data), error: None },
            Err(err) => {
                let severity = match err.downcast_ref::<ProbeError>() {
                    Some(ProbeError::Unauthorized { .. }) => "auth_failed",
                    Some(ProbeError::Unreachable { .. }) => "unreachable",
                    Some(ProbeError::Http { .. }) => "http_error",
                    Some(ProbeError::Protocol { .. }) => "protocol_error",
                    None => "error",
                };
                Self { ok: false, severity, data: None, error: Some(format!("{err:#}")) }
            }
        }
    }
}

/// `harness status` — balance/channels/peers health for each instance.
///
/// Every check is reported honestly: a failed check is `"ok": false` with a
/// `severity` (an expired/rejected token is `"auth_failed"`, a daemon that
/// can't be reached at all is `"unreachable"`) rather than being folded into
/// a healthy-looking `{"error": "..."}` field the way this used to work —
/// that swallowing is exactly what made a 401 on every check look like a
/// clean run (spec D5). The exit code reflects reality: non-zero whenever
/// any check across any instance failed, never success reported over a
/// failure.
///
/// Auth failures recover on their own when possible: each `AgentHttpClient`
/// here is bound to the instance's session file, so an expired access token
/// is refreshed via its `refresh_token` and the request retried once before
/// this function ever sees a failure to report (see `agent::client`'s
/// `with_session` / `authed_get` / `authed_post`). A check only shows
/// `"auth_failed"` when that recovery itself did not work.
pub fn status() -> Result<()> {
    let state = load_state()?;
    let mut instances = serde_json::Map::new();
    let mut all_healthy = true;
    let mut failures: Vec<String> = Vec::new();

    for inst in &state.instances {
        let token = AgentSession::read_token(&inst.session_path)
            .with_context(|| format!("read token for {}", inst.name))?;
        let client = AgentHttpClient::with_session(inst.base_url.clone(), inst.session_path.clone());

        let checks: [(&str, CheckResult); 3] = [
            ("balance", CheckResult::from_result(client.get_balance(&token))),
            ("channels", CheckResult::from_result(client.list_channels(&token))),
            ("peers", CheckResult::from_result(client.list_peers(&token))),
        ];

        let instance_healthy = checks.iter().all(|(_, c)| c.ok);
        if !instance_healthy {
            all_healthy = false;
            for (name, check) in &checks {
                if !check.ok {
                    failures.push(format!(
                        "{}.{name} [{}]: {}",
                        inst.name,
                        check.severity,
                        check.error.as_deref().unwrap_or("unknown error"),
                    ));
                }
            }
        }

        let mut checks_map = serde_json::Map::new();
        for (name, check) in checks {
            checks_map.insert(name.to_string(), serde_json::to_value(check)?);
        }
        instances.insert(inst.name.clone(), json!({
            "healthy": instance_healthy,
            "checks": serde_json::Value::Object(checks_map),
        }));
    }

    let report = json!({
        "healthy": all_healthy,
        "instances": serde_json::Value::Object(instances),
    });
    println!("{}", serde_json::to_string_pretty(&report)?);

    if all_healthy {
        Ok(())
    } else {
        anyhow::bail!(
            "harness status: {} check(s) failed:\n  {}",
            failures.len(),
            failures.join("\n  "),
        );
    }
}

/// `harness mine <blocks>` — mine N regtest blocks and print the new height.
pub fn mine(blocks: u32) -> Result<()> {
    let state = load_state()?;
    let btc = Bitcoind::from_state(&state.bitcoind);
    btc.mine(blocks)?;
    let height = btc.block_count()?;
    println!("{}", json!({ "mined": blocks, "height": height }));
    Ok(())
}

/// `harness fund <node> <btc>` — send BTC to a node's on-chain address,
/// mine 6 confirmations, and print the address + txid.
pub fn fund(node: &str, btc_amount: f64) -> Result<()> {
    let state = load_state()?;
    let inst = state.instance(node)?;
    let token = AgentSession::read_token(&inst.session_path)
        .with_context(|| format!("read token for {node}"))?;
    let client = AgentHttpClient::with_session(inst.base_url.clone(), inst.session_path.clone());

    let addr = client.new_onchain_address(&token)?;
    let btc_handle = Bitcoind::from_state(&state.bitcoind);
    let txid = btc_handle.send_to_address(&addr, btc_amount)?;
    btc_handle.mine(6)?;

    println!("{}", json!({
        "address": addr,
        "txid": txid,
        "confirmations": 6,
    }));
    Ok(())
}

/// `harness channel-open <from> <to> <sats>` — open a channel and persist the
/// result into the harness state.
pub fn channel_open(from: &str, to: &str, sats: u64) -> Result<()> {
    let mut state = load_state()?;
    let btc = Bitcoind::from_state(&state.bitcoind);
    let ch = open_channel_flow(&state, &btc, from, to, sats)?;
    let ch_json = serde_json::to_value(&ch)?;
    state.channel = Some(ch);
    state.save()?;
    println!("{}", serde_json::to_string_pretty(&ch_json)?);
    Ok(())
}

/// `harness invoke <node> <capability> <payload>` — invoke a capability on a node.
pub fn invoke(node: &str, capability: &str, payload_str: &str) -> Result<()> {
    let state = load_state()?;
    let inst = state.instance(node)?;
    let token = AgentSession::read_token(&inst.session_path)
        .with_context(|| format!("read token for {node}"))?;
    let client = AgentHttpClient::with_session(inst.base_url.clone(), inst.session_path.clone());

    let payload: serde_json::Value = serde_json::from_str(payload_str)
        .with_context(|| format!("parse payload JSON: {payload_str}"))?;

    let response = client.invoke_capability(&token, capability, payload)?;
    println!("{}", serde_json::to_string_pretty(&response)?);
    Ok(())
}

/// The resolved material a `harness pair-browser` invocation renders and
/// prints. Split out from `pair_browser` so instance resolution + rendering
/// (`build_pair_browser_output`) can be unit-tested against a fixture
/// `HarnessState` without touching the live harness-state file — `pair_browser`
/// itself is the thin, disk-touching wrapper, following the same split
/// `selected_client_node` already uses in this file for the same reason.
/// The instance-resolution and missing-session failure paths still need no
/// live daemon; only the success path (token validated live and possibly
/// refreshed) does, since [`ensure_live_owner_token`] makes a real HTTP call.
#[derive(Debug)]
struct PairBrowserOutput {
    base_url: String,
    browser_origin: String,
    owner_token: String,
    snippet: String,
    device_name: String,
}

/// `<instance-root>`, derived from `session_path` the same way
/// `kill_recorded_daemons` and the `harness pair` instance-root lookup do:
/// `session_path` is always `<instance-root>/dev-apps/<name>-agent-session.json`
/// (`AgentSession::file_path` called with `env_dir.join("dev-apps")` in
/// `host/monorepo.rs`), so its grandparent is the same `env_dir` that holds
/// `daemon.env` and `tls.json`.
fn instance_root(inst: &InstanceState) -> Option<&Path> {
    inst.session_path.parent().and_then(|p| p.parent())
}

/// Whether `<instance_root>/tls.json` — the exact path `daemon.env` points
/// `NODE_RUNTIME_TLS_STATE` at (see the `NODE_RUNTIME_TLS_STATE` pair in
/// `host/monorepo.rs`, written unconditionally for every instance) — reports
/// `"state": "ready"`.
///
/// This manifest is written by the RUNNING daemon itself at boot
/// (`publish_runtime_tls_state`,
/// `core/adapters-system/src/certificate/runtime_materialization.rs`), so it
/// reflects an actually-materialized certificate rather than which CLI flag
/// started the instance. Deliberately parsed as a bare JSON value (rather
/// than depending on `node-adapters-system`'s `RuntimeTlsState` type) so this
/// dev-tool binary doesn't pull in the server's full dependency graph for one
/// string field; `"ready"` is `RuntimeTlsStateKind::Ready`'s
/// `#[serde(rename_all = "snake_case")]` wire form and is pinned by
/// `runtime_materialization.rs`'s own tests.
///
/// Missing file, unreadable file, or malformed JSON all read as "not ready"
/// — this is a best-effort signal, not the sole source of truth (see
/// [`browser_origin`]'s fallback chain).
fn tls_manifest_ready(instance_root: &Path) -> bool {
    let Ok(contents) = std::fs::read_to_string(instance_root.join("tls.json")) else {
        return false;
    };
    let Ok(value) = serde_json::from_str::<serde_json::Value>(&contents) else {
        return false;
    };
    value.get("state").and_then(|s| s.as_str()) == Some("ready")
}

/// The HTTPS port this instance's daemon is actually configured to bind,
/// read from `<instance_root>/daemon.env`'s `HTTPS_SERVER_ADDRESS=host:port`
/// line. That key is written unconditionally for every instance (see the
/// `HTTPS_SERVER_ADDRESS` pair in `host/monorepo.rs`) — not gated on
/// `--client-node` — so it's available regardless of which lane started the
/// instance. `tls.json` itself carries no port, so this is the only source
/// for one once [`tls_manifest_ready`] says a certificate exists.
fn https_port_from_daemon_env(instance_root: &Path) -> Option<u16> {
    let contents = std::fs::read_to_string(instance_root.join("daemon.env")).ok()?;
    contents.lines().find_map(|line| {
        let (key, value) = line.split_once('=')?;
        if key.trim() != "HTTPS_SERVER_ADDRESS" {
            return None;
        }
        let (_, port) = value.trim().rsplit_once(':')?;
        port.trim().parse::<u16>().ok()
    })
}

/// The origin an operator should actually load in a browser before pasting
/// the snippet.
///
/// The PWA kernel's boot gate does not activate over plain HTTP — its own
/// trust probe (`GET /.well-known/client-node-origin`) is meaningless
/// without a real TLS context, and the PWA's CSP (`connect-src 'self' https:
/// ws: wss:`) blocks a plain-HTTP page from completing any fetch that
/// matters. `inst.base_url` (`http://127.0.0.1:<port>`) is therefore never
/// the right thing to tell an operator to open — UNLESS no HTTPS listener
/// exists at all, in which case it is returned honestly as the only
/// reachable origin and callers must warn accordingly.
///
/// Signal, in order of preference:
///
///  1. **Live TLS state** ([`tls_manifest_ready`] + [`https_port_from_daemon_env`]):
///     whether THIS instance's own runtime published a ready TLS manifest,
///     independent of which CLI flag brought it up. This is what makes a
///     plain (non-`--client-node`) instance that had TLS provisioned onto it
///     after boot report correctly — the previous version of this function
///     inferred HTTPS-or-not solely from `client_node_ports.is_some()`,
///     which is a launch-time INTENT flag, not an observation, and was wrong
///     for exactly that case (an operator-verified live incident: a plain
///     `harness up` instance that ended up serving real HTTPS on its
///     `HTTPS_SERVER_ADDRESS` port, which this function reported as
///     plain-HTTP-only and told the operator to needlessly rebuild).
///  2. `inst.client_node_ports.https`, the allocated HTTPS lane port for an
///     instance started with `--client-node` (`ports::allocate_lane_ports` —
///     it may have shifted past the documented base). Used only when (1) is
///     inconclusive (no resolvable instance root, unreadable/missing
///     manifest, or a manifest that isn't `"ready"`) — this is the
///     PREVIOUS/original signal, kept as a fallback because it reflects
///     intent rather than an observed listener, and `AUTO_SELF_SIGNED_TLS`
///     is turned on for that lane (`host/monorepo.rs`'s `self.client_node`
///     branch) so in practice it should already agree with (1) once the
///     daemon has finished booting.
///  3. Neither: `inst.base_url` (plain HTTP) — there is genuinely no known
///     HTTPS origin for this instance.
fn browser_origin(inst: &InstanceState) -> String {
    if let Some(root) = instance_root(inst) {
        if tls_manifest_ready(root) {
            if let Some(port) = https_port_from_daemon_env(root) {
                return format!("https://127.0.0.1:{port}");
            }
        }
    }
    match &inst.client_node_ports {
        Some(ports) => format!("https://127.0.0.1:{}", ports.https),
        None => inst.base_url.clone(),
    }
}

const PAIR_BROWSER_DEVICE_NAME: &str = "harness-browser";

/// Monotonic per-process disambiguator for [`unique_device_name`] — the
/// timestamp alone is millisecond-granular, so two invocations issued back
/// to back in a script could otherwise collide.
static PAIR_BROWSER_DEVICE_COUNTER: std::sync::atomic::AtomicU32 =
    std::sync::atomic::AtomicU32::new(0);

/// A fresh `harness-browser`-prefixed device name for one `pair-browser`
/// invocation. Every call used to target the SAME fixed `device_id`
/// (`PAIR_BROWSER_DEVICE_NAME` alone), even though the browser generates a
/// fresh Ed25519 identity on every run of the snippet — so a second
/// `pair-browser` invocation (a re-run after the first token went stale, a
/// second operator, a second browser) collided with the first pairing's
/// device row instead of registering its own. The `harness-browser` prefix
/// is kept so the device is still recognizable as harness-issued in
/// `GET /api/v2/did-devices`.
fn unique_device_name() -> String {
    let counter = PAIR_BROWSER_DEVICE_COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    format!(
        "{PAIR_BROWSER_DEVICE_NAME}-{}-{}-{counter}",
        std::process::id(),
        chrono::Utc::now().timestamp_millis(),
    )
}

/// Prove the cached owner token is actually live before it gets embedded in
/// a snippet, refreshing it (and persisting the refresh) via the existing
/// spec-D5 `with_session`/`authed_get` machinery if it has expired.
///
/// `GET /api/node/info` is used as the liveness probe: it is the cheapest
/// authed endpoint this client already has a typed call for
/// ([`AgentHttpClient::get_node_id`]), and going through `authed_get`
/// (rather than decoding the JWT's `exp` locally) is deliberate — the
/// live incident this guards against was a **server-side** session
/// invalidation (the daemon restarted, which invalidates the refresh token
/// even though the on-disk session file still looks fine and its `exp` may
/// not even have elapsed yet). A local `exp` check cannot see that; a real
/// round trip can, and it also tolerates ordinary clock skew between this
/// process and the daemon.
///
/// On success, re-reads the token from `session_path` rather than trusting
/// the token passed in: `authed_get` refreshes and persists to disk
/// in-place on a 401, so the on-disk copy is the freshest one regardless of
/// whether a refresh happened.
///
/// On failure — including the exact incident this exists to catch, where
/// the access token is dead AND `POST /api/auth/refresh` also comes back
/// `401 "Invalid refresh token"` because the daemon restarted since this
/// session was minted — returns an error naming what was attempted, what
/// was observed, and the remedy, per AC-0
/// (`docs/superpowers/plans/2026-08-10-harness-browser-pairing.md`).
fn ensure_live_owner_token(inst: &InstanceState, cached_token: &str) -> Result<String> {
    let client = AgentHttpClient::with_session(inst.base_url.clone(), inst.session_path.clone());
    match client.get_node_id(cached_token) {
        Ok(_) => AgentSession::read_token(&inst.session_path).with_context(|| {
            format!(
                "re-read {}'s token from {} after validating it",
                inst.name,
                inst.session_path.display()
            )
        }),
        Err(e) => Err(anyhow::anyhow!(
            "harness pair-browser: attempted to validate '{node}'s cached owner token via a \
             live GET /api/node/info call (auto-refreshing once on a 401); observed: {e:#}. The \
             harness session credentials for '{node}' are dead — most likely the daemon \
             restarted since this session was minted, which invalidates its refresh token \
             server-side even though the on-disk session file at {session_path} still looks \
             valid. Refusing to print a snippet carrying a token that could not be proven live. \
             Remedy: re-onboard this instance with `node-app harness up --clean` (bring the \
             stack down and back up fresh), then retry `node-app harness pair-browser {node}`.",
            node = inst.name,
            session_path = inst.session_path.display(),
        )),
    }
}

fn build_pair_browser_output(state: &HarnessState, node: &str) -> Result<PairBrowserOutput> {
    let inst = state.instance(node)?;
    let cached_token = AgentSession::read_token(&inst.session_path)
        .with_context(|| format!("read token for {node}"))?;
    let token = ensure_live_owner_token(inst, &cached_token)?;
    let device_name = unique_device_name();
    let origin = browser_origin(inst);
    let snippet =
        crate::commands::harness::snippet::render(&inst.node_id, &origin, &token, &device_name);
    Ok(PairBrowserOutput {
        base_url: inst.base_url.clone(),
        browser_origin: origin,
        owner_token: token,
        snippet,
        device_name,
    })
}

/// The accurate, non-overclaiming warning printed when [`browser_origin`]
/// could find no live HTTPS listener at all (it fell all the way back to the
/// plain-HTTP `base_url`). Split out from [`pair_browser`] so its exact
/// wording — in particular, that it states only the ONE verified remedy as
/// verified and flags the other as unconfirmed rather than inventing it — is
/// directly unit-testable without capturing process stderr.
fn no_https_listener_warning(node: &str, base_url: &str) -> String {
    format!(
        "harness: WARNING — no live HTTPS listener was found for '{node}' (checked its TLS \
         state manifest for a ready certificate, and found no `--client-node` HTTPS lane \
         either). The PWA kernel does NOT activate over plain HTTP — its boot-gate trust \
         probe (GET /.well-known/client-node-origin) requires a real HTTPS context — so \
         pasting this snippet at {base_url} is expected to fail the origin guard. Verified \
         remedy: bring this instance up with `harness up --client-node {node}`, which \
         provisions a real self-signed certificate for it. Provisioning TLS onto an \
         already-running, non-`--client-node` instance may also be possible (this harness has \
         observed that exact state on a live instance before), but no supported way to trigger \
         it from here is confirmed — treat that as unconfirmed, not a fix to rely on."
    )
}

/// `harness pair-browser <node> [--json]` — resolve `node`'s harness
/// instance and print an in-page JS snippet (spec D2,
/// `docs/superpowers/specs/2026-08-10-harness-browser-pairing-design.md`)
/// that pairs a real browser through the genuine client-device lifecycle,
/// carrying the instance's owner bearer token so the node self-approves
/// (`activate_for_token_owner`). This command performs no pairing itself and
/// no network I/O — all of that happens in the page once the snippet is
/// pasted into devtools at the instance's own origin.
///
/// Before rendering anything, [`build_pair_browser_output`] proves the
/// embedded token is actually live: [`ensure_live_owner_token`] makes a real
/// authenticated call, transparently refreshing (and persisting) an expired
/// access token via the same machinery `harness status` uses. If that
/// refresh also fails — the session itself is dead, e.g. after a daemon
/// restart invalidated it server-side — this returns `Err` and NOTHING is
/// printed to stdout: a caller must never receive a snippet carrying a
/// token that could not be proven to work.
///
/// stdout carries only the snippet (or, with `--json`, the JSON envelope
/// around it) — every diagnostic, including the live-credential warning,
/// goes to stderr so stdout stays paste-safe.
pub fn pair_browser(node: &str, json: bool) -> Result<()> {
    let state = load_state()?;
    let output = build_pair_browser_output(&state, node)?;

    eprintln!(
        "harness: pairing snippet for '{node}' — daemon API at {}",
        output.base_url
    );
    if output.browser_origin == output.base_url {
        // `browser_origin` fell back to the plain-HTTP `base_url`, which only
        // happens when it could find no live TLS signal at all: no readable
        // `tls.json` reporting `"state": "ready"` for this instance AND no
        // `--client-node` lane port allocated (see `browser_origin`'s doc
        // comment). This IS an accurate "no HTTPS" conclusion — it checked,
        // it didn't just infer from the launch flag.
        eprintln!("{}", no_https_listener_warning(node, &output.base_url));
    } else {
        eprintln!(
            "harness: open devtools at that EXACT origin ({}) — over HTTPS; the PWA kernel does \
             not activate over plain HTTP — and paste the snippet into the console",
            output.browser_origin
        );
    }
    eprintln!(
        "harness: WARNING — this snippet embeds a LIVE owner bearer token. Do not save it to a \
         file, paste it into a shared channel, or commit it anywhere."
    );

    if json {
        let payload = serde_json::json!({
            "base_url": output.base_url,
            "browser_origin": output.browser_origin,
            "owner_token": output.owner_token,
            "snippet": output.snippet,
            "device_name": output.device_name,
        });
        println!("{}", serde_json::to_string_pretty(&payload)?);
    } else {
        println!("{}", output.snippet);
    }

    Ok(())
}

/// `harness logs <node> [--tail]` — print (or tail) the daemon log for a node.
pub fn logs(node: &str, tail: bool) -> Result<()> {
    let state = load_state()?;
    let inst = state.instance(node)?;

    // The session file lives at `<instance-root>/dev-apps/<name>-agent-session.json`.
    // The daemon writes `daemon.log` at `<instance-root>/daemon.log`.
    // Walk up two levels: dev-apps → instance root.
    let instance_root = inst.session_path
        .parent()                       // dev-apps/
        .and_then(|p| p.parent())       // <instance-root>/
        .ok_or_else(|| anyhow::anyhow!("session_path has no grandparent"))?;
    let log_path = instance_root.join("daemon.log");

    if !log_path.exists() {
        anyhow::bail!("log not found: {}", log_path.display());
    }

    let content = std::fs::read_to_string(&log_path)
        .with_context(|| format!("read {}", log_path.display()))?;

    if tail {
        // Print last ~200 lines.
        let lines: Vec<&str> = content.lines().collect();
        let start = lines.len().saturating_sub(200);
        for line in &lines[start..] {
            println!("{}", line);
        }
    } else {
        print!("{}", content);
    }
    Ok(())
}

/// `harness down [--clean]` — stop the harness via the supervisor PID, or
/// best-effort pkill if no supervisor PID is stored.
pub fn down(clean: bool) -> Result<()> {
    let state = match HarnessState::load() {
        Ok(s) => s,
        Err(_) => {
            // No state file is NOT proof that nothing is running. A concurrent `up --clean`
            // deletes the shared per-checkout state, and a SIGKILLed supervisor never writes its
            // teardown — both leave live daemons behind with no record. Reporting "no running
            // harness" and exiting is how those leak: the operator believes the box is clean
            // while node-servers still hold 3001/3301/4731/…, and the NEXT `up` fails on a bound
            // port with no hint as to why. So look for them directly before answering.
            // Unconditionally, before the no-orphans early return: a SIGKILLed supervisor leaves
            // a lock its `Drop` never removed, and that outlives the daemons it was guarding.
            remove_stale_lock_for_cwd();

            // `down` takes no `--monorepo-path`, so — exactly like `resolve_state_path` — the
            // current directory IS this invocation's checkout identity.
            let cwd = std::env::current_dir().context("resolve current directory")?;
            let all = discover_orphaned_daemons();
            let (orphans, foreign) = partition_orphaned_daemons(all, &cwd);

            // SAFETY-CRITICAL ASYMMETRY (see `ports::classify_port_holder` and
            // `partition_orphaned_daemons`): a daemon that looks harness-shaped but does not
            // attribute to THIS checkout is reported, never touched — this is the fix for the
            // sibling bug to #2221, where the fallback below used to terminate every
            // harness-shaped daemon on the box regardless of which checkout started it.
            if !foreign.is_empty() {
                eprintln!(
                    "harness down: {} daemon-shaped process(es) look harness-generated but do \
                     not belong to this checkout ({}) — left alone, not terminated:\n{}",
                    foreign.len(),
                    cwd.display(),
                    foreign
                        .iter()
                        .map(|d| format!("  pid {} env {}", d.pid, d.env_path.display()))
                        .collect::<Vec<_>>()
                        .join("\n"),
                );
            }

            if orphans.is_empty() {
                println!("{}", json!({ "stopped": false, "reason": "no running harness" }));
                return Ok(());
            }
            eprintln!(
                "harness down: no state file, but {} orphaned daemon(s) belonging to this \
                 checkout are still running — stopping them",
                orphans.len(),
            );
            for orphan in &orphans {
                eprintln!("harness down: SIGTERM {} ({})", orphan.pid, orphan.env_path.display());
                #[cfg(unix)]
                // SAFETY: `kill` is safe for any PID; ESRCH on a dead process is ignored.
                unsafe {
                    libc::kill(orphan.pid as libc::pid_t, libc::SIGTERM);
                }
            }
            // Give them the same graceful window a supervised shutdown gets, then escalate.
            let deadline = Instant::now() + Duration::from_secs(40);
            loop {
                std::thread::sleep(Duration::from_millis(300));
                let alive: Vec<&OrphanedDaemon> = orphans
                    .iter()
                    .filter(|o| crate::commands::harness::state::pid_is_alive(o.pid))
                    .collect();
                if alive.is_empty() {
                    break;
                }
                if Instant::now() >= deadline {
                    for o in alive {
                        eprintln!("harness down: {} did not exit within 40s — SIGKILL", o.pid);
                        #[cfg(unix)]
                        // SAFETY: as above.
                        unsafe {
                            libc::kill(o.pid as libc::pid_t, libc::SIGKILL);
                        }
                    }
                    break;
                }
            }
            // The container is named, so it can be reclaimed without any state to read.
            let _ = std::process::Command::new("docker")
                .args(["rm", "-f", crate::commands::harness::bitcoind::CONTAINER_NAME])
                .output();
            println!(
                "{}",
                json!({
                    "stopped": true,
                    "reason": "recovered orphaned daemons (no state file)",
                    "daemons": orphans.iter().map(|o| o.pid).collect::<Vec<_>>(),
                }),
            );
            return Ok(());
        }
    };

    #[cfg(unix)]
    {
        if let Some(pid) = state.supervisor_pid {
            eprintln!("harness down: sending SIGTERM to supervisor PID {pid}");
            // SAFETY: kill() is always safe to call; the PID might not exist, which
            // just returns ESRCH.
            let rc = unsafe { libc::kill(pid as libc::pid_t, libc::SIGTERM) };
            if rc != 0 {
                // errno is not portable to read inline; just check if the process
                // still exists by probing with signal 0.
                let still_alive = unsafe { libc::kill(pid as libc::pid_t, 0) } == 0;
                if !still_alive {
                    eprintln!("harness down: supervisor {pid} is no longer running");
                } else {
                    eprintln!("harness down: kill({pid}, SIGTERM) returned non-zero");
                }
            } else {
                // Poll up to 40s for the supervisor to exit.
                // MonorepoHost::shutdown() is sequential per host (daemon ~10s + UI
                // ~5s each), so alice+bob worst-case is ~30s.  Give an extra 10s
                // margin before we escalate.
                let deadline = Instant::now() + Duration::from_secs(40);
                let mut timed_out = false;
                loop {
                    std::thread::sleep(Duration::from_millis(300));
                    let probe = unsafe { libc::kill(pid as libc::pid_t, 0) };
                    if probe != 0 {
                        // ESRCH = no such process → supervisor is gone.
                        break;
                    }
                    if Instant::now() >= deadline {
                        eprintln!(
                            "harness down: supervisor {pid} did not exit within 40s — \
                             escalating to SIGKILL"
                        );
                        timed_out = true;
                        break;
                    }
                }

                if timed_out {
                    // SIGKILL the supervisor so it cannot continue leaking daemons.
                    // SAFETY: kill() is always safe; ESRCH is ignored.
                    unsafe { libc::kill(pid as libc::pid_t, libc::SIGKILL) };
                    // Best-effort: also kill the node-server processes this
                    // supervisor spawned. Matched on each instance's own
                    // --env path (unique per checkout+instance) — a bare
                    // `pkill -f "node-server --env"` would take down every
                    // other checkout's daemons on the box too.
                    kill_recorded_daemons(&state);
                }
            }
        } else {
            // Stale state without supervisor PID — best-effort cleanup.
            eprintln!("harness down: no supervisor_pid in state, falling back to best-effort teardown");
            kill_recorded_daemons(&state);
        }
    }

    // Always stop the bitcoind container, regardless of supervisor state.
    // The supervisor's clean-teardown path stops it too, but if the supervisor
    // was already dead (SIGTERM errored / confirmed gone) or failed to exit
    // within the poll window, that stop never ran and the container would leak.
    // Stopping an already-stopped or absent container is a harmless ignored error.
    if let Some(id) = &state.bitcoind.container_id {
        // `.output()`, not `.status()`: on the common path the supervisor's own
        // teardown already stopped this `--rm` container, so docker writes
        // "No such container: <id>" to stderr. That is the expected outcome
        // here, not something to show the operator mid-teardown.
        let _ = std::process::Command::new("docker").args(["stop", id]).output();
    }

    // Optional clean: wipe per-instance data files.
    if clean {
        // Determine the cache root so we never wipe outside it.
        let cache_root = state_path(&state.monorepo_path)
            .ok()
            .and_then(|p| {
                // Walk up to find the `node-app` ancestor.
                let mut cur = p.parent()?.to_path_buf();
                loop {
                    if cur.file_name().map(|n| n == "node-app").unwrap_or(false) {
                        return Some(cur);
                    }
                    if !cur.pop() {
                        return None;
                    }
                }
            });

        for inst in &state.instances {
            // session_path = <instance-root>/dev-apps/<name>-agent-session.json
            // Data files (dev.db, lightning.db, ldk_data) live at <instance-root>.
            let instance_root = match inst.session_path
                .parent()                  // dev-apps/
                .and_then(|p| p.parent())  // <instance-root>/
            {
                Some(d) => d.to_path_buf(),
                None => continue,
            };

            // Canonicalize so that a path containing `..` components cannot
            // lexically pass the cache-root guard.  The directory must exist
            // at this point (it held the session file), so canonicalize()
            // should succeed; fall back to the raw path if it doesn't.
            let instance_root = instance_root.canonicalize().unwrap_or(instance_root);

            // Guard: only wipe if the path is under the cache root.
            let under_cache = cache_root.as_ref().map(|root| instance_root.starts_with(root)).unwrap_or(false);
            if !under_cache {
                eprintln!(
                    "harness down: skipping clean for {} (not under cache root)",
                    instance_root.display()
                );
                continue;
            }

            // Wipe database files.
            for name in ["dev.db", "dev.db-shm", "dev.db-wal", "lightning.db"] {
                let _ = std::fs::remove_file(instance_root.join(name));
            }

            // Wipe LDK data directories.
            for name in ["ldk_data", "ldk_node_data", "ldk_node_data_backup"] {
                let p = instance_root.join(name);
                if p.is_dir() {
                    let _ = std::fs::remove_dir_all(&p);
                }
            }
        }
    }

    // Remove the state file.
    let _ = std::fs::remove_file(resolve_state_path()?);

    println!("{}", json!({ "stopped": true, "cleaned": clean }));
    Ok(())
}

/// `harness pay <from> <to> <sats>` — `to` creates an invoice; `from` pays it.
///
/// Flow:
///   1. `to` creates a BOLT11 invoice for `sats * 1000` msat.
///   2. `from` sends the payment.
///   3. If the pay response is `status == "pending"` (the LDK capability
///      returned before the preimage was extracted), poll
///      `core.lightning.get_payment_status` on `from` up to ~30s.
///   4. Print `{ invoice, status, payment_hash, preimage }` and return.
///
/// A "no route / no channel" failure exits non-zero with a message pointing
/// at `harness channel-open`.
pub fn pay(from: &str, to: &str, sats: u64) -> Result<()> {
    let state = load_state()?;
    let from_i = state.instance(from)?;
    let to_i = state.instance(to)?;

    let from_tok = AgentSession::read_token(&from_i.session_path)
        .with_context(|| format!("read token for {from}"))?;
    let to_tok = AgentSession::read_token(&to_i.session_path)
        .with_context(|| format!("read token for {to}"))?;

    let from_client = AgentHttpClient::with_session(from_i.base_url.clone(), from_i.session_path.clone());
    let to_client = AgentHttpClient::with_session(to_i.base_url.clone(), to_i.session_path.clone());

    // 1. `to` creates an invoice.
    let bolt11 = to_client
        .create_invoice(&to_tok, sats * 1_000, "harness pay")
        .with_context(|| format!("{to} create_invoice failed"))?;

    // 2. `from` pays the invoice.
    let pay_resp = from_client
        .pay_invoice(&from_tok, &bolt11)
        .map_err(|e| {
            let msg = e.to_string();
            // Detect "no route" or "channel" errors and hint the user.
            if msg.to_lowercase().contains("route")
                || msg.to_lowercase().contains("channel")
                || msg.to_lowercase().contains("liquidity")
                || msg.to_lowercase().contains("no path")
            {
                anyhow::anyhow!(
                    "payment failed — no usable route/channel: {msg}\n\
                     hint: run `node-app harness channel-open {from} {to} 100000` first"
                )
            } else {
                anyhow::anyhow!("pay_invoice failed: {msg}")
            }
        })?;

    let payment_hash = pay_resp
        .get("payment_hash")
        .and_then(|v| v.as_str())
        .unwrap_or("")
        .to_string();

    let initial_status = pay_resp
        .get("status")
        .and_then(|v| v.as_str())
        .unwrap_or("unknown")
        .to_string();

    let initial_preimage = pay_resp
        .get("preimage")
        .and_then(|v| v.as_str())
        .map(str::to_owned);

    // 3. If still pending, poll get_payment_status up to ~30s.
    let (final_status, final_preimage) = if initial_status == "pending"
        && !payment_hash.is_empty()
    {
        eprintln!("harness pay: payment pending — polling status (30s deadline)…");
        let deadline = Instant::now() + Duration::from_secs(30);
        let mut status = initial_status.clone();
        let mut preimage = initial_preimage.clone();

        loop {
            std::thread::sleep(Duration::from_millis(500));

            match from_client.invoke_capability(
                &from_tok,
                "core.lightning.get_payment_status",
                json!({ "payment_hash": payment_hash }),
            ) {
                Ok(v) => {
                    status = v
                        .get("status")
                        .and_then(|s| s.as_str())
                        .unwrap_or("unknown")
                        .to_string();
                    preimage = v
                        .get("preimage")
                        .and_then(|p| p.as_str())
                        .map(str::to_owned);

                    if status == "succeeded" || status == "failed" {
                        break;
                    }
                }
                Err(e) => {
                    eprintln!("harness pay: get_payment_status error: {e}");
                }
            }

            if Instant::now() >= deadline {
                eprintln!("harness pay: payment still pending after 30s");
                break;
            }
        }

        (status, preimage)
    } else {
        (initial_status, initial_preimage)
    };

    // 4. Print result.
    println!(
        "{}",
        serde_json::to_string_pretty(&json!({
            "invoice": bolt11,
            "status": final_status,
            "payment_hash": payment_hash,
            "preimage": final_preimage,
        }))?
    );

    if !matches!(final_status.as_str(), "succeeded" | "settled") {
        anyhow::bail!(
            "payment did not settle (status: {final_status}); \
             check that a usable channel exists: `node-app harness channel-open {from} {to} 100000`"
        );
    }

    Ok(())
}

/// `harness l402 <from> <to> <route> <payload>` — drive a cross-node L402 paid
/// call where `from`'s daemon proxies to `to` via its L402HttpClient.
///
/// `from` calls `route` on its OWN daemon (authenticated).  Internally the
/// daemon's transport layer looks up `to` in the IP pool and sends the request
/// to `to`'s daemon.  If `to` requires payment, alice's L402HttpClient
/// auto-settles using the channel and retries.
///
/// Outcome:
///   - 200 → `{ "route", "settled": true, "response": … }` + exit 0.
///   - 402 or unconfigured route → `{ "route", "settled": false, "hint": "…" }`
///     + exit non-zero (soft outcome — dev env may have no paid route).
pub fn l402(from: &str, to: &str, route: &str, payload_str: &str) -> Result<()> {
    let state = load_state()?;
    let from_i = state.instance(from)?;
    // Validate `to` is a known instance (used for the hint message only;
    // actual routing is via the IP pool registered during `harness up`).
    let _to_i = state.instance(to)?;

    let from_tok = AgentSession::read_token(&from_i.session_path)
        .with_context(|| format!("read token for {from}"))?;

    let payload: serde_json::Value = serde_json::from_str(payload_str)
        .with_context(|| format!("parse payload JSON: {payload_str}"))?;

    // Force the CROSS-NODE path: without `execution_preference: "remote"`,
    // `from`'s daemon handles the call LOCALLY (no L402 proxy to `to`, no
    // cross-node settlement) and a 200 would be a false positive for a probe
    // named "l402". Inject the field if the payload is a JSON object, without
    // overwriting a caller-supplied value.
    let mut payload = payload;
    if let Some(obj) = payload.as_object_mut() {
        obj.entry("execution_preference".to_string())
            .or_insert(serde_json::Value::String("remote".to_string()));
    }

    let from_client = AgentHttpClient::new(from_i.base_url.clone());

    let (status_code, body) = from_client
        .post_raw_with_status(&from_tok, route, &payload)
        .with_context(|| format!("POST {route} on {from}"))?;

    if status_code == 200 {
        println!(
            "{}",
            serde_json::to_string_pretty(&json!({
                "route": route,
                "settled": true,
                "note": "settled=true means the remote route returned 200; \
                         in a dev env with no paid route configured the daemon \
                         may handle locally",
                "response": body,
            }))?
        );
        Ok(())
    } else {
        // Soft outcome: 402 means no channel / no paid route; other 4xx/5xx
        // also treated as soft so the harness doesn't thrash.
        let hint = if status_code == 402 {
            format!(
                "received 402 — no channel or budget / no paid route configured \
                 between {from} and {to}; \
                 open a channel first: `node-app harness channel-open {from} {to} 100000`"
            )
        } else {
            format!(
                "route returned HTTP {status_code} (may be unconfigured or require \
                 additional setup)"
            )
        };

        println!(
            "{}",
            serde_json::to_string_pretty(&json!({
                "route": route,
                "settled": false,
                "http_status": status_code,
                "hint": hint,
                "body": body,
            }))?
        );

        anyhow::bail!("l402 probe: route {route} did not return 200 (got {status_code})");
    }
}

// ─── Internal helper ──────────────────────────────────────────────────────────

fn load_state() -> Result<HarnessState> {
    HarnessState::load().map_err(|_| {
        anyhow::anyhow!(
            "no harness state found — run `node-app harness up` first"
        )
    })
}

/// Resolve the harness instance selected for the client-node PWA lane.
///
/// `None` (no `--client-node` flag) means no instance is selected — this is
/// not an error. `Some(name)` must match a known instance in `state`; an
/// unknown name fails closed (mirrors `HarnessState::instance`'s error text)
/// rather than silently falling back to a default instance.
/// Every `modules/<app>/` directory holding a `manifest.json`.
///
/// The harness's daemons discover their built-in apps from the checkout's `modules/` tree (the
/// same directory the packaged build installs from), so that tree — not `~/.cache/node-app/deps`,
/// which only `node-app dev`'s dependency staging populates — is the right source for the
/// standalone apps to stage and spawn. `spawn_standalones` filters to `app_type: "standalone"`
/// itself, so handing it every module directory is correct and keeps this free of a second,
/// drifting list of which apps happen to be standalone today.
fn module_app_dirs(monorepo_path: &std::path::Path) -> Vec<std::path::PathBuf> {
    let modules = monorepo_path.join("modules");
    let Ok(entries) = std::fs::read_dir(&modules) else {
        return Vec::new();
    };
    let mut dirs: Vec<std::path::PathBuf> = entries
        .filter_map(|e| e.ok())
        .map(|e| e.path())
        .filter(|p| p.join("manifest.json").is_file())
        .collect();
    // Stable order so staging/spawn logs are reproducible run to run.
    dirs.sort();
    dirs
}

fn selected_client_node<'a>(
    state: &'a HarnessState,
    selected: Option<&str>,
) -> Result<Option<&'a InstanceState>> {
    match selected {
        None => Ok(None),
        Some(name) => state.instance(name).map(Some),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::commands::harness::state::BitcoindState;
    use crate::commands::dev::agent::session::AgentSession;
    use crate::commands::dev::host::monorepo::{lane_instance_name, monorepo_dev_dir};

    /// Regression: `harness up --client-node` onboarded `alice-pwa` and then died loading
    /// `alice`'s session, because the lane rename reached the daemons (via `MonorepoHost::new`)
    /// but not the harness's own filesystem paths. The two labels must not resolve to the same
    /// session file, and the harness must address the lane one.
    ///
    /// Asserted on paths rather than a live `up`: the failure was purely one of path derivation,
    /// and pinning it here needs no daemon, no bitcoind and no onboarding.
    #[test]
    fn client_node_lane_resolves_a_different_session_path_than_the_base_instance() {
        let monorepo = std::path::Path::new("/tmp/monorepo");

        let base = lane_instance_name("alice", false);
        let lane = lane_instance_name("alice", true);
        assert_eq!(base, "alice");
        assert_eq!(lane, "alice-pwa");

        let base_dir = monorepo_dev_dir(monorepo, &base, None).expect("base dev dir");
        let lane_dir = monorepo_dev_dir(monorepo, &lane, None).expect("lane dev dir");
        // The cache dir is hashed over (monorepo_path, instance_name), so the rename MUST move
        // the whole instance root — this is what made the mismatch silent rather than a missing
        // file in a shared directory.
        assert_ne!(
            base_dir, lane_dir,
            "client-node lane must get its own instance root, not share the base instance's",
        );

        let base_session = AgentSession::file_path(&base_dir, &base);
        let lane_session = AgentSession::file_path(&lane_dir, &lane);
        assert_ne!(base_session, lane_session);
        assert_eq!(
            lane_session.file_name().and_then(|n| n.to_str()),
            Some("alice-pwa-agent-session.json"),
        );
    }

    /// The base name stays the harness's user-facing vocabulary: `harness pay alice bob` and
    /// `--client-node alice` must keep working while the lane suffix stays an on-disk detail.
    #[test]
    fn instance_state_keeps_the_base_name_in_client_node_mode() {
        let harness_state = client_node_state();
        let selected = selected_client_node(&harness_state, Some("alice"))
            .expect("selection")
            .expect("some instance");
        assert_eq!(selected.name, "alice");
        assert_eq!(
            lane_instance_name(&selected.name, true),
            "alice-pwa",
            "the lane label is derived on demand, never stored in InstanceState",
        );
    }

    /// Regression: `harness down` used to answer "no running harness" whenever the state file was
    /// absent — which is exactly the situation a concurrent `up --clean` (it deletes the shared
    /// per-checkout state) or a SIGKILLed supervisor leaves behind, with live daemons still
    /// holding their ports. The recovery path finds them by their harness-generated `--env` path.
    #[test]
    fn orphan_discovery_matches_harness_daemons_only() {
        let listing = "\
  36775 ./target/debug/node-server --env /Users/x/.cache/node-app/monorepo-9c9913da/daemon.env
  40746 ./target/debug/node-server --env /Users/x/.cache/node-app/monorepo-82b77b5f/daemon.env
";
        let found = parse_orphaned_daemons(listing);
        assert_eq!(found.len(), 2);
        assert_eq!(found[0].pid, 36775);
        assert_eq!(found[1].pid, 40746);
        assert!(found[0].env_path.ends_with("daemon.env"));
    }

    /// `down` must never kill a node-server it did not start. A packaged install reads its env
    /// from `/etc`, and the shell line that launched the harness quotes the daemon's own command —
    /// neither is a daemon this harness owns.
    #[test]
    fn orphan_discovery_skips_foreign_and_launcher_processes() {
        let listing = "\
  111 /usr/bin/node-server --env /etc/node/daemon.env
  222 /bin/zsh -c node-app harness down --clean
  333 /usr/lib/node/node-server
  444 ugrep node-server --env /Users/x/.cache/node-app/monorepo-1/daemon.env
";
        let found = parse_orphaned_daemons(listing);
        let pids: Vec<u32> = found.iter().map(|o| o.pid).collect();
        assert!(!pids.contains(&111), "packaged install must not be swept up");
        assert!(!pids.contains(&222), "the launcher shell must not be swept up");
        assert!(!pids.contains(&333), "a daemon with no --env is not ours to judge");
        assert!(!pids.contains(&444), "a `harness down` command line must not match itself");
    }

    /// The sibling bug to #2221: `down`'s no-state-file fallback used to treat EVERY
    /// harness-shaped daemon on the box as fair game, regardless of which checkout started it
    /// (a DIFFERENT checkout's daemon also has an env path containing `node-app/`, `/monorepo-`,
    /// ending in `daemon.env` — the substring check alone can't tell them apart). A daemon whose
    /// env path names a different checkout must never be selected for termination.
    #[test]
    fn partition_orphaned_daemons_leaves_a_different_checkouts_daemon_alone() {
        let mine = std::path::Path::new("/tmp/checkout-mine");
        let theirs = std::path::Path::new("/tmp/checkout-theirs");

        let mine_env = monorepo_dev_dir(mine, &lane_instance_name("alice", false), None)
            .unwrap()
            .parent()
            .unwrap()
            .join("daemon.env");
        let theirs_env = monorepo_dev_dir(theirs, &lane_instance_name("bob", true), None)
            .unwrap()
            .parent()
            .unwrap()
            .join("daemon.env");

        let all = vec![
            OrphanedDaemon { pid: 111, env_path: mine_env },
            OrphanedDaemon { pid: 222, env_path: theirs_env },
        ];

        let (ours, foreign) = partition_orphaned_daemons(all, mine);
        assert_eq!(ours.len(), 1);
        assert_eq!(ours[0].pid, 111);
        assert_eq!(
            foreign.len(),
            1,
        );
        assert_eq!(
            foreign[0].pid, 222,
            "a different checkout's daemon must never be selected for termination"
        );
    }

    #[test]
    fn this_checkouts_daemon_env_paths_covers_every_instance_and_lane() {
        let monorepo = std::path::Path::new("/tmp/some-checkout");
        let paths = this_checkouts_daemon_env_paths(monorepo);
        assert_eq!(paths.len(), 4, "alice/bob x plain/client-node = 4 possible env files");
        for p in &paths {
            assert!(p.ends_with("daemon.env"));
        }
        // All four must be distinct — a collision would mean two different lanes silently
        // share one env file (and therefore attribution could not tell them apart).
        let mut sorted = paths.clone();
        sorted.sort();
        sorted.dedup();
        assert_eq!(sorted.len(), 4);
    }

    /// `state()` with the client-node marker set, mirroring what `up` persists in that mode.
    fn client_node_state() -> HarnessState {
        let mut s = state();
        s.client_node_instance = Some("alice".into());
        s
    }

    fn state() -> HarnessState {
        HarnessState {
            created_at: "2026-07-01T00:00:00Z".into(),
            monorepo_path: "/tmp/monorepo".into(),
            bitcoind: BitcoindState {
                mode: "docker".into(),
                rpc_url: "http://127.0.0.1:18443".into(),
                rpc_user: "polaruser".into(),
                container_id: None,
            },
            instances: vec![
                InstanceState {
                    name: "alice".into(),
                    session_path: "/tmp/alice-agent-session.json".into(),
                    base_url: "http://127.0.0.1:3001".into(),
                    ldk_addr: "127.0.0.1:9937".into(),
                    node_id: "03aa".into(),
                    pid: None,
                    client_node_ports: None,
                },
                InstanceState {
                    name: "bob".into(),
                    session_path: "/tmp/bob-agent-session.json".into(),
                    base_url: "http://127.0.0.1:3002".into(),
                    ldk_addr: "127.0.0.1:9938".into(),
                    node_id: "03bb".into(),
                    pid: None,
                    client_node_ports: None,
                },
            ],
            channel: None,
            supervisor_pid: None,
            client_node_instance: None,
            operation_mode: false,
            pwa_dist_built: None,
        }
    }

    #[test]
    fn no_client_node_selection_returns_none() {
        assert!(selected_client_node(&state(), None).unwrap().is_none());
    }

    #[test]
    fn alice_selection_returns_alice() {
        let harness_state = state();
        let selected = selected_client_node(&harness_state, Some("alice"))
            .unwrap()
            .unwrap();
        assert_eq!(selected.name, "alice");
    }

    #[test]
    fn unknown_selection_fails_closed() {
        let harness_state = state();
        let error = selected_client_node(&harness_state, Some("carol")).unwrap_err();
        assert!(error.to_string().contains("unknown instance"));
    }

    /// Build an `InstanceState` whose `session_path` resolves (via
    /// `instance_root`) to `root` — i.e.
    /// `root/dev-apps/<name>-agent-session.json`, matching the real layout
    /// `host/monorepo.rs` writes (`AgentSession::file_path(env_dir.join(
    /// "dev-apps"), name)`) — so tests can control exactly what
    /// `browser_origin` finds at `root/tls.json` and `root/daemon.env`
    /// without touching any real harness state.
    fn instance_with_root(name: &str, root: &Path, base_url: &str) -> InstanceState {
        InstanceState {
            name: name.into(),
            session_path: root.join("dev-apps").join(format!("{name}-agent-session.json")),
            base_url: base_url.into(),
            ldk_addr: "127.0.0.1:9937".into(),
            node_id: "03aa".into(),
            pid: None,
            client_node_ports: None,
        }
    }

    /// The exact case that was wrong before this fix: an instance with NO
    /// `--client-node` lane (`client_node_ports: None`) whose runtime
    /// nonetheless published a ready TLS manifest (e.g. TLS was provisioned
    /// onto it after boot, independent of the launch flag). The old
    /// `browser_origin` inferred HTTPS-or-not solely from
    /// `client_node_ports.is_some()` and would have reported the plain-HTTP
    /// `base_url` here — wrongly, since a real HTTPS listener exists on
    /// `HTTPS_SERVER_ADDRESS`'s port.
    #[test]
    fn browser_origin_reports_the_https_origin_for_a_tls_ready_instance_without_a_client_node_lane()
    {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(
            dir.path().join("daemon.env"),
            "SERVER_ADDRESS=0.0.0.0:3001\nHTTPS_SERVER_ADDRESS=0.0.0.0:4431\n",
        )
        .expect("write daemon.env");
        std::fs::write(
            dir.path().join("tls.json"),
            r#"{"schema_version":1,"state":"ready","browser_redirect_enabled":true,"certificate_trusted":false}"#,
        )
        .expect("write tls.json");

        let inst = instance_with_root("alice", dir.path(), "http://127.0.0.1:3001");
        assert!(inst.client_node_ports.is_none());
        assert_eq!(browser_origin(&inst), "https://127.0.0.1:4431");
    }

    /// A `--client-node` instance (`client_node_ports: Some(..)`) still
    /// resolves to its allocated HTTPS lane port when there is no TLS
    /// manifest to read (e.g. the instance root can't be resolved, or the
    /// manifest is missing/not-yet-written) — the fallback path this
    /// function had before the fix, preserved as a fallback rather than
    /// removed.
    #[test]
    fn browser_origin_falls_back_to_the_allocated_https_lane_port_without_a_tls_manifest() {
        let dir = tempfile::tempdir().expect("tempdir");
        let mut inst = instance_with_root("alice", dir.path(), "http://127.0.0.1:3001");
        inst.client_node_ports = Some(ports::PortSet { http: 3301, https: 4431, p2p: 4331, ui: 3300 });
        assert_eq!(browser_origin(&inst), "https://127.0.0.1:4431");
    }

    #[test]
    fn browser_origin_falls_back_to_plain_http_base_url_without_any_tls_signal() {
        // No `--client-node` lane AND no readable/ready TLS manifest means
        // there is no known HTTPS origin at all — the plain `base_url` is
        // the honest, best-available fallback (see `browser_origin`'s doc
        // comment).
        let dir = tempfile::tempdir().expect("tempdir");
        let inst = instance_with_root("alice", dir.path(), "http://127.0.0.1:3001");
        assert!(inst.client_node_ports.is_none());
        assert_eq!(browser_origin(&inst), inst.base_url);
    }

    /// The warning printed when `browser_origin` genuinely found no HTTPS
    /// listener must state the no-HTTPS conclusion and the ONE verified
    /// remedy (`--client-node`) without asserting outcomes it hasn't
    /// verified: no bare "will fail" certainty, and the second (unverified)
    /// remedy must be explicitly labeled unconfirmed rather than presented
    /// as equally valid.
    #[test]
    fn no_https_listener_warning_does_not_overclaim() {
        let msg = no_https_listener_warning("alice", "http://127.0.0.1:3001");

        assert!(
            msg.contains("no live HTTPS listener"),
            "must state the no-HTTPS conclusion plainly: {msg}"
        );
        assert!(
            msg.contains("harness up --client-node alice"),
            "must name the one verified remedy: {msg}"
        );
        assert!(
            msg.contains("unconfirmed"),
            "the non-`--client-node` TLS-provisioning path must be labeled unconfirmed, not \
             asserted as a working remedy: {msg}"
        );
        assert!(
            !msg.contains("will fail"),
            "must not assert an unverified certain outcome (\"will fail\") — only \"expected \
             to fail\": {msg}"
        );
    }

    /// `pair_browser` itself resolves `HarnessState::load()` from disk, which
    /// depends on whatever harness (if any) happens to be running on the box
    /// this test executes on — exactly the kind of environment coupling the
    /// rest of this test module avoids (see `state()` below). Driving the
    /// unknown-instance rejection through `build_pair_browser_output` against
    /// a fixture state exercises the identical `state.instance(node)?` error
    /// path deterministically.
    #[test]
    fn pair_browser_rejects_an_unknown_instance() {
        let error = build_pair_browser_output(&state(), "nope").unwrap_err();
        assert!(format!("{error:#}").contains("nope"));
    }

    /// A known instance renders a snippet carrying that instance's base URL
    /// and device name, without needing a real on-disk agent session for the
    /// token (`AgentSession::read_token` reads `session_path`, which the
    /// fixture below points at a file that does not exist — so this also
    /// pins that a missing session surfaces as a named, contextual error
    /// rather than resolving successfully).
    #[test]
    fn pair_browser_reports_a_missing_session_by_name() {
        let error = build_pair_browser_output(&state(), "alice").unwrap_err();
        assert!(
            format!("{error:#}").contains("alice"),
            "a missing session file must name the instance it was read for"
        );
    }

    /// Every `pair-browser` invocation used to target the exact same
    /// `device_id` (`PAIR_BROWSER_DEVICE_NAME` alone), even though the
    /// browser generates a fresh Ed25519 identity per run — so a second
    /// invocation collided with the first pairing's device row instead of
    /// registering its own. `unique_device_name` must both keep the
    /// recognizable prefix and actually differ across calls.
    #[test]
    fn unique_device_name_keeps_the_prefix_and_differs_between_calls() {
        let a = unique_device_name();
        let b = unique_device_name();
        assert!(
            a.starts_with(PAIR_BROWSER_DEVICE_NAME),
            "device name must keep the recognizable harness-browser prefix: {a}"
        );
        assert!(
            b.starts_with(PAIR_BROWSER_DEVICE_NAME),
            "device name must keep the recognizable harness-browser prefix: {b}"
        );
        assert_ne!(
            a, b,
            "two invocations must not collide on the same device_id"
        );
    }

    /// Minimal single-purpose HTTP/1.1 stub for [`ensure_live_owner_token`]
    /// tests below. Deliberately not shared with `agent::client`'s own
    /// `refresh_tests` stub (different module, `#[cfg(test)]`-only, small
    /// enough that duplicating it is cheaper than adding a cross-module
    /// pub(crate) test surface) — but it follows the same bounded-`accept()`
    /// shape for the same reason: this box runs several concurrent sessions,
    /// and an unbounded `accept()` previously hung a test for minutes rather
    /// than failing it.
    mod stub_http {
        use std::io::{Read, Write};
        use std::net::TcpListener;
        use std::sync::mpsc;
        use std::time::{Duration, Instant};

        pub struct Canned {
            status: u16,
            body: String,
        }

        pub fn canned(status: u16, body: serde_json::Value) -> Canned {
            Canned { status, body: body.to_string() }
        }

        const DEADLINE: Duration = Duration::from_secs(10);

        /// Serves `responses` in order over successive connections, then
        /// reports `Ok(())` on `done` — or, if its own deadline elapses
        /// first, an `Err` naming how many of the scripted responses it
        /// actually got to serve.
        pub fn spawn(responses: Vec<Canned>) -> (String, mpsc::Receiver<Result<(), String>>) {
            let listener = TcpListener::bind("127.0.0.1:0").expect("bind stub listener");
            listener
                .set_nonblocking(true)
                .expect("set stub listener non-blocking (needed to bound accept())");
            let addr = listener.local_addr().expect("stub listener addr");
            let (tx, rx) = mpsc::channel();
            std::thread::spawn(move || {
                let expected = responses.len();
                let deadline = Instant::now() + DEADLINE;
                for (served, canned) in responses.into_iter().enumerate() {
                    let mut stream = loop {
                        match listener.accept() {
                            Ok((stream, _)) => break stream,
                            Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
                                if Instant::now() >= deadline {
                                    let _ = tx.send(Err(format!(
                                        "stub only saw {served}/{expected} scripted \
                                         connections before its own {DEADLINE:?} deadline"
                                    )));
                                    return;
                                }
                                std::thread::sleep(Duration::from_millis(20));
                            }
                            Err(_) => {
                                let _ = tx.send(Err(format!(
                                    "stub accept() failed after {served}/{expected} served"
                                )));
                                return;
                            }
                        }
                    };
                    let _ = stream.set_nonblocking(false);
                    let _ = stream.set_read_timeout(Some(Duration::from_secs(5)));
                    let mut buf = [0u8; 8192];
                    let _ = stream.read(&mut buf); // drain the request; bodies here are tiny.
                    let reason = match canned.status {
                        200 => "OK",
                        401 => "Unauthorized",
                        _ => "Status",
                    };
                    let response = format!(
                        "HTTP/1.1 {} {}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
                        canned.status,
                        reason,
                        canned.body.len(),
                        canned.body,
                    );
                    let _ = stream.write_all(response.as_bytes());
                    let _ = stream.flush();
                }
                let _ = tx.send(Ok(()));
            });
            (format!("http://{addr}"), rx)
        }

        pub fn await_done(rx: &mpsc::Receiver<Result<(), String>>) -> Result<(), String> {
            match rx.recv_timeout(DEADLINE + Duration::from_secs(2)) {
                Ok(result) => result,
                Err(_) => Err(format!(
                    "stub thread never reported an outcome within {:?}",
                    DEADLINE + Duration::from_secs(2)
                )),
            }
        }
    }

    fn write_pair_browser_test_session(
        dir: &std::path::Path,
        token: &str,
        refresh_token: &str,
        base_url: &str,
    ) -> PathBuf {
        let session = AgentSession {
            instance: "alice".into(),
            base_url: base_url.into(),
            node_id: "03aa".into(),
            public_key: "pub".into(),
            secret_key_hex: "sec".into(),
            mnemonic: "test mnemonic".into(),
            token: token.into(),
            refresh_token: refresh_token.into(),
            onboarded_at: chrono::Utc::now(),
            last_login_at: chrono::Utc::now(),
        };
        session.save(dir).expect("write test session");
        AgentSession::file_path(dir, &session.instance)
    }

    fn pair_browser_test_instance(name: &str, session_path: PathBuf, base_url: String) -> InstanceState {
        InstanceState {
            name: name.into(),
            session_path,
            base_url,
            ldk_addr: "127.0.0.1:9937".into(),
            node_id: "03aa".into(),
            pid: None,
            client_node_ports: None,
        }
    }

    /// The core of the live-run fix: a stale cached access token must not
    /// abort `pair-browser` — it must be silently refreshed (via the spec-D5
    /// `with_session`/`authed_get` machinery `ensure_live_owner_token` goes
    /// through) and the REFRESHED token, not the stale one, must be what
    /// ends up embedded in the snippet. Also pins that the refresh is
    /// actually persisted to disk, not just held in memory.
    #[test]
    fn ensure_live_owner_token_refreshes_a_stale_token_and_returns_the_fresh_one() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (base_url, done_rx) = stub_http::spawn(vec![
            stub_http::canned(401, json!({ "error": "Invalid or expired token" })),
            stub_http::canned(
                200,
                json!({ "token": "fresh-access-token", "refresh_token": "fresh-refresh-token" }),
            ),
            stub_http::canned(200, json!({ "node_id": "03aa" })),
        ]);

        let session_path =
            write_pair_browser_test_session(dir.path(), "stale-token", "still-valid-refresh", &base_url);
        let inst = pair_browser_test_instance("alice", session_path.clone(), base_url);

        let live = ensure_live_owner_token(&inst, "stale-token")
            .expect("a stale token must be transparently refreshed, not fail the call");
        stub_http::await_done(&done_rx).expect("stub should have served all 3 scripted responses");

        assert_eq!(live, "fresh-access-token");
        let persisted = AgentSession::load_from_path(&session_path).expect("reload session");
        assert_eq!(
            persisted.token, "fresh-access-token",
            "the refreshed token must be persisted to disk, not just returned"
        );
    }

    /// The exact live incident this exists to catch: the access token is
    /// dead AND the refresh token is ALSO dead (as happens once a daemon
    /// restart invalidates the session server-side), so refreshing cannot
    /// recover. `pair-browser` must fail loudly rather than embed a token it
    /// could not validate — and per AC-0, the error must name what was
    /// attempted, what was observed, and the exact remedy command.
    #[test]
    fn ensure_live_owner_token_fails_loudly_when_the_refresh_token_is_also_dead() {
        let dir = tempfile::tempdir().expect("tempdir");
        let (base_url, done_rx) = stub_http::spawn(vec![
            stub_http::canned(401, json!({ "error": "Invalid or expired token" })),
            stub_http::canned(401, json!({ "error": "Invalid refresh token" })),
        ]);

        let session_path =
            write_pair_browser_test_session(dir.path(), "stale-token", "dead-refresh-token", &base_url);
        let inst = pair_browser_test_instance("alice", session_path, base_url);

        let error = ensure_live_owner_token(&inst, "stale-token")
            .expect_err("a dead refresh token must not resolve to a usable token");
        stub_http::await_done(&done_rx).expect("stub should have served both scripted responses");

        let msg = format!("{error:#}");
        assert!(msg.contains("alice"), "must name the instance: {msg}");
        assert!(
            msg.contains("attempted") && msg.contains("observed"),
            "AC-0: must name what was attempted and what was observed: {msg}"
        );
        assert!(
            msg.contains("harness up --clean"),
            "must name the exact remedy command: {msg}"
        );
    }

    /// A `modules/<app>/` holding only the stale cdylib that the retired
    /// `make builtin-apps` used to stage registers no capabilities, so the
    /// preflight must reject it exactly as it rejects a missing directory.
    #[test]
    fn preflight_rejects_manifestless_app_dirs() {
        let root = std::env::temp_dir().join(format!("harness-preflight-{}", std::process::id()));
        let modules = root.join("modules");
        std::fs::create_dir_all(modules.join("device-registry")).unwrap();
        std::fs::write(
            modules.join("device-registry/libnode_app_device_registry.dylib"),
            b"",
        )
        .unwrap();

        let error = preflight_apps(&root).unwrap_err().to_string();
        assert!(error.contains("device-registry"), "got: {error}");
        assert!(error.contains("core-storage"), "got: {error}");
        assert!(error.contains("ldk-node"), "got: {error}");
        assert!(error.contains("make bootstrap-apps"), "got: {error}");
        assert!(error.contains("make build-ldk-node"), "got: {error}");

        // Both manifests present, and base env files already in place (so the
        // gap-0c/0e materialize-from-.example path is never exercised here —
        // that path is covered by materialize_base_env_from_example's own
        // tests in monorepo.rs) → preflight passes.
        for app in CRITICAL_APPS {
            std::fs::create_dir_all(modules.join(app)).unwrap();
            std::fs::write(modules.join(app).join("manifest.json"), b"{}").unwrap();
        }
        let server_dir = root.join("system/server");
        std::fs::create_dir_all(&server_dir).unwrap();
        std::fs::write(server_dir.join("alice.env"), b"JWT_SECRET=test\n").unwrap();
        std::fs::write(server_dir.join("bob.env"), b"JWT_SECRET=test\n").unwrap();
        assert!(preflight_apps(&root).is_ok());

        std::fs::remove_dir_all(&root).ok();
    }
}