openyida 2026.10.13 → 2026.10.14-1

package/README.md

@@ -8,7 +8,7 @@
 
 OpenYida connects AI coding agents with Yida's low-code platform, so developers can create apps, forms, workflows, custom pages, reports, integrations, and deployment configuration from a normal chat-driven development workflow.
 
-[Quick Start](#quick-start) · [帮助网站&文档](https://demo.aliwork.com/o/openyida/helpCenter) · [Capabilities](#capabilities) · [Full Capability List](https://demo.aliwork.com/o/openyida/helpCenter?openyidaPath=capabilities) · [CLI Reference](https://demo.aliwork.com/o/openyida/helpCenter?openyidaPath=features/skills) · [Examples](https://demo.aliwork.com/o/openyida/helpCenter?openyidaRoute=showcase) · [Contributing](./CONTRIBUTING.md) · [Changelog](https://demo.aliwork.com/o/openyida/helpCenter?openyidaRoute=changelog)
+[Quick Start](#quick-start) · [帮助网站&文档](https://demo.aliwork.com/o/openyida/helpCenter) · [Capabilities](#capabilities) · [Full Capability List](https://demo.aliwork.com/o/openyida/helpCenter?openyidaPath=capabilities) · [CLI Reference](https://demo.aliwork.com/o/openyida/helpCenter?openyidaPath=features/skills) · [Examples](https://demo.aliwork.com/o/openyida/helpCenter?openyidaRoute=showcase) · [Contributing](./CONTRIBUTING.md) · [Changelog](https://demo.aliwork.com/o/openyida/helpCenter?openyidaRoute=changelog) · [Application Previews](#application-previews)
 
 [![npm version](https://img.shields.io/npm/v/openyida?color=brightgreen&label=npm)](https://www.npmjs.com/package/openyida)
 [![npm downloads](https://img.shields.io/npm/dm/openyida?color=blue)](https://www.npmjs.com/package/openyida)
@@ -16,8 +16,6 @@ OpenYida connects AI coding agents with Yida's low-code platform, so developers
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**帮助网站&文档:** [帮助网站&文档](https://demo.aliwork.com/o/openyida/helpCenter)
-
 [English README](./README.md) · [简体中文 README](./README_zhCN.md)
 
 </div>
@@ -26,7 +24,32 @@ OpenYida connects AI coding agents with Yida's low-code platform, so developers
 
 ## What OpenYida Provides
 
-OpenYida is a bridge between AI coding tools and Yida. It gives agents a stable command-line interface for the full application lifecycle:
+OpenYida is a bridge between AI coding tools and Yida. It gives agents a stable `openyida` CLI to create resources, inspect schemas, generate source code, compile and publish pages, and diagnose issues.
+
+The result remains a native Yida application: teams can continue editing it in Yida, use existing enterprise security controls, and deploy through the Yida platform.
+
+## Application Previews
+
+Example applications built with the themes below. Click an image to view it at full size. These are visual references, not ready-made business applications: content, data, brand colors, and layouts are adapted to your requirements.
+
+<table>
+  <tr>
+    <td width="50%" align="center"><strong>Dark Rail · Fine Lines</strong><br><a href="https://img.alicdn.com/imgextra/i1/O1CN01oFp7XMYEjSI5r31K_!!6000000006946-2-tps-2884-1794.png"><img src="https://img.alicdn.com/imgextra/i1/O1CN01oFp7XMYEjSI5r31K_!!6000000006946-2-tps-2884-1794.png" alt="Dark Rail · Fine Lines example application" width="100%"></a></td>
+    <td width="50%" align="center"><strong>Soft Inset Surfaces</strong><br><a href="https://img.alicdn.com/imgextra/i3/O1CN01UEEmuLlMF3I5pHky_!!6000000006290-2-tps-2870-1798.png"><img src="https://img.alicdn.com/imgextra/i3/O1CN01UEEmuLlMF3I5pHky_!!6000000006290-2-tps-2870-1798.png" alt="Soft Inset Surfaces example application" width="100%"></a></td>
+  </tr>
+  <tr>
+    <td width="50%" align="center"><strong>Sage</strong><br><a href="https://img.alicdn.com/imgextra/i1/O1CN01NiHI4pBsbOK5qIC4_!!6000000007377-2-tps-2878-1798.png"><img src="https://img.alicdn.com/imgextra/i1/O1CN01NiHI4pBsbOK5qIC4_!!6000000007377-2-tps-2878-1798.png" alt="Sage example application" width="100%"></a></td>
+    <td width="50%" align="center"><strong>Teal</strong><br><a href="https://img.alicdn.com/imgextra/i2/O1CN01hLAdOTwuEWF5qXno_!!6000000004848-2-tps-2880-1796.png"><img src="https://img.alicdn.com/imgextra/i2/O1CN01hLAdOTwuEWF5qXno_!!6000000004848-2-tps-2880-1796.png" alt="Teal example application" width="100%"></a></td>
+  </tr>
+  <tr>
+    <td width="50%" align="center"><strong>Terminal</strong><br><a href="https://img.alicdn.com/imgextra/i3/O1CN01PPHEYDv6nMB5qXnq_!!6000000004777-2-tps-2880-1798.png"><img src="https://img.alicdn.com/imgextra/i3/O1CN01PPHEYDv6nMB5qXnq_!!6000000004777-2-tps-2880-1798.png" alt="Terminal example application" width="100%"></a></td>
+    <td width="50%" align="center"><strong>Platinum</strong><br><a href="https://img.alicdn.com/imgextra/i2/O1CN01eDGhh1WCtFI5soHi_!!6000000007333-2-tps-2898-1792.png"><img src="https://img.alicdn.com/imgextra/i2/O1CN01eDGhh1WCtFI5soHi_!!6000000007333-2-tps-2898-1792.png" alt="Platinum example application" width="100%"></a></td>
+  </tr>
+</table>
+
+Use an **application theme or an independent creative direction**. Describe a style you like, or provide a reference website or design image to customize your app’s appearance. [Browse more application examples](https://demo.aliwork.com/o/openyida/helpCenter?openyidaRoute=showcase).
+
+## Core Capabilities
 
 | Area | What you can do |
 |------|-----------------|
@@ -38,7 +61,18 @@ OpenYida is a bridge between AI coding tools and Yida. It gives agents a stable
 | Integrations | Manage HTTP connectors, connector actions, auth accounts, and automation flows |
 | Operations | Diagnose environment issues, manage login state, configure sharing, upload CDN assets |
 
-The result remains a native Yida application: teams can continue editing it in Yida, use existing enterprise security controls, and deploy through the Yida platform.
+## From Request to Delivery
+
+1. **Describe the goal.** Explain who will use the app, what they need to do, and any existing app or reference material.
+2. **Share requirements and preferences.** Add the business details and appearance preferences that matter to you. Include any colors, websites, or design images you like.
+3. **Choose how to build.** Fast suits clear requirements you want to move forward with. Plan produces a reviewable proposal and waits for approval before creating resources.
+4. **Review and refine.** Check the delivered app and common actions, then request page, field, or workflow changes. Your chosen style is reused unless you ask to change it.
+
+For existing-app improvements, review the visual proposal before backups and implementation. Restoration uses the saved backups; page content and theme settings need separate backups, with the supported scope explained before changes.
+
+## Recent Updates
+
+**2026.10.14-1** improves appearance customization, with better support for style descriptions, reference websites, and design images. [Read the full changelog](./CHANGELOG.md#20261014-1---2026-10-14).
 
 ## Quick Start
 
@@ -50,9 +84,14 @@ npm install -g openyida
 
 OpenYida requires Node.js 18 or later. The package exposes both `openyida` and `yida` commands.
 
-For npm global installations, OpenYida checks the npm registry before a normal command at most once every 24 hours. When a newer version is available, it installs that exact version and then reruns the original command. This behavior is identical whether the local command is launched from a terminal, Codex, Claude Code, or Qoder. Managed cloud Agent runtimes are excluded before any cache access, registry request, or npm invocation.
+Global npm installations check for updates at most once a day and update automatically. Run `openyida update` to update manually, or set `OPENYIDA_NO_AUTO_UPDATE=1` to keep your installed version.
+
+<details>
+<summary>Auto-update environments and development settings</summary>
+
+Local terminals and AI tools share the same policy. Managed cloud Agent runtimes skip automatic updates. For development and testing, `OPENYIDA_AUTO_UPDATE_SECS` changes the check interval.
 
-Set `OPENYIDA_NO_AUTO_UPDATE=1` to disable automatic updates. `OPENYIDA_AUTO_UPDATE_SECS` can override the check interval for development and testing. The explicit `openyida update` command remains available.
+</details>
 
 If Codex is already installed, OpenYida also imports a local Codex plugin during postinstall. Restart Codex after installation, then type `@宜搭` or `@openyida` in the composer to attach the OpenYida context.
 
@@ -64,7 +103,7 @@ Run this from the AI coding workspace where you want OpenYida to operate:
 openyida agent-capabilities --summary-json
 ```
 
-OpenYida returns a compact machine-readable summary with the version, login state, workspace/cache paths, and command manifest digest. `openyida agent-capabilities --json` is the full diagnostic snapshot, where compact `workdir` maps to `active.projectRoot` and `workdir_exists` maps to `active.projectRootExists`. `openyida commands --json` remains available when an agent only needs the command manifest.
+This checks the installed version, login state, and workspace. Use `openyida agent-capabilities --json` for detailed diagnostics.
 
 ### 3. Log In
 
@@ -105,8 +144,9 @@ Ask your coding agent for a concrete Yida application or workflow:
 
 ```text
 Create a CRM application in Yida with customer, contact, opportunity, and follow-up forms.
-Build an IPD workflow for chip production, including approval nodes and dashboard pages.
-Generate a public landing page and publish it to my Yida app.
+Use Plan mode to design a procurement app with requests, approvals, and dashboards. Show me the proposal first.
+Build an oolong tea brand storefront and order management back office, with navigation groups.
+Improve the appearance of this existing app. Show me the proposal first, preserve business logic, and back up before changes.
 ```
 
 The agent can then call OpenYida commands to create the application, generate source files, publish pages, and return the final Yida URLs. In Codex, QwenWork, Qoder, Qoder IDE, and QoderWork environments, successful creation and publish commands also include a browser handoff so the agent can open the resulting Yida page in the in-app browser. Use `--open` to force this handoff or `--no-open` to suppress it.
@@ -118,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 |
@@ -163,18 +202,6 @@ openyida/
 
 For a user-facing list of supported features and matching CLI commands, see [OpenYida 功能完整列表](https://demo.aliwork.com/o/openyida/helpCenter?openyidaPath=capabilities).
 
-### Style Selection and Optional Previews
-
-Only show reference previews when the user explicitly requests them. Style choices use the host's supported ask_human tool on every platform.
-
-```bash
-openyida sample yida-design theme-preview --theme-ids app-sage,app-teal,app-terminal,app-platinum --output .cache/theme-preview.html --json
-```
-
-This creates a read-only HTML gallery of all requested themes: titles and images only, four to six columns on desktop, fewer on narrow screens, with no row limit. It has no selection controls and refuses to overwrite existing files. Open it with the host's preview tools; raw HTML is not guaranteed to render in chat. QwenWork may alternatively prepare the same read-only template with `sample yida-design theme-selector --json` and pass its returned relative `widget_path` to `qoder_show_widget`. Neither preview path submits a choice.
-
-Ready style questions join the same ask_human call as other necessary questions; split only for dependencies or host limits. Pop art is omitted unless explicitly requested or the primary task is showcase-oriented. Previewing app-pop requires --pop-art-context explicit-request or showcase, based on that evidence.
-
 ### Application and Form Management
 
 ```bash
@@ -537,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 |
@@ -605,6 +633,18 @@ 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.
 
+### Connect a Local Agent
+
+Use an installed Qoder or Codex CLI on your computer to run tasks from the Yida web app. Local Agent supports macOS and Windows; the ordinary OpenYida CLI also supports Linux.
+
+Check your local environment, then follow the connection instructions in the Yida web app:
+
+```bash
+openyida agent doctor --json
+```
+
+After connecting, the service runs in the background. Use `openyida agent status` to check its status, `openyida agent logs` to view logs, and `openyida agent disconnect` to disconnect. After restarting your computer, run `openyida agent run` to reconnect.
+
 ## 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)],
+};