@phnx-labs/agents-cli 1.20.31 → 1.20.33

package/dist/lib/crabbox/cli.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Typed wrapper over the external `crabbox` binary (github.com/openclaw/crabbox).
+ *
+ * crabbox leases ephemeral cloud boxes (Hetzner/DO/EC2/…), syncs the dirty
+ * checkout, and runs commands on them. We use it as the transport for
+ * `agents run --lease`: warm a box → run the agent on it via `crabbox run` →
+ * stop it. crabbox owns the SSH connection, so agents-cli never needs a direct
+ * ssh target (unlike the `agents hosts` model).
+ *
+ * crabbox talks to its cloud provider's API for list/status/warmup/stop, which
+ * needs a provider token (e.g. HCLOUD_TOKEN) in the environment. We inject it
+ * from a secrets bundle when one is configured (see `crabboxEnv`).
+ */
+/** A crabbox machine as reported by `crabbox list --json`. */
+export interface CrabboxBox {
+    /** Provider machine name, e.g. `crabbox-blue-hermit-1039689b`. */
+    name: string;
+    /** Provider run state, e.g. `running`. */
+    status: string;
+    /** Friendly slug used with `--id`, e.g. `blue-hermit`. */
+    slug: string;
+    /** Lease id, e.g. `cbx_9968746bb15c`. */
+    lease: string;
+    /** crabbox bootstrap state; `ready` once the box is usable. */
+    state: string;
+    /** Public IPv4, when the provider exposes one. */
+    ip?: string;
+    profile?: string;
+    class?: string;
+    /** True when running + bootstrap-complete. */
+    ready: boolean;
+}
+export interface CrabboxOptions {
+    /**
+     * Name of a secrets bundle whose env (e.g. `HCLOUD_TOKEN`) crabbox needs to
+     * reach its cloud provider. Resolved via agents-cli's own keychain-backed
+     * secrets. When unset, crabbox runs with the ambient environment / its own
+     * `crabbox login` credentials.
+     */
+    secretsBundle?: string;
+}
+/** Locate the crabbox binary, or throw an actionable error. */
+export declare function findCrabbox(): string;
+/** Build the child env for crabbox, injecting a secrets bundle when configured. */
+export declare function crabboxEnv(opts: CrabboxOptions): NodeJS.ProcessEnv;
+/** All crabbox machines the broker knows about. */
+export declare function crabboxList(opts?: CrabboxOptions): CrabboxBox[];
+/** Find one box by slug, or null. */
+export declare function crabboxFind(slug: string, opts?: CrabboxOptions): CrabboxBox | null;
+export interface WarmupOptions extends CrabboxOptions {
+    class?: string;
+    profile?: string;
+    /** Provision web code-server capability on the box. */
+    code?: boolean;
+    /** Cloud backend override (crabbox provider id, e.g. hetzner/aws/do). */
+    provider?: string;
+}
+/**
+ * Lease a box and block until it is ready. Returns the leased box.
+ *
+ * We diff `crabbox list` before/after so we reliably identify the box this call
+ * created even if warmup's stdout format changes — the new lease id is the one
+ * that wasn't present before.
+ */
+export declare function crabboxWarmup(opts?: WarmupOptions): CrabboxBox;
+/**
+ * Poll until the box reports ready, or throw after timeoutMs.
+ * `sleep` is injectable so tests don't wall-clock wait.
+ */
+export declare function crabboxWaitReady(slug: string, opts?: CrabboxOptions & {
+    timeoutMs?: number;
+    intervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<CrabboxBox>;
+export interface CrabboxRunOptions extends CrabboxOptions {
+    /** Called with each chunk of combined stdout/stderr as it streams. */
+    onData?: (chunk: string) => void;
+    /** Force a full remote resync before running. */
+    fullResync?: boolean;
+}
+/**
+ * Run `remoteCmd` on the leased box via `crabbox run` (crabbox syncs the dirty
+ * checkout and owns the SSH). Streams combined output; resolves with the remote
+ * exit code (or null if crabbox itself failed to dispatch).
+ */
+export declare function crabboxRun(slug: string, remoteCmd: string, opts?: CrabboxRunOptions): Promise<number | null>;
+/**
+ * Upload `script` to the box via `crabbox run --script-stdin` and run it.
+ *
+ * The script body travels over stdin and is written to a file on the box before
+ * execution — it never appears in argv / `ps` / shell history, which is why this
+ * is the transport for credential provisioning (the token contents live only in
+ * the uploaded script, then the file is removed by the script itself).
+ * Streams combined output; resolves with the remote exit code (null on dispatch failure).
+ */
+export declare function crabboxRunScript(slug: string, script: string, opts?: CrabboxRunOptions): Promise<number | null>;
+/** Release the lease / delete the box. Best-effort; never throws. */
+export declare function crabboxStop(slug: string, opts?: CrabboxOptions): boolean;

package/dist/lib/crabbox/cli.js

@@ -0,0 +1,218 @@
+/**
+ * Typed wrapper over the external `crabbox` binary (github.com/openclaw/crabbox).
+ *
+ * crabbox leases ephemeral cloud boxes (Hetzner/DO/EC2/…), syncs the dirty
+ * checkout, and runs commands on them. We use it as the transport for
+ * `agents run --lease`: warm a box → run the agent on it via `crabbox run` →
+ * stop it. crabbox owns the SSH connection, so agents-cli never needs a direct
+ * ssh target (unlike the `agents hosts` model).
+ *
+ * crabbox talks to its cloud provider's API for list/status/warmup/stop, which
+ * needs a provider token (e.g. HCLOUD_TOKEN) in the environment. We inject it
+ * from a secrets bundle when one is configured (see `crabboxEnv`).
+ */
+import { spawn, spawnSync } from 'child_process';
+import { readAndResolveBundleEnv } from '../secrets/bundles.js';
+/** Locate the crabbox binary, or throw an actionable error. */
+export function findCrabbox() {
+    const r = spawnSync('crabbox', ['--help'], { encoding: 'utf-8' });
+    if (r.error) {
+        throw new Error('crabbox is not installed or not on PATH. Install it and run `crabbox login`, then `crabbox doctor` to verify provider access.');
+    }
+    return 'crabbox';
+}
+/** Build the child env for crabbox, injecting a secrets bundle when configured. */
+export function crabboxEnv(opts) {
+    const bundle = opts.secretsBundle ?? process.env.AGENTS_LEASE_SECRETS_BUNDLE;
+    if (!bundle)
+        return process.env;
+    try {
+        // Reuse the same resolver `agents secrets exec` uses so a keychain-backed
+        // bundle (e.g. hetzner.com → HCLOUD_TOKEN) reaches crabbox without ever
+        // touching disk.
+        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents run --lease (crabbox)' });
+        return { ...process.env, ...env };
+    }
+    catch (e) {
+        throw new Error(`Could not load secrets bundle "${bundle}" for crabbox: ${e.message}. ` +
+            `Fix the bundle (agents secrets view ${bundle}) or unset lease.secretsBundle to use crabbox's own login.`);
+    }
+}
+function normalizeBox(raw) {
+    const labels = (raw.labels ?? {});
+    const slug = labels.slug ?? '';
+    if (!slug)
+        return null;
+    const status = String(raw.status ?? '');
+    const state = String(labels.state ?? '');
+    const publicNet = (raw.public_net ?? {});
+    return {
+        name: String(raw.name ?? ''),
+        status,
+        slug,
+        lease: labels.lease ?? '',
+        state,
+        ip: publicNet.ipv4?.ip || undefined,
+        profile: labels.profile,
+        class: labels.class,
+        ready: status === 'running' && state === 'ready',
+    };
+}
+/** All crabbox machines the broker knows about. */
+export function crabboxList(opts = {}) {
+    findCrabbox();
+    const r = spawnSync('crabbox', ['list', '--json'], { encoding: 'utf-8', env: crabboxEnv(opts) });
+    if (r.status !== 0) {
+        throw new Error(`crabbox list failed: ${(r.stderr || r.stdout || '').trim() || 'unknown error'}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(r.stdout || '[]');
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.map((b) => normalizeBox(b)).filter((b) => b !== null);
+}
+/** Find one box by slug, or null. */
+export function crabboxFind(slug, opts = {}) {
+    return crabboxList(opts).find((b) => b.slug === slug) ?? null;
+}
+/**
+ * Lease a box and block until it is ready. Returns the leased box.
+ *
+ * We diff `crabbox list` before/after so we reliably identify the box this call
+ * created even if warmup's stdout format changes — the new lease id is the one
+ * that wasn't present before.
+ */
+export function crabboxWarmup(opts = {}) {
+    findCrabbox();
+    const env = crabboxEnv(opts);
+    const before = new Set(crabboxList(opts).map((b) => b.lease));
+    const args = ['warmup'];
+    if (opts.class)
+        args.push('--class', opts.class);
+    if (opts.profile)
+        args.push('--profile', opts.profile);
+    if (opts.provider)
+        args.push('--provider', opts.provider);
+    if (opts.code)
+        args.push('--code');
+    const r = spawnSync('crabbox', args, { encoding: 'utf-8', env, stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status !== 0) {
+        const detail = (r.stderr || r.stdout || '').trim();
+        throw new Error(`crabbox warmup failed: ${detail || 'unknown error'}. ` +
+            `Check provider access with \`crabbox doctor\`; a missing cloud token often means \`crabbox login\` or a lease.secretsBundle is needed.`);
+    }
+    // Prefer the freshly-created box (lease absent from the pre-warmup snapshot).
+    const after = crabboxList(opts);
+    const fresh = after.filter((b) => !before.has(b.lease));
+    if (fresh.length === 1)
+        return fresh[0];
+    // Fallback: parse the cbx_ lease id crabbox prints and match it.
+    const m = (r.stdout || '').match(/cbx_[0-9a-f]+/i);
+    if (m) {
+        const byLease = after.find((b) => b.lease === m[0]);
+        if (byLease)
+            return byLease;
+    }
+    if (fresh.length > 1) {
+        // Multiple new boxes (concurrent warmups) — pick the newest ready one.
+        const ready = fresh.filter((b) => b.ready);
+        if (ready.length)
+            return ready[ready.length - 1];
+        return fresh[fresh.length - 1];
+    }
+    throw new Error('crabbox warmup succeeded but the new box could not be located in `crabbox list`.');
+}
+/**
+ * Poll until the box reports ready, or throw after timeoutMs.
+ * `sleep` is injectable so tests don't wall-clock wait.
+ */
+export async function crabboxWaitReady(slug, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const intervalMs = opts.intervalMs ?? 5_000;
+    const sleep = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
+    const deadline = Date.now() + timeoutMs;
+    let last = null;
+    // First check is immediate (warmup usually returns an already-ready box).
+    for (;;) {
+        last = crabboxFind(slug, opts);
+        if (last?.ready)
+            return last;
+        if (Date.now() >= deadline)
+            break;
+        await sleep(intervalMs);
+    }
+    throw new Error(`crabbox box "${slug}" did not become ready within ${Math.round(timeoutMs / 1000)}s (state: ${last?.state ?? 'gone'}).`);
+}
+/**
+ * Run `remoteCmd` on the leased box via `crabbox run` (crabbox syncs the dirty
+ * checkout and owns the SSH). Streams combined output; resolves with the remote
+ * exit code (or null if crabbox itself failed to dispatch).
+ */
+export function crabboxRun(slug, remoteCmd, opts = {}) {
+    findCrabbox();
+    const args = ['run', '--id', slug, '--reclaim'];
+    if (opts.fullResync)
+        args.push('--full-resync');
+    args.push('--', 'bash', '-lc', remoteCmd);
+    return new Promise((resolve) => {
+        const proc = spawn('crabbox', args, { env: crabboxEnv(opts), stdio: ['ignore', 'pipe', 'pipe'] });
+        const pump = (chunk) => {
+            const s = chunk.toString('utf-8');
+            if (opts.onData)
+                opts.onData(s);
+            else
+                process.stdout.write(s);
+        };
+        proc.stdout.on('data', pump);
+        proc.stderr.on('data', pump);
+        proc.on('error', () => resolve(null));
+        proc.on('close', (code) => resolve(code));
+    });
+}
+/**
+ * Upload `script` to the box via `crabbox run --script-stdin` and run it.
+ *
+ * The script body travels over stdin and is written to a file on the box before
+ * execution — it never appears in argv / `ps` / shell history, which is why this
+ * is the transport for credential provisioning (the token contents live only in
+ * the uploaded script, then the file is removed by the script itself).
+ * Streams combined output; resolves with the remote exit code (null on dispatch failure).
+ */
+export function crabboxRunScript(slug, script, opts = {}) {
+    findCrabbox();
+    const args = ['run', '--id', slug, '--reclaim'];
+    if (opts.fullResync)
+        args.push('--full-resync');
+    args.push('--script-stdin');
+    return new Promise((resolve) => {
+        const proc = spawn('crabbox', args, { env: crabboxEnv(opts), stdio: ['pipe', 'pipe', 'pipe'] });
+        const pump = (chunk) => {
+            const s = chunk.toString('utf-8');
+            if (opts.onData)
+                opts.onData(s);
+            else
+                process.stdout.write(s);
+        };
+        proc.stdout.on('data', pump);
+        proc.stderr.on('data', pump);
+        proc.on('error', () => resolve(null));
+        proc.on('close', (code) => resolve(code));
+        proc.stdin.write(script);
+        proc.stdin.end();
+    });
+}
+/** Release the lease / delete the box. Best-effort; never throws. */
+export function crabboxStop(slug, opts = {}) {
+    try {
+        const r = spawnSync('crabbox', ['stop', '--id', slug], { encoding: 'utf-8', env: crabboxEnv(opts) });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/crabbox/lease.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `agents run --lease` orchestrator.
+ *
+ * Lease an ephemeral crabbox → provision the picked runtime(s) + their
+ * credentials → run the agent on the box (via `crabbox run`, which owns the
+ * SSH) → tear the box down. The whole box-side sequence rides a single
+ * `--script-stdin` body so the token contents never touch argv.
+ */
+import type { AgentId } from '../types.js';
+import { type CrabboxBox } from './cli.js';
+import { type DetectedRuntime } from './runtimes.js';
+export interface LeaseRunOptions {
+    agent: string;
+    prompt: string;
+    mode?: string;
+    model?: string;
+    /** Cloud backend crabbox provisions on (hetzner/aws/do/…). */
+    backend?: string;
+    boxClass?: string;
+    profile?: string;
+    /** Runtimes to install + authenticate on the box (from the picker). */
+    runtimes: AgentId[];
+    detected: DetectedRuntime[];
+    /** Secrets bundle providing crabbox's provider token. */
+    secretsBundle?: string;
+    onData?: (s: string) => void;
+    /** Keep the box after the run instead of stopping it. */
+    keep?: boolean;
+}
+export interface LeaseRunResult {
+    box: CrabboxBox;
+    exitCode: number | null;
+    toreDown: boolean;
+}
+/**
+ * Build the single bootstrap script run on the box: ensure agents-cli, install
+ * the picked runtime CLIs, write their credentials, run the agent, then shred
+ * the credential files. Best-effort install steps never abort the run.
+ */
+export declare function buildBootstrapScript(opts: LeaseRunOptions): string;
+export declare function leaseAndRun(opts: LeaseRunOptions): Promise<LeaseRunResult>;

package/dist/lib/crabbox/lease.js

@@ -0,0 +1,73 @@
+/**
+ * `agents run --lease` orchestrator.
+ *
+ * Lease an ephemeral crabbox → provision the picked runtime(s) + their
+ * credentials → run the agent on the box (via `crabbox run`, which owns the
+ * SSH) → tear the box down. The whole box-side sequence rides a single
+ * `--script-stdin` body so the token contents never touch argv.
+ */
+import { crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop } from './cli.js';
+import { buildCredentialScript } from './runtimes.js';
+/** POSIX single-quote for safe embedding in the generated bootstrap script. */
+function q(s) {
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+/**
+ * Build the single bootstrap script run on the box: ensure agents-cli, install
+ * the picked runtime CLIs, write their credentials, run the agent, then shred
+ * the credential files. Best-effort install steps never abort the run.
+ */
+export function buildBootstrapScript(opts) {
+    const credScript = buildCredentialScript(opts.runtimes, opts.detected);
+    const runParts = ['agents', 'run', q(opts.agent), q(opts.prompt), '--quiet'];
+    if (opts.mode)
+        runParts.push('--mode', q(opts.mode));
+    if (opts.model)
+        runParts.push('--model', q(opts.model));
+    // Credential files to shred after the run (home-level paths written above).
+    const shred = opts.runtimes
+        .map((id) => {
+        const cred = { claude: '.claude.json', codex: '.codex/auth.json', gemini: '.gemini/google_accounts.json', grok: '.grok/auth.json' }[id];
+        return cred ? `rm -f "$HOME/${cred}" 2>/dev/null || true` : '';
+    })
+        .filter(Boolean)
+        .join('\n');
+    const installRuntimes = opts.runtimes.map((id) => `agents add ${q(id)} >/dev/null 2>&1 || true`).join('\n');
+    return [
+        'set -uo pipefail',
+        'if ! command -v agents >/dev/null 2>&1; then npm install -g @phnx-labs/agents-cli >/dev/null 2>&1 || true; fi',
+        installRuntimes,
+        credScript,
+        `${runParts.join(' ')}`,
+        'rc=$?',
+        shred,
+        'exit $rc',
+    ]
+        .filter((l) => l.length > 0)
+        .join('\n');
+}
+export async function leaseAndRun(opts) {
+    const box = crabboxWarmup({
+        class: opts.boxClass,
+        profile: opts.profile,
+        provider: opts.backend,
+        secretsBundle: opts.secretsBundle,
+    });
+    await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+    const script = buildBootstrapScript(opts);
+    let exitCode = null;
+    let toreDown = false;
+    try {
+        exitCode = await crabboxRunScript(box.slug, script, {
+            secretsBundle: opts.secretsBundle,
+            onData: opts.onData,
+        });
+    }
+    finally {
+        // Always attempt teardown (bounds credential lifetime to the run) unless the
+        // caller explicitly asked to keep the box.
+        if (!opts.keep)
+            toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
+    }
+    return { box, exitCode, toreDown };
+}

package/dist/lib/crabbox/runtimes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Runtime detection + picker + credential-script builder for `agents run --lease`.
+ *
+ * The picker asks which coding-agent runtime(s) to provision on a leased box.
+ * The default selection is whatever the user is currently signed into locally
+ * (via `getAccountInfo`, the same source `agents view` uses). The chosen runtimes
+ * drive both what gets installed on the box and which auth token file is copied
+ * over — the token contents ride the uploaded `--script-stdin` body, never argv.
+ *
+ * SECURITY: copying a runtime's auth token to an ephemeral cloud box is a
+ * credential transfer. It is strictly opt-in (a confirm prompt in the command
+ * layer), the token never appears in argv/`ps`, and `--lease` one-shot runs tear
+ * the box down afterward so the credential's lifetime is bounded by the run.
+ */
+import type { AgentId } from '../types.js';
+/**
+ * Credential file locations per runtime. `localCandidates` are read in order
+ * (first existing wins); `remote` is where the box's CLI reads it by default
+ * (home-level — no per-version shim). Source of truth for these paths is
+ * `getAccountInfo` in src/lib/agents.ts; keep them in sync.
+ */
+interface RuntimeCred {
+    id: AgentId;
+    label: string;
+    localCandidates: string[];
+    remote: string;
+}
+export declare const LEASE_RUNTIMES: RuntimeCred[];
+export interface DetectedRuntime {
+    id: AgentId;
+    label: string;
+    email: string | null;
+    signedIn: boolean;
+    /** Absolute local path of the credential file, if found. */
+    credPath: string | null;
+}
+/** Which lease-capable runtimes the user is signed into on this machine. */
+export declare function detectSignedInRuntimes(): Promise<DetectedRuntime[]>;
+/**
+ * Interactive checkbox: which runtimes to provision on the box. Defaults to the
+ * signed-in ones. Runtimes with no local credential are shown disabled.
+ * `prompt` is injected so tests don't require a TTY.
+ */
+export declare function pickRuntimes(detected: DetectedRuntime[], prompt?: (choices: {
+    name: string;
+    value: AgentId;
+    checked: boolean;
+    disabled: boolean | string;
+}[]) => Promise<AgentId[]>): Promise<AgentId[]>;
+/**
+ * Build a bash snippet that writes each picked runtime's token file to the box's
+ * home-level config path (0600), from the token contents read locally. Returns
+ * `''` when no runtimes were selected. The snippet is meant to be embedded in
+ * the `--script-stdin` body (never argv).
+ */
+export declare function buildCredentialScript(picked: AgentId[], detected: DetectedRuntime[]): string;
+export {};

package/dist/lib/crabbox/runtimes.js

@@ -0,0 +1,109 @@
+/**
+ * Runtime detection + picker + credential-script builder for `agents run --lease`.
+ *
+ * The picker asks which coding-agent runtime(s) to provision on a leased box.
+ * The default selection is whatever the user is currently signed into locally
+ * (via `getAccountInfo`, the same source `agents view` uses). The chosen runtimes
+ * drive both what gets installed on the box and which auth token file is copied
+ * over — the token contents ride the uploaded `--script-stdin` body, never argv.
+ *
+ * SECURITY: copying a runtime's auth token to an ephemeral cloud box is a
+ * credential transfer. It is strictly opt-in (a confirm prompt in the command
+ * layer), the token never appears in argv/`ps`, and `--lease` one-shot runs tear
+ * the box down afterward so the credential's lifetime is bounded by the run.
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import { getAccountInfo } from '../agents.js';
+export const LEASE_RUNTIMES = [
+    { id: 'claude', label: 'Claude Code', localCandidates: ['.claude/.claude.json', '.claude.json'], remote: '.claude.json' },
+    { id: 'codex', label: 'Codex CLI', localCandidates: ['.codex/auth.json'], remote: '.codex/auth.json' },
+    { id: 'gemini', label: 'Gemini CLI', localCandidates: ['.gemini/google_accounts.json'], remote: '.gemini/google_accounts.json' },
+    { id: 'grok', label: 'Grok CLI', localCandidates: ['.grok/auth.json'], remote: '.grok/auth.json' },
+];
+/** First existing candidate path under the real home, or null. */
+function findLocalCred(cred) {
+    const home = process.env.AGENTS_REAL_HOME || os.homedir();
+    for (const rel of cred.localCandidates) {
+        const p = path.join(home, rel);
+        try {
+            if (fs.existsSync(p))
+                return p;
+        }
+        catch {
+            /* unreadable — skip */
+        }
+    }
+    return null;
+}
+/** Which lease-capable runtimes the user is signed into on this machine. */
+export async function detectSignedInRuntimes() {
+    const out = [];
+    for (const cred of LEASE_RUNTIMES) {
+        let info;
+        try {
+            info = await getAccountInfo(cred.id);
+        }
+        catch {
+            info = null;
+        }
+        out.push({
+            id: cred.id,
+            label: cred.label,
+            email: info?.email ?? null,
+            signedIn: !!info?.signedIn,
+            credPath: findLocalCred(cred),
+        });
+    }
+    return out;
+}
+/**
+ * Interactive checkbox: which runtimes to provision on the box. Defaults to the
+ * signed-in ones. Runtimes with no local credential are shown disabled.
+ * `prompt` is injected so tests don't require a TTY.
+ */
+export async function pickRuntimes(detected, prompt) {
+    const choices = detected.map((d) => ({
+        name: `${d.label}${d.email ? ` (${d.email})` : d.signedIn ? ' (signed in)' : ''}`,
+        value: d.id,
+        checked: d.signedIn && !!d.credPath,
+        disabled: d.credPath ? false : 'no local credential — sign in first',
+    }));
+    if (prompt)
+        return prompt(choices);
+    const { checkbox } = await import('@inquirer/prompts');
+    return checkbox({ message: 'Provision which runtime(s) on the leased box?', choices });
+}
+// A long random sentinel makes an accidental (or malicious) collision with a
+// token's contents effectively impossible, so the quoted heredoc can never be
+// closed early by the credential body.
+const CRED_EOF = 'AGENTS_LEASE_CRED_EOF_9f3c1a7b5e2d4068';
+/**
+ * Build a bash snippet that writes each picked runtime's token file to the box's
+ * home-level config path (0600), from the token contents read locally. Returns
+ * `''` when no runtimes were selected. The snippet is meant to be embedded in
+ * the `--script-stdin` body (never argv).
+ */
+export function buildCredentialScript(picked, detected) {
+    const byId = new Map(detected.map((d) => [d.id, d]));
+    const parts = [];
+    for (const id of picked) {
+        const d = byId.get(id);
+        const cred = LEASE_RUNTIMES.find((c) => c.id === id);
+        if (!d?.credPath || !cred)
+            continue;
+        let contents;
+        try {
+            contents = fs.readFileSync(d.credPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const dir = path.posix.dirname(cred.remote);
+        const mkdir = dir && dir !== '.' ? `mkdir -p "$HOME/${dir}"\n` : '';
+        parts.push(`${mkdir}cat > "$HOME/${cred.remote}" <<'${CRED_EOF}'\n${contents}${contents.endsWith('\n') ? '' : '\n'}${CRED_EOF}\n` +
+            `chmod 600 "$HOME/${cred.remote}"`);
+    }
+    return parts.join('\n');
+}

package/dist/lib/daemon.js

@@ -290,6 +290,36 @@ export async function runDaemon() {
     };
     const healInterval = setInterval(() => { void runHealCheck(); }, 6 * 60 * 60_000);
     const healKickoff = setTimeout(() => { void runHealCheck(); }, 30_000);
+    // Device probe: refresh registered devices' reachability and detect newly
+    // appeared tailnet nodes, dropping a sentinel per pending device so the
+    // menu-bar helper can surface "NEW DEVICES → Register / Ignore". Refresh mode
+    // never auto-registers a newcomer. Soft + overlap-guarded like session sync;
+    // a machine without tailscale is a clean no-op. ~every 3 min.
+    let probingDevices = false;
+    const runDeviceProbe = async () => {
+        if (probingDevices)
+            return;
+        probingDevices = true;
+        try {
+            const { runDeviceSync } = await import('./devices/sync.js');
+            const { reconcilePendingSentinels } = await import('./devices/pending.js');
+            const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
+            if (dev.ok) {
+                reconcilePendingSentinels(dev.pending);
+                if (dev.pending.length) {
+                    log('INFO', `devices: ${dev.pending.length} new pending (${dev.pending.map((p) => p.name).join(', ')})`);
+                }
+            }
+        }
+        catch (err) {
+            log('ERROR', `device probe failed: ${err.message}`);
+        }
+        finally {
+            probingDevices = false;
+        }
+    };
+    const deviceProbeInterval = setInterval(() => { void runDeviceProbe(); }, 3 * 60_000);
+    const deviceProbeKickoff = setTimeout(() => { void runDeviceProbe(); }, 15_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -307,6 +337,8 @@ export async function runDaemon() {
         clearInterval(syncInterval);
         clearInterval(healInterval);
         clearTimeout(healKickoff);
+        clearInterval(deviceProbeInterval);
+        clearTimeout(deviceProbeKickoff);
         removeDaemonPid();
         process.exit(0);
     };

package/dist/lib/devices/pending.d.ts

@@ -0,0 +1,18 @@
+export interface PendingDevice {
+    name: string;
+    platform: string;
+}
+/**
+ * Make the sentinel dir exactly match `pending`: create a file per pending
+ * device (content = platform), and delete any leftover sentinel whose device is
+ * no longer pending (it got registered, ignored, or left the tailnet). Best-
+ * effort — a filesystem error here must never crash the daemon, so callers pass
+ * this through their existing try/catch.
+ */
+export declare function reconcilePendingSentinels(pending: PendingDevice[]): void;
+/** Remove one device's pending sentinel (after the user registers or ignores it).
+ * No-op if it doesn't exist. */
+export declare function clearPendingSentinel(name: string): void;
+/** Read the current pending sentinels (name + platform). Used by tests and any
+ * TS-side consumer; the menu-bar helper reads the dir directly in Swift. */
+export declare function readPendingSentinels(): PendingDevice[];