hivehq 2.0.0

package/dist/src/cli/hive-remote.js

@@ -0,0 +1,257 @@
+import { createAppStateStore } from '../server/app-state-store.js';
+import { getMachineName } from '../server/machine-name.js';
+import { DEFAULT_GATEWAY_URL, REMOTE_DAEMON_ID_KEY, REMOTE_DAEMON_TOKEN_KEY, REMOTE_ENABLED_KEY, REMOTE_GATEWAY_URL_KEY, } from '../server/remote-config-keys.js';
+import { createRemoteDeviceStore } from '../server/remote-device-store.js';
+import { openRuntimeDatabase } from '../server/runtime-database.js';
+import { resolveDataDir } from './hive.js';
+// Re-export so existing callers (and the CLI tests) can keep importing the keys
+// from here; the canonical definitions live in remote-config-keys.ts, shared
+// with the daemon-side tunnel so the on-disk contract can't drift between sides.
+export { DEFAULT_GATEWAY_URL, REMOTE_DAEMON_ID_KEY, REMOTE_DAEMON_TOKEN_KEY, REMOTE_ENABLED_KEY, REMOTE_GATEWAY_URL_KEY, };
+// `hive remote` — manage the daemon's connection to the remote-access gateway.
+//
+//   hive remote login [--gateway <url>]   bind this machine to a Hive account
+//   hive remote status                    show connection + enabled state
+//   hive remote logout                    forget the gateway token, disable remote
+//   hive remote devices                   list paired phones/devices
+//   hive remote revoke <deviceId>         revoke a paired device
+//
+// login drives the gateway's daemon-binding flow (gateway/src/daemon.ts):
+//   POST /daemon/code  -> { code, expiresAt, pollIntervalMs }   (print URL + code)
+//   ... human approves in their logged-in browser at /daemon/approve?code=... ...
+//   POST /daemon/token -> 401 not_approved (keep polling) | 200 { daemonId, daemonToken }
+//
+// The token is account-scoped and is local RCE on this machine, so it lands in
+// app_state (the same SQLite the daemon reads) and is NEVER printed back.
+// `enabled` defaults OFF for the whole subsystem; a successful login flips it on.
+// Off == zero behavior change: no token, no outbound tunnel (see remote-tunnel).
+export const HIVE_REMOTE_USAGE = [
+    'Usage:',
+    '  hive remote login [--gateway <url>]   Link this machine to your Hive account.',
+    '  hive remote status                    Show remote-access connection state.',
+    '  hive remote logout                    Forget the gateway token and disable remote.',
+    '  hive remote devices                   List paired devices.',
+    '  hive remote revoke <deviceId>         Revoke a paired device.',
+    '',
+    'Remote access lets you reach this Hive from a phone through the gateway over',
+    'an end-to-end encrypted tunnel. It is OFF until you log in, and `logout`',
+    'turns it off again. The gateway only relays ciphertext — it never sees your',
+    'data or terminals.',
+    '',
+    'Options:',
+    `  --gateway <url>   Gateway base URL (default: ${DEFAULT_GATEWAY_URL}).`,
+    '  -h, --help        Print this help.',
+].join('\n');
+const openConfigStore = () => {
+    const db = openRuntimeDatabase(resolveDataDir());
+    return { store: createAppStateStore(db), close: () => db.close() };
+};
+const readConfig = (store, key) => store.get(key)?.value ?? null;
+const openDeviceStore = () => {
+    const db = openRuntimeDatabase(resolveDataDir());
+    return { store: createRemoteDeviceStore(db), close: () => db.close() };
+};
+const trimSlash = (url) => url.replace(/\/+$/, '');
+const postJson = async (url, body, token) => {
+    const headers = { 'content-type': 'application/json' };
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    return fetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+};
+// Default client: real fetch against the gateway. The contracts mirror
+// gateway/src/daemon.ts exactly (field names, the 401 not_approved poll signal).
+export const defaultGatewayClient = {
+    async requestCode(gatewayUrl) {
+        const res = await postJson(`${trimSlash(gatewayUrl)}/daemon/code`, {});
+        if (!res.ok)
+            throw new Error(`gateway /daemon/code failed: ${res.status}`);
+        const body = (await res.json());
+        if (typeof body.code !== 'string' || typeof body.expiresAt !== 'number') {
+            throw new Error('gateway /daemon/code returned an unexpected response');
+        }
+        return {
+            code: body.code,
+            expiresAt: body.expiresAt,
+            pollIntervalMs: typeof body.pollIntervalMs === 'number' ? body.pollIntervalMs : 2000,
+        };
+    },
+    async exchangeToken(gatewayUrl, code, name) {
+        const payload = { code };
+        if (name)
+            payload.name = name;
+        const res = await postJson(`${trimSlash(gatewayUrl)}/daemon/token`, payload);
+        // 401 == not yet approved (or expired). 429 == the gateway throttled this poll. Both mean "keep
+        // polling until the code's expiresAt" — a transient 429 mid-wait must NOT kill the login (the
+        // gateway sizes the /daemon/token budget for the poll cadence, but we stay robust if it ever
+        // trips). Any other non-2xx is a hard failure.
+        if (res.status === 401 || res.status === 429)
+            return null;
+        if (!res.ok)
+            throw new Error(`gateway /daemon/token failed: ${res.status}`);
+        const body = (await res.json());
+        if (typeof body.daemonId !== 'string' || typeof body.daemonToken !== 'string') {
+            throw new Error('gateway /daemon/token returned an unexpected response');
+        }
+        return { daemonId: body.daemonId, daemonToken: body.daemonToken };
+    },
+};
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const readGatewayFlag = (argv) => {
+    const index = argv.indexOf('--gateway');
+    if (index === -1)
+        return undefined;
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) {
+        throw new Error('Usage: hive remote login [--gateway <url>]');
+    }
+    return value;
+};
+const approveUrl = (gatewayUrl, code) => `${trimSlash(gatewayUrl)}/daemon/approve?code=${encodeURIComponent(code)}`;
+const runLogin = async (argv, store, client, now, sleep, log) => {
+    const gatewayUrl = readGatewayFlag(argv) ?? readConfig(store, REMOTE_GATEWAY_URL_KEY) ?? DEFAULT_GATEWAY_URL;
+    const { code, expiresAt, pollIntervalMs } = await client.requestCode(gatewayUrl);
+    log('To link this machine, open the approval page in a browser where you are');
+    log('logged in to your Hive account, and confirm the code matches:');
+    log('');
+    log(`  ${approveUrl(gatewayUrl, code)}`);
+    log('');
+    log(`  Code: ${code}`);
+    log('');
+    log('Waiting for approval…');
+    const machineName = getMachineName() ?? undefined;
+    // Poll until the human approves or the code expires. The gateway hands back
+    // null (HTTP 401) until approval flips the code; we never bail early.
+    for (;;) {
+        const token = await client.exchangeToken(gatewayUrl, code, machineName);
+        if (token) {
+            store.set(REMOTE_GATEWAY_URL_KEY, gatewayUrl);
+            store.set(REMOTE_DAEMON_ID_KEY, token.daemonId);
+            store.set(REMOTE_DAEMON_TOKEN_KEY, token.daemonToken);
+            store.set(REMOTE_ENABLED_KEY, 'true');
+            log('');
+            log('This machine is linked. Remote access is now enabled.');
+            log('Restart the Hive runtime (or it will connect on next start) to bring');
+            log('the tunnel online. Pair a phone from Settings → Remote access.');
+            return 0;
+        }
+        if (now() >= expiresAt) {
+            log('');
+            log('The login code expired before it was approved. Run `hive remote login` again.');
+            return 1;
+        }
+        await sleep(pollIntervalMs);
+    }
+};
+const runStatus = (store, log) => {
+    const enabled = readConfig(store, REMOTE_ENABLED_KEY) === 'true';
+    const gatewayUrl = readConfig(store, REMOTE_GATEWAY_URL_KEY);
+    const daemonId = readConfig(store, REMOTE_DAEMON_ID_KEY);
+    const loggedIn = readConfig(store, REMOTE_DAEMON_TOKEN_KEY) !== null;
+    log(`Remote access: ${enabled ? 'enabled' : 'disabled'}`);
+    log(`Logged in: ${loggedIn ? 'yes' : 'no'}`);
+    // The token is secret and is intentionally never printed.
+    if (gatewayUrl)
+        log(`Gateway: ${gatewayUrl}`);
+    if (daemonId)
+        log(`Machine id: ${daemonId}`);
+    if (!loggedIn)
+        log('Run `hive remote login` to link this machine.');
+    return 0;
+};
+const runLogout = (store, log) => {
+    const wasLoggedIn = readConfig(store, REMOTE_DAEMON_TOKEN_KEY) !== null;
+    store.set(REMOTE_DAEMON_TOKEN_KEY, null);
+    store.set(REMOTE_DAEMON_ID_KEY, null);
+    store.set(REMOTE_ENABLED_KEY, 'false');
+    log(wasLoggedIn
+        ? 'Logged out. Remote access is disabled and the gateway token has been forgotten.'
+        : 'Not logged in. Remote access is disabled.');
+    return 0;
+};
+const runDevices = (store, log) => {
+    const devices = store.list(true); // include revoked so the operator sees the full roster
+    if (devices.length === 0) {
+        log('No paired devices. Pair a phone from Settings → Remote access.');
+        return 0;
+    }
+    for (const device of devices) {
+        const lastSeen = device.lastActive ? new Date(device.lastActive).toISOString() : 'never';
+        const status = device.revokedAt ? ' (revoked)' : '';
+        log(`${device.id}  ${device.name}  last active ${lastSeen}${status}`);
+    }
+    return 0;
+};
+const runRevoke = (deviceId, store, log, error) => {
+    if (!deviceId) {
+        error('Usage: hive remote revoke <deviceId>');
+        return 1;
+    }
+    const revoked = store.revoke(deviceId);
+    if (!revoked) {
+        error(`Unknown or already-revoked device: ${deviceId}`);
+        return 1;
+    }
+    // The daemon's provider reads live sessions fresh, so the device is refused on its
+    // next frame. To tear down an IN-PROGRESS session immediately, revoke from
+    // Settings → Remote access (which fires the live closed-loop disconnect).
+    log(`Revoked device ${deviceId}. It is refused on its next connection.`);
+    return 0;
+};
+export const runHiveRemoteCommand = async (argv, options = {}) => {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        const log = options.log ?? console.log;
+        log(HIVE_REMOTE_USAGE);
+        return argv.length === 0 ? 1 : 0;
+    }
+    const [subcommand, ...rest] = argv;
+    const client = options.client ?? defaultGatewayClient;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? defaultSleep;
+    const log = options.log ?? console.log;
+    const error = options.error ?? console.error;
+    // Open the config store lazily so --help / unknown subcommands don't touch
+    // the DB, and always close an owned handle.
+    // Annotated as a possibly-undefined holder so TS doesn't narrow it to `never`
+    // in the finally block (the assignment happens inside resolveStore's closure,
+    // which control-flow analysis can't see executing).
+    const owned = {};
+    const resolveStore = () => {
+        if (options.config)
+            return options.config;
+        const opened = openConfigStore();
+        owned.close = opened.close;
+        return opened.store;
+    };
+    const resolveDeviceStore = () => {
+        if (options.deviceStore)
+            return options.deviceStore;
+        const opened = openDeviceStore();
+        owned.close = opened.close;
+        return opened.store;
+    };
+    try {
+        switch (subcommand) {
+            case 'login':
+                return await runLogin(rest, resolveStore(), client, now, sleep, log);
+            case 'status':
+                return runStatus(resolveStore(), log);
+            case 'logout':
+                return runLogout(resolveStore(), log);
+            case 'devices':
+                return runDevices(resolveDeviceStore(), log);
+            case 'revoke':
+                return runRevoke(rest[0], resolveDeviceStore(), log, error);
+            default:
+                error(`Unknown remote subcommand: ${subcommand}`);
+                error(HIVE_REMOTE_USAGE);
+                return 1;
+        }
+    }
+    catch (err) {
+        error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    finally {
+        owned.close?.();
+    }
+};

package/dist/src/cli/hive-update.d.ts

@@ -0,0 +1,75 @@
+export declare const HIVE_UPDATE_USAGE: string;
+export interface RunUpdateResult {
+    exitCode: number;
+    spawnError?: Error;
+}
+export type RunUpdate = (command: string, args: readonly string[]) => Promise<RunUpdateResult>;
+export interface SpawnInvocationPlan {
+    command: string;
+    args: string[];
+    options: {
+        stdio: 'inherit';
+        windowsHide?: boolean;
+    };
+}
+/**
+ * Plan how `defaultRunUpdate` should hand the npm invocation to
+ * `child_process.spawn`. Two non-obvious cases collapse here.
+ *
+ * 1. Node 22+ refuses to spawn `.cmd` / `.bat` files directly after
+ *    CVE-2024-27980 unless `shell: true` is passed. We do not want
+ *    `shell: true` though — its arg-stringification path joins argv
+ *    without quoting, so an install prefix containing spaces (the
+ *    common Windows case `C:\Program Files\nodejs`) gets word-split
+ *    by cmd.exe and `--prefix` only sees the first token, so npm
+ *    silently installs hive to the wrong directory.
+ * 2. Wrapping with `cmd.exe /d /s /c <npm.cmd> <args>` solves both:
+ *    spawning `cmd.exe` (a native exe) avoids the .cmd refusal, and
+ *    Node's own argv-quoting builds an lpCommandLine where each
+ *    space-containing arg is wrapped in double quotes that cmd.exe
+ *    then re-parses correctly. `/d` skips AutoRun, `/s` keeps the
+ *    quote-handling consistent with `/c`.
+ *
+ * Detect by filename suffix instead of `process.platform` so unit
+ * tests can inject `platform: 'win32'` and exercise the wrap.
+ */
+export declare const planSpawnInvocation: (command: string, args: readonly string[], platform?: NodeJS.Platform) => SpawnInvocationPlan;
+/**
+ * Signals the upgrade child should receive when the parent runtime is
+ * interrupted. Beyond the POSIX-only SIGTERM/SIGINT, SIGHUP is what
+ * libuv synthesises from Windows CTRL_CLOSE_EVENT (window X close),
+ * and SIGBREAK comes from Windows Ctrl+Break. Without forwarding
+ * those two the npm child outlives the runtime on the most common
+ * Windows exit paths.
+ */
+export declare const FORWARDED_UPDATE_SIGNALS: readonly NodeJS.Signals[];
+/**
+ * Forward a parent-process signal to the spawned npm child. On POSIX
+ * we hand the signal straight to the child; on Windows there are no
+ * real signals, so `child.kill(SIGTERM)` resolves to TerminateProcess
+ * against cmd.exe (our wrapper) only — npm itself, plus any install
+ * scripts it spawned, become orphans. `taskkill /pid <pid> /t /f`
+ * walks the wrapper's process tree so the whole branch dies together.
+ * If taskkill is unavailable (restricted PATH, locked-down policy)
+ * we fall back to `child.kill` so the wrapper at least exits.
+ *
+ * Exported so the win32 path can be unit-tested by injecting a stub
+ * `killTree` runner — the real `taskkillProcessTree` shells out, and
+ * we don't want that running during the test suite.
+ */
+export declare const killUpdateChild: (child: {
+    pid?: number | undefined;
+    kill: (signal: NodeJS.Signals) => boolean;
+}, signal: NodeJS.Signals, platform?: NodeJS.Platform, killTree?: (pid: number, onFailure?: () => void) => boolean) => void;
+export declare const defaultRunUpdate: RunUpdate;
+export declare const resolveHiveUpdateInstallArgs: (moduleUrl?: string) => string[];
+interface RunHiveUpdateOptions {
+    /** Inject a fake spawn for tests. */
+    runUpdate?: RunUpdate;
+    /** Override platform detection for tests. */
+    platform?: NodeJS.Platform;
+    /** Override the current module URL for install-prefix detection in tests. */
+    moduleUrl?: string;
+}
+export declare const runHiveUpdateCommand: (argv: string[], options?: RunHiveUpdateOptions) => Promise<number>;
+export {};

package/dist/src/cli/hive-update.js

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { taskkillProcessTree } from '../server/agent-manager-support.js';
+import { getNpmCommand, INSTALL_COMMAND_ARGS, INSTALL_COMMAND_DISPLAY, PACKAGE_NAME, } from '../server/package-version.js';
+import { buildCmdCallCommand } from '../server/windows-command-line.js';
+export const HIVE_UPDATE_USAGE = [
+    'Usage:',
+    '  hive update',
+    '',
+    `Runs \`${INSTALL_COMMAND_DISPLAY}\` to upgrade Hive in place.`,
+    'When Hive was installed under a custom npm prefix, the update is applied',
+    'to that same prefix so the `hive` on your PATH actually changes.',
+    'Restart any running Hive process afterwards to pick up the new version.',
+    '',
+    'Note: only npm-installed Hive can be upgraded this way. If you installed',
+    'Hive via pnpm or yarn, upgrade through the same package manager instead;',
+    'otherwise the npm copy will shadow your existing install.',
+    '',
+    'Options:',
+    '  -h, --help      Print this help.',
+].join('\n');
+/**
+ * Plan how `defaultRunUpdate` should hand the npm invocation to
+ * `child_process.spawn`. Two non-obvious cases collapse here.
+ *
+ * 1. Node 22+ refuses to spawn `.cmd` / `.bat` files directly after
+ *    CVE-2024-27980 unless `shell: true` is passed. We do not want
+ *    `shell: true` though — its arg-stringification path joins argv
+ *    without quoting, so an install prefix containing spaces (the
+ *    common Windows case `C:\Program Files\nodejs`) gets word-split
+ *    by cmd.exe and `--prefix` only sees the first token, so npm
+ *    silently installs hive to the wrong directory.
+ * 2. Wrapping with `cmd.exe /d /s /c <npm.cmd> <args>` solves both:
+ *    spawning `cmd.exe` (a native exe) avoids the .cmd refusal, and
+ *    Node's own argv-quoting builds an lpCommandLine where each
+ *    space-containing arg is wrapped in double quotes that cmd.exe
+ *    then re-parses correctly. `/d` skips AutoRun, `/s` keeps the
+ *    quote-handling consistent with `/c`.
+ *
+ * Detect by filename suffix instead of `process.platform` so unit
+ * tests can inject `platform: 'win32'` and exercise the wrap.
+ */
+export const planSpawnInvocation = (command, args, platform = process.platform) => {
+    if (platform === 'win32' && /\.(cmd|bat)$/i.test(command)) {
+        return {
+            command: 'cmd.exe',
+            args: ['/d', '/s', '/c', buildCmdCallCommand(command, args)],
+            options: { stdio: 'inherit', windowsHide: false },
+        };
+    }
+    return { command, args: [...args], options: { stdio: 'inherit' } };
+};
+/**
+ * Signals the upgrade child should receive when the parent runtime is
+ * interrupted. Beyond the POSIX-only SIGTERM/SIGINT, SIGHUP is what
+ * libuv synthesises from Windows CTRL_CLOSE_EVENT (window X close),
+ * and SIGBREAK comes from Windows Ctrl+Break. Without forwarding
+ * those two the npm child outlives the runtime on the most common
+ * Windows exit paths.
+ */
+export const FORWARDED_UPDATE_SIGNALS = [
+    'SIGINT',
+    'SIGTERM',
+    'SIGHUP',
+    'SIGBREAK',
+];
+/**
+ * Forward a parent-process signal to the spawned npm child. On POSIX
+ * we hand the signal straight to the child; on Windows there are no
+ * real signals, so `child.kill(SIGTERM)` resolves to TerminateProcess
+ * against cmd.exe (our wrapper) only — npm itself, plus any install
+ * scripts it spawned, become orphans. `taskkill /pid <pid> /t /f`
+ * walks the wrapper's process tree so the whole branch dies together.
+ * If taskkill is unavailable (restricted PATH, locked-down policy)
+ * we fall back to `child.kill` so the wrapper at least exits.
+ *
+ * Exported so the win32 path can be unit-tested by injecting a stub
+ * `killTree` runner — the real `taskkillProcessTree` shells out, and
+ * we don't want that running during the test suite.
+ */
+export const killUpdateChild = (child, signal, platform = process.platform, killTree = (pid, onFailure) => taskkillProcessTree(pid, platform, undefined, onFailure)) => {
+    const fallback = () => {
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // child.kill on Windows throws if the signal name isn't
+            // implemented; we forward what we can and ignore the rest.
+        }
+    };
+    if (platform === 'win32' && typeof child.pid === 'number' && child.pid > 0) {
+        if (killTree(child.pid, fallback))
+            return;
+    }
+    fallback();
+};
+export const defaultRunUpdate = (command, args) => new Promise((resolve) => {
+    const plan = planSpawnInvocation(command, args);
+    const child = spawn(plan.command, plan.args, plan.options);
+    let resolved = false;
+    // Handlers are registered with `once` so they don't accumulate
+    // across invocations and explicitly removed at finalize().
+    const handlers = new Map();
+    for (const signal of FORWARDED_UPDATE_SIGNALS) {
+        const handler = () => {
+            killUpdateChild(child, signal);
+        };
+        handlers.set(signal, handler);
+        process.once(signal, handler);
+    }
+    const finalize = (result) => {
+        if (resolved)
+            return;
+        resolved = true;
+        for (const [signal, handler] of handlers) {
+            process.off(signal, handler);
+        }
+        resolve(result);
+    };
+    child.on('error', (error) => {
+        finalize({ exitCode: 1, spawnError: error });
+    });
+    child.on('close', (code) => {
+        finalize({ exitCode: typeof code === 'number' ? code : 1 });
+    });
+});
+const shellQuote = (value) => {
+    if (/^[A-Za-z0-9_/:=.,@+-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", "'\\''")}'`;
+};
+const findPackageRoot = (moduleUrl) => {
+    let dir = dirname(fileURLToPath(moduleUrl));
+    for (let depth = 0; depth < 12; depth += 1) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
+                if (parsed.name === PACKAGE_NAME)
+                    return dir;
+            }
+            catch {
+                // Keep walking. A malformed unrelated package.json should not break update.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+};
+const findPrefixFromPackageRoot = (packageRoot) => {
+    let dir = packageRoot;
+    for (let depth = 0; depth < 8; depth += 1) {
+        if (basename(dir) === 'node_modules') {
+            const parent = dirname(dir);
+            return basename(parent) === 'lib' ? dirname(parent) : parent;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+};
+export const resolveHiveUpdateInstallArgs = (moduleUrl = import.meta.url) => {
+    const packageRoot = findPackageRoot(moduleUrl);
+    const prefix = packageRoot ? findPrefixFromPackageRoot(packageRoot) : undefined;
+    if (!prefix)
+        return [...INSTALL_COMMAND_ARGS];
+    return [...INSTALL_COMMAND_ARGS, '--prefix', prefix];
+};
+const windowsQuote = (value) => {
+    if (/^[-A-Za-z0-9_/:=.,@+\\]+$/.test(value))
+        return value;
+    return `"${value.replace(/"/g, '""')}"`;
+};
+const formatInstallCommand = (args, platform = process.platform) => `npm ${args.map(platform === 'win32' ? windowsQuote : shellQuote).join(' ')}`;
+export const runHiveUpdateCommand = async (argv, options = {}) => {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(HIVE_UPDATE_USAGE);
+        return 0;
+    }
+    // Reject unknown flags rather than silently ignoring them — keeps behavior
+    // consistent with how `parsePort` validates `hive` itself.
+    const extra = argv.find((arg) => arg !== '--help' && arg !== '-h');
+    if (extra !== undefined) {
+        console.error(`Unknown argument: ${extra}`);
+        console.error(HIVE_UPDATE_USAGE);
+        return 1;
+    }
+    const run = options.runUpdate ?? defaultRunUpdate;
+    const command = getNpmCommand(options.platform);
+    const args = resolveHiveUpdateInstallArgs(options.moduleUrl);
+    const displayCommand = formatInstallCommand(args, options.platform);
+    console.log(`Running: ${displayCommand}`);
+    const result = await run(command, args);
+    if (result.spawnError) {
+        console.error(`Failed to spawn npm: ${result.spawnError.message}`);
+        console.error(`You can run the upgrade manually: ${displayCommand}`);
+        return 1;
+    }
+    if (result.exitCode === 0) {
+        console.log('Hive updated. Restart any running Hive process to pick up the new version.');
+        return 0;
+    }
+    console.error(`npm install exited with code ${result.exitCode}.`);
+    // Permission failures (EACCES on root-owned /usr/bin/npm) and other
+    // non-spawn errors leave the user with copy-paste recovery either way.
+    console.error(`You can run the upgrade manually: ${displayCommand}`);
+    return result.exitCode;
+};

package/dist/src/cli/hive.d.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { type RemoteTunnel, type RemoteTunnelDeps } from '../server/remote-tunnel.js';
+import { type RuntimeStore } from '../server/runtime-store.js';
+import { type VersionService } from '../server/version-service.js';
+interface RunHiveCommandResult {
+    port: number;
+    close: () => Promise<void>;
+    store: RuntimeStore;
+    /** The remote-access tunnel. Gated by remote_enabled (default OFF); off => no outbound socket. */
+    tunnel: RemoteTunnel;
+}
+type RunHiveCommandOptions = {
+    versionService?: VersionService;
+    /** Seam: override the tunnel factory in tests. Defaults to the real createRemoteTunnel. */
+    createRemoteTunnel?: (deps: RemoteTunnelDeps) => RemoteTunnel;
+};
+/**
+ * Signals that should drive a graceful shutdown. The interesting ones:
+ *
+ *   SIGINT  — Ctrl+C in the runtime terminal (all platforms).
+ *   SIGTERM — `kill <pid>` on POSIX. Never delivered on Windows.
+ *   SIGHUP  — POSIX: parent shell exits. On Windows libuv synthesises
+ *             SIGHUP from `CTRL_CLOSE_EVENT`, i.e. the user clicking
+ *             the X on the runtime's cmd / Terminal window. Without
+ *             this listener that close path skips the graceful path
+ *             entirely on Windows.
+ *   SIGBREAK — Windows: Ctrl+Break. Less common than Ctrl+C but kit
+ *             scripts and CI hosts still send it.
+ *
+ * Stale agent_runs from a non-graceful exit are reconciled at next
+ * startup via `agentRunStore.markUnfinishedRunsStale()`
+ * (runtime-store-helpers.ts), so a dropped signal does not leave the
+ * database in an inconsistent state — only the PTY children miss the
+ * forwarded SIGTERM. On Windows there's no graceful equivalent for
+ * those children anyway (pty.kill is TerminateProcess), so this
+ * registration is mostly about giving SQLite a chance to checkpoint.
+ */
+export declare const SHUTDOWN_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGHUP", "SIGBREAK"];
+export declare const HIVE_USAGE: string;
+export declare const handleHiveInfoCommand: (argv: string[]) => boolean;
+/**
+ * Resolve the directory where Hive persists its SQLite DB and supporting
+ * state. Platform-aware because `~/.config/hive` is a hidden dot-directory
+ * convention that Windows Explorer treats as second-class — Windows users
+ * can't navigate there from the address bar without typing the full path,
+ * and the standard roaming-profile location is `%APPDATA%\<app>` instead.
+ *
+ * Resolution order:
+ *   1. HIVE_DATA_DIR override (any platform, for tests / opinionated users).
+ *   2. Windows: %APPDATA%\hive — roaming user state, follows the user
+ *      across machines on a domain profile. APPDATA, not LOCALAPPDATA,
+ *      because Hive's DB is user data, not a machine-local cache.
+ *      Falls back to homedir()\AppData\Roaming\hive when APPDATA is
+ *      stripped from the env (some Windows Task Scheduler configs do this).
+ *   3. POSIX: $XDG_CONFIG_HOME/hive, falling back to ~/.config/hive.
+ *
+ * Migration: pre-fix Windows installs wrote to ~/.config/hive. When that
+ * legacy directory exists but the new %APPDATA%\hive does not, prefer the
+ * legacy path so an upgrade does not surface as an empty workspace list.
+ * This is a one-way ratchet — once the new location is populated, it wins.
+ *
+ * Exported so the resolution rules are unit-testable without touching env
+ * or the real filesystem.
+ */
+export declare const resolveDataDir: (platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, pathExists?: (path: string) => boolean) => string;
+/**
+ * Recovery hint formatter for the "port already in use" error. Platform-aware
+ * because the lsof / xargs / kill pipeline is POSIX-only; on Windows a user
+ * pasting that command into cmd or PowerShell gets nothing useful. The
+ * Windows path swaps in `netstat -ano | findstr` + `taskkill /F /PID` which
+ * is the documented Microsoft workflow for the same problem.
+ *
+ * Exported for unit testing.
+ */
+export declare const formatPortInUseMessage: (port: number, platform?: NodeJS.Platform) => string;
+export declare const formatPortAccessDeniedMessage: (port: number, platform?: NodeJS.Platform) => string;
+export declare const runHiveCommand: (argv: string[], options?: RunHiveCommandOptions) => Promise<RunHiveCommandResult>;
+export type { RunHiveCommandResult };