@tt-a1i/hive 1.6.0 → 2.0.1

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

@@ -173,7 +173,12 @@ export const resolveHiveUpdateInstallArgs = (moduleUrl = import.meta.url) => {
         return [...INSTALL_COMMAND_ARGS];
     return [...INSTALL_COMMAND_ARGS, '--prefix', prefix];
 };
-const formatInstallCommand = (args) => `npm ${args.map(shellQuote).join(' ')}`;
+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);
@@ -190,7 +195,7 @@ export const runHiveUpdateCommand = async (argv, options = {}) => {
     const run = options.runUpdate ?? defaultRunUpdate;
     const command = getNpmCommand(options.platform);
     const args = resolveHiveUpdateInstallArgs(options.moduleUrl);
-    const displayCommand = formatInstallCommand(args);
+    const displayCommand = formatInstallCommand(args, options.platform);
     console.log(`Running: ${displayCommand}`);
     const result = await run(command, args);
     if (result.spawnError) {

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

@@ -1,13 +1,18 @@
 #!/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:
@@ -68,5 +73,6 @@ export declare const resolveDataDir: (platform?: NodeJS.Platform, env?: NodeJS.P
  * 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 };

package/dist/src/cli/hive.js

@@ -8,8 +8,11 @@ import { createAgentManager } from '../server/agent-manager.js';
 import { createApp } from '../server/app.js';
 import { readPackageVersion } from '../server/package-version.js';
 import { sameFilesystemPath } from '../server/path-canonicalization.js';
+import { createRemoteConfigSource } from '../server/remote-config-keys.js';
+import { createRemoteTunnel, } from '../server/remote-tunnel.js';
 import { createRuntimeStore } from '../server/runtime-store.js';
 import { createVersionService } from '../server/version-service.js';
+import { runHiveRemoteCommand } from './hive-remote.js';
 import { runHiveUpdateCommand } from './hive-update.js';
 /**
  * Signals that should drive a graceful shutdown. The interesting ones:
@@ -45,6 +48,7 @@ export const HIVE_USAGE = [
     '',
     'Commands:',
     '  update          Upgrade Hive in place via `npm install -g`.',
+    '  remote          Manage remote access (login / status / logout / devices / revoke).',
 ].join('\n');
 export const handleHiveInfoCommand = (argv) => {
     if (argv.includes('--help') || argv.includes('-h')) {
@@ -159,10 +163,31 @@ export const formatPortInUseMessage = (port, platform = process.platform) => {
         `      hive --port ${port + 1}`,
     ].join('\n');
 };
+export const formatPortAccessDeniedMessage = (port, platform = process.platform) => {
+    if (platform !== 'win32') {
+        return `Hive could not start on port ${port}: permission denied.`;
+    }
+    return [
+        `Hive could not start on port ${port}: Windows denied access to that port.`,
+        '',
+        'This can happen when Hyper-V, Docker Desktop, WSL2, or Windows itself reserves a TCP port range.',
+        '',
+        'Check reserved ranges:',
+        '  netsh int ipv4 show excludedportrange protocol=tcp',
+        '',
+        'Options:',
+        '  - Start Hive on a high unreserved port:',
+        '      hive --port 49152',
+        '  - Or choose another port outside the listed excluded ranges.',
+    ].join('\n');
+};
 const formatListenError = (error, requestedPort) => {
     if (isListenError(error) && error.code === 'EADDRINUSE') {
         return new Error(formatPortInUseMessage(error.port ?? requestedPort));
     }
+    if (isListenError(error) && error.code === 'EACCES') {
+        return new Error(formatPortAccessDeniedMessage(error.port ?? requestedPort));
+    }
     return error;
 };
 export const runHiveCommand = async (argv, options = {}) => {
@@ -193,6 +218,32 @@ export const runHiveCommand = async (argv, options = {}) => {
     if (!address || typeof address === 'string') {
         throw new Error('Server did not bind to an inet port');
     }
+    // Remote tunnel — the outbound WebSocket to the gateway. GATED by app_state[remote_enabled]
+    // (default OFF). When off, refresh() settles 'disabled' synchronously: no socket is opened, no
+    // timer is armed, no listener is added, and the per-boot secret accept path stays inert (a request
+    // with no secret header hits the unchanged cookie path). This is invariant 4 — off == zero
+    // behavior change. Loopback requests authenticate via the per-boot internal secret (invariant 2),
+    // so the bridge never juggles browser cookies.
+    const tunnelFactory = options.createRemoteTunnel ?? createRemoteTunnel;
+    const tunnel = tunnelFactory({
+        loopbackPort: address.port,
+        config: createRemoteConfigSource({
+            get: (key) => app.store.settings.getAppState(key),
+        }),
+        deviceSessions: app.store.getRemoteDeviceSessions(),
+        loopbackSecret: app.store.getRemoteTunnelSecret(),
+        audit: app.store.getRemoteAuditStore(),
+        // The pairing engine — the tunnel carries pairing TEXT frames alongside the binary data plane and
+        // drives the daemon handshake half + the desktop-confirm sequence (gateway register + confirmed).
+        pairing: app.store.getRemotePairing(),
+        // Capture status so GET /api/remote/status.connected reflects the live tunnel (M4).
+        onStatus: (e) => app.store.setRemoteTunnelStatus(e.status),
+    });
+    // Bind the tunnel onto the store BEFORE refresh() so a revoke route fired during boot can close a
+    // device's live streams (the §6 closed loop). The provider-drop half is independent of binding.
+    app.store.bindRemoteTunnel(tunnel);
+    // refresh() reconciles desired (config) vs actual (socket). Disabled => settles immediately.
+    tunnel.refresh();
     let closePromise = null;
     const close = async () => {
         if (closePromise) {
@@ -202,6 +253,10 @@ export const runHiveCommand = async (argv, options = {}) => {
             for (const signal of SHUTDOWN_SIGNALS) {
                 process.off(signal, gracefulShutdown);
             }
+            // Close the outbound tunnel FIRST so it stops reconnecting and tears down its in-flight
+            // loopback streams before we rip the inbound WS layer out from under them. Graceful: no status
+            // churn, hard-terminate after a short grace.
+            await tunnel.close();
             // Tear down the WebSocket layer FIRST. `app.server.close()` waits
             // on every existing socket, including upgraded WebSocket clients
             // that never go idle on their own; `server.closeAllConnections()`
@@ -245,6 +300,7 @@ export const runHiveCommand = async (argv, options = {}) => {
         port: address.port,
         close,
         store: app.store,
+        tunnel,
     };
 };
 const isMainModule = process.argv[1]
@@ -260,6 +316,14 @@ if (isMainModule) {
             process.exit(1);
         });
     }
+    else if (argv[0] === 'remote') {
+        runHiveRemoteCommand(argv.slice(1))
+            .then((code) => process.exit(code))
+            .catch((error) => {
+            console.error(error instanceof Error ? error.message : error);
+            process.exit(1);
+        });
+    }
     else if (handleHiveInfoCommand(argv)) {
         process.exit(0);
     }

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

@@ -1,3 +1,4 @@
+import { type MemoryKind } from '../shared/team-memory.js';
 interface ParsedCancelArgs {
     dispatchId: string;
     reason: string;
@@ -10,6 +11,27 @@ export interface ParsedReportArgs {
 }
 export declare const parseReportArgs: (args: string[], command?: string) => ParsedReportArgs;
 export declare const parseCancelArgs: (args: string[]) => ParsedCancelArgs;
+export declare const parseRecallArgs: (args: string[]) => {
+    window?: number;
+    limit?: number;
+    query: string;
+};
+export interface ParsedMemoryAddArgs {
+    body: string;
+    kind: MemoryKind;
+    tags: string[];
+}
+export declare const parseMemoryAddArgs: (args: string[]) => ParsedMemoryAddArgs;
+export declare const parseMemoryShowArgs: (args: string[]) => {
+    memoryId: string;
+};
+export declare const parseMemorySearchArgs: (args: string[]) => {
+    limit?: number;
+    query: string;
+};
+export declare const parseMemoryForgetArgs: (args: string[]) => {
+    memoryId: string;
+};
 export declare const decodeStdinBuffer: (buffer: Buffer) => string;
 export declare const readStdinToString: (command?: string) => Promise<string>;
 export declare const runTeamCommand: (argv: string[]) => Promise<void>;

package/dist/src/cli/team.js

@@ -1,5 +1,8 @@
 import { fileURLToPath } from 'node:url';
+import { BUILTIN_COMMAND_PRESET_CLI_LIST } from '../server/command-preset-defaults.js';
 import { sameFilesystemPath } from '../server/path-canonicalization.js';
+import { isMemoryKind, MEMORY_BODY_MAX_CHARS, MEMORY_KINDS, MEMORY_QUERY_MAX_CHARS, MEMORY_SEARCH_MAX_LIMIT, MEMORY_TAG_MAX_CHARS, MEMORY_TAG_MAX_COUNT, } from '../shared/team-memory.js';
+import { RECALL_QUERY_MAX_CHARS } from '../shared/team-recall.js';
 const REQUIRED_ENV_KEYS = [
     'HIVE_PORT',
     'HIVE_PROJECT_ID',
@@ -10,8 +13,13 @@ const TEAM_USAGE = [
     'Usage:',
     '  team list',
     '  team next   (tasks in .hive/tasks.md that are unblocked now — those whose [needs: #n] deps are all done)',
+    '  team recall "<query>" [--limit <n>] [--window <n>]',
+    '  team memory add "<body>" [--kind fact|preference|decision|pitfall|procedure_ref] [--tag <tag>]',
+    '  team memory show <memory-id>',
+    '  team memory search "<query>" [--limit <n>]',
+    '  team memory forget <memory-id>',
     '  team send <worker-name> "<task>"',
-    '  team spawn <role> [--name <name>] [--cli <claude|codex|opencode|gemini>] [--ephemeral]',
+    `  team spawn <role> [--name <name>] [--cli <${BUILTIN_COMMAND_PRESET_CLI_LIST}>] [--ephemeral]`,
     '  team dismiss <worker-name>',
     "  team workflow run --stdin [--args '<JSON>']   (script from stdin — for multi-line scripts)",
     '  team workflow run --inline "<source>" [--args \'<JSON>\']',
@@ -30,7 +38,7 @@ const TEAM_USAGE = [
     '                ... long report ...',
     '                EOF',
     '  Windows cmd:  type body.txt | team report --stdin --dispatch <id>',
-    '  PowerShell:   Get-Content body.txt | team report --stdin --dispatch <id>',
+    '  PowerShell:   Get-Content -Raw -Encoding utf8 body.txt | team report --stdin --dispatch <id>',
     '  Portable:     team report --stdin --dispatch <id> < body.txt',
     '',
     'For role rules, workflow, and recovery instructions, see .hive/PROTOCOL.md',
@@ -52,7 +60,6 @@ const readFlag = (args, flag) => {
     const value = args[index + 1];
     return value && !value.startsWith('--') ? value : undefined;
 };
-const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const describeFetchError = (baseUrl, error) => {
     const cause = error instanceof Error && error.cause instanceof Error ? ` (${error.cause.message})` : '';
     const message = error instanceof Error ? error.message : String(error);
@@ -102,6 +109,11 @@ const postJson = async (baseUrl, path, body) => {
 const REPORT_USAGE = 'Usage: team report (<result> | --stdin) [--dispatch <dispatch-id>] [--artifact <path>]';
 const STATUS_USAGE = 'Usage: team status (<current status> | --stdin) [--artifact <path>]';
 const CANCEL_USAGE = 'Usage: team cancel --dispatch <dispatch-id> <reason>';
+const RECALL_USAGE = 'Usage: team recall "<query>" [--limit <n>] [--window <n>]';
+const MEMORY_ADD_USAGE = 'Usage: team memory add "<body>" [--kind fact|preference|decision|pitfall|procedure_ref] [--tag <tag>]';
+const MEMORY_SHOW_USAGE = 'Usage: team memory show <memory-id>';
+const MEMORY_SEARCH_USAGE = 'Usage: team memory search "<query>" [--limit <n>]';
+const MEMORY_FORGET_USAGE = 'Usage: team memory forget <memory-id>';
 const usageFor = (command) => (command === 'status' ? STATUS_USAGE : REPORT_USAGE);
 const withUsage = (message, command) => `${message}\n\n${usageFor(command)}`;
 export const parseReportArgs = (args, command = 'report') => {
@@ -194,6 +206,165 @@ export const parseCancelArgs = (args) => {
     }
     return { dispatchId, reason };
 };
+const parseNonNegativeIntFlag = (value, flag) => {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`${flag} must be a non-negative integer\n\n${RECALL_USAGE}`);
+    }
+    return parsed;
+};
+export const parseRecallArgs = (args) => {
+    const positionals = [];
+    let limit;
+    let window;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--limit' || arg === '--window') {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new Error(`${arg} requires a value\n\n${RECALL_USAGE}`);
+            }
+            if (arg === '--limit')
+                limit = parseNonNegativeIntFlag(next, '--limit');
+            else
+                window = parseNonNegativeIntFlag(next, '--window');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            throw new Error(`Unknown argument: ${arg}\n\n${RECALL_USAGE}`);
+        }
+        positionals.push(arg);
+    }
+    if (positionals.length === 0) {
+        throw new Error(`Missing <query>\n\n${RECALL_USAGE}`);
+    }
+    const query = positionals.join(' ').trim();
+    if ([...query].length > RECALL_QUERY_MAX_CHARS) {
+        throw new Error(`query must be ${RECALL_QUERY_MAX_CHARS} characters or fewer\n\n${RECALL_USAGE}`);
+    }
+    return {
+        query,
+        ...(limit !== undefined ? { limit } : {}),
+        ...(window !== undefined ? { window } : {}),
+    };
+};
+export const parseMemoryAddArgs = (args) => {
+    const positionals = [];
+    const tags = [];
+    let kind = 'fact';
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--kind') {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new Error(`--kind requires a value\n\n${MEMORY_ADD_USAGE}`);
+            }
+            if (!isMemoryKind(next)) {
+                throw new Error(`--kind must be one of: ${MEMORY_KINDS.join(', ')}\n\n${MEMORY_ADD_USAGE}`);
+            }
+            kind = next;
+            index += 1;
+            continue;
+        }
+        if (arg === '--tag') {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new Error(`--tag requires a value\n\n${MEMORY_ADD_USAGE}`);
+            }
+            const tag = next.trim();
+            if (!tag) {
+                throw new Error(`--tag requires a non-empty value\n\n${MEMORY_ADD_USAGE}`);
+            }
+            if ([...tag].length > MEMORY_TAG_MAX_CHARS) {
+                throw new Error(`--tag must be ${MEMORY_TAG_MAX_CHARS} characters or fewer\n\n${MEMORY_ADD_USAGE}`);
+            }
+            if (!tags.includes(tag))
+                tags.push(tag);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            throw new Error(`Unknown argument: ${arg}\n\n${MEMORY_ADD_USAGE}`);
+        }
+        positionals.push(arg);
+    }
+    if (tags.length > MEMORY_TAG_MAX_COUNT) {
+        throw new Error(`--tag may be repeated ${MEMORY_TAG_MAX_COUNT} times or fewer\n\n${MEMORY_ADD_USAGE}`);
+    }
+    if (positionals.length === 0) {
+        throw new Error(`Missing <body>\n\n${MEMORY_ADD_USAGE}`);
+    }
+    const body = positionals.join(' ').trim();
+    if (!body) {
+        throw new Error(`Missing <body>\n\n${MEMORY_ADD_USAGE}`);
+    }
+    if ([...body].length > MEMORY_BODY_MAX_CHARS) {
+        throw new Error(`body must be ${MEMORY_BODY_MAX_CHARS} characters or fewer\n\n${MEMORY_ADD_USAGE}`);
+    }
+    return { body, kind, tags };
+};
+export const parseMemoryShowArgs = (args) => {
+    if (args.length !== 1 || !args[0] || args[0].startsWith('--')) {
+        throw new Error(`Missing <memory-id>\n\n${MEMORY_SHOW_USAGE}`);
+    }
+    return { memoryId: args[0] };
+};
+export const parseMemorySearchArgs = (args) => {
+    const positionals = [];
+    let limit;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--limit') {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new Error(`--limit requires a value\n\n${MEMORY_SEARCH_USAGE}`);
+            }
+            const parsed = Number(next);
+            if (!Number.isInteger(parsed) || parsed < 0) {
+                throw new Error(`--limit must be a non-negative integer\n\n${MEMORY_SEARCH_USAGE}`);
+            }
+            limit = Math.min(parsed, MEMORY_SEARCH_MAX_LIMIT);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            throw new Error(`Unknown argument: ${arg}\n\n${MEMORY_SEARCH_USAGE}`);
+        }
+        positionals.push(arg);
+    }
+    if (positionals.length === 0) {
+        throw new Error(`Missing <query>\n\n${MEMORY_SEARCH_USAGE}`);
+    }
+    const query = positionals.join(' ').trim();
+    if (!query) {
+        throw new Error(`Missing <query>\n\n${MEMORY_SEARCH_USAGE}`);
+    }
+    if ([...query].length > MEMORY_QUERY_MAX_CHARS) {
+        throw new Error(`query must be ${MEMORY_QUERY_MAX_CHARS} characters or fewer\n\n${MEMORY_SEARCH_USAGE}`);
+    }
+    return {
+        query,
+        ...(limit !== undefined ? { limit } : {}),
+    };
+};
+export const parseMemoryForgetArgs = (args) => {
+    if (args.length === 0 || !args[0] || args[0].startsWith('--')) {
+        throw new Error(`Missing <memory-id>\n\n${MEMORY_FORGET_USAGE}`);
+    }
+    if (args.length !== 1) {
+        throw new Error(`Expected exactly one <memory-id>\n\n${MEMORY_FORGET_USAGE}`);
+    }
+    return { memoryId: args[0] };
+};
 export const decodeStdinBuffer = (buffer) => {
     if (buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
         return buffer.subarray(3).toString('utf8');
@@ -260,10 +431,85 @@ export const runTeamCommand = async (argv) => {
         console.log(JSON.stringify(await response.json()));
         return;
     }
+    if (command === 'recall') {
+        const recall = parseRecallArgs(args);
+        const env = getHiveEnv();
+        const response = await postJson(getBaseUrl(env), '/api/team/recall', {
+            project_id: env.HIVE_PROJECT_ID,
+            from_agent_id: env.HIVE_AGENT_ID,
+            token: env.HIVE_AGENT_TOKEN,
+            query: recall.query,
+            ...(recall.limit !== undefined ? { limit: recall.limit } : {}),
+            ...(recall.window !== undefined ? { window: recall.window } : {}),
+        });
+        console.log(JSON.stringify(await response.json()));
+        return;
+    }
+    if (command === 'memory') {
+        const [subcommand, ...memoryArgs] = args;
+        if (subcommand === 'add') {
+            const memory = parseMemoryAddArgs(memoryArgs);
+            const env = getHiveEnv();
+            const response = await postJson(getBaseUrl(env), '/api/team/memory/add', {
+                project_id: env.HIVE_PROJECT_ID,
+                from_agent_id: env.HIVE_AGENT_ID,
+                token: env.HIVE_AGENT_TOKEN,
+                body: memory.body,
+                kind: memory.kind,
+                tags: memory.tags,
+            });
+            console.log(JSON.stringify(await response.json()));
+            return;
+        }
+        if (subcommand === 'show') {
+            const memory = parseMemoryShowArgs(memoryArgs);
+            const env = getHiveEnv();
+            const response = await postJson(getBaseUrl(env), '/api/team/memory/show', {
+                project_id: env.HIVE_PROJECT_ID,
+                from_agent_id: env.HIVE_AGENT_ID,
+                token: env.HIVE_AGENT_TOKEN,
+                memory_id: memory.memoryId,
+            });
+            console.log(JSON.stringify(await response.json()));
+            return;
+        }
+        if (subcommand === 'search') {
+            const memory = parseMemorySearchArgs(memoryArgs);
+            const env = getHiveEnv();
+            const response = await postJson(getBaseUrl(env), '/api/team/memory/search', {
+                project_id: env.HIVE_PROJECT_ID,
+                from_agent_id: env.HIVE_AGENT_ID,
+                token: env.HIVE_AGENT_TOKEN,
+                query: memory.query,
+                ...(memory.limit !== undefined ? { limit: memory.limit } : {}),
+            });
+            console.log(JSON.stringify(await response.json()));
+            return;
+        }
+        if (subcommand === 'forget') {
+            const memory = parseMemoryForgetArgs(memoryArgs);
+            const env = getHiveEnv();
+            const response = await postJson(getBaseUrl(env), '/api/team/memory/forget', {
+                project_id: env.HIVE_PROJECT_ID,
+                from_agent_id: env.HIVE_AGENT_ID,
+                token: env.HIVE_AGENT_TOKEN,
+                memory_id: memory.memoryId,
+            });
+            console.log(JSON.stringify(await response.json()));
+            return;
+        }
+        throw new Error([
+            'Usage:',
+            `  ${MEMORY_ADD_USAGE}`,
+            `  ${MEMORY_SHOW_USAGE}`,
+            `  ${MEMORY_SEARCH_USAGE}`,
+            `  ${MEMORY_FORGET_USAGE}`,
+        ].join('\n'));
+    }
     if (command === 'send') {
         const [workerName, ...taskParts] = args;
         const task = taskParts.join(' ').trim();
-        if (!workerName || !task || uuidPattern.test(workerName)) {
+        if (!workerName || !task) {
             throw new Error('Usage: team send <worker-name> <task>');
         }
         const env = getHiveEnv();
@@ -291,7 +537,7 @@ export const runTeamCommand = async (argv) => {
     if (command === 'spawn') {
         const role = args[0];
         if (!role || role.startsWith('--')) {
-            throw new Error('Usage: team spawn <role> [--name <name>] [--cli <claude|codex|opencode|gemini>] [--ephemeral]\n' +
+            throw new Error(`Usage: team spawn <role> [--name <name>] [--cli <${BUILTIN_COMMAND_PRESET_CLI_LIST}>] [--ephemeral]\n` +
                 '  Default: persistent member (lives until you `team dismiss` it).\n' +
                 '  --ephemeral: auto-dismiss after the next dispatch report (one-shot worker).');
         }
@@ -483,6 +729,8 @@ export const runTeamCommand = async (argv) => {
         if (payload.forwarded === false && payload.forward_error) {
             console.error(`Hive recorded the status update, but could not deliver it to Orchestrator in real time: ${payload.forward_error}`);
         }
+        if (payload.pending_warning)
+            console.error(payload.pending_warning);
         return;
     }
     if (command === 'report') {
@@ -502,6 +750,8 @@ export const runTeamCommand = async (argv) => {
         if (payload.forwarded === false && payload.forward_error) {
             console.error(`Hive recorded the report, but could not deliver it to Orchestrator in real time: ${payload.forward_error}`);
         }
+        if (payload.pending_warning)
+            console.error(payload.pending_warning);
         return;
     }
     throw new Error('Unsupported team command');

package/dist/src/server/agent-command-resolver.js

@@ -18,7 +18,11 @@ const createCommandNotFoundError = (command) => Object.assign(new Error(`${comma
 const getEnvValue = (env, key, platform = process.platform) => {
     if (platform !== 'win32')
         return env[key];
-    const matchedKey = Object.keys(env).find((item) => item.toLowerCase() === key.toLowerCase());
+    if (Object.hasOwn(env, key))
+        return env[key];
+    const matchedKey = Object.keys(env)
+        .filter((item) => item.toLowerCase() === key.toLowerCase())
+        .at(-1);
     return matchedKey ? env[matchedKey] : undefined;
 };
 const getWindowsExecutableNames = (command, env, platform = process.platform) => {
@@ -28,7 +32,7 @@ const getWindowsExecutableNames = (command, env, platform = process.platform) =>
         .split(';')
         .map((item) => item.trim())
         .filter(Boolean);
-    return [...extensions.map((extension) => `${command}${extension}`), command];
+    return extensions.map((extension) => `${command}${extension}`);
 };
 const getExecutableNames = (command, env, platform = process.platform) => platform === 'win32' ? getWindowsExecutableNames(command, env, platform) : [command];
 export const resolveCommandPath = (command, cwd, env, platform = process.platform) => {
@@ -59,7 +63,10 @@ const buildWindowsBatchCommandLine = (command, args) => {
     // `call` is cmd's built-in batch invocation; it handles quoted .cmd / .bat
     // paths reliably (this is the same pattern Node.js's child_process uses
     // internally on Windows since the CVE-2024-27980 fix).
-    return `/d /s /c ${buildCmdCallCommand(command, args)}`;
+    // Most Windows agent CLIs are npm .cmd shims. Set the console code page to
+    // UTF-8 before launching them so Hive's injected CJK startup guidance is not
+    // interpreted through the machine's OEM code page.
+    return `/d /s /c chcp 65001 >nul && ${buildCmdCallCommand(command, args)}`;
 };
 /**
  * Recognize the exact shape that `createStartupCommandLaunch` produces on

package/dist/src/server/agent-exit-classification.d.ts

@@ -0,0 +1,6 @@
+import type { PersistedAgentRun } from './agent-run-store.js';
+export declare const WINDOWS_CONTROL_C_EXIT_CODE = 3221225786;
+export declare const isUserInterruptExitCode: (exitCode: number | null) => boolean;
+export declare const isCleanRunExitCode: (exitCode: number | null) => boolean;
+export declare const classifyCompletedRunStatus: (exitCode: number | null) => PersistedAgentRun["status"];
+export declare const shouldClearResumedSessionOnExit: (exitCode: number | null) => boolean;

package/dist/src/server/agent-exit-classification.js

@@ -0,0 +1,6 @@
+export const WINDOWS_CONTROL_C_EXIT_CODE = 0xc000013a;
+const USER_INTERRUPT_EXIT_CODES = new Set([130, 143, WINDOWS_CONTROL_C_EXIT_CODE]);
+export const isUserInterruptExitCode = (exitCode) => exitCode !== null && USER_INTERRUPT_EXIT_CODES.has(exitCode);
+export const isCleanRunExitCode = (exitCode) => exitCode === 0 || isUserInterruptExitCode(exitCode);
+export const classifyCompletedRunStatus = (exitCode) => isCleanRunExitCode(exitCode) ? 'exited' : 'error';
+export const shouldClearResumedSessionOnExit = (exitCode) => !isCleanRunExitCode(exitCode);

package/dist/src/server/agent-manager-support.d.ts

@@ -3,6 +3,7 @@ import type { AgentRunRecord, AgentRunSnapshot } from './agent-manager.js';
 import type { PtyOutputBus } from './pty-output-bus.js';
 export declare const MAX_RUN_OUTPUT_LENGTH = 1000000;
 type ExecRunner = (cmd: string, args: readonly string[], done: (success: boolean) => void) => void;
+export declare const withSilencedConptyConsoleListAgent: <T>(platform: NodeJS.Platform, action: () => T) => T;
 /**
  * Windows analogue of POSIX `process.kill(-pgid, SIGKILL)`. node-pty on
  * Windows hands `pty.kill()` to TerminateProcess against the PTY's main
@@ -31,5 +32,5 @@ type ExecRunner = (cmd: string, args: readonly string[], done: (success: boolean
 export declare const taskkillProcessTree: (pid: number, platform?: NodeJS.Platform, runner?: ExecRunner, onFailure?: () => void) => boolean;
 export declare const toAgentRunSnapshot: (run: AgentRunRecord) => AgentRunSnapshot;
 export declare const finishAgentRun: (run: AgentRunRecord, exitCode: number | null, ptyOutputBus: PtyOutputBus) => void;
-export declare const attachAgentPty: (run: AgentRunRecord, pty: IPty, ptyOutputBus: PtyOutputBus) => void;
+export declare const attachAgentPty: (run: AgentRunRecord, pty: IPty, ptyOutputBus: PtyOutputBus, platform?: NodeJS.Platform, execRunner?: ExecRunner) => void;
 export {};