@phnx-labs/agents-cli 1.20.71 → 1.20.73

package/dist/commands/feed.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { ensureFeedPublishHook, listBlocks, recordNotified } from '../lib/feed.js';
+import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified } from '../lib/feed.js';
+import { ensureActivityLogHook, readRecentActivity, formatActivityLine } from '../lib/activity.js';
 import { enrichBlocksFromSessions, groupBlocksByOutcome, isUnambiguousOutcomeAnswer, openBlocksForOutcome, stampBlockOutcomes, } from '../lib/feed-outcome.js';
 import { classifyBlock, filterBlocksForFeed, suppressionDigest, } from '../lib/ask-classifier.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
@@ -12,6 +13,9 @@ import { isValidMailboxId } from '../lib/mailbox.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
 import { GLYPH, masthead } from '../lib/comms-render.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { resolveProvider } from '../lib/cloud/registry.js';
+import { buildSessionSignals, rankFeedBlocks, synthesizeControlCards, } from '../lib/feed-ranking.js';
 export const FEED_NO_FANOUT_ENV = 'AGENTS_FEED_LOCAL';
 /** Right-hand masthead summary: `N blocks · M agents`. */
 export function formatFeedMastheadRight(blocks) {
@@ -58,6 +62,36 @@ export function mergeFeedBlocks(...groups) {
     }
     return [...byIdentity.values()].sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts));
 }
+function matchesControlTarget(signal, target) {
+    return [
+        signal.mailboxId,
+        signal.sessionId,
+        signal.cloudTaskId,
+        signal.pid !== undefined ? String(signal.pid) : undefined,
+    ].some((value) => value === target);
+}
+export async function controlFeedSession(action, target, signals) {
+    const signal = signals.find((s) => matchesControlTarget(s, target));
+    if (!signal)
+        throw new Error(`No live feed session matches '${target}'.`);
+    if (signal.cloudProvider && signal.cloudTaskId) {
+        const provider = resolveProvider(signal.cloudProvider);
+        await provider.cancel(signal.cloudTaskId);
+        return `${action === 'pause' ? 'paused' : 'killed'} cloud task ${signal.cloudTaskId}`;
+    }
+    if (!signal.pid) {
+        throw new Error(`Session '${target}' has no local pid or cancellable cloud task.`);
+    }
+    if (action === 'pause') {
+        if (process.platform === 'win32') {
+            throw new Error('Pause is not supported for local Windows processes; use --kill.');
+        }
+        process.kill(signal.pid, 'SIGSTOP');
+        return `paused pid ${signal.pid}`;
+    }
+    process.kill(signal.pid, 'SIGTERM');
+    return `killed pid ${signal.pid}`;
+}
 function hostToken(host) {
     return normalizeHost(host.split('@').pop() || host);
 }
@@ -69,6 +103,16 @@ export function remoteFeedHostsToDial(hosts, self) {
         return undefined;
     return hosts.filter((host) => hostToken(host) !== self);
 }
+export function prepareLocalFeedBlocks(localBlocks, opts) {
+    const filter = filterBlocksForFeed(localBlocks, {
+        apply: opts.includeLocal && (!opts.all || opts.dispatch === true),
+    });
+    return {
+        visible: opts.all ? localBlocks : filter.surfaced,
+        dispatch: filter.surfaced,
+        filter,
+    };
+}
 function renderBlock(b, localHost, indent = '') {
     const host = b.host !== localHost ? chalk.yellow(` [${b.host}]`) : '';
     const runtime = chalk.gray(b.runtime);
@@ -76,13 +120,16 @@ function renderBlock(b, localHost, indent = '') {
     const cls = b.blockClass ? chalk.gray(`(${b.blockClass})`) : '';
     const consequence = b.consequence && b.consequence !== 'normal' ? chalk.red(`[${b.consequence}]`) : '';
     const cost = b.costOfDelay ? chalk.gray(`cost:${b.costOfDelay}`) : '';
+    const rank = b.delayRank ? chalk.gray(`rank:${Math.round(b.delayRank.score)}`) : '';
     // Shared fleet-comms glyphs: ▲ open ask, ✓ answered (see comms-render GLYPH).
     const marker = b.answer
         ? chalk.green(GLYPH.delivered)
-        : !b.parkedAt
-            ? chalk.yellow(GLYPH.ask)
-            : ' ';
-    console.log(`${indent}${marker} ${chalk.cyan(b.mailboxId)}${host}  ${runtime}  ${age}  ${cls} ${consequence} ${cost}`.trimEnd());
+        : b.kind === 'control'
+            ? chalk.red('!')
+            : !b.parkedAt
+                ? chalk.yellow(GLYPH.ask)
+                : ' ';
+    console.log(`${indent}${marker} ${chalk.cyan(b.mailboxId)}${host}  ${runtime}  ${age}  ${cls} ${consequence} ${cost} ${rank}`.trimEnd());
     for (const question of b.questions) {
         const header = question.header ? chalk.gray(`[${question.header}] `) : '';
         console.log(`${indent}  ${header}${question.text}`);
@@ -119,7 +166,15 @@ function renderBlock(b, localHost, indent = '') {
     if (b.notifiedAt) {
         console.log(`${indent}  ${chalk.dim('notified')} ${relTime(b.notifiedAt)}`);
     }
-    if (!b.answer && !b.parkedAt) {
+    if (b.runaway) {
+        console.log(`${indent}  ${chalk.red('runaway:')} ${b.runaway.reason}`);
+        console.log(`${indent}  ${chalk.dim(`control: ag feed --pause ${b.mailboxId}  ·  ag feed --kill ${b.mailboxId}`)}`);
+    }
+    if (b.needy) {
+        console.log(`${indent}  ${chalk.yellow('needy:')} ${b.needy.askCountLastHour}/${b.needy.threshold} asks in the last hour`);
+        console.log(`${indent}  ${chalk.dim(`inspect: ag sessions ${b.sessionId}`)}`);
+    }
+    if (!b.answer && !b.parkedAt && b.kind !== 'control') {
         console.log(`${indent}  ${chalk.dim(formatFeedReplyHint(b.mailboxId))}`);
     }
     console.log();
@@ -169,6 +224,8 @@ export function registerFeedCommand(program) {
         .option('-H, --host <target...>', 'Scope to remote machine(s) over SSH; repeatable')
         .option('--device <target...>', 'Alias for --host; repeatable')
         .option('--dispatch', 'Run stall suppression + default-on-no-answer policy and urgent notifications')
+        .option('--pause <id>', 'Pause a runaway/needy local process (SIGSTOP) or cancel a cloud task')
+        .option('--kill <id>', 'Kill a runaway/needy local process (SIGTERM) or cancel a cloud task')
         .action(async (opts) => {
         if (opts.device?.length)
             opts.host = [...(opts.host ?? []), ...opts.device];
@@ -176,11 +233,16 @@ export function registerFeedCommand(program) {
         const includeLocal = shouldIncludeLocalFeed(opts.host, self);
         const setupWarnings = [];
         if (includeLocal) {
+            // Feed and activity hooks are independent -- install both, and register
+            // the manifest as long as at least one wrote its entries (don't couple
+            // activity registration to the feed hook succeeding).
             const hookInstall = ensureFeedPublishHook();
-            if (hookInstall.error) {
+            const activityInstall = ensureActivityLogHook();
+            if (hookInstall.error)
                 setupWarnings.push(hookInstall.error);
-            }
-            else {
+            if (activityInstall.error)
+                setupWarnings.push(activityInstall.error);
+            if (!hookInstall.error || !activityInstall.error) {
                 const [{ iterHooksCapableVersions, parseHookManifest, registerHooksToSettings }, { getVersionHomePath }] = await Promise.all([
                     import('../lib/hooks.js'),
                     import('../lib/versions.js'),
@@ -199,6 +261,17 @@ export function registerFeedCommand(program) {
         if (includeLocal) {
             sessions = await getActiveSessions();
         }
+        const sessionMetas = includeLocal && sessions.length > 0 ? await discoverSessions({ all: true, limit: 5000 }) : [];
+        const localSignals = buildSessionSignals(sessions, sessionMetas);
+        if (opts.pause || opts.kill) {
+            if (!includeLocal) {
+                throw new Error('Feed controls run on the local machine. Re-run against the target host with --local.');
+            }
+            const action = opts.pause ? 'pause' : 'kill';
+            const target = opts.pause ?? opts.kill ?? '';
+            console.log(await controlFeedSession(action, target, localSignals));
+            return;
+        }
         if (opts.dispatch && includeLocal) {
             // Liveness sweep: drop messages to dead agents and retire stale blocks
             // before we render the feed.
@@ -208,8 +281,26 @@ export function registerFeedCommand(program) {
                 console.log(chalk.yellow(`gc: ${gcResult.messagesDroppedDead} dead messages, ${gcResult.blocksRemoved} stale blocks removed`));
             }
         }
-        const localBlocks = includeLocal ? listBlocks() : [];
-        let blocks = localBlocks;
+        let localBlocks = includeLocal
+            ? [...listBlocks(), ...synthesizeControlCards(localSignals, listAskStats())]
+            : [];
+        // Fill missing ticket/PR/worktree from live session meta before local
+        // policy mutates the store, so outcome keys land even when the publish
+        // hook had no deliverable stamp.
+        if (sessions.length > 0) {
+            localBlocks = enrichBlocksFromSessions(localBlocks, sessionHintsFromActive(sessions));
+        }
+        // Stall suppression (RUSH-1477) must only mutate blocks owned by this
+        // machine. Remote peers run their own `feed --json`; never enqueue a
+        // policy answer into a local mailbox for a remote agent.
+        const preparedLocal = prepareLocalFeedBlocks(localBlocks, {
+            includeLocal,
+            all: opts.all,
+            dispatch: opts.dispatch,
+        });
+        const visibleLocalBlocks = preparedLocal.visible;
+        const dispatchBlocks = preparedLocal.dispatch;
+        let blocks = visibleLocalBlocks;
         const forceLocal = opts.local === true || process.env[FEED_NO_FANOUT_ENV] === '1';
         if (!forceLocal) {
             const remoteHosts = remoteFeedHostsToDial(opts.host, self);
@@ -221,31 +312,18 @@ export function registerFeedCommand(program) {
                     hosts: remoteHosts,
                     parse: parseRemoteFeed,
                 });
-                blocks = mergeFeedBlocks(localBlocks, remote.items);
+                blocks = mergeFeedBlocks(visibleLocalBlocks, remote.items);
             }
         }
-        // Fill missing ticket/PR/worktree from live session meta so outcome keys
-        // land even when the publish hook had no deliverable stamp.
-        if (sessions.length > 0) {
-            blocks = enrichBlocksFromSessions(blocks, sessionHintsFromActive(sessions));
-        }
-        // Stall suppression (RUSH-1477): auto-answer "should I…?" / "what's next?"
-        // so they never render. Applied on every feed read unless --all; --dispatch
-        // also applies so unattended ticks drain the stall backlog.
-        const filter = filterBlocksForFeed(blocks, {
-            apply: !opts.all || opts.dispatch === true,
-        });
-        if (!opts.all) {
-            blocks = filter.surfaced;
-        }
-        const digest = suppressionDigest(filter);
+        blocks = rankFeedBlocks(blocks, localSignals);
+        const digest = suppressionDigest(preparedLocal.filter);
         if (digest && !opts.json) {
             console.log(chalk.dim(digest));
         }
         if (opts.dispatch) {
             const policy = loadPolicy();
             const now = new Date();
-            for (const b of blocks) {
+            for (const b of dispatchBlocks) {
                 // Wrap per-block policy so one malformed block (e.g. a crafted
                 // mailboxId that throws in mailboxDir) can't abort the whole loop and
                 // strand every remaining block's dispatch.
@@ -285,6 +363,8 @@ export function registerFeedCommand(program) {
         }
         if (blocks.length === 0) {
             console.log(chalk.gray(digest ? 'No open blocks after stall suppression.' : 'No open blocks.'));
+            if (includeLocal)
+                renderActivityLane();
             return;
         }
         // Shared fleet-comms masthead (same family as `agents mailboxes`).
@@ -300,8 +380,29 @@ export function registerFeedCommand(program) {
                 renderBlock(b, self);
             return;
         }
-        const groups = groupBlocksByOutcome(blocks);
+        const groups = groupBlocksByOutcome(blocks).sort((a, b) => {
+            const ar = Math.max(...a.blocks.map((block) => block.delayRank?.score ?? 0));
+            const br = Math.max(...b.blocks.map((block) => block.delayRank?.score ?? 0));
+            return br - ar;
+        });
         for (const g of groups)
             renderOutcomeGroup(g, self);
+        if (includeLocal)
+            renderActivityLane();
     });
 }
+/**
+ * Print a compact "recent activity" lane under the feed: the last few milestone
+ * events (plans, PRs, worktrees, sub-agents) from the append-only activity logs.
+ * Read-only tail of the logs -- no transcript re-parsing. Silent when empty.
+ */
+function renderActivityLane() {
+    const events = readRecentActivity({ sinceMs: Date.now() - 24 * 60 * 60 * 1000, limit: 6 })
+        .filter((e) => e.tier === 'milestone');
+    if (events.length === 0)
+        return;
+    console.log(chalk.bold('\n  recent activity'));
+    for (const ev of events)
+        console.log(formatActivityLine(ev, { showHost: true }));
+    console.log(chalk.gray('  → agents activity  for the full stream'));
+}

package/dist/commands/hq.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerHqCommand(program: Command): void;

package/dist/commands/hq.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { getActiveSessions } from '../lib/session/active.js';
+import { AgentManager } from '../lib/teams/agents.js';
+import { handleStatus, handleTasks } from '../lib/teams/api.js';
+import { listAskStats, listBlocks } from '../lib/feed.js';
+import { buildSessionSignals, synthesizeControlCards } from '../lib/feed-ranking.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { buildHqFloor } from '../lib/hq/floor.js';
+import { die } from '../lib/format.js';
+async function collectFloorSnapshot() {
+    const manager = new AgentManager();
+    const [sessions, tasksResult] = await Promise.all([
+        getActiveSessions(),
+        handleTasks(manager, 1000),
+    ]);
+    const teammatesByTeam = new Map();
+    await Promise.all(tasksResult.tasks.map(async (team) => {
+        const status = await handleStatus(manager, team.task_name, 'all');
+        teammatesByTeam.set(team.task_name, status.agents);
+    }));
+    const sessionMetas = sessions.length > 0 ? await discoverSessions({ all: true, limit: 5000 }) : [];
+    const blocks = [
+        ...listBlocks(),
+        ...synthesizeControlCards(buildSessionSignals(sessions, sessionMetas), listAskStats()),
+    ];
+    return buildHqFloor({
+        sessions,
+        teams: tasksResult.tasks,
+        teammatesByTeam,
+        blocks,
+    });
+}
+export function registerHqCommand(program) {
+    const hq = program
+        .command('hq')
+        .description('Machine-readable bridge for Agents HQ floor management.');
+    hq
+        .command('floor')
+        .description('Emit the live floor snapshot: rooms, agents, ambient events, and runnable actions.')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (opts) => {
+        try {
+            const snapshot = await collectFloorSnapshot();
+            if (opts.json || !process.stdout.isTTY) {
+                console.log(JSON.stringify(snapshot, null, 2));
+                return;
+            }
+            console.log(chalk.bold('Agents HQ floor'));
+            console.log(chalk.gray(`${snapshot.counters.agents} agents, ${snapshot.counters.rooms} rooms, ${snapshot.counters.needsInput} need input`));
+            for (const room of snapshot.rooms) {
+                console.log(`${chalk.cyan(room.name)}  ${chalk.gray(`${room.counts.agents} agents, ${room.counts.running} running, ${room.counts.needsInput} need input`)}`);
+            }
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+}

package/dist/commands/lease.d.ts

@@ -8,6 +8,25 @@
  * so a box a concurrent run just reused is never stopped.
  */
 import type { Command } from 'commander';
+import { type CrabboxBox } from '../lib/crabbox/cli.js';
+/** Compact human duration: "45s", "12m", "2h", "1h 5m". Clamps negatives to 0. */
+export declare function fmtDurationShort(secs: number): string;
+/** Idle time since the box was last touched, e.g. "idle 5m" / "idle ?". */
+export declare function fmtIdleShort(box: CrabboxBox, nowSecs: number): string;
+/** Time until the lease expires, e.g. "expires 42m" / "expires ?" / "expired". */
+export declare function fmtExpiresShort(box: CrabboxBox, nowSecs: number): string;
+/** Reachable address for a leased box: tailnet FQDN/IP first, else public IP. */
+export declare function boxAddress(box: CrabboxBox): string | undefined;
+/** Human status: "ready" when usable, else the raw bootstrap state/status. */
+export declare function boxStatus(box: CrabboxBox): string;
+/**
+ * Warm boxes eligible for reuse: `ready` and the lease has not expired.
+ * Sorted most-recently-touched first so `--reuse` / the auto-pick lands on the
+ * freshest box (an untouched `lastTouchedAt` sorts last).
+ */
+export declare function reusableBoxes(boxes: CrabboxBox[], nowSecs: number): CrabboxBox[];
+/** One aligned row for the reuse picker / `agents lease list`. */
+export declare function formatBoxRow(box: CrabboxBox, nowSecs: number): string;
 /** Validate a Hetzner token against the live API. Exported for unit tests (fetch injectable). */
 export declare function validateHetznerToken(token: string, fetchImpl?: typeof fetch): Promise<'valid' | 'invalid' | 'unreachable'>;
 /**

package/dist/commands/lease.js

@@ -7,9 +7,9 @@
  * that have been untouched for a safety window are eligible (see `isReapSafe`),
  * so a box a concurrent run just reused is never stopped.
  */
-import { spawn } from 'child_process';
 import chalk from 'chalk';
-import { crabboxList, reapSafeOrphans, reapOrphans, setLeaseSecretsBundle } from '../lib/crabbox/cli.js';
+import { openUrl } from '../lib/open-url.js';
+import { crabboxList, crabboxStop, reapSafeOrphans, reapOrphans, setLeaseSecretsBundle } from '../lib/crabbox/cli.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { bundleExists, readBundle, writeBundle, keychainRef, bundleItemStore } from '../lib/secrets/bundles.js';
 import { secretsKeychainItem } from '../lib/secrets/index.js';
@@ -19,21 +19,104 @@ function fmtIdle(box) {
     const iso = new Date(box.lastTouchedAt * 1000).toISOString().slice(0, 16).replace('T', ' ');
     return `idle since ${iso}Z`;
 }
+// ── Shared box helpers (consumed by exec.ts's reuse picker + ssh.ts's devices
+// section, so the reuse/format logic lives in exactly one place) ─────────────
+/** Compact human duration: "45s", "12m", "2h", "1h 5m". Clamps negatives to 0. */
+export function fmtDurationShort(secs) {
+    const s = Math.max(0, Math.round(secs));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    const rem = m % 60;
+    return rem ? `${h}h ${rem}m` : `${h}h`;
+}
+/** Idle time since the box was last touched, e.g. "idle 5m" / "idle ?". */
+export function fmtIdleShort(box, nowSecs) {
+    if (box.lastTouchedAt === null)
+        return 'idle ?';
+    return `idle ${fmtDurationShort(nowSecs - box.lastTouchedAt)}`;
+}
+/** Time until the lease expires, e.g. "expires 42m" / "expires ?" / "expired". */
+export function fmtExpiresShort(box, nowSecs) {
+    if (box.expiresAt === null)
+        return 'expires ?';
+    const left = box.expiresAt - nowSecs;
+    return left <= 0 ? 'expired' : `expires ${fmtDurationShort(left)}`;
+}
+/** Reachable address for a leased box: tailnet FQDN/IP first, else public IP. */
+export function boxAddress(box) {
+    return box.tailscaleFQDN || box.tailscaleIPv4 || box.ip || undefined;
+}
+/** Human status: "ready" when usable, else the raw bootstrap state/status. */
+export function boxStatus(box) {
+    return box.ready ? 'ready' : box.state || box.status || 'pending';
+}
+/**
+ * Warm boxes eligible for reuse: `ready` and the lease has not expired.
+ * Sorted most-recently-touched first so `--reuse` / the auto-pick lands on the
+ * freshest box (an untouched `lastTouchedAt` sorts last).
+ */
+export function reusableBoxes(boxes, nowSecs) {
+    return boxes
+        .filter((b) => b.ready && (b.expiresAt === null || b.expiresAt > nowSecs))
+        .sort((a, b) => (b.lastTouchedAt ?? 0) - (a.lastTouchedAt ?? 0));
+}
+/** One aligned row for the reuse picker / `agents lease list`. */
+export function formatBoxRow(box, nowSecs) {
+    const slug = box.slug.padEnd(16);
+    const cls = (box.class ?? '?').padEnd(10);
+    const addr = (boxAddress(box) ?? '—').padEnd(24);
+    const status = boxStatus(box).padEnd(8);
+    const idle = fmtIdleShort(box, nowSecs).padEnd(12);
+    return `${slug} ${cls} ${addr} ${status} ${idle} ${fmtExpiresShort(box, nowSecs)}`;
+}
 const HETZNER_BUNDLE = 'hetzner.com';
 const HCLOUD_KEY = 'HCLOUD_TOKEN';
 const HETZNER_CONSOLE_URL = 'https://console.hetzner.cloud/';
-/** Best-effort: open a URL in the user's default browser. Never throws. */
-function openUrl(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+const TAILSCALE_BUNDLE = 'tailscale.com';
+const TAILSCALE_KEY = 'CRABBOX_TAILSCALE_AUTH_KEY';
+const TAILSCALE_KEYS_URL = 'https://login.tailscale.com/admin/settings/keys';
+/**
+ * Optional Tailscale setup for private-network leases (`--tailscale`). Collects
+ * an EPHEMERAL, pre-authorized, `tag:crabbox` auth key and stores it in the
+ * `tailscale.com` keychain bundle under `CRABBOX_TAILSCALE_AUTH_KEY` (the exact
+ * key `crabboxEnv` auto-injects). Blank input skips — public-IP leases still
+ * work with no Tailscale key. Never throws for cancel; mirrors the Hetzner
+ * capture above but does no live validation (Tailscale has no cheap probe).
+ */
+async function captureTailscaleAuthKey() {
+    console.error(chalk.bold('\nOptional: private-network leases over Tailscale'));
+    console.error(chalk.dim('Mint an EPHEMERAL, pre-authorized auth key tagged `tag:crabbox` in the Tailscale admin,'));
+    console.error(chalk.dim('then paste it to reach leased boxes only over your tailnet (`--tailscale`). Leave blank to skip.\n'));
+    const { password } = await import('@inquirer/prompts');
+    let key;
     try {
-        const p = spawn(cmd, args, { stdio: 'ignore', detached: true });
-        p.on('error', () => { });
-        p.unref();
+        openUrl(TAILSCALE_KEYS_URL);
+        key = (await password({ message: 'Paste a Tailscale auth key (blank to skip):', mask: true })).trim();
     }
-    catch {
-        /* best-effort */
+    catch (e) {
+        if (isPromptCancelled(e)) {
+            console.error(chalk.yellow('Skipped Tailscale setup.'));
+            return;
+        }
+        throw e;
+    }
+    if (!key) {
+        console.error(chalk.dim('Skipped Tailscale setup — public-IP leases only.'));
+        return;
     }
+    const bundle = bundleExists(TAILSCALE_BUNDLE)
+        ? readBundle(TAILSCALE_BUNDLE)
+        : { name: TAILSCALE_BUNDLE, description: 'Tailscale ephemeral auth key for crabbox tailnet leases', vars: {} };
+    const store = bundleItemStore(bundle.backend);
+    store.set(secretsKeychainItem(TAILSCALE_BUNDLE, TAILSCALE_KEY), key);
+    bundle.vars[TAILSCALE_KEY] = keychainRef(TAILSCALE_KEY);
+    writeBundle(bundle);
+    console.error(chalk.green(`✔ Stored Tailscale auth key in keychain bundle '${TAILSCALE_BUNDLE}'.`));
+    console.error(chalk.dim('  Add --tailscale to a lease (reuse defaults to it) to reach the box over your tailnet.'));
 }
 /** Validate a Hetzner token against the live API. Exported for unit tests (fetch injectable). */
 export async function validateHetznerToken(token, fetchImpl = fetch) {
@@ -103,6 +186,8 @@ export async function runLeaseSetup(opts = {}) {
             setLeaseSecretsBundle(HETZNER_BUNDLE);
             console.error(chalk.green(`\n✔ Stored in keychain bundle '${HETZNER_BUNDLE}' and set as the default lease provider.`));
             console.error(chalk.dim('  Run `agents run <agent> "…" --lease` — no env var, no flag needed.'));
+            // Also offer to capture a Tailscale auth key for private-network leases.
+            await captureTailscaleAuthKey();
             return true;
         }
         console.error(chalk.yellow('lease setup: no valid token after 3 attempts — aborted.'));
@@ -128,6 +213,48 @@ export function registerLeaseCommand(program) {
         const ok = await runLeaseSetup({ provider: opts.provider });
         process.exit(ok ? 0 : 1);
     });
+    lease
+        .command('list')
+        .alias('ls')
+        .description('List warm crabbox boxes you can reuse with `agents run --box <slug>`.')
+        .option('--json', 'Output JSON', false)
+        .action((opts) => {
+        const boxOpts = { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE };
+        let boxes;
+        try {
+            boxes = crabboxList(boxOpts);
+        }
+        catch (e) {
+            console.error(chalk.red(`lease list: ${e.message}`));
+            process.exit(1);
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(boxes, null, 2));
+            return;
+        }
+        if (boxes.length === 0) {
+            console.error(chalk.gray('No crabbox boxes. `agents run <agent> "…" --lease` provisions one.'));
+            return;
+        }
+        const nowSecs = Math.floor(Date.now() / 1000);
+        console.log(chalk.bold(`Warm boxes (${boxes.length})`));
+        for (const b of boxes)
+            console.log('  ' + formatBoxRow(b, nowSecs));
+        console.log(chalk.gray('  Reuse: agents run <agent> "…" --box <slug>   ·   Stop: agents lease stop <slug>'));
+    });
+    lease
+        .command('stop <slug>')
+        .description('Stop (release) a leased crabbox box now.')
+        .action((slug) => {
+        const boxOpts = { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE };
+        const ok = crabboxStop(slug, boxOpts);
+        if (ok)
+            console.error(chalk.green(`Stopped box ${slug}.`));
+        else
+            console.error(chalk.red(`Could not stop box ${slug} (already gone, or crabbox is unavailable).`));
+        process.exit(ok ? 0 : 1);
+    });
     lease
         .command('gc')
         .description('Stop expired, idle lease boxes that are holding your provider quota. Safe: never stops a box in active use.')

package/dist/commands/login.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerLoginCommands(program: Command): void;

package/dist/commands/login.js

@@ -0,0 +1,123 @@
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { readStdinSync } from '../lib/format.js';
+import { clearVaultKey, createVault, getVaultSession, joinVault, unlock, vaultExists, vaultPath, } from '../lib/secrets/vault.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+async function promptPassword(message) {
+    if (!isInteractiveTerminal()) {
+        throw new Error('A password is required. Run from a TTY or pass --password-stdin.');
+    }
+    const { password } = await import('@inquirer/prompts');
+    return password({ message, mask: true });
+}
+async function readPassword(opts, message) {
+    if (opts.passwordStdin) {
+        const value = readStdinSync();
+        if (!value)
+            throw new Error('No password received on stdin.');
+        return value.replace(/\r?\n$/, '');
+    }
+    return promptPassword(message);
+}
+async function chooseFreshLoginMode(opts) {
+    if (opts.create && opts.join)
+        throw new Error('--create and --join are mutually exclusive.');
+    if (opts.create)
+        return 'create';
+    if (opts.join)
+        return 'join';
+    if (!isInteractiveTerminal()) {
+        throw new Error('No synced secrets file exists. Pass --create or --join <vault.age> in a non-interactive shell.');
+    }
+    const { select } = await import('@inquirer/prompts');
+    return select({
+        message: 'No synced secrets login found. What do you want to do?',
+        choices: [
+            { name: 'Create a new login', value: 'create' },
+            { name: 'Join with an existing synced secrets file', value: 'join' },
+        ],
+    });
+}
+function formatRemaining(expiresAt) {
+    const ms = expiresAt - Date.now();
+    if (ms <= 0)
+        return 'expired';
+    const mins = Math.round(ms / 60000);
+    if (mins < 60)
+        return `${mins} minute${mins === 1 ? '' : 's'}`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? '' : 's'}`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? '' : 's'}`;
+}
+export function registerLoginCommands(program) {
+    program
+        .command('login')
+        .description('Unlock synced secrets for this shell session')
+        .option('--create', 'Create a new encrypted synced-secrets file at ~/.agents/vault.age')
+        .option('--join <path>', 'Copy and unlock an existing vault.age file')
+        .option('--force', 'Replace an existing synced-secrets file when used with --create or --join')
+        .option('--password-stdin', 'Read the master password from stdin')
+        .action(async (opts) => {
+        try {
+            if (opts.force && !opts.create && !opts.join) {
+                throw new Error('--force can only be used with --create or --join.');
+            }
+            if (vaultExists() && !opts.create && !opts.join) {
+                const password = await readPassword(opts, 'Master password');
+                unlock(password);
+                const session = getVaultSession();
+                const ttl = session.loggedIn ? formatRemaining(session.expiresAt) : '8 hours';
+                console.log(chalk.green(`Logged in. Synced secrets unlocked for ${ttl}.`));
+                return;
+            }
+            const mode = await chooseFreshLoginMode(opts);
+            if (mode === 'join') {
+                let source = opts.join;
+                if (!source) {
+                    if (!isInteractiveTerminal())
+                        throw new Error('--join needs a vault.age path.');
+                    const { input } = await import('@inquirer/prompts');
+                    source = await input({
+                        message: 'Path to existing vault.age',
+                        validate: (value) => fs.existsSync(value) || 'File not found.',
+                    });
+                }
+                const password = await readPassword(opts, 'Master password');
+                joinVault(password, source, { overwrite: opts.force });
+                console.log(chalk.green(`Logged in. Copied synced secrets file to ${vaultPath()}.`));
+                return;
+            }
+            const password = await readPassword(opts, 'Choose a master password');
+            createVault(password, { overwrite: opts.force });
+            console.log(chalk.green(`Logged in. Created synced secrets file at ${vaultPath()}.`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    program
+        .command('logout')
+        .description('Forget the cached synced-secrets key')
+        .action(() => {
+        clearVaultKey();
+        console.log(chalk.green('Logged out. Synced secrets are locked.'));
+    });
+    program
+        .command('whoami')
+        .description('Show synced-secrets login status')
+        .action(() => {
+        const session = getVaultSession();
+        if (!session.loggedIn) {
+            console.log(chalk.yellow('Not logged in.'));
+            console.log(chalk.gray(`File: ${vaultPath()}${vaultExists() ? '' : ' (not created)'}`));
+            return;
+        }
+        console.log(chalk.green(`Logged in (${formatRemaining(session.expiresAt)} remaining).`));
+        console.log(chalk.gray(`File: ${vaultPath()}`));
+    });
+}