openyida 2026.10.13 → 2026.10.14

package/lib/agent/managed-command-map.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const { resolveManagedPolicy } = require('../core/managed-policy');
+
+// Compatibility adapter for receipts and application checks. Scope and mutation
+// metadata come from the same manifest consumed by the invocation guard.
+function resolveManagedAppCommand(command, args = []) {
+  if (args.includes('--help') || args.includes('-h')) {return null;}
+  const selected = resolveManagedPolicy(command, args);
+  if (selected?.policy.scope !== 'app') {return null;}
+  const policy = selected.policy;
+  let target;
+  if (policy.appParser === 'prd-completeness') {
+    const { parseArgs } = require('../app/check-prd-completeness');
+    try {
+      const parsed = parseArgs(args, { strict: true });
+      if (!parsed.prdPath || !parsed.appType) {return null;}
+      target = { appType: parsed.appType };
+    } catch {return null;}
+  } else if (policy.appOption) {
+    const positions = args.flatMap((arg, index) => arg === policy.appOption ? [index] : []);
+    if (positions.length !== 1 || !args[positions[0] + 1] || args[positions[0] + 1].startsWith('-')) {return null;}
+    target = { appType: args[positions[0] + 1] };
+  } else {
+    if (policy.sourcePosition !== undefined && (!args[policy.sourcePosition] || /^APP_/i.test(args[policy.sourcePosition]) || args[policy.sourcePosition].startsWith('-'))) {return null;}
+    target = { appPosition: policy.appPosition };
+  }
+  const mutation = policy.mutation;
+  return { ...target, ...(mutation ? { operation: mutation.operation,
+    ...(mutation.formUuidPosition !== undefined ? { formUuid: values => values[mutation.formUuidPosition] }
+      : mutation.formUuidOption ? { formUuid: values => {
+        const positions = values.flatMap((value, index) => value === mutation.formUuidOption ? [index] : []);
+        return positions.length === 1 && values[positions[0] + 1] && !values[positions[0] + 1].startsWith('-')
+          ? values[positions[0] + 1] : undefined;
+      } } : {}) } : {}) };
+}
+
+function classifyManagedMutation(command, args = []) {
+  const entry = resolveManagedAppCommand(command, args);
+  const policy = resolveManagedPolicy(command, args)?.policy;
+  if (policy?.mutation?.requiredFlags?.some(flag => !args.includes(flag)) || policy?.mutation?.forbiddenFlags?.some(flag => args.includes(flag))) {return null;}
+  return entry?.operation
+    ? { operation: entry.operation, ...(entry.formUuid ? { formUuid: entry.formUuid(args) } : {}) }
+    : null;
+}
+
+module.exports = { resolveManagedAppCommand, classifyManagedMutation };

package/lib/agent/managed-context.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const { CliError } = require('../core/cli-error');
+const { t } = require('../core/i18n');
+
+function managedError(code, key, details = {}) {
+  return new CliError(t(`agent.${key}`), { code, details: { ...details, retryable: false } });
+}
+
+// Supplied only by the Go-owned attempt launcher. The fixed-value task grant has
+// a server-managed lease and is app-scoped by Tianshu; ordinary OpenYida profiles
+// are never consulted and Node cannot renew the task grant.
+function readManagedContext(env = process.env) {
+  if (env.OPENYIDA_MANAGED_RUN !== '1') {return null;}
+  const context = {
+    appType: env.OPENYIDA_AGENT_APP_TYPE,
+    corpId: env.OPENYIDA_AGENT_CORP_ID,
+    userId: env.OPENYIDA_AGENT_USER_ID,
+    runId: env.OPENYIDA_AGENT_RUN_ID,
+    attemptId: env.OPENYIDA_AGENT_ATTEMPT_ID,
+    formUuid: env.OPENYIDA_AGENT_FORM_UUID || null,
+    baseUrl: env.OPENYIDA_AGENT_BASE_URL,
+    taskGrant: env.OPENYIDA_AGENT_TASK_GRANT,
+  };
+  let parsed;
+  try {parsed = new URL(context.baseUrl);} catch {parsed = null;}
+  if (!/^APP_[a-zA-Z0-9_-]{1,200}$/.test(context.appType || '') ||
+      ['corpId', 'userId', 'runId', 'attemptId'].some(key => typeof context[key] !== 'string' || !context[key] || context[key].length > 512 || /\s/.test(context[key]) || [...context[key]].some(char => char.charCodeAt(0) < 32)) ||
+      !parsed || parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.search || parsed.hash ||
+      typeof context.taskGrant !== 'string' || context.taskGrant.length < 16 || context.taskGrant.length > 4096 || /\s/.test(context.taskGrant)) {
+    throw managedError('MANAGED_CONTEXT_INVALID', 'managed_context_invalid');
+  }
+  if (context.formUuid !== null && (context.formUuid.length > 256 || !/^(?:FORM|REPORT)-[a-zA-Z0-9_-]+$/.test(context.formUuid))) {
+    throw managedError('MANAGED_CONTEXT_INVALID', 'managed_context_invalid');
+  }
+  context.baseUrl = context.baseUrl.replace(/\/+$/, '');
+  return context;
+}
+
+module.exports = { readManagedContext, managedError };

package/lib/agent/managed-run.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const { readManagedContext, managedError } = require('./managed-context');
+const { resolveManagedAppCommand } = require('./managed-command-map');
+const { resolveManagedPolicy } = require('../core/managed-policy');
+
+const IDENTITY_OPTIONS = new Set([
+  '--profile', '--auth-profile', '--corp-id', '--user-id', '--client-id', '--endpoint', '--base-url',
+  '--env', '--public', '--intl', '--international', '--overseas', '--global', '--yidaapps', '--alibaba',
+  '--access-token', '--refresh-token', '--token', '--auth-dir', '--app-type', '--appType', '--app_type',
+  '--system-token-app', '--connector-system-token-app',
+]);
+const HELP_OPTIONS = new Set(['--help', '-h', '--json', '--quiet']);
+
+function resolveManagedHelp(command, args = [], options = {}) {
+  if (command === 'agent' && args.length === 2 && args[0] === 'ask-human' && ['--help', '-h'].includes(args[1])) {
+    return [require('./ask-human-help')];
+  }
+  const topLevel = command === '--help' || command === '-h';
+  const helpFlags = [command, ...args].filter(arg => arg === '--help' || arg === '-h');
+  if (helpFlags.length !== 1 || typeof command !== 'string') {return null;}
+  const flags = args.filter(arg => HELP_OPTIONS.has(arg));
+  if (new Set(flags).size !== flags.length || args.some(arg => arg.startsWith('-') && !HELP_OPTIONS.has(arg))) {return null;}
+  const path = topLevel ? [] : [command, ...args.filter(arg => !HELP_OPTIONS.has(arg))];
+  if (topLevel && args.some(arg => !HELP_OPTIONS.has(arg))) {return null;}
+  const manifest = require('../core/command-manifest').buildCommandManifest(options);
+  const entries = manifest.commands.filter(entry => path.length <= entry.path.length &&
+    path.every((token, index) => /^[a-z][a-z0-9-]*$/.test(token) && token === entry.path[index]));
+  return entries.length ? entries : null;
+}
+
+function assertManagedInvocation(command, args = [], options = {}) {
+  const context = readManagedContext(options.env || process.env);
+  if (!context) {return null;}
+  // Before global flags, auto-update, and command modules with side effects.
+  const declared = resolveManagedPolicy(command, args);
+  const scopeOptions = declared?.policy.appOption ? [declared.policy.appOption] : command === 'check-prd-completeness'
+    ? require('../app/check-prd-completeness').APP_TYPE_OPTIONS : [];
+  if (args.some(value => {
+    const option = String(value).split('=')[0];
+    return IDENTITY_OPTIONS.has(option) && !scopeOptions.includes(option);
+  })) {
+    throw managedError('MANAGED_OVERRIDE_FORBIDDEN', 'managed_override_forbidden');
+  }
+  if ([command, ...args].some(arg => arg === '--help' || arg === '-h')) {
+    if (resolveManagedHelp(command, args)) {return context;}
+    throw managedError('MANAGED_COMMAND_UNSUPPORTED', 'managed_command_unsupported');
+  }
+  if (['--version', '-v'].includes(command)) {return context;}
+  const selected = resolveManagedPolicy(command, args);
+  const unsupported = reason => {
+    throw managedError('MANAGED_COMMAND_UNSUPPORTED', 'managed_command_unsupported', {
+      ...(selected ? { commandId: selected.entry.id } : {}), reason,
+    });
+  };
+  if (!selected) {unsupported('command_or_action_unknown');}
+  const { policy, policyArgs } = selected;
+  if (policy.scope === 'denied') {unsupported(policy.reason);}
+  if (policy.scope === 'local') {
+    if (policy.allowedFlags && (policyArgs.some(arg => !policy.allowedFlags.includes(arg)) ||
+        new Set(policyArgs).size !== policyArgs.length || policy.requiredFlags?.some(flag => !policyArgs.includes(flag)))) {
+      unsupported('arguments_outside_declared_scope');
+    }
+    return context;
+  }
+  if (policy.scope === 'selected_input') {
+    let inputs;
+    try {inputs = JSON.parse((options.env || process.env).OPENYIDA_AGENT_INPUT_REFS || '[]');} catch {inputs = null;}
+    const selectedInput = Array.isArray(inputs) && inputs.some(input => input.type === policy.inputType && input[policy.inputField] === policyArgs[0]);
+    if (!selectedInput || policyArgs.length > 2 || (policyArgs[1] !== undefined && policyArgs[1] !== '--json')) {
+      unsupported('input_not_selected_or_arguments_invalid');
+    }
+    return context;
+  }
+  const entry = resolveManagedAppCommand(command, args);
+  if (!entry) {unsupported('application_target_unresolved');}
+  const appType = entry.appType === undefined ? args[entry.appPosition] : entry.appType;
+  if (appType !== context.appType || (entry.appPosition !== undefined && args.slice(0, entry.appPosition).some(arg => arg.startsWith('-')))) {
+    throw managedError('MANAGED_APP_MISMATCH', 'managed_app_mismatch');
+  }
+  return context;
+}
+
+module.exports = { assertManagedInvocation, resolveManagedHelp };

package/lib/agent/mutation-receipt.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+const APP_TYPE = /^APP_[A-Za-z0-9_-]{1,200}$/;
+const { classifyManagedMutation } = require('./managed-command-map');
+
+function safeText(value, max = 256) {
+  return typeof value === 'string' && value.trim() && value.length <= max ? value.trim() : undefined;
+}
+
+function resourceId(...values) {
+  return values.map((value) => safeText(value, 128)).find((value) => value && ID.test(value));
+}
+
+function safeOutput(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {return null;}
+  return value;
+}
+
+/**
+ * Captures only successful JSON result metadata for a Runtime-managed command.
+ * Console output is preserved byte-for-byte; ordinary OpenYida invocations are untouched.
+ */
+function beginManagedMutationCapture({ command, args, env = process.env, consoleObject = console, eventId } = {}) {
+  const classification = classifyManagedMutation(command, args);
+  const appType = env.OPENYIDA_AGENT_APP_TYPE;
+  const active = env.OPENYIDA_MANAGED_RUN === '1' && classification && ID.test(eventId || '') && APP_TYPE.test(appType || '');
+  if (!active) {return { commit: () => null, discard: () => undefined };}
+
+  const original = consoleObject.log;
+  let latest = null;
+  let explicitFailure = false;
+  let restored = false;
+  consoleObject.log = function managedMutationConsoleLog(...values) {
+    try {
+      const text = values.length === 1 && typeof values[0] === 'string' ? values[0].trim() : '';
+      if (text.startsWith('{') && text.endsWith('}') && text.length <= 64 * 1024) {
+        const parsed = safeOutput(JSON.parse(text));
+        if (parsed?.success === false) {explicitFailure = true;}
+        if (parsed?.success === true) {latest = parsed;}
+      }
+    } catch { /* CLI output is not a protocol unless it is valid allowlisted JSON. */ }
+    return original.apply(this, values);
+  };
+  const restore = () => {
+    if (!restored) {consoleObject.log = original;}
+    restored = true;
+  };
+  return {
+    commit() {
+      restore();
+      if (explicitFailure || !latest) {return null;}
+      const isReport = command === 'create-report' || command === 'append-chart';
+      const formUuid = resourceId(latest?.formUuid, latest?.pageId,
+        isReport ? latest?.reportId : undefined, classification.formUuid);
+      const pageType = safeText(latest?.pageType, 64) || (isReport ? 'report' : undefined);
+      const updatedFields = safeOutput(latest?.updatedFields);
+      const appName = safeText(latest?.appName || updatedFields?.name);
+      const appIcon = safeText(latest?.appIcon || updatedFields?.icon);
+      const colour = safeText(latest?.colour || updatedFields?.colour, 64);
+      const receipt = {
+        schemaVersion: 'openyida.mutation.v1',
+        eventId,
+        source: 'openyida-cli',
+        operation: classification.operation,
+        status: 'succeeded',
+        appType,
+        ...(formUuid ? { formUuid } : {}),
+        ...(pageType ? { pageType } : {}),
+        ...(appName ? { appName } : {}),
+        ...(appIcon ? { appIcon } : {}),
+        ...(colour ? { colour } : {}),
+        ...(safeText(latest?.formName || latest?.formTitle || latest?.pageName || (isReport && latest?.reportTitle)) ? { formName: safeText(latest?.formName || latest?.formTitle || latest?.pageName || (isReport && latest?.reportTitle)) } : {}),
+        ...(safeText(latest?.schemaHash, 128) ? { schemaHash: safeText(latest.schemaHash, 128) } : {}),
+      };
+      return receipt;
+    },
+    discard: restore,
+  };
+}
+
+module.exports = { beginManagedMutationCapture, classifyManagedMutation };

package/lib/agent/private-directory.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { CliError } = require('../core/cli-error');
+const { t } = require('../core/i18n');
+
+function directoryError() {
+  return new CliError(t('agent.private_directory_failed'), { code: 'AGENT_PRIVATE_DIRECTORY_INVALID' });
+}
+
+// Node's mkdir mode is ignored on Windows. Create each missing directory with
+// an inheritable private DACL before any credentials or logs are written.
+// Existing directories are never re-permissioned here.
+function mkdirPrivate(directory) {
+  if (process.platform !== 'win32') {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    return;
+  }
+  const target = path.resolve(directory);
+  const missing = [];
+  let ancestor = target;
+  while (!fs.existsSync(ancestor)) {
+    missing.unshift(ancestor);
+    ancestor = path.dirname(ancestor);
+  }
+  for (let parent = ancestor; ; parent = path.dirname(parent)) {
+    const stat = fs.lstatSync(parent);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {throw directoryError();}
+    if (parent === path.dirname(parent)) {break;}
+  }
+  if (!missing.length) {return;}
+  const script = `
+$ErrorActionPreference = 'Stop'
+$identity = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$acl = New-Object System.Security.AccessControl.DirectorySecurity
+$acl.SetOwner($identity)
+$acl.SetAccessRuleProtection($true, $false)
+foreach ($sid in @($identity.Value, 'S-1-5-18', 'S-1-5-32-544')) {
+  $principal = New-Object System.Security.Principal.SecurityIdentifier($sid)
+  $rule = New-Object System.Security.AccessControl.FileSystemAccessRule($principal, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
+  $acl.AddAccessRule($rule)
+}
+foreach ($directory in ($env:OPENYIDA_PRIVATE_DIRECTORIES | ConvertFrom-Json)) {
+  if ([System.IO.Directory]::Exists($directory)) {throw 'Directory changed during creation'}
+  [System.IO.Directory]::CreateDirectory($directory, $acl) | Out-Null
+}
+`;
+  try {
+    execFileSync(path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+      ['-NoProfile', '-NonInteractive', '-Command', script], {
+        windowsHide: true, timeout: 15000, stdio: 'pipe',
+        env: { ...process.env, OPENYIDA_PRIVATE_DIRECTORIES: JSON.stringify(missing) },
+      });
+  } catch {
+    throw directoryError();
+  }
+  const stat = fs.lstatSync(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {throw directoryError();}
+}
+
+module.exports = { mkdirPrivate };

package/lib/agent/provider-preflight.js

@@ -0,0 +1,257 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, execFile } = require('child_process');
+const { runtimeEnvironment } = require('./stdio');
+const { t } = require('../core/i18n');
+
+const PROVIDERS = require('./providers');
+const DOCS = {
+  qoder: 'https://docs.qoder.com/cli/installation',
+  codex: 'https://developers.openai.com/codex/cli/',
+  opencode: 'https://opencode.ai/docs/',
+};
+
+function exists(file) {
+  try { return fs.statSync(file).isFile(); } catch { return false; }
+}
+
+// Finite installation locations only; never recursively search a user's disk.
+function installationPaths(env, platform, home) {
+  const join = path.join;
+  const bin = home ? ['.local/bin', '.qoder/bin', '.codex/bin', '.opencode/bin'].map(p => join(home, p)) : [];
+  const desktop = { qoder: [], codex: [], opencode: [] };
+  const bundled = { qoder: [], codex: [], opencode: [] };
+  if (platform === 'win32') {
+    if (env.APPDATA) { bin.push(join(env.APPDATA, 'npm')); }
+    if (env.LOCALAPPDATA) {
+      desktop.qoder.push(join(env.LOCALAPPDATA, 'Programs/Qoder/Qoder.exe'));
+      desktop.codex.push(join(env.LOCALAPPDATA, 'OpenAI/Codex/Codex.exe'));
+      const root = join(env.LOCALAPPDATA, 'OpenAI/Codex/bin');
+      try {
+        const versions = fs.readdirSync(root, { withFileTypes: true }).filter(d => d.isDirectory())
+          .map(d => join(root, d.name, 'codex.exe')).filter(exists)
+          .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs).slice(0, 8);
+        bundled.codex.push(...versions);
+      } catch { /* Desktop CLI is optional. */ }
+    }
+    if (env.ProgramFiles) { desktop.qoder.push(join(env.ProgramFiles, 'Qoder/Qoder.exe')); }
+  } else if (platform === 'darwin') {
+    bin.push('/opt/homebrew/bin', '/usr/local/bin');
+    for (const root of ['/Applications', ...(home ? [join(home, 'Applications')] : [])]) {
+      desktop.qoder.push(join(root, 'Qoder.app/Contents/MacOS/Qoder'));
+      desktop.qoder.push(join(root, 'QoderWork.app/Contents/MacOS/QoderWork'));
+      desktop.codex.push(join(root, 'Codex.app/Contents/MacOS/Codex'));
+      desktop.codex.push(join(root, 'ChatGPT.app/Contents/MacOS/ChatGPT'));
+      bundled.qoder.push(join(root, 'Qoder.app/Contents/Resources/bin/qodercli'));
+      bundled.qoder.push(join(root, 'QoderWork.app/Contents/Resources/bin/qodercli'));
+      for (const app of ['Codex.app', 'ChatGPT.app']) {
+        const resources = join(root, app, 'Contents/Resources');
+        // Prefer the bundled native CLI; the bin entry is an optional shell launcher.
+        bundled.codex.push(join(resources, 'codex-cli/CodexCLI.app/Contents/MacOS/codex'));
+        bundled.codex.push(join(resources, 'codex'));
+        bundled.codex.push(join(resources, 'codex-cli/bin/codex'));
+      }
+    }
+  } else {
+    bin.push('/usr/local/bin', '/usr/bin');
+    desktop.qoder.push('/opt/Qoder/qoder', '/opt/qoder/qoder');
+    if (home) { desktop.qoder.push(join(home, '.local/share/applications/qoder.desktop')); }
+  }
+  return { bin, desktop, bundled };
+}
+
+function inventory(env = process.env, platform = process.platform, home = env.HOME || env.USERPROFILE || (env === process.env ? os.homedir() : '')) {
+  const locations = installationPaths(env, platform, home);
+  const paths = (env.PATH || env.Path || env.path || '').split(platform === 'win32' ? ';' : ':')
+    .map(p => p.replace(/^"(.*)"$/, '$1')).filter(p => p && path.isAbsolute(p));
+  const extensions = platform === 'win32' ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';').map(e => e.toLowerCase()) : [''];
+  return PROVIDERS.map(provider => {
+    const candidates = [];
+    const desktopExecutables = locations.desktop[provider].map(candidate => {
+      try { return fs.realpathSync(candidate); } catch { return path.resolve(candidate); }
+    });
+    for (const name of provider === 'qoder' ? ['qodercli', 'qoder'] : [provider]) {
+      for (const dir of [...paths, ...locations.bin]) {
+        for (const ext of extensions) { candidates.push(path.join(dir, name + ext)); }
+      }
+    }
+    candidates.push(...locations.bundled[provider]);
+    const found = [];
+    for (const candidate of candidates) {
+      try {
+        const resolved = fs.realpathSync(candidate);
+        // A GUI binary is not a CLI, even when its directory appears on PATH.
+        if (desktopExecutables.some(p => p.toLowerCase() === resolved.toLowerCase())) { continue; }
+        fs.accessSync(resolved, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+        if (fs.statSync(resolved).isFile() && !found.includes(resolved)) { found.push(resolved); }
+      } catch { /* Missing candidates are normal. */ }
+    }
+    return { provider, desktopDetected: locations.desktop[provider].some(exists) || locations.bundled[provider].some(exists), candidates: found };
+  });
+}
+
+function discoverProviders(env = process.env, platform = process.platform, home) {
+  return inventory(env, platform, home).filter(p => p.candidates.length).map(p => ({
+    profileId: `openyida.${p.provider}`, provider: p.provider, executable: p.candidates[0],
+  }));
+}
+
+function powerShellLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+// Match the Go Runtime's npm launcher handling without cmd.exe interpolation.
+function probeCommand(executable, args, platform = process.platform, env = process.env) {
+  if (platform !== 'win32' || !/\.(cmd|bat)$/i.test(executable)) { return { executable, args }; }
+  const script = executable.replace(/\.(cmd|bat)$/i, '.ps1');
+  if (!exists(script)) { throw new Error('npm launcher has no PowerShell sibling; select a native CLI'); }
+  const command = `& ${[script, ...args].map(powerShellLiteral).join(' ')}`;
+  return { executable: path.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe'),
+    args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', command] };
+}
+
+// No prompts, model calls, login flows or provider output enter our report.
+function probe(executable, args, rpc, options = {}) {
+  const env = runtimeEnvironment(options.env || process.env);
+  const platform = options.platform || process.platform;
+  return new Promise(resolve => {
+    const signals = options.signals || process;
+    const interrupted = () => { stop(); finish({ status: 'probe_cancelled' }); };
+    let child, timer, finished = false, output = '', pending = '', result;
+    function stop() {
+      if (!child || !child.pid) { return; }
+      if (platform === 'win32') {
+        execFile(path.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32/taskkill.exe'),
+          ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, timeout: 3000 }, () => {});
+      } else {
+        try { process.kill(-child.pid, 'SIGKILL'); } catch { child.kill('SIGKILL'); }
+      }
+    }
+    function finish(value) {
+      if (finished) { return; }
+      finished = true;
+      clearTimeout(timer);
+      signals.removeListener('SIGINT', interrupted);
+      signals.removeListener('SIGTERM', interrupted);
+      resolve(value);
+    }
+    try {
+      const command = probeCommand(executable, args, platform, env);
+      child = (options.probeSpawn || spawn)(command.executable, command.args, {
+        env, cwd: os.tmpdir(), shell: false, windowsHide: true,
+        windowsVerbatimArguments: command.windowsVerbatimArguments,
+        detached: platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      signals.once('SIGINT', interrupted);
+      signals.once('SIGTERM', interrupted);
+      timer = setTimeout(() => { stop(); finish({ status: 'probe_timeout' }); }, options.timeoutMs || 15000);
+      child.on('error', () => finish({ status: 'launch_failed' }));
+      child.stdin.on('error', () => {});
+      child.stderr.on('data', chunk => { output = (output + chunk.toString()).slice(-65536); });
+      child.stdout.on('data', chunk => {
+        output = (output + chunk.toString()).slice(-65536);
+        if (!rpc || result) { return; }
+        pending += chunk.toString();
+        if (pending.length > 262144) { stop(); finish({ status: 'protocol_unsupported' }); return; }
+        let end;
+        while ((end = pending.indexOf('\n')) >= 0) {
+          const line = pending.slice(0, end); pending = pending.slice(end + 1);
+          try {
+            const message = JSON.parse(line);
+            if (message.id !== 1) { continue; }
+            const valid = rpc === 'qoder' ? message.result?.protocolVersion === 1 : typeof message.result?.userAgent === 'string';
+            result = { status: valid ? 'passed' : isLoginRequired(message.error?.message) ? 'login_required' : 'protocol_unsupported' };
+            stop();
+            finish(result);
+          } catch { /* Ignore non-protocol startup banners. */ }
+        }
+      });
+      child.on('close', code => finish(result || { status: rpc ? 'protocol_unsupported' : code === 0 ? 'passed' : 'probe_failed', output }));
+      if (rpc) {
+        const params = rpc === 'qoder'
+          ? { protocolVersion: 1, clientCapabilities: {}, clientInfo: { name: 'openyida-preflight', version: '1' } }
+          : { clientInfo: { name: 'openyida-preflight', version: '1' }, capabilities: {} };
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params }) + '\n');
+      } else { child.stdin.end(); }
+    } catch { finish({ status: 'launch_failed' }); }
+  });
+}
+
+function isLoginRequired(output) {
+  return /\bnot logged in\b|\bnot authenticated\b|\bplease (?:log|sign) in\b/i.test(output || '');
+}
+
+async function checkProvider(provider, executable, options) {
+  const execute = options.probe || probe;
+  const version = await execute(executable, ['--version'], null, options);
+  if (version.status !== 'passed') { return { status: version.status, cliDetected: false }; }
+  // Installation evidence is independent of authentication/protocol readiness.
+  // Apply this consistently to every enabled provider, including future adapters.
+  const detected = { cliDetected: true };
+  if (provider === 'opencode') { return { ...detected, status: 'available', authKnown: false, protocolProbe: 'not_run' }; }
+  const protocol = await execute(executable, provider === 'qoder' ? ['--acp'] : ['app-server', '--listen', 'stdio://'], provider, options);
+  if (protocol.status === 'login_required') {
+    return { ...detected, status: 'login_required', authKnown: true, protocolProbe: 'login_required' };
+  }
+  if (protocol.status !== 'passed') { return { ...detected, status: protocol.status === 'probe_failed' ? 'protocol_unsupported' : protocol.status }; }
+  const auth = await execute(executable, provider === 'qoder' ? ['--list-models'] : ['login', 'status'], null, options);
+  if (isLoginRequired(auth.output)) {
+    return { ...detected, status: 'login_required', authKnown: true, protocolProbe: 'passed' };
+  }
+  return { ...detected, status: auth.status === 'passed' ? 'ready' : auth.status, authKnown: auth.status === 'passed', protocolProbe: 'passed' };
+}
+
+function remediation(provider) {
+  return {
+    action: 'INFORMATION_ONLY',
+    requiresExplicitUserRequest: true,
+    automaticActionAllowed: false,
+    documentationUrl: DOCS[provider],
+    providerPathOption: `--provider ${provider} --provider-path <absolute-cli-path>`,
+    retry: 'repeat_original_connect_command',
+    verifyCommand: 'openyida agent doctor --json',
+  };
+}
+
+async function preflight(args, options = {}) {
+  const platform = options.platform || process.platform;
+  const entries = args.provider && !PROVIDERS.includes(args.provider) ? [] : args.providerPath ? [{ provider: args.provider, candidates: [args.providerPath], desktopDetected: false }]
+    : inventory(options.env || process.env, platform, options.homedir).filter(p => !args.provider || p.provider === args.provider);
+  const providers = await Promise.all(entries.map(async entry => {
+    let result = { status: 'cli_not_found', cliDetected: false }, executable, discovered;
+    // Try a small number of installations; a stale PATH entry must not hide a working bundled CLI.
+    // Windows npm shims start PowerShell and Node for each of the three checks.
+    // A healthy cold CLI can take more than 15 seconds for a single handshake.
+    const timeoutMs = options.timeoutMs || (platform === 'win32' ? 45000 : 15000);
+    const deadline = Date.now() + (options.budgetMs || (platform === 'win32' ? 135000 : 30000));
+    const boundedProbe = async (exe, flags, rpc, opts) => {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) { return { status: 'probe_timeout' }; }
+      return (options.probe || probe)(exe, flags, rpc, { ...opts, timeoutMs: Math.min(timeoutMs, remaining) });
+    };
+    for (const candidate of entry.candidates.slice(0, 4)) {
+      executable = candidate;
+      result = await checkProvider(entry.provider, executable, { ...options, probe: boundedProbe });
+      if (result.cliDetected && !discovered) { discovered = { result, executable }; }
+      if (Date.now() >= deadline || ['ready', 'available', 'login_required', 'probe_cancelled'].includes(result.status)) { break; }
+    }
+    if (!result.cliDetected && result.status !== 'probe_cancelled' && discovered) {
+      ({ result, executable } = discovered);
+    }
+    const usable = ['ready', 'available'].includes(result.status);
+    const registrable = result.cliDetected && result.status !== 'probe_cancelled';
+    return { provider: entry.provider, desktopDetected: entry.desktopDetected, executable, ...result, usable, registrable,
+      message: t(`agent.preflight_${result.status}`),
+      ...(!usable ? { remediation: remediation(entry.provider) } : {}),
+    };
+  }));
+  return { schemaVersion: 1, type: 'preflight', platform, ready: providers.some(p => p.usable) && !providers.some(p => p.status === 'probe_cancelled'),
+    readyForEnrollment: providers.some(p => p.registrable) && !providers.some(p => p.status === 'probe_cancelled'),
+    paidPromptExecuted: false, advisoryOnly: true, automaticInstallAllowed: false,
+    guidance: t('agent.preflight_advisory'), providers };
+}
+
+module.exports = { discoverProviders, inventory, installationPaths, probeCommand, probe, preflight };

package/lib/agent/providers.js

@@ -0,0 +1,4 @@
+'use strict';
+
+// Public Local Agent rollout. Other adapters remain implemented but unadvertised.
+module.exports = Object.freeze(['qoder', 'codex']);

package/lib/agent/runtime-catalog.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": 1,
+  "keys": {
+    "openyida-runtime-public-beta-20260923-1": {
+      "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEApl2Q+64rX997KxEQUY2yU8Xnc7sM3NRQ8Nf0bAi9Hck=\n-----END PUBLIC KEY-----\n"
+    }
+  },
+  "releases": [
+    {
+      "platform": "darwin",
+      "arch": "arm64",
+      "packageName": "@openyida/local-agent-runtime-darwin-arm64",
+      "packageVersion": "0.1.1",
+      "runtimeVersion": "0.1.1",
+      "manifestSha256": "7f3d8e2596210b50db6b664db902f1036a1d51a87fd80e298a50d337d6a44205"
+    },
+    {
+      "platform": "darwin",
+      "arch": "x64",
+      "packageName": "@openyida/local-agent-runtime-darwin-x64",
+      "packageVersion": "0.1.1",
+      "runtimeVersion": "0.1.1",
+      "manifestSha256": "e4922eaff8f0000737ede59a7beeb30f88c8a2c97f7a93c871bfe9938d16dc3d"
+    },
+    {
+      "platform": "win32",
+      "arch": "x64",
+      "packageName": "@openyida/local-agent-runtime-win32-x64",
+      "packageVersion": "0.1.1",
+      "runtimeVersion": "0.1.1",
+      "manifestSha256": "3f18fd2f73870e96af8d6eab8edb7594575cf870f90ac9cf1d1506f03f854023"
+    },
+    {
+      "platform": "win32",
+      "arch": "arm64",
+      "packageName": "@openyida/local-agent-runtime-win32-arm64",
+      "packageVersion": "0.1.1",
+      "runtimeVersion": "0.1.1",
+      "manifestSha256": "0af4afe0bb61466e702500609948b0c3ad24546fe2f80de31cf20ff86ad87266"
+    }
+  ]
+}