openyida 2026.10.13-1 → 2026.10.14

package/README.md

@@ -158,7 +158,6 @@ The agent can then call OpenYida commands to create the application, generate so
 | [Codex](https://openai.com/codex/) | Full support |
 | [Claude Code](https://claude.ai/code) | Full support |
 | [MuleRun](https://mulerun.com) | Full support |
-| [OpenCode](https://opencode.ai) | Full support |
 | [Cursor](https://cursor.com/) | Full support |
 | [Visual Studio Code](https://code.visualstudio.com/) | Full support |
 | QwenWork（千问办公） | Full support |
@@ -565,6 +564,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 |---------|-------------|
 | `openyida commands [--json]` | Output machine-readable command manifest |
 | `openyida agent-capabilities [--json] [--summary-json\|--compact]` | Output one-shot agent capability snapshot |
+| `openyida agent <doctor\|diagnose\|status\|connect\|run\|disconnect\|logout\|logs> [options]` | Connect a local Agent (Go runtime, development preview) |
 | `openyida a2a <serve\|agent-card> [options]` | Start local read-only A2A adapter or print Agent Card |
 | `openyida bridge start [--token <pair-token>] [--port 6736] [--origin https://demo.aliwork.com] [--open\|--no-open]` | Start OpenYida local web bridge service |
 | `openyida copy [--force]` | Copy project working directory |
@@ -633,6 +633,31 @@ Form field definitions can include `alias` or `componentAlias` to populate Yida
 
 `openyida integration create` supports form events (`insert`, `update`, `delete`, `comment`) and approval events (`processFinish`, `activityTask`; aliases: `approval`, `approvalNode`). Approval events require `--approval-actions agree,disagree,terminated`; `activityTask` also requires `--approval-node-ids <nodeId,...>`. Passing `--process-code` selects a full graph replacement and now requires explicit `--replace`; it is not a safe update. `integration update` currently performs capability detection only: because full platform `processJson` + `viewJson` readback is unproven, it writes a redacted local probe artifact and returns `PLATFORM_PROBE_REQUIRED` before authentication, spec reading, or remote writes. It does not edit a flow.
 
+### Local Agent development preview
+
+`openyida agent` is a thin Node launcher for a separately supplied Go runtime. Node does not connect to the agent service or manage provider sessions. Four signed platform packages support macOS/Windows x64 and ARM64; npm installs the package matching the current platform. Node does not discover a Go executable on `PATH` or install provider CLIs.
+
+The Local Agent Beta production allowlist contains macOS and Windows only. Linux remains supported by the ordinary OpenYida CLI and by the explicit development-runtime workflow below, but Linux Local Agent packages are not published and production `connect`/`run` are rejected until native acceptance is complete.
+
+```bash
+openyida agent doctor --json
+openyida agent doctor --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json
+openyida agent connect --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json --endpoint https://agent.example.test --endpoint-id configured-platform-id
+openyida agent run --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json --endpoint https://agent.example.test --endpoint-id configured-platform-id --provider qoder --provider-path /absolute/path/qodercli
+```
+
+Development manifest v1 specifies runtime version, protocol `1`, Node-style OS/architecture names, and `binary: {file, sha256}`; it requires the explicit `--development-runtime` flag. This is an integrity check, **not a publisher signature**. The production loader requires a strictly validated v2 manifest, exact approved platform-package version/digest, and an Ed25519 signature over the original manifest bytes using trust roots bundled in the Node host. The bundled catalog pins the approved runtime version, manifest digest and signing public key. See the [launcher contract](lib/agent/PROTOCOL.md).
+
+`connect` supports two equivalent enrollment entries. CLI-first opens the Yida browser approval page and returns through a state/PKCE-protected loopback callback. Web-first copies one five-minute command containing `--enroll`; the token is single-use and carries no business authority. Neither path reads or uploads an ordinary OpenYida login profile.
+
+One installation may connect to multiple organizations. Node keeps only a shared Installation ID at the installation root; each organization authorization gets an isolated private Connection state directory, device credentials, journals, control socket, and frozen bundle. `agent connect` and `agent run` start an independent background daemon by default and return once it is ready. `status`, `logs`, `disconnect`, and `logout` enumerate valid Connections. Background mode is not boot-time autostart. Each Connection registers all locally discovered Qoder and Codex Runtimes, and the web UI selects computer, CLI, and model.
+
+For each attempt, Go injects `OPENYIDA_MANAGED_RUN=1`, the cloud user/corp/app/run/attempt context, and a fixed-value Tianshu task grant with an initial 60-minute lease. The CLI uses that grant instead of local auth and sends scope-correlation headers. While the authenticated device connection and server-side Run remain active, yida-agent can renew the same bearer server-to-server; the CLI cannot renew it and never receives a task refresh token. Tianshu independently checks the grant against the requested app and rejects application creation, identity/environment changes, cross-application requests and unsupported organization-wide operations; declared application-bound batches are supported. `formUuid` remains optional per-turn page-focus context, so one app-bound session can work across pages in that application. Without `OPENYIDA_MANAGED_RUN`, existing login, token refresh, and command behavior are unchanged.
+
+Before `connect` or `run`, Node now freezes the verified runtime bytes, CLI, full production dependency closure, and packaged Skills into a private content-addressed bundle. Source changes during copying fail closed. Existing bundles are verified, never silently repaired or garbage-collected by Node, and survive replacement/removal of the original npm directory. Go owns active/session references and version activation; the external Node executable and provider installations are not copied or managed by npm. A separate parent-watch pipe and a 15-second stop grace prevent normal config EOF from being mistaken for parent death; an unconfirmed forced stop remains unknown.
+
+This is not an OS sandbox or an authorization boundary against arbitrary shell code. Production signing/release infrastructure, full Go/provider recovery and upgrade acceptance, and OS/architecture-specific provider E2E are not claimed by these fake-process tests. Auto-update is disabled for `agent` and managed invocations; ordinary CLI commands neither spawn nor download the runtime.
+
 ## Agent Skills
 
 The `yida-skills/` directory is the source skill library used by OpenYida during development and distributed with the npm package.

package/bin/yida.js

@@ -24,6 +24,8 @@ const { COMMAND_GROUPS, buildCommandManifest, findCommandSuggestion } = require(
 const command = process.argv[2];
 const args = process.argv.slice(3);
 const rawArgs = process.argv.slice(3);
+const { beginCommandReceipt } = require('../lib/agent/command-receipt');
+let commandReceipt;
 
 function shouldUseEnvManagement(argsList) {
   const subCommand = argsList[0];
@@ -571,6 +573,26 @@ function assertNoUnsupportedLegacyLoginFlags(...argLists) {
 }
 
 async function main() {
+  const { assertManagedInvocation, resolveManagedHelp } = require('../lib/agent/managed-run');
+  const { readManagedContext } = require('../lib/agent/managed-context');
+  if (readManagedContext() && [command, ...rawArgs].some(arg => arg === '--help' || arg === '-h')) {
+    assertManagedInvocation(command, rawArgs);
+    const entries = resolveManagedHelp(command, rawArgs, { t, version: currentVersion });
+    // Managed help is static and local: no Receipt, auth, update, first-run
+    // guide or business command module may run on this path.
+    commandReceipt = { finish() {} };
+    if (rawArgs.includes('--json')) {
+      console.log(JSON.stringify({ name: 'openyida', version: currentVersion, commands: entries }, null, 2));
+    } else {
+      printCommandUsage(...entries.flatMap(entry => [entry.usage, entry.description, ...(entry.examples || [])]));
+    }
+    return;
+  }
+  commandReceipt = beginCommandReceipt({ command, args: rawArgs });
+  process.once('exit', code => {
+    try {commandReceipt.finish(code);} catch {process.exitCode = 1;}
+  });
+  assertManagedInvocation(command, rawArgs);
   applyQuietFlag();
   applyGlobalEnvironmentFlags();
 
@@ -619,6 +641,12 @@ async function main() {
       break;
     }
 
+    case 'agent': {
+      const { run } = require('../lib/agent/cmd');
+      await run(args);
+      break;
+    }
+
     case 'mcp': {
       const { runStdioServer } = require('../lib/mcp/server');
       runStdioServer();
@@ -894,8 +922,8 @@ async function main() {
       if (args.length < 4) {
         throwCliUsage(t('cli.form_config_usage'), t('cli.form_config_example'));
       }
-      process.argv = [process.argv[0], process.argv[1], ...args];
-      require('../lib/app/update-form-config');
+      const { run: runUpdateFormConfig } = require('../lib/app/update-form-config');
+      await runUpdateFormConfig(args);
       break;
     }
 
@@ -1291,7 +1319,9 @@ async function main() {
 }
 
 main()
+  .then(() => { commandReceipt.finish(process.exitCode || 0); })
   .catch((err) => {
+    try {commandReceipt?.finish(err && err.exitCode ? err.exitCode : 1);} catch { /* Intent remains recoverable. */ }
     if (shouldUseStructuredErrorOutput(err, args)) {
       console.error(JSON.stringify(toErrorPayload(err), null, 2));
     } else if (isCliError(err)) {

package/lib/agent/PROTOCOL.md

@@ -0,0 +1,201 @@
+# Local runtime launcher contract
+
+This Node package ships no Go source. The packaged catalog and exact optional
+platform dependencies select signed runtime binaries for macOS and Windows,
+x64 and ARM64. npm installs the package matching the actual OS/CPU. Ordinary
+commands do not resolve or spawn this runtime. There is no arbitrary URL, PATH
+runtime discovery, or build/download fallback.
+
+## Production metadata and development mode
+
+`runtime-manifest.js` is the strict v2 codec: no extra/duplicate JSON keys, malformed
+UTF-8, unknown OS/CPU aliases, invalid protocol/state ranges, unsafe binary paths,
+oversized metadata/binaries or invalid digests. The binary path is exactly
+`bin/openyida-agent-runtime` (Windows: `.exe`). `sourceRevision` is a 40- or
+64-character lowercase source commit digest, not a public artifact tag.
+
+Detached Ed25519 signature: original UTF-8 `runtime-manifest.json` bytes, with no
+re-serialization; `.sig` is canonical base64 for 64 signature bytes, optionally
+one final LF. Trust roots live in the main package's `runtime-catalog.json`:
+`keys[keyId] = {publicKey: <SPKI PEM>, revoked?: boolean}`. Unknown/revoked keys
+fail closed; no TOFU, downloaded trust key, arbitrary URL or PATH fallback exists.
+
+Each approved release entry is `{platform, arch, packageName, packageVersion,
+runtimeVersion, manifestSha256}`. The main package must declare that exact
+`optionalDependencies` version. Public package naming is
+`@openyida/local-agent-runtime-${process.platform}-${process.arch}`. Platform metadata must match its
+exact name/version and single-element `os`/`cpu`, and have no lifecycle scripts.
+Main-package-relative Node resolution supports hoisting; platform packages must
+make `package.json` resolvable. Missing optional packages block Local Agent only.
+The current production platform allowlist is macOS (`darwin`) and Windows (`win32`).
+Linux remains a source/development target but must not appear in the production
+catalog or optional dependencies until native acceptance is complete. Ordinary
+non-Agent OpenYida CLI commands remain available on Linux.
+
+Unsigned v1 requires CLI `--development-runtime` plus explicit absolute
+`--runtime-path` and `--runtime-manifest`. Environment variables cannot enable it.
+Node sends `developmentRuntime: true` only for that flag. v1 is not accepted as a
+production compatibility fallback. Development binaries are normalized to the
+bundle executable filename; their original manifest is preserved as evidence.
+
+## Launch DTO (protocolVersion remains 1)
+
+Go argv is `[command, "--stdio-config"]`; stdin is one JSON object plus LF, at
+most 64 KiB. Business access/refresh tokens and ordinary OpenYida profile
+identifiers are never included. The launch contains the control endpoint,
+endpointId, providers and stateDir; web-first connect may additionally contain
+one short-lived Enrollment token. `node.version` remains the OpenYida package
+version, not the Node version.
+
+CLI-first connect lets Go create a state/PKCE/device-key-bound Enrollment and open
+the configured browser authorization page. Web-first connect receives the same
+device result by claiming the single-use `--enroll` token. Both modes persist only
+device connection credentials. For every accepted attempt, Python requests a
+fixed-value Tianshu task grant with an initial 60-minute lease and Go injects it
+only into that attempt's managed environment; Node never falls back to a normal
+local profile. The authenticated Runtime heartbeat lets Python renew the lease
+server-to-server while the authoritative Run remains active. Node has no task
+RefreshToken and cannot renew the bearer itself. The grant is bound to the
+application, not one form/page. An optional `formUuid` remains per-turn focus
+context and may change between turns inside the same `appType`.
+
+The device bearer is not sufficient by itself. Python sends a fresh nonce before
+accepting the Runtime hello, and Go signs the device/endpoint/nonce binding with
+the Ed25519 key created at Enrollment. Refresh requests similarly sign the
+device/action/refresh-token digest/endpoint binding. A copied access or refresh
+bearer therefore cannot connect or rotate without the enrolled private key.
+
+For both `connect` and `run`, added fields are:
+
+```json
+{
+  "parentWatchFD": 3,
+  "node": {
+    "executable": "/external/node",
+    "nodeVersion": "v22.22.3",
+    "sha256": "NODE_BINARY_SHA256",
+    "version": "2026.9.7",
+    "packageRoot": "/private/bundles/BUNDLE_SHA256/openyida",
+    "cliEntry": "/private/bundles/BUNDLE_SHA256/openyida/bin/yida.js"
+  },
+  "bundle": {
+    "schemaVersion": 1,
+    "id": "BUNDLE_SHA256",
+    "root": "/private/bundles/BUNDLE_SHA256",
+    "manifestPath": "/private/bundles/BUNDLE_SHA256/bundle-manifest.json",
+    "manifestSha256": "BUNDLE_SHA256",
+    "runtimeVersion": "0.1.0-dev",
+    "skillsDir": "/private/bundles/BUNDLE_SHA256/openyida/yida-skills"
+  }
+}
+```
+
+The launcher uses four stdio pipes and keeps fd 3 open independently from normal
+configuration stdin EOF. Parent death/pipe EOF asks Go to stop admission and
+cancel/drain, never to report successful completion. Node forwards SIGINT/TERM;
+failure grants 15 seconds before forcing the Go wrapper down. Such timeout returns
+`AGENT_RUNTIME_STOP_UNCONFIRMED` with `executionState: unknown`, not proof that
+provider processes or in-flight business effects stopped.
+
+## Bundle bytes, ownership and lifetime
+
+`bundle-manifest.json` is `JSON.stringify(object) + "\n"`, encoded as UTF-8.
+Its exact SHA-256 is the bundle ID; it is a local content manifest, not a publisher
+signature. Fields (in emitted order) are:
+
+```text
+schemaVersion: 1
+product: "openyida-local-agent-bundle"
+openyidaVersion, runtimeVersion
+launcherProtocol: 1
+wireProtocol: 1
+node: {version: <process.version>, sha256: <external Node binary hash>}
+runtime: {executable: "runtime/bin/openyida-agent-runtime[.exe]",
+          manifest: "runtime/runtime-manifest.json",
+          signature: "runtime/runtime-manifest.sig" | null,
+          development: boolean}
+cliEntry: "openyida/bin/yida.js"
+skillsDir: "openyida/yida-skills"
+files: [{path: <relative POSIX>, size: <integer>, sha256: <lowercase hex>,
+         mode: 292 | 365}]
+```
+
+Files sort by path using UTF-8 byte order (not JavaScript UTF-16 comparison).
+Mode 292 is octal 0444; 365 is 0555.
+The manifest is not its own files entry. Unknown files and symlinks are rejected.
+Go verifies the same raw manifest digest, file list/hash/size/mode, launch paths,
+runtime version and external Node identity before accepting work and before
+subsequent helper/new-turn use. Production publication trust is established by
+Node's v2 signature and approved digest, not by pretending the local bundle hash
+is a release signature.
+
+Node copies only packaged CLI assets and the recursively resolved production
+dependency/peer/available optional closure, preserving nested dependency
+resolution and cycles. It omits root platform packages (verified runtime bytes
+are copied separately), user projects, credentials, checkout metadata and
+devDependencies. Source content/tree membership is checked again before publish;
+missing dependencies or concurrent replacement fail closed. No install hook runs.
+
+Unique private staging directories plus atomic compare-and-publish handle
+concurrent materializers without a second execution lease. Contents are read-only;
+on macOS the staging root must remain writable until rename, then becomes 0500.
+Cache is 0700 on Unix. Same-user/root compromise is outside this protection;
+Windows ACL/OS release acceptance remains unverified. Interrupted staging is not
+an executable published bundle. Node does not repair a modified winner or GC
+existing bundles, unknown journals or user files.
+
+Go exclusively owns durable refs under
+`stateDir/bundle-references/<bundleId>/...` for connection, session and attempt
+lifetimes. Session identity no longer pins BundleID.
+Node has no ref writer, owner lease, GC or automatic migration. Global npm upgrade
+can produce a new bundle. After the connection drains and is restarted, a compatible
+bundle may continue the same native session; an active attempt never switches. External Node and
+provider binaries are not redistributed/frozen by this package; loss or an
+incompatible change blocks new work rather than silently starting fresh.
+
+For allowlisted Yida write commands only, Node writes one bounded Mutation Receipt
+after an explicit success result in OPENYIDA_AGENT_RECEIPTS_DIR. Read-only, failed
+and interrupted commands write nothing.
+Go forwards a successful openyida_mutation through the authenticated Run stream;
+Python adds requiresHostRefresh. No Go command gateway is involved.
+Windows parent lifetime uses parentPID and an OS process handle, not parentWatchFD.
+
+All current automated tests use generated signing keys and fake processes.
+No real provider, user account, Yida write, public upload or npm publication is
+part of this implementation checkpoint.
+
+### Background startup receipt
+
+A background `run` can carry a fresh `startupId` (safe identifier, generated per
+spawn). The runtime atomically writes `startup-<startupId>.json` in `stateDir`
+with mode 0600 after the control endpoint is bound, the cloud welcome is
+validated, and recovery finishes. Its only fields are `protocolVersion: 1`,
+`startupId`, and boolean `ready`. The launcher requires `ready: true`, then removes
+the receipt and detaches. Provider logs are never a startup acknowledgement.
+A startup failure/exit or the 60-second deadline rejects the launch; the launcher
+terminates only its own new child, preserving credentials and journals.
+
+This is an additive launch-config extension. Older launchers omit it. Older
+runtimes reject unknown fields, so release the updated runtime and update the
+CLI's exact runtime dependencies and signed catalog together before publishing
+this launcher. Do not pair the updated launcher with a previously published
+runtime and assume compatibility.
+
+## Managed output delivery and business questions
+
+Only `openyida.ask-human.v2` receipts are accepted. The CLI explicitly declares
+bounded text attachments and freezes their bytes in the attempt's private
+`.files` directory. Runtime verifies each snapshot and uploads it with device
+authentication to `/api/local-runtime/v1/runs/{runId}/artifacts`, with bounded
+base64url JSON metadata in `X-OpenYida-Output` and an octet-stream body.
+Server-owned paths, digests and sizes are durably acknowledged in the attempt
+journal before `question_opened`; local paths and file bytes never enter events.
+No recursive directory sync or v1 receipt compatibility is implemented.
+
+Question choices retain stable `value` separately from display labels; business
+`contextRevision` is distinct from the integer interaction revision. Answers and
+file references remain bound to the displayed question on continuation. The UI
+uses the existing authenticated project-file reader and isolated HTML preview.
+Permanent upload errors fail the turn; bounded transient retries remain cancellable.
+Persisted ACKs/events can be replayed without executing business commands again.
+An interrupted upload does not silently resume an unconfirmed provider execution.

package/lib/agent/ask-human-help.js

@@ -0,0 +1,19 @@
+'use strict';
+
+// Shared static help: no authentication, file access, or receipt creation.
+const example = {
+  title: '确认搭建方案', revision: '<confirmation.revision>',
+  attachments: [{ name: '搭建方案.html', path: '<outputs.confirmationHtml>' }],
+  questions: [{ id: 'plan_decision', header: '搭建方案', question: '请确认当前搭建方案',
+    type: 'single_select', options: [
+      { label: '确认并开始搭建', value: 'confirm_build' },
+      { label: '继续调整', value: 'continue_editing' },
+    ] }],
+};
+
+module.exports = {
+  path: ['agent', 'ask-human'],
+  usage: 'openyida agent ask-human --request-key <稳定业务键> --questions-file <相对路径> --json',
+  description: '在宜搭云端发起的本地 Agent 任务中提交结构化问题并等待网页回答。',
+  examples: [JSON.stringify(example)],
+};

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