secrets-vault 2.4.1

use std::io::{self, Read, IsTerminal};
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use std::{env, fs, process};

use clap::{Parser, Subcommand};
use rpassword::prompt_password;
use zeroize::Zeroizing;

use secrets_vault::{
    is_v1, is_v2, is_valid_key, parse_env_lines, random_bytes, random_salt, v2_create, v2_salt,
    MasterSecret, Vault, VaultError, VaultReader,
};

mod backend;
mod gsm;
mod inbox;
mod keychain;
#[cfg(windows)]
mod keychain_win;
mod lease;
mod registry;
mod session;
mod window;
#[cfg(windows)]
mod session_win;
#[cfg(windows)]
mod winacl;

use backend::Backend;

/// A batch of (env-var name, decrypted value) pairs headed for a child's env.
type ServedBatch = Vec<(String, Zeroizing<Vec<u8>>)>;

#[derive(Parser)]
#[command(name = "secrets", version)]
#[command(about = "Encrypted secret manager — AES-256-GCM + PBKDF2")]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    /// Store a secret (prompts if no value given)
    Set {
        key: String,
        value: Option<String>,
        /// Read the value from stdin (explicit; a piped/redirected stdin is
        /// also auto-detected without this flag). Errors if a positional
        /// value is also given.
        #[arg(long, conflicts_with = "value")]
        stdin: bool,
        /// Namespace under a project (stored internally as project/KEY)
        #[arg(long, short)]
        project: Option<String>,
        /// Store in Google Secret Manager (requires --project = GCP project id)
        #[arg(long)]
        gsm: bool,
        /// Write to the external backend configured in .secrets.toml's [backend]
        /// block (AWS / Vault / Doppler / 1Password / …) instead of the local vault.
        #[arg(long)]
        remote: bool,
        /// Seal into the write-only inbox (no Touch ID) instead of the vault. Merge
        /// later with one tap (`secrets inbox merge`). Local-vault only.
        #[arg(long)]
        inbox: bool,
    },
    /// Generate a random secret and store it — value is NEVER printed
    Gen {
        /// Secret name
        key: String,
        /// Number of random bytes (hex-encoded; default 32 → 64 hex chars)
        #[arg(long, default_value_t = 32)]
        bytes: usize,
        /// Overwrite if the key already exists (local only)
        #[arg(long)]
        force: bool,
        /// Namespace under a project (stored internally as project/KEY)
        #[arg(long, short)]
        project: Option<String>,
        /// Store in Google Secret Manager (requires --project = GCP project id)
        #[arg(long)]
        gsm: bool,
        /// Write to the external backend configured in .secrets.toml's [backend]
        /// block (AWS / Vault / Doppler / …) instead of the local vault.
        #[arg(long)]
        remote: bool,
        /// Seal into the write-only inbox (no Touch ID) instead of the vault. Merge
        /// later with one tap (`secrets inbox merge`). Local-vault only.
        #[arg(long)]
        inbox: bool,
    },
    /// Retrieve a secret (stdout, no trailing newline)
    Get {
        key: String,
        /// Namespace under a project (stored internally as project/KEY)
        #[arg(long, short)]
        project: Option<String>,
    },
    /// Remove a secret
    Delete { key: String },
    /// List all stored key names
    List {
        /// Read the plaintext name index (NO unlock / Touch ID) instead of the vault
        #[arg(long)]
        names_only: bool,
        /// Emit JSON: `{"keys":[{"project":…,"name":…}]}`. NAMES ONLY — a value
        /// never appears in this output, which is what makes it safe for a GUI.
        #[arg(long)]
        json: bool,
    },
    /// Check whether a key exists — names only, NO Touch ID, no value exposure.
    /// Prints `true`/`false`; exits 0 if present, 1 if not. Lets an agent avoid
    /// generating a duplicate secret without unlocking the vault.
    ///
    /// With -p this answers "can this project READ the key" (scoped entry OR
    /// the bare shared entry — the same resolution get/exec/lease use), and a
    /// stderr note says which one resolved. It does NOT mean a scoped copy
    /// exists; ask that question with --scoped-only before anything
    /// irreversible like deleting the bare entry.
    Has {
        key: String,
        /// Namespace under a project (checks project/KEY, then the bare KEY)
        #[arg(long, short)]
        project: Option<String>,
        /// True only if the SCOPED entry project/KEY itself exists — no bare
        /// fallback. The pre-deletion check.
        #[arg(long, requires = "project")]
        scoped_only: bool,
    },
    /// Output as shell exports or JSON
    Env {
        #[arg(long)]
        json: bool,
    },
    /// Import KEY=VALUE lines from stdin
    Import,
    /// Export all as KEY=VALUE
    Export,
    /// Store the vault passphrase behind the OS presence gate
    /// (macOS: Touch ID Keychain · Windows: DPAPI + Windows Hello)
    Unlock {
        /// Strict mode: enrolled biometry ONLY (no watch/passcode fallback),
        /// self-invalidates on fingerprint change, and forces a FRESH tap on every
        /// read (no grace window). Trades convenience for max security.
        ///
        /// macOS only — Windows Hello exposes no biometry-only mode, and Windows
        /// reads are already prompt-every-time. See src/keychain_win.rs.
        #[arg(long)]
        strict: bool,
        /// WINDOWS ONLY, and a real downgrade: store the master key under DPAPI
        /// with NO Windows Hello gate. The key then rests encrypted to your user
        /// account, but ANY process running as you can open it with no prompt.
        /// Only for a box with no Hello enrolled where you accept that trade.
        #[arg(long)]
        no_presence: bool,
    },
    /// Remove the stored master key (re-lock)
    Lock,
    /// Start a session-unlock broker: ONE Touch ID, then `secrets exec` runs
    /// tap-free for the lifetime (ssh-agent model). For unattended drains —
    /// the passphrase stays in the broker's memory, never in a child env.
    Session {
        /// Broker lifetime in minutes (it self-terminates after this).
        #[arg(default_value = "60")]
        minutes: u64,
    },
    /// INTERNAL: the detached session-broker serve loop. Reads the passphrase
    /// from stdin (a pipe — never argv/env) and serves it on the socket. Not
    /// for direct use; `secrets session` spawns it.
    #[command(hide = true, name = "__session-serve")]
    SessionServe {
        minutes: u64,
    },
    /// Run a command with ONLY a project's secrets in its environment.
    ///   secrets exec <project> -- <command> [args...]
    Exec {
        /// Project name — selects the secret list from .secrets.toml
        project: String,
        /// Human justification shown on the approval prompt ("why do you need this?").
        /// Surfaces on the Touch ID sheet and the aiconductor consent slab so the
        /// approver sees intent, not just a bare biometric scan. Optional; when
        /// omitted the prompt still shows agent/project/keys/command.
        #[arg(long)]
        reason: Option<String>,
        /// Command and arguments (everything after `--`)
        #[arg(last = true)]
        command: Vec<String>,
    },
    /// Authorize an agent to access a project (Touch ID gated)
    Authorize {
        agent: String,
        project: String,
        /// Timed session grant in minutes (default: permanent)
        #[arg(long)]
        session_minutes: Option<u64>,
    },
    /// Revoke an agent's access to a project (Touch ID gated)
    Revoke { agent: String, project: String },
    /// List registered projects and agent grants (Touch ID gated)
    ListProjects {
        /// Emit JSON. Project names, key COUNTS, and grant scopes — the
        /// registry holds no values, and neither does this.
        #[arg(long)]
        json: bool,
    },
    /// Write-only inbox for agent-generated secrets (AGENT_SECRET_LIFECYCLE.md)
    Inbox {
        #[command(subcommand)]
        sub: InboxCmd,
    },
    /// Project-scoped TTL lease: ONE Touch ID copies the project's declared
    /// secrets into an encrypted lease; reads during the TTL need no tap, the
    /// agent can never decrypt the file directly, and the lease destroys
    /// itself at expiry (LEASE_DESIGN.md).
    Lease {
        #[command(subcommand)]
        sub: LeaseCmd,
    },
    /// Migrate the vault (and grant registry) from v1 to the QVLT v2 format —
    /// per-entry encryption, so reads decrypt ONLY the requested key. One
    /// unlock; the v1 file is preserved as vault.qvlt.v1.bak.
    Migrate,
    /// Re-derive all vault keys under a fresh salt (full decrypt → re-encrypt).
    /// Ends any live session broker first. Run after revoking a party who may
    /// have held the master secret — and delete the old backups it warns about.
    Rekey,
}

#[derive(Subcommand)]
enum InboxCmd {
    /// Generate the inbox keypair (identity → Keychain, recipient → inbox.pub).
    /// Idempotent and tap-free; also lazy-runs on the first `--inbox` write.
    Init,
    /// Show pending entries — names + new/⚠overwrite (from the name index). No Touch ID.
    List,
    /// Open + merge all pending entries into the vault — ONE Touch ID tap. Wipes the
    /// inbox; entries that fail to open stay behind. Overwrites are reported.
    Merge,
    /// Reject a pending entry by name (removes it without merging). No Touch ID.
    Drop { name: String },
}

#[derive(Subcommand)]
enum LeaseCmd {
    /// Create (or replace) the lease for a project — ONE Touch ID. Copies the
    /// project's declared keys (.secrets.toml, names only) into the lease.
    Create {
        project: String,
        /// Lifetime: 30s / 90m / 2h / 1d, or a bare number of minutes.
        /// Default: the window's `until` bound when the project declares one,
        /// else 1h. An explicit --ttl always caps the expiry.
        #[arg(long)]
        ttl: Option<String>,
        /// Bind reads to this agent (default: the resolved calling agent).
        #[arg(long)]
        agent: Option<String>,
        /// Leave the lease unbound: any same-uid caller may read it.
        #[arg(long, conflicts_with = "agent")]
        any_agent: bool,
    },
    /// Read ONE leased value to stdout — no Touch ID. TTL enforced here: an
    /// expired lease is destroyed by this very read.
    #[command(visible_alias = "read")]
    Get { project: String, key: String },
    /// Show live leases (key names, expiry, binding). Expired and orphaned
    /// leases found by the scan are purged. No Touch ID.
    Status {
        /// Emit JSON: `{"leases":[…]}`, empty array when there are none, so a
        /// caller parses one shape rather than a sentence on stderr.
        #[arg(long)]
        json: bool,
    },
    /// Destroy a project's lease NOW: Keychain key crypto-erased first, then
    /// the file overwritten + removed. No Touch ID — revocation is free.
    Revoke { project: String },
}

fn vault_path() -> std::path::PathBuf {
    if let Ok(dir) = env::var("SECRETS_DIR") {
        return std::path::PathBuf::from(dir).join("vault.qvlt");
    }
    dirs::home_dir()
        .expect("HOME not set")
        .join(".config")
        .join("secrets")
        .join("vault.qvlt")
}

fn secrets_dir() -> PathBuf {
    if let Ok(dir) = env::var("SECRETS_DIR") {
        return PathBuf::from(dir);
    }
    dirs::home_dir()
        .expect("HOME not set")
        .join(".config")
        .join("secrets")
}

/// Load a project's manifest from `.secrets.toml` (current dir) or the global
/// `<secrets-dir>/projects.toml`: the secret NAMES it needs, plus which `Backend`
/// supplies the values. Name list comes from `[backend].secrets`, `[gsm].secrets`,
/// `[projects.<name>].secrets`, or a flat top-level `secrets = [...]`.
///
/// Backend selection (first match wins):
/// 1. `[backend]` table → `kind = "vault" | "gsm" | "command"` (see `backend::from_table`).
/// 2. `[gsm].project` → Google Secret Manager (backward-compatible shorthand).
/// 3. otherwise → the local biometric vault.
///
/// Only NAMES ever leave the manifest — values stay in the vault or the external manager.
fn load_manifest(project: &str) -> Result<(Vec<String>, Backend, Option<window::Window>), String> {
    let candidates = [PathBuf::from(".secrets.toml"), secrets_dir().join("projects.toml")];
    let path = candidates.iter().find(|p| p.exists()).ok_or_else(|| {
        "no .secrets.toml in this directory (or projects.toml in your secrets dir)".to_string()
    })?;
    let content =
        fs::read_to_string(path).map_err(|e| format!("reading {}: {e}", path.display()))?;
    let table: toml::Table = content
        .parse()
        .map_err(|e| format!("invalid TOML in {}: {e}", path.display()))?;

    let arr = table
        .get("projects")
        .and_then(|p| p.get(project))
        .and_then(|s| s.get("secrets"))
        .or_else(|| table.get("backend").and_then(|b| b.get("secrets"))) // [backend].secrets
        .or_else(|| table.get("gsm").and_then(|g| g.get("secrets"))) // [gsm].secrets
        .or_else(|| table.get("secrets")) // flat top-level
        .ok_or_else(|| {
            format!("no secret list for '{project}' (expected [backend].secrets, [gsm].secrets, [projects.{project}].secrets, or a top-level secrets = [...])")
        })?;
    let names: Vec<String> = arr
        .as_array()
        .ok_or_else(|| "`secrets` must be an array of names".to_string())?
        .iter()
        .filter_map(|v| v.as_str().map(str::to_string))
        .collect();
    if names.is_empty() {
        return Err(format!("project '{project}' lists no secrets"));
    }

    let win = table
        .get("projects")
        .and_then(|p| p.get(project))
        .and_then(|s| s.get("window"))
        .map(parse_window)
        .transpose()?;

    Ok((names, select_backend(&table)?, win))
}

/// `window = { hours = "09:30-16:00", tz = "America/New_York", days = "mon-fri",
///             grace_before = "30m", grace_after = "30m", until = "2026-09-04" }`
/// Graces default to 30m each way — the load-bearing figure from the schedule
/// that motivated the feature (a 09:00 fire probing the 09:30 open must read).
fn parse_window(v: &toml::Value) -> Result<window::Window, String> {
    let t = v.as_table().ok_or("window must be a table")?;
    let field = |k: &str| t.get(k).and_then(|x| x.as_str()).map(str::to_string);
    let grace = |k: &str| -> Result<u64, String> {
        match t.get(k) {
            None => Ok(30 * 60),
            Some(x) => {
                let raw = x
                    .as_str()
                    .ok_or_else(|| format!("window {k} must be a duration string"))?;
                // Zero grace is a legitimate declaration; parse_ttl (for
                // lease lifetimes) rejects it, so special-case it here.
                let digits = raw.trim().trim_end_matches(|c: char| c.is_ascii_alphabetic());
                if digits.parse::<u64>() == Ok(0) {
                    return Ok(0);
                }
                lease::parse_ttl(raw)
            }
        }
    };
    let w = window::Window {
        hours: field("hours").ok_or("window needs hours = \"HH:MM-HH:MM\"")?,
        tz: field("tz").ok_or("window needs tz = an IANA zone name")?,
        days: field("days"),
        grace_before_secs: grace("grace_before")?,
        grace_after_secs: grace("grace_after")?,
        until: field("until"),
    };
    w.validate()?;
    Ok(w)
}

/// Choose a `Backend` from a parsed manifest table (first match wins):
/// explicit `[backend]` → `[gsm].project` shorthand → local vault.
fn select_backend(table: &toml::Table) -> Result<Backend, String> {
    if let Some(bt) = table.get("backend").and_then(|b| b.as_table()) {
        backend::from_table(bt)
    } else if let Some(gcp) = table.get("gsm").and_then(|g| g.get("project")).and_then(|p| p.as_str()) {
        Ok(Backend::Gsm(gsm::GsmConfig {
            project: gcp.to_string(),
            account: table
                .get("gsm")
                .and_then(|g| g.get("account"))
                .and_then(|a| a.as_str())
                .map(String::from)
                .or_else(|| env::var("SECRETS_GSM_ACCOUNT").ok()),
            impersonate: table
                .get("gsm")
                .and_then(|g| g.get("impersonate"))
                .and_then(|a| a.as_str())
                .map(String::from)
                .or_else(|| env::var("SECRETS_GSM_IMPERSONATE").ok()),
        }))
    } else {
        Ok(Backend::Vault)
    }
}

/// Read just the backend from the manifest — for `set --remote` / `gen --remote`,
/// which write a value but don't need the project's secret-name list. Errors if no
/// manifest exists or it selects the local vault (there's nothing "remote" to write).
fn manifest_backend() -> Result<Backend, String> {
    let candidates = [PathBuf::from(".secrets.toml"), secrets_dir().join("projects.toml")];
    let path = candidates.iter().find(|p| p.exists()).ok_or_else(|| {
        "no .secrets.toml in this directory (or projects.toml in your secrets dir)".to_string()
    })?;
    let content =
        fs::read_to_string(path).map_err(|e| format!("reading {}: {e}", path.display()))?;
    let table: toml::Table = content
        .parse()
        .map_err(|e| format!("invalid TOML in {}: {e}", path.display()))?;
    let be = select_backend(&table)?;
    if !be.is_external() {
        return Err("no external [backend] in .secrets.toml — nothing to write with --remote".into());
    }
    Ok(be)
}

/// Obtain the master passphrase: `SECRETS_PASSPHRASE` env → biometric Keychain read
/// (the native Touch ID sheet surfaces even from a headless/agent process and blocks
/// until the human taps — verified) → TTY prompt if we have a terminal → else fail
/// closed. Note: a single read here covers a whole `exec` batch (all keys decrypt in
/// one vault-open after this), so an exec does exactly ONE keychain read.
/// Marker file recording that the Keychain item was stored in strict mode, so
/// reads attach a zero-reuse LAContext. The item's own ACL (BiometryCurrentSet) is
/// the hard enforcement — this only controls the read-side reuse behavior.
fn strict_marker_path() -> PathBuf {
    secrets_dir().join("strict")
}

fn is_strict_mode() -> bool {
    strict_marker_path().exists()
}

/// Passphrase acquisition with a custom reason line for the OS Touch ID sheet —
/// so an `exec` can show "read DATABASE_URL for 'promeasure' (agent claude)…" instead
/// of the generic default. The string is display-only; the keychain ACL is the real
/// enforcement. Values never leave this function.
fn get_passphrase_prompted(prompt: &str) -> Zeroizing<String> {
    if let Ok(pass) = env::var("SECRETS_PASSPHRASE") {
        return Zeroizing::new(pass);
    }
    // NOTE (v2): the session broker serves individual VALUES (session.rs), not
    // the passphrase — so there is deliberately no broker hook here. Callers
    // that can use the broker (exec/get with a project) try it BEFORE asking
    // for the passphrase at all.
    //
    // SECRETS_NO_KEYCHAIN skips the Keychain READ so PTY tests can drive the
    // TTY prompt against a throwaway SECRETS_DIR without touching the real
    // biometric item. Read-side only: removing a credential source can only
    // make acquisition stricter (TTY prompt or fail closed), never looser.
    if env::var_os("SECRETS_NO_KEYCHAIN").is_none() {
        match keychain::read(prompt, is_strict_mode()) {
            Ok(Some(p)) => return Zeroizing::new(p),
            Ok(None) => {} // no Keychain item yet (run `secrets unlock`)
            Err(e) => eprintln!("(keychain unavailable: {e})"),
        }
    }
    if io::stdin().is_terminal() {
        return prompt_only_passphrase();
    }
    // Headless and the vault isn't unlocked into the Keychain — fail closed.
    eprintln!("Vault is locked and there's no terminal to prompt on.");
    eprintln!("Run `secrets unlock` once (stores the master key behind Touch ID); after");
    eprintln!("that the Touch ID sheet surfaces even from a headless agent invocation.");
    process::exit(1);
}

/// Build the reason line shown on the OS Touch ID sheet for an `exec` unlock.
/// Always names the keys + project (the "what"); adds the agent (the "who") and the
/// human `--reason` (the "why") when known. This is the enrichment that turns the
/// "basic" bare biometric popup into something the human can actually judge.
fn exec_prompt(project: &str, keys: &[String], agent: Option<&str>, reason: Option<&str>) -> String {
    let key_list = if keys.is_empty() {
        "secrets".to_string()
    } else if keys.len() <= 4 {
        keys.join(", ")
    } else {
        format!("{} +{} more", keys[..4].join(", "), keys.len() - 4)
    };
    let mut s = format!("Unlock {key_list} for project “{project}”");
    if let Some(a) = agent {
        s.push_str(&format!(" — requested by {a}"));
    }
    if let Some(r) = reason.filter(|r| !r.is_empty()) {
        s.push_str(&format!("\nReason: {r}"));
    }
    s
}

/// Passphrase from env or a TTY prompt only — never the Keychain. Used by
/// `unlock` (which is *setting* the Keychain entry) to avoid a circular read.
/// When no vault file exists yet, the typed passphrase is about to become the
/// permanent master, so this routes through the confirmed creation prompt.
fn prompt_only_passphrase() -> Zeroizing<String> {
    if let Ok(pass) = env::var("SECRETS_PASSPHRASE") {
        return Zeroizing::new(pass);
    }
    if !vault_path().exists() {
        return prompt_new_vault_passphrase();
    }
    // Existing vault: masked prompt with bullet-per-char length feedback on an
    // interactive terminal; read_masked falls back to the silent prompt when
    // stdin isn't a TTY, so piped callers are unaffected.
    Zeroizing::new(read_masked("Vault passphrase: "))
}

/// First-run passphrase creation. There is no vault yet, so whatever is typed
/// here becomes the master passphrase of a brand-new vault — a single typo
/// would create a vault nobody can ever open, and there is no recovery.
/// So on an interactive terminal it is asked twice (masked, bullet-per-char)
/// and must match. Non-TTY callers read one line from stdin as before:
/// a scripted caller supplies the passphrase, it doesn't invent one by typo.
fn prompt_new_vault_passphrase() -> Zeroizing<String> {
    if !io::stdin().is_terminal() {
        return Zeroizing::new(prompt_password("Vault passphrase: ").unwrap_or_else(|e| {
            eprintln!("Error reading passphrase: {e}");
            process::exit(1);
        }));
    }
    eprintln!("No vault yet — this passphrase will create it and become the master key.");
    eprintln!("It cannot be recovered or reset if lost, so it must be entered twice.");
    loop {
        let first = Zeroizing::new(read_masked("New vault passphrase: "));
        if first.is_empty() {
            eprintln!("Passphrase can't be empty.");
            continue;
        }
        let confirm = Zeroizing::new(read_masked("Confirm passphrase: "));
        if *first == *confirm {
            return first;
        }
        eprintln!("Passphrases don't match — try again.");
    }
}

/// Read a secret value from an interactive TTY, echoing a bullet (•) per
/// character so the typist sees the *length* accumulate — feedback the silent
/// rpassword prompt never gave. The value itself is never echoed. Handles
/// Backspace/Delete (erase one char), Enter (submit), Ctrl-C (abort 130),
/// Ctrl-D (submit what's typed). Falls back to the silent prompt when stdin
/// isn't a real terminal or raw mode can't be entered, so piped/redirected
/// callers are unaffected.
///
/// macOS-only raw path (libc is a macOS-target dep here for sysctl); other
/// platforms keep the silent prompt.
#[cfg(target_os = "macos")]
fn read_masked(prompt: &str) -> String {
    use std::io::Write;
    use std::os::unix::io::AsRawFd;

    // Only drive raw mode on an interactive terminal; else defer to rpassword.
    if !io::stdin().is_terminal() {
        return prompt_password(prompt).unwrap_or_default();
    }
    let fd = io::stdin().as_raw_fd();

    let mut orig: libc::termios = unsafe { std::mem::zeroed() };
    if unsafe { libc::tcgetattr(fd, &mut orig) } != 0 {
        return prompt_password(prompt).unwrap_or_default();
    }
    let mut raw = orig; // libc::termios is Copy — `orig` stays valid for restore
    raw.c_lflag &= !(libc::ICANON | libc::ECHO);
    raw.c_cc[libc::VMIN] = 1;
    raw.c_cc[libc::VTIME] = 0;
    if unsafe { libc::tcsetattr(fd, libc::TCSANOW, &raw) } != 0 {
        return prompt_password(prompt).unwrap_or_default();
    }

    // RAII: restore the terminal on every *normal* exit path (return / panic
    // unwind). Ctrl-C uses process::exit, which skips Drop, so that arm
    // restores explicitly before exiting.
    struct TermGuard {
        fd: libc::c_int,
        orig: libc::termios,
    }
    impl Drop for TermGuard {
        fn drop(&mut self) {
            unsafe { libc::tcsetattr(self.fd, libc::TCSANOW, &self.orig) };
        }
    }
    let _guard = TermGuard { fd, orig };

    let mut err = io::stderr();
    let _ = write!(err, "{prompt}");
    let _ = err.flush();

    // Zeroizing so the plaintext buffer is wiped on drop.
    let mut buf: Zeroizing<Vec<u8>> = Zeroizing::new(Vec::new());
    let mut byte = [0u8; 1];
    loop {
        let n = unsafe { libc::read(fd, byte.as_mut_ptr() as *mut libc::c_void, 1) };
        if n <= 0 {
            break; // EOF / read error
        }
        match byte[0] {
            b'\n' | b'\r' => {
                let _ = write!(err, "\r\n");
                let _ = err.flush();
                break;
            }
            3 => {
                // Ctrl-C: restore the terminal ourselves (exit skips Drop), then abort.
                unsafe { libc::tcsetattr(fd, libc::TCSANOW, &orig) };
                let _ = write!(err, "\r\n");
                let _ = err.flush();
                process::exit(130);
            }
            4 => break, // Ctrl-D: submit what's been typed so far
            0x7f | 0x08 => {
                // Backspace/Delete: drop one whole UTF-8 char, erase one bullet.
                if !buf.is_empty() {
                    while let Some(&b) = buf.last() {
                        buf.pop();
                        if (b & 0xC0) != 0x80 {
                            break; // stopped at the lead byte
                        }
                    }
                    let _ = write!(err, "\x08 \x08");
                    let _ = err.flush();
                }
            }
            b => {
                buf.push(b);
                // One bullet per character: skip UTF-8 continuation bytes.
                if (b & 0xC0) != 0x80 {
                    let _ = write!(err, "•");
                    let _ = err.flush();
                }
            }
        }
    }
    // `_guard` drops here → terminal restored.
    String::from_utf8_lossy(&buf).into_owned()
}

#[cfg(not(target_os = "macos"))]
fn read_masked(prompt: &str) -> String {
    prompt_password(prompt).unwrap_or_default()
}

/// Legacy v1 whole-vault save — used ONLY by `VaultView::V1` (pre-migration
/// vaults keep the v1 format on write, spec §8).
fn save_vault(vault: &Vault, passphrase: &str) {
    let path = vault_path();
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent).ok();
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            fs::set_permissions(parent, fs::Permissions::from_mode(0o700)).ok();
        }
    }

    let encrypted = vault.encrypt(passphrase).unwrap_or_else(|e| {
        eprintln!("Error encrypting: {e}");
        process::exit(1);
    });

    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        let mut file = fs::OpenOptions::new()
            .write(true)
            .create(true)
            .truncate(true)
            .mode(0o600)
            .open(&path)
            .unwrap_or_else(|e| {
                eprintln!("Error writing vault: {e}");
                process::exit(1);
            });
        io::Write::write_all(&mut file, &encrypted).unwrap();
        write_index(vault);
        return;
    }

    #[cfg(not(unix))]
    {
        fs::write(&path, &encrypted).unwrap_or_else(|e| {
            eprintln!("Error writing vault: {e}");
            process::exit(1);
        });
        write_index(vault);
    }
}

// ── QVLT v2 key material + helpers (QVLT2_SPEC.md §5) ──

fn migrate_hint() {
    eprintln!("note: this vault is in the legacy v1 format (every read decrypts everything).");
    eprintln!("      Run `secrets migrate` once to upgrade to per-entry encryption.");
}

/// Read the vault file, if it exists (any version).
fn read_vault_bytes() -> Option<Vec<u8>> {
    match fs::read(vault_path()) {
        Ok(d) => Some(d),
        Err(e) if e.kind() == io::ErrorKind::NotFound => None,
        Err(e) => {
            eprintln!("Error reading vault: {e}");
            process::exit(1);
        }
    }
}

/// An unlocked vault, dispatched on on-disk format.
///
/// v2: the passphrase was zeroized at derivation (spec G4); reads decrypt one
/// record at a time; writes splice without touching unrelated ciphertext.
/// v1 (pre-`secrets migrate`): legacy whole-blob semantics, passphrase kept as
/// the working key so `save` and the legacy registry container still work.
enum VaultView {
    V2 { master: MasterSecret, reader: VaultReader },
    V1 { pass: Zeroizing<String>, vault: Vault },
}

/// Build a view from an already-obtained passphrase (consumed; zeroized here
/// for v2). Missing vault file → a fresh EMPTY v2 vault is created and
/// persisted immediately, so the salt (and thus the registry key) is stable
/// from the very first unlock.
fn view_from_passphrase(pass: Zeroizing<String>) -> VaultView {
    match read_vault_bytes() {
        Some(d) if is_v2(&d) => {
            let salt = v2_salt(&d).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            let master = MasterSecret::derive(&pass, &salt);
            drop(pass);
            let reader = open_reader(d, &master);
            VaultView::V2 { master, reader }
        }
        Some(d) if is_v1(&d) => {
            migrate_hint();
            let vault = match Vault::decrypt(&d, &pass) {
                Ok(v) => v,
                Err(VaultError::DecryptionFailed) => {
                    eprintln!("Error: wrong passphrase");
                    process::exit(1);
                }
                Err(e) => {
                    eprintln!("Error: {e}");
                    process::exit(1);
                }
            };
            VaultView::V1 { pass, vault }
        }
        Some(_) => {
            eprintln!("Error: vault file is not a recognized QVLT format");
            process::exit(1);
        }
        None => {
            // New vault → born v2 under a fresh salt, persisted NOW.
            let master = MasterSecret::derive(&pass, &random_salt());
            drop(pass);
            let out = v2_create(&master, &[]).unwrap_or_else(|e| {
                eprintln!("Error creating vault: {e}");
                process::exit(1);
            });
            write_v2_vault(&out, &[]);
            let reader = open_reader(out, &master);
            VaultView::V2 { master, reader }
        }
    }
}

/// ONE passphrase acquisition (env / Touch ID Keychain / TTY) → unlocked view.
fn unlock_view(prompt: &str) -> VaultView {
    view_from_passphrase(get_passphrase_prompted(prompt))
}

impl VaultView {
    fn contains(&self, name: &str) -> bool {
        match self {
            Self::V2 { reader, .. } => reader.contains(name),
            Self::V1 { vault, .. } => vault.get(name).is_some(),
        }
    }

    fn names(&self) -> Vec<String> {
        match self {
            Self::V2 { reader, .. } => reader.names().map(String::from).collect(),
            Self::V1 { vault, .. } => vault.keys().map(String::from).collect(),
        }
    }

    /// Decrypt ONE value (v2: exactly one record — G1). None = not present.
    /// Project-scoped read with the resolution order every project surface
    /// shares: the scoped entry (`project/NAME`, a project-specific override
    /// written by `set -p`) wins, else the bare entry (`NAME`, the shared
    /// value written by plain `set`/`gen`/`import`). Without the fallback the
    /// documented default flow — store bare, declare names in .secrets.toml,
    /// then `exec`/`lease create` — reported the key as "not in vault" while
    /// `has`/`get` said it was there.
    fn get_project(&self, project: &str, name: &str) -> Option<Zeroizing<Vec<u8>>> {
        self.get_one(&format!("{project}/{name}"))
            .or_else(|| self.get_one(name))
    }

    fn get_one(&self, name: &str) -> Option<Zeroizing<Vec<u8>>> {
        match self {
            Self::V2 { master, reader } => match reader.decrypt_one(master, name) {
                Ok(v) => Some(v),
                Err(VaultError::NotFound) => None,
                Err(e) => {
                    eprintln!("Error: {e}");
                    process::exit(1);
                }
            },
            Self::V1 { vault, .. } => {
                vault.get(name).map(|v| Zeroizing::new(v.as_bytes().to_vec()))
            }
        }
    }

    /// Apply upserts + deletes in one atomic write. v2 splices (untouched
    /// entries are never decrypted — G3); v1 keeps legacy full re-encrypt.
    fn write(&mut self, upserts: Vec<(String, Zeroizing<Vec<u8>>)>, deletes: Vec<String>) {
        match self {
            Self::V2 { master, reader } => {
                let out = reader.splice(master, &upserts, &deletes).unwrap_or_else(|e| {
                    eprintln!("Error encrypting: {e}");
                    process::exit(1);
                });
                let mut names: std::collections::BTreeSet<String> =
                    reader.names().map(String::from).collect();
                for d in &deletes {
                    names.remove(d);
                }
                for (n, _) in &upserts {
                    names.insert(n.clone());
                }
                let names: Vec<String> = names.into_iter().collect();
                write_v2_vault(&out, &names);
                *reader = open_reader(out, master); // view stays consistent
            }
            Self::V1 { pass, vault } => {
                for d in &deletes {
                    vault.delete(d);
                }
                for (n, v) in upserts {
                    vault.set(n, String::from_utf8_lossy(&v).into_owned());
                }
                save_vault(vault, pass);
            }
        }
    }

    /// Full decrypt — ONLY for the inherently whole-vault ops (env/export/
    /// legacy list of values). Discouraged elsewhere.
    fn decrypt_all(&self) -> Vault {
        match self {
            Self::V2 { master, reader } => reader.decrypt_all(master).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            }),
            Self::V1 { vault, .. } => vault.clone(),
        }
    }

    fn registry_load(&self, dir: &Path) -> Result<registry::Registry, String> {
        match self {
            Self::V2 { master, .. } => registry::Registry::load_raw(dir, &master.registry_key()),
            Self::V1 { pass, .. } => registry::Registry::load_v1(dir, pass),
        }
    }

    fn registry_save(&self, reg: &registry::Registry, dir: &Path) -> Result<(), String> {
        match self {
            Self::V2 { master, .. } => reg.save_raw(dir, &master.registry_key()),
            Self::V1 { pass, .. } => reg.save_v1(dir, pass),
        }
    }
}

/// Open + MAC-verify a v2 image, exiting with the standard message on failure.
fn open_reader(data: Vec<u8>, master: &MasterSecret) -> VaultReader {
    match VaultReader::open(data, master) {
        Ok(r) => r,
        Err(VaultError::DecryptionFailed) => {
            eprintln!("Error: wrong passphrase (or tampered vault)");
            process::exit(1);
        }
        Err(e) => {
            eprintln!("Error: {e}");
            process::exit(1);
        }
    }
}

/// Atomic v2 vault write (spec §5.2 step 4): 0600 temp in the secrets dir,
/// fsync the file, rename over vault.qvlt, fsync the DIRECTORY (without it the
/// rename itself can be lost on crash). Refreshes the plaintext name index.
fn write_v2_vault(bytes: &[u8], names: &[String]) {
    let path = vault_path();
    let parent = path.parent().expect("vault path has a parent").to_path_buf();
    fs::create_dir_all(&parent).ok();
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        fs::set_permissions(&parent, fs::Permissions::from_mode(0o700)).ok();
    }
    let tmp = parent.join(".vault.qvlt.tmp");
    #[cfg(unix)]
    let mut file = {
        use std::os::unix::fs::OpenOptionsExt;
        fs::OpenOptions::new()
            .write(true)
            .create(true)
            .truncate(true)
            .mode(0o600)
            .open(&tmp)
            .unwrap_or_else(|e| {
                eprintln!("Error writing vault: {e}");
                process::exit(1);
            })
    };
    #[cfg(not(unix))]
    let mut file = fs::File::create(&tmp).unwrap_or_else(|e| {
        eprintln!("Error writing vault: {e}");
        process::exit(1);
    });
    io::Write::write_all(&mut file, bytes).unwrap_or_else(|e| {
        eprintln!("Error writing vault: {e}");
        process::exit(1);
    });
    file.sync_all().ok();
    drop(file);
    fs::rename(&tmp, &path).unwrap_or_else(|e| {
        eprintln!("Error replacing vault: {e}");
        process::exit(1);
    });
    if let Ok(dir) = fs::File::open(&parent) {
        dir.sync_all().ok(); // directory fsync — makes the rename durable
    }
    write_index_names(names);
}

/// Plaintext index of vault KEY NAMES (never values) at `<secrets-dir>/index.json`,
/// refreshed on every vault save. Lets an agent answer "do we already have KEY?"
/// (`secrets has`) and enumerate names (`secrets list --names-only`) with NO Touch
/// ID and zero value exposure — names aren't secret (the manifest lists them too).
/// Newline-delimited, owner-only 0600. Best-effort: the encrypted vault stays the
/// source of truth; the index is only a no-unlock existence hint.
fn index_path() -> PathBuf {
    secrets_dir().join("index.json")
}

fn write_index(vault: &Vault) {
    let names: Vec<String> = vault.keys().map(String::from).collect();
    write_index_names(&names);
}

fn write_index_names(names: &[String]) {
    let body = names.join("\n");
    let path = index_path();
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent).ok();
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        if let Ok(mut f) = fs::OpenOptions::new()
            .write(true).create(true).truncate(true).mode(0o600).open(&path)
        {
            io::Write::write_all(&mut f, body.as_bytes()).ok();
        }
    }
    #[cfg(not(unix))]
    {
        fs::write(&path, body.as_bytes()).ok();
    }
}

fn read_index() -> Vec<String> {
    fs::read_to_string(index_path())
        .map(|s| s.lines().filter(|l| !l.is_empty()).map(String::from).collect())
        .unwrap_or_default()
}

/// Validate key (+ project) and build the storage key: `project/KEY` or `KEY`.
fn scoped_key(project: &Option<String>, key: &str) -> String {
    if !is_valid_key(key) {
        eprintln!("Invalid key: '{key}' (use A-Z, 0-9, _, -)");
        process::exit(1);
    }
    match project {
        Some(p) => {
            if !secrets_vault::is_valid_project(p) {
                eprintln!("Invalid project: '{p}' (use A-Z, 0-9, _, -, .)");
                process::exit(1);
            }
            format!("{p}/{key}")
        }
        None => key.to_string(),
    }
}

/// Build a GSM config for a GCP project, taking the acting account / impersonation
/// from the environment (override the active gcloud account if it lacks perms).
fn gsm_config(project: String) -> gsm::GsmConfig {
    gsm::GsmConfig {
        project,
        account: env::var("SECRETS_GSM_ACCOUNT").ok(),
        impersonate: env::var("SECRETS_GSM_IMPERSONATE").ok(),
    }
}

/// Directory both `secrets` and `aiconductor` use for the approval handshake.
/// A plain same-user dir (no App Group entitlement / provisioning profile).
/// COORDINATION: aiconductor must watch this same path.
fn approval_dir() -> PathBuf {
    if let Ok(d) = env::var("SECRETS_APPROVAL_DIR") {
        return PathBuf::from(d);
    }
    dirs::home_dir()
        .expect("HOME not set")
        .join(".secrets")
        .join("pending_approvals")
}

/// Request real-time approval via aiconductor and return whether a valid grant
/// now exists. SECURITY: the `[id]_response.json` file is an UNTRUSTED "re-check"
/// signal — a same-user agent could forge it. The approval is real ONLY if a
/// grant now appears in the encrypted `registry.enc`, which only aiconductor (with
/// the human's biometric) can write. We re-read the registry with the passphrase
/// we already hold — no second CLI prompt.
fn ipc_approval(
    agent: &str,
    project: &str,
    command: &str,
    keys: &[String],
    reason: Option<&str>,
    reg_dir: &Path,
    view: &VaultView,
) -> bool {
    let dir = approval_dir();
    if fs::create_dir_all(&dir).is_err() {
        eprintln!("Could not create approval dir {}", dir.display());
        return false;
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let _ = fs::set_permissions(&dir, fs::Permissions::from_mode(0o700));
    }

    let id = to_hex(&random_bytes(16));
    let req_path = dir.join(format!("{id}.json"));
    let resp_path = dir.join(format!("{id}_response.json"));

    let mut req = serde_json::json!({
        "id": id, "agent": agent, "project": project, "command": command, "keys": keys,
    });
    // Human justification (`--reason`), shown on the aiconductor consent slab. Omitted
    // from the wire when absent so the field only appears when there's a real reason.
    if let Some(r) = reason.filter(|r| !r.is_empty()) {
        req["reason"] = serde_json::Value::String(r.to_string());
    }
    if fs::write(&req_path, serde_json::to_vec_pretty(&req).unwrap_or_default()).is_err() {
        eprintln!("Could not write approval request.");
        return false;
    }

    eprintln!("Waiting for approval in aiconductor… ({agent} → {project})");
    let timeout = env::var("SECRETS_APPROVAL_TIMEOUT_SECS")
        .ok()
        .and_then(|s| s.parse::<u64>().ok())
        .unwrap_or(30);
    let start = Instant::now();
    let granted = loop {
        if resp_path.exists() {
            // Untrusted signal → re-read the encrypted registry (the real boundary).
            let reg = view.registry_load(reg_dir).unwrap_or_default();
            break reg.grant_for(agent, project, registry::now()).is_some();
        }
        if start.elapsed().as_secs() >= timeout {
            eprintln!("Approval timed out (is aiconductor running?).");
            break false;
        }
        std::thread::sleep(Duration::from_millis(100));
    };

    let _ = fs::remove_file(&req_path);
    let _ = fs::remove_file(&resp_path);
    granted
}

fn to_hex(bytes: &[u8]) -> String {
    use std::fmt::Write as _;
    let mut s = String::with_capacity(bytes.len() * 2);
    for b in bytes {
        let _ = write!(s, "{b:02x}");
    }
    s
}

/// Loud stderr warning for the `secrets env` vault-dump footgun.
fn eval_warning() {
    let (red, bold, off) = if io::stderr().is_terminal() {
        ("\x1b[1;31m", "\x1b[1m", "\x1b[0m")
    } else {
        ("", "", "")
    };
    eprintln!("{red}⚠️  WARNING:{off} `secrets env` dumps your ENTIRE vault into the shell");
    eprintln!("   environment — every secret is then exposed to ALL child processes");
    eprintln!("   (including untrusted npm/pip postinstall scripts).");
    eprintln!("   Use {bold}secrets exec <project> -- <cmd>{off} for scoped, child-only injection.");
}

/// Windows stand-in for the `0o700` the Unix arms chmod onto the secrets dir.
///
/// Done once, up front, on the DIRECTORY rather than at each of the dozen
/// `cfg(not(unix))` write sites: the DACL winacl installs is inheritable
/// (`OICI`) and protected, so `vault.qvlt`, `index.json`, `registry.enc`, the
/// leases and the logs all inherit owner-only as they are created. Idempotent
/// and cheap, so every invocation re-asserts it — an ACL loosened by an
/// installer or a folder-sync tool gets repaired on the next command rather
/// than staying wrong until someone notices.
#[cfg(windows)]
fn harden_secrets_dirs() {
    let dir = secrets_dir();
    if fs::create_dir_all(&dir).is_ok() {
        winacl::restrict_to_owner_warn(&dir);
    }
    // The approval handshake dir is a sibling under ~/.secrets and carries
    // request metadata (project + key NAMES), so it gets the same treatment.
    let approvals = approval_dir();
    if let Some(parent) = approvals.parent() {
        if fs::create_dir_all(parent).is_ok() {
            winacl::restrict_to_owner_warn(parent);
        }
    }
}

/// Read `session.log` past `offset` and report the first outcome the broker
/// recorded there: `Ok(())` for a successful bind, `Err(reason)` for a failure.
/// `None` while it has not decided yet.
///
/// This is how `secrets session` learns whether the broker it launched actually
/// came up. The broker binds in a detached child whose stderr goes nowhere, so
/// its audit line is the only channel back — and unlike probing the rendezvous
/// address, it cannot be answered by some other process that happens to be
/// listening there.
fn broker_outcome(log: &Path, offset: u64) -> Option<Result<(), String>> {
    let data = fs::read(log).ok()?;
    if (data.len() as u64) <= offset {
        return None;
    }
    let tail = String::from_utf8_lossy(&data[offset as usize..]);
    for line in tail.lines() {
        if let Some(i) = line.find(" FAILED ") {
            return Some(Err(line[i + " FAILED ".len()..].to_string()));
        }
        if line.contains(" START lifetime=") {
            return Some(Ok(()));
        }
    }
    None
}

fn main() {
    let cli = Cli::parse();
    #[cfg(windows)]
    harden_secrets_dirs();
    match cli.command {
        Commands::Set { key, value, stdin, project, gsm, remote, inbox } => {
            if !is_valid_key(&key) {
                eprintln!("Invalid key: '{key}' (use A-Z, 0-9, _, -)");
                process::exit(1);
            }
            let value = match value {
                Some(v) => v,
                None => {
                    // Explicit --stdin, or an auto-detected non-TTY stdin, reads
                    // the value from stdin (never argv). An interactive TTY gets
                    // the masked prompt (bullets show length; value never echoed).
                    if stdin || !io::stdin().is_terminal() {
                        // Read the ENTIRE payload to EOF. Multi-line values (e.g. a
                        // pretty-printed JSON service-account key) must NOT be
                        // truncated at the first newline — read_line did exactly
                        // that, storing only `{`. Strip a single trailing newline so
                        // the common `echo secret | secrets set` case stores `secret`
                        // (not `secret\n`); internal newlines are preserved verbatim.
                        let mut buf = String::new();
                        io::stdin().read_to_string(&mut buf).expect("Failed to read stdin");
                        let trimmed = buf.strip_suffix('\n').unwrap_or(&buf);
                        let trimmed = trimmed.strip_suffix('\r').unwrap_or(trimmed);
                        trimmed.to_string()
                    } else {
                        read_masked(&format!("Enter value for {key}: "))
                    }
                }
            };
            if value.is_empty() {
                eprintln!("Error: empty value");
                process::exit(1);
            }
            if inbox {
                if gsm || remote {
                    eprintln!("--inbox seals into the local vault inbox; not valid with --gsm/--remote.");
                    process::exit(1);
                }
                let storage = scoped_key(&project, &key);
                match inbox::append(&secrets_dir(), &storage, &value) {
                    Ok(count) => eprintln!(
                        "Sealed {storage} into the inbox ({count} pending) — no Touch ID. \
                         Merge later: secrets inbox merge"
                    ),
                    Err(e) => {
                        eprintln!("Inbox error: {e}");
                        process::exit(1);
                    }
                }
            } else if remote {
                let be = manifest_backend().unwrap_or_else(|e| {
                    eprintln!("Error: {e}");
                    process::exit(1);
                });
                match be.add(&key, &value) {
                    Ok(()) => eprintln!("Stored {key} → {}.", be.label()),
                    Err(e) => {
                        eprintln!("{} error: {e}", be.label());
                        process::exit(1);
                    }
                }
            } else if gsm {
                let proj = project.unwrap_or_else(|| {
                    eprintln!("--gsm requires --project <gcp-project>");
                    process::exit(1);
                });
                let cfg = gsm_config(proj);
                match gsm::add(&cfg, &key, &value) {
                    Ok(()) => eprintln!("Stored {key} → GSM project '{}'.", cfg.project),
                    Err(e) => {
                        eprintln!("GSM error: {e}");
                        process::exit(1);
                    }
                }
            } else {
                let storage = scoped_key(&project, &key);
                let mut view = unlock_view("Unlock your secrets vault");
                view.write(
                    vec![(storage.clone(), Zeroizing::new(value.into_bytes()))],
                    vec![],
                );
                eprintln!("Stored: {storage}");
            }
        }

        Commands::Gen { key, bytes, force, project, gsm, remote, inbox } => {
            if !is_valid_key(&key) {
                eprintln!("Invalid key: '{key}' (use A-Z, 0-9, _, -)");
                process::exit(1);
            }
            if bytes == 0 || bytes > 1024 {
                eprintln!("Error: --bytes must be between 1 and 1024");
                process::exit(1);
            }
            // Random bytes → hex. The value is NEVER printed (no stdout, no
            // scrollback, no shell history): the agent only handles the name.
            let value = to_hex(&random_bytes(bytes));
            if inbox {
                if gsm || remote {
                    eprintln!("--inbox seals into the local vault inbox; not valid with --gsm/--remote.");
                    process::exit(1);
                }
                // new-vs-overwrite is decided at merge against the unlocked vault, so
                // --force is irrelevant here; the inbox always accepts the seal.
                let _ = force;
                let storage = scoped_key(&project, &key);
                match inbox::append(&secrets_dir(), &storage, &value) {
                    Ok(count) => eprintln!(
                        "Generated {storage} ({bytes} bytes) → sealed into the inbox ({count} pending), \
                         value never printed. Merge later: secrets inbox merge"
                    ),
                    Err(e) => {
                        eprintln!("Inbox error: {e}");
                        process::exit(1);
                    }
                }
            } else if remote {
                let be = manifest_backend().unwrap_or_else(|e| {
                    eprintln!("Error: {e}");
                    process::exit(1);
                });
                match be.add(&key, &value) {
                    Ok(()) => eprintln!(
                        "Generated {key} ({bytes} bytes) → {} — value never printed.",
                        be.label()
                    ),
                    Err(e) => {
                        eprintln!("{} error: {e}", be.label());
                        process::exit(1);
                    }
                }
            } else if gsm {
                let proj = project.unwrap_or_else(|| {
                    eprintln!("--gsm requires --project <gcp-project>");
                    process::exit(1);
                });
                let cfg = gsm_config(proj);
                match gsm::add(&cfg, &key, &value) {
                    Ok(()) => eprintln!(
                        "Generated {key} ({bytes} bytes) → GSM project '{}' — value never printed.",
                        cfg.project
                    ),
                    Err(e) => {
                        eprintln!("GSM error: {e}");
                        process::exit(1);
                    }
                }
            } else {
                let storage = scoped_key(&project, &key);
                let mut view = unlock_view("Unlock your secrets vault");
                // Existence check needs NO value decryption in v2.
                if view.contains(&storage) && !force {
                    eprintln!("'{storage}' already exists — use --force to regenerate (overwrites).");
                    process::exit(1);
                }
                view.write(
                    vec![(storage.clone(), Zeroizing::new(value.into_bytes()))],
                    vec![],
                );
                eprintln!("Generated {storage} ({bytes} random bytes, hex) — value stored, never printed.");
            }
        }

        Commands::Get { key, project } => {
            let storage = scoped_key(&project, &key);
            // Session broker first (v2, per-key, grant-checked server-side):
            // a granted agent inside a session window reads tap-free; everyone
            // else silently falls through to the Touch ID path below.
            if let Some(p) = &project {
                if let Some(value) = session::request_value(&secrets_dir(), p, &key) {
                    io::Write::write_all(&mut io::stdout(), &value).ok();
                    return;
                }
                // Then any live lease (offline, TTL-checked, agent-bound —
                // LEASE_DESIGN.md §6). Every miss falls through silently,
                // exactly like a broker miss.
                if let Ok(ks) = lease::keystore_from_env() {
                    if let lease::ReadOutcome::Served(value) = lease::read(
                        &secrets_dir(),
                        ks,
                        p,
                        &key,
                        registry::resolve_agent().as_deref(),
                        lease::now(),
                    ) {
                        io::Write::write_all(&mut io::stdout(), &value).ok();
                        return;
                    }
                }
            }
            let view = unlock_view(&format!("Read {storage} from your secrets vault"));
            let found = match &project {
                Some(p) => view.get_project(p, &key),
                None => view.get_one(&storage),
            };
            match found {
                Some(value) => {
                    io::Write::write_all(&mut io::stdout(), &value).ok();
                }
                None => {
                    eprintln!("Not found: {key}");
                    process::exit(1);
                }
            }
        }

        Commands::Delete { key } => {
            let mut view = unlock_view(&format!("Delete {key} from your secrets vault"));
            if !view.contains(&key) {
                eprintln!("Not found: {key}");
                process::exit(1);
            }
            // v2: removal is a splice — no value (this one or any other) is decrypted.
            view.write(vec![], vec![key.clone()]);
            eprintln!("Deleted: {key}");
        }

        Commands::List { names_only, json } => {
            let names = if names_only {
                // No unlock: read the plaintext name index.
                read_index()
            } else {
                // Authenticated listing: MAC-verified names. v2 decrypts NO values.
                let view = unlock_view("List your secrets vault");
                let names = view.names();
                write_index_names(&names); // self-heal the index
                names
            };
            if json {
                // Split the storage key back into its parts so a caller does not
                // have to know that `project/KEY` is the on-disk convention.
                // First separator only: projects cannot contain '/', keys can.
                let keys: Vec<serde_json::Value> = names
                    .iter()
                    .map(|k| match k.split_once('/') {
                        Some((p, name)) => serde_json::json!({ "project": p, "name": name }),
                        None => serde_json::json!({ "project": null, "name": k }),
                    })
                    .collect();
                println!("{}", serde_json::json!({ "keys": keys }));
            } else {
                for key in &names {
                    println!("{key}");
                }
            }
        }

        Commands::Has { key, project, scoped_only } => {
            let storage = scoped_key(&project, &key);
            let index = read_index();
            let scoped_hit = project.is_some() && index.iter().any(|k| k == &storage);
            let bare_hit = index.iter().any(|k| k == &key);
            // Mirror the read-side resolution (get_project): a scoped query
            // also answers true when the bare shared entry would serve it —
            // unless --scoped-only asks the narrower question.
            let exists = if scoped_only {
                scoped_hit
            } else if project.is_some() {
                scoped_hit || bare_hit
            } else {
                bare_hit
            };
            // Provenance on stderr (stdout stays exactly true/false for
            // scripts): "resolvable by this project" and "a scoped copy
            // exists" are different facts, and conflating them once nearly
            // deleted the only copy of a credential.
            if project.is_some() && !scoped_only && exists {
                if scoped_hit {
                    eprintln!("(scoped entry {storage})");
                } else {
                    eprintln!("(bare entry {key} — no scoped copy for this project)");
                }
            }
            println!("{exists}");
            process::exit(if exists { 0 } else { 1 });
        }

        Commands::Env { json } => {
            // The `eval $(secrets env)` footgun — warn loudly (to stderr, so it
            // doesn't pollute the eval'd stdout). The shell-exports form is the one
            // people pipe into `eval`, so target that path.
            if !json {
                eval_warning();
            }
            let view = unlock_view("Dump your ENTIRE secrets vault (env)");
            let vault = view.decrypt_all();
            if json {
                print!("{}", vault.to_json());
            } else {
                print!("{}", vault.to_shell_exports());
            }
        }

        Commands::Import => {
            let mut input = String::new();
            io::stdin()
                .read_to_string(&mut input)
                .expect("Failed to read stdin");
            let pairs = parse_env_lines(&input);
            let count = pairs.len();
            let upserts: Vec<(String, Zeroizing<Vec<u8>>)> = pairs
                .into_iter()
                .map(|(k, v)| (k, Zeroizing::new(v.into_bytes())))
                .collect();
            // v2: one splice — existing entries are never decrypted (G3).
            let mut view = unlock_view("Import secrets into your vault");
            view.write(upserts, vec![]);
            eprintln!("Imported {count} secrets");
        }

        Commands::Export => {
            // The KEY=VALUE line format is newline-delimited, so it cannot faithfully
            // carry a value that itself contains newlines (a multi-line JSON key would
            // be split across physical lines and `import` — which parses line-by-line —
            // would only recover the first fragment). Rather than silently corrupt such
            // a value, warn loudly to stderr (stdout stays clean for redirection).
            let view = unlock_view("Export your ENTIRE secrets vault");
            let vault = view.decrypt_all();
            for (key, value) in vault.iter() {
                if value.contains('\n') {
                    eprintln!(
                        "warning: '{key}' is multi-line; the KEY=VALUE export format cannot \
                         round-trip it via `import`. Use `secrets get {key}` to retrieve it intact."
                    );
                }
                println!("{key}={value}");
            }
        }

        Commands::Unlock { strict, no_presence } => {
            #[cfg(not(windows))]
            if no_presence {
                eprintln!("--no-presence is a Windows-only option (it disables the Windows Hello gate).");
                process::exit(2);
            }
            #[cfg(windows)]
            if strict {
                eprintln!(
                    "note: --strict has no Windows equivalent — Windows Hello exposes no \
                     biometry-only mode. Windows reads are already prompt-every-time."
                );
            }
            let pass = prompt_only_passphrase();
            // If a vault already exists, verify the passphrase opens it before
            // storing — don't lock in a wrong passphrase.
            if let Ok(data) = fs::read(vault_path()) {
                let ok = if is_v2(&data) {
                    v2_salt(&data)
                        .map(|salt| {
                            let m = MasterSecret::derive(&pass, &salt);
                            VaultReader::open(data, &m).is_ok()
                        })
                        .unwrap_or(false)
                } else {
                    Vault::decrypt(&data, &pass).is_ok()
                };
                if !ok {
                    eprintln!("Wrong passphrase — nothing stored.");
                    process::exit(1);
                }
            }
            #[cfg(windows)]
            let stored = if no_presence {
                keychain_win::store_no_presence(&pass)
            } else {
                keychain::store(&pass, strict)
            };
            #[cfg(not(windows))]
            let stored = keychain::store(&pass, strict);

            match stored {
                Ok(()) => {
                    // Persist (or clear) the strict marker so reads match the ACL.
                    let marker = strict_marker_path();
                    if strict {
                        if let Some(parent) = marker.parent() {
                            fs::create_dir_all(parent).ok();
                        }
                        let _ = fs::write(&marker, b"1");
                    } else {
                        let _ = fs::remove_file(&marker);
                    }

                    #[cfg(windows)]
                    if no_presence {
                        eprintln!(
                            "Unlocked WITHOUT a presence gate. The master key is DPAPI-encrypted \
                             to your Windows account, but any process running as you can open it \
                             with no prompt. Re-run `secrets unlock` (no flag) to restore the \
                             Windows Hello gate."
                        );
                    } else {
                        eprintln!(
                            "Unlocked. Master key sealed with DPAPI (your Windows account) — \
                             Windows Hello required on every read."
                        );
                    }
                    #[cfg(target_os = "macos")]
                    if strict {
                        eprintln!(
                            "Unlocked (STRICT). Enrolled biometry only, no reuse — a fresh Touch ID tap is required on every access."
                        );
                    } else {
                        eprintln!(
                            "Unlocked. Master key stored in the biometric Keychain — Touch ID required on read (with the system reuse grace)."
                        );
                    }
                    #[cfg(not(any(windows, target_os = "macos")))]
                    eprintln!("Unlocked.");
                }
                Err(e) => {
                    eprintln!("Storing the master key failed: {e}");
                    process::exit(1);
                }
            }
        }

        Commands::Lock => match keychain::delete() {
            Ok(()) => {
                let _ = fs::remove_file(strict_marker_path());
                session::end(&secrets_dir());   // also kill any live session broker
                // Lock means lockdown: a surviving tap-free lease would
                // contradict it (LEASE_DESIGN.md §6).
                if let Ok(ks) = lease::keystore_from_env() {
                    let n = lease::revoke_all(&secrets_dir(), ks);
                    if n > 0 {
                        eprintln!("Revoked {n} live lease(s).");
                    }
                }
                #[cfg(windows)]
                eprintln!("Locked. DPAPI master-key entry removed.");
                #[cfg(not(windows))]
                eprintln!("Locked. Biometric Keychain entry removed.");
            }
            Err(e) => {
                eprintln!("Removing the stored master key failed: {e}");
                process::exit(1);
            }
        },

        Commands::Session { minutes } => {
            // ONE presence check here (the keychain read), then hand the
            // passphrase to a detached broker over a pipe. The broker derives
            // the master secret and zeroizes the passphrase at startup; it
            // serves per-key, grant-checked values — never the passphrase
            // (QVLT2_SPEC.md §6).
            {
            let Some(data) = read_vault_bytes() else {
                eprintln!("No vault yet — nothing to serve. Store a secret first.");
                process::exit(1);
            };
            if !is_v2(&data) {
                // A v1 vault must never revive the passphrase-dispenser broker.
                migrate_hint();
                eprintln!("`secrets session` requires a v2 vault.");
                process::exit(1);
            }
            let pass = get_passphrase_prompted("Start a secrets session (unattended drain)");
            let salt = v2_salt(&data).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            let master = MasterSecret::derive(&pass, &salt);
            if VaultReader::open(data, &master).is_err() {
                eprintln!("Wrong passphrase — session not started.");
                process::exit(1);
            }
            drop(master);
            // Spawn the detached serve loop; pass the secret via its stdin (pipe),
            // never argv/env. The child re-execs THIS binary's hidden subcommand.
            // Note where the audit log ends BEFORE spawning, so the outcome we
            // read back is unambiguously this launch's and not a previous one's.
            let log_path = secrets_dir().join("session.log");
            let log_before = fs::metadata(&log_path).map(|m| m.len()).unwrap_or(0);

            let exe = env::current_exe().unwrap_or_else(|_| PathBuf::from("secrets"));
            let mut cmd = process::Command::new(exe);
            cmd.arg("__session-serve")
                .arg(minutes.to_string())
                .stdin(process::Stdio::piped())
                .stdout(process::Stdio::null())
                .stderr(process::Stdio::null());
            // Detachment is the PARENT's job on Windows: a console process is
            // bound to its console at creation, so there is no post-hoc `setsid`
            // equivalent the child could call. DETACHED_PROCESS (0x8) gives the
            // broker no console, and CREATE_NEW_PROCESS_GROUP (0x200) keeps a
            // Ctrl-C in the launching shell from killing it.
            #[cfg(windows)]
            {
                use std::os::windows::process::CommandExt;
                cmd.creation_flags(0x0000_0008 | 0x0000_0200);
                // And stop our OWN std handles being inherited. CreateProcess
                // duplicates every inheritable handle in this process, not just
                // the ones we redirect — so a broker launched from a shell
                // pipeline (`secrets session | tee log`) would hold that
                // pipeline's write end open and the shell would hang until the
                // broker expired, minutes later. Detaching means detaching from
                // the launching shell's plumbing too.
                unsafe {
                    use windows::Win32::Foundation::{
                        SetHandleInformation, HANDLE_FLAGS, HANDLE_FLAG_INHERIT,
                    };
                    use windows::Win32::System::Console::{
                        GetStdHandle, STD_ERROR_HANDLE, STD_INPUT_HANDLE, STD_OUTPUT_HANDLE,
                    };
                    for id in [STD_INPUT_HANDLE, STD_OUTPUT_HANDLE, STD_ERROR_HANDLE] {
                        if let Ok(h) = GetStdHandle(id) {
                            let _ = SetHandleInformation(h, HANDLE_FLAG_INHERIT.0, HANDLE_FLAGS(0));
                        }
                    }
                }
            }
            let mut child = cmd.spawn().unwrap_or_else(|e| {
                eprintln!("Failed to start session broker: {e}");
                process::exit(1);
            });
            if let Some(mut sin) = child.stdin.take() {
                use std::io::Write as _;
                let _ = sin.write_all(pass.as_bytes());
                // dropping sin closes the pipe → the child stops reading
            }
            // The broker binds in the CHILD, so "spawned" is not "running".
            // Confirm it is actually reachable before saying so — a parent that
            // announces a key server which never came up is worse than one that
            // fails, because every later `exec` silently takes the fallback path
            // while the user believes requests are being grant-checked.
            // Wait for OUR CHILD to say what happened.
            //
            // "Something is listening at the address" is not the question — a
            // process already holding the rendezvous name answers that just as
            // well as our broker would, and the parent would report a running
            // key server while its own child exited with "name already taken".
            // The child's own audit line is the only signal that distinguishes
            // them, and it carries the reason, so the user gets told WHY rather
            // than being pointed at a log.
            let mut failure: Option<String> = None;
            let mut live = false;
            for _ in 0..100 {
                match broker_outcome(&log_path, log_before) {
                    Some(Ok(())) => {
                        live = true;
                        break;
                    }
                    Some(Err(why)) => {
                        failure = Some(why);
                        break;
                    }
                    None => {}
                }
                if matches!(child.try_wait(), Ok(Some(_))) {
                    // Exited without recording anything — keep the generic
                    // message rather than inventing a cause.
                    break;
                }
                std::thread::sleep(Duration::from_millis(50));
            }

            if live {
                // Cross-user squatting is a separate question from "did my child
                // bind": it needs the pipe's OWNER, not its presence.
                if let session::Probe::Foreign(why) = session::probe(&secrets_dir()) {
                    eprintln!("Refusing to report a session: {why}");
                    process::exit(1);
                }
            } else {
                eprintln!("Session broker failed to start — no key server is running.");
                match failure {
                    Some(why) => eprintln!("{why}"),
                    None => eprintln!(
                        "It exited without recording a reason; see {}",
                        secrets_dir().join("session.log").display()
                    ),
                }
                process::exit(1);
            }

            eprintln!(
                "Session started — `secrets exec` runs tap-free for {minutes} min. \
                 `secrets lock` ends it early."
            );
            }
        }

        Commands::SessionServe { minutes } => {
            // Detached broker child. Read the passphrase from stdin (the pipe the
            // parent wrote), then serve it on the socket until expiry/END.
            use std::io::Read as _;
            let mut pass = String::new();
            if std::io::stdin().read_to_string(&mut pass).is_err() {
                process::exit(1);
            }
            let pass = Zeroizing::new(pass);
            if pass.is_empty() {
                process::exit(1);
            }
            session::detach();
            if let Err(e) = session::serve(&secrets_dir(), minutes, pass) {
                // We are detached: stderr goes nowhere. The audit log is the
                // only channel back to the human, and the parent points at it.
                session::audit(&secrets_dir(), &format!("FAILED {e}"));
                eprintln!("session broker: {e}");
                process::exit(1);
            }
            return;
        }

        Commands::Exec { project, reason, command } => {
            if command.is_empty() {
                eprintln!("Usage: secrets exec <project> -- <command> [args...]");
                process::exit(2);
            }
            if !secrets_vault::is_valid_project(&project) {
                eprintln!("Invalid project: '{project}'");
                process::exit(1);
            }
            let (names, be, _window) = load_manifest(&project).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });

            let dir = secrets_dir();
            let mut cmd = process::Command::new(&command[0]);
            cmd.args(&command[1..]);
            cmd.env_remove("SECRETS_PASSPHRASE");

            // Tap-free fast paths (all-or-nothing per batch; any miss → the
            // Touch ID path for the whole batch):
            // 1. Session broker (v2): enforces caller identity + grant +
            //    manifest SERVER-SIDE and audits every request.
            // 2. Project lease (LEASE_DESIGN.md §6): offline snapshot, TTL
            //    enforced on read, agent-bound, audited.
            let mut tapfree_served: Option<(ServedBatch, String)> = None;
            if matches!(be, Backend::Vault) {
                let mut got = Vec::with_capacity(names.len());
                for name in &names {
                    match session::request_value(&dir, &project, name) {
                        Some(v) => got.push((name.clone(), v)),
                        None => {
                            got.clear();
                            break;
                        }
                    }
                }
                if got.len() == names.len() && !names.is_empty() {
                    tapfree_served =
                        Some((got, "session broker (grant-checked, tap-free)".to_string()));
                }

                if tapfree_served.is_none() {
                    if let Ok(ks) = lease::keystore_from_env() {
                        let caller = registry::resolve_agent();
                        let t = lease::now();
                        let mut got = Vec::with_capacity(names.len());
                        for name in &names {
                            match lease::read(&dir, ks, &project, name, caller.as_deref(), t) {
                                lease::ReadOutcome::Served(v) => got.push((name.clone(), v)),
                                _ => {
                                    got.clear();
                                    break;
                                }
                            }
                        }
                        if got.len() == names.len() && !names.is_empty() {
                            let left = lease::expires_at(&dir, ks, &project)
                                .map(|e| lease::human_secs(e.saturating_sub(t)))
                                .unwrap_or_else(|| "?".to_string());
                            tapfree_served =
                                Some((got, format!("project lease (tap-free, {left} left)")));
                        }
                    }
                }
            }

            let mut injected = 0usize;
            let mut missing: Vec<&str> = Vec::new();

            if let Some((served, via)) = &tapfree_served {
                eprintln!("secrets exec: {} secret(s) via {via}", served.len());
                for (name, value) in served {
                    cmd.env(name, std::ffi::OsStr::new(&String::from_utf8_lossy(value).into_owned()));
                    injected += 1;
                }
            } else {
                // Resolve the calling agent up front — it feeds both the enriched
                // Touch ID prompt (the "who") and the approval enforcement below.
                let agent = registry::resolve_agent();

                // One Touch ID: unlock once (native sheet surfaces even headless);
                // the same key material covers the registry AND the per-key vault
                // reads — no second prompt. The sheet names the keys/project/agent
                // and the human --reason instead of a bare "authenticate" default.
                let prompt = exec_prompt(&project, &names, agent.as_deref(), reason.as_deref());
                let view = unlock_view(&prompt);
                let reg = view.registry_load(&dir).unwrap_or_else(|e| {
                    eprintln!("Error: {e}");
                    process::exit(1);
                });

                // Enforcement: a recognized agent must hold a valid grant for this
                // project — or earn one via real-time approval in aiconductor
                // (registry-anchored, NOT the forgeable response file). The request
                // lists the ENTIRE key batch, so the human reviews/authorizes all
                // of it in one consent. A human / unrecognized operator who
                // satisfied Touch ID proceeds.
                if let Some(agent) = agent {
                    if reg.grant_for(&agent, &project, registry::now()).is_none()
                        && !ipc_approval(
                            &agent, &project, &command[0], &names, reason.as_deref(), &dir, &view,
                        )
                    {
                        eprintln!("'{agent}' was not granted access to '{project}'.");
                        eprintln!("Or pre-authorize out-of-band:  secrets authorize {agent} {project}");
                        process::exit(1);
                    }
                    eprintln!("secrets exec: agent '{agent}' authorized for '{project}'.");
                }

                // Inject the project-scoped values under their clean env-var names.
                // Values go ONLY into the child's env, never argv.
                match &be {
                    Backend::Vault => {
                        // v2: decrypt EXACTLY the declared keys (G2) — nothing else
                        // in the vault is ever materialized. Scoped override
                        // first, bare shared value second (see get_project).
                        for name in &names {
                            match view.get_project(&project, name) {
                                Some(value) => {
                                    cmd.env(
                                        name,
                                        std::ffi::OsStr::new(
                                            &String::from_utf8_lossy(&value).into_owned(),
                                        ),
                                    );
                                    injected += 1;
                                }
                                None => missing.push(name.as_str()),
                            }
                        }
                        if !missing.is_empty() {
                            eprintln!("warning: not in vault, skipped: {}", missing.join(", "));
                        }
                    }
                    external => {
                        eprintln!(
                            "secrets exec: pulling {} secret(s) from {}",
                            names.len(),
                            external.label()
                        );
                        for name in &names {
                            match external.access(name) {
                                // Value already has its trailing newline handled by the
                                // backend; goes ONLY into the child's env, never argv.
                                Ok(value) => {
                                    cmd.env(name, value);
                                    injected += 1;
                                }
                                Err(e) => {
                                    eprintln!("  ! {name}: {e}");
                                    missing.push(name.as_str());
                                }
                            }
                        }
                        if !missing.is_empty() {
                            eprintln!(
                                "warning: could not fetch from {}, skipped: {}",
                                external.label(),
                                missing.join(", ")
                            );
                        }
                    }
                }
            }
            eprintln!(
                "secrets exec: injecting {injected} secret(s) into `{}` (project: {project})",
                command[0]
            );

            let mut child = cmd.spawn().unwrap_or_else(|e| {
                eprintln!("Failed to spawn `{}`: {e}", command[0]);
                process::exit(127);
            });

            let status = child.wait().unwrap_or_else(|e| {
                eprintln!("Failed waiting for child: {e}");
                process::exit(1);
            });

            // Forward the child's exact exit code so CI/scripts see the real
            // result (signal → 128 + signo, matching shell convention).
            #[cfg(unix)]
            let code = {
                use std::os::unix::process::ExitStatusExt;
                status
                    .code()
                    .or_else(|| status.signal().map(|s| 128 + s))
                    .unwrap_or(1)
            };
            #[cfg(not(unix))]
            let code = status.code().unwrap_or(1);
            process::exit(code);
        }

        Commands::Authorize { agent, project, session_minutes } => {
            let view = unlock_view(&format!("Authorize '{agent}' for project '{project}'")); // Touch ID
            let dir = secrets_dir();
            let mut reg = view.registry_load(&dir).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            let scope = match session_minutes {
                Some(m) => registry::Scope::Session { expires: registry::now() + m * 60 },
                None => registry::Scope::Always,
            };
            reg.set_grant(&agent, &project, scope);
            view.registry_save(&reg, &dir).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            match session_minutes {
                Some(m) => eprintln!("Authorized '{agent}' → '{project}' for {m} min."),
                None => eprintln!("Authorized '{agent}' → '{project}' (permanent)."),
            }
        }

        Commands::Revoke { agent, project } => {
            let view = unlock_view(&format!("Revoke '{agent}' from project '{project}'"));
            let dir = secrets_dir();
            let mut reg = view.registry_load(&dir).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            if reg.revoke(&agent, &project) {
                view.registry_save(&reg, &dir).unwrap_or_else(|e| {
                    eprintln!("Error: {e}");
                    process::exit(1);
                });
                eprintln!("Revoked '{agent}' → '{project}'.");
            } else {
                eprintln!("No grant for '{agent}' → '{project}'.");
                process::exit(1);
            }
        }

        Commands::ListProjects { json } => {
            let view = unlock_view("List projects and agent grants");
            let dir = secrets_dir();
            let reg = view.registry_load(&dir).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            if json {
                let now = registry::now();
                let projects: Vec<serde_json::Value> = reg
                    .projects
                    .iter()
                    .map(|(name, meta)| {
                        // The COUNT, not the names: this is the registry's own
                        // view and the key list belongs to `list`.
                        serde_json::json!({
                            "name": name,
                            "gcp_project": meta.gcp_project,
                            "keys": meta.keys.len(),
                        })
                    })
                    .collect();
                let mut grants: Vec<serde_json::Value> = Vec::new();
                for (agent, projs) in &reg.grants {
                    for (project, grant) in projs {
                        // `expires_in_secs` rather than an absolute stamp: the
                        // caller wants "how long left", and a clock difference
                        // between writer and reader cannot corrupt a duration.
                        let (scope, left) = match grant.scope {
                            registry::Scope::Always => ("permanent", None),
                            registry::Scope::Session { expires } if expires > now => {
                                ("session", Some(expires - now))
                            }
                            registry::Scope::Session { .. } => ("expired", Some(0)),
                        };
                        grants.push(serde_json::json!({
                            "agent": agent,
                            "project": project,
                            "scope": scope,
                            "expires_in_secs": left,
                        }));
                    }
                }
                println!(
                    "{}",
                    serde_json::json!({ "projects": projects, "grants": grants })
                );
                return;
            }
            if reg.projects.is_empty() && reg.grants.is_empty() {
                println!("(registry empty — no projects or grants yet)");
            } else {
                let now = registry::now();
                if !reg.projects.is_empty() {
                    println!("Projects:");
                    for (name, meta) in &reg.projects {
                        println!("  {name} → {} ({} keys)", meta.gcp_project, meta.keys.len());
                    }
                }
                println!("Grants:");
                for (agent, projs) in &reg.grants {
                    for (project, grant) in projs {
                        let scope = match grant.scope {
                            registry::Scope::Always => "permanent".to_string(),
                            registry::Scope::Session { expires } if expires > now => {
                                format!("session, {}m left", (expires - now) / 60)
                            }
                            registry::Scope::Session { .. } => "expired".to_string(),
                        };
                        println!("  {agent} → {project} [{scope}]");
                    }
                }
            }
        }

        Commands::Lease { sub } => {
            let dir = secrets_dir();
            let ks = lease::keystore_from_env().unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            match sub {
                LeaseCmd::Create { project, ttl, agent, any_agent } => {
                    if !secrets_vault::is_valid_project(&project) {
                        eprintln!("Invalid project: '{project}'");
                        process::exit(1);
                    }
                    let (names, be, win) = load_manifest(&project).unwrap_or_else(|e| {
                        eprintln!("Error: {e}");
                        process::exit(1);
                    });
                    // Expiry: a windowed project with an `until` bound is
                    // authorized to that bound (the schedule IS the boundary);
                    // an explicit --ttl always caps it. Without a window this
                    // is the classic TTL lease.
                    let now = lease::now();
                    let explicit_ttl = ttl.as_deref().map(|t| {
                        lease::parse_ttl(t).unwrap_or_else(|e| {
                            eprintln!("Error: {e}");
                            process::exit(1);
                        })
                    });
                    let until_end: Option<u64> = win
                        .as_ref()
                        .and_then(|w| w.end_of_authorisation().transpose())
                        .transpose()
                        .unwrap_or_else(|e| {
                            eprintln!("Error: {e}");
                            process::exit(1);
                        })
                        .map(|t| t.max(0) as u64);
                    if let Some(end) = until_end {
                        if end <= now {
                            eprintln!(
                                "Error: the window for '{project}' ended on its `until` date — nothing left to lease."
                            );
                            process::exit(1);
                        }
                    }
                    let ttl_secs = match (explicit_ttl, until_end) {
                        (Some(t), Some(end)) => t.min(end - now),
                        (Some(t), None) => t,
                        (None, Some(end)) => end - now,
                        (None, None) => lease::parse_ttl(lease::DEFAULT_TTL).expect("default TTL parses"),
                    };
                    // The 24h warning is about a long CONTINUOUS tap-free span;
                    // a windowed lease is only readable inside its hours, so
                    // the warning would misread the trade being approved.
                    if win.is_none() && ttl_secs > lease::TTL_WARN_SECS {
                        eprintln!(
                            "⚠️  TTL {} exceeds 24h — that is a long tap-free window; consider shorter.",
                            lease::human_secs(ttl_secs)
                        );
                    }
                    if !matches!(be, Backend::Vault) {
                        eprintln!(
                            "Leases snapshot the LOCAL vault; project '{project}' uses {}.",
                            be.label()
                        );
                        process::exit(1);
                    }
                    // Soft binding: explicit --agent wins; --any-agent leaves it
                    // open; default is whoever's ancestry is driving this create.
                    let agent = if any_agent { None } else { agent.or_else(registry::resolve_agent) };

                    // THE tap. The sheet names keys, project, TTL, and binding —
                    // exactly the trade being approved (LEASE_DESIGN.md §5).
                    let key_list = if names.len() <= 4 {
                        names.join(", ")
                    } else {
                        format!("{} +{} more", names[..4].join(", "), names.len() - 4)
                    };
                    // The sheet must name the WINDOW when there is one — that
                    // schedule, not a duration, is what the human approves.
                    let span = match &win {
                        Some(w) => format!("inside {}", w.describe()),
                        None => format!("for {}", lease::human_secs(ttl_secs)),
                    };
                    let prompt = format!(
                        "Lease {key_list} for “{project}” — tap-free reads {span}{}",
                        match &agent {
                            Some(a) => format!(", bound to agent {a}"),
                            None => ", any local caller".to_string(),
                        }
                    );
                    let view = unlock_view(&prompt);

                    // Decrypt exactly the declared keys (bare names inside the
                    // lease — the file itself is the project scope). Scoped
                    // override first, bare shared value second (get_project).
                    let mut entries: Vec<(String, Zeroizing<Vec<u8>>)> = Vec::new();
                    let mut absent: Vec<&str> = Vec::new();
                    for name in &names {
                        match view.get_project(&project, name) {
                            Some(v) => entries.push((name.clone(), v)),
                            None => absent.push(name.as_str()),
                        }
                    }
                    if !absent.is_empty() {
                        eprintln!("warning: not in vault, not leased: {}", absent.join(", "));
                    }
                    if entries.is_empty() {
                        eprintln!("Error: none of '{project}'s declared keys are in the vault.");
                        process::exit(1);
                    }
                    let stored = entries.len();
                    let expires =
                        lease::create(&dir, ks, &project, &entries, ttl_secs, agent.as_deref(), win.as_ref(), now)
                            .unwrap_or_else(|e| {
                                eprintln!("Error: {e}");
                                process::exit(1);
                            });
                    // Keep the registry consistent with the lease window: if
                    // the bound agent holds no current grant, record a Session
                    // grant expiring with the lease (so the Touch-ID fallback
                    // path and list-projects tell the same story).
                    if let Some(a) = &agent {
                        if let Ok(mut reg) = view.registry_load(&dir) {
                            if reg.grant_for(a, &project, registry::now()).is_none() {
                                reg.set_grant(a, &project, registry::Scope::Session { expires });
                                if let Err(e) = view.registry_save(&reg, &dir) {
                                    eprintln!("(warning: could not record session grant: {e})");
                                }
                            }
                        }
                    }
                    eprintln!(
                        "Leased {stored} secret(s) for '{project}' — tap-free {}{}.",
                        match &win {
                            Some(w) => format!("inside {} (outer bound {})",
                                w.describe(), lease::human_secs(ttl_secs)),
                            None => format!("for {}", lease::human_secs(ttl_secs)),
                        },
                        match &agent {
                            Some(a) => format!(", bound to agent '{a}'"),
                            None => ", any local caller".to_string(),
                        }
                    );
                    eprintln!(
                        "Reads: secrets get KEY -p {project}   (or: secrets exec {project} -- cmd)"
                    );
                    eprintln!("Ends: at expiry, or now via `secrets lease revoke {project}`.");
                }

                LeaseCmd::Get { project, key } => {
                    if !is_valid_key(&key) {
                        eprintln!("Invalid key: '{key}'");
                        process::exit(1);
                    }
                    match lease::read(
                        &dir,
                        ks,
                        &project,
                        &key,
                        registry::resolve_agent().as_deref(),
                        lease::now(),
                    ) {
                        lease::ReadOutcome::Served(value) => {
                            io::Write::write_all(&mut io::stdout(), &value).ok();
                        }
                        lease::ReadOutcome::NoLease => {
                            eprintln!(
                                "No lease for '{project}'. Create one (one tap): secrets lease create {project}"
                            );
                            process::exit(1);
                        }
                        lease::ReadOutcome::Expired => {
                            eprintln!("Lease for '{project}' has expired — it was just destroyed.");
                            process::exit(1);
                        }
                        lease::ReadOutcome::Denied => {
                            eprintln!("Lease for '{project}' is bound to a different agent.");
                            process::exit(1);
                        }
                        lease::ReadOutcome::NotInLease => {
                            eprintln!("'{key}' is not in the lease for '{project}' (only the keys approved at create are served).");
                            process::exit(1);
                        }
                        lease::ReadOutcome::Error(e) => {
                            eprintln!("Error: {e}");
                            process::exit(1);
                        }
                    }
                }

                LeaseCmd::Status { json } => {
                    let rows = lease::status(&dir, ks, lease::now());
                    if json {
                        let t = lease::now();
                        // Note the scan PURGES as it reads, so the purged states
                        // are reported too: a caller that only saw "active" rows
                        // could not tell "nothing was there" from "it expired
                        // just now and I destroyed it", and those differ.
                        let leases: Vec<serde_json::Value> = rows
                            .iter()
                            .map(|(project, state)| match state {
                                lease::LeaseState::Active { expires, agent, keys, window } => {
                                    let mut row = serde_json::json!({
                                        "project": project,
                                        "state": "active",
                                        "keys": keys,
                                        "expires_in_secs": expires.saturating_sub(t),
                                        "agent": agent,
                                    });
                                    if let Some(w) = window {
                                        // Next open/close, not a duration —
                                        // the caller wants "can the next fire
                                        // read", which a remaining span of a
                                        // mostly-closed lease cannot answer.
                                        row["window"] = serde_json::json!({
                                            "schedule": w.describe(),
                                        });
                                        match w.state(t) {
                                            Ok(window::State::Open { closes }) => {
                                                row["window"]["state"] = "open".into();
                                                row["window"]["closes_in_secs"] =
                                                    ((closes - t as i64).max(0)).into();
                                            }
                                            Ok(window::State::Closed { next_open }) => {
                                                row["window"]["state"] = "closed".into();
                                                if let Some(n) = next_open {
                                                    row["window"]["opens_in_secs"] =
                                                        ((n - t as i64).max(0)).into();
                                                }
                                            }
                                            Err(e) => {
                                                row["window"]["state"] = "unevaluable".into();
                                                row["window"]["error"] = e.into();
                                            }
                                        }
                                    }
                                    row
                                }
                                lease::LeaseState::ExpiredPurged => serde_json::json!({
                                    "project": project, "state": "expired_purged",
                                }),
                                lease::LeaseState::OrphanPurged => serde_json::json!({
                                    "project": project, "state": "orphan_purged",
                                }),
                                lease::LeaseState::Corrupt(e) => serde_json::json!({
                                    "project": project, "state": "corrupt", "error": e,
                                }),
                            })
                            .collect();
                        // An empty array, NOT a sentence on stderr: one shape to
                        // parse whether or not anything is leased.
                        println!("{}", serde_json::json!({ "leases": leases }));
                        return;
                    }
                    if rows.is_empty() {
                        eprintln!("No leases.");
                        return;
                    }
                    let t = lease::now();
                    for (project, state) in rows {
                        match state {
                            lease::LeaseState::Active { expires, agent, keys, window } => {
                                let sched = match &window {
                                    None => format!("{} left", lease::human_secs(expires.saturating_sub(t))),
                                    Some(w) => {
                                        let phase = match w.state(t) {
                                            Ok(window::State::Open { closes }) => format!(
                                                "OPEN, closes in {}",
                                                lease::human_secs((closes - t as i64).max(0) as u64)
                                            ),
                                            Ok(window::State::Closed { next_open: Some(n) }) => format!(
                                                "closed, opens in {}",
                                                lease::human_secs((n - t as i64).max(0) as u64)
                                            ),
                                            Ok(window::State::Closed { next_open: None }) =>
                                                "closed, never opens again".to_string(),
                                            Err(e) => format!("window unevaluable ({e}) — reads refused"),
                                        };
                                        format!("window {} — {}", w.describe(), phase)
                                    }
                                };
                                println!(
                                    "{project}: {} key(s) [{}] — {sched}{}",
                                    keys.len(),
                                    keys.join(", "),
                                    match agent {
                                        Some(a) => format!(", bound to '{a}'"),
                                        None => ", any local caller".to_string(),
                                    }
                                );
                            }
                            lease::LeaseState::ExpiredPurged => {
                                println!("{project}: expired — destroyed");
                            }
                            lease::LeaseState::OrphanPurged => {
                                println!("{project}: orphaned lease artifact — removed");
                            }
                            lease::LeaseState::Corrupt(e) => {
                                println!("{project}: CORRUPT — {e} (fix: secrets lease revoke {project})");
                            }
                        }
                    }
                }

                LeaseCmd::Revoke { project } => {
                    if lease::revoke(&dir, ks, &project) {
                        eprintln!(
                            "Lease for '{project}' destroyed (key crypto-erased, file removed)."
                        );
                    } else {
                        eprintln!("No lease for '{project}'.");
                        process::exit(1);
                    }
                }
            }
        }

        Commands::Migrate => {
            let dir = secrets_dir();
            let Some(data) = read_vault_bytes() else {
                eprintln!("No vault to migrate — a new vault is created as v2 automatically.");
                process::exit(1);
            };
            if is_v2(&data) {
                // Vault already v2 — still convert a straggler v1 registry.
                let reg_path = registry::Registry::path(&dir);
                let reg_is_v1 = fs::read(&reg_path)
                    .map(|d| d.starts_with(b"QVLT"))
                    .unwrap_or(false);
                if !reg_is_v1 {
                    eprintln!("Vault is already QVLT v2 — nothing to migrate.");
                    return;
                }
                let salt = v2_salt(&data).unwrap_or_else(|e| {
                    eprintln!("Error: {e}");
                    process::exit(1);
                });
                let pass = get_passphrase_prompted("Migrate the grant registry to v2");
                let reg = registry::Registry::load_v1(&dir, &pass).unwrap_or_else(|e| {
                    eprintln!("Error: {e}");
                    process::exit(1);
                });
                let master = MasterSecret::derive(&pass, &salt);
                drop(pass);
                if VaultReader::open(data, &master).is_err() {
                    eprintln!("Error: wrong passphrase");
                    process::exit(1);
                }
                reg.save_raw(&dir, &master.registry_key()).unwrap_or_else(|e| {
                    eprintln!("Error: {e}");
                    process::exit(1);
                });
                eprintln!("Registry converted to the v2 raw-key container.");
                return;
            }
            if !is_v1(&data) {
                eprintln!("Error: vault file is not a recognized QVLT format");
                process::exit(1);
            }

            // ONE unlock: decrypt the v1 vault (this is the last-ever full
            // decrypt), convert the registry with the same passphrase, then
            // derive the v2 master under a FRESH salt and zeroize.
            let pass = get_passphrase_prompted("Migrate vault to v2 (per-entry encryption)");
            let vault = match Vault::decrypt(&data, &pass) {
                Ok(v) => v,
                Err(VaultError::DecryptionFailed) => {
                    eprintln!("Error: wrong passphrase");
                    process::exit(1);
                }
                Err(e) => {
                    eprintln!("Error: {e}");
                    process::exit(1);
                }
            };
            let reg_path = registry::Registry::path(&dir);
            let legacy_reg = if fs::read(&reg_path)
                .map(|d| d.starts_with(b"QVLT"))
                .unwrap_or(false)
            {
                Some(registry::Registry::load_v1(&dir, &pass).unwrap_or_else(|e| {
                    eprintln!("Error: {e}");
                    process::exit(1);
                }))
            } else {
                None
            };
            let master = MasterSecret::derive(&pass, &random_salt());
            drop(pass);

            let entries: Vec<(String, Zeroizing<Vec<u8>>)> = vault
                .iter()
                .map(|(k, v)| (k.to_string(), Zeroizing::new(v.as_bytes().to_vec())))
                .collect();
            let count = entries.len();
            let out = v2_create(&master, &entries).unwrap_or_else(|e| {
                eprintln!("Error encrypting v2 vault: {e}");
                process::exit(1);
            });

            // Preserve the v1 ciphertext as a backup FIRST (0600), then the
            // atomic v2 replace. `rekey` will nag about this file until deleted.
            let backup = vault_path().with_extension("qvlt.v1.bak");
            #[cfg(unix)]
            {
                use std::os::unix::fs::OpenOptionsExt;
                if let Ok(mut f) = fs::OpenOptions::new()
                    .write(true)
                    .create(true)
                    .truncate(true)
                    .mode(0o600)
                    .open(&backup)
                {
                    io::Write::write_all(&mut f, &data).ok();
                }
            }
            #[cfg(not(unix))]
            fs::write(&backup, &data).ok();

            let names: Vec<String> = vault.keys().map(String::from).collect();
            write_v2_vault(&out, &names);
            if let Some(reg) = legacy_reg {
                reg.save_raw(&dir, &master.registry_key()).unwrap_or_else(|e| {
                    eprintln!("Error converting registry: {e}");
                    process::exit(1);
                });
            }
            // A live v1 broker is a passphrase dispenser — kill it.
            session::end(&dir);

            eprintln!("Migrated {count} secret(s) to QVLT v2 (per-entry encryption).");
            eprintln!("Reads now decrypt ONLY the requested key; writes splice without reading.");
            eprintln!("v1 backup kept at {} — delete it once confident:", backup.display());
            eprintln!("  trash {}", backup.display());
        }

        Commands::Rekey => {
            let dir = secrets_dir();
            let Some(data) = read_vault_bytes() else {
                eprintln!("No vault to rekey.");
                process::exit(1);
            };
            if is_v1(&data) {
                migrate_hint();
                eprintln!("`secrets rekey` requires a v2 vault.");
                process::exit(1);
            }
            let salt = v2_salt(&data).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            let pass = get_passphrase_prompted("Rekey your secrets vault (fresh salt)");
            let old_master = MasterSecret::derive(&pass, &salt);
            let new_master = MasterSecret::derive(&pass, &random_salt());
            drop(pass);

            let reader = open_reader(data, &old_master);
            let vault = reader.decrypt_all(&old_master).unwrap_or_else(|e| {
                eprintln!("Error: {e}");
                process::exit(1);
            });
            let reg = registry::Registry::load_raw(&dir, &old_master.registry_key())
                .unwrap_or_default();

            // A live broker holds keys derived from the OLD salt — every
            // request after the rewrite would fail its MAC check. End it now,
            // loudly (spec §5.1).
            if session::socket_path(&dir).exists() {
                session::end(&dir);
                eprintln!("(ended the live session broker — its keys predate the rekey)");
            }
            // A live lease IS old key material with a sanctioned no-tap read
            // path — a rekey that left it alive would revoke nothing
            // (LEASE_DESIGN.md §6).
            if let Ok(ks) = lease::keystore_from_env() {
                let n = lease::revoke_all(&dir, ks);
                if n > 0 {
                    eprintln!("(revoked {n} live lease(s) — they served pre-rekey values tap-free)");
                }
            }

            let entries: Vec<(String, Zeroizing<Vec<u8>>)> = vault
                .iter()
                .map(|(k, v)| (k.to_string(), Zeroizing::new(v.as_bytes().to_vec())))
                .collect();
            let out = v2_create(&new_master, &entries).unwrap_or_else(|e| {
                eprintln!("Error encrypting: {e}");
                process::exit(1);
            });
            let names: Vec<String> = vault.keys().map(String::from).collect();
            write_v2_vault(&out, &names);
            reg.save_raw(&dir, &new_master.registry_key()).unwrap_or_else(|e| {
                eprintln!("Error re-encrypting registry: {e}");
                process::exit(1);
            });
            eprintln!("Rekeyed {} secret(s) under a fresh salt.", entries.len());

            // A rekey that leaves old-key ciphertext on disk has not revoked
            // anything — name every stale sibling loudly (spec §5.1).
            let mut stale: Vec<PathBuf> = Vec::new();
            for cand in [vault_path().with_extension("qvlt.v1.bak"), dir.join(".vault.qvlt.tmp")] {
                if cand.exists() {
                    stale.push(cand);
                }
            }
            if !stale.is_empty() {
                eprintln!("⚠️  STALE CIPHERTEXT still on disk — the old key material opens these:");
                for s in &stale {
                    eprintln!("   {}", s.display());
                }
                eprintln!("   Delete them (trash <file>) or this rekey revokes nothing.");
            }
        }

        Commands::Inbox { sub } => {
            let dir = secrets_dir();
            match sub {
                InboxCmd::Init => match inbox::ensure_recipient(&dir) {
                    Ok(_) => eprintln!(
                        "Inbox ready — recipient at {} (identity in the Keychain).",
                        inbox::pub_path(&dir).display()
                    ),
                    Err(e) => {
                        eprintln!("Error: {e}");
                        process::exit(1);
                    }
                },

                InboxCmd::List => {
                    let entries = inbox::read_entries(&dir).unwrap_or_default();
                    if entries.is_empty() {
                        eprintln!("Inbox empty — nothing pending.");
                    } else {
                        // new-vs-overwrite from the plaintext name index — no Touch ID.
                        let index = read_index();
                        eprintln!("{} pending (review, then `secrets inbox merge`):", entries.len());
                        for e in &entries {
                            let tag = if index.iter().any(|k| k == &e.name) {
                                "⚠ OVERWRITE"
                            } else {
                                "new"
                            };
                            println!("  {}  [{tag}]", e.name);
                        }
                    }
                }

                InboxCmd::Drop { name } => match inbox::drop_entry(&dir, &name) {
                    Ok(true) => eprintln!("Dropped pending '{name}'."),
                    Ok(false) => {
                        eprintln!("No pending entry named '{name}'.");
                        process::exit(1);
                    }
                    Err(e) => {
                        eprintln!("Error: {e}");
                        process::exit(1);
                    }
                },

                InboxCmd::Merge => {
                    let entries = match inbox::read_entries(&dir) {
                        Ok(e) => e,
                        Err(e) => {
                            eprintln!("Error: {e}");
                            process::exit(1);
                        }
                    };
                    if entries.is_empty() {
                        eprintln!("Inbox empty — nothing to merge.");
                        return;
                    }

                    // ONE tap (non-strict): open the inbox identity + the vault master
                    // under a single shared auth context. Strict mode → a fresh tap each.
                    let vals = match keychain::read_accounts(
                        &["inbox-identity", "vault-master"],
                        is_strict_mode(),
                    ) {
                        Ok(v) => v,
                        Err(e) => {
                            eprintln!("Keychain error: {e}");
                            process::exit(1);
                        }
                    };

                    let identity_str = match vals.first().cloned().flatten() {
                        Some(s) => s,
                        None => {
                            eprintln!("Inbox identity not found — run `secrets inbox init` first.");
                            process::exit(1);
                        }
                    };
                    let identity: age::x25519::Identity = match identity_str.parse() {
                        Ok(i) => i,
                        Err(e) => {
                            eprintln!("Corrupt inbox identity: {e}");
                            process::exit(1);
                        }
                    };

                    // Master: env override → the keychain read above.
                    let master = match env::var("SECRETS_PASSPHRASE")
                        .ok()
                        .or_else(|| vals.get(1).cloned().flatten())
                    {
                        Some(m) => Zeroizing::new(m),
                        None => {
                            eprintln!("Vault is locked — run `secrets unlock` first.");
                            process::exit(1);
                        }
                    };

                    // One unlock covers the whole merge; v2 splices the batch in
                    // without decrypting any existing entry.
                    let mut view = view_from_passphrase(master);
                    let mut new_keys: Vec<String> = Vec::new();
                    let mut overwrites: Vec<String> = Vec::new();
                    let mut failed: Vec<(String, String)> = Vec::new();
                    let mut upserts: Vec<(String, Zeroizing<Vec<u8>>)> = Vec::new();

                    for e in &entries {
                        match inbox::open(&identity, &e.sealed) {
                            Ok(value) => {
                                if view.contains(&e.name) {
                                    overwrites.push(e.name.clone());
                                } else {
                                    new_keys.push(e.name.clone());
                                }
                                upserts.push((e.name.clone(), Zeroizing::new(value.into_bytes())));
                            }
                            Err(err) => failed.push((e.name.clone(), err)),
                        }
                    }

                    if new_keys.is_empty() && overwrites.is_empty() {
                        eprintln!("Nothing merged — all entries failed to open:");
                        for (n, err) in &failed {
                            eprintln!("  ✗ {n}: {err}");
                        }
                        process::exit(1);
                    }

                    view.write(upserts, vec![]); // also refreshes the name index

                    // Keep only entries that failed to open; remove the merged ones.
                    use std::collections::HashSet;
                    let merged: HashSet<&String> =
                        new_keys.iter().chain(overwrites.iter()).collect();
                    let leftover: Vec<&inbox::Entry> =
                        entries.iter().filter(|e| !merged.contains(&e.name)).collect();
                    if let Err(e) = inbox::rewrite(&dir, &leftover) {
                        eprintln!("(warning: could not rewrite inbox: {e})");
                    }

                    eprintln!(
                        "Merged {} new + {} overwrite into the vault:",
                        new_keys.len(),
                        overwrites.len()
                    );
                    for n in &new_keys {
                        eprintln!("  + {n} (new)");
                    }
                    for n in &overwrites {
                        eprintln!("  ⚠ {n} (OVERWRITE)");
                    }
                    for (n, err) in &failed {
                        eprintln!("  ✗ {n}: {err} (left in inbox)");
                    }
                }
            }
        }
    }
}