@gobius/t3ctl 0.5.0 → 0.7.0

package/dist/t3ctl.js

@@ -2,7 +2,10 @@
 // t3ctl — a controller CLI for T3 Code hosts.
 // Peer of the mobile app: pairs once per host, then reads/controls remotely.
 // Spike scope: host registry + read-only listing.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
+import net from 'node:net';
 import { Command } from 'commander';
 import os from 'node:os';
 import path from 'node:path';
@@ -18,6 +21,7 @@ const writeHosts = (hosts) => {
     fs.writeFileSync(HOSTS_FILE, JSON.stringify({ hosts }, null, 2), { mode: 0o600 });
 };
 const snapshot = async (host) => {
+    await ensureTunnel(host);
     const res = await fetch(`${host.origin}/api/orchestration/snapshot`, {
         headers: host.token ? { authorization: `Bearer ${host.token}` } : {},
         signal: AbortSignal.timeout(host.timeoutMs ?? 15000),
@@ -78,7 +82,7 @@ const cmdLs = async ({ threads: showThreads, all: showAll, json: asJson }) => {
     const hosts = readHosts();
     if (!hosts.length)
         return console.error('No hosts registered. Run: t3ctl host add <origin> <token>');
-    const { ok, failed } = await collect(hosts);
+    const [{ ok, failed }] = await Promise.all([collect(hosts), warnRivals(hosts)]);
     if (asJson) {
         const out = ok.flatMap(({ host, snap }) => snap.projects
             .filter((p) => showAll || !p.deletedAt)
@@ -183,7 +187,10 @@ const cmdHostAdd = async (pos, flags, hosts) => {
         return usage(HOST_ADD_USAGE);
     const origin = parsed.origin.replace(/\/$/, '');
     const descriptor = await probe(origin);
-    const existing = hosts.find((h) => h.origin === origin);
+    // Re-pointing a named host at another port of the same environment (see the
+    // split-brain guard) keeps its token: both ports serve one auth database.
+    const existing = hosts.find((h) => h.origin === origin) ??
+        hosts.find((h) => !h.ssh && h.name === flags.name && h.environmentId === descriptor.environmentId);
     // A changed environmentId on a known origin means the origin now points at a
     // different machine — the stored token almost certainly belongs to the old one.
     if (existing?.environmentId && existing.environmentId !== descriptor.environmentId) {
@@ -214,6 +221,7 @@ const cmdHostAdd = async (pos, flags, hosts) => {
 const cmdHostsList = async (hosts) => {
     if (!hosts.length)
         return console.log('(no hosts)');
+    await Promise.allSettled(hosts.filter((h) => h.ssh).map((h) => ensureTunnel(h)));
     const probes = await Promise.allSettled(hosts.map((h) => probe(h.origin)));
     const drifted = [];
     hosts.forEach((h, i) => {
@@ -228,13 +236,372 @@ const cmdHostsList = async (hosts) => {
         // Values for an unreachable host are whatever was last stored, so dim the
         // whole row to keep remembered data visually distinct from probed data.
         const cell = (text, width) => (live ? text.padEnd(width) : dim(text.padEnd(width)));
-        console.log(`${icon} ${live ? bold(h.name.padEnd(14)) : dim(h.name.padEnd(14))} ${cell(label, 18)} ${dim(env.padEnd(9))} ${cell(version, 28)} ${dim(h.origin)}` +
+        const where = dim(h.ssh ? `${h.ssh} -> ${h.origin}` : h.origin);
+        console.log(`${icon} ${live ? bold(h.name.padEnd(14)) : dim(h.name.padEnd(14))} ${cell(label, 18)} ${dim(env.padEnd(9))} ${cell(version, 28)} ${where}` +
             (live || !p || p.status !== 'rejected' ? '' : ` ${dim(errorMessage(p.reason))}`));
     });
     for (const { h, live } of drifted) {
         warn(`${h.name} (${h.origin}) is now a DIFFERENT environment\n` +
             `  was ${h.environmentId} (${h.label ?? 'unknown'})\n  now ${live.environmentId} (${live.label})`);
     }
+    await warnRivals(hosts);
+};
+// ---- ssh hosts ----------------------------------------------------------
+// `t3ctl host add agent@box` fully bootstraps a remote T3 Code host: detect a
+// running server, install the boot service if none, mint a token, and keep a
+// local ssh port-forward alive. Three properties of T3 Code make "just an ssh
+// login" enough:
+//   * the server records {pid, port} in ~/.t3/userdata/server-runtime.json, so
+//     the port is discoverable, never hardcoded (3773 or an ephemeral fallback,
+//     rewritten on every start);
+//   * `t3 auth session issue` mints a bearer token filesystem-locally — no HTTP,
+//     no --port — valid for the already-running server sharing ~/.t3, so t3ctl
+//     can mint its own token over ssh;
+//   * `t3 service install` is per-user launchd/systemd (no sudo, macOS/Linux).
+// Remote shell scripts pass data back on stdout as lines starting with a
+// marker, parsed bottom-up: `t3 auth` can leak Effect error logs onto stdout
+// (the desktop's own SSH path parses the same way, tunnel.ts:791).
+// npm package is literally `t3`; exact versions are pinned because the boot
+// service installs that same version into its pinned runtime.
+const SSH_READY_MS = 90_000; // server readiness after install (npm download can be slow)
+const TUNNEL_WAIT_MS = 30_000; // ssh auth may prompt interactively; give it time
+const PROBE_MS = 2500; // liveness probe of the local tunnel end
+const T3_PACKAGE = 't3';
+const SSH_SCRIPT = `set -eu
+# PATH discovery for NON-INTERACTIVE ssh shells, trimmed from T3 Code's own
+# remote runner (packages/ssh/src/tunnel.ts REMOTE_NODE_ENV_SCRIPT): plain PATH
+# additions, version-manager shims, nvm. Engine checks and the "prefer installed
+# t3" branch are dropped on purpose — t3ctl pins an exact version and runs npx.
+prepend_path_if_dir() {
+  if [ -d "$1" ]; then
+    case ":$PATH:" in
+      *":$1:"*) ;;
+      *) PATH="$1:$PATH" ;;
+    esac
+  fi
+}
+ensure_node_path() {
+  command -v node >/dev/null 2>&1 && return 0
+  prepend_path_if_dir "$HOME/.local/bin"
+  prepend_path_if_dir "$HOME/bin"
+  prepend_path_if_dir "/opt/homebrew/bin"
+  prepend_path_if_dir "/usr/local/bin"
+  prepend_path_if_dir "/usr/bin"
+  prepend_path_if_dir "/bin"
+  if [ -z "\${VOLTA_HOME:-}" ]; then VOLTA_HOME="$HOME/.volta"; fi
+  prepend_path_if_dir "$VOLTA_HOME/bin"
+  prepend_path_if_dir "$HOME/.asdf/shims"
+  prepend_path_if_dir "$HOME/.asdf/bin"
+  if [ ! -x "$HOME/.asdf/shims/node" ] && [ -s "$HOME/.asdf/asdf.sh" ]; then . "$HOME/.asdf/asdf.sh"; fi
+  prepend_path_if_dir "$HOME/.local/share/mise/shims"
+  prepend_path_if_dir "$HOME/.mise/shims"
+  if ! command -v node >/dev/null 2>&1 && command -v mise >/dev/null 2>&1; then eval "$(mise activate sh)" >/dev/null 2>&1 || true; fi
+  if [ -z "\${FNM_DIR:-}" ]; then FNM_DIR="$HOME/.local/share/fnm"; fi
+  prepend_path_if_dir "$FNM_DIR"
+  prepend_path_if_dir "$HOME/.fnm"
+  if ! command -v node >/dev/null 2>&1 && command -v fnm >/dev/null 2>&1; then
+    eval "$(fnm env --shell bash)" >/dev/null 2>&1 || true
+    fnm use --silent-if-unchanged >/dev/null 2>&1 || fnm use default >/dev/null 2>&1 || true
+  fi
+  prepend_path_if_dir "$HOME/.nodenv/bin"
+  prepend_path_if_dir "$HOME/.nodenv/shims"
+  if ! command -v node >/dev/null 2>&1 && command -v nodenv >/dev/null 2>&1; then eval "$(nodenv init -)" >/dev/null 2>&1 || true; fi
+  if [ -z "\${NVM_DIR:-}" ]; then NVM_DIR="$HOME/.nvm"; fi
+  if [ -s "$NVM_DIR/nvm.sh" ]; then
+    . "$NVM_DIR/nvm.sh"
+    if ! command -v node >/dev/null 2>&1 && command -v nvm >/dev/null 2>&1; then
+      nvm use --silent default >/dev/null 2>&1 || nvm use --silent node >/dev/null 2>&1 || nvm use --silent --lts >/dev/null 2>&1 || true
+    fi
+  fi
+  if ! command -v node >/dev/null 2>&1 && [ -d "$NVM_DIR/versions/node" ]; then
+    for NODE_BIN in "$NVM_DIR"/versions/node/*/bin; do
+      if [ -x "$NODE_BIN/node" ]; then PATH="$NODE_BIN:$PATH"; fi
+    done
+  fi
+  command -v node >/dev/null 2>&1
+}
+# npm extracts a package before running its deps' native builds; a failed
+# node-pty build leaves the npx cache WITHOUT a t3 bin while \`npx --yes\` still
+# exits 0 (same guard as T3 Code's require_installed_t3_cli). Resolve up front
+# so the failure is reported here, with npm's own output on stderr.
+require_t3_cli() {
+  T3_CLI_PATH="$(npx --yes --package t3@"$1" -- sh -c 'command -v t3' 2>/dev/null || true)"
+  if [ -n "$T3_CLI_PATH" ]; then return 0; fi
+  printf 'npm installed t3@"%s" but produced no t3 executable — usually a native dependency (node-pty) failed to build. Install a C toolchain on this host (Debian/Ubuntu: build-essential, Fedora/RHEL: gcc-c++ make, macOS: xcode-select --install) and retry.\\n' "$1" >&2
+  return 1
+}
+# detect: is there a T3 Code server running on this machine? The runtime file is
+# rewritten on every server start and cleared on shutdown, so its pid is
+# checked before its port is trusted (stale file, reused port).
+RUNTIME_JSON="$HOME/.t3/userdata/server-runtime.json"
+detect() {
+  if ! ensure_node_path; then
+    printf 'T3CTL {"node":false}\\n'
+    return 0
+  fi
+  node - "$RUNTIME_JSON" <<'NODE'
+const fs = require('node:fs');
+try {
+  const r = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  const pid = Number(r.pid), port = Number(r.port);
+  if (!Number.isInteger(pid) || pid <= 0 || !Number.isInteger(port)) throw 0;
+  const origin = new URL(String(r.origin ?? ''));
+  if (origin.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(origin.hostname)) throw 0;
+  process.kill(pid, 0);
+  process.stdout.write('T3CTL {"running":true,"port":' + port + '}\\n');
+} catch {
+  process.stdout.write('T3CTL {"running":false}\\n');
+}
+NODE
+}
+case "$1" in
+  detect) detect ;;
+  install)
+    ensure_node_path || { printf 'no node on this machine — install Node 22+ (non-interactive shells may need a version manager configured)\\n' >&2; exit 1; }
+    require_t3_cli "$2" || exit 1
+    exec npx --yes --package t3@"$2" t3 service install
+    ;;
+  token)
+    ensure_node_path || { printf 'no node on this machine\\n' >&2; exit 1; }
+    require_t3_cli "$2" || exit 1
+    exec npx --yes --package t3@"$2" t3 auth session issue --json --label "$3" --ttl "$4"
+    ;;
+  *) printf 'unknown op: %s\\n' "$1" >&2; exit 2 ;;
+esac
+`;
+const sshRun = (target, args, { streamStderr = false } = {}) => {
+    const res = spawnSync('ssh', ['-o', 'ConnectTimeout=15', target, 'sh', '-s', '--', ...args], {
+        input: SSH_SCRIPT,
+        encoding: 'utf8',
+        maxBuffer: 8 * 1024 * 1024,
+        stdio: streamStderr ? ['pipe', 'pipe', 'inherit'] : 'pipe',
+    });
+    if (res.error?.code === 'ENOENT')
+        throw new Error('ssh not found locally');
+    return { status: res.status ?? 1, stdout: String(res.stdout ?? ''), stderr: String(res.stderr ?? '') };
+};
+// Bottom-up scan for the last T3CTL JSON marker — immune to npm chatter above it.
+const sshDetect = (target) => {
+    const res = sshRun(target, ['detect']);
+    if (res.status !== 0)
+        throw new Error(`ssh to ${target} failed (exit ${res.status})${res.stderr.trim() ? `: ${res.stderr.trim().split('\n').slice(-2).join('\n')}` : ''}`);
+    const line = res.stdout.split('\n').reverse().find((l) => l.startsWith('T3CTL {'));
+    if (!line)
+        throw new Error(`detect on ${target} produced no answer`);
+    return JSON.parse(line.slice('T3CTL '.length));
+};
+const sshToken = (target, version, label, ttl) => {
+    // First run downloads t3@<version> into the remote npx cache — minutes with
+    // nothing to show unless npm's progress on stderr streams through.
+    const res = sshRun(target, ['token', version, label, ttl], { streamStderr: true });
+    if (res.status !== 0)
+        throw new Error(`token minting failed on ${target}${res.stderr.trim() ? `: ${res.stderr.trim().split('\n').slice(-3).join('\n')}` : ''}`);
+    // The session JSON is pretty-printed over many lines and stray Effect error
+    // lines can precede it, so accumulate bottom-up until an object with a token
+    // field parses — the token is the only reliable anchor.
+    const lines = res.stdout.split('\n').filter((l) => l.trim() !== '');
+    let buf = '';
+    for (let i = lines.length - 1; i >= 0; i--) {
+        buf = `${lines[i]}\n${buf}`;
+        try {
+            const parsed = JSON.parse(buf);
+            if (typeof parsed.token === 'string' && parsed.token)
+                return { token: parsed.token, sessionId: parsed.sessionId };
+        }
+        catch { /* keep accumulating */ }
+    }
+    throw new Error(`no token in output from ${target}`);
+};
+// --t3-version wins; else ask npm locally for the exact latest, nightly only as
+// a fallback. An exact version is required by the boot service's pinned runtime.
+const resolveT3Version = (flags) => {
+    if (flags['t3-version'])
+        return flags['t3-version'];
+    if (spawnSync('npm', ['--version'], { stdio: 'ignore' }).status !== 0) {
+        throw new Error('npm not found locally — install npm or pass --t3-version <version-or-tag>');
+    }
+    const res = spawnSync('npm', ['view', `${T3_PACKAGE}@latest`, 'version'], { encoding: 'utf8' });
+    if (res.status === 0 && res.stdout.trim())
+        return res.stdout.trim();
+    const nightly = spawnSync('npm', ['view', `${T3_PACKAGE}@nightly`, 'version'], { encoding: 'utf8' });
+    if (nightly.status === 0 && nightly.stdout.trim())
+        return nightly.stdout.trim();
+    throw new Error(`cannot resolve a t3 CLI version via npm — pass --t3-version (tried: ${res.stderr?.trim().split('\n')[0] ?? 'npm failed'})`);
+};
+const freePort = async () => 
+// TOCTOU between this probe and ssh binding the port is real; ExitOnForwardFailure
+// turns the loss into a nonzero ssh exit, which spawnMaster retries on.
+new Promise((resolve, reject) => {
+    const s = net.createServer();
+    s.listen(0, '127.0.0.1', () => {
+        const p = s.address();
+        s.close(() => resolve(p && typeof p === 'object' ? p.port : 0));
+    });
+    s.on('error', reject);
+});
+const ctlPath = (target, port) => path.join(CONFIG_DIR, `ssh-${createHash('sha256').update(`${target}:${port ?? ''}`).digest('hex').slice(0, 12)}`);
+// ssh -fN + ControlPersist=yes keeps the master alive after t3ctl exits
+// (ssh_config(5)); -f with ExitOnForwardFailure=yes means a clean return from
+// spawnSync implies the local listener exists. stderr stays visible so
+// passphrase prompts (ssh opens /dev/tty itself) and bind errors surface.
+const spawnMaster = async (ssh, sshRemotePort) => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const port = await freePort();
+        const res = spawnSync('ssh', [
+            '-M', '-S', ctlPath(ssh, port), '-fN',
+            '-o', 'ConnectTimeout=15', '-o', 'ControlPersist=yes',
+            '-o', 'ExitOnForwardFailure=yes', '-o', 'ServerAliveInterval=15',
+            '-o', 'StrictHostKeyChecking=accept-new',
+            '-L', `${port}:127.0.0.1:${sshRemotePort}`, ssh,
+        ], { stdio: ['ignore', 'ignore', 'inherit'] });
+        if (res.status === 0)
+            return port;
+        if (res.error?.code === 'ENOENT')
+            throw new Error('ssh not found locally');
+    }
+    throw new Error(`could not establish the ssh tunnel to ${ssh} (3 attempts)`);
+};
+const waitForOrigin = async (origin, deadline) => {
+    while (Date.now() < deadline) {
+        if (await probe(origin, PROBE_MS).then(() => true, () => false))
+            return true;
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    return false;
+};
+// Single-flight per host name: cmdLs fans out concurrently and every write
+// command re-enters here.
+const tunnelJobs = new Map();
+const ensureTunnel = (host) => {
+    if (!host.ssh)
+        return Promise.resolve();
+    const inFlight = tunnelJobs.get(host.name);
+    if (inFlight)
+        return inFlight;
+    const job = (async () => {
+        const target = host.ssh; // captured: TS cannot narrow the optional inside the closure
+        if (!target)
+            return;
+        // Liveness is the HTTP probe, never `ssh -O check` — a live master does not
+        // prove the forward works, and the remote port can change on server restart.
+        if (await probe(host.origin, PROBE_MS).then(() => true, () => false))
+            return;
+        spawnSync('ssh', ['-O', 'exit', '-S', ctlPath(target, host.sshLocalPort), target], { stdio: 'ignore' });
+        const detect = sshDetect(target);
+        if (!detect.running)
+            throw new Error(`${target}: no T3 Code server is running — rerun: t3ctl host add ${target}`);
+        // Re-pick the local port if something else grabbed it; the origin changes
+        // with it, so persist both.
+        const localPort = await spawnMaster(target, detect.port ?? 3773);
+        const origin = `http://127.0.0.1:${localPort}`;
+        writeHosts(readHosts().map((h) => h.name === host.name ? { ...h, sshLocalPort: localPort, sshRemotePort: detect.port ?? 3773, origin } : h));
+        if (!(await waitForOrigin(origin, Date.now() + TUNNEL_WAIT_MS))) {
+            throw new Error(`${host.ssh}: the ssh tunnel is up but ${origin} is not answering (is the server still running on the remote port?)`);
+        }
+    })().finally(() => tunnelJobs.delete(host.name));
+    tunnelJobs.set(host.name, job);
+    return job;
+};
+// `t3ctl host add agent@box` — the full bootstrap. Idempotent: rerunning
+// refreshes the tunnel and keeps the stored token unless the machine behind
+// the login changed (different environmentId).
+const cmdHostAddSsh = async (target, flags, hosts) => {
+    const version = resolveT3Version(flags);
+    console.log(`probing ${bold(target)} over ssh`);
+    let detect = sshDetect(target);
+    if (detect.node === false) {
+        throw new Error(`${target} has no node on PATH for non-interactive ssh — install Node 22+ there (a version manager may need configuring for non-login shells)`);
+    }
+    if (!detect.running) {
+        console.log(`no T3 Code server on ${target} — installing the t3 boot service (t3@${version})`);
+        console.log(dim(`  this downloads packages on ${target} and can take a few minutes; its output follows`));
+        // No timeout: t3code itself allows 10 minutes for the pinned-runtime npm
+        // install, and the user watches the output stream by.
+        const res = sshRun(target, ['install', version], { streamStderr: true });
+        if (res.status !== 0)
+            throw new Error(`t3 service install failed on ${target} (exit ${res.status})`);
+        const deadline = Date.now() + SSH_READY_MS;
+        let ready = null;
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 3000));
+            try {
+                ready = await sshDetect(target);
+                if (ready.running)
+                    break;
+            }
+            catch { /* transient ssh hiccups while the service boots */ }
+        }
+        if (!ready?.running) {
+            // Nothing is written to the registry — the origin is not proven yet
+            // (probe-first discipline). A tunnel master is only spawned after the
+            // probe below, so there is nothing to clean up here either.
+            usage(`the boot service was installed on ${target} but no server became ready within ${SSH_READY_MS / 1000}s.\n` +
+                `  Check its service log on ${target}: ~/.t3/userdata/logs/boot-service.log\n` +
+                `  On a Mac this usually means nobody is logged in at that console — a launchd\n` +
+                `  agent starts at login, and an ssh install alone cannot start it.\n` +
+                `  Rerunning t3ctl host add ${target} is safe once the server is up.`);
+            return;
+        }
+        detect = ready;
+    }
+    // The stored local port may be taken by now; spawnMaster retries with fresh
+    // ports and returns whichever won.
+    const existing = hosts.find((h) => h.ssh === target);
+    const localPort = await spawnMaster(target, detect.port ?? 3773);
+    const origin = `http://127.0.0.1:${localPort}`;
+    try {
+        if (!(await waitForOrigin(origin, Date.now() + TUNNEL_WAIT_MS))) {
+            throw new Error(`the tunnel is up but ${origin} is not answering — is the server listening on 127.0.0.1:${detect.port ?? 3773} on ${target}?`);
+        }
+        const descriptor = await probe(origin);
+        // A changed environmentId on a known login means it now lands on a
+        // different machine — same warning as a changed origin, same consequence.
+        if (existing?.environmentId && existing.environmentId !== descriptor.environmentId) {
+            warn(`${target} is now a DIFFERENT environment\n` +
+                `  was ${existing.environmentId} (${existing.label ?? 'unknown'})\n` +
+                `  now ${descriptor.environmentId} (${descriptor.label})\n` +
+                `  the token stored for "${existing.name}" was issued by the old one and will be replaced`);
+        }
+        const name = flags.name ?? existing?.name ?? uniqueName(slugify(descriptor.label), hosts);
+        let token = existing?.token ?? null;
+        let session = null;
+        if (!token || (existing?.environmentId && existing.environmentId !== descriptor.environmentId)) {
+            const issued = sshToken(target, version, `t3ctl:${name}`, flags.ttl ?? '30d');
+            token = issued.token;
+            session = issued;
+        }
+        const others = hosts.filter((h) => h.name !== name && h.origin !== origin && h.serverVersion);
+        const skewed = [...new Set(others.flatMap((h) => (h.serverVersion ? [h.serverVersion] : [])))]
+            .filter((v) => v !== descriptor.serverVersion);
+        if (skewed.length)
+            warn(`serverVersion ${descriptor.serverVersion} differs from other hosts: ${skewed.join(', ')}`);
+        // A master on a superseded local port would linger forever otherwise.
+        if (existing?.sshLocalPort && existing.sshLocalPort !== localPort) {
+            spawnSync('ssh', ['-O', 'exit', '-S', ctlPath(target, existing.sshLocalPort), target], { stdio: 'ignore' });
+        }
+        writeHosts(hosts.filter((h) => h.name !== name && h.ssh !== target).concat({
+            name, origin, token,
+            environmentId: descriptor.environmentId,
+            label: descriptor.label,
+            serverVersion: descriptor.serverVersion,
+            ssh: target, sshLocalPort: localPort, sshRemotePort: detect.port ?? 3773, t3Version: version,
+        }));
+        console.log(`added ${bold(name)} -> ${origin} (via ssh)\n  label   ${descriptor.label}\n` +
+            `  env     ${descriptor.environmentId}\n  version ${descriptor.serverVersion}\n` +
+            `  tunnel  127.0.0.1:${localPort} -> 127.0.0.1:${detect.port ?? 3773} on ${target}`);
+        if (session) {
+            console.log(`  session ${session.sessionId ?? '?'} (label t3ctl:${name})\n` +
+                `  revoke on ${target} with: npx t3 auth session revoke ${session.sessionId ?? '?'}`);
+        }
+        else {
+            console.log('  token   reusing the stored session');
+        }
+    }
+    catch (error) {
+        // Keep no half-registered host: the master would outlive t3ctl otherwise.
+        spawnSync('ssh', ['-O', 'exit', '-S', ctlPath(target, localPort), target], { stdio: 'ignore' });
+        throw error;
+    }
 };
 // ---- writes -------------------------------------------------------------
 // Commands are dispatched directly (no envelope). The CLIENT mints every id;
@@ -257,7 +624,95 @@ const pickHost = (flags) => {
         throw new Error('no hosts registered — run: t3ctl host add <origin> <token>');
     return only;
 };
+const RUNTIME_JSON = '.t3/userdata/server-runtime.json';
+const localRival = async (host) => {
+    let ours;
+    try {
+        ours = new URL(host.origin);
+    }
+    catch {
+        return null;
+    }
+    if (!LOOPBACK.has(ours.hostname))
+        return null;
+    let r;
+    try {
+        r = JSON.parse(fs.readFileSync(path.join(os.homedir(), RUNTIME_JSON), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const pid = Number(r.pid);
+    let theirs;
+    try {
+        theirs = new URL(String(r.origin ?? ''));
+    }
+    catch {
+        return null;
+    }
+    if (!Number.isInteger(pid) || pid <= 0 || theirs.port === ours.port)
+        return null;
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        return null;
+    }
+    // Same environmentId means same ~/.t3, i.e. the same database behind both ports.
+    const [live, mine] = await Promise.all([
+        probe(theirs.origin, PROBE_MS).catch(() => null),
+        probe(host.origin, PROBE_MS).catch(() => null),
+    ]);
+    const env = mine?.environmentId ?? host.environmentId;
+    if (!live || !env || live.environmentId !== env)
+        return null;
+    return {
+        origin: theirs.origin, pid, serverVersion: live.serverVersion,
+        startedAt: typeof r.startedAt === 'string' ? r.startedAt : undefined,
+        moved: !mine,
+    };
+};
+// Over ssh the remote runtime file is only re-read when the tunnel is rebuilt,
+// so a server that keeps running on the old port hides a newer one the same way.
+const sshRival = (host) => {
+    // ensureTunnel may have just re-pointed the tunnel and rewritten the registry.
+    const current = readHosts().find((h) => h.name === host.name) ?? host;
+    if (!current.ssh || !current.sshRemotePort)
+        return null;
+    const detect = sshDetect(current.ssh);
+    if (!detect.running || !detect.port || detect.port === current.sshRemotePort)
+        return null;
+    return { origin: `${current.ssh}:${detect.port} (remote)` };
+};
+const findRival = (host) => host.ssh ? Promise.resolve().then(() => sshRival(host)) : localRival(host);
+const rivalMessage = (host, rival) => (rival.moved
+    ? `${host.name} (${host.origin}) is not answering; its T3 Code server now runs at `
+    : `${host.name} (${host.origin}) is not the only T3 Code server on this data dir — `) +
+    `${rival.origin}${rival.serverVersion ? ` (${rival.serverVersion}` : ''}` +
+    `${rival.pid ? `, pid ${rival.pid}` : ''}${rival.startedAt ? `, started ${rival.startedAt}` : ''}` +
+    `${rival.serverVersion ? ')' : ''}${rival.moved ? '' : ' started after it'}.\n` +
+    (rival.moved ? '  Point t3ctl at it:\n' :
+        `  Each server only sees threads created through itself, so the app talking to one\n` +
+            `  gets "Thread … does not exist" for threads made on the other.\n` +
+            `  Stop the stale server, or point t3ctl at the current one:\n`) +
+    (host.ssh
+        ? `    t3ctl host rm ${host.name} && t3ctl host add ${host.ssh} --name ${host.name}`
+        : `    t3ctl host add ${rival.origin} --name ${host.name}`);
+// Writes are what strand threads, so they refuse; reads only warn.
+const assertNoRival = async (host) => {
+    const rival = await findRival(host);
+    if (rival)
+        throw new Error(rivalMessage(host, rival));
+};
+// ssh hosts are skipped here: a detect round-trip per host per `ls` is too slow.
+const warnRivals = async (hosts) => {
+    const rivals = await Promise.all(hosts.map((h) => (h.ssh ? null : localRival(h).catch(() => null))));
+    hosts.forEach((h, i) => { const r = rivals[i]; if (r)
+        warn(rivalMessage(h, r)); });
+};
 const dispatch = async (host, command) => {
+    await ensureTunnel(host);
+    await assertNoRival(host);
     const res = await fetch(`${host.origin}/api/orchestration/dispatch`, {
         method: 'POST',
         headers: { ...(host.token ? { authorization: `Bearer ${host.token}` } : {}), 'content-type': 'application/json' },
@@ -293,6 +748,33 @@ const resolveThread = (snap, ref) => {
     }
     throw new Error(`no thread matching "${ref}"`);
 };
+// instanceId is the segment before the FIRST slash; the model keeps the rest,
+// because opencode model ids are themselves slashed ("github-copilot/gpt-5.4").
+const parseModel = (raw) => {
+    const slash = raw.indexOf('/');
+    if (slash < 1)
+        throw new Error(`--model must be <instance>/<model>, got "${raw}"`);
+    return { instanceId: raw.slice(0, slash), model: raw.slice(slash + 1) };
+};
+// `--option id=value` sets one entry of modelSelection.options, replacing an
+// entry with the same id. The server accepts strings and booleans, so `true`
+// and `false` are sent as booleans (`fastMode=true`), anything else as a string.
+const withOptions = (selection, raw = []) => {
+    if (raw.length === 0)
+        return selection;
+    const options = new Map((selection.options ?? []).map((o) => [o.id, o]));
+    for (const entry of raw) {
+        const eq = entry.indexOf('=');
+        const id = entry.slice(0, eq).trim();
+        const text = entry.slice(eq + 1).trim();
+        if (eq < 0 || !id || !text)
+            throw new Error(`--option must be <id>=<value>, got "${entry}"`);
+        options.set(id, { id, value: text === 'true' ? true : text === 'false' ? false : text });
+    }
+    return { ...selection, options: [...options.values()] };
+};
+const describeModel = (m) => `${m.instanceId}/${m.model}` +
+    (m.options?.length ? ` (${m.options.map((o) => `${o.id}=${o.value}`).join(', ')})` : '');
 // thread.turn.start is ONE command carrying the first message inline — this is
 // what the UI fires immediately after thread.create, which is why a thread with
 // no messages is a state the UI never produces. The client-side schema requires
@@ -307,19 +789,15 @@ const cmdThreadStart = async (thread, host, text, flags) => {
         interactionMode: flags['interaction-mode'] ?? 'default',
         createdAt: new Date().toISOString(),
     };
-    if (flags.model) {
-        const slash = flags.model.indexOf('/');
-        if (slash < 1)
-            throw new Error(`--model must be <instance>/<model>, got "${flags.model}"`);
-        command.modelSelection = { instanceId: flags.model.slice(0, slash), model: flags.model.slice(slash + 1) };
-    }
-    else if (thread.modelSelection) {
-        command.modelSelection = thread.modelSelection;
-    }
+    const base = flags.model ? parseModel(flags.model) : thread.modelSelection;
+    if (!base && flags.option?.length)
+        throw new Error('--option needs a model; the thread has none, so pass --model too');
+    if (base)
+        command.modelSelection = withOptions(base, flags.option);
     const { sequence } = await dispatch(host, command);
     const m = command['modelSelection'];
     console.log(`started ${bold(thread.title || thread.id)}\n  id    ${thread.id}` +
-        (m ? `\n  model ${m.instanceId}/${m.model}` : '') +
+        (m ? `\n  model ${describeModel(m)}` : '') +
         `\n  mode  ${command.runtimeMode} / ${command.interactionMode}\n  seq   ${sequence}`);
 };
 const cmdThreadInterrupt = async (thread, host) => {
@@ -338,8 +816,12 @@ const cmdThreadRename = async (thread, host, title) => {
 };
 // Lighter than the full snapshot; retitle polls this so it does not refetch every
 // thread's history once a second.
-const threadDetail = async (host, threadId) => {
-    const res = await fetch(`${host.origin}/api/orchestration/threads/${threadId}?turnLimit=1`, {
+// `turnLimit` is null for callers that want the whole history (export), 1 for
+// callers that only want to poll a field (retitle).
+const threadDetail = async (host, threadId, turnLimit = 1) => {
+    await ensureTunnel(host);
+    const query = turnLimit === null ? '' : `?turnLimit=${turnLimit}`;
+    const res = await fetch(`${host.origin}/api/orchestration/threads/${threadId}${query}`, {
         headers: { authorization: `Bearer ${host.token}` },
         signal: AbortSignal.timeout(host.timeoutMs ?? 15000),
     });
@@ -398,13 +880,7 @@ const cmdThreadCreate = async (projectRef, title, flags) => {
     const project = resolveProject(await snapshot(host), projectRef);
     if (!project)
         throw new Error(`no project matching "${projectRef}" on ${host.name}`);
-    // instanceId is the segment before the FIRST slash; the model keeps the rest,
-    // because opencode model ids are themselves slashed ("github-copilot/gpt-5.4").
-    const raw = flags.model ?? 'claudeAgent/claude-opus-5';
-    const slash = raw.indexOf('/');
-    if (slash < 1)
-        throw new Error(`--model must be <instance>/<model>, got "${raw}"`);
-    const modelSelection = { instanceId: raw.slice(0, slash), model: raw.slice(slash + 1) };
+    const modelSelection = withOptions(parseModel(flags.model ?? 'claudeAgent/claude-opus-5'), flags.option);
     const threadId = crypto.randomUUID();
     const { sequence } = await dispatch(host, {
         type: 'thread.create', commandId: crypto.randomUUID(),
@@ -415,7 +891,7 @@ const cmdThreadCreate = async (projectRef, title, flags) => {
         worktreePath: flags.worktree ?? null,
         createdAt: new Date().toISOString(),
     });
-    console.log(`created thread ${bold(title)} in ${project.title} on ${host.name}\n  id    ${threadId}\n  model ${modelSelection.instanceId}/${modelSelection.model}\n  seq   ${sequence}`);
+    console.log(`created thread ${bold(title)} in ${project.title} on ${host.name}\n  id    ${threadId}\n  model ${describeModel(modelSelection)}\n  seq   ${sequence}`);
 };
 const cmdThreadSimple = async (verb, ref, flags) => {
     const host = pickHost(flags);
@@ -425,6 +901,256 @@ const cmdThreadSimple = async (verb, ref, flags) => {
     });
     console.log(`${verb}d ${bold(thread.title || thread.id)}\n  id  ${thread.id}\n  seq ${sequence}`);
 };
+const STRATEGY_LABEL = {
+    sqlite: 'local state.sqlite',
+    http: 'snapshot + per-thread fetch',
+};
+/** Fixed by T3 Code. Read relative to whichever machine's home directory applies. */
+const STATE_DB = '.t3/userdata/state.sqlite';
+const expandHome = (p) => path.resolve(p.replace(/^~(?=$|\/)/, os.homedir()));
+/**
+ * Where a prompt happened, named the way a human would: the workspace path made
+ * relative to the watched root it sits under. Longest matching root wins, so
+ * `~/Code` and `~/Code/@clients` both configured gives `afa`, not `@clients/afa`.
+ * A workspace under no watched root has no marker and the prompt is dropped.
+ */
+const markerForWorkspace = (workspaceRoot, watched) => {
+    const ws = workspaceRoot.replace(/\/+$/, '');
+    let best = null;
+    let bestLen = -1;
+    for (const root of watched) {
+        const r = root.replace(/\/+$/, '');
+        if (ws === r)
+            return ws.split('/').pop() ?? ws;
+        if (ws.startsWith(`${r}/`) && r.length > bestLen) {
+            best = ws.slice(r.length + 1);
+            bestLen = r.length;
+        }
+    }
+    return best;
+};
+/**
+ * Prompts arrive with the harness's wrapping still on them. Mirrors
+ * `cleanPrompt` in spr-time-entrier, which is the consumer this shape is for:
+ * unwrap `<user_query>` when present, then collapse whitespace to one line.
+ */
+const cleanPrompt = (text) => {
+    const tagged = text.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/);
+    return (tagged?.[1] ?? text).replace(/\s+/g, ' ').trim();
+};
+// One statement, shared by every strategy that reads the local store directly,
+// so it cannot drift from what the HTTP path reconstructs.
+const PROMPT_SQL = `SELECT m.message_id, m.thread_id, m.text, m.created_at, p.workspace_root
+FROM projection_thread_messages m
+JOIN projection_threads t ON t.thread_id = m.thread_id
+JOIN projection_projects p ON p.project_id = t.project_id
+WHERE m.role = 'user'
+  AND t.deleted_at IS NULL
+  AND p.deleted_at IS NULL
+  AND m.created_at >= ? AND m.created_at < ?
+ORDER BY m.created_at`;
+/**
+ * A bare `--since 2026-09-14` is the UTC day boundary, not local midnight: the
+ * rows being filtered are UTC, and an export should describe the same window
+ * whichever machine runs it. Anything else is handed to `Date` as written.
+ */
+const isoBound = (value, flag) => {
+    const raw = /^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00.000Z` : value;
+    const at = new Date(raw);
+    if (Number.isNaN(at.getTime()))
+        throw new Error(`${flag}: not a date I can read: ${value}`);
+    return at.toISOString();
+};
+/**
+ * node:sqlite arrived in Node 22.5 behind `--experimental-sqlite`. Current
+ * releases have it unflagged (verified on 22.23 and 24), but `engines` allows
+ * `>=22`, which still admits the flagged ones. Importing it lazily means only
+ * this command fails there, instead of the whole CLI failing to start.
+ */
+const loadSqlite = async () => {
+    try {
+        return (await import('node:sqlite')).DatabaseSync;
+    }
+    catch {
+        throw new Error('reading state.sqlite needs node:sqlite — upgrade to Node >= 22.13, or pass --experimental-sqlite on 22.5-22.12');
+    }
+};
+const queryLocal = async (since, until) => {
+    const file = path.join(os.homedir(), STATE_DB);
+    if (!fs.existsSync(file))
+        throw new Error(`no T3 Code database at ${file}`);
+    const DatabaseSync = await loadSqlite();
+    // The database is in WAL mode, so this reader neither blocks the running app
+    // nor is blocked by it, and no copy is needed — it is ~500 MB.
+    const db = new DatabaseSync(file, { readOnly: true });
+    try {
+        return db.prepare(PROMPT_SQL).all(since, until);
+    }
+    finally {
+        db.close();
+    }
+};
+/** `Date.parse` returns NaN for junk and for null; both mean "cannot compare". */
+const instant = (value) => {
+    const t = value ? Date.parse(value) : Number.NaN;
+    return Number.isNaN(t) ? null : t;
+};
+/**
+ * Which threads are worth a request. `updatedAt` moves with every new message,
+ * so a thread untouched since the window opened cannot hold one, and a thread
+ * created after it closed cannot either. Anything unknown is fetched.
+ */
+const mayHavePrompts = (t, since, until) => {
+    if (t.deletedAt)
+        return false;
+    const updated = instant(t.updatedAt);
+    if (updated !== null && updated < since)
+        return false;
+    const created = instant(t.createdAt);
+    if (created !== null && created >= until)
+        return false;
+    return true;
+};
+/** Bounded fan-out: a host with 200 live threads should not get 200 sockets at once. */
+const mapPool = async (items, limit, fn) => {
+    const out = new Array(items.length);
+    // Every worker pulls from the same iterator, so each entry goes to exactly one
+    // of them and the last to finish is the last item, not the last worker.
+    const queue = items.entries();
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (const [i, item] of queue)
+            out[i] = await fn(item);
+    }));
+    return out;
+};
+const queryOverHttp = async (host, since, until) => {
+    const snap = await snapshot(host);
+    const roots = new Map(snap.projects.filter((p) => !p.deletedAt).map((p) => [p.id, p.workspaceRoot]));
+    const from = Date.parse(since);
+    const to = Date.parse(until);
+    const threads = snap.threads.filter((t) => roots.has(t.projectId) && mayHavePrompts(t, from, to));
+    const perThread = await mapPool(threads, 8, async (t) => {
+        const workspaceRoot = roots.get(t.projectId);
+        if (workspaceRoot === undefined)
+            return [];
+        const detail = await threadDetail(host, t.id, null);
+        const rows = [];
+        for (const m of detail.messages ?? []) {
+            if (m.role !== 'user')
+                continue;
+            const at = instant(m.createdAt);
+            if (at === null || at < from || at >= to)
+                continue;
+            const messageId = m.messageId ?? m.id;
+            if (messageId === undefined)
+                continue;
+            rows.push({
+                message_id: messageId,
+                thread_id: t.id,
+                text: m.text ?? '',
+                created_at: new Date(at).toISOString(),
+                workspace_root: workspaceRoot,
+            });
+        }
+        return rows;
+    });
+    return perThread.flat();
+};
+/**
+ * Loopback means the database this process can already open is the very one the
+ * host serves, so read it and skip the network entirely. Everything else goes
+ * over HTTP.
+ */
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const strategyFor = (host) => {
+    let hostname = '';
+    try {
+        hostname = new URL(host.origin).hostname;
+    }
+    catch { /* an unparseable origin is not loopback; let the HTTP path report it */ }
+    return LOOPBACK.has(hostname) ? 'sqlite' : 'http';
+};
+const readPrompts = (host, strategy, since, until) => {
+    if (strategy === 'sqlite')
+        return queryLocal(since, until);
+    return queryOverHttp(host, since, until);
+};
+const cmdExportPrompts = async (o) => {
+    const since = isoBound(o.since, '--since');
+    const until = o.until ? isoBound(o.until, '--until') : new Date().toISOString();
+    if (until <= since)
+        throw new Error(`--until (${until}) must be after --since (${since})`);
+    const registered = readHosts();
+    if (!registered.length)
+        throw new Error('no hosts registered — run: t3ctl host add <origin> <token>');
+    const hosts = o.host ? registered.filter((h) => h.name === o.host) : registered;
+    if (!hosts.length)
+        throw new Error(`no such host: ${o.host}`);
+    const watched = (o.watch?.length ? o.watch : ['~/Code']).map(expandHome);
+    const settled = await Promise.allSettled(hosts.map(async (h) => {
+        const strategy = strategyFor(h);
+        return { strategy, rows: await readPrompts(h, strategy, since, until) };
+    }));
+    const messages = [];
+    const unreachable = [];
+    const reached = [];
+    settled.forEach((result, i) => {
+        const host = hosts[i];
+        if (!host)
+            return;
+        if (result.status === 'rejected') {
+            unreachable.push({ host: host.name, error: errorMessage(result.reason) });
+            return;
+        }
+        const { strategy, rows } = result.value;
+        let count = 0;
+        for (const row of rows) {
+            const marker = markerForWorkspace(row.workspace_root, watched);
+            if (marker === null)
+                continue; // outside every watched root
+            messages.push({
+                host: host.name,
+                threadId: row.thread_id,
+                messageId: row.message_id,
+                createdAt: row.created_at,
+                text: cleanPrompt(row.text),
+                workspaceRoot: row.workspace_root,
+                // Markers have to stay unique across machines, and two hosts routinely
+                // hold a checkout of the same repo at the same path. The local host is
+                // the unprefixed one so single-machine consumers see plain names.
+                marker: strategy === 'sqlite' ? marker : `${host.name}/${marker}`,
+            });
+            count++;
+        }
+        reached.push({ host: host.name, strategy, count });
+    });
+    messages.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.messageId.localeCompare(b.messageId));
+    if (o.json) {
+        console.log(JSON.stringify({ messages, unreachable }, null, 2));
+    }
+    else {
+        const n = messages.length;
+        console.log(`${bold(String(n))} prompt${n === 1 ? '' : 's'}  ${dim(`${since} -> ${until}`)}`);
+        for (const { host, strategy, count } of reached) {
+            console.log(`\n${bold(host)}  ${count}  ${dim(STRATEGY_LABEL[strategy])}`);
+            const tally = new Map();
+            for (const m of messages) {
+                if (m.host === host)
+                    tally.set(m.marker, (tally.get(m.marker) ?? 0) + 1);
+            }
+            const width = Math.max(0, ...[...tally.keys()].map((k) => k.length));
+            for (const [marker, hits] of [...tally].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))) {
+                console.log(`  ${marker.padEnd(width)}  ${hits}`);
+            }
+        }
+    }
+    for (const u of unreachable)
+        console.error(`${ICON.error} ${u.host} ${dim(u.error)}`);
+    // Partial results are still useful and `unreachable` reports what is missing,
+    // so only a total failure is an error.
+    if (unreachable.length === hosts.length)
+        process.exitCode = 1;
+};
 // ---- cli ----------------------------------------------------------------
 // commander's option names arrive camelCased; the command implementations were
 // written against the kebab-case spellings, so translate once here rather than
@@ -433,6 +1159,7 @@ const FLAG_NAMES = {
     host: 'host', model: 'model', branch: 'branch', worktree: 'worktree',
     name: 'name', timeout: 'timeout',
     runtimeMode: 'runtime-mode', interactionMode: 'interaction-mode',
+    option: 'option',
 };
 // Only carry options that were actually supplied. Emitting every key
 // unconditionally made `'name' in flags` always true, which made host add bail
@@ -454,6 +1181,7 @@ program
     .version(pkg.version, '-v, --version', 'print the t3ctl version')
     .showHelpAfterError('(run `t3ctl --help` or `t3ctl <command> --help`)')
     .configureHelp({ showGlobalOptions: true });
+const addOption = (value, previous) => [...(previous ?? []), value];
 const hostOption = (cmd) => cmd.option('--host <name>', 'which registered host to talk to (required when several are registered)');
 program.command('ls')
     .description('list projects and threads across all registered hosts')
@@ -463,18 +1191,43 @@ program.command('ls')
     .action((o) => cmdLs(o));
 const host = program.command('host').description('manage the host registry');
 host.command('add')
-    .argument('<origin>', 'base URL of the host, e.g. https://box.tailnet.ts.net:3773')
-    .argument('[token]', 'bearer token from `t3 auth session issue` on that host')
-    .description('register a host, probing /.well-known/t3/environment first')
+    .argument('<origin>', 'base URL of the host, e.g. https://box.tailnet.ts.net:3773 — or an ssh login like agent@box to bootstrap that machine end to end')
+    .argument('[token]', 'bearer token from `t3 auth session issue` on that host (origin form only)')
+    .description('register a host — from a URL, or from its ssh login alone')
     .option('--name <name>', 'override the label detected from the host')
-    .action((origin, token, o) => cmdHostAdd([origin, token].filter(Boolean), toFlags(o), readHosts()));
+    .option('--ttl <duration>', 'session lifetime for the ssh form, e.g. 30d (default 30d)', '30d')
+    .option('--t3-version <version>', 'exact t3 CLI version to install remotely (default: npm-resolved latest, nightly as fallback)')
+    .action(async (origin, token, o) => {
+    const flags = toFlags(o);
+    const hosts = readHosts();
+    // Two shapes, told apart by scheme: an http(s) origin pairs with an existing
+    // server; anything else is an ssh login that bootstraps one.
+    if (isOrigin(origin)) {
+        return cmdHostAdd([origin, ...(token ? [token] : [])], flags, hosts);
+    }
+    // An origin missing its scheme is still the old, deliberate rejection — not
+    // guessed at, and not misread as an ssh target (ssh targets never carry a
+    // colon; ports belong to origins).
+    if (origin.includes(':')) {
+        return usage('an origin needs a scheme, e.g. http://localhost:3773');
+    }
+    if (token) {
+        throw new Error('a token argument only makes sense with an <origin>; the ssh form mints its own');
+    }
+    return cmdHostAddSsh(origin, flags, hosts);
+});
 host.command('rm')
     .argument('<name>', 'registered host name')
     .description('remove a host from the registry')
     .action((name) => {
     const hosts = readHosts();
-    if (!hosts.some((h) => h.name === name))
+    const gone = hosts.find((h) => h.name === name);
+    if (!gone)
         throw new Error(`no such host: ${name}`);
+    // Taking the ssh master down with the entry; a missing socket just exits 255.
+    if (gone.ssh) {
+        spawnSync('ssh', ['-O', 'exit', '-S', ctlPath(gone.ssh, gone.sshLocalPort), gone.ssh], { stdio: 'ignore' });
+    }
     writeHosts(hosts.filter((h) => h.name !== name));
     console.log(`removed ${name}`);
 });
@@ -482,6 +1235,19 @@ host.command('ls').description('list registered hosts and probe each one')
     .action(() => cmdHostsList(readHosts()));
 program.command('hosts').description('list registered hosts and probe each one (alias of `host ls`)')
     .action(() => cmdHostsList(readHosts()));
+// Repeatable, because a workspace tree is not always one root. No default value
+// is handed to commander: it would print `(default: [])` in the help, which is
+// not what happens when the flag is omitted.
+const addWatch = (value, previous) => [...(previous ?? []), value];
+const exportGroup = program.command('export').description('read-only exports for other tools');
+exportGroup.command('prompts')
+    .description('every prompt a human typed, across hosts, with the project it happened in')
+    .requiredOption('--since <date>', 'window start, inclusive — a bare YYYY-MM-DD is a UTC day boundary')
+    .option('--until <date>', 'window end, exclusive (default: now)')
+    .option('--host <name>', 'only this registered host (default: every one of them)')
+    .option('--watch <path>', 'only prompts in projects under this root; repeatable (default: ~/Code)', addWatch)
+    .option('--json', 'emit JSON instead of a summary')
+    .action((o) => cmdExportPrompts(o));
 const project = program.command('project').description('manage projects');
 hostOption(project.command('create')
     .argument('<title>', 'name for the project as it appears in T3 Code')
@@ -494,6 +1260,7 @@ hostOption(thread.command('create')
     .argument('<title...>', 'thread title; everything after the project is used')
     .description('create a thread (idle — use `thread send` to run it)')
     .option('--model <instance/model>', 'e.g. claudeAgent/claude-opus-5', 'claudeAgent/claude-opus-5')
+    .option('--option <id=value>', 'model option, e.g. effort=high; repeatable', addOption)
     .option('--branch <branch>', 'git branch to associate with the thread')
     .option('--worktree <path>', 'git worktree the thread should run in')
     .option('--runtime-mode <mode>', 'approval-required | auto-accept-edits | auto | full-access', 'full-access')
@@ -505,6 +1272,7 @@ hostOption(thread.command('send')
     .argument('<message...>', 'the message; everything after the thread is sent')
     .description('send a message to a thread and run the agent')
     .option('--model <instance/model>', "override the thread's model for this turn")
+    .option('--option <id=value>', "model option for this turn, e.g. effort=high; repeatable", addOption)
     .option('--runtime-mode <mode>', 'approval-required | auto-accept-edits | auto | full-access')
     .option('--interaction-mode <mode>', 'default | plan'))
     .action(async (ref, message, o) => {