openyida 2026.10.13 → 2026.10.14

package/lib/agent/ask-human.js

@@ -0,0 +1,222 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { CliError } = require('../core/cli-error');
+const { readManagedContext } = require('./managed-context');
+
+const SCHEMA = 'openyida.ask-human.v2';
+const MAX_FILE_BYTES = 32 * 1024;
+const HELP = require('./ask-human-help');
+const USAGE = `用法：${HELP.usage}`;
+
+function fail(code, message) { throw new CliError(message, { code, details: { retryable: false } }); }
+function text(value, max) { return typeof value === 'string' && value === value.trim() && value.length > 0 && Buffer.byteLength(value) <= max && !/\p{Cc}/u.test(value); }
+
+function parseArgs(argv) {
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) { return { help: true }; }
+  const result = { json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const name = argv[i];
+    if (name === '--json' && !result.json) { result.json = true; continue; }
+    const key = name === '--request-key' ? 'requestKey' : name === '--questions-file' ? 'questionsFile' : null;
+    if (!key || result[key] !== undefined || !argv[i + 1] || argv[i + 1].startsWith('--')) {
+      fail('AGENT_ASK_HUMAN_INVALID', USAGE);
+    }
+    result[key] = argv[++i];
+  }
+  if (!text(result.requestKey, 128) || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(result.requestKey) ||
+      !text(result.questionsFile, 512) || path.isAbsolute(result.questionsFile)) {
+    fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 参数无效。');
+  }
+  return result;
+}
+
+function readQuestions(relativePath, cwd) {
+  let root;
+  let candidate;
+  let realCandidate;
+  let stat;
+  try {
+    root = fs.realpathSync(cwd);
+    candidate = path.resolve(root, relativePath);
+    stat = fs.lstatSync(candidate);
+    realCandidate = fs.realpathSync(candidate);
+  } catch { fail('AGENT_ASK_HUMAN_INVALID', '问题文件不可读取。'); }
+  if (candidate === root || !candidate.startsWith(root + path.sep) || realCandidate === root || !realCandidate.startsWith(root + path.sep)) {
+    fail('AGENT_ASK_HUMAN_INVALID', '问题文件必须位于当前工作目录。');
+  }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_FILE_BYTES) { fail('AGENT_ASK_HUMAN_INVALID', '问题文件必须是 32 KiB 以内的普通文件。'); }
+  let document;
+  try { document = JSON.parse(fs.readFileSync(candidate, 'utf8')); } catch { fail('AGENT_ASK_HUMAN_INVALID', '问题文件不是有效 JSON。'); }
+  if (!document || typeof document !== 'object' || Array.isArray(document) || !text(document.title, 256) ||
+      !Array.isArray(document.questions) || document.questions.length < 1 || document.questions.length > 3) {
+    fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 问题结构无效。');
+  }
+  const ids = new Set();
+  for (const question of document.questions) {
+    const allowed = new Set(['id', 'header', 'question', 'type', 'required', 'options']);
+    if (!question || typeof question !== 'object' || Array.isArray(question) || Object.keys(question).some(key => !allowed.has(key)) ||
+        !text(question.id, 128) || ids.has(question.id) || !text(question.header, 128) || !text(question.question, 2048) ||
+        !['text', 'single_select', 'multi_select'].includes(question.type) ||
+        (question.required !== undefined && typeof question.required !== 'boolean')) {
+      fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 问题结构无效。');
+    }
+    ids.add(question.id);
+    const options = question.options === undefined ? [] : question.options;
+    if (!Array.isArray(options)) { fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 选项结构无效。'); }
+    if ((question.type === 'text' && options.length) || (question.type !== 'text' && (!Array.isArray(options) || options.length < 1 || options.length > 12)) ||
+        options.some(option => !option || typeof option !== 'object' || Array.isArray(option) || Object.keys(option).some(key => !['label', 'value', 'description'].includes(key)) || !text(option.label, 512) || (option.value !== undefined && !text(option.value, 512)) ||
+          (option.description !== undefined && option.description !== '' && !text(option.description, 1024)))) {
+      fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 选项结构无效。');
+    }
+    if (new Set(options.map(option => option.value || option.label)).size !== options.length) { fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 选项不能重复。'); }
+  }
+  if (Object.keys(document).some(key => !['title', 'questions', 'revision', 'attachments'].includes(key)) ||
+      (document.revision !== undefined && !text(document.revision, 256)) ||
+      (document.attachments !== undefined && (!Array.isArray(document.attachments) || document.attachments.length > 10))) {
+    fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 附件或方案版本无效。');
+  }
+  return { title: document.title,
+    ...(document.revision ? { contextRevision: document.revision } : {}),
+    attachments: document.attachments || [],
+    questions: document.questions.map(question => ({ ...question, required: question.required !== false,
+      ...(question.options ? { options: question.options.map(option => ({ ...option, value: option.value || option.label })) } : {}) })) };
+}
+
+// Explicit output only. Freeze bytes before publishing a question receipt.
+function snapshotAttachments(attachments, cwd, directory) {
+  const root = fs.realpathSync(cwd);
+  const files = path.join(directory, '.files');
+  fs.mkdirSync(files, { recursive: true, mode: 0o700 });
+  if (fs.lstatSync(files).isSymbolicLink() || fs.realpathSync(files) !== files) { fail('AGENT_ASK_HUMAN_INVALID', '附件目录无效。'); }
+  const seen = new Set();
+  let total = 0;
+  return attachments.map(attachment => {
+    if (!attachment || typeof attachment !== 'object' || Array.isArray(attachment) ||
+        Object.keys(attachment).some(key => !['name', 'path'].includes(key)) ||
+        !text(attachment.name, 256) || !text(attachment.path, 1024)) {
+      fail('AGENT_ASK_HUMAN_INVALID', '附件格式无效。');
+    }
+    const source = path.resolve(root, attachment.path);
+    const relative = path.relative(root, source);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative) ||
+        relative.split(path.sep).some(part => /^(?:\.env(?:\..*)?|\.git|node_modules|\.openyida|credentials?|auth|tokens?)$/i.test(part))) {
+      fail('AGENT_ASK_HUMAN_INVALID', '附件必须是任务工作目录中的交付文件。');
+    }
+    const extension = path.extname(source).toLowerCase();
+    if (!['.html', '.htm', '.md', '.txt'].includes(extension)) { fail('AGENT_ASK_HUMAN_INVALID', '附件仅支持 HTML、Markdown 或文本。'); }
+    let bytes;
+    try {
+      // Reject symlink/reparse traversal, including linked parent directories.
+      if (fs.realpathSync(source) !== source || !fs.lstatSync(source).isFile() || fs.lstatSync(source).isSymbolicLink()) { throw new Error(); }
+      const fd = fs.openSync(source, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+      try {
+        const info = fs.fstatSync(fd);
+        if (!info.isFile() || info.size > 1024 * 1024) { throw new Error(); }
+        const bounded = Buffer.alloc(1024 * 1024 + 1);
+        let count = 0;
+        while (count < bounded.length) {
+          const read = fs.readSync(fd, bounded, count, bounded.length - count, null);
+          if (!read) { break; }
+          count += read;
+        }
+        bytes = bounded.subarray(0, count);
+      } finally { fs.closeSync(fd); }
+      if (bytes.length > 1024 * 1024 || bytes.includes(0) || !Buffer.from(bytes.toString('utf8')).equals(bytes)) { throw new Error(); }
+    } catch { fail('AGENT_ASK_HUMAN_INVALID', '附件不可读取，或超过 1 MiB/不是 UTF-8 文本。'); }
+    total += bytes.length;
+    if (total > 10 * 1024 * 1024) { fail('AGENT_ASK_HUMAN_LIMIT', '附件总大小超过限制。'); }
+    const sha256 = crypto.createHash('sha256').update(bytes).digest('hex');
+    const file = `${sha256}${extension}`;
+    if (seen.has(file)) { fail('AGENT_ASK_HUMAN_INVALID', '附件不能重复。'); }
+    seen.add(file);
+    const target = path.join(files, file);
+    if (fs.existsSync(target)) {
+      if (fs.lstatSync(target).isSymbolicLink() || !fs.readFileSync(target).equals(bytes)) { fail('AGENT_ASK_HUMAN_CONFLICT', '附件快照冲突。'); }
+    } else {
+      const temporary = path.join(files, `.${crypto.randomUUID()}.tmp`);
+      const fd = fs.openSync(temporary, 'wx', 0o600);
+      try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+      retryWindowsFileOperation(() => fs.renameSync(temporary, target));
+    }
+    return { name: attachment.name, path: `.files/${file}`, sha256, sizeBytes: bytes.length };
+  });
+}
+
+function ensureReceiptDir(env) {
+  const value = env.OPENYIDA_AGENT_INTERACTIONS_DIR;
+  if (!value || !path.isAbsolute(value)) { fail('AGENT_ASK_HUMAN_UNAVAILABLE', '当前任务未启用 Ask Human。'); }
+  fs.mkdirSync(value, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(value);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) { fail('AGENT_ASK_HUMAN_UNAVAILABLE', 'Ask Human 私有目录不可用。'); }
+  if (fs.readdirSync(value).filter(name => name.endsWith('.json')).length >= 64) { fail('AGENT_ASK_HUMAN_LIMIT', '本轮 Ask Human 请求过多。'); }
+  return fs.realpathSync(value);
+}
+
+function retryWindowsFileOperation(operation) {
+  const delays = [20, 40, 80, 160, 320];
+  for (let attempt = 0; ; attempt++) {
+    try { return operation(); } catch (error) {
+      if (process.platform !== 'win32' || attempt === delays.length || !['EBUSY', 'EPERM', 'EACCES'].includes(error.code)) { throw error; }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delays[attempt]);
+    }
+  }
+}
+
+function writeReceipt(directory, requestId, receipt) {
+  const temporary = path.join(directory, `.${requestId}.tmp`);
+  const target = path.join(directory, `${requestId}.json`);
+  let fd;
+  try {
+    fd = fs.openSync(temporary, 'wx', 0o600);
+    fs.writeFileSync(fd, JSON.stringify(receipt));
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    retryWindowsFileOperation(() => fs.renameSync(temporary, target));
+    if (process.platform !== 'win32') {
+      const parent = fs.openSync(directory, 'r');
+      try { fs.fsyncSync(parent); } finally { fs.closeSync(parent); }
+    }
+  } catch (error) {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* Preserve the original write failure if cleanup also fails. */ } }
+    if (fs.existsSync(temporary)) { try { retryWindowsFileOperation(() => fs.unlinkSync(temporary)); } catch { /* Preserve the original write failure if cleanup also fails. */ } }
+    throw error;
+  }
+}
+
+function run(argv = [], options = {}) {
+  const env = options.env || process.env;
+  const context = readManagedContext(env);
+  if (!context) { fail('AGENT_ASK_HUMAN_MANAGED_ONLY', 'Ask Human 仅可在宜搭云端发起的本地 Agent 任务中使用。'); }
+  const args = parseArgs(argv);
+  if (args.help) {
+    (options.stdout || process.stdout).write([USAGE, HELP.description, ...HELP.examples].join('\n') + '\n');
+    return { ok: true, help: true };
+  }
+  const document = readQuestions(args.questionsFile, options.cwd || process.cwd());
+  const directory = ensureReceiptDir(env);
+  document.attachments = snapshotAttachments(document.attachments, options.cwd || process.cwd(), directory);
+  const digest = crypto.createHash('sha256').update(JSON.stringify(document)).digest('hex');
+  for (const name of fs.readdirSync(directory).filter(item => item.endsWith('.json'))) {
+    let prior;
+    try { prior = JSON.parse(fs.readFileSync(path.join(directory, name), 'utf8')); } catch { continue; }
+    if (prior.requestKey === args.requestKey) {
+      if (prior.contentDigest !== digest) { fail('AGENT_ASK_HUMAN_CONFLICT', '同一 request-key 不能提交不同问题。'); }
+      const output = { ok: true, requestId: prior.requestId, status: 'queued' };
+      (options.stdout || process.stdout).write(JSON.stringify(output) + '\n');
+      return output;
+    }
+  }
+  const requestId = crypto.randomUUID();
+  const receipt = { schemaVersion: SCHEMA, requestId, requestKey: args.requestKey, contentDigest: digest,
+    runId: context.runId, attemptId: context.attemptId, createdAt: new Date().toISOString(), ...document };
+  writeReceipt(directory, requestId, receipt);
+  const output = { ok: true, requestId, status: 'queued' };
+  (options.stdout || process.stdout).write(JSON.stringify(output) + '\n');
+  return output;
+}
+
+module.exports = { run, SCHEMA };

package/lib/agent/cmd.js

@@ -0,0 +1,405 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const crypto = require('crypto');
+const { EventEmitter } = require('events');
+const { CliError } = require('../core/cli-error');
+const { t } = require('../core/i18n');
+const { resolveRuntime, PROTOCOL_VERSION } = require('./runtime-package');
+const { materializeBundle } = require('./frozen-bundle');
+const { launchRuntime, launchBackgroundRuntime, BACKGROUND_LOG_NAME } = require('./stdio');
+const { prepareConnection, listConnections } = require('./connection-store');
+const { createDiagnosticLog, defaultDiagnosticDir, readRecentCredentialFailures } = require('./diagnostic-log');
+const { version, openyidaAgent = {} } = require('../../package.json');
+
+const COMMANDS = ['doctor', 'diagnose', 'status', 'connect', 'run', 'disconnect', 'logout', 'logs'];
+const VALUE_OPTIONS = {
+  '--runtime-path': 'runtimePath', '--runtime-manifest': 'manifestPath',
+  '--endpoint': 'endpoint', '--endpoint-id': 'endpointId', '--enroll': 'enrollmentToken',
+  '--provider': 'provider', '--provider-path': 'providerPath', '--state-dir': 'stateDir',
+  '--session': 'diagnosticSession', '--output': 'diagnosticOutput',
+};
+
+function safeUrl(value) {
+  let url;
+  try {url = new URL(value);} catch {throw new CliError(t('agent.identity_invalid'), { code: 'AGENT_ENDPOINT_INVALID' });}
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) || url.username || url.password || url.search || url.hash) {
+    throw new CliError(t('agent.identity_invalid'), { code: 'AGENT_ENDPOINT_INVALID' });
+  }
+  return url.toString().replace(/\/+$/, '');
+}
+
+const PROVIDERS = require('./providers');
+
+const { discoverProviders, preflight } = require('./provider-preflight');
+
+function discoverProvider(env = process.env, platform = process.platform) {
+  return discoverProviders(env, platform)[0];
+}
+
+function parseArgs(args = []) {
+  const result = { command: args[0] || 'help', json: false };
+  if (args.includes('--help') || args.includes('-h')) {return { command: 'help' };}
+  if (result.command === 'help') {return result;}
+  if (!COMMANDS.includes(result.command)) {
+    throw new CliError(t('agent.usage'), { code: 'INVALID_ARGUMENTS' });
+  }
+  for (let i = 1; i < args.length; i++) {
+    const name = args[i];
+    if (['--json', '--development-runtime', '--deep'].includes(name)) {
+      const key = name === '--json' ? 'json' : name === '--deep' ? 'diagnosticDeep' : 'developmentRuntime';
+      if (result[key] === true) {throw new CliError(t('agent.usage'), { code: 'INVALID_ARGUMENTS' });}
+      result[key] = true;
+      continue;
+    }
+    const key = VALUE_OPTIONS[name];
+    if (!key || result[key] !== undefined || !args[i + 1] || args[i + 1].startsWith('--')) {
+      throw new CliError(t('agent.usage'), { code: 'INVALID_ARGUMENTS' });
+    }
+    result[key] = args[++i];
+  }
+  if (result.enrollmentToken && result.command !== 'connect') {throw new CliError(t('agent.input_invalid'), { code: 'AGENT_INPUT_INVALID' });}
+  if ((result.diagnosticSession || result.diagnosticOutput || result.diagnosticDeep) && result.command !== 'diagnose') {
+    throw new CliError(t('agent.input_invalid'), { code: 'AGENT_INPUT_INVALID' });
+  }
+  return result;
+}
+
+function parseDiagnosticSession(value) {
+  if (!value) {return null;}
+  const direct = /^local_[a-zA-Z0-9_-]{1,200}$/.test(value) ? value : null;
+  if (direct) {return { sessionId: direct, appType: null };}
+  let parsed;
+  try {parsed = new URL(value);} catch {parsed = null;}
+  if (!parsed || parsed.protocol !== 'https:' || parsed.username || parsed.password) {
+    throw new CliError(t('agent.diagnostic_session_invalid'), { code: 'AGENT_DIAGNOSTIC_SESSION_INVALID' });
+  }
+  const sessionId = parsed.searchParams.get('sessionId') || '';
+  const appType = parsed.pathname.split('/').find(part => /^APP_[a-zA-Z0-9_-]{1,200}$/.test(part)) || null;
+  if (!/^local_[a-zA-Z0-9_-]{1,200}$/.test(sessionId)) {
+    throw new CliError(t('agent.diagnostic_session_invalid'), { code: 'AGENT_DIAGNOSTIC_SESSION_INVALID' });
+  }
+  return { sessionId, appType };
+}
+
+function writeDiagnosticSummary(args, config, results, stdout) {
+  const diagnosticId = config.diagnosticId || `diag_${crypto.randomUUID()}`;
+  const summary = { type: 'diagnostic', schemaVersion: 1, diagnosticId,
+    phase: config.diagnosticSession ? 'session' : 'connection',
+    sessionId: config.diagnosticSession || undefined, appType: config.diagnosticAppType || undefined,
+    connections: results, findings: results.flatMap(item => Array.isArray(item.findings) ? item.findings : []) };
+  // Connection-stage failures can predate any paired Connection or Session.
+  // Do not attribute installation-wide history to an unrelated session.
+  if (!config.diagnosticSession && config.diagnosticsDir) {
+    summary.recentConnectionFailures = readRecentCredentialFailures(config.diagnosticsDir);
+    if (summary.recentConnectionFailures.length) {
+      summary.findings.push({ severity: 'warning', code: 'RECENT_DEVICE_CREDENTIAL_REJECTION',
+        historical: true, action: 'CHECK_RECENT_CONNECTION_FAILURE_DETAILS' });
+    }
+  }
+  const serialized = `${JSON.stringify(summary, null, args.json ? 0 : 2)}\n`;
+  if (args.diagnosticOutput) {
+    const output = path.resolve(args.diagnosticOutput);
+    fs.mkdirSync(output, { recursive: true, mode: 0o700 });
+    const target = path.join(output, `openyida-local-agent-diagnostic-${diagnosticId}.json`);
+    fs.writeFileSync(target, serialized, { mode: 0o600, flag: 'wx' });
+    summary.outputPath = target;
+  }
+  stdout.write(`${JSON.stringify(summary, null, args.json ? 0 : 2)}\n`);
+}
+
+function buildLaunchConfig(args, options = {}) {
+  const packageRoot = options.packageRoot || path.resolve(__dirname, '..', '..');
+  const stateDir = args.stateDir || path.join(options.homedir || os.homedir(), '.openyida', 'local-agent');
+  const env = options.env === undefined ? process.env : options.env;
+  if (!path.isAbsolute(stateDir)) {
+    throw new CliError(t('agent.absolute_path_required'), { code: 'AGENT_STATE_PATH_INVALID' });
+  }
+  const config = {
+    protocolVersion: PROTOCOL_VERSION,
+    command: args.command,
+    stateDir,
+    sessionStateDir: path.join(stateDir, 'sessions'),
+    node: { executable: process.execPath, cliEntry: path.join(packageRoot, 'bin', 'yida.js'), packageRoot, version },
+    providers: [],
+    diagnosticsDir: path.join(stateDir, 'logs'),
+  };
+  if (args.diagnosticId) {config.diagnosticId = args.diagnosticId;}
+  if (args.developmentRuntime === true) {config.developmentRuntime = true;}
+  const endpoint = args.endpoint || env.OPENYIDA_AGENT_CONTROL_ENDPOINT ||
+    (options.env === undefined ? openyidaAgent.endpoint : undefined);
+  const endpointId = args.endpointId || env.OPENYIDA_AGENT_ENDPOINT_ID ||
+    (options.env === undefined ? openyidaAgent.endpointId : undefined);
+  if (endpoint) {config.endpoint = safeUrl(endpoint);}
+  if (endpointId) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(endpointId)) {
+      throw new CliError(t('agent.identity_invalid'), { code: 'AGENT_ENDPOINT_INVALID' });
+    }
+    config.endpointId = endpointId;
+  }
+  if (args.enrollmentToken) {
+    if (args.enrollmentToken.length < 32 || args.enrollmentToken.length > 4096 || /\s/.test(args.enrollmentToken)) {
+      throw new CliError(t('agent.input_invalid'), { code: 'AGENT_ENROLLMENT_TOKEN_INVALID' });
+    }
+    config.enrollmentToken = args.enrollmentToken;
+  }
+  if (args.diagnosticSession) {
+    const diagnostic = parseDiagnosticSession(args.diagnosticSession);
+    config.diagnosticSession = diagnostic.sessionId;
+    if (diagnostic.appType) {config.diagnosticAppType = diagnostic.appType;}
+  }
+  if (args.diagnosticDeep === true) {config.diagnosticDeep = true;}
+  if (['connect', 'run'].includes(args.command) && (!config.endpoint || !config.endpointId) && !options.allowStoredConnections) {
+    throw new CliError(t('agent.connection_options_required'), { code: 'AGENT_CONNECTION_OPTIONS_REQUIRED' });
+  }
+  if (args.provider || args.providerPath) {
+    if (!PROVIDERS.includes(args.provider) || (args.providerPath && !path.isAbsolute(args.providerPath))) {
+      throw new CliError(t('agent.provider_options_required'), { code: 'AGENT_PROVIDER_OPTIONS_INVALID' });
+    }
+    if (args.providerPath) { config.providers.push({ profileId: `openyida.${args.provider}`, provider: args.provider, executable: args.providerPath }); }
+  }
+  if (['connect', 'run', 'doctor', 'diagnose'].includes(args.command) && config.providers.length === 0) {
+    const discovered = discoverProviders(env, options.platform || process.platform, options.homedir).filter(p => !args.provider || p.provider === args.provider);
+    if (discovered.length === 0) {
+      if (args.command === 'run') {
+        throw new CliError(t('agent.provider_not_found'), { code: 'AGENT_PROVIDER_NOT_FOUND' });
+      }
+    }
+    config.providers.push(...discovered);
+  }
+  return config;
+}
+
+function readLogTail(logPath, maxBytes = 64 * 1024) {
+  let fd;
+  try {fd = fs.openSync(logPath, 'r');} catch {return null;}
+  try {
+    const { size } = fs.fstatSync(fd);
+    const start = size > maxBytes ? size - maxBytes : 0;
+    const length = size - start;
+    if (length <= 0) {return '';}
+    const buffer = Buffer.alloc(length);
+    fs.readSync(fd, buffer, 0, length, start);
+    return buffer.toString('utf8');
+  } finally {fs.closeSync(fd);}
+}
+
+// `logs` is a Node-only inspection command. It never launches the Go runtime;
+// it surfaces the per-connection background daemon log so the user can review a
+// connection that is running detached after the terminal already returned.
+function emitLogs(args, options, stdout) {
+  const baseStateDir = args.stateDir || path.join(options.homedir || os.homedir(), '.openyida', 'local-agent');
+  if (!path.isAbsolute(baseStateDir)) {
+    throw new CliError(t('agent.absolute_path_required'), { code: 'AGENT_STATE_PATH_INVALID' });
+  }
+  const connections = options.disableConnectionManager === true ? [] : listConnections(baseStateDir);
+  if (connections.length === 0) {
+    stdout.write(`${JSON.stringify({ type: 'logs', connections: [] })}\n`);
+    return;
+  }
+  for (const connection of connections) {
+    const logPath = path.join(connection.stateDir, 'logs', BACKGROUND_LOG_NAME);
+    const content = readLogTail(logPath);
+    stdout.write(`${JSON.stringify({ type: 'logs', connectionId: connection.connectionId, endpointId: connection.endpointId, logPath, available: content !== null })}\n`);
+    if (content) {stdout.write(content.endsWith('\n') ? content : `${content}\n`);}
+  }
+}
+
+async function run(argv = [], options = {}) {
+  if (argv[0] === 'ask-human') {
+    return require('./ask-human').run(argv.slice(1), options);
+  }
+  const args = parseArgs(argv);
+  const stdout = options.stdout || process.stdout;
+  if (args.command === 'help') {stdout.write(`${t('agent.usage')}\n`); return;}
+  if (args.command === 'logs') {return emitLogs(args, options, stdout);}
+  let providerCheck;
+  // A normal `run` must resolve the same discovered executable that connect/doctor
+  // validated. A stale earlier PATH entry must not replace a working bundled
+  // CLI after restart. An explicit absolute provider path is verified by Go.
+  if (['connect', 'doctor'].includes(args.command) || (args.command === 'run' && !args.providerPath)) {
+    if ((args.provider || args.providerPath) && (!PROVIDERS.includes(args.provider) || (args.providerPath && !path.isAbsolute(args.providerPath)))) {
+      throw new CliError(t('agent.provider_options_required'), { code: 'AGENT_PROVIDER_OPTIONS_INVALID' });
+    }
+    providerCheck = await preflight(args, options);
+    if (args.command === 'connect') {
+      if (args.json) { stdout.write(JSON.stringify(providerCheck) + '\n'); }
+      else {
+        const stderr = options.stderr || process.stderr;
+        stderr.write(t('agent.preflight_advisory') + '\n');
+        for (const item of providerCheck.providers) {
+          stderr.write(item.provider + ': ' + item.message + (item.desktopDetected ? ' (' + t('agent.preflight_desktop') + ')' : '') + '\n');
+        }
+        stderr.write(t(providerCheck.readyForEnrollment ? 'agent.preflight_continue' : 'agent.preflight_retry') + '\n');
+      }
+      if (!providerCheck.readyForEnrollment) {
+        throw new CliError(t('agent.preflight_blocked'), { code: 'AGENT_PREFLIGHT_BLOCKED', details: providerCheck });
+      }
+    }
+    if (args.command === 'run' && !providerCheck.readyForEnrollment) {
+      throw new CliError(t('agent.preflight_blocked'), { code: 'AGENT_PREFLIGHT_BLOCKED', details: providerCheck });
+    }
+  }
+  const diagnosticsDir = args.stateDir
+    ? path.join(args.stateDir, 'logs')
+    : defaultDiagnosticDir(options.homedir || os.homedir());
+  const diagnostic = createDiagnosticLog(diagnosticsDir);
+  diagnostic('info', 'launcher_started', { command: args.command, component: 'node', runtimeVersion: version });
+  options = { ...options, diagnostic };
+  if (args.command === 'diagnose') {args.diagnosticId = `diag_${crypto.randomUUID()}`;}
+  let runtime;
+  try {
+    runtime = resolveRuntime({ ...options, runtimePath: args.runtimePath, manifestPath: args.manifestPath, developmentRuntime: args.developmentRuntime === true });
+  } catch (error) {
+    diagnostic('error', 'runtime_unavailable', { command: args.command, component: 'node', errorCode: error.code || 'AGENT_RUNTIME_NOT_AVAILABLE' });
+    if (!['doctor', 'diagnose'].includes(args.command)) {throw error;}
+    if (args.command === 'diagnose') {
+      const correlation = parseDiagnosticSession(args.diagnosticSession);
+      writeDiagnosticSummary(args, {
+        diagnosticId: args.diagnosticId,
+        diagnosticsDir,
+        diagnosticSession: correlation?.sessionId,
+        diagnosticAppType: correlation?.appType,
+      }, [{ type: 'diagnostic', ready: false, phase: 'connection', runtime: { installed: false, code: error.code }, providers: [], findings: [{ severity: 'error', code: 'RUNTIME_NOT_AVAILABLE', action: 'INSTALL_OR_UPDATE_OPENYIDA' }] }], stdout);
+      return;
+    }
+    stdout.write(JSON.stringify({ ...providerCheck, type: 'doctor', providerReady: providerCheck.ready, ready: false, authKnown: providerCheck.providers.some(p => p.authKnown), runtime: { installed: false, code: error.code } }) + '\n');
+    return;
+  }
+  if (args.command === 'doctor') {
+    stdout.write(JSON.stringify({ ...providerCheck, type: 'doctor', providerReady: providerCheck.ready,
+      readyForEnrollment: providerCheck.readyForEnrollment, ready: false, providerAcceptanceRequired: true,
+      runtime: { installed: true } }) + '\n');
+    return;
+  }
+  // An unsigned development Runtime still uses the same installation and
+  // per-organization Connection state as a production Runtime. Without this
+  // preparation Go rejects `connect` before it can create an enrollment because
+  // its state store correctly requires an installation identity.
+  const managedConnections = options.disableConnectionManager !== true;
+  let config = buildLaunchConfig(args, { ...options, allowStoredConnections: managedConnections && args.command === 'run' });
+  if (providerCheck) {
+    // Inventory includes signed-out CLIs. Runtime reports their auth status;
+    // the control plane independently enforces task readiness.
+    config.providers = providerCheck.providers.filter(p => p.registrable).map(p => ({
+      profileId: 'openyida.' + p.provider, provider: p.provider, executable: p.executable,
+    }));
+  }
+  if (managedConnections && args.command === 'connect') {
+    const prepared = prepareConnection(config.stateDir, config.enrollmentToken);
+    config = { ...config, stateDir: prepared.stateDir, installationId: prepared.installationId };
+  }
+  if (managedConnections && ['run', 'diagnose', 'status', 'disconnect', 'logout'].includes(args.command)) {
+    const connections = listConnections(config.stateDir);
+    const diagnosticResults = [];
+    const diagnosticWriter = {write(value) {
+      try {diagnosticResults.push(JSON.parse(String(value)));} catch { /* Runtime output is validated by launchRuntime. */ }
+    }};
+    if (connections.length === 0) {
+      // Development `status` has historically been a no-side-effect Runtime
+      // probe before the first enrollment. Keep that useful empty-state
+      // diagnostic while requiring a real Connection for all mutations/runs.
+      if (args.command === 'diagnose' || args.developmentRuntime === true && args.command === 'status') {
+        await launchRuntime(runtime, config, { ...options, stdout: args.command === 'diagnose' ? diagnosticWriter : stdout });
+        if (args.command === 'diagnose') {writeDiagnosticSummary(args, config, diagnosticResults, stdout);}
+        return;
+      }
+      throw new CliError(t('agent.identity_invalid'), { code: 'AGENT_CONNECTION_NOT_FOUND' });
+    }
+    // Bundle preparation performs synchronous filesystem work. Finish it before
+    // spawning children so their launch-config stdin can flush without blocking.
+    const preparedConnections = connections.map((connection) => {
+      const connectionConfig = {
+        ...config,
+        stateDir: connection.stateDir,
+        installationId: connection.installationId,
+        endpoint: connection.endpoint,
+        endpointId: connection.endpointId,
+      };
+      return args.command === 'run'
+        ? materializeBundle(runtime, connectionConfig, options)
+        : { runtime, config: connectionConfig };
+    });
+    if (args.command === 'run') {
+      // Re-online mirrors connect: each Connection's serving loop runs as its own
+      // detached background daemon and the terminal returns immediately, persisting
+      // until `disconnect`. Organization Connections are independent security and
+      // execution domains, so one failing to launch must not take the others
+      // offline; only an all-Connection failure is fatal.
+      const results = await Promise.allSettled(preparedConnections.map((prepared, index) => {
+        const runConfig = { ...prepared.config, command: 'run' };
+        return launchBackgroundRuntime(prepared.runtime, runConfig, { ...options, stdout }).then((background) => {
+          stdout.write(`${JSON.stringify({
+            type: 'connected', background: true,
+            connectionId: connections[index].connectionId, endpointId: connections[index].endpointId,
+            stateDir: runConfig.stateDir, logPath: background.logPath,
+          })}\n`);
+        });
+      }));
+      const failures = results
+        .map((result, index) => ({ result, connection: connections[index] }))
+        .filter(({ result }) => result.status === 'rejected');
+      for (const { result, connection } of failures) {
+        diagnostic('error', 'connection_runtime_failed', {
+          command: args.command,
+          component: 'node',
+          connectionId: connection.connectionId,
+          endpointId: connection.endpointId,
+          errorCode: result.reason?.code || 'RUNTIME_ACTION_FAILED',
+        });
+      }
+      if (failures.length === preparedConnections.length) {throw failures[0].result.reason;}
+      return;
+    }
+    // status/disconnect/logout/diagnose stay in the foreground: they are short
+    // queries or graceful stops that must report their result to this terminal.
+    const upstreamSignals = options.signals || process;
+    const supervisorSignals = new EventEmitter();
+    // Each Connection owns one Go child and therefore one pair of signal
+    // listeners. Multi-organization installations can legitimately exceed the
+    // EventEmitter default of ten listeners; this emitter is private and all
+    // listeners are removed when their child exits.
+    supervisorSignals.setMaxListeners(0);
+    const forwardInterrupt = () => supervisorSignals.emit('SIGINT');
+    const forwardTerminate = () => supervisorSignals.emit('SIGTERM');
+    upstreamSignals.on('SIGINT', forwardInterrupt);
+    upstreamSignals.on('SIGTERM', forwardTerminate);
+    const launches = preparedConnections.map((prepared) => launchRuntime(prepared.runtime, prepared.config, {
+      ...options, stdout: args.command === 'diagnose' ? diagnosticWriter : stdout, signals: supervisorSignals,
+    }));
+    try {
+      await Promise.all(launches);
+    } catch (error) {
+      supervisorSignals.emit('SIGTERM');
+      await Promise.allSettled(launches);
+      throw error;
+    } finally {
+      upstreamSignals.removeListener('SIGINT', forwardInterrupt);
+      upstreamSignals.removeListener('SIGTERM', forwardTerminate);
+    }
+    if (args.command === 'diagnose') {
+      writeDiagnosticSummary(args, config, diagnosticResults, stdout);
+    }
+    return;
+  }
+  if (['connect', 'run'].includes(args.command)) {
+    const frozen = materializeBundle(runtime, config, options);
+    runtime = frozen.runtime;
+    config = frozen.config;
+  }
+  await launchRuntime(runtime, config, { ...options, stdout });
+  if (args.command === 'connect') {
+    // Pairing has completed in the foreground above. The serving loop now runs
+    // as a detached background daemon so the terminal returns immediately and
+    // the connection persists across terminal/desktop close until `disconnect`.
+    const runConfig = { ...config, command: 'run' };
+    delete runConfig.enrollmentToken;
+    const background = await launchBackgroundRuntime(runtime, runConfig, { ...options, stdout });
+    stdout.write(`${JSON.stringify({ type: 'connected', background: true, stateDir: runConfig.stateDir, logPath: background.logPath })}\n`);
+  }
+}
+
+module.exports = { parseArgs, parseDiagnosticSession, buildLaunchConfig, discoverProvider, discoverProviders, run };