Document in-place upgrades

AGENTS.md

@@ -58,7 +58,7 @@ The categories are [process settings](docs/configuration.md#process-settings), [
 
 ### Pre-release: no compatibility layers
 
-OpenAgentCore is pre-release. Replace superseded interfaces, execution paths and files outright. Keep no version fallback, compatibility shim or migration for superseded behavior unless an explicit upgrade contract requires it. Keep the pinned official public protocol, valid data and still-used, verified infrastructure. Do not rewrite working infrastructure only to rename it.
+OpenAgentCore is pre-release. Replace superseded interfaces, execution paths and files outright. Keep no version fallback, compatibility shim or migration for superseded behavior unless an explicit upgrade contract requires it. The [in-place upgrade](docs/getting-started/operations.md#upgrade) from v0.0.10 or later is that contract: persisted changes ship as forward migrations (goose for PostgreSQL, `oac init` for the data volume), and a landed migration is never edited. Protocols may change; the release notes list each change with the operator actions it requires. Keep the pinned official public protocol, valid data and still-used, verified infrastructure. Do not rewrite working infrastructure only to rename it.
 
 ## Documentation
 

CONTRIBUTING.md

@@ -37,7 +37,7 @@ This guide owns how to work in the repository: documentation ownership, the repo
 | Installer lifecycle, locking, generated state, managed HTTPS and downloads | [Deployment](deploy/README.md) and [Node installer](deploy/node/README.md) |
 | Operator installation and alternatives | [Installation](docs/getting-started/install.md), [installation options](docs/getting-started/install-options.md) |
 | Settings, defaults, files and installation layout | [Configuration](docs/configuration.md) |
-| Operator commands, keys, backup and version policy | [Operations](docs/getting-started/operations.md) |
+| Operator commands, keys, backup and upgrades | [Operations](docs/getting-started/operations.md) |
 | Web console request boundary and sign-in | [Console server](docs/web/console-server.md) |
 | Web page behavior and visual rules | [Web product](apps/web/PRODUCT.md), [Web design](apps/web/DESIGN.md) |
 | Application example behavior and local operation | [Application example](example/parsar/README.md) |
@@ -145,7 +145,7 @@ Native adapter changes require their build/check targets and live provider accep
 
 Provider bootstrap, Runtime images and Harness adapters must agree on these names.
 
-The [installation version policy](docs/getting-started/operations.md#installation-version-policy) owns release changes and preservation of installed data and resources.
+[Upgrade](docs/getting-started/operations.md#upgrade) owns release changes and preservation of installed data and resources.
 
 ## Branding
 

apps/web/src/features/sandbox/NodeRolloutStatus.tsx

@@ -14,6 +14,6 @@ export function NodeRolloutStatus({ node, stale = false }: { node: SandboxNode;
   return <span className="status-with-help">
     <StatusDot tone={tones[state]} label={t(labels[state])} />
     {state === "failed" && node.rollout.diagnostic ? <DiagnosticTip code={node.rollout.diagnostic} /> : null}
-    {state === "update_required" ? <HelpTip>{t("In-place upgrades from older project versions are not supported. Reinstall using the current version. Existing data is not removed automatically.")}</HelpTip> : null}
+    {state === "update_required" ? <HelpTip>{t("This node can't prepare new sandbox configurations and keeps serving the one it registered with. To move it to the current configuration, choose Remove node, then add the host again with Add node.")}</HelpTip> : null}
   </span>;
 }

apps/web/src/i18n/locales/zh-CN/sandbox.ts

@@ -59,7 +59,7 @@ export const sandbox = {
   "Review affected nodes for preparation errors, incompatible node software or an unconfirmed connection. Qualified earlier generations may still serve work.": "请检查相关节点的准备错误、不兼容的节点程序或尚未确认的连接。符合条件的旧代次仍可提供服务。",
   "Existing sandboxes keep their configuration generation. Saving does not move them or prove the target is ready.": "现有沙箱保留所属配置代次。保存不会迁移沙箱，也不代表目标配置已就绪。",
   "Changes keep this backend and existing Sessions and nodes. Core prepares the new target for future work; placement may continue on qualified earlier generations.": "修改会保留当前沙箱提供商、现有 Session 和节点。Core 为后续任务准备新目标配置，期间仍可能将任务分配到符合条件的旧代次。",
-  "In-place upgrades from older project versions are not supported. Reinstall using the current version. Existing data is not removed automatically.": "不支持旧项目版本原地升级，请使用当前版本重新安装。现有数据不会自动删除。",
+  "This node can't prepare new sandbox configurations and keeps serving the one it registered with. To move it to the current configuration, choose Remove node, then add the host again with Add node.": "该节点无法准备新的沙箱配置，会继续服务注册时的配置。要让它使用当前配置，请选择“移除节点”，再通过“添加节点”重新添加该主机。",
   "The saved serving generation is not proof that this node is online, ready or has free capacity.": "已保存的服务代次不代表节点当前在线、已就绪或有空闲容量。",
   "Node observations are from an earlier configuration generation. Refreshing does not change their owned sandboxes.": "节点观测来自较早的配置代次。刷新不会改变节点所属的沙箱。",
   "Leave blank to keep the saved key. Any key you enter is verified as a replacement, even if unchanged.": "留空可保留已保存的密钥。填写的密钥都会作为替换密钥进行验证，即使内容未变。",

contracts/agents-api/node-generation-protocol.md

@@ -123,4 +123,4 @@ The readiness classes, one exported error and one code each, are authored in `se
 
 Preparation diagnostics keep fixed typed causes. Only artifact transfer, checksum or release-provenance failures report `runtime_download_failed`; the private preparer signals that class through its exit category, without Core or the node parsing stderr. Provider, ownership, cancellation and unclassified failures keep their typed code or `provider_unavailable`. No raw provider text crosses the protocol.
 
-The current wire version is 5. Create bootstrap and Resume requests may carry an optional workspace filesystem binding. The node validates its tenant and Environment against the allocation reference, its immutable ObjectID, and its attachment configuration ID against the supplied configuration before forwarding it. The filesystem resolver validates adapter-native ownership. A missing binding selects owned storage; a present binding cannot fall back. Error responses may retain a Resume target only when its nonempty native ID, name, generation and snapshot provenance match the requested target; this is cleanup evidence, never successful restore.
+Create bootstrap and Resume requests may carry an optional workspace filesystem binding. The node validates its tenant and Environment against the allocation reference, its immutable ObjectID, and its attachment configuration ID against the supplied configuration before forwarding it. The filesystem resolver validates adapter-native ownership. A missing binding selects owned storage; a present binding cannot fall back. Error responses may retain a Resume target only when its nonempty native ID, name, generation and snapshot provenance match the requested target; this is cleanup evidence, never successful restore.

contracts/agents-api/zh/node-generation-protocol.md

@@ -1,7 +1,7 @@
 ---
 title: "沙箱节点协议"
 source: contracts/agents-api/node-generation-protocol.md
-source_hash: fb446e91c3df3c9e397e5e9abb794245b0ae11d81176879207718680e8ab4173
+source_hash: 06982830caebaaaa95b37a78c73710555a332a4a182aeab6d73836a964805443
 ---
 
 沙箱节点在其主机上运行 Docker 或 microsandbox 提供商，并通过一个 WebSocket 与 Core 相连。Core 通过该连接发送提供商操作；节点针对本地提供商执行这些操作，并报告就绪状态、主机测量值及其持有的部署代次。Core 始终是唯一的生命周期所有者：节点绝不重试变更操作或调度工作。帧和校验器位于 [`services/core/internal/sandbox/node`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/sandbox/node)（`wire.go`、`generation_wire.go`）；节点用于注册和读取配置的 HTTP 路由位于[机器连接 API](machine-api.md#node-routes)。
@@ -125,4 +125,4 @@ Runtime 字节缺失时，绝不将固定的放置实例迁移到当前 Runtime
 
 准备诊断使用固定的类型化原因。只有制品传输、校验和或版本来源验证失败才会报告 `runtime_download_failed`；私有准备器通过退出类别指示这一类失败，Core 和节点都不解析 stderr。提供商故障、所有权故障、取消和未分类故障保留其类型化代码，或使用 `provider_unavailable`。协议中不会传输任何提供商原始文本。
 
-当前线协议版本为 5。Create 引导和 Resume 请求可携带可选的工作区文件系统绑定。节点在转发前校验其租户及 Environment 与分配引用一致、ObjectID 不可变且有效，以及挂载配置 ID 与所传配置一致。文件系统解析器负责适配器原生所有权校验。未提供绑定时选择自有存储；已提供绑定时不得回退。错误响应仅可保留原生 ID 非空且名称、代次、快照来源均匹配请求的 Resume 目标；这仅为清理证据，不代表恢复成功。
+Create 引导和 Resume 请求可携带可选的工作区文件系统绑定。节点在转发前校验其租户及 Environment 与分配引用一致、ObjectID 不可变且有效，以及挂载配置 ID 与所传配置一致。文件系统解析器负责适配器原生所有权校验。未提供绑定时选择自有存储；已提供绑定时不得回退。错误响应仅可保留原生 ID 非空且名称、代次、快照来源均匹配请求的 Resume 目标；这仅为清理证据，不代表恢复成功。

docs/configuration.md

@@ -245,7 +245,8 @@ The installer creates `~/.oac/core` by default (`$HOME/.oac/core` on Windows). I
 | Path | Content | Changed by |
 | --- | --- | --- |
 | `.env` | Process settings and the stable Compose project name | You, then `oac apply` |
-| `compose.yaml`, `compose-sha256sums.txt` | Verified release service definition | The release |
+| `compose.yaml` | Verified release service definition | The installer, when it installs or [upgrades](./getting-started/operations.md#upgrade) |
+| `compose.override.yaml` | Optional local Compose entries. For a source bundle it is JSON and also holds the four service images and Web's `/node-payload` bind | You. `install.py` replaces only its own entries and requires JSON |
 | `oac` (`oac.exe` on Windows) | Native management command | The installer |
 
 The sibling `<install-dir>.lock` directory remains for synchronization; `<install-dir>.staging` holds unpublished installation files. Neither contains service data. On Unix the installer creates private directories with mode `0700` and configuration files with mode `0600`.

docs/development.md

@@ -86,7 +86,7 @@ docker compose up -d --wait --pull never
 ./oac core-key --show
 ```
 
-`install.py` requires an empty installation directory. Configuration preparation failures before `compose.yaml`, `.env` and `oac` exist require removing that incomplete directory and retrying. After those files exist, use Compose to retry. Use the [operator commands](./getting-started/operations.md) for configuration, keys and stopping services. A different source commit is a fresh installation, not an in-place upgrade: delete managed resources and uninstall nodes first, then remove the old Compose containers and data volume with `docker compose down --volumes`, and remove its installation directory. This permanently deletes that test installation's data. Alternatively choose another installation directory and Web port.
+Rerunning the same bundle's `install.py` on its installation directory resumes the installation with the saved settings; `--public-url` is required only for a new directory. A bundle from another commit refuses an existing installation unless you pass `--upgrade`, which [upgrades it in place](./getting-started/operations.md#upgrade). If preparation fails before `compose.yaml` and `.env` exist, remove that incomplete directory and retry. Use the [operator commands](./getting-started/operations.md) for configuration, keys and stopping services.
 
 ## Build and run components
 

docs/getting-started/install-options.md

@@ -41,7 +41,7 @@ On either platform, open its server terminal and run `docker compose ls` to find
 
 After signing in, choose the sandbox backend and add nodes using [Nodes](./nodes.md). The Compose stack deploys the control plane; execution machines remain separate.
 
-Stop with `docker compose stop` using the same files and environment. Back up the data volume and configuration together while the services are stopped. Follow the [installation version policy](./operations.md#installation-version-policy): a different release needs a new Compose project and a fresh data volume.
+Stop with `docker compose stop` using the same files and environment. Back up the data volume and configuration together while the services are stopped. To upgrade, back up first, then deploy the new release's `compose.yaml` with the same project, environment and data volume: initialization upgrades the volume and Core migrates the database. [Upgrade](./operations.md#upgrade) describes what is kept and why an older release is refused.
 
 ## Process settings
 
@@ -56,11 +56,12 @@ These flags are written to `.env` once. After installation, edit that file and r
 
 ## Installation actions
 
-`--install-dir` chooses where the installation is created. It is not a process setting.
+`--install-dir` chooses where the installation is created. Neither option is a process setting.
 
 | Option | Purpose |
 | --- | --- |
-| `--install-dir DIR` | Absolute installation directory; defaults to `~/.oac/core`. Use an empty or missing directory for a new installation, or an existing installation directory to [retry](./install.md#install) |
+| `--install-dir DIR` | Absolute installation directory; defaults to `~/.oac/core`. Use an empty or missing directory for a new installation, or an existing installation directory to [retry](./install.md#install) or upgrade |
+| `--upgrade` | Upgrade the existing installation in `--install-dir` to the installer's release; see [Upgrade](./operations.md#upgrade) |
 
 Several installations can share a machine when they use distinct installation directories and ports. Use distinct IP addresses or a shared reverse proxy for more. Each installation has its own database, Core key and nodes.
 

docs/getting-started/install.md

@@ -58,7 +58,7 @@ Downloads and configuration checks happen before the installation directory is p
 curl -fsSL https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.sh | bash -s -- --install-dir "$HOME/.oac/core"
 ```
 
-Use your chosen directory if it differs. A rerun uses the saved Compose file and settings; installation flags only apply to new directories. Existing images and containers are reused; missing images are downloaded. To change settings, edit `.env` and run `oac apply`. A new release needs a new directory; see [version policy](./operations.md#installation-version-policy).
+Use your chosen directory if it differs. A rerun uses the saved Compose file and settings; installation flags only apply to new directories. Existing images and containers are reused; missing images are downloaded. To change settings, edit `.env` and run `oac apply`. To move to a newer release, follow [Upgrade](./operations.md#upgrade).
 
 For insufficient space or quota, free space on the filesystem named by the error. Image-loading failures can also require space in Docker's storage, which may be on a different filesystem.
 

docs/getting-started/nodes.md

@@ -78,13 +78,13 @@ Root only prepares the account, the group and the unit; everything else, the Doc
 
 **One Core per host.** Nodes share the `oac-node` account, so a host serves one Core; a command from a second Core is refused.
 
-**One release.** A node runs the program of the console that added it and is never upgraded in place; see the [installation version policy](./operations.md#installation-version-policy).
+**Node software.** A node keeps the host program of the console that added it; an upgrade of Core doesn't replace it. A release that changes the node protocol lists the actions it requires; see [protocol changes](./operations.md#protocol-changes).
 
 **The token.** It is single-use, expires after 10 minutes and only registers the node. The installer takes it only on standard input and refuses it in the environment, where `sudo VAR=… python3` would record it in sudo's log. A sudoers policy with `log_input` records standard input, and so the token.
 
 ## Rerun, expiry and slow links
 
-- Rerunning the same command is safe. Once the node is registered, a rerun uses the node's own credential, changes nothing that already matches and needs no token. It refuses, without changing anything, when the node's retained identity belongs to another Core address or installation.
+- Rerunning the same command is safe. Once the node is registered, a rerun uses the node's own credential, changes nothing that already matches and needs no token. It refuses, without changing anything, when the node's retained identity belongs to another Core address or installation, and with `Retained node specification differs from Core` once the sandbox configuration has changed since the node registered. A node added with this command prepares new configurations itself; see [Change the sandbox configuration](#change-the-sandbox-configuration).
 - A command that already expired, or was used on another host, fails at once with `Core rejected the node configuration read (HTTP 401)`: generate a new command and run it within 10 minutes.
 - If the command expires during a slow download, registration fails with `The enrollment command expired or was already used`. The downloaded files are kept: generate a new command in Web and run it.
 - Failed or interrupted downloads discard their temporary files. A rerun downloads missing files from the beginning and reuses verified complete files. A transfer that brings less than 64 KiB in a minute stops; check the network and retry.