shennian 0.2.29 → 0.2.32

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 });
     });
 }