openyida 2026.10.8 → 2026.10.9-beta.2

package/README.md

@@ -118,7 +118,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 |
@@ -183,7 +182,7 @@ openyida get-schema APP_XXX FORM_XXX --compact --resolve-fields "Customer Name,S
 openyida get-schema APP_XXX --all --output-dir .cache/schemas
 ```
 
-Native forms use a component tree: business fields capture data, tabs switch content, action groups trigger business actions, images establish visual focus, status areas provide feedback, and `Divider` plus `ColumnContainer` organize hierarchy and columns. `create-form` field definitions create 19 business field types plus `Divider` and `ColumnContainer` (mapped to `ColumnsLayout` + `Column`), while updates retain other existing components.
+Form definitions support 19 business field types plus verified presentation/layout components. Prefer `Divider` for section titles and `ColumnContainer` (mapped to `ColumnsLayout` + `Column`) for multi-column layout; use `GroupContainer` / `PageSection` only when an actual grouping container is needed.
 
 ### Custom Page Development
 
@@ -393,15 +392,13 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 | Command | Description |
 |---------|-------------|
-| `openyida app-entry get <appType> [--json]` | Read frontend and management runtime entries |
-| `openyida app-entry set <appType> [--frontend <url>\|--frontend-page <formUuid>] [--management <url>\|--management-page <formUuid>] [--clear-frontend] [--clear-management] [--json]` | Register application entries with partial update and readback |
 | `openyida app-list [--type managed\|created] [--page N] [--size N]` | Page through apps I manage or created |
 | `openyida corp-efficiency [overview\|details\|detail\|groups\|notify] [options] [--open\|--no-open]` | Query enterprise efficiency overview and detail reports |
 | `openyida create-app "<name>"\|--name <name> [options] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a Yida app |
 | `openyida design-plan catalog [--json]` | List available planning themes and page patterns |
 | `openyida design-plan init <requirement-brief.json> [--theme-id <id>] [--output-dir <dir>] [--json]` | Initialize a plan draft from confirmed requirements |
 | `openyida design-plan preview <build-plan.json> --part-file <module.json> [--json]` | Update plan drafts by module |
-| `openyida design-plan materialize <build-plan.json> [--from-preview \| --business-file <json> --visual-file <json>] [--output-dir <dir>] [--rebase-parts] [--check] [--json]` | Generate or update plan documents and theme with consistency checks |
+| `openyida design-plan materialize <build-plan.json> [--from-preview \| --business-file <json> --visual-file <json>] [--output-dir <dir>] [--check] [--json]` | Generate or update plan documents and theme with consistency checks |
 | `openyida design-plan patch <build-plan.json> --set <path=value> [--set <path=value> ...] [--materialize] [--output-dir <dir>] [--json]` | Patch plan fields and optionally sync documents and theme |
 | `openyida update-app <appType> [--name "..."] [--desc "..."] [--icon <name>] [--icon-color <color>] [--colour <key>] [--theme-color <color>] [--theme-file <css>] [--nav-theme light\|dark\|white\|gray] [--logo-source appIcon\|customImage] [--layout side\|top\|l_shape] [--hide-app-nav\|--show-app-nav]` | Update app info |
 | `openyida app-online <appType> [--to-ding-app-center] [--show-app-center]` | Enable a Yida app |
@@ -417,7 +414,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | Command | Description |
 |---------|-------------|
 | `openyida create-form batch <appType> <plan.json> [--concurrency 1..4] [--check] [--json]` | Create forms concurrently by dependency |
-| `openyida create-form create <appType> "<formTitle>" <fieldsJsonFile> [--layout single\|double\|card\|section] [--theme default\|compact\|comfortable] [--label-align top\|left\|right] [--icon auto\|<iconName>] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
+| `openyida create-form create <appType> "<formTitle>" <fieldsJsonFile> [--icon auto\|<iconName>] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
 | `openyida create-form icons [--json]` | List available form navigation icons |
 | `openyida create-form validate-fields <fieldsJsonOrFile> [--json]` | Validate form field JSON locally |
 | `openyida create-form update <appType> <formUuid> (<changesJsonOrFile> \| --data-file <changesJsonOrFile>) [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Update a form page |
@@ -437,8 +434,8 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida create-page <appType> "<name>" [--mode dashboard] [--hide-nav] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a custom display page |
 | `openyida build-page <sourceFile> [--output file\|--write]` | Build Yida-compatible page source |
 | `openyida check-page <src> [--compat] [--json]` | Check custom page standards |
-| `openyida compile <src> [--canvas] [--compat] [--skip-lint] [--strict-theme\|--allow-fixed-brand] [--json]` | Compile custom page locally |
-| `openyida publish <src> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--fix-theme] [--strict-theme] [--allow-fixed-brand] [--auto-nav-order] [--open\|--no-open] [--json]` | Compile and publish custom page |
+| `openyida compile <src> [--canvas] [--compat] [--skip-lint] [--json]` | Compile custom page locally |
+| `openyida publish <src> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--auto-nav-order] [--open\|--no-open] [--json]` | Compile and publish custom page |
 | `openyida update-form-config <appType> <formUuid> <true\|false\|keep> "<title>" [--locale zh_CN\|en_US\|ja_JP]` | Update form configuration |
 | `openyida get-form-config <appType> <formUuid> [--json]` | Query form configuration |
 
@@ -522,10 +519,11 @@ 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 |
-| `openyida sample [--list] [<skill> <name>] [--output <file-or-directory>] [--var KEY=VALUE ...] [--design-file <design.md>] [--style-id <themeId\|free-creative>]` | Output code samples/templates |
+| `openyida sample [--list] [<skill> <name>] [--output <file>] [--var KEY=VALUE ...] [--design-file <design.md>]` | Output code samples/templates |
 | `openyida doctor [--fix]` | Environment diagnostics & auto-fix |
 | `openyida db-seq-fix [--fix]` | Detect and repair PostgreSQL sequence drift |
 | `openyida formula evaluate <formula\|file> [--schema file]` | Static-check Yida formula syntax and field refs |
@@ -590,6 +588,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. Platform runtime packages are **not published** in this preview; no Go executable is discovered on `PATH` and no provider is installed or invoked by Node.
+
+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 release catalog is currently empty: no production signing key or package is implied to exist. 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` keeps the new Connection online in the foreground, while `agent run`, `status`, `disconnect`, and `logout` enumerate every valid Connection. 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, arbitrary batches, and cross-application requests. `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();
@@ -733,12 +761,6 @@ async function main() {
       break;
     }
 
-    case 'app-entry': {
-      const { run } = require('../lib/app/app-entry');
-      await run(args);
-      break;
-    }
-
     case 'app-list': {
       const { run } = require('../lib/app/app-list');
       await run(args);
@@ -894,8 +916,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;
     }
 
@@ -1281,7 +1303,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)) {
@@ -1292,7 +1316,5 @@ main()
     } else {
       warn(t('cli.exec_failed', err.message));
     }
-    // Let pending stdout/stderr writes drain, especially large JSON diagnostics
-    // sent through pipes on macOS/Linux. process.exit() can truncate them.
-    process.exitCode = err && err.exitCode ? err.exitCode : 1;
+    process.exit(err && err.exitCode ? err.exitCode : 1);
   });

package/lib/agent/PROTOCOL.md

@@ -0,0 +1,182 @@
+# Local runtime launcher contract (development implementation)
+
+This Node package contains no Go source or build/download fallback. The runtime
+catalog is intentionally empty until release ownership, signing keys, platform
+support and real package publication are approved. Internal test injection is not
+a CLI trust-root option. Ordinary commands do not resolve or spawn this runtime.
+
+## 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. Candidate naming is
+`@openyida/local-agent-runtime-${process.platform}-${process.arch}`; this is not a
+claim those names are registered or published. 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 Beta production 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.

package/lib/agent/ask-human.js

@@ -0,0 +1,151 @@
+'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.v1';
+const MAX_FILE_BYTES = 32 * 1024;
+const USAGE = '用法：openyida agent ask-human --request-key <稳定业务键> --questions-file <相对路径> --json';
+
+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', 'description'].includes(key)) || !text(option.label, 512) ||
+          (option.description !== undefined && option.description !== '' && !text(option.description, 1024)))) {
+      fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 选项结构无效。');
+    }
+    if (new Set(options.map(option => option.label)).size !== options.length) { fail('AGENT_ASK_HUMAN_INVALID', 'Ask Human 选项不能重复。'); }
+  }
+  return { title: document.title, questions: document.questions.map(question => ({ ...question, required: question.required !== false })) };
+}
+
+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 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}\n问题文件格式：{ "title": "...", "questions": [{ "id": "...", "header": "...", "question": "...", "type": "text|single_select|multi_select", "options": [{ "label": "...", "description": "..." }] }] }\n`);
+    return { ok: true, help: true };
+  }
+  const document = readQuestions(args.questionsFile, options.cwd || process.cwd());
+  const digest = crypto.createHash('sha256').update(JSON.stringify(document)).digest('hex');
+  const directory = ensureReceiptDir(env);
+  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 };