shennian 0.2.30 → 0.2.33

package/dist/src/agent-env.d.ts

@@ -0,0 +1,7 @@
+export declare function readLatestUserEnv(): NodeJS.ProcessEnv;
+export declare function mergeAgentProcessEnv(input: {
+    daemonEnv: NodeJS.ProcessEnv;
+    userEnv: NodeJS.ProcessEnv;
+    extra?: NodeJS.ProcessEnv;
+}): NodeJS.ProcessEnv;
+export declare function buildAgentProcessEnv(extra?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/src/agent-env.js

@@ -0,0 +1,82 @@
+// @arch docs/architecture/cli/agent-adapters.md
+// @test src/__tests__/agent-env.test.ts
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+const SHELL_ENV_START = '__SHENNIAN_AGENT_ENV_START__';
+const SHELL_ENV_END = '__SHENNIAN_AGENT_ENV_END__';
+function quotePosix(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function parseEnvJson(stdout) {
+    const start = stdout.indexOf(SHELL_ENV_START);
+    const end = stdout.indexOf(SHELL_ENV_END, start + SHELL_ENV_START.length);
+    if (start === -1 || end === -1)
+        return null;
+    const json = stdout.slice(start + SHELL_ENV_START.length, end);
+    try {
+        const parsed = JSON.parse(json);
+        const env = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === 'string')
+                env[key] = value;
+        }
+        return env;
+    }
+    catch {
+        return null;
+    }
+}
+function readPosixShellEnv() {
+    const shell = process.env.SHELL?.trim() || '/bin/sh';
+    const script = [
+        `printf ${quotePosix(SHELL_ENV_START)}`,
+        `${quotePosix(process.execPath)} -e ${quotePosix('process.stdout.write(JSON.stringify(process.env))')}`,
+        `printf ${quotePosix(SHELL_ENV_END)}`,
+    ].join('; ');
+    for (const args of [['-ilc', script], ['-lc', script]]) {
+        const result = spawnSync(shell, args, {
+            env: process.env,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 1500,
+        });
+        const parsed = typeof result.stdout === 'string' ? parseEnvJson(result.stdout) : null;
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+function readWindowsGlobalEnv() {
+    const script = `
+$envs = @{}
+[Environment]::GetEnvironmentVariables('Machine').GetEnumerator() | ForEach-Object { $envs[$_.Key] = [string]$_.Value }
+[Environment]::GetEnvironmentVariables('User').GetEnumerator() | ForEach-Object { $envs[$_.Key] = [string]$_.Value }
+Write-Output '${SHELL_ENV_START}'
+$envs | ConvertTo-Json -Compress
+Write-Output '${SHELL_ENV_END}'
+`;
+    const result = spawnSync('powershell.exe', ['-NoProfile', '-Command', script], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 1500,
+    });
+    return typeof result.stdout === 'string' ? parseEnvJson(result.stdout) : null;
+}
+export function readLatestUserEnv() {
+    const env = os.platform() === 'win32' ? readWindowsGlobalEnv() : readPosixShellEnv();
+    return env ?? {};
+}
+export function mergeAgentProcessEnv(input) {
+    return {
+        ...input.daemonEnv,
+        ...input.userEnv,
+        ...input.extra,
+    };
+}
+export function buildAgentProcessEnv(extra = {}) {
+    return mergeAgentProcessEnv({
+        daemonEnv: process.env,
+        userEnv: readLatestUserEnv(),
+        extra,
+    });
+}

package/dist/src/agents/claude.js

@@ -2,6 +2,7 @@ import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
 import { AgentAdapter, registerAgent } from './adapter.js';
 import { resolveBuiltinCommand, spawnResolvedCommand } from './command-spec.js';
+import { buildAgentProcessEnv } from '../agent-env.js';
 export function normalizeClaudeModelId(modelId) {
     const trimmed = modelId?.trim();
     return trimmed || 'default';
@@ -60,7 +61,7 @@ export class ClaudeAdapter extends AgentAdapter {
         const proc = spawnResolvedCommand(spec, args, {
             cwd: this.workDir ?? undefined,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env },
+            env: buildAgentProcessEnv(),
         });
         this.process = proc;
         const rl = createInterface({ input: proc.stdout });

package/dist/src/agents/codex.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
 import { AgentAdapter, registerAgent } from './adapter.js';
 import { resolveBuiltinCommand, spawnResolvedCommand } from './command-spec.js';
+import { buildAgentProcessEnv } from '../agent-env.js';
 export class CodexAdapter extends AgentAdapter {
     type = 'codex';
     process = null;
@@ -78,7 +79,7 @@ export class CodexAdapter extends AgentAdapter {
         const proc = spawnResolvedCommand(spec, args, {
             cwd: this.workDir ?? undefined,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env },
+            env: buildAgentProcessEnv(),
         });
         this.process = proc;
         const rl = createInterface({ input: proc.stdout });
@@ -125,7 +126,7 @@ export class CodexAdapter extends AgentAdapter {
         const proc = spawnResolvedCommand(spec, ['app-server', '--listen', 'stdio://'], {
             cwd: this.workDir ?? undefined,
             stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env, NO_COLOR: '1' },
+            env: buildAgentProcessEnv({ NO_COLOR: '1' }),
         });
         this.process = proc;
         this.stderrBuf = '';

package/dist/src/agents/cursor.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
 import { AgentAdapter, registerAgent } from './adapter.js';
 import { resolveBuiltinCommand, spawnResolvedCommand } from './command-spec.js';
+import { buildAgentProcessEnv } from '../agent-env.js';
 export class CursorAdapter extends AgentAdapter {
     type = 'cursor';
     process = null;
@@ -60,7 +61,7 @@ export class CursorAdapter extends AgentAdapter {
         const proc = spawnResolvedCommand(spec, args, {
             cwd: this.workDir ?? undefined,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env },
+            env: buildAgentProcessEnv(),
         });
         this.process = proc;
         const rl = createInterface({ input: proc.stdout });

package/dist/src/agents/custom.js

@@ -3,6 +3,7 @@ import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
 import { AgentAdapter, registerAgent } from './adapter.js';
 import { spawnCommandString } from './command-spec.js';
+import { buildAgentProcessEnv } from '../agent-env.js';
 export class CustomAgentAdapter extends AgentAdapter {
     type;
     command;
@@ -75,7 +76,7 @@ export class CustomAgentAdapter extends AgentAdapter {
         const proc = spawnCommandString(this.command, args, {
             cwd: this.workDir ?? undefined,
             stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env },
+            env: buildAgentProcessEnv(),
         });
         this.spawnProcess = proc;
         this.attachOutputHandlers(proc, () => {
@@ -101,7 +102,7 @@ export class CustomAgentAdapter extends AgentAdapter {
         const proc = spawnCommandString(this.command, ['/start', '--workdir', this.workDir ?? process.cwd()], {
             cwd: this.workDir ?? undefined,
             stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env },
+            env: buildAgentProcessEnv(),
         });
         this.stdioProcess = proc;
         this.attachOutputHandlers(proc, () => {

package/dist/src/agents/gemini.js

@@ -2,6 +2,7 @@ import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
 import { AgentAdapter, registerAgent } from './adapter.js';
 import { resolveBuiltinCommand, spawnResolvedCommand } from './command-spec.js';
+import { buildAgentProcessEnv } from '../agent-env.js';
 function num(v) {
     return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
 }
@@ -72,7 +73,7 @@ export class GeminiAdapter extends AgentAdapter {
         const proc = spawnResolvedCommand(spec, args, {
             cwd: this.workDir ?? undefined,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env },
+            env: buildAgentProcessEnv(),
         });
         this.process = proc;
         const rl = createInterface({ input: proc.stdout });

package/dist/src/agents/model-registry/discovery.js

@@ -5,6 +5,7 @@ import { resolveBuiltinCommand, spawnResolvedCommand } from '../command-spec.js'
 import { fallbackClaudeAliasModels, fallbackGeminiModels, parseCodexAppServerModels, parseCursorModels, parseOpenCodeModels, } from './parsers.js';
 import { runResolvedCommand } from './runner.js';
 import { DISCOVERY_WORKDIR } from './types.js';
+import { buildAgentProcessEnv } from '../../agent-env.js';
 function sendAppServerRpc(proc, pending, id, method, params, timeoutMs) {
     if (!proc.stdin)
         return Promise.reject(new Error('codex app-server stdin unavailable'));
@@ -27,7 +28,7 @@ async function discoverCodexModelsViaAppServer(spec) {
     const proc = spawnResolvedCommand(spec, ['app-server', '--listen', 'stdio://'], {
         cwd: DISCOVERY_WORKDIR,
         stdio: ['pipe', 'pipe', 'pipe'],
-        env: { ...process.env, NO_COLOR: '1' },
+        env: buildAgentProcessEnv({ NO_COLOR: '1' }),
     });
     const pending = new Map();
     let seq = 1;

package/dist/src/agents/model-registry/runner.js

@@ -2,12 +2,13 @@
 // @test src/__tests__/model-switching.test.ts
 import { spawnResolvedCommand } from '../command-spec.js';
 import { DISCOVERY_WORKDIR } from './types.js';
+import { buildAgentProcessEnv } from '../../agent-env.js';
 export function runResolvedCommand(spec, args, timeoutMs = 15_000) {
     return new Promise((resolve, reject) => {
         const proc = spawnResolvedCommand(spec, args, {
             cwd: DISCOVERY_WORKDIR,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, NO_COLOR: '1' },
+            env: buildAgentProcessEnv({ NO_COLOR: '1' }),
         });
         let stdout = '';
         let stderr = '';

package/dist/src/agents/openclaw.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { AgentAdapter } from './adapter.js';
 import { resolveBuiltinCommand, spawnResolvedCommand } from './command-spec.js';
+import { buildAgentProcessEnv } from '../agent-env.js';
 /** Best-effort parse of `openclaw agent --json` stdout; shape may vary by version. */
 function extractResponseText(parsed) {
     if (parsed == null)
@@ -125,7 +126,7 @@ export class OpenClawAdapter extends AgentAdapter {
         const proc = spawnResolvedCommand(spec, args, {
             cwd: this.workDir ?? undefined,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env },
+            env: buildAgentProcessEnv(),
         });
         this.process = proc;
         let stdoutBuf = '';
@@ -204,7 +205,7 @@ export class OpenClawAdapter extends AgentAdapter {
             const proc = spawnResolvedCommand(spec, args, {
                 cwd: this.workDir ?? undefined,
                 stdio: ['ignore', 'pipe', 'pipe'],
-                env: { ...process.env },
+                env: buildAgentProcessEnv(),
             });
             let stdoutBuf = '';
             let stderrBuf = '';

package/dist/src/agents/opencode.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
 import { AgentAdapter, registerAgent } from './adapter.js';
 import { resolveBuiltinCommand, spawnResolvedCommand } from './command-spec.js';
+import { buildAgentProcessEnv } from '../agent-env.js';
 function usageFromTokens(tokens) {
     if (!tokens)
         return undefined;
@@ -103,7 +104,7 @@ export class OpenCodeAdapter extends AgentAdapter {
         const proc = spawnResolvedCommand(spec, args, {
             cwd: this.workDir ?? undefined,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, NO_COLOR: '1' },
+            env: buildAgentProcessEnv({ NO_COLOR: '1' }),
         });
         this.process = proc;
         const rl = createInterface({ input: proc.stdout });

package/dist/src/commands/daemon.d.ts

@@ -1,4 +1,5 @@
 import type { Command } from 'commander';
+export declare function isSafeSnapshotEnvKey(key: string): boolean;
 type Platform = 'darwin' | 'linux' | 'win32';
 type ServiceLaunchMode = 'direct' | 'global-shim' | 'npx';
 type DaemonLauncher = 'desktop-managed' | 'global-cli' | 'unknown';
@@ -13,6 +14,7 @@ export type DaemonStatus = {
     pidFile: string;
     logFile: string;
     machineId?: string;
+    paired?: boolean;
     serverUrl?: string;
 };
 export type ServiceLaunchSpec = {

package/dist/src/commands/daemon.js

@@ -7,6 +7,7 @@ import os from 'node:os';
 import { execSync, spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { getShennianDir, loadConfig, resolveShennianPath, saveConfig } from '../config/index.js';
+import { buildAugmentedPath } from '../env-path.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SHENNIAN_DIR = getShennianDir();
 const PID_FILE = resolveShennianPath('daemon.pid');
@@ -15,6 +16,32 @@ const REMOTE_ACCESS_DISABLED_FILE = resolveShennianPath('remote-access.disabled'
 const LAUNCHER_FILE = resolveShennianPath('daemon-launcher.json');
 const SHENNIAN_SCRIPT = path.resolve(__dirname, '../../bin/shennian.js');
 const NODE_EXEC = process.execPath;
+const SAFE_SNAPSHOT_ENV_KEYS = new Set([
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'TMPDIR',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'SSH_AUTH_SOCK',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+    'TEMP',
+    'TMP',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'ELECTRON_RUN_AS_NODE',
+    'SHENNIAN_DESKTOP_CLI_SCRIPT',
+    'SHENNIAN_DESKTOP_CLI_BRIDGE',
+    'SHENNIAN_DESKTOP_SERVER_URL',
+    'SHENNIAN_HOME',
+]);
+export function isSafeSnapshotEnvKey(key) {
+    return SAFE_SNAPSHOT_ENV_KEYS.has(key);
+}
 function getPlatform() {
     const p = os.platform();
     if (p === 'darwin' || p === 'linux' || p === 'win32')
@@ -176,6 +203,7 @@ export function getDaemonStatus(opts = {}) {
         pidFile: PID_FILE,
         logFile: LOG_FILE,
         ...(config.machineId ? { machineId: config.machineId } : {}),
+        paired: Boolean(config.machineToken && config.machineId),
         ...(config.serverUrl ? { serverUrl: config.serverUrl } : {}),
     };
 }
@@ -190,6 +218,9 @@ function persistServerUrlOverride(serverUrl) {
     config.serverUrl = normalized;
     saveConfig(config);
 }
+function resolveServerUrlOverride(api) {
+    return api?.trim() || process.env.SHENNIAN_DESKTOP_SERVER_URL?.trim() || undefined;
+}
 // ─── Service definitions ─────────────────────────────────────────────────────
 const LAUNCHD_LABEL = 'com.shennian.agent';
 const LAUNCHD_PLIST = path.join(os.homedir(), 'Library/LaunchAgents', `${LAUNCHD_LABEL}.plist`);
@@ -391,40 +422,13 @@ function installWindowsScheduledTask() {
     }
 }
 export function captureEnvForService() {
-    const keep = [
-        'PATH',
-        'HOME',
-        'USER',
-        'LOGNAME',
-        'SHELL',
-        'TMPDIR',
-        'LANG',
-        'LC_ALL',
-        'LC_CTYPE',
-        'SSH_AUTH_SOCK',
-        'XDG_CONFIG_HOME',
-        'XDG_DATA_HOME',
-        'TEMP',
-        'TMP',
-        'ANTHROPIC_API_KEY',
-        'ANTHROPIC_AUTH_TOKEN',
-        'ANTHROPIC_BASE_URL',
-        'OPENAI_API_KEY',
-        'OPENAI_BASE_URL',
-        'GEMINI_API_KEY',
-        'GOOGLE_API_KEY',
-        'ELECTRON_RUN_AS_NODE',
-        'SHENNIAN_DESKTOP_CLI_SCRIPT',
-        'SHENNIAN_DESKTOP_CLI_BRIDGE',
-        'SHENNIAN_HOME',
-    ];
     const env = {};
-    for (const k of keep) {
+    for (const k of SAFE_SNAPSHOT_ENV_KEYS) {
         if (process.env[k])
             env[k] = process.env[k];
     }
     env.HOME ??= os.homedir();
-    env.PATH ??= '/usr/local/bin:/usr/bin:/bin';
+    env.PATH = buildAugmentedPath({ pathValue: env.PATH, env });
     env.USER ??= os.userInfo().username;
     if (getPlatform() === 'win32') {
         const tempDir = process.env.TEMP || process.env.TMP || os.tmpdir();
@@ -505,7 +509,7 @@ export function saveEnvSnapshot() {
     fs.mkdirSync(SHENNIAN_DIR, { recursive: true });
     const snapshot = {};
     for (const [k, v] of Object.entries(process.env)) {
-        if (v !== undefined)
+        if (v !== undefined && isSafeSnapshotEnvKey(k))
             snapshot[k] = v;
     }
     fs.writeFileSync(resolveShennianPath('env.json'), JSON.stringify(snapshot, null, 2));
@@ -650,7 +654,7 @@ async function stopDaemonProcessAndWait(timeoutMs = 5000) {
     return result;
 }
 function enableRemoteAccess(opts = {}) {
-    persistServerUrlOverride(opts.api);
+    persistServerUrlOverride(resolveServerUrlOverride(opts.api));
     try {
         fs.unlinkSync(REMOTE_ACCESS_DISABLED_FILE);
     }
@@ -723,6 +727,7 @@ async function disableRemoteAccess(opts = {}) {
     }
 }
 function daemonStart(opts) {
+    saveEnvSnapshot();
     enableRemoteAccess(opts);
 }
 async function daemonStop(opts = {}) {
@@ -738,7 +743,7 @@ async function waitForPidExit(pid, timeoutMs = 5000) {
     return !isRunning(pid);
 }
 async function daemonRestart(opts = {}) {
-    persistServerUrlOverride(opts.api);
+    persistServerUrlOverride(resolveServerUrlOverride(opts.api));
     const pid = readPid();
     if (pid !== null && isRunning(pid)) {
         try {

package/dist/src/commands/pair.d.ts

@@ -3,6 +3,7 @@ export declare function runPairFlow(opts: {
     serverUrl: string;
     machineName: string;
     force?: boolean;
+    json?: boolean;
 }): Promise<void>;
 export declare function registerDesktopMachine(opts: {
     serverUrl: string;

package/dist/src/commands/pair.js

@@ -8,6 +8,13 @@ import { detectAndChooseServer } from '../region.js';
 import { buildPairQrPayload, PAIR_QR_RENDER_OPTIONS } from './pair-qr.js';
 const POLL_INTERVAL_MS = 3000;
 const POLL_TIMEOUT_MS = 10 * 60 * 1000;
+function emitPairJson(event) {
+    process.stdout.write(`${JSON.stringify(event)}\n`);
+}
+function failPairJson(code, message) {
+    emitPairJson({ type: 'error', code, message });
+    process.exit(1);
+}
 function renderTokenBox(token) {
     const line = '─'.repeat(token.length + 4);
     console.log(chalk.cyan(`┌${line}┐`));
@@ -23,8 +30,10 @@ async function renderQR(url) {
         });
     });
 }
-async function pollStatus(serverUrl, pairToken) {
+async function pollStatus(serverUrl, pairToken, opts = {}) {
     const deadline = Date.now() + POLL_TIMEOUT_MS;
+    if (opts.json)
+        emitPairJson({ type: 'pair.waiting' });
     while (Date.now() < deadline) {
         await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
         let res;
@@ -35,13 +44,19 @@ async function pollStatus(serverUrl, pairToken) {
             continue;
         }
         if (res.status === 410) {
-            console.error(chalk.red('\n✗ Pairing code expired. Please re-run: shennian pair'));
-            process.exit(1);
+            if (opts.json)
+                failPairJson('PAIR_EXPIRED', 'Pairing code expired');
+            else {
+                console.error(chalk.red('\n✗ Pairing code expired. Please re-run: shennian pair'));
+                process.exit(1);
+            }
         }
         if (!res.ok)
             continue;
         const data = (await res.json());
         if (data.status === 'claimed' && data.machineToken && data.machineId) {
+            if (opts.json)
+                emitPairJson({ type: 'pair.claimed' });
             return {
                 machineToken: data.machineToken,
                 machineId: data.machineId,
@@ -61,11 +76,15 @@ function askConfirm(question) {
     });
 }
 export async function runPairFlow(opts) {
-    const { serverUrl, machineName, force } = opts;
+    const { serverUrl, machineName, force, json } = opts;
     const config = loadConfig();
     if (config.machineToken && config.machineId && !force) {
-        console.log(chalk.green(`✓ Already paired (machine ID: ${config.machineId})`));
-        console.log(chalk.gray('  Run "shennian pair" to re-pair to another account'));
+        if (json)
+            emitPairJson({ type: 'done', status: 'already-paired', machineId: config.machineId });
+        else {
+            console.log(chalk.green(`✓ Already paired (machine ID: ${config.machineId})`));
+            console.log(chalk.gray('  Run "shennian pair" to re-pair to another account'));
+        }
         return;
     }
     if (config.machineToken && !force)
@@ -74,9 +93,11 @@ export async function runPairFlow(opts) {
     const agentList = detectedAgents.map((a) => a.type);
     const platform = os.platform();
     const osName = platform === 'win32' ? 'windows' : platform === 'darwin' ? 'macos' : 'linux';
-    console.log(chalk.bold('\nShennian CLI — Pairing\n'));
-    console.log(chalk.gray(`  Machine: ${machineName}  |  OS: ${osName}  |  Agents: ${agentList.join(', ') || 'none'}`));
-    console.log();
+    if (!json) {
+        console.log(chalk.bold('\nShennian CLI — Pairing\n'));
+        console.log(chalk.gray(`  Machine: ${machineName}  |  OS: ${osName}  |  Agents: ${agentList.join(', ') || 'none'}`));
+        console.log();
+    }
     let res;
     try {
         res = await fetch(`${serverUrl}/api/machines/pair/create`, {
@@ -86,12 +107,18 @@ export async function runPairFlow(opts) {
         });
     }
     catch {
-        console.error(chalk.red(`✗ Network error: cannot connect to ${serverUrl}`));
+        const message = `Network error: cannot connect to ${serverUrl}`;
+        if (json)
+            failPairJson('NETWORK_ERROR', message);
+        console.error(chalk.red(`✗ ${message}`));
         process.exit(1);
     }
     if (!res.ok) {
         const body = await res.json().catch(() => ({}));
-        console.error(chalk.red(`✗ Failed to create machine: ${body.error ?? res.statusText}`));
+        const message = `Failed to create machine: ${body.error ?? res.statusText}`;
+        if (json)
+            failPairJson('PAIR_CREATE_FAILED', message);
+        console.error(chalk.red(`✗ ${message}`));
         process.exit(1);
     }
     const data = (await res.json());
@@ -99,21 +126,37 @@ export async function runPairFlow(opts) {
     config.serverUrl = serverUrl;
     saveConfig(config);
     const pairUrl = buildPairQrPayload(data.pairToken);
-    console.log(chalk.white('Scan QR code or enter the pairing code in the Shennian app:'));
-    console.log();
-    await renderQR(pairUrl);
-    renderTokenBox(data.pairToken);
-    console.log();
-    console.log(chalk.gray('Waiting for pairing... (Ctrl+C to cancel)'));
-    const result = await pollStatus(serverUrl, data.pairToken);
+    if (json) {
+        emitPairJson({
+            type: 'pair.created',
+            code: data.pairToken,
+            machineId: data.machineId,
+            expiresAt: new Date(Date.now() + POLL_TIMEOUT_MS).toISOString(),
+        });
+    }
+    else {
+        console.log(chalk.white('Scan QR code or enter the pairing code in the Shennian app:'));
+        console.log();
+        await renderQR(pairUrl);
+        renderTokenBox(data.pairToken);
+        console.log();
+        console.log(chalk.gray('Waiting for pairing... (Ctrl+C to cancel)'));
+    }
+    const result = await pollStatus(serverUrl, data.pairToken, { json });
     if (!result) {
+        if (json)
+            failPairJson('PAIR_TIMEOUT', 'Timed out waiting for pairing');
         console.error(chalk.red('\n✗ Timed out. Pairing code expired, please try again.'));
         process.exit(1);
     }
     config.machineToken = result.machineToken;
     config.machineId = result.machineId;
     saveConfig(config);
-    console.log(chalk.green(`\n✓ Paired successfully! Machine "${result.machineName}" is now linked.`));
+    if (json)
+        emitPairJson({ type: 'pair.saved', machineId: result.machineId });
+    if (!json) {
+        console.log(chalk.green(`\n✓ Paired successfully! Machine "${result.machineName}" is now linked.`));
+    }
 }
 export async function registerDesktopMachine(opts) {
     const config = loadConfig();
@@ -149,6 +192,18 @@ export async function registerDesktopMachine(opts) {
     saveConfig(config);
     return { machineId: data.machine.id, machineName: data.machine.name };
 }
+async function resolveDesktopRegisterServerUrl(api) {
+    const explicit = api?.trim();
+    if (explicit)
+        return explicit;
+    const envUrl = process.env.SHENNIAN_DESKTOP_SERVER_URL?.trim();
+    if (envUrl)
+        return envUrl;
+    const configUrl = loadConfig().serverUrl?.trim();
+    if (configUrl)
+        return configUrl;
+    return detectAndChooseServer();
+}
 export async function runSmartStart(serverUrl, machineName) {
     const config = loadConfig();
     if (!config.machineToken) {
@@ -169,15 +224,16 @@ export function registerPairCommand(program) {
     program
         .command('desktop-register', { hidden: true })
         .description('Register this desktop-managed machine to the authenticated account')
-        .requiredOption('--api <url>', 'Server URL')
+        .option('--api <url>', 'Server URL')
         .option('--name <name>', 'Machine name', os.hostname())
         .action(async (opts) => {
         try {
             const token = process.env.SHENNIAN_DESKTOP_AUTH_TOKEN;
             if (!token)
                 throw new Error('Missing desktop auth token');
+            const serverUrl = await resolveDesktopRegisterServerUrl(opts.api);
             const result = await registerDesktopMachine({
-                serverUrl: opts.api,
+                serverUrl,
                 authToken: token,
                 machineName: opts.name,
             });
@@ -192,10 +248,16 @@ export function registerPairCommand(program) {
         .command('pair')
         .description('Pair this machine to a Shennian account (re-pair if already paired)')
         .option('--api <url>', 'Server URL override')
+        .option('--server <url>', 'Server URL override')
         .option('--name <name>', 'Machine name', os.hostname())
+        .option('--json', 'Emit machine-readable JSONL events')
         .action(async (opts) => {
         const config = loadConfig();
         if (config.machineToken) {
+            if (opts.json) {
+                emitPairJson({ type: 'done', status: 'already-paired', machineId: config.machineId });
+                return;
+            }
             console.log(chalk.yellow(`Currently paired (machine ID: ${config.machineId})`));
             const yes = await askConfirm('Re-pairing will unlink the current account. Continue? (y/N) ');
             if (!yes) {
@@ -206,13 +268,18 @@ export function registerPairCommand(program) {
             delete config.machineId;
             saveConfig(config);
         }
-        const serverUrl = opts.api ?? (await detectAndChooseServer());
-        await runPairFlow({ serverUrl, machineName: opts.name, force: true });
+        const serverUrl = opts.server ?? opts.api ?? (await detectAndChooseServer());
+        await runPairFlow({ serverUrl, machineName: opts.name, force: true, json: Boolean(opts.json) });
         saveEnvSnapshot();
-        console.log(chalk.gray('\nStarting background service...'));
+        if (opts.json)
+            emitPairJson({ type: 'daemon.starting' });
+        else
+            console.log(chalk.gray('\nStarting background service...'));
         const startedByService = installService();
         if (!startedByService) {
-            startDaemonProcess();
+            startDaemonProcess({ quiet: Boolean(opts.json) });
         }
+        if (opts.json)
+            emitPairJson({ type: 'done', status: 'paired', machineId: loadConfig().machineId });
     });
 }

package/dist/src/env-path.d.ts

@@ -0,0 +1,14 @@
+export declare function getUserBinPathCandidates(input?: {
+    env?: NodeJS.ProcessEnv;
+    homedir?: string;
+    exists?: (filePath: string) => boolean;
+    readdir?: (filePath: string) => string[];
+}): string[];
+export declare function buildAugmentedPath(input?: {
+    pathValue?: string;
+    env?: NodeJS.ProcessEnv;
+    homedir?: string;
+    exists?: (filePath: string) => boolean;
+    readdir?: (filePath: string) => string[];
+}): string;
+export declare function augmentProcessPath(): void;

package/dist/src/env-path.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const DEFAULT_POSIX_PATH = '/usr/local/bin:/usr/bin:/bin';
+function uniquePush(parts, value, front = false) {
+    if (!value || parts.includes(value))
+        return;
+    if (front)
+        parts.unshift(value);
+    else
+        parts.push(value);
+}
+export function getUserBinPathCandidates(input = {}) {
+    const env = input.env ?? process.env;
+    const home = input.homedir ?? os.homedir();
+    const exists = input.exists ?? fs.existsSync;
+    const readdir = input.readdir ?? ((filePath) => fs.readdirSync(filePath));
+    const candidates = [];
+    if (process.platform === 'win32') {
+        const appData = env.APPDATA?.trim() || path.join(home, 'AppData', 'Roaming');
+        const localAppData = env.LOCALAPPDATA?.trim() || path.join(home, 'AppData', 'Local');
+        uniquePush(candidates, path.join(appData, 'npm'));
+        uniquePush(candidates, path.join(localAppData, 'pnpm'));
+        uniquePush(candidates, path.join(home, 'scoop', 'shims'));
+        uniquePush(candidates, path.join('C:\\', 'Program Files', 'nodejs'));
+        return candidates;
+    }
+    uniquePush(candidates, path.join(home, '.local', 'bin'));
+    uniquePush(candidates, path.join(home, '.bun', 'bin'));
+    uniquePush(candidates, path.join(home, '.npm-global', 'bin'));
+    uniquePush(candidates, path.join(home, '.npm', 'bin'));
+    uniquePush(candidates, path.join(home, '.cargo', 'bin'));
+    uniquePush(candidates, path.join(home, '.maestro', 'bin'));
+    const nvmDir = env.NVM_DIR?.trim() || path.join(home, '.nvm');
+    const nvmVersionsDir = path.join(nvmDir, 'versions', 'node');
+    try {
+        const nvmBins = readdir(nvmVersionsDir)
+            .sort((left, right) => right.localeCompare(left, undefined, { numeric: true }))
+            .map((version) => path.join(nvmVersionsDir, version, 'bin'))
+            .filter((candidate) => exists(candidate));
+        for (const candidate of nvmBins)
+            uniquePush(candidates, candidate);
+    }
+    catch {
+        // nvm is optional.
+    }
+    uniquePush(candidates, '/opt/homebrew/bin');
+    uniquePush(candidates, '/usr/local/bin');
+    uniquePush(candidates, '/usr/bin');
+    uniquePush(candidates, '/bin');
+    uniquePush(candidates, '/usr/sbin');
+    uniquePush(candidates, '/sbin');
+    return candidates;
+}
+export function buildAugmentedPath(input = {}) {
+    const basePath = input.pathValue ?? input.env?.PATH ?? process.env.PATH ?? DEFAULT_POSIX_PATH;
+    const parts = basePath.split(path.delimiter).filter(Boolean);
+    for (const candidate of getUserBinPathCandidates(input))
+        uniquePush(parts, candidate);
+    return parts.join(path.delimiter);
+}
+export function augmentProcessPath() {
+    process.env.PATH = buildAugmentedPath();
+}

package/dist/src/index.js

@@ -15,6 +15,8 @@ import { SessionManager } from './session/manager.js';
 import { SERVERS, regionToUrl, urlToRegion } from './region.js';
 import { getCurrentVersion, handleStartupCrashCheck, checkForUpdate, isUpgradeVersionInCooldown, recordUpgradeFailure, } from './upgrade/engine.js';
 import { detectAgents } from './agents/detect.js';
+import { augmentProcessPath } from './env-path.js';
+augmentProcessPath();
 const cliVersion = getCurrentVersion();
 const AUTO_UPGRADE_INITIAL_DELAY_MS = 30_000;
 const AUTO_UPGRADE_POLL_INTERVAL_MS = 5 * 60_000;
@@ -66,7 +68,7 @@ program
     .option('--name <name>', 'Machine name', os.hostname())
     .action(async (opts) => {
     const config = loadConfig();
-    const serverUrl = opts.api ?? config.serverUrl ?? undefined;
+    const serverUrl = opts.api ?? process.env.SHENNIAN_DESKTOP_SERVER_URL ?? config.serverUrl ?? undefined;
     await runSmartStart(serverUrl, opts.name);
 });
 // run-service: internal command used by the background service process
@@ -82,6 +84,7 @@ program
             if (!process.env[k])
                 process.env[k] = v;
         }
+        augmentProcessPath();
     }
     catch {
         // env.json may not exist yet
@@ -148,7 +151,7 @@ program
         console.error(chalk.red('✗ Not paired yet. Run: shennian'));
         process.exit(1);
     }
-    const serverUrl = opts.api ?? config.serverUrl ?? SERVERS.global.url;
+    const serverUrl = opts.api ?? process.env.SHENNIAN_DESKTOP_SERVER_URL ?? config.serverUrl ?? SERVERS.global.url;
     const wsBase = httpToWs(serverUrl);
     const wsUrl = `${wsBase}/relay/machine`;
     const cliVersion = getCurrentVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shennian",
-  "version": "0.2.30",
+  "version": "0.2.33",
   "description": "Shennian — AI Agent Control Plane CLI",
   "type": "module",
   "bin": {
@@ -32,14 +32,20 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "build": "tsc",
+    "build:publish": "node -e \"const fs=require('node:fs'); fs.rmSync('dist', { recursive: true, force: true }); fs.rmSync('.tsbuildinfo.publish', { force: true })\" && tsc -p tsconfig.publish.json",
+    "dev": "tsc --watch",
+    "prepublishOnly": "pnpm build:publish"
+  },
   "dependencies": {
     "@mariozechner/pi-agent-core": "^0.64.0",
     "@sinclair/typebox": "^0.34.49",
+    "@shennian/wire": "^0.1.2",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "qrcode-terminal": "^0.12.0",
-    "ws": "^8.18.1",
-    "@shennian/wire": "0.1.2"
+    "ws": "^8.18.1"
   },
   "devDependencies": {
     "@types/node": "^20",
@@ -47,10 +53,5 @@
     "@types/ws": "^8.18.1",
     "tsx": "^4.19.4",
     "typescript": "^5.9.3"
-  },
-  "scripts": {
-    "build": "tsc",
-    "build:publish": "node -e \"const fs=require('node:fs'); fs.rmSync('dist', { recursive: true, force: true }); fs.rmSync('.tsbuildinfo.publish', { force: true })\" && tsc -p tsconfig.publish.json",
-    "dev": "tsc --watch"
   }
-}
+}